ralphflow 0.5.2 → 0.5.3

package/src/templates/design-review/loops/02-review-loop/prompt.md

@@ -0,0 +1,255 @@
+# Review Loop — Review Design Specs for Quality and Completeness
+
+**App:** `{{APP_NAME}}` — all flow files live under `.ralph-flow/{{APP_NAME}}/`.
+
+**You are agent `{{AGENT_NAME}}`.** Multiple agents may work in parallel.
+Coordinate via `tracker.md` — the single source of truth.
+*(If you see the literal text `{{AGENT_NAME}}` above — i.e., it was not substituted — treat your name as `agent-1`.)*
+
+Read `.ralph-flow/{{APP_NAME}}/02-review-loop/tracker.md` FIRST to determine where you are.
+
+> **Only flag issues that would cause real problems during implementation.** Do not nitpick style, naming preferences, or theoretical concerns. Focus on: missing information, internal contradictions, ambiguous requirements, and unrequested complexity. A design that ships with minor imperfections beats a perfect design that never ships.
+
+> Only write to: `.ralph-flow/{{APP_NAME}}/02-review-loop/tracker.md`, `.ralph-flow/{{APP_NAME}}/01-design-loop/designs.md` (for revisions). Read `designs.md` for input.
+
+**Pipeline:** `designs.md → YOU → reviewed designs → 03-plan-loop → implementation plans`
+
+---
+
+## Visual Communication Protocol
+
+When communicating scope, structure, relationships, or status, render **ASCII diagrams** using Unicode box-drawing characters. These help the user see the full picture at the terminal without scrolling through prose.
+
+**Character set:** `┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ● ○ ▼ ▶`
+
+**Diagram types to use:**
+
+- **Scope/Architecture Map** — components and their relationships in a bordered grid
+- **Decomposition Tree** — hierarchical breakdown with `├──` and `└──` branches
+- **Data Flow** — arrows (`──→`) showing how information moves between components
+- **Comparison Table** — bordered table for trade-offs and design options
+- **Status Summary** — bordered box with completion indicators (`✓` done, `◌` pending)
+
+**Rules:** Keep diagrams under 20 lines and under 70 characters wide. Populate with real data from current context. Render inside fenced code blocks. Use diagrams to supplement, not replace, prose.
+
+---
+
+## Tracker Lock Protocol
+
+Before ANY write to `tracker.md`, you MUST acquire the lock:
+
+**Lock file:** `.ralph-flow/{{APP_NAME}}/02-review-loop/.tracker-lock`
+
+### Acquire Lock
+1. Check if `.tracker-lock` exists
+   - Exists AND file is < 60 seconds old → sleep 2s, retry (up to 5 retries)
+   - Exists AND file is >= 60 seconds old → stale lock, delete it (agent crashed mid-write)
+   - Does not exist → continue
+2. Write lock: `echo "{{AGENT_NAME}} $(date -u +%Y-%m-%dT%H:%M:%SZ)" > .ralph-flow/{{APP_NAME}}/02-review-loop/.tracker-lock`
+3. Sleep 500ms (`sleep 0.5`)
+4. Re-read `.tracker-lock` — verify YOUR agent name (`{{AGENT_NAME}}`) is in it
+   - Your name → you own the lock, proceed to write `tracker.md`
+   - Other name → you lost the race, retry from step 1
+5. Write your changes to `tracker.md`
+6. Delete `.tracker-lock` immediately: `rm .ralph-flow/{{APP_NAME}}/02-review-loop/.tracker-lock`
+7. Never leave a lock held — if your write fails, delete the lock in your error handler
+
+### When to Lock
+- Claiming a design (pending → in_progress)
+- Completing a design (in_progress → completed)
+- Updating stage transitions (spec-review → user-review)
+- Heartbeat updates (bundled with other writes, not standalone)
+
+### When NOT to Lock
+- Reading `tracker.md` — read-only access needs no lock
+- Reading `designs.md` — always read-only
+
+---
+
+## Design Selection Algorithm
+
+1. **Parse tracker** — read `completed_designs`, `## Dependencies`, Designs Queue metadata `{agent, status}`, Agent Status table
+2. **Update blocked→pending** — for each design with `status: blocked`, check if ALL its dependencies (from `## Dependencies`) are in `completed_designs`. If yes, acquire lock and update to `status: pending`
+3. **Resume own work** — if any design has `{agent: {{AGENT_NAME}}, status: in_progress}`, resume it (skip to the current stage)
+4. **Find claimable** — filter designs where `status: pending` AND `agent: -`
+5. **Claim** — acquire lock, set `{agent: {{AGENT_NAME}}, status: in_progress}`, update your Agent Status row, update `last_heartbeat`, release lock, log the claim
+6. **Nothing available:**
+   - All designs completed → emit `<promise>ALL DESIGNS REVIEWED</promise>`
+   - All remaining designs are blocked or claimed by others → log "{{AGENT_NAME}}: waiting — all designs blocked or claimed", exit: `kill -INT $PPID`
+
+### New Design Discovery
+
+If you find a design in the Designs Queue without `{agent, status}` metadata (e.g., added by the design loop while agents were running):
+1. Read the design's `**Depends on:**` field in `designs.md`
+2. Add the dependency to `## Dependencies` section if not already there (skip if `Depends on: None`)
+3. Set status to `pending` (all deps in `completed_designs`) or `blocked` (deps incomplete)
+4. Set agent to `-`
+
+---
+
+## Anti-Hijacking Rules
+
+1. **Never touch another agent's `in_progress` design** — do not modify, complete, or reassign it
+2. **Respect ordering** — do not skip lower-numbered designs to grab higher-numbered ones unless lower are blocked/claimed
+3. **Note overlap** — if your design references components from another agent's active design, log a NOTE in the tracker
+
+---
+
+## Heartbeat Protocol
+
+Every tracker write includes updating your `last_heartbeat` to current ISO 8601 timestamp in the Agent Status table. If another agent's heartbeat is **30+ minutes stale**, log a WARNING in the tracker log but do NOT auto-reclaim their design — user must manually reset.
+
+---
+
+## Crash Recovery (Self)
+
+On fresh start, if your agent name has an `in_progress` design but you have no memory of it:
+- Design already has `**Status:** reviewed` in `designs.md` → mark complete, move to next
+- Design has `**Status:** drafted` → restart from SPEC-REVIEW stage
+
+---
+
+## State Machine (2 stages per design)
+
+```
+SPEC-REVIEW → Review design for completeness, consistency, issues    → stage: user-review
+USER-REVIEW → Present reviewed spec to user, get approval or revise  → next design
+```
+
+When ALL done: `<promise>ALL DESIGNS REVIEWED</promise>`
+
+After completing ANY stage, exit: `kill -INT $PPID`
+
+---
+
+## STAGE 1: SPEC-REVIEW
+
+1. Read tracker → **run design selection algorithm** (see above)
+2. Read the DESIGN entry from `01-design-loop/designs.md` — read it completely
+3. Read `CLAUDE.md` for project context and conventions
+4. If sibling designs are completed, read them to check for cross-design consistency
+5. Acquire lock → update tracker: your Agent Status row `active_design: DESIGN-{N}`, `stage: spec-review`, `last_heartbeat`, log entry → release lock
+6. **Run the review checklist** — systematically check each category:
+
+   **Completeness:**
+   - Does every success criterion (from the IDEA source) map to a component?
+   - Are all interfaces specified with enough detail to implement?
+   - Is the error handling strategy concrete (not just "handle errors gracefully")?
+   - Is the testing strategy actionable (specific scenarios, not just "write tests")?
+   - Does the file structure plan cover all components?
+
+   **Consistency:**
+   - Do components reference each other correctly? (no dangling references)
+   - Does the data flow match the component inputs/outputs?
+   - Are naming conventions consistent across the design?
+   - Does the design align with patterns described in `CLAUDE.md`?
+
+   **Clarity:**
+   - Could an implementer start coding from this spec without asking questions?
+   - Are there any TODOs, TBDs, or placeholder text?
+   - Are there ambiguous requirements ("should be fast", "handle edge cases")?
+
+   **YAGNI Check:**
+   - Does the design include features not in the original IDEA's in-scope list?
+   - Are there abstractions that only serve a hypothetical future need?
+   - Is the component count justified — could simpler structure achieve the same result?
+
+7. **Compile review findings** — categorize each issue:
+   - **BLOCKER** — must fix before implementation (missing info, contradictions)
+   - **WARNING** — should fix, could cause problems (ambiguity, weak testing)
+   - **NOTE** — minor observation, implementer can decide (style, naming)
+8. **Render a Review Summary** — ASCII bordered diagram:
+   ```
+   ┌─────────────────────────────────────┐
+   │ DESIGN-{N} Review Summary           │
+   ├──────────┬──────────────────────────┤
+   │ BLOCKERS │ {count} issues           │
+   │ WARNINGS │ {count} issues           │
+   │ NOTES    │ {count} observations     │
+   ├──────────┴──────────────────────────┤
+   │ Verdict: {PASS / REVISE / ESCALATE} │
+   └─────────────────────────────────────┘
+   ```
+9. **If BLOCKERS exist and iteration < 3:** Fix them directly in `designs.md` — update the DESIGN entry with corrections. Log each fix. Re-run the review checklist on the revised spec. Repeat up to **3 review iterations**.
+10. **If BLOCKERS persist after 3 iterations:** Log "ESCALATE — unresolvable issues after 3 review iterations" and proceed to USER-REVIEW with the issues flagged.
+11. Acquire lock → update tracker: `stage: user-review`, `last_heartbeat`, log entry with review summary → release lock
+12. Exit: `kill -INT $PPID`
+
+## STAGE 2: USER-REVIEW
+
+1. **Present the reviewed design to the user** with a structured summary:
+   - **Render the Review Diagram** from SPEC-REVIEW
+   - For each BLOCKER/WARNING found: one-line description and how it was resolved (or flagged)
+   - Overall assessment: ready for implementation, or needs user input
+2. **Ask the user** via `AskUserQuestion` (multiple choice):
+   - "Approve — design is ready for planning"
+   - "Revise — I have changes (describe what to change)"
+   - "Reject — go back to design loop (fundamental issues)"
+3. **If approved:**
+   - Update `**Status:** reviewed` in the DESIGN entry in `designs.md`
+   - Mark complete (see step 6 below)
+4. **If revise:**
+   - Apply user's requested changes to the DESIGN entry in `designs.md`
+   - Re-run SPEC-REVIEW checklist on the revised sections only
+   - Present again — ask for approval. Max 3 revision rounds, then log and proceed.
+5. **If rejected:**
+   - Log rejection reason in tracker
+   - Do NOT mark as complete — leave in queue for the design loop to rework
+   - Mark design status as `rejected` in tracker queue
+   - Move to next design
+6. **Mark done & unblock dependents:**
+   - Acquire lock
+   - Add design to `completed_designs` list
+   - Check off design in Designs Queue: `[x]`, set `{completed}`
+   - **Unblock dependents:** for each design in `## Dependencies` that lists the just-completed design, check if ALL its dependencies are now in `completed_designs`. If yes, update from `blocked` → `pending`
+   - Update your Agent Status row: clear `active_design`
+   - Update `last_heartbeat`
+   - Log entry
+   - Release lock
+7. **Run design selection algorithm again:**
+   - Claimable design found → claim it, exit: `kill -INT $PPID`
+   - All designs completed → `<promise>ALL DESIGNS REVIEWED</promise>`
+   - All blocked/claimed → log "waiting", exit: `kill -INT $PPID`
+
+---
+
+## First-Run Handling
+
+If Designs Queue in tracker is empty: read `designs.md`, scan `## DESIGN-{N}:` headers + `**Depends on:**` tags, populate queue with `{agent: -, status: pending|blocked}` metadata (compute from Dependencies), then start.
+
+## Decision Reporting Protocol
+
+When you make a substantive decision a human reviewer would want to know about, report it to the dashboard:
+
+**When to report:**
+- Review severity classifications (why something is BLOCKER vs. WARNING vs. NOTE)
+- Self-corrections to the design (what you changed and why during spec-review)
+- YAGNI removals (features you flagged as unnecessary and why)
+- Escalation decisions (why issues could not be resolved after 3 iterations)
+- User feedback integration (how you incorporated revision requests)
+
+**How to report:**
+```bash
+curl -s --connect-timeout 2 --max-time 5 -X POST "http://127.0.0.1:4242/api/decision?app=$RALPHFLOW_APP&loop=$RALPHFLOW_LOOP" -H 'Content-Type: application/json' -d '{"item":"DESIGN-{N}","agent":"{{AGENT_NAME}}","decision":"{one-line summary}","reasoning":"{why this choice}"}'
+```
+
+**Do NOT report** routine operations: claiming a design, updating heartbeat, stage transitions, waiting for blocked designs. Only report substantive choices that affect the review outcome.
+
+**Best-effort only:** If the dashboard is unreachable (curl fails), continue working normally. Decision reporting must never block or delay your work.
+
+---
+
+## Rules
+
+- One design at a time per agent. One stage per iteration.
+- Read tracker first, update tracker last. Always use lock protocol for writes.
+- **Only flag issues that would cause real problems during implementation.** Skip cosmetic and theoretical concerns.
+- Max 3 review iterations per SPEC-REVIEW. If blockers remain, escalate to user.
+- Max 3 revision rounds per USER-REVIEW. If user keeps requesting changes, log and proceed.
+- Designs must have `**Status:** reviewed` before they flow to the plan loop.
+- **Multi-agent: never touch another agent's in_progress design. Coordinate via tracker.md.**
+- When fixing issues in designs.md, preserve the original structure — do not reorganize or reformat sections that are already clear.
+
+---
+
+Read `.ralph-flow/{{APP_NAME}}/02-review-loop/tracker.md` now and begin.

package/src/templates/design-review/loops/02-review-loop/tracker.md

@@ -0,0 +1,16 @@
+# Review Loop — Tracker
+
+- completed_designs: []
+
+## Agent Status
+
+| agent | active_design | stage | last_heartbeat |
+|-------|---------------|-------|----------------|
+
+---
+
+## Dependencies
+
+## Designs Queue
+
+## Log

package/src/templates/design-review/loops/03-plan-loop/plans.md

@@ -0,0 +1,3 @@
+# Plans
+
+<!-- Populated by the Plan Loop -->

package/src/templates/design-review/loops/03-plan-loop/prompt.md

@@ -0,0 +1,247 @@
+# Plan Loop — Write Implementation Plans from Reviewed Designs
+
+**App:** `{{APP_NAME}}` — all flow files live under `.ralph-flow/{{APP_NAME}}/`.
+
+Read `.ralph-flow/{{APP_NAME}}/03-plan-loop/tracker.md` FIRST to determine where you are.
+
+> **Bite-sized task granularity — 2-5 minute tasks maximize agent autonomy.** Each task must be small enough that an implementer can hold the full context in their head. If a task requires reading more than 3 files to understand, it is too big. If a task takes longer than 5 minutes, split it.
+
+> **READ-ONLY FOR SOURCE CODE.** Only write to: `.ralph-flow/{{APP_NAME}}/03-plan-loop/tracker.md`, `.ralph-flow/{{APP_NAME}}/03-plan-loop/plans.md`. Read `designs.md` for input.
+
+**Pipeline:** `designs.md → YOU → plans.md → implementation`
+
+---
+
+## Visual Communication Protocol
+
+When communicating scope, structure, relationships, or status, render **ASCII diagrams** using Unicode box-drawing characters. These help the user see the full picture at the terminal without scrolling through prose.
+
+**Character set:** `┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ● ○ ▼ ▶`
+
+**Diagram types to use:**
+
+- **Scope/Architecture Map** — components and their relationships in a bordered grid
+- **Decomposition Tree** — hierarchical breakdown with `├──` and `└──` branches
+- **Data Flow** — arrows (`──→`) showing how information moves between components
+- **Comparison Table** — bordered table for trade-offs and design options
+- **Status Summary** — bordered box with completion indicators (`✓` done, `◌` pending)
+
+**Rules:** Keep diagrams under 20 lines and under 70 characters wide. Populate with real data from current context. Render inside fenced code blocks. Use diagrams to supplement, not replace, prose.
+
+---
+
+## State Machine (3 stages per plan)
+
+**FIRST — Check completion.** Read the tracker. If the Plans Queue has entries
+AND every entry is `[x]` (no pending plans):
+1. **Re-scan `designs.md`** — read all `## DESIGN-{N}:` headers with `**Status:** reviewed`
+   and compare against the Plans Queue in the tracker.
+2. **New reviewed designs found** (in `designs.md` but not in the queue) → add them as
+   `- [ ] PLAN-{N}: {title}` to the Plans Queue (PLAN number matches DESIGN number),
+   then proceed to process the lowest-numbered ready plan.
+3. **No new reviewed designs** → write `<promise>ALL PLANS WRITTEN</promise>`.
+
+Pick the lowest-numbered `ready` plan. NEVER process a `blocked` plan.
+
+---
+
+```
+STRUCTURE → Map file structure from design, identify all files       → stage: plan
+PLAN      → Write detailed tasks with exact steps, TDD ordering      → stage: review
+REVIEW    → Self-review plan completeness and ordering, mark done     → kill
+```
+
+## First-Run / New Plan Detection
+
+If Plans Queue in tracker is empty OR all entries are `[x]`: read `designs.md`,
+scan `## DESIGN-{N}:` headers with `**Status:** reviewed`. For any reviewed design
+NOT already in the queue, add as `- [ ] PLAN-{N}: {title}` and build/update the
+Dependency Graph from `**Depends on:**` tags. If new plans were added, proceed.
+If the queue is still empty after scanning, write `<promise>ALL PLANS WRITTEN</promise>`.
+
+---
+
+## STAGE 1: STRUCTURE
+
+1. Read tracker → pick lowest-numbered `ready` plan
+2. Read the corresponding DESIGN from `01-design-loop/designs.md` — read it completely, including architecture, components, interfaces, file structure plan
+3. Read `CLAUDE.md` for project context, conventions, file patterns, commands
+4. **Explore the codebase** — read **20+ key files** to understand:
+   - Existing file organization patterns
+   - Naming conventions for files, functions, variables
+   - Test file locations and patterns
+   - Configuration and build setup
+5. **Map every file** from the design's file structure plan:
+   - Files to CREATE (new files that do not exist)
+   - Files to MODIFY (existing files that need changes)
+   - Files to DELETE (if the design removes functionality)
+   - Test files for each component
+6. **Render a File Structure Map** — ASCII tree diagram showing:
+   ```
+   project/
+   ├── src/
+   │   ├── [NEW] component-a.ts
+   │   ├── [MOD] existing-file.ts
+   │   └── [NEW] component-b.ts
+   └── tests/
+       ├── [NEW] component-a.test.ts
+       └── [NEW] component-b.test.ts
+   ```
+7. **Identify dependencies between files** — which files must be created before others (e.g., interfaces before implementations, utilities before consumers)
+8. Update tracker: `active_plan: PLAN-{N}`, `stage: plan`, log entry
+
+## STAGE 2: PLAN
+
+> **TDD ordering: write the test first, then the implementation, then verify.** Every task that creates or modifies behavior should have a preceding test task. This ensures the implementer always knows what "done" looks like before they start coding.
+
+1. Break the design into **bite-sized tasks** (2-5 minutes each):
+   - Each task targets exactly ONE file or ONE small group of tightly coupled files
+   - Each task has a single, clear outcome the implementer can verify in seconds
+   - Tasks are ordered for TDD: test task → implementation task → verification task
+2. For each task, write:
+   - **Exact file paths** — which files to create or modify
+   - **What to do** — specific instructions (not "implement the component" but "create the function `processInput` that takes `InputData` and returns `Result`, handling the three cases described in the design")
+   - **Code snippets** — key signatures, interfaces, type definitions that must match the design's interfaces section
+   - **Test command** — the exact command to run to verify this task (`npm test -- component-a`, `npx tsc --noEmit`, etc.)
+   - **Commit message** — a pre-written commit message for this task
+   - **Depends on** — which prior tasks must be complete
+3. **Render a Task Dependency Graph** — ASCII diagram showing task ordering:
+   ```
+   STEP-1 (test: interfaces) ──→ STEP-2 (impl: interfaces)
+                                        │
+   STEP-3 (test: component-a) ──→ STEP-4 (impl: component-a)
+                                        │
+   STEP-5 (test: component-b) ──→ STEP-6 (impl: component-b)
+                                        │
+                               STEP-7 (integration test)
+   ```
+4. Group tasks into phases:
+   - **Phase 1: Foundation** — types, interfaces, utilities
+   - **Phase 2: Core** — main components and their tests
+   - **Phase 3: Integration** — wiring components together, integration tests
+   - **Phase 4: Polish** — error handling, edge cases, documentation
+5. Update tracker: `stage: review`, log entry
+
+## STAGE 3: REVIEW
+
+> **Every design requirement must have a task. Every task must trace back to a design requirement.** If the mapping is not 1:1, the plan is incomplete or bloated.
+
+1. **Completeness check** — walk through the DESIGN entry section by section:
+   - Does every component have creation and test tasks?
+   - Does every interface have a definition task?
+   - Does the error handling strategy have corresponding tasks?
+   - Does every success criterion have at least one verification task?
+   - Are all files from the file structure plan accounted for?
+2. **Ordering check:**
+   - Can each task be executed with only its dependencies complete? (no implicit dependencies)
+   - Is TDD ordering maintained? (tests before implementations)
+   - Are foundation tasks (types, interfaces) before consumers?
+3. **Granularity check:**
+   - Is any task longer than 5 minutes of work? → split it
+   - Is any task trivial (< 1 minute)? → merge with an adjacent task
+   - Does any task require reading more than 3 files to understand? → add context or split
+4. **Render a Coverage Matrix** — ASCII table mapping design sections to tasks:
+   ```
+   ┌─────────────────────┬──────────────────────┐
+   │ Design Section       │ Tasks                │
+   ├─────────────────────┼──────────────────────┤
+   │ Component A          │ STEP-1, STEP-2       │
+   │ Component B          │ STEP-3, STEP-4       │
+   │ Data Flow            │ STEP-5               │
+   │ Error Handling       │ STEP-6               │
+   │ Integration          │ STEP-7               │
+   └─────────────────────┴──────────────────────┘
+   ```
+5. **Fix any gaps** found during review — add missing tasks, adjust ordering, split oversized tasks
+6. Write the final PLAN entry to `03-plan-loop/plans.md` using the format below
+7. Mark done in tracker: check off queue, completed mapping, `active_plan: none`, `stage: structure`, update Dependency Graph, log
+8. Exit: `kill -INT $PPID`
+
+**PLAN entry format:**
+```markdown
+## PLAN-{N}: {Title}
+
+**Source:** DESIGN-{N}
+**Depends on:** {PLAN-{M} or "None"}
+**Status:** complete
+**Total Steps:** {count}
+**Estimated Time:** {minutes} minutes
+
+### Phase 1: Foundation
+
+#### STEP-{N}.1: {Title}
+- **Files:** `{path/to/file}`
+- **Action:** {CREATE | MODIFY | DELETE}
+- **Do:** {Specific instructions — what to create/change, key signatures, behavior}
+- **Test:** `{exact test command}`
+- **Commit:** `{pre-written commit message}`
+- **Depends on:** {STEP-{N}.X or "None"}
+
+### Phase 2: Core
+
+#### STEP-{N}.2: {Title}
+...
+
+### Phase 3: Integration
+
+#### STEP-{N}.X: {Title}
+...
+
+### Phase 4: Polish
+
+#### STEP-{N}.X: {Title}
+...
+
+### Coverage Matrix
+| Design Section | Steps |
+|----------------|-------|
+| {Section} | STEP-{N}.X, STEP-{N}.Y |
+
+### Verification Checklist
+- [ ] All success criteria from IDEA have corresponding steps
+- [ ] TDD ordering maintained (tests before implementations)
+- [ ] No step exceeds 5 minutes of estimated work
+- [ ] All file paths from design's file structure plan are covered
+- [ ] Every step has a test command or verification method
+```
+
+---
+
+## Decision Reporting Protocol
+
+When you make a substantive decision a human reviewer would want to know about, report it to the dashboard:
+
+**When to report:**
+- Task decomposition choices (why you split work at certain boundaries)
+- Ordering decisions (why task A comes before task B when either order could work)
+- Granularity trade-offs (why a task was kept larger or split further than the 2-5 minute guideline)
+- Design interpretation (how you translated an ambiguous design section into concrete tasks)
+- Scope additions (tasks you added that are not explicitly in the design but are necessary)
+
+**How to report:**
+```bash
+curl -s --connect-timeout 2 --max-time 5 -X POST "http://127.0.0.1:4242/api/decision?app=$RALPHFLOW_APP&loop=$RALPHFLOW_LOOP" -H 'Content-Type: application/json' -d '{"item":"PLAN-{N}","agent":"plan-loop","decision":"{one-line summary}","reasoning":"{why this choice}"}'
+```
+
+**Do NOT report** routine operations: picking the next plan, updating tracker, stage transitions. Only report substantive choices that affect the implementation plan.
+
+**Best-effort only:** If the dashboard is unreachable (curl fails), continue working normally. Decision reporting must never block or delay your work.
+
+---
+
+## Rules
+
+- One plan at a time. All 3 stages run in one iteration, one `kill` at the end.
+- Read tracker first, update tracker last.
+- Append to `plans.md` — never overwrite. PLAN numbers match DESIGN numbers.
+- **Bite-sized tasks: 2-5 minutes each.** If it takes longer, split it.
+- **TDD ordering: test first, implement second, verify third.** Always.
+- Every design requirement must have a task. Every task must trace back to a design requirement.
+- Include exact file paths, code snippets, and test commands. No ambiguity.
+- Plans must be self-contained — an implementer should be able to execute the plan without reading the design.
+- Pre-write commit messages for each task. This forces clarity about what each task delivers.
+- Group tasks into phases (Foundation → Core → Integration → Polish) for natural ordering.
+
+---
+
+Read `.ralph-flow/{{APP_NAME}}/03-plan-loop/tracker.md` now and begin.

package/src/templates/design-review/loops/03-plan-loop/tracker.md

@@ -0,0 +1,16 @@
+# Plan Loop — Tracker
+
+- active_plan: none
+- stage: structure
+- completed_plans: []
+- pending_plans: []
+
+---
+
+## Plans Queue
+
+## Dependency Graph
+
+## Completed Mapping
+
+## Log

package/src/templates/design-review/ralphflow.yaml

@@ -0,0 +1,84 @@
+name: design-review
+description: "Explore → Design → Review → Plan pipeline for design-first development"
+version: 1
+dir: .ralph-flow
+
+entities:
+  IDEA:
+    prefix: IDEA
+    data_file: 00-explore-loop/ideas.md
+  DESIGN:
+    prefix: DESIGN
+    data_file: 01-design-loop/designs.md
+  PLAN:
+    prefix: PLAN
+    data_file: 03-plan-loop/plans.md
+
+loops:
+  explore-loop:
+    order: 0
+    name: "Explore Loop"
+    prompt: 00-explore-loop/prompt.md
+    tracker: 00-explore-loop/tracker.md
+    data_files:
+      - 00-explore-loop/ideas.md
+    entities: [IDEA]
+    stages: [context, clarify, scope]
+    completion: "ALL IDEAS SCOPED"
+    feeds: [design-loop]
+    multi_agent: false
+    model: claude-sonnet-4-6
+    cadence: 0
+
+  design-loop:
+    order: 1
+    name: "Design Loop"
+    prompt: 01-design-loop/prompt.md
+    tracker: 01-design-loop/tracker.md
+    data_files:
+      - 01-design-loop/designs.md
+    entities: [DESIGN, IDEA]
+    stages: [alternatives, design, document]
+    completion: "ALL DESIGNS WRITTEN"
+    fed_by: [explore-loop]
+    feeds: [review-loop]
+    multi_agent: false
+    model: claude-sonnet-4-6
+    cadence: 0
+
+  review-loop:
+    order: 2
+    name: "Review Loop"
+    prompt: 02-review-loop/prompt.md
+    tracker: 02-review-loop/tracker.md
+    entities: [DESIGN]
+    stages: [spec-review, user-review]
+    completion: "ALL DESIGNS REVIEWED"
+    fed_by: [design-loop]
+    feeds: [plan-loop]
+    model: claude-sonnet-4-6
+    multi_agent:
+      enabled: true
+      max_agents: 2
+      strategy: tracker-lock
+      agent_placeholder: "{{AGENT_NAME}}"
+    lock:
+      file: 02-review-loop/.tracker-lock
+      type: echo
+      stale_seconds: 60
+    cadence: 0
+
+  plan-loop:
+    order: 3
+    name: "Plan Loop"
+    prompt: 03-plan-loop/prompt.md
+    tracker: 03-plan-loop/tracker.md
+    data_files:
+      - 03-plan-loop/plans.md
+    entities: [PLAN, DESIGN]
+    stages: [structure, plan, review]
+    completion: "ALL PLANS WRITTEN"
+    fed_by: [review-loop]
+    multi_agent: false
+    model: claude-sonnet-4-6
+    cadence: 0

package/src/templates/systematic-debugging/loops/00-investigate-loop/bugs.md

@@ -0,0 +1,3 @@
+# Bugs
+
+<!-- Populated by the investigate loop -->