Executing

Executing

Orchestrate implementation by creating an agent team and spawning teammates per user story. Workers own code, test, and fix edits; the lead owns decomposition, dispatch, integration, deterministic verification, gates, and operational records. After every worker in a wave finishes, the lead runs one wave-scoped Outer Ralph pass.

Agent Teams vs Subagents: This skill uses agent teams so that teammates can communicate with each other during parallel waves. When one teammate discovers a gotcha, it broadcasts to all others immediately — no waiting for the wave to finish. For sequential single-US waves, a regular subagent is fine.

One PROJ at a time: The executing loop runs per PROJ. Each PROJ has multiple wave-plan files (PROJ-<X>-wave-1-plan.md, PROJ-<X>-wave-2-plan.md, …) that are read in order. A single 5_progress/PROJ-<X>-progress.md tracks all waves. When the user provides multiple PROJ plans, execute each PROJ fully (all waves → Quality Gate → QA) before starting the next.

Decomposed PROJs: If the plan references sibling PROJs, treat them as dependencies or context only. Do not implement sibling scope from the current PROJ's waves. If a wave depends on an incomplete sibling PROJ, stop before that wave and report the blocker. Shared design-language files from sibling PROJs may be consumed, but they do not authorize building sibling workflows.

Context economy — always delegate to subagents

The orchestrator (main agent) must stay lean so it survives the full PROJ → QA → docs chain. Delegate every code, test, and fix edit when subagents are available and delegation is permitted; the main agent coordinates.

• US implementation: always spawned (implementer / backend-implementer / frontend-implementer). Never write code inline.
• Wave-scoped Outer Ralph: the main agent owns deterministic commands and evidence; workers own every resulting fix.
• PROJ-end Ken review: spawned in Skill 6, not read inline. Ken no longer runs per wave — only once against the assembled PROJ.
• Quality Gate (Step 9): code-reviewer-gate plus optional sonar-cli quality input run as delegated streams, not inline review by the orchestrator.
• Fix-spawns: every Critical/High finding is fixed by a spawned subagent, clustered by file.
• Even trivial or single-file edits: delegate; there is no size exception.
• Concurrency: dispatch independent tasks with disjoint ownership together; serialize dependencies and overlapping ownership.
• Integration corrections: send the exact failure to a follow-up worker; the lead does not patch it directly.
• Fallback: edit locally only when subagents are unavailable or delegation is prohibited, and report the reason explicitly.

Subagents return a ≤ 300-token summary; raw diffs/logs stay in their context and die with them. The orchestrator keeps only IDs, verdicts, and next-step pointers. If the main agent has to read more than ~3 source files directly for a decision, it's the wrong tool — spawn an Explore or domain agent instead.

Run in background by default. Spawn all subagents with run_in_background: true unless the orchestrator genuinely cannot proceed without the result. Background spawns let the orchestrator dispatch the next wave of work immediately and get notified on completion — parallel fan-out without blocking. Foreground is the exception, not the norm. Dependencies like implementer → Ralph → Build → Gate still run sequentially (the orchestrator awaits each stage), but within a stage every independent spawn goes to background in a single parallel batch.

FIRST ACTION (before reading any plan)

This file is your single source of truth for the whole PROJ. Update it after EVERY action. If progress.md does not exist, you have skipped this step — STOP and create it now.

Wave Completion Gate

Doc-input collection is owned by Skill 7. Do not fill documentation summaries or Post-Wave-Notes blocks during Skill 5. Keep progress.md, commit messages, and agent.md accurate; Skill 7 harvests those sources after QA.

bash scripts/wave-gate.sh <N> <PROJ-X> <theme>

Exit code ≠ 0 → STOP. For blocked_external / exit 76, retain the AC and wait for its declared prerequisite (see Step 4); do not dispatch a code repair. For other failures, fix the failing check and rerun until green. Only then spawn the next wave's teammates.

