# Executing

> Execute implementation plans user-story by user-story using agent teams, TDD, wave-scoped Ralph verification, wave gates, and an integration-focused Quality Gate before mandatory QA. Use when: (1) an implementation plan exists and is ready for execution, (2) feature tasks need to be implemented with TDD. Not for: planning, architecture, or requirements.

- Skill: `silviobeer/executing-2` (Agent Skill, multi-file: 17 files)
- Install (CLI): `npx skillmds@latest add silviobeer/executing-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/silviobeer/executing-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: silviobeer (https://skillmd.com/u/silviobeer)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/silviobeer/executing-2

---


# 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)

<HARD-GATE>
Before doing ANYTHING else — before reading plans, before spawning any agent:
0. Run `/compact` to flush prior conversation context. Steps 1–4 leave large artifacts in the context window that are no longer needed — the PRDs, architecture and wave plans are on disk. Reclaim that space now before the most context-intensive step begins.
1. **P0 setup gate — setup (4b) owns all preflights.**
   - If `specs/PROJ-<X>-<theme>/state.json` exists:
     `bash scripts/state.sh get <X> <theme> '.phase + ":" + .status'` must be
     `P0:done` (fresh PROJ) or `P5:*` (resume). Anything earlier → STOP and
     route: `CP1:*` → run **checkpoint** (4a); `CP1:approved` → run
     **setup** (4b). The former inline preflights — permissions merge,
     `.coderabbit.yaml`, Supabase/browser/CLI + auth checks — now run in
     4b's `preflight.sh`; do NOT re-run them here.
   - Verify the current directory is `.worktree.path` from state. P0 owns the
     persistent PROJ worktree and the runner re-executes there; do not implement
     from the control checkout. Dependencies are isolated, while `.env.local`,
     development data, and hosted-auth limits are deliberately shared.
   - **On every implementation start or resume**, after verifying the worktree path and before launching workers, run `node ~/.claude/skills/4b_setup/scripts/sync-framework.mjs`. Use the installed command, not a potentially stale project copy. A non-zero result blocks implementation: reconcile reported differences against installed sources, test adaptations, and rerun with `--adopt <reviewed-path>` for each resolved file. Never overwrite or blindly adopt project customizations.
   - Commit `.skillchain-helpers.json` and changed managed helpers/templates before implementation. If a refresh changes context tooling or role templates, recompile the context bundles and record them via `state.sh`. This new commit invalidates old gate evidence; never refresh during workers or a gate.
   - Then mark the phase if needed: if state shows `P0:done`, run `bash scripts/state.sh transition <X> <theme> P5 running`.
2. **Standalone fallback (no state.json — manual run without the framework):**
   run the legacy preflights inline before wave 1: (a) permission preflight —
   `claude --dangerously-skip-permissions` or `bash scripts/merge-project-settings.sh`
   (copy from `~/.claude/skills/5_executing/scripts/` if missing, commit);
   (b) `.coderabbit.yaml` at repo root (copy
   `~/.claude/skills/5_executing/references/coderabbit-template.yaml`, adjust
   `path_filters`); (c) tool checks — `jq`, `coderabbit`, browser automation
   when `wave-gate-config.json` has `frontend_routes`, Supabase CLI/MCP when
   the project uses Supabase. Any hard tool missing → STOP.
3. Record BASE_SHA: from `state.json` (`.base_sha`, set by 4b) — standalone: `git rev-parse HEAD`
4. Create `specs/PROJ-<X>-<theme>/5_progress/PROJ-<X>-progress.md` using the template below
5. Store BASE_SHA in progress.md

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.
</HARD-GATE>

---

## Wave Completion Gate

<HARD-GATE>
Before spawning ANY teammate for a new wave N+1, you MUST run the Wave Gate script — it MUST exit 0.

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
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.
</HARD-GATE>

---

## 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.

```markdown
# 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.

```markdown
# 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:
```bash
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:

```bash
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

<HARD-GATE>
Before spawning any teammate for wave N, tag the current HEAD as the wave base. `wave-gate.sh` resolves this tag to scope the CodeRabbit diff. Without `WAVE_BASE_SHA` or this tag, the gate fails hard. This prevents accidentally reviewing broad branch history.
</HARD-GATE>

```bash
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](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.

<HARD-GATE>
After ALL workers in the wave report back and their changes are integrated, run one wave-scoped Outer Ralph pass. Run no story-scoped Outer Ralph pass. Do not proceed to the wave gate until the bounded recovery below passes or reaches the existing blocked path.
</HARD-GATE>

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

```bash
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

<HARD-GATE>
CodeRabbit is MANDATORY, but it is run by `wave-gate.sh`, not as a separate pre-gate command. Do NOT run a second per-wave review outside the gate.
If CodeRabbit fails to execute (e.g., not installed, auth error), the gate exits non-zero. Fix the tool/auth problem and rerun the gate.
</HARD-GATE>

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:**
```markdown
### 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.

```bash
# 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:
```markdown
### 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

<HARD-GATE>
Ken does **not** run per wave. CodeRabbit is the only per-wave review. Ken runs once at PROJ end in Skill 6, after all waves have assembled into a complete feature.
</HARD-GATE>

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
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:

```bash
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)