grace-multiagent-execute

Execute a GRACE development plan with multiple agents while keeping planning artifacts and shared context consistent.

## Prerequisites
- `docs/development-plan.xml` must exist with module contracts and implementation order
- `docs/knowledge-graph.xml` must exist
- `docs/verification-plan.xml` should exist with module-local verification commands and gate expectations
- if `docs/operational-packets.xml` exists, use it as the canonical packet and delta reference
- If the plan or graph is missing, stop immediately and tell the user to run `$grace-plan` themselves before dispatching a large wave
- If the verification plan is missing or still skeletal, stop immediately and tell the user to run `$grace-verification` themselves before dispatching a large wave
- Prefer this skill only when module-local verification commands already exist or can be defined clearly

## Core Principle

Parallelize **module implementation**, not **architectural truth**.

- One controller owns shared artifacts: `docs/development-plan.xml`, `docs/knowledge-graph.xml`, `docs/verification-plan.xml`, phase status, and execution queue
- Worker agents own only their assigned module files and module-local tests
- Reviewers validate module outputs before the controller merges graph and plan updates
- Speed should come from better context packaging, batched shared-artifact work, and scoped reviews - not from letting workers invent architecture
- Packets should be good enough that workers do not need mid-wave goal reinterpretation
- Controller checkpoints matter more than chatty mid-flight intervention; revise packets between waves, not by hoping the worker will self-correct from vague new prompts

If multiple agents edit the same module, the same shared XML file, or the same tightly coupled slice, this is not a multi-agent wave. Use `$grace-execute` instead.

## Execution Profiles

Default to `balanced` unless the user asks otherwise.

### `safe`
- Ask for approval on the proposed waves before dispatch
- Run contract review and verification review for every module output
- Run targeted graph sync after each wave and a full refresh at each phase boundary
- Use when modules are novel, risky, or touch poorly understood integration surfaces

### `balanced` (default)
- Parse plan and graph once at the start of the run
- Ask for one approval on the execution schedule up front unless the plan changes mid-run
- Give workers compact execution packets instead of making each worker reread full XML artifacts
- Run module-local verification per worker, scoped gate reviews per module, and batched integrity checks per wave or phase
- Run targeted graph sync after each wave and full refresh only at phase boundaries, when drift is suspected, or at final wrap-up

### `fast`
- Use only for mature codebases with strong verification and stable architecture
- Ask for one approval for the whole run unless a blocker or plan change appears
- Keep worker packets compact and require only the minimum context needed for exact scope execution
- Block only on critical scoped review issues during a wave, then batch the deeper integrity audit at phase end or final wrap-up
- Reserve full refresh for phase completion or final reconciliation

Every module still gets a fresh worker. Do not optimize this workflow by reusing worker sessions across modules.

## Process

### Step 1: Build the Execution Waves Once
Read `docs/development-plan.xml`, `docs/knowledge-graph.xml`, and `docs/verification-plan.xml` once per run, then build the controller view of the execution queue.

1. Parse pending `Phase-N` and `step-N` entries
2. Group steps into **parallel-safe waves**
3. A step is parallel-safe only if:
   - all of its dependencies are already complete
   - it has a disjoint write scope from every other step in the wave
   - it does not require shared edits to the same integration surface
4. Choose the execution profile: `safe`, `balanced`, or `fast`
5. For each wave, prepare a compact **execution packet** for every module containing:
     - module ID and purpose
     - target file paths and exact write scope
     - preferred stack or tooling excerpt from `docs/technology.xml` when the project defines one
     - module contract excerpt from `docs/development-plan.xml`
     - module graph entry excerpt from `docs/knowledge-graph.xml`
     - dependency contract summaries for every module in `DEPENDS`
     - verification excerpt from `docs/verification-plan.xml`, including module-local commands, required scenarios, required log markers, and target test files
     - assumptions or unresolved edges that remain acceptable inside the write scope
     - stop conditions or replan triggers that should halt the worker immediately
     - retry budget for fix or review loops
     - wave-level integration checks that will run after merge
     - expected graph delta fields: imports, public exports, public annotations, and CrossLinks
     - expected verification delta fields: test files, commands, markers, and phase follow-up notes

   When `docs/operational-packets.xml` exists, shape packets and delta proposals to the canonical `ExecutionPacket`, `GraphDelta`, and `VerificationDelta` templates.

Present the proposed waves, selected profile, and packet scopes to the user. In `safe`, wait for approval before each dispatch. In `balanced` and `fast`, one up-front approval is enough unless the plan changes.

### Step 2: Assign Ownership
Before dispatching, define ownership explicitly:

- **Controller**:
  - owns `docs/development-plan.xml`
  - owns `docs/knowledge-graph.xml`
  - owns `docs/verification-plan.xml`
  - owns wave packets, phase completion, and commits that touch shared artifacts
- **Worker agent**:
  - owns one module or one explicitly bounded slice
  - may edit only that module's source files and module-local tests
  - must not change shared planning artifacts directly
- **Reviewer agent**:
  - read-only validation of contract compliance, GRACE markup, imports, graph delta