sisyphi 1.2.2 → 1.2.11

package/templates/orchestrator-plugin/skills/orchestration/task-patterns.md

@@ -1,266 +0,0 @@
-# Work Breakdown Patterns
-
-Patterns for how the orchestrator should structure roadmap.md for common workflow types. Each pattern shows the plan structure, agent assignments, cycle sequencing, and failure handling.
-
----
-
-## Bug Fix
-
-### When to use
-Something is broken. User reports a bug, test is failing, behavior is wrong.
-
-### Plan structure
-```
-## Bug Fix: [description]
-
-- [ ] Diagnose root cause of [bug description]
-- [ ] Implement fix for [root cause]
-- [ ] Validate fix — regression tests pass, bug is resolved
-- [ ] Review fix for unintended side effects
-```
-
-### Cycle plan
-- **Cycle 1**: Spawn `sisyphus:debug` for diagnosis. Yield.
-- **Cycle 2**: Read diagnosis report. If confident root cause found, spawn `sisyphus:implement` for fix with the diagnosis as context. Yield.
-- **Cycle 3**: Spawn `sisyphus:validate` for validation. Yield.
-- **Cycle 4**: If validation passes, spawn `sisyphus:review` for review. If fails, update plan with failure context and respawn implement. Yield.
-- **Cycle 5**: Review results. Complete or address review findings.
-
-### Failure modes
-- **Debug inconclusive**: Add more context to plan, respawn debug with narrower scope or different focus areas.
-- **Fix breaks other things**: Validation catches this. Feed validation failures back into a new implement cycle.
-- **Root cause was wrong**: Update plan with what was learned, respawn debug.
-
-### Parallelization
-Usually serial — diagnosis must complete before fix, fix before validation. Exception: if the bug affects multiple independent areas, spawn multiple debug agents in parallel.
-
----
-
-## Feature Build (Small — 1-3 files)
-
-### When to use
-Clear requirements, small scope, no formal requirements document needed.
-
-### Plan structure
-```
-## Feature: [description]
-
-- [ ] Plan implementation for [feature]
-- [ ] Implement [feature]
-- [ ] Validate implementation
-```
-
-### Cycle plan
-- **Cycle 1**: Spawn `sisyphus:plan` for planning. Yield.
-- **Cycle 2**: Spawn `sisyphus:implement` with plan path. Yield.
-- **Cycle 3**: Spawn `sisyphus:validate` for validation. Yield.
-- **Cycle 4**: Complete or fix issues.
-
-### Parallelization
-Serial. Too small to benefit from parallel agents.
-
----
-
-## Feature Build (Medium — 4-10 files)
-
-### When to use
-Feature with moderate complexity. Requirements may need clarification. Multiple files across a few modules.
-
-### Plan structure
-```
-## Feature: [description]
-
-### Requirements & Design
-- [ ] (conditional) Problem exploration — if goal is nebulous, explore before spec
-- [ ] Requirements — define acceptance criteria
-- [ ] Design — architecture, component boundaries, data models
-- [ ] Create implementation plan from requirements + design
-- [ ] Review plan against requirements + design
-
-### Implementation
-- [ ] Phase 1 — [foundation/types/interfaces]
-- [ ] Phase 2 — [core logic]
-- [ ] Critique phases 1-2
-- [ ] Phase 3 — [integration/wiring]
-- [ ] Validate — smoketest full feature e2e
-- [ ] Review implementation
-```
-
-Note: critique and validation are embedded between implementation phases, not deferred to the end. Phase 1 (types) is low-risk and doesn't need its own review, but critique catches issues before Phase 3 builds on them. Validation happens after integration, when all the pieces come together.
-
-### Cycle plan
-- **Cycle 0** (conditional): If the problem is nebulous — multiple valid framings, unclear what "done" looks like — spawn `sisyphus:problem` for interactive exploration. Yield `--mode discovery`. Skip if goal is clear and acceptance criteria are obvious.
-- **Cycle 1**: Spawn `sisyphus:spec` for combined design + requirements. Yield. (Human iterates inside the spec session.)
-- **Cycle 2**: Spawn `sisyphus:plan` for plan. Yield.
-- **Cycle 3**: Spawn `sisyphus:review-plan` for review. If fail, respawn plan with issues. Yield.
-- **Cycle 4**: Spawn `sisyphus:implement` for Phase 1. Yield.
-- **Cycle 5**: Spawn `sisyphus:implement` for Phase 2. Phase 1 is types — low risk, doesn't need its own validation. Yield.
-- **Cycle 6**: Spawn `sisyphus:review` for critique of phases 1-2. This is the checkpoint before integration builds on top. Yield.
-- **Cycle 7**: Address critique findings + spawn `sisyphus:implement` for Phase 3. Yield.
-- **Cycle 8**: `sis orch yield --mode validation` for e2e smoketest. Validation mode proves the feature works — operator for UI, evidence for every claim.
-- **Cycle 9**: Address validation failures (back to `--mode implementation`) or complete.
-
-### Failure modes
-- **Spec needs human input**: Mark session as needing human review. Orchestrator notes open questions.
-- **Plan fails review**: Feed review issues back, respawn planner.
-- **Critique finds issues in foundation**: Fix before starting integration — don't build on shaky ground.
-- **Validation fails**: Feed specifics back to implement agent for the failing area.
-
-### Parallelization
-Phases without dependencies can run in parallel. Types/interfaces (Phase 1) must complete before implementation phases that consume them. Critique can run alongside detail-planning for the next phase.
-
----
-
-## Feature Build (Large — 10+ files)
-
-### When to use
-Cross-cutting feature, multiple domains, needs team coordination. Uses **progressive planning** — high-level outline first, then detail-plan each stage as it's reached.
-
-### Plan structure
-```
-## Feature: [description]
-
-### Requirements & Design
-- [ ] (conditional) Problem exploration — if goal is nebulous
-- [ ] Requirements
-- [ ] Design
-
-### Stage Outline (high-level only — no file-level detail yet)
-1. [domain A foundation] — no deps — ~N cycles
-2. [domain B foundation] — no deps — ~N cycles
-   → critique stages 1-2 (foundation is low-risk individually, but review before building on it)
-3. [domain A implementation] — depends on 1 — ~N cycles
-4. [domain B implementation] — depends on 2 — ~N cycles
-   → critique + validate stages 3-4 (core logic, high risk — verify before integration)
-5. [integration layer] — depends on 3, 4 — ~N cycles
-   → validate end-to-end (integration is where accumulated assumptions break)
-6. [final review] — depends on all
-
-### Current Stage: [whichever is active]
-See context/{plan-lead-agent-id}/plan-stage-N-{name}.md for detail plan. (Path comes from the plan lead's submission report.)
-- [ ] [task-level items from detail plan]
-```
-
-Note: verification checkpoints are embedded in the stage outline, not deferred to a final phase. The level of rigor varies — foundation stages get a light critique, core logic gets critique + validation, integration gets full e2e validation. This is judgment, not formula.
-
-### Cycle plan
-- **Cycle 0** (conditional): If the problem is nebulous, spawn explore agents for technical landscape (yield `--mode discovery`), then spawn `sisyphus:problem` for interactive problem exploration (yield `--mode discovery`). May take 1-3 discovery cycles. Skip if the goal and scope are already clear.
-- **Cycle 1**: Spawn `sisyphus:spec` for combined design + requirements. Yield. (Human iterates inside the spec session.)
-- **Cycle 2**: Spawn `sisyphus:plan` for **high-level stage outline only**. Instruction: "Outline stages, dependencies, one-sentence descriptions, cycle estimates. Include verification checkpoints between stages based on risk." If the user's initial prompt or goal.md explicitly requested tests, also spawn `sisyphus:test-spec` for test properties in parallel; otherwise skip. Yield.
-- **Cycle 4**: Review outline. Spawn `sisyphus:plan` to **detail-plan stage 1 only** (provide outline as context). The plan agent saves under its own subdir and reports the full path — carry that path forward for the implement cycle. Yield.
-- **Cycle 5**: Spawn `sisyphus:implement` for stage 1. If stage 2 is independent, spawn `sisyphus:plan` to detail-plan stage 2 in parallel. Yield.
-- **Cycle 6**: Spawn `sisyphus:implement` for stage 2 (if detail-planned). Spawn `sisyphus:review` to critique stages 1-2 in parallel — foundation review before core logic builds on it. Detail-plan stage 3 in parallel. Yield.
-- **Cycle 7**: Address critique findings. Spawn `sisyphus:implement` for stage 3. Yield.
-- **Cycle 8**: Spawn `sisyphus:implement` for stage 4. Spawn `sisyphus:review` to critique stage 3 in parallel. Yield.
-- **Cycle 9**: Spawn `sisyphus:validate` for stages 3-4 — core logic checkpoint before integration. Address stage 3 critique. Yield.
-- **Cycle 10+**: Implement integration stage. Final review. Then `sis orch yield --mode validation` for comprehensive e2e proof.
-
-### Failure modes
-- **Detail-plan agent can't produce quality output**: The stage is still too large. Break it into sub-stages in the outline and detail-plan each sub-stage individually.
-- **Integration failures**: Often means contracts between domains don't match. Spawn debug agent targeting the integration seam.
-- **Stage N implementation invalidates stage N+1 outline**: Update the high-level outline. This is expected — it's why you don't detail-plan everything upfront.
-- **Critique finds issues after multiple stages built on top**: This is the scenario verification checkpoints exist to prevent. If it happens, you waited too long to review — add earlier checkpoints to the roadmap going forward.
-
-### Parallelization
-Maximize within the progressive pattern. Independent stages run in parallel. Detail-planning the next stage runs alongside implementing the current one. Critique and validation agents run alongside the next stage's planning or implementation. Foundation stages complete before dependent stages. Integration waits for all domain implementations.
-
----
-
-## Refactor
-
-### When to use
-Restructure code without changing behavior. Move files, rename abstractions, consolidate patterns.
-
-### Plan structure
-```
-## Refactor: [description]
-
-- [ ] Analyze current structure and plan refactor
-- [ ] Capture behavioral snapshot (existing tests + manual checks)
-- [ ] Execute refactor phase 1 — [structural changes]
-- [ ] Execute refactor phase 2 — [update consumers]
-- [ ] Validate behavior preserved — all original tests pass
-- [ ] Review for missed references, dead code, broken imports
-```
-
-### Cycle plan
-- **Cycle 1**: Spawn `sisyphus:plan` for analysis + `sisyphus:validate` to capture baseline (parallel). Yield.
-- **Cycle 2**: Spawn `sisyphus:implement` for phase 1. Yield.
-- **Cycle 3**: Spawn `sisyphus:implement` for phase 2 + `sisyphus:validate` for phase 1 (parallel). Yield.
-- **Cycle 4**: Spawn `sisyphus:validate` for full validation. Yield.
-- **Cycle 5**: Spawn `sisyphus:review` for final review. Complete.
-
-### Key principle
-**Behavior preservation is the only metric.** The refactor is correct if and only if all existing tests pass and externally observable behavior is unchanged.
-
-### Parallelization
-Limited. Refactor phases are often sequential (move before update consumers). Validation can run in parallel with the next phase if they touch different files.
-
----
-
-## Code Review
-
-### When to use
-PR review, pre-merge check, or periodic quality audit.
-
-### Plan structure
-```
-## Review: [scope]
-
-- [ ] Review [scope] for issues
-- [ ] (conditional) Fix critical/high issues found
-- [ ] Verify fixes landed (type-check, tests pass)
-```
-
-### Cycle plan
-- **Cycle 1**: Spawn `sisyphus:review` for review. Yield.
-- **Cycle 2**: If critical/high issues, spawn `sisyphus:implement` for fixes. If clean, complete.
-- **Cycle 3**: Verify fixes landed by reading fix-agent reports + running type-check/tests. Complete. Do **not** spawn a second review pass — review runs once, validation catches regressions.
-
-### Parallelization
-Review itself parallelizes internally (subagents per concern). Fix cycle is usually serial.
-
----
-
-## Investigation / Spike
-
-### When to use
-Need to understand something before committing to an approach. Prototype, explore, or answer a technical question.
-
-### Plan structure
-```
-## Investigation: [question/area]
-
-- [ ] Investigate [question/area]
-- [ ] Summarize findings and recommendation
-```
-
-### Cycle plan
-- **Cycle 1**: Spawn `sisyphus:debug` (for code investigation) or `sisyphus:general` (for broader research). Yield.
-- **Cycle 2**: Spawn `sisyphus:general` to synthesize findings. Complete.
-
-### Parallelization
-If investigating multiple independent areas, spawn parallel agents each exploring a different angle.
-
----
-
-## Tactician-Driven Implementation
-
-### When to use
-The plan exists and you want automated cycle-by-cycle execution without manual orchestrator decisions. The tactician reads the plan, dispatches one phase at a time, and tracks progress.
-
-### Plan structure
-```
-## Tactician Execution
-
-- [ ] Execute implementation plan at [path] using tactician loop
-```
-
-### Cycle plan
-This is a single-item pattern. The orchestrator spawns the tactician once:
-- **Cycle 1**: Spawn `sisyphus:tactician` with plan path. The tactician internally dispatches implement/validate agents via submit tool actions. The orchestrator's role is minimal — just monitor the tactician's completion report.
-
-### When NOT to use
-- When you need human checkpoints between phases
-- When phases have external dependencies (waiting on API access, design review, etc.)
-- When the task requires creative decisions the tactician shouldn't make alone

package/templates/orchestrator-plugin/skills/orchestration/workflow-examples.md

@@ -1,428 +0,0 @@
-# Workflow Examples
-
-End-to-end examples showing how the orchestrator structures cycles for real scenarios.
-
-### Path conventions in these examples
-
-Plan files live under per-plan-lead subdirectories: `context/{plan-lead-agent-id}/plan-*.md`. These examples elide the subdir (showing `context/plan-rate-limiting.md`) for readability. In a real cycle, the orchestrator reads the exact path from the plan lead's submission report and carries it verbatim into downstream implement, review-plan, and validate agent prompts.
-
----
-
-## Example 4: Wrapper-Shaped Config Migration (LOW effort — 5 files, mechanical)
-
-**Starting task**: "All config access goes through `process.env` directly — migrate to a `getConfig()` wrapper already defined in `src/config.ts`"
-
-**Effort tier**: LOW. Every change is a call-site swap onto an existing handler. No new behavior.
-
-### Cycle 1 — Plan
-```
-roadmap.md:
-  ## Refactor: Migrate env access to getConfig()
-
-  - [ ] Plan migration — enumerate all process.env call sites
-  - [ ] Update call sites to use getConfig()
-  - [ ] Validate — no direct process.env access remains; tests pass
-
-Agents spawned:
-  plan agent → "Enumerate every direct process.env access in src/. Map each call site
-    to the matching getConfig() key. Output a migration checklist. Files expected:
-    src/api/server.ts, src/db/connection.ts, src/queue/worker.ts,
-    src/cli/commands/start.ts, src/config.ts (source of truth — do not modify)."
-```
-
-### Cycle 2 — Implement
-```
-Plan complete. 23 call sites across 4 files.
-
-Agents spawned:
-  implement agent → "Execute migration plan at context/{plan-agent-id}/plan-config-migration.md.
-    Replace every process.env.X access with getConfig('X'). Do not modify src/config.ts.
-    Do not add error handling — getConfig() already throws on missing keys."
-```
-
-### Cycle 3 — Validate + complete
-```
-Implementation complete.
-
-Agents spawned:
-  validate agent → "Verify migration: grep for remaining process.env access in src/ (excluding
-    src/config.ts). Run existing tests. Confirm zero direct env reads outside config.ts."
-
-Validation: PASS. Complete — "All env access routed through getConfig()."
-```
-
-**Pipeline shape**: `plan → implement → validate`. 3 cycles. No `sisyphus:spec`, no `sisyphus:test-spec`, no `sisyphus:review-plan`.
-
----
-
-## Example 5: New Subsystem — Distributed Task Queue (HIGH effort)
-
-**Starting task**: "Add a persistent task queue so long-running jobs survive server restarts. Include test coverage of the survival, retry, and concurrency invariants."
-
-**Effort tier**: HIGH. New subsystem, new protocol (worker ↔ queue contract), cross-domain orchestration (API + storage + worker process). The prompt explicitly asks for test coverage — `sisyphus:test-spec` is justified at Cycle 2.
-
-### Cycle 0 — Problem exploration
-```
-roadmap.md:
-  ## Feature: Persistent Task Queue
-
-  - [ ] Explore current job execution patterns and constraints
-  - [ ] Spec — requirements + architecture
-  - [ ] Plan implementation (staged outline)
-  - [ ] Spec behavioral properties (test-spec) — user asked for tests in the prompt
-  ...
-
-Agents spawned:
-  explore agent → "Map current job execution in src/jobs/. Identify what needs to survive
-    restarts, current storage backends, worker process lifecycle."
-  problem agent → "Explore design space for persistent task queue. Questions: push vs pull
-    worker model, at-least-once vs exactly-once semantics, failure/retry policy, storage
-    backend options (Redis, Postgres, SQLite)."
-```
-
-### Cycle 1 — Spec (human iterates)
-```
-Agents spawned:
-  sisyphus:spec → "Run spec session for persistent task queue.
-    Context in context/problem-task-queue.md and context/explore-task-queue.md."
-
-Human iterates. Spec outputs:
-  context/requirements-task-queue.md — acceptance criteria, failure semantics
-  context/design-task-queue.md — Redis-backed queue, pull workers, at-least-once delivery
-```
-
-### Cycle 2 — High-level plan + test-spec (parallel)
-```
-Agents spawned (parallel):
-  plan agent → "Create high-level stage outline from context/requirements-task-queue.md
-    and context/design-task-queue.md. Stages: (1) queue storage layer, (2) producer API,
-    (3) worker consumer, (4) integration + retry logic. Cycle estimates per stage."
-  test-spec agent → "Define behavioral properties: job survives server restart, failed
-    jobs retry up to N times, concurrent workers don't double-execute the same job."
-```
-
-If the original prompt had been silent on tests, the test-spec spawn would be omitted and Cycle 2 would be plan-only — Cycle 3 would then proceed straight to detail-planning stage 1.
-
-### Cycles 3–9 — Staged implementation with critique + validation checkpoints
-```
-Follows Feature Build Large pattern:
-  Cycle 3: detail-plan stage 1 + implement stage 1
-  Cycle 4: implement stage 2; detail-plan stage 3 in parallel
-  Cycle 5: critique stages 1-2 (foundation review before worker builds on it)
-  Cycle 6: address critique + implement stage 3
-  Cycle 7: implement stage 4 (integration + retry); validate stages 3-4
-  Cycle 8: sis orch yield --mode validation — e2e: enqueue job, kill server, restart,
-    confirm job ran exactly once
-  Cycle 9: final review agent; complete
-```
-
-**Pipeline shape**: Full HIGH pipeline — `problem → spec → plan (+ test-spec because the prompt asked for tests) → staged implement → critique → validate → review`. 9+ cycles. Without an explicit test request in the prompt, the parallel `test-spec` would be omitted and Cycle 2 would be plan-only.
-
----
-
-## Example 1: Fix a Race Condition in WebSocket Reconnection
-
-**Starting task**: "WebSocket connections sometimes drop messages during reconnection"
-
-### Cycle 1 — Diagnosis
-```
-roadmap.md:
-  ## Bug Fix: WebSocket message loss during reconnection
-
-  - [ ] Diagnose message loss during WebSocket reconnection
-  - [ ] Fix root cause
-  - [ ] Validate fix under concurrent load
-  - [ ] Review fix
-
-Agents spawned:
-  debug agent → "Diagnose why WebSocket messages are lost during reconnection.
-    Focus on src/ws/client.ts and src/ws/reconnect.ts.
-    Check for race conditions between disconnect handler and message queue.
-    Look at git blame for recent changes to reconnection logic."
-```
-
-### Cycle 2 — Read diagnosis, plan fix
-```
-Agent report: "Root cause: reconnect() clears the message queue before the new socket
-  is ready. Messages sent between disconnect and reconnect are dropped.
-  Line 47 of src/ws/reconnect.ts — queue.clear() is called in onDisconnect
-  but should be deferred until onReconnect confirms the new socket is live.
-  Confidence: High."
-
-roadmap.md updated:
-  - [x] ~~Diagnose message loss during WebSocket reconnection~~
-  - [ ] Fix root cause — queue.clear() at L47 of reconnect.ts runs too early
-  - [ ] Validate fix under concurrent load
-  - [ ] Review fix
-
-Agents spawned:
-  implement agent → "Fix race condition in src/ws/reconnect.ts.
-    Root cause: queue.clear() at line 47 runs on disconnect, dropping pending messages.
-    Fix: defer queue drain until reconnect confirms new socket. Buffer messages during
-    reconnection window. See existing buffer pattern in src/ws/buffer.ts."
-```
-
-### Cycle 3 — Validate
-```
-Agent report: "Fixed. Moved queue.clear() to onReconnect callback after socket.readyState
-  confirms OPEN. Added message buffer during reconnection window. 2 files changed."
-
-roadmap.md updated:
-  - [x] ~~Diagnose message loss~~
-  - [x] ~~Fix root cause~~
-  - [ ] Validate fix under concurrent load
-  - [ ] Review fix
-
-Agents spawned:
-  validate agent → "Verify WebSocket reconnection fix. Run existing tests in
-    src/__tests__/ws/. Manually verify: disconnect simulation should not lose queued
-    messages. Check that buffer drains correctly on reconnect."
-```
-
-### Cycle 4 — Review and complete
-```
-Validation: PASS. Existing tests pass, reconnection preserves messages.
-
-roadmap.md updated:
-  - [x] ~~Diagnose~~, [x] ~~Fix~~, [x] ~~Validate~~
-  - [ ] Review fix
-
-Agents spawned:
-  review agent → "Review changes in src/ws/reconnect.ts and src/ws/buffer.ts.
-    Focus on: thread safety of the new buffer, memory leak potential if reconnect
-    never succeeds, edge case of rapid disconnect/reconnect cycles."
-```
-
-### Cycle 5 — Complete
-```
-Review: Clean. One medium finding — buffer should have a max size to prevent
-  memory issues if reconnect fails indefinitely. Not blocking.
-
-All roadmap.md items complete.
-
-Action: complete — "Fixed WebSocket message loss during reconnection. Messages now
-  buffered during reconnection window and drained on successful reconnect."
-```
-
----
-
-## Example 2: Add API Rate Limiting
-
-**Starting task**: "Add rate limiting to the REST API — per-user, configurable limits, with tests for the limit-enforcement and 429 response behavior"
-
-### Cycle 1 — Problem exploration
-```
-roadmap.md:
-  ## Feature: API Rate Limiting
-
-  ### Requirements & Design
-  - [ ] Problem exploration — understand rate limiting needs
-  - [ ] Requirements — define acceptance criteria
-  - [ ] Design — architecture for rate limiting
-  - [ ] Plan implementation
-  - [ ] Review plan
-
-  ### Implementation
-  - [ ] Implement rate limiting middleware
-  - [ ] Implement rate limit configuration
-  - [ ] Implement rate limit headers and error responses
-
-  ### Validation
-  - [ ] Validate implementation
-  - [ ] Review implementation
-
-Agents spawned:
-  problem agent → "Explore the codebase and understand the API rate limiting landscape.
-    Check existing middleware patterns in src/api/middleware/.
-    Questions to explore: current request handling, existing auth/middleware chain,
-    what storage backends are available (Redis?), user identification mechanisms."
-```
-
-### Cycle 2 — Spec (after human iterates on problem)
-```
-Agent report: "Problem document saved to context/problem-rate-limiting.md.
-  Current middleware chain uses Express middleware pattern. Redis is already in stack.
-  Users are identified by JWT sub claim. No existing rate limiting."
-
-roadmap.md updated:
-  - [x] ~~Problem exploration~~
-  - [ ] Spec — define acceptance criteria and architecture
-  ...
-
-Agents spawned:
-  sisyphus:spec → "Run a spec session for per-user API rate limiting. Read context/problem-rate-limiting.md for context."
-
-Later report: "Spec completed.
-  Requirements saved to context/requirements-rate-limiting.md.
-  Design saved to context/design-rate-limiting.md.
-  Covers: per-user limits, endpoint-specific overrides, 429 response format,
-  Retry-After headers, and a Redis-backed sliding window approach."
-```
-
-### Cycle 3 — Plan (after human reviews spec)
-```
-Agent report: "Spec outputs approved.
-  Approach: Redis-backed sliding window middleware. Per-user with endpoint-specific
-  overrides. Standard 429 response with Retry-After header. Config via environment variables."
-
-roadmap.md updated:
-  - [x] ~~Problem exploration~~, [x] ~~Spec~~
-  - [ ] Plan implementation
-  ...
-
-Agents spawned:
-  plan agent → "Create implementation plan from context/requirements-rate-limiting.md
-    and context/design-rate-limiting.md"
-  test-spec agent → "Define behavioral properties for rate limiting from
-    context/requirements-rate-limiting.md"
-```
-
-### Cycle 4 — Review plan
-```
-Both agents complete. Plan at context/plan-rate-limiting.md.
-Plan has 3 phases: middleware, config, response format.
-
-Agents spawned:
-  review-plan agent → "Validate plan at context/plan-rate-limiting.md
-    against context/requirements-rate-limiting.md and context/design-rate-limiting.md"
-```
-
-### Cycle 5 — Implement phases 1+2 (parallel, low-risk foundation)
-```
-Plan review: PASS.
-
-roadmap.md updated (plan review done, starting implementation):
-  - [x] ~~Spec~~, [x] ~~Plan~~, [x] ~~Review plan~~
-  - [ ] Implement rate limiting middleware
-  - [ ] Implement rate limit configuration
-  - [ ] Critique phases 1-2 — review before integration phase
-  - [ ] Implement rate limit headers and error responses
-  - [ ] Validate — smoketest rate limiting end-to-end
-  - [ ] Final review
-
-Agents spawned (parallel — phases touch different files):
-  implement agent → "Implement Phase 1 from context/plan-rate-limiting.md —
-    rate limiting middleware in src/api/middleware/rate-limit.ts"
-  implement agent → "Implement Phase 2 from context/plan-rate-limiting.md —
-    rate limit configuration in src/config/rate-limits.ts"
-```
-
-### Cycle 6 — Critique before integration builds on top
-```
-Both implementation agents complete.
-
-Why critique now: Phase 3 (headers/error responses) integrates the middleware and
-  config — if the foundation has issues, they'll cascade. Cheaper to catch now.
-
-roadmap.md updated:
-  - [x] ~~Implement middleware~~, [x] ~~Implement config~~
-  - [ ] Critique phases 1-2
-  ...
-
-Agents spawned:
-  review agent → "Review rate limiting middleware and config implementation.
-    Focus on: Redis connection handling, sliding window correctness,
-    config schema matches what middleware expects."
-```
-
-### Cycle 7 — Implement phase 3 + address critique
-```
-Review: 2 findings — middleware doesn't handle Redis connection failure gracefully,
-  config schema allows negative rate limits.
-
-Agents spawned (parallel):
-  implement agent → "Fix review findings in reports/agent-008-final.md for
-    rate limiting middleware and config."
-  implement agent → "Implement Phase 3 from context/plan-rate-limiting.md —
-    rate limit headers and 429 error responses in src/api/middleware/rate-limit.ts"
-```
-
-### Cycle 8 — Validate end-to-end
-```
-Phase 3 and fixes complete.
-
-Why validate now: all three phases are done and integrated. This is the checkpoint
-  before calling it complete — verify it actually works, not just compiles.
-
-Agents spawned:
-  validate agent → "Verify rate limiting end-to-end: start server, send requests
-    exceeding limits, confirm 429 responses with correct Retry-After headers.
-    Test per-user isolation, endpoint-specific overrides, Redis failover behavior."
-```
-
-### Cycle 10 — Complete
-```
-Validation: PASS. Final review agent confirms no issues.
-Complete — "Added per-user API rate limiting with Redis-backed sliding window,
-  configurable per-endpoint limits, and graceful Redis failover."
-```
-
----
-
-## Example 3: Refactor Authentication Module
-
-**Starting task**: "Refactor auth — extract token logic from route handlers into dedicated service"
-
-### Cycle 1 — Plan + baseline
-```
-roadmap.md:
-  ## Refactor: Extract Token Service
-
-  - [ ] Plan auth refactor — extract token service
-  - [ ] Capture behavioral baseline (run all auth tests)
-  - [ ] Create TokenService class with extracted logic
-  - [ ] Update route handlers to use TokenService
-  - [ ] Update tests to use new service interface
-  - [ ] Validate all auth tests still pass
-  - [ ] Review for dead code and missed references
-
-Agents spawned (parallel):
-  plan agent → "Plan refactor: extract token creation, validation, and refresh
-    logic from src/api/routes/auth.ts into a new src/services/token-service.ts.
-    Map all token-related functions, their callers, and the extraction plan."
-  validate agent → "Run all tests in src/__tests__/auth/ and record results.
-    This is the behavioral baseline — these must all pass after refactor."
-```
-
-### Cycle 2 — Extract (serial — must happen before consumer updates)
-```
-Plan complete, baseline captured (47 tests passing).
-
-roadmap.md updated:
-  - [x] ~~Plan auth refactor~~
-  - [x] ~~Capture behavioral baseline~~ (47 tests passing)
-  - [ ] Create TokenService class with extracted logic
-  ...
-
-Agents spawned:
-  implement agent → "Execute Phase 1 of refactor plan: create TokenService class
-    at src/services/token-service.ts. Extract validateToken, createToken, refreshToken
-    from src/api/routes/auth.ts. Export the class. Do NOT modify route handlers yet."
-```
-
-### Cycle 3 — Update consumers (parallel where possible)
-```
-TokenService created.
-
-Agents spawned:
-  implement agent → "Update route handlers in src/api/routes/auth.ts to import
-    and use TokenService instead of inline token logic. Remove extracted functions."
-  implement agent → "Update tests in src/__tests__/auth/ to use TokenService
-    where they directly tested extracted functions."
-```
-
-### Cycle 4 — Validate + review
-```
-Agents spawned (parallel):
-  validate agent → "Run all auth tests. Compare against baseline of 47 passing.
-    Every test must still pass."
-  review agent → "Review src/api/routes/auth.ts and src/services/token-service.ts.
-    Check for: dead code left behind, missed references to old functions, broken imports."
-```
-
-### Cycle 5 — Complete
-```
-All 47 tests passing. Review clean.
-All roadmap.md items complete.
-Complete — "Extracted token logic into TokenService. All existing tests pass."
-```