For a provider signature only (over_request_rate_limit, Request rate limit reached, or HTTP/status 429), the gate pauses and retries that AC once. For auth-consuming browser commands, auth_budget.rate_limit_evidence_cmd may establish the same fact from server/provider evidence outside the Playwright stream; its output is retained. A second occurrence is red infrastructure, not a reason to widen limits. Other failures — including a test name containing “rate limit” — are ordinary red ACs.

Before P0 seals an auth-budget project, bash scripts/wave-gate.sh --auth-budget-negative-control 1 <PROJ-X> <theme> must return the configured exhausted exit code and persist infrastructure_failed. It exercises the configured hooks with SKILLCHAIN_AUTH_BUDGET_NEGATIVE_CONTROL=1 and never drains a real hosted bucket.

The script validates:

1. Current wave ACs — every structured ac_commands entry exits 0 and reports a non-empty selected-test count. A cached pass requires the same command, test files, auth classification, gate-config fingerprint, positive selection, and committed verified_head; equivalent commands may share execution across AC IDs, with evidence recorded for each ID. Changed or uncommitted code cannot be certified.
2. Declared targeted regressions — every regression_commands entry covers shared behavior affected by this wave and runs after the current ACs and before smoke; selection-aware entries must prove that they selected tests. Broad hosted-auth/browser suites belong in phase_commands, not every wave.
3. Smoke Test — the configured dev server is reused or started by the gate. Anonymous routes must match URL and characteristic content; redirects are failures. Protected routes require auth state or authenticated E2E coverage.
4. Component registry — gen-component-registry.mjs --check passes where applicable.
5. Build — build_cmd from config exits 0; runs in parallel with CodeRabbit as the last phase.
6. CodeRabbit — every attempt archives raw and normalized evidence, validates the finding count, ingests it, and then requires zero cumulative open blocking findings in the ledger.

The wave gate does not run Sonar. The top-level sonar_cmd runs once, at the PROJ-end Quality Gate (Step 9) after all waves pass — not per wave.

A green wave gate proves the current wave's ACs plus its declared broad regression suite. It does not claim that every earlier AC command was rerun.

On success the script appends a ### Wave N Gate — PASSED block with timestamp to progress.md. This is the canonical proof that the wave is done — no manual checkbox editing.

Framework runs (state.json exists): after every green gate, update the machine state too — bash scripts/state.sh set <X> <theme> .waves '{"current": <N>, "total": <M>, "stories": {…per-US status…}}' (merge with the existing block). The gate pipes its normalized CodeRabbit findings into the ledger when scripts/ledger.mjs is present; Sonar evidence remains in the configured system — never re-enter either by hand.

If a framework helper is missing: run node ~/.claude/skills/4b_setup/scripts/sync-framework.mjs to restore the managed inventory, resolve any reported conflicts, and commit before running the gate. Standalone runs use the same synchronization before their first wave.

If jq, coderabbit, or agent-browser are missing: the script prints a clear error and exits non-zero. Install them, do not work around the gate.

Belt-and-braces enforcement: A global PreToolUse hook (~/.claude/hooks/wave-gate-enforcer.js) inspects every Agent spawn. When subagent_type is implementer / backend-implementer / frontend-implementer and the prompt mentions Wave N with N > 1, it refuses the spawn unless ### Wave N-1 Gate — PASSED exists in 5_progress/PROJ-<X>-progress.md. The script is the primary gate; the hook is the fail-safe so the main agent cannot accidentally skip it.

Memory Files

Two files are maintained throughout execution:

progress.md (short-term memory)

Created at the start of execution, lives in specs/ alongside the plan. Tracks granular build state — task completion, test status, AC verification, and blockers. Updated after every task, after the initial wave verification and each recovery stage, and whenever a blocker occurs.

# PROJ-X Progress

## Status: [in progress | blocked | complete]
## Current Wave: [N]
## BASE_SHA: [commit hash before first change]

---

## US-1: [title] — [pending | in progress | complete]

### Tasks
| Task | Tests Written | Tests Passing | Done |
|------|:---:|:---:|:---:|
| 1.1 [name] | ✗ | — | ✗ |
| 1.2 [name] | ✓ | ✓ | ✓ |
| 1.3 [name] | ✓ | ✗ | ✗ |

### Acceptance Criteria
| AC | Text | Verified |
|----|------|:---:|
| AC-1 | [verbatim from spec] | ✓ |
| AC-2 | [verbatim from spec] | ✗ |
| AC-3 | [verbatim from spec] | — |

### Wave-Scoped Ralph Evidence
- Initial pass: AC-1 PASS; AC-2 FAIL — [exact failure reason]
- Recovery stage: normal fix round 1 → follow-up worker dispatched
- Reused during repair: AC-1 — verified at [committed HEAD]; changed files not plausibly affecting it
- Rerun: AC-2 PASS — [exact command, positive selection, verified HEAD]
- Commit: `feat(PROJ-<X>-PRD-<Y>): implement US-1 [name]`

---

## US-2: [title] — pending
*(blocked by US-1)*

---

## Quality Gate — PROJ-X

### Code Review
Status: pending | passed
| Severity | Found | Fixed | Deferred |
|----------|:-----:|:-----:|:--------:|
| P0 Critical | 0 | 0 | 0 |
| P1 High | 0 | 0 | 0 |
| P2 Medium | 0 | 0 | 0 |
| P3 Low | 0 | 0 | 0 |

### SonarCloud (once per PROJ, via top-level `sonar_cmd`)
Status: pending | ran | skipped (sonar CLI unavailable) | skipped (project not configured)
| Severity | Found | Fixed | Deferred |
|----------|:-----:|:-----:|:--------:|
| Critical/Major | 0 | 0 | 0 |
| Minor | 0 | 0 | 0 |
| Info | 0 | 0 | 0 |

### Build
Status: pending | passed

### Tests
Status: pending | passed

### Lint
Status: pending | passed

### Fixed Issues
- [severity]: `file:line` — [issue] → fixed in [commit]

### Deferred (user decision)
- [severity]: `file:line` — [issue]

---

## Open Blockers
- US-7: [exact reason] — escalated to user [timestamp]

Update rules:

• Subagent updates task rows after each TDD cycle (tests written → tests passing → done)
• Main agent updates AC rows after the initial wave pass and every recovery stage
• — means not yet attempted; ✗ means attempted and failing; ✓ means passing
• Wave-Scoped Ralph Evidence records canonical AC, command, positive selection, committed HEAD, reuse/invalidation, and verbatim failure output

agent.md (long-term memory)

Lives in the feature's source folder (e.g., src/features/deliveries/agent.md). Written when any agent hits a wall and finds a workaround — or discovers something a future developer must know. Written like notes to a developer who has never seen this code.

# Agent Notes — [Feature Name]

## Gotchas

### Supabase RLS blocks server actions without explicit role claim
Discovered during US-4 (activate delivery). Server actions run as `anon` unless
`set role authenticated` is called explicitly. Workaround: call `supabase.auth.getUser()`
at the top of every mutating server action before any DB write.

### Zod refinements don't run on optional fields when undefined
If a field is optional and undefined, `.refine()` is skipped entirely.
Use `.optional().refine()` vs `.refine()` on the base type — different behavior.

## Patterns That Work Well
...

## Dead Ends (don't try these again)
...

Write to agent.md immediately when a learning occurs — not at the end. Future subagents in the same session read it at the start.

Input

Read the following before starting each PROJ:

All PRDs — specs/PROJ-<X>-<theme>/2_PRDs/*.md. These are the authoritative requirements source. Used by the wave-scoped Outer Ralph pass to verify ACs. If plan and PRD disagree on AC text, the PRD wins.

Architecture — specs/PROJ-<X>-<theme>/3-4_plan/PROJ-<X>-architecture.md. Cross-PRD tech design.

Wave plans — specs/PROJ-<X>-<theme>/3-4_plan/PROJ-<X>-wave-<N>-plan.md (in numeric order). Each wave plan lists:

• The user stories in that wave (may span multiple PRDs)
• Tasks per US with TDD cycle descriptions and file paths
• For UI tasks, UI Implementation Notes and UI handoff constraints propagated from 1d_mockups/implementation-handoff.md

UI implementation handoff — for UI PROJs, read specs/PROJ-<X>-<theme>/1d_mockups/implementation-handoff.md before starting implementation. It is the compact source for project mode, component reuse, new component candidates, design tokens, interaction contract, implementation tolerance, and demo-only mockup exclusions.

The PRDs define WHAT success means. The wave plans define HOW to get there. The UI handoff defines how to preserve the approved interface shape without treating HTML mockups as pixel-perfect production specs.

When multiple PROJ plans are provided: Execute one PROJ fully (all waves → Quality Gate → QA) before starting the next. Each PROJ has its own 5_progress/PROJ-<X>-progress.md.

Per-PROJ-X Execution Loop

For each PROJ-X plan (in order):

0. Record BASE_SHA (git rev-parse HEAD)
1. Create specs/PROJ-<X>-<theme>/5_progress/PROJ-<X>-progress.md
2. Execute waves (Steps 1–5 below)
3. One wave-scoped Outer Ralph pass, then the wave gate (Steps 4 and 8)
4. Integration-focused Quality Gate after all waves (Step 9)
5. Handoff directly to mandatory Skill 6 QA (Step 10)
6. Mark Step 5 complete
→ Next PROJ-X

After ALL PROJ-X plans complete: Final Summary Report (Step 9).

Orchestration (per PROJ-X)

0. Record BASE_SHA

Before any implementation changes, record the current commit:

git rev-parse HEAD

Store this in progress.md as BASE_SHA. It is used later by the Quality Gate to diff only this feature's changes.

1. Read the dependency map

Extract waves from the plan's dependency table:

Wave 1: US-1                    → 1 teammate
Wave 2: US-2, US-7 (parallel)   → 2 teammates simultaneously
Wave 3: US-3                    → 1 teammate
...

2. Before each wave: read agent.md, refresh the context bundles

If agent.md exists in the source folder, read it before spawning teammates. Include relevant sections in the teammate prompt so they don't repeat known dead ends. (Implementers additionally follow the agent.md read/write protocol in references/implementer.md; entries are rendered with templates/agent-md-entry.md.tmpl.)

When specs/.../api-contracts.md has entries for this wave, recompile the bundles wave-scoped so api-contracts-own-wave is real, and record the new hashes:

node scripts/compile-context-bundles.mjs compile <X> <theme> --wave <N>
bash scripts/state.sh set <X> <theme> .context.bundles "$(jq -c . specs/PROJ-<X>-<theme>/context/bundles.lock.json)"

2a. Mark wave start with a git tag

git tag "wave-${WAVE}-start-PROJ-${PROJ}"

One tag per (wave, PROJ) pair. Tags are local-only; do not push. If neither WAVE_BASE_SHA nor wave-${WAVE}-start-PROJ-${PROJ} exists, wave-gate.sh fails hard. There is no HEAD~20, commit-message, or root-commit fallback. If the tag already exists from a re-run, delete and re-create: git tag -d "wave-${WAVE}-start-PROJ-${PROJ}".

3. Create team and spawn teammates for the wave

Before dispatch, read references/worker-lifecycle.md for worker status/stop/replacement and shared DB/browser scheduling. Assign both file ownership and resource windows, including the wave's browser scenarios. Use its verification-cost procedure when browser/DB waits dominate: measure selection and wait time, establish fixture isolation, then opt independent lifecycles into shared mode. Existing auth-consuming gate commands remain exclusively locked; a helper refresh alone does not parallelize those suites.

All implementation work is worker-owned when delegation is available. The lead decomposes the wave, assigns explicit disjoint ownership, dispatches workers, integrates their commits, runs deterministic verification and gates, and maintains operational records. For waves with 2+ independent user stories: create an agent team and dispatch them concurrently. Serialize dependent stories or overlapping ownership.

Honor the plan's ## Execution block before spawning. sequential means dispatch exactly one US at a time even when Can start when says both are ready. For any frontend wave, the lead owns the dev server: start and stop it once for the round; agents reuse it and never start or kill one. For a parallel wave, the lead also owns every other declared shared resource and the control plane: progress.md, staging, and commits. Include the execution mode, runtime constraints, and these ownership rules in every spawn prompt.

The development database and hosted-auth budget are shared across the PROJ worktrees. Every database migration command—including one delegated to a story agent—and every other explicitly auth_consuming command must therefore be wrapped as scripts/worktree.sh with-shared-lock -- <command>. Put that exact constraint in the agent prompt; never let parallel agents run migrations outside the project lock. That lock only stops concurrent collisions; wave-gate.sh separately re-checks at the start of every wave that this worktree's own supabase/migrations/ still matches what the shared DB has actually applied (scripts/migration-drift-check.sh), since a sibling worktree can advance the schema between waves with no lock involved at all.

Choose the right implementer type per US. Where the current session can spawn P0's skillchain-<role> agent types, use them. Otherwise use the normal agent type and attach the path printed by node scripts/context-injector.mjs claude <role> --path to its prompt; a non-zero exit means that role is blocked and must not be spawned. A generic general-purpose spawn gets no bundle unless that path is explicitly passed:

• US touches only UI (components, pages, styling) → frontend-implementer (skillchain-frontend-implementer)
• US touches only server-side (API, DB, server actions) → backend-implementer (skillchain-backend-implementer)
• US is full-stack (both UI and server logic) → implementer (generic)

Choose the right model per US (from the wave plan's Complexity column): Read the Complexity column in the wave plan's "User Stories in this Wave" table. Pass the value as the model parameter on the Agent spawn so the teammate runs on the right brain for the job.

• sonnet → model: "sonnet" (default for standard US)
• opus → model: "opus" (architecture-sensitive: state machines, concurrency, cross-feature contracts, migrations, auth/session, money, crypto)

Haiku is deliberately not in the menu — US-level work loses too much fidelity on it. If the wave plan is missing the Complexity column (older plan format), default to sonnet and log a one-line note in 5_progress/PROJ-<X>-progress.md so the planner can retrofit it.

Create an agent team for Wave N of PROJ-X.

Spawn teammates:
- "us-2" using the frontend-implementer agent type, model: "sonnet": [US-2 prompt with full context]
- "us-7" using the backend-implementer agent type, model: "opus": [US-7 prompt with full context — this one touches auth/session]

Require plan approval for each implementer before they make changes.

For waves with a single user story: Use a regular subagent (no team overhead needed). Pick the matching implementer type based on the US scope. Local editing is permitted only when delegation is unavailable or prohibited; report that reason explicitly.

Pass to each teammate (via references/implementer.md template):

• Full user story (Given/When/Then)
• Its acceptance criteria
• Its task list with TDD steps
• Codebase context + conventions
• What previous waves implemented
• Relevant sections from agent.md
• If the US touches UI: include the relevant UI Implementation Notes from the wave plan and the matching sections from 1d_mockups/implementation-handoff.md:
  • Project mode (greenfield, brownfield, hybrid)
  • Mockup file reference and selected UI direction
  • Existing components/tokens to reuse
  • Approved new component candidates
  • Required interaction contract and responsive behavior
  • Implementation tolerance and demo-only exclusions
• If the US touches UI: the design system baseline is docs/DESIGN-SYSTEM.md (rules) plus docs/components.md (inventory). In framework runs the frontend-implementer context bundle injects both — do not paste them again, that pays the token budget twice. Outside bundle runs, paste both files. Either way the teammate reuses registered components — never one-off styled elements.
• If a US needs a component the catalog does not have: the teammate escalates instead of styling a one-off. The main agent runs the extension procedure from 1c_frontend-design → Extending The Design System (variant before new component, confirm with the user, then catalog + docs/components.md + /dev/components showcase), then the teammate composes the new entry. A component that reaches QA without a catalog and registry entry is a Critical bug (6_qa hard-checks this).
• If the US touches Tailwind CSS styling: Include the contents of ~/.claude/skills/tailwind-css/SKILL.md. Pass the relevant sections (responsive patterns, dark mode, class organisation, component patterns) so the teammate uses consistent utility classes and avoids conflicts.
• If the US involves Next.js App Router: Include the contents of ~/.claude/skills/nextjs-app-router-patterns/SKILL.md. Pass the relevant sections (Server vs. Client Components, data fetching, routing, caching) so the teammate follows App Router conventions and avoids common pitfalls (e.g. accidentally marking a Server Component as 'use client').

UI implementation rule: Existing React components and design tokens take precedence over exact HTML mockup CSS. Preserve the selected layout direction and interaction contract; do not replace a sidepanel with a modal, a wizard with a single page, or a brownfield component with a one-off styled element unless the user explicitly approved that change.

Wait for all teammates in the wave to complete before running Outer Ralph. If integration or verification exposes a correction, dispatch it to a follow-up worker; do not absorb the edit into the lead. Clean up the team after each wave.

4. Wave-scoped Outer Ralph (AC verification)

Wave closure checklist — parallel and sequential modes alike:

1. Collect all story Smoke Test blocks and match each route/behavior to gate smoke or the current wave's authenticated scenario coverage.
2. If scenarios are missing, dispatch their implementation to the named browser owner after DB workers release the shared resource. Reuse an existing story worker when appropriate; a separate browser worker is not mandatory.
3. Integrate and commit scenario files, exact command/route mappings and any selection-only hook. Do not append unrelated waves to a growing shared suite.
4. Only then run AC-only Ralph below; Phase 0 checks declared selection hooks. A successful route load alone does not prove the story's interaction.

The lead starts the pass through the gate's AC-only mode so evidence is written in the canonical cache schema:

bash scripts/wave-gate.sh --ac-only <N> <X> <theme>

It runs each uncached AC sequentially under the gate's timeout, auth-budget, pacing, and rate-limit controls. Ordinary AC failures are all evidenced before the pass exits non-zero so disjoint repairs can be batched; infrastructure and exhausted auth budgets still stop immediately. Each evidence record binds the canonical AC ID, task, exact command, test files, positive selected-test count, and committed HEAD.

run bash scripts/wave-gate.sh --ac-only <N> <X> <theme>
for normal_fix_round in 1..2:
  cluster failures by disjoint ownership
  dispatch correction workers concurrently where safe
  commit corrections, then rerun the same --ac-only command
if failures remain:
  dispatch one fresh diagnostic worker that makes no edits
  dispatch a different implementer to apply the diagnosis
  commit the correction, then rerun the same --ac-only command
if failures still remain: use the existing blocked-run evidence path

Rules for wave-scoped Ralph:

• Checks must be deterministic — run actual test commands, read actual output. No subjective judgment ("this looks like it works").
• Tests inside the shared-resource lock must not acquire that lock again. Node --test workers do not preserve arbitrary inherited file descriptors; when a node:test entry point detects ownership through a descriptor, execute it directly with node path/to/test.mjs and verify the selected-test count.
• A test that depends on state outside itself — provider rate budget, file order, or clock — must establish that state itself or explicitly assert it. Never accept a green result merely because neighbouring tests primed the bucket or fixture.
• Treat “nothing happened” as weak evidence: add a positive control that proves the valid session/input/path would have worked, and do not let polling matchers pass on their first attempt without proving the observed transition.
• Failure output is passed verbatim to correction and diagnostic workers — not summarized or interpreted.
• Reuse requires the same committed HEAD and complete gate-config fingerprint. Identical AC commands with matching test_files and auth_consuming share successful execution across AC IDs, with separate evidence for every ID. Identical failed/empty/timed-out commands also share their result within one AC-only invocation, but failures are retried on the next invocation; infrastructure and auth exhaustion still stop immediately. Every correction commit invalidates reuse; no cross-HEAD impact inference is supported. Remove cached Ralph evidence after dependency, runtime, or environment changes.
• Recovery has exactly four stages: normal fix round 1, normal fix round 2 with fresh workers, fresh diagnosis, then a different diagnosis-driven implementer. Do not add retries or silently weaken an AC.
• If diagnosis finds an invalid or contradictory AC, record the evidence and use the existing blocked/escalation path.
• Exit 76 with blocked_external is a missing declared prerequisite, not a code defect and not a green AC. Keep the test and plan scope; no repair rounds, invented approval, PASSED block or next-wave unlock. Use state.sh for the blocked phase/stop reason and render the stop report. Rerun the unchanged gate when the prerequisite arrives: readiness is rechecked and its AC is not cached. PR, stop and morning renderers include declared prerequisites; final summaries must name each unresolved AC, reason, decision author/date and evidence path.
• The normal wave gate reuses matching AC-only passes. Regression reuse requires explicit reuse_passed: true and is limited to deterministic, non-auth local commands independent of external state. Other regressions and remaining gate phases still run. Any committed or non-evidence uncommitted change prevents reuse.

Update progress.md after the initial pass, each recovery stage, each reuse or invalidation decision, and the final result.

5. Build check — handled by wave-gate.sh

Do not run an extra build between Ralph and the wave gate. Build is intentionally centralized:

• Wave-end build: wave-gate.sh runs build_cmd once per wave. After ACs, regressions, browser smoke and the component registry check pass, build and CodeRabbit run concurrently on the same committed HEAD as the last gate phase, so an environmental smoke failure costs no review. The coordinator retains separate logs, waits for both results, then checks findings; either failure blocks. Interruption stops both command groups. Database and browser tests remain sequential.
• PROJ-end build: the Quality Gate verifies the assembled PROJ before QA, reusing matching final-wave build evidence only when declared artifacts and inputs remain valid.

If the wave gate finds a build failure, dispatch a fix worker with the verbatim compiler output, then rerun the gate.

6. Write learnings to agent.md

After a wave worker completes or a recovery stage exposes a durable learning, write it to the source folder's agent.md. Include:

• Walls hit and how they were bypassed
• Surprising behavior in the framework/DB/tooling
• Patterns that worked well
• Dead ends (so future agents don't repeat them)

7. Wave review with CodeRabbit CLI

The single wave-gate invocation in Step 8 runs CodeRabbit on the wave's changes. This section describes its review requirements; do not invoke the gate here.

The base commit must be either WAVE_BASE_SHA or tag wave-${WAVE}-start-PROJ-${PROJ}. Missing base = hard fail. No fallback is allowed.

How to handle findings:

• Each gate attempt retains coderabbit-wave-<N>-attempt-<M>.jsonl and its normalized sibling; never overwrite earlier review evidence.
• Any cumulative open ledger severity not listed in the wave's advisory_severities blocks. Fix immediately — spawn a fix teammate before the next wave.
• Listed advisory severities are logged by CodeRabbit output and revisited at the PROJ-end Quality Gate if still relevant.

Log in progress.md:

### CodeRabbit Review
- Command: `coderabbit review --agent --base-commit $WAVE_BASE_SHA`
- Result: [PASS / findings found / ERROR with reason]
- Critical/High: [N found, N fixed]
- Medium/Low: [N logged for Quality Gate]

Update $WAVE_BASE_SHA to the current commit after the wave review passes.

7b. Browser smoke test (if wave touched frontend)

Scenario authoring must already be complete via the Step 4 closure checklist. This step verifies coverage; it does not create missing scenarios.

Skip this step if the wave only contained backend-implementer teammates.

Browser smoke testing is owned by wave-gate.sh. It reuses a matching reachable server or starts frontend.dev_cmd, waits for readiness, logs its output, and stops only the process it started. It then runs agent-browser to verify URL and characteristic content. Redirects are failures; protected routes require auth_state or authenticated E2E coverage.

# The lead owns this server for the wave; do not start or stop another one.
agent-browser open http://localhost:3000/[route-affected-by-wave]
agent-browser read
agent-browser errors

For multiple pages affected by the wave, run one agent-browser call per route.

Pass criteria: Anonymous routes keep the expected URL and characteristic text. Protected routes supply auth_state, or current-wave AC/regression commands provide equivalent authenticated E2E coverage through authenticated_e2e_test_files. Omit auth_state for a covered route to avoid repeating its smoke; retain smoke for routes the scenario does not exercise. Fail: Stop and fix before the next wave — broken UI compounds fast.

Log the result in progress.md under the wave section:

### Browser Smoke Test
- Pages tested: [list of URLs]
- Result: PASS / FAIL
- Details: [agent-browser output summary]

Why agent-browser as an option? It runs as a standalone CLI — no MCP context required. This means it can also be delegated to a teammate if needed. Full browser testing is reserved for comprehensive QA in Skill 6.

7c. Minimalism Review — Ken Takahashi

Do not invoke Ken from Skill 5. Do not create Ken wave BUG IDs or Ken wave backlog sections. If minimalism concerns appear during implementation, write them as normal agent.md learnings or progress notes; Skill 6 will review the complete PROJ diff with Ken's PROJ-level lens.

8. Mark wave complete, auto-continue to next wave

Run the Wave Gate script once (including the Step 7 review and browser smoke):

bash scripts/wave-gate.sh <N> <PROJ-X> <theme>

• Exit 0 → script appended ### Wave N Gate — PASSED block to progress.md. Commit the wave. Immediately proceed to next wave — do NOT pause, do NOT ask the user, do NOT announce "ready for next wave". The gate already proved the wave is done; the next wave's Step 1 (read dependency map) is the next action.
• Exit 76 / blocked_external → retain scope and report the missing external prerequisite; resume after it is available. No next-wave certification.
• Other non-zero → read the script's error, fix the failing check (spawn fix teammate if code problem, install missing tool if env problem), re-run.

No stop between waves. A PROJ with 5 waves should execute as one continuous run: wave 1 → gate ✓ → wave 2 → gate ✓ → … → wave 5 → gate ✓ → Step 9 Quality Gate. Pausing for user confirmation between waves defeats the wave-gate design — the gate IS the signal.

Manual checklist editing in progress.md is no longer sufficient proof of wave completion — only the script's passed-block counts.

9. PROJ Quality Gate (integration only, after all waves)

After all waves for this PROJ-X are complete and their gates passed, run the Quality Gate. It evaluates the assembled cross-wave result; it does not replay wave ACs or replace the wave gates.

See references/quality-gate.md for full instructions.

Run the integration reviewer alongside build and coverage where safe; start Sonar after coverage is ready. Use the command/evidence sequence in references/quality-gate.md; keep DB/browser work serialized. Collect every stream before dispatching a combined fix round.

Sonar runs here at PROJ end, with bounded fix/rescans — no wave gate runs it. Skip is allowed only when the tooling genuinely is not available; scripts/quality-gate-proof.sh rejects a skip when both CLIs and sonar-project.properties are present, so treat this as required whenever the project is Sonar-configured.

Before launching the Sonar stream, check tool availability:

command -v sonar >/dev/null && command -v sonar-scanner >/dev/null

• If both CLIs are available, run the Sonar quality-gate stream using the sonar-cli skill guidance, executing the top-level sonar_cmd from wave-gate-config.json as the analysis command.
• If either CLI is missing, skip Sonar and record SonarCloud: skipped (sonar CLI unavailable) in progress.md.

Create an agent team for Quality Gate of PROJ-X.

Spawn teammates:
- "reviewer" using the code-reviewer-gate agent type with prompt:
  "Review the feature diff from BASE_SHA=$BASE_SHA. Focus on cross-wave contracts, shared state, authorization boundaries and unresolved wave findings; use references/code-reviewer.md only for relevant integration risks. Return findings without starting fixes."
- "sonar" only if `sonar` and `sonar-scanner` are installed, using the sonar-cli skill with prompt:
  "Wait for successful current-revision coverage, then run the PROJ Sonar scan through quality-evidence.mjs run sonar, which executes the top-level sonar_cmd from wave-gate-config.json from the persistent PROJ worktree, then use sonar CLI/API for quality gate, issue, coverage, and duplication data. Verify a fre

…(truncated)