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

Introduces an RFC for a unified, git-backed filesystem for org and user workspaces in Studio. Defines a simple layout and two agent modes to standardize how agents and humans store work and share via PRs.

• 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.

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