multirepo-space

Quick routing

User intent → Command:

• “Create/scaffold workspace” → setup
• “Add a repo” → add (verify workspace exists with status first)
• “Remove/detach repo” → remove
• “Check/verify/health” → status
• Single repo project → DO NOT use this Skill
• Monorepo (Nx/Turborepo) → DO NOT use this Skill

Before running — decision guide

Before executing, think about the workspace design:

• Do these repos share API contracts or interfaces? → they benefit from cross-repo analysis (global agents)
• Is the workspace inside an existing git repo? → git root symlinks will be needed
• Will multiple workspaces coexist in the same git repo? → prefixed symlinks prevent collisions

Ask the user before executing:

1. Does the workspace directory already exist? If not, create it first (mkdir).
2. Is this a NEW workspace or adding to an EXISTING one? → setup vs add.
3. Are all repo paths absolute? They MUST be absolute — symlinks break with relative paths.
4. First time? Always suggest --dry-run so user can preview changes.
5. Does the user want global transversal agents? Default is yes. Use --no-global-agents to opt out.
6. Does the user need custom model assignments? Default: coordinator=opus, specialist=sonnet, global=sonnet.

Flags — when to use each

If detect_stack returns “Generic”

The CLI creates the specialist agent without verify commands. Ask the user: “Stack was not auto-detected for [repo]. What is the main language/framework?” Then manually add verify commands to the generated specialist agent file.

When NOT to use this

• Single repo projects — no benefit, just overhead.
• True monorepos (one repo, multiple packages) — use monorepo tools (Nx, Turborepo) instead.
• Repos that must stay completely independent — managed blocks modify external repos’ AGENTS.md/CLAUDE.md.

NEVER

• Run setup on a populated workspace without confirming with the user first.
• Use relative paths for repos — symlinks will break when working directory changes.
• Skip --dry-run for first-time users — always suggest preview first.
• Assume symlinks always work on Windows — the PowerShell port falls back to junctions when symlinks need elevation, but junctions only support local directories (not network paths).
• Assume workspace exists — verify with status before running add or remove.
• Create the workspace directory inside one of the repos — git root detection will find the repo itself, creating circular symlink references.
• Edit managed blocks manually in external repos — they get overwritten on next add/setup.
• Run add with a repo whose basename matches an existing alias — the previous specialist gets overwritten without warning.
• Modify settings.json manually — the CLI expects a specific format and manual edits can break parsing in add/remove.
• Run setup/add while another agent is using the workspace — managed blocks and settings can end up in an inconsistent state.

Detect OS and run

• macOS/Linux/WSL: bash "$SKILL_DIR/scripts/multirepo-space" <subcommand> [args]
• Windows PowerShell: powershell "$SKILL_DIR/scripts/multirepo-space.ps1" <subcommand> [args]

Replace $SKILL_DIR with the absolute path to this skill’s directory.

Templates are in $SKILL_DIR/templates/ — read them to understand what files get generated (e.g., workspace-instructions.md.tmpl, coordinator.md.tmpl, specialist.md.tmpl, global-agent.md.tmpl).

Script behavior summary

The scripts (scripts/multirepo-space for bash, scripts/multirepo-space.ps1 for PowerShell) are fully offline — they make NO network requests and do NOT modify system files.

What each subcommand does:

• setup: reads repo manifest files (package.json, pom.xml, etc.) to detect tech stacks, then generates .md agent files, .claude/settings.json, and symlinks inside the workspace directory. Also appends a managed block to AGENTS.md/CLAUDE.md in each listed repo. Creates global transversal agents (architecture, style, code-review) unless --no-global-agents. If workspace is nested inside a git repo, creates prefixed symlinks in git root for agent discovery. Saves configuration to .claude/.multirepo-space.conf.
• add: same as setup but for a single repo added to an existing workspace. Loads config from .multirepo-space.conf to preserve original model and global agent settings.
• remove: deletes the specialist agent file and symlink for a repo, removes the managed block from the repo’s AGENTS.md/CLAUDE.md, and refreshes git root symlinks.
• status: read-only — checks symlink health, agent file parity, global agents, config persistence, and git root symlink state. Writes nothing.

All extracted values from repo files are sanitized (length-limited, control characters and injection patterns stripped) before being inserted into templates.

Scope of filesystem writes is limited to:

1. The workspace directory (files it creates)
2. AGENTS.md/CLAUDE.md inside each configured repo (managed block only, delimited by <!-- MULTIREPO_SPACE_MANAGED:START/END --> markers)
3. Git root .claude/agents/ and .agents/ directories (symlinks only, prefixed with ws-<name>--)

Agent hierarchy

Coordinator (opus)
├── architecture-agent (sonnet) — transversal, read-only
├── style-agent (sonnet) — transversal, read-only
├── code-review-agent (sonnet) — transversal, read-only
├── repo-frontend (sonnet) — can invoke global agents
└── repo-backend (sonnet) — can invoke global agents

• Global agents: read-only, analyze and recommend, never modify code
• Specialists can invoke global agents for analysis within their repo
• Coordinator invokes global agents for cross-repo analysis

Claude Code vs Codex compatibility

• .claude/agents/*.md → includes YAML frontmatter (model, description, allowedTools)
• .agents/*.md → plain markdown only, no frontmatter (Codex/Gemini/Cursor compatible)
• Both directories contain identical agent logic, only the frontmatter differs

After running

• Run status <workspace_path> to verify all symlinks are healthy and agents are in parity.
• Check that AGENTS.md and CLAUDE.md exist in both the workspace and each external repo.
• If setup failed mid-way, it’s safe to re-run — existing files get overwritten.
• To start working: cd <workspace_path> && claude or cd <workspace_path> && codex.
• If workspace is nested in a git repo, verify git root symlinks with ls -la <git-root>/.claude/agents/ws-*.

Common issues

• “Workspace path does not exist”: create directory first, then run setup.
• Broken symlinks after moving repos: re-run setup with updated absolute paths.
• “Permission denied” on Windows: run PowerShell as Administrator for symlink creation.
• Stack not detected: the CLI falls back to “Generic” — specialist agent still gets created, just without stack-specific verify commands.
• Agents not discovered in nested workspace: verify git root symlinks exist. Run status to check. Re-run setup if symlinks are missing.
• Partial setup failure (files created but symlinks missing): re-run setup with same args — the script overwrites existing files safely and recreates all symlinks.
• Global agents not generated: check if --no-global-agents was used during setup. Config is saved in .claude/.multirepo-space.conf.