Ss Multi Repo Workflow

Multi-Repo Workflow

Executes a requirement that spans multiple git repositories: plan once, then run one repository-scoped execution unit per repository (each running ss-coding-workflow from that repo's real working root), batched by dependency order, and finally consolidate all pull requests into one cross-repo report.

Why repository runners. Every unit must start with the target repository as its real working root so it loads that repo's own project instructions, specs, skills, and git state. Use a native child runner only when the host can guarantee an independent absolute working directory, fresh repository context, nested implementation/review delegation, observable lifecycle, and exact run identity. Otherwise use a fresh headless process. Extra file access without repository-scoped context is not sufficient.

Orchestrator (this session)
  ├── in repo-a: run ss-coding-workflow <plan-a>, autonomous, lite/full     ┐ batch 1 (parallel)
  ├── in repo-b: run ss-coding-workflow <plan-b>, autonomous, lite/full     ┘
  └── in repo-c: run ss-coding-workflow <plan-c>, autonomous, lite/full       batch 2 (after batch 1)

Core principle: thin orchestration. This skill never writes code or edits source/configuration inside target repositories. Its only target-repository write is distributing the generated sub-plan artifact before execution. Planning-stage work is delegated to other ss-* skills in this session; execution-stage work is delegated to per-repo runners.

When to Run

Only run this when the user explicitly asks for it, or a single-repo workflow hands off to it after multi-repo detection (see ../ss-references/multi-repo-detection.md). Do not auto-trigger it for ordinary single-repo work.

Inputs

• Planning input, one of:
  • a path to an existing master plan (see "Input Type Detection"), or
  • a requirement/PRD link, issue link, or plain-text requirement — triggers the planning stage first.
• Delivery mode — full (default) or lite, forwarded to every per-repo ss-coding-workflow invocation. See ss-coding-workflow's "Delivery Mode" section; the choice is made once here and applied uniformly across repos.
• Skip-gates — skip the manual multi-repo execution gate.
• Decide-autonomously — resolve clarification questions without pausing; also forwarded to the planning-stage skills.
• Runner adapter — auto (default), native child, or headless process. auto selects a native child only when all readiness guarantees in this skill can be proven; otherwise it uses a headless process. Never treat mere access to another directory as repository-scoped context.
• Allow unattended edits (optional, default off) — authorize the selected runner's unattended edit mode in trusted environments only.

Iron Rules

Violating any of these means stopping and explaining to the user:

1. The orchestrator does no real work — during planning, only call other ss-* skills. During execution, its sole target-repository write is copying each generated sub-plan to that repo's plan directory; otherwise it only launches/monitors runners and collects results. Never edit source, configuration, or any other project-owned file in a target repository.
2. Repository runners do not own product decisions — launch them in unattended mode. A native child may surface a needs-attention event, but this parent session owns every clarification and scope decision: before launch at the multi-repo gate or after an escalation.
3. Batch order is a hard constraint — repos in the same batch may run in parallel; batches run strictly in the master plan's dependency order. A consumer of an API never starts before its provider's batch completes.
4. Distribute sub-plans before launching — copy each repo's sub-plan into that repo first; a runner never reads plans across repositories.
5. Verify every repository's result individually — PR link, verdict, and task completion for each repo. A failed, timed-out, or blocked repo must never be hidden inside an aggregate report.
6. Full-scope delivery — no unauthorized reduction — every repository and every task completes, or is explicitly escalated. Never settle for "N of M repos done" unless the user explicitly approved dropping scope; record any such approval and repeat it in the final report.
7. Never modify the internal behavior of orchestrated skills — every runner uses stock ss-coding-workflow.
8. Adapter readiness fails closed — before launch, prove the selected adapter's cwd, context, nested-delegation, lifecycle, result, and exact-identity guarantees. If any guarantee is absent, stop or obtain explicit approval to select another adapter; never silently fall back mid-run.
9. The security boundary is external — run only on a trusted dev machine or container. A per-repo cwd/worktree is a change-isolation boundary, not a security sandbox; protection comes from feature branches, PR review, and branch protection.

Input Type Detection

A troubleshooting master plan is valid only when its Problem ID and investigation-report path match the report; **Violated Invariant:**, **Owning Boundary:**, and **Patch-Style Alternative Rejected:** match the report's repair basis; every report repository has one sub-plan; and every sub-plan contains a complete Troubleshooting Repair Basis with an implementation-and-verification mapping for each applicable **Affected Paths:** entry. Validate this before skipping planning and again before launch.

Pre-flight Checks (execution stage)

Run before launching any repository runner. Any unmet check defaults to asking the user, not terminating.

Repository location convention: the master plan's local-path column is authoritative. When planning generates it, paths are probed as siblings of the current repo (../<repo-name>); anything unresolvable is asked about, never guessed.

Resume Detection

Process

1. Pre-flight and repo location.

2. Planning stage (only when the input is not a master plan) — run in this session, since planning needs the global view and no process nesting is involved:

   1. For large requirements, draft a proposal with ss-proposal (with its own approval gate, skippable via skip-gates). The proposal's repo list feeds the master plan. Skip this step for a confirmed investigation report; that complete report is the design input.
   2. Run ss-plan — its scope check detects the multi-repo span and produces the master plan plus per-repo sub-plans. Shared API contract changes are handled inside the proposal/plan flow as usual (contract-first: provider repos land in earlier batches).
   3. If ss-plan does not produce a master plan: for an ordinary requirement, tell the user this is single-repo work and hand back to ss-coding-workflow/ss-feature-workflow; for a confirmed multi-repo investigation, fail closed and correct the plan because its verified repository scope cannot be downgraded.

3. Gate: multi-repo execution confirmation — default on; skip-gates bypasses it. Changing code in N repositories at once is a large blast radius, so show and pause for approval on:

   • the repository list with local paths and remotes;
   • batches and dependency order;
   • per-repo sub-plan task counts;
   • the number of parallel repository runners and the selected adapter/readiness evidence;
   • detection evidence, when arrived via hand-off.

   Options: continue / adjust (edit the master plan, then re-show) / abort.

4. Distribute sub-plans — copy each repo's sub-plan into that repo's plan directory, keeping a descriptive, slug-based filename. The plan travels with the repo's PR — reviewable and traceable. The master plan stays in the originating repo.

5. Launch a batch — for each repo in the current batch, start one runner with an absolute repository cwd, fresh repository context, stock ss-coding-workflow, the distributed sub-plan, and a captured exact execution identity. Defaults: at most 3 concurrent repos per batch (each runner may itself launch several implementer subagents — count the total against machine and API rate limits; split a larger batch into sub-batches), per-repo timeout of 60 minutes (both overridable by asking, or by the autonomous defaults). A process adapter captures its exit code, session ID, and per-repo log; a native child adapter captures its run/task ID, lifecycle state, and structured output.

6. Monitor and collect — require three signals together for every adapter: terminal lifecycle state + valid normalized ---SS-RESULT--- block + timeout not exceeded. A process exit code contributes to its terminal state but never replaces the result contract. Missing, malformed, contradictory, or non-terminal output counts as failure; preserve its log/lifecycle evidence.

   Normalize and validate the result before trusting its status:

   • require every shared field from ss-coding-workflow: status, exact persisted input identity, branch, delivery location, delivered commit ref, constrained review verdict, final test-verified ref, structured test evidence, task count, changed files, structured commands run, residual risks, and clean-worktree state;
   • parse every object/array field as valid JSON and reject unknown enum values or malformed 7–64-character lowercase hexadecimal commit refs;
   • accept SUCCESS only when input_identity exactly matches the distributed sub-plan identity, review is APPROVED, all tasks are complete, delivery is present, delivered_ref is the commit at that delivery location, test_verified_ref == delivered_ref, the passed full-test command appears in both test evidence and commands run, changed files are non-empty, the worktree is clean, and no blocker is present;
   • require a blocker for FAILED/BLOCKED; prose outside the block never overrides missing or contradictory structured evidence.

   Failure handling, per repo:

   1. Read the adapter's terminal evidence; classify the cause.
   2. Auto-resumable (transient error, missing context the orchestrator can supply) → resume the recorded exact execution identity with a corrective instruction, at most twice. Never use an ambiguous "latest" or cwd-global continuation in parallel execution.
   3. Not auto-resolvable (blocked, root-cause ambiguity, permission denial) → pause the workflow and escalate to the user with that repo's log summary and the status of every other repo. Repos already running in the same batch keep going to completion — never kill healthy work.
   4. A repo the user decides to abandon must be recorded as an approved scope reduction and flagged in the final report.

7. Repeat for remaining batches once the current one fully succeeds (or the user accepts a partial result and unblocked later batches can proceed).

8. Converge:

   1. Cross-link PRs — for every PR created, update its description to list every sibling PR link plus a reference to the master plan.

   2. Consolidated report:

      ## Multi-Repo Execution Report
      
      | Repo | Branch | PR | Review Verdict | Tests | Tasks |
      |---|---|---|---|---|---|
      | payment-service | feat/refund-6297 | https://github.com/example/payment-service/pull/456 | APPROVED | 18 passed @def456 | 3/3 |
      | order-service | feat/refund-6297 | https://github.com/example/order-service/pull/123 | APPROVED | 42 passed @abc123 | 5/5 |
      
      ## Needs Human Sign-off
      (collected from each runner's manual-verification checklist, grouped by repo)
      
      ## Suggested Merge Order
      1. payment-service #456 (API provider, batch 1)
      2. order-service #123 (batch 2)
      
      ## User-Approved Scope Reductions
      (none / listed one by one, quoting the user's own words)
      

Repository Runner Contract

Each repository runner starts from the target repo's real working root and executes something equivalent to:

Run ss-coding-workflow on docs/plans/<sub-plan-file> in mode=<full|lite>, deciding
autonomously, using branch <unified-branch-name>.

Requirements for every adapter:

• Real absolute cwd and fresh repository context — load the target repo's project instructions, specs, skills, and git state before executing the plan.
• Unattended execution — no child-owned product decisions. A native attention channel may ask the parent for help; a headless process must use closed/redirected stdin.
• Nested delegation — the runner must be able to execute ss-coding-workflow's implementer and reviewer fanout without delegating back into another repository.
• Explicit edit/network permissions — grant only what implementation and PR delivery require, and only in a trusted environment.
• Observable terminal lifecycle — capture exit/lifecycle status and enough per-repo evidence to diagnose a failure.
• Exact execution identity — record the process session ID or native run/task ID at launch and use only that identity for resume.
• Normalized structured result — preserve the exact ---SS-RESULT--- contract emitted by ss-coding-workflow.

The unified branch name comes from the master plan; passing it explicitly to every runner is what makes every repository use the same branch name.

A note on isolation: don't rely on a runner's own sandbox as a security boundary when agent sessions are nested. Treat the trusted-machine/container boundary in Iron Rule 9 as the real protection.

Edge Cases & Error Handling

Examples

Run ss-multi-repo-workflow on docs/plans/2026-07-03-refund-master.md
Run ss-multi-repo-workflow on https://your-tracker.example/issues/PROJ-6297, deciding autonomously
Run ss-multi-repo-workflow with "refund flow spanning the order and payment services", fully autonomous, using the available headless-process adapter