Parallel plan-and-build path: contract registry, owned packages, convergence critic, DAG build with merge train (build brief)

• I searched existing issues and this has not been proposed before

Related, narrower: #2368 (DAG/wave execution inside SDD), #2245 (parallel dispatch checks), #2309 (DAG closure in plan self-review), #429 (Agent Teams). Those add scheduling to an ordinary task list. This issue covers what it took to make parallel build converge, and specifies it as a first-class alternate path.

Who's filing this request? (required)

Claude (Opus 5.5, Claude Code), filing for Jesse Vincent, Superpowers' primary author. Jesse's instructions: "open an issue … describing everything you built and how you would add this as an alternate plan and build implementation for superpowers so that every superpowers user could have this … think about how we would do it in a harness that doesn't have first-class workflows", then "update the issue with everything that Claude would need to know about how to build this. It's going to be another Claude … include versions of all necessary scripts … not describe anything about what [the project] is. You can speak in Claudese." So this issue is a build brief for another Claude instance, in dense form.

Human-authored summary (required, under 200 words)

Jesse hasn't written one. In its place, his request verbatim: "Could you open an issue against obra/superpowers Describing everything you built and how you would add this as an alternate plan and build implementation for superpowers so that every superpowers user could have this? Also think about how we would do it in a harness that doesn't have first-class workflows."

What problem does this solve?

writing-plans + SDD = one ordered task list, one implementer at a time. That's correct by default, but too slow for big builds. The real session: spec → ~26 work packages → ~100k lines of code and tests, built overnight by fanned-out agents.

Naive fan-out failed: a master plan, then N agents each writing a package plan in parallel. A cross-package critic then found:

• 24 interface mismatches. Each package invented its own wire types and fields.
• 13 shared-file overlaps. Packages all edited lib.rs mod lines, manifests, lockfiles, and the route tree.
• 7 dependencies on same-wave work.
• ~200 contract change requests and ~72 "open questions", mostly duplicates.

Root cause: too little of the shared surface was frozen. A scheduler alone (#2368) can't fix disagreeing packages.

Proposed solution

Overview

brainstorming → spec (unchanged)
  → lead writes 00-master.md: decomposition, DAG, constraints, shared-file policy  [single mind, not fanned out]
  → parallel-plan-converge: registry → verify → package plans → review → CCRs → triage → critic loop until dry
  → human answers the short "Open questions" list (or authorizes recommendations)
  → parallel-build: foundations package alone first, then an audit of foundation contracts
  → DAG fan-out: worktree TDD → competing reviewers ×2 rounds → merge train → gate
  → stop at approval-gated actions (infra apply, push, external services)

The scripts are posted as comments below: parallel-plan-converge.workflow.js and parallel-build.workflow.js. Both are generalized, parameterized versions of the scripts that ran the real build, with no project specifics.

Deliverables

1. skills/writing-parallel-plans/
   • SKILL.md: when to choose this path, the lead's job (master plan), how to run convergence, how to handle the human question list.
   • master-template.md, registry-format.md, package-template.md, decisions-log.md: all spec'd below.
   • parallel-plan-converge.workflow.js (comment 1) for harnesses with the Claude Code Workflow tool.
   • manual-converge.md: the same steps as plain subagent dispatches, for other harnesses (see "No-workflow harnesses").
2. skills/executing-parallel-plans/
   • SKILL.md: preconditions, the foundations-first rule, the audit step, stopping rules, how to report to the human.
   • Prompt files: implementer-prompt.md, reviewer-spec-prompt.md, reviewer-code-prompt.md, fixer-prompt.md, integrator-prompt.md, gate-prompt.md, foundations-audit-prompt.md. The first six can be pulled from the script; the audit prompt is below.
   • parallel-build.workflow.js (comment 2).
   • manual-scheduler.md + plan-state.schema.json for no-workflow harnesses.
3. Entry points:
   • brainstorming / writing-plans scope check: when the spec implies more than ~8 independent packages, or the human asks for fan-out, offer writing-parallel-plans.
   • SDD: "plans with 00-master.md + 01-contracts.md → executing-parallel-plans".
4. Vocabulary: reuse #2368's task metadata (Depends on, write scope) where it overlaps. Don't invent a second dialect.

Artifacts (formats)

00-master.md is written by the lead alone. Decomposition needs one coherent mind.

• §1 Global constraints: stack, datastore, test policy (real services, no mocks in integration/e2e, pristine output), style rules, commit trailer.
• §2 Layout + shared-file policy (this was the biggest single fix):
  • A foundations package (wave 1) pre-creates every module file, every mod/import line, every dependency in every manifest, the whole route registry with placeholders, and the shared test fixtures, all straight from the registry. No later package edits these files.
  • Lockfiles and generated artifacts (lockfiles, OpenAPI snapshot, generated client types) belong to the integrator. Package agents never commit them.
  • Non-leaf modules hold only declarations and re-exports, so leaf files are ownable.
  • Each worktree gets its own service instance (database, etc.), with names derived from the worktree path. Add a reset recipe: agents edit unshipped migrations in place, and dev databases then reject the checksum.
  • A package needing anything outside its Owns stops and reports. It never reaches across.
• §3 Frozen core contracts: the types every package touches. The registry extends and supersedes this section.
• §4 Package table + DAG: name, deps, scope, rough size. Split the big packages: the largest package sets the wall clock.
• §5 Orchestration + stopping rules: never push; no infrastructure apply, external publish or other irreversible action without explicit human approval; stop on a red gate that can't be fixed.
• §6 Cross-cutting acceptance scenarios: the e2e package builds these, and earlier packages design toward them.
• §7 Review focus: likely failure modes no single package owns.

01-contracts.md + 01-contracts/<area>.md is the contract registry:

• Each part is written by its own author, in parallel. Good areas: HTTP-by-domain groups; cross-module code API + schema + events; layout (modules, deps, routes, fixtures, CLI syntax/output/exit codes).
• Every entry names its producer package and its consumer packages. HTTP rows give method, path, request and response types (with field types), and error codes. Rust/TS rows give the exact path and signature.
• Authority: the registry wins over package plans and never contradicts the spec.
• Each part ends with a "Resolved conflicts" list. The index has an append-only "Registry fixes" log naming the packages each fix affects.

packages/<name>.md follows the template embedded in the converge script:

• Spec sections; Depends on; Owns (exact paths, disjoint within a wave); reserved numbering.
• Scope in/out; Interfaces (Consumes/Produces using exact registry names).
• Acceptance tests with concrete assertions; TDD steps; the gate command.
• "Decisions made here" plus contract change requests. Package writers never edit the registry: CCRs are applied centrally.

02-decisions.md is the decisions log:

• Append-only, with merge=union in .gitattributes, because every fix branch appends to it.
• It has three sections: decided (builder-level), "Open questions for the human" (each with a recommendation), and "Decisions made during execution".
• Mark each entry [decided] or [pending human]. If the human authorizes recommendations ahead of time, adopted items stay marked pending, so they can be audited the next morning.

Execution rules that mattered (all encoded in the build script)

• Foundations first, alone. Then run an adversarial foundation-contracts audit (prompt below) before fanning out. In the real session it found a privilege escalation that two per-package reviews had missed: an item-scoped credential could take workspace-wide admin actions. It also found a deadlock between lock orders and roles that weren't enforced in the DB.
• DAG scheduling, not wave barriers. A package starts when its specific deps have merged. With wave barriers, finished packages sat idle for about 2.5h waiting on the slowest.
• Per package: an isolated worktree + its own services, then a TDD implementer, then two competing adversarial reviewers (/par pattern; lenses: spec+contracts and correctness+security+style), then a fixer.
  • Cap at 2 rounds. Round 1 fixes everything. Round 2 fixes only critical/major, and its moderates go to the gate. Rounds beyond 2 rarely paid off.
• Merge train: finished packages queue up, and one integrator at a time merges the whole queue in dependency order. It regenerates lockfiles and codegen per merge, then runs the full check once per batch, bisecting only when it's red. Full CI after every merge cost more than 1h on an 8-package wave.
  • After merging, it releases per-worktree resources (stops containers). Otherwise dozens pile up.
• Gate: a completeness critic compares what was built against the plans and spec, and also judges leftover moderates. A gate-fix agent then closes the gaps test-first.
• Between batches, the lead reads results and runs targeted fix branches for anything a gate flagged as a design issue. Those fixes merge before any dependent packages start.
• CI must include the browser e2e suite, which starts and stops its own stack. Otherwise web gates quietly never run.
• Build cache: sccache shares third-party crates across worktrees. It does not share workspace crates (absolute paths differ) or test binaries. A shared target/ serializes on cargo's lock, so don't use one.

Foundation-contracts audit prompt (not in the scripts)

Read-only adversarial audit of the merged foundations package. Every later package builds on it, so contract mistakes multiply; false or inflated findings are worse than useless. Read the registry, master §1–§3, the foundations plan, and the spec's access/privacy section. Compare them against the code and the schema. Report, ranked critical/major/moderate, each with file:line + registry § + a one-line fix:

• contract drift (missing or reshaped types, signatures, variants, tables, columns);
• schema safety: append-only enforcement, row-level isolation on every tenant table, role grants actually enforced by the DB (not just by convention);
• access-logic edge cases: credential narrowing, delegated actors, humans-only rules, governance/admin actions under narrowed credentials;
• concurrency: ordering/gap-freedom claims actually tested under concurrent commits; lock-order deadlocks between triggers and app code;
• missing pre-created files or dependencies that later packages need.

No-workflow harnesses

The orchestration needs only: spawn a subagent with a prompt, run several at once, and collect structured results. Everything else is plain files.

• plan-state.json (checked into the plan dir, written only by the orchestrator) survives compaction and resumption:

  {"integrationBranch":"wip/integration",
   "packages":{"pkg-a":{"deps":[],"status":"merged|queued|reviewing|implementing|pending|blocked",
     "branch":"pkg/pkg-a","worktree":"/abs/path","round":1,"blockers":[],"leftoverModerates":[]}},
   "batches":[{"packages":["pkg-a"],"ciGreen":true}],
   "gate":{"gaps":[],"done":false}}

• Manual scheduler loop (manual-scheduler.md):
  1. Read the state.
  2. For every pending package whose deps are all merged: create a worktree (git worktree add -b pkg/<n> <path> <integrationBranch> if the harness has no isolation), then dispatch the implementer in the background with the path in its prompt. Mark it implementing.
  3. When an implementer reports, dispatch both reviewers at once, then the fixer. Repeat up to the round cap, then mark it queued.
  4. When nothing is implementing or reviewing, or the queue holds ≥ N packages, dispatch the integrator for the whole queue. On green, mark them merged and go to step 2.
  5. When everything is merged or blocked, run the gate.
  6. Write the state after every transition.
• Harnesses with subagents but no worktree isolation (Codex, etc.): the orchestrator makes the worktrees. Each subagent writes a required JSON report to <worktree>/.parallel-report.json, and the orchestrator reads that file instead of relying on the agent's final text.
• Harnesses with no subagents at all: run serially over the same artifacts.
  • Run the reviewers as separate passes with an explicit adversarial persona and a fresh re-read of the files.
  • The registry and ownership rules still pay off, because they prevent drift across context resets.
  • For real parallelism, drive separate sessions with claude-session-driver or tmux.

Acceptance for the implementing Claude

• Plan-side pressure test (writing-skills style): given a multi-module spec, the agent writes the master plan itself, doesn't fan it out, and produces a registry where every entry names its producer and consumers, and package Owns lists don't overlap within a wave.
• Build-side pressure tests:
  • the executor runs foundations alone, then the audit, then fans out;
  • it refuses to apply infrastructure without approval;
  • an injected "need a file outside Owns" ends up in blockers, not as a cross-package edit.
• Manual-scheduler walkthrough: in a harness without the Workflow tool, a 4-package DAG runs through to the gate with plan-state.json as the only memory.
• Both scripts parse and run under the Claude Code Workflow tool: pure JS, export const meta literal first, no Date.now()/Math.random().

What alternatives did you consider?

• Scheduler over a task list (#2368): necessary but not sufficient. Plans drifted even with perfect scheduling.
• Hard wave barriers: simple, but the slowest package gates everyone. DAG + merge train is strictly better.
• Shared build dir: serializes builds on the build-tool lock.
• More review rounds: diminishing returns past 2. Gates and foundation audits caught what rounds 3+ didn't.

Is this appropriate for core Superpowers?

Yes, as an opt-in path. Nothing here is specific to a domain or stack. The registry, ownership policy, convergence critic, merge train and gates apply to any multi-module codebase large enough to parallelize. The manual scheduler keeps it working across harnesses.

Environment (required)

Context

Process lessons for the skill text:

• The lead must read every gate result and turn design-level findings into targeted fix branches before dependents start. Don't let the runner auto-continue past them.
• Merge agents drift from the commit conventions unless the prompt spells them out.
• Integrators should resolve append-only-log conflicts by union; .gitattributes handles it.
• Tell implementers where secrets live, and that worktrees inherit the parent .env. They must never print or commit it.
• Write the registry before the package plans. The real session did it after, and paid for two convergence rounds.