workspace-layout

name

workspace-layout

description

The canonical owner-prefixed workspace layout. Every repo lives at ~/Code/<host>/<owner>/<repo> -- no active/ or language segment. Enumerate with `ls ~/Code/github.com/*/*`; resolve siblings by path arithmetic. The manager (workspace-root) CLAUDE.md is a map of where things are and how to read them, never a cache of per-project inventory or status. Load this whenever a session reasons about where a repo lives, walks the workspace, or resolves one project from another.

Workspace layout

The canonical convention for where every repo lives and how the manager session reasons about the workspace. This is the single source of truth for the path shape; other skills (workspace-survey, dispatch, sibling resolution) reference it rather than restating it.

The path shape

Every clone lives at one derivable, owner-prefixed path:

~/Code/<host>/<owner>/<repo>

• <host> is the forge host (github.com today; the segment leaves room for others without reshuffling).
• <owner> is the GitHub owner/org (joshrotenberg, genagent, ...).
• <repo> is the repository name.

Example: ~/Code/github.com/joshrotenberg/adrs.

No active/, no inactive/, no language/framework segment. Those facts are mutable and derivable; encoding them in the path rots it the moment a project changes language or goes dormant. Forks need no -fork suffix either -- the <owner> segment already disambiguates, and provenance lives in git remote.

Enumeration

The filesystem is the index. List every project with one glob:

ls -d ~/Code/github.com/*/*

<host>/<owner>/<repo> is exactly three levels deep, so */* under a host enumerates every repo. Do NOT walk by language buckets or look for an active/ root -- there is none.

A project is "in the workspace" if its directory exists under this layout. Whether it is actively worked is a reconstituted fact (recent commits, open PRs), not a path segment and not a cached flag.

Sibling resolution is path arithmetic

Because the path is derivable, one project resolves another by relative arithmetic from its own directory -- no lookup table, no config:

Target	From ~/Code/<host>/<owner>/<repo>
Same owner, other repo	../<repo>
Other owner, same host	../../<owner>/<repo>
Other host entirely	../../../<host>/<owner>/<repo>

This is why the layout is owner-prefixed and flat: the deterministic cwd makes cross-project consultation pure path math, and the matching escaped dir under ~/.claude/projects/ is equally derivable.

Map, not model: the manager CLAUDE.md

The workspace-root ~/Code/CLAUDE.md (the "manager" / Code Manager context) is a map: it says where projects are (this path convention + the enumeration glob) and how to read each one. It is not an inventory and not a status cache.

Specifically, the manager CLAUDE.md must NOT carry:

• A hardcoded project list / inventory (the glob enumerates it fresh).
• Per-project last-seen PR/issue/CI/notable-change status.
• Any "agents update this section when they learn something" cache.

Per-project status is reconstituted on demand -- read the project's own files and query gh (or cratesio/hexpm) at the moment you need it, emit it to a report, and let it go. Nothing flows upward into the manager CLAUDE.md. The moment the map starts caching what is inside a project rather than where it is and how to read it, pull it back: that is the "map, not model" line, and crossing it turns the manager into the stateful system it must never become.

When to apply

• Any time a session needs the canonical path for a repo, or builds one from <host>/<owner>/<repo> parts.
• Walking/enumerating the workspace (use the glob above).
• Resolving a sibling project from the current one (path arithmetic).
• Deciding what belongs in the manager CLAUDE.md vs. what must be reconstituted (the map/model line).

Anti-patterns

• Assuming an ~/Code/active/ root or a language/framework bucket -- there is none; that was the pre-reorg layout.
• Walking deep directory trees looking for .git/ when a single ls ~/Code/github.com/*/* glob enumerates everything.
• Writing a project inventory or per-project status into the manager CLAUDE.md ("so the dispatcher doesn't have to re-survey") -- that is the cache the model forbids; reconstitute instead.

Related

• workspace-survey -- how the dispatcher enumerates projects under this layout and reconstitutes a status report.
• durable-context -- why state is reconstituted from durable substrate, not carried in context or cached upward.