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

• If either is missing, tell the user to run $grace-plan first

• If the shell does not already have GRACE worker/reviewer presets, use $grace-setup-subagents 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 , 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

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 and docs/knowledge-graph.xml once per run, then build the controller view of the execution queue.

• Parse pending Phase-N and step-N entries

• Group steps into parallel-safe waves

• 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

• Choose the execution profile: safe , balanced , or fast

• For each wave, prepare a compact execution packet for every module containing:

• module ID and purpose

• target file paths and exact write scope

• 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

• module-local verification commands

• wave-level integration checks that will run after merge

• expected graph delta fields: imports, exports, annotations, and CrossLinks

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 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 accuracy, and verification evidence

If a worker discovers that a missing module or new dependency is required, stop that worker and ask the user to revise the plan before proceeding. Do not allow silent architectural drift.

Step 3: Dispatch Fresh Worker Agents Per Wave

For each approved wave:

• Dispatch one fresh worker agent per module

• Give each worker only the execution packet and the files inside its write scope

• Require the worker to:

• generate or update code using the $grace-generate protocol

• preserve MODULE_CONTRACT, MODULE_MAP, CHANGE_SUMMARY, function contracts, and semantic blocks

• add or update module-local tests only

• run module-local verification only

• commit their work after module-local verification passes with format: grace(MODULE_ID): short description

Wave N, Phase M

• return a result packet with changed files, verification evidence, graph delta proposal, commit hash, and any integration assumptions

Step 4: Review with the Smallest Safe Scope

After each worker finishes:

• Run a scoped contract review against the changed files and execution packet

• Run a scoped verification review against the module-local tests and verification evidence

• Escalate to a full $grace-reviewer audit only when:

• cross-module drift is suspected

• the graph delta contradicts the packet or actual imports

• verification is too weak for the chosen profile

• a phase boundary audit is due

• If issues are found:

• send the same worker back to fix them

• re-run only the affected reviews unless escalation is required

• Only approved module outputs may move to controller integration

Step 5: Controller Integration and Batch Graph Sync

After all modules in the wave are approved:

• Integrate the accepted module outputs

• Apply graph delta proposals once, centrally, to docs/knowledge-graph.xml

• Update docs/development-plan.xml step status once per wave

• Run targeted $grace-refresh against the changed modules and touched dependency surfaces

• If targeted refresh reports wider drift, escalate to a full refresh before the next wave

• If the wave reveals weak or missing automated checks, use $grace-verification before continuing

Step 6: Verify by Level

Run verification at the smallest level that still protects correctness.

• Worker level: module-local typecheck, lint, unit tests, and deterministic local assertions

• Wave level: integration checks only for the merged surfaces touched by the wave

• Phase level: full suite, full integrity audit, and final graph reconciliation before marking the phase done

Do not run full-repository tests and full-repository graph scans after every successful module unless the risk profile requires it.

Step 7: Controller Shared-Artifact Commits and Report

After each wave, the controller commits only shared artifacts that changed:

• Update docs/knowledge-graph.xml and docs/development-plan.xml with wave results

• Commit with format: grace(graph): sync after wave N

Modules: M-xxx, M-yyy

Worker implementation commits are already done per module in Step 3. Controller commits are only for shared planning artifacts.

After each wave, report:

=== WAVE COMPLETE === Wave: N Profile: safe / balanced / fast Modules: M-xxx, M-yyy Approved: count/count Graph sync: targeted passed / targeted fixed / escalated to full refresh Verification: module-local passed / wave checks passed / follow-up required Remaining waves: count

Dispatch Rules

• Parse shared XML artifacts once per run unless the plan changes

• Prefer controller-built execution packets over repeated raw XML reads by workers

• Parallelize only across independent modules, never across unknown coupling

• Do not let workers invent new architecture

• Do not let workers edit the same XML planning artifacts in parallel

• Do not reuse worker sessions across modules; keep workers fresh and packets compact

• Give every worker exact file ownership and exact success criteria

• Workers must commit their implementation after verification passes - do not wait for controller

• Controller commits only shared artifacts (graph, plan), not implementation files

• Prefer targeted refresh and scoped review during active waves

• Reserve full reviewer audits and full refresh scans for phase boundaries, drift suspicion, or critical failures

• If verification is weak, slow down and move to safe rather than pretending fast is safe

When NOT to Use

• Only one module remains

• Steps are tightly coupled and share the same files

• The plan is still changing frequently

• The team has not defined reliable module-local verification yet

Use $grace-execute for sequential execution when dependency risk is higher than the parallelism gain.