design: org filesystem layout

[tlgimenes]

Summary

RFC for a unified, git-backed filesystem per organization in Studio.

• Each org owns one git repository (main = shared/published layer)
• Well-known paths: AGENTS.md, skills/, artifacts/, connections/
• Each agent lives under /agents/<slug>/ with its own AGENTS.md (frontmatter carries name, description, icon, mcps), memory.json, skills/, artifacts/, and automations/
• Two agent modes driven by the github: frontmatter property:
  • Plain agent — freeform workspace, cwd is /agents/<slug>/
  • GitHub agent — child folders are git worktrees (one per branch), cwd is /agents/<slug>/<branch>/
• Connections exposed as /connections/<slug>/mcp.json (public metadata only, no secrets)
• Sharing = PR from agent branch → main

See design/org-filesystem-layout.md for the full spec.

Open questions for discussion

• Should memory.json have a prescribed schema or be fully freeform?
• Should automations/ have a prescribed file format (e.g. one .json per automation)?
• Skills folder format — one file per skill, or a manifest?

🤖 Generated with Claude Code

---

Summary by cubic

Adds a shareable product/UX overview and an RFC for a unified, git-backed filesystem for org and user workspaces in Studio. Standardizes layout, agent modes, and PR-based sharing across /orgs and /users.

• New Features
  • Dual-root global tree: /orgs/<org-id>/ and /users/<user-id>/ share the same layout; one git repo per org and per user (main is the shared/published layer).
  • Well-known paths: AGENTS.md, memory.json, skills/, artifacts/, automations/, connections/.
  • Agent modes: plain workspace or GitHub-linked with per-branch worktrees; cwd is the agent folder or active branch.
  • Write rules: plain agents can write only to agents/<slug>/artifacts/; GitHub agents write within their branch.
  • Connections under /connections/<slug>/mcp.json (no secrets); sharing = branch commit + PR to main.
  • Adds design/design-docs.md: now includes Home pilot routing with a findings/tasks/automations digest, progressive agent discovery through output, private agent-scoped connections with token slots, and a storefront pages browser.

^{Written for commit 3c10d2f. Summary will update on new commits.}

Review in cubic

[cubic-dev-ai]

1 issue found across 2 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="design/org-filesystem-layout.md">

<violation number="1" location="design/org-filesystem-layout.md:193">
P2: Clarify the writable boundary for GitHub agents; this row is broader than the branch worktree described above.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Clarify the writable boundary for GitHub agents; this row is broader than the branch worktree described above.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At design/org-filesystem-layout.md, line 193:

<comment>Clarify the writable boundary for GitHub agents; this row is broader than the branch worktree described above.</comment>

<file context>
@@ -0,0 +1,266 @@
+| Location | Plain agent | GitHub agent |
+|----------|-------------|--------------|
+| `agents/<slug>/artifacts/` | ✅ writable | ✅ writable |
+| `agents/<slug>/` (all other paths) | ❌ read-only | ✅ writable (lands on the active branch) |
+| Workspace root, `connections/`, `skills/` | ✅ writable | ✅ writable |
+
</file context>