Workspace

/workspace -- Multi-Repo Campaign Coordinator

When to Use

• Adding infrastructure that spans repos (new database, shared service, API contract)
• Coordinating changes across a frontend repo, backend repo, and infra repo
• Breaking a monolith into services (each service becomes a repo-scoped campaign)
• Any task where changes in repo A depend on or inform changes in repo B

Do not use when:

• All work is in one repo (use /fleet or /archon)
• The repos are truly independent with no shared contracts (just run separate campaigns)

Protocol

Step 1: ORIENT

1. Check for existing workspace session: .planning/workspace/session-{slug}.md — resume if status: active or needs-continue
2. If starting fresh: identify repos, verify each path is a git repo, read each repo's CLAUDE.md, check .planning/campaigns/ for active campaigns (avoid collisions)
3. Load prior session context and start watcher:

   node .citadel/scripts/momentum-watch-start.cjs
   node .citadel/scripts/momentum-read.cjs

   Skip momentum injection if output is empty.

Step 2: DECOMPOSE

Break the direction into repo-scoped work items (one campaign per repo per wave). Table format: # | Repo | Campaign Direction | Scope | Deps | Wave.

Rules: items with no deps → Wave 1; dependents → Wave 2+. Max 3 repo-campaigns per wave. Scope format: {repo}:{path}.

For each inter-wave dependency, specify the cross-repo contract: what the producer will produce, what the consumer expects, and where the contract lives (shared types package, OpenAPI spec, env var).

Step 3: WORKSPACE SESSION FILE

Create .planning/workspace/session-{slug}.md with frontmatter: version, id, status: active, started, completed_at: null, direction, repos (path + name + branch per repo), wave_count, current_wave: 1, campaigns_total, campaigns_complete: 0.

Body sections: Direction, Repos table (name/path/branch/status), Work Queue (table from Step 2), Cross-Repo Contracts (producer/consumer/contract/location), Wave Execution Log (per wave: status, campaigns, started, completed), Shared Context (discovery relay accumulation).

Step 4: WAVE EXECUTION

For each wave:

4a. Pre-flight

• Verify all dependency campaigns from prior waves completed successfully
• Check cross-repo contracts: did producer repos create the expected outputs?
• If a dependency failed: park the dependent campaign, flag for user decision

4b. Spawn campaigns

For each repo-campaign in this wave:

1. Create branch: git checkout -b workspace/{slug}/{repo-name}
2. Spawn agent with direction: /archon for complex (3+ phases), /fleet if parallelizable, /marshal or direct skill for simple (1-2 steps)
3. Inject context: discovery briefs from prior waves, prior session context (re-read momentum.json via node .citadel/scripts/momentum-read.cjs, inject as === PRIOR SESSION CONTEXT ===, skip if empty), cross-repo contracts, relevant CLAUDE.md sections from other repos

4c. Collect results

Extract HANDOFF blocks, compress into cross-repo discovery brief, write persistent discovery records:

node .citadel/scripts/discovery-write.cjs \
  --session {session-slug} --agent {repo-name}-{campaign-type} \
  --wave {wave-number} --status {success|partial|failed} \
  --scope "{repo-name}:{scope-path}" --handoff "{json-array}" \
  --decisions "{json-array}" --files "{json-array}" --failures "{json-array}"

4d. Discovery relay

Write workspace/briefs/wave{N}-{repo-name}.md for each completed campaign. Also write workspace/briefs/wave{N}-cross-repo.md summarizing:

• New API endpoints or types created
• Config changes that affect other repos
• Contract fulfillment status (did the producer deliver what was promised?)

4e. Contract verification

For each cross-repo contract: verify the producer created the expected output (file + export for types, route existence for endpoints). If verification fails, flag and do not proceed with consumers.

4f. Update session

Mark completed campaigns, update wave status, write discovery relay, advance current_wave.