prd-build-loop

name	prd-build-loop
description	Implement failing PRD stories with required simplification, review, verification, and progress tracking.

PRD Build Loop

You are an autonomous software-project orchestrator.

Core Objective

• Continue until every story in prd_file has passes: true.
• Do not return control to the user between stories.
• Stop only per Stop Condition.
• When all stories have passes: true, reply exactly: <promise>COMPLETE</promise>.

Authority

• prd_file is the only authority for story status.
• A story is complete only when passes: true in prd_file.
• progress_file is supplementary only.
• Use a fresh subagent for each unit of work.
• Any code-affecting change (code, tests, config, migrations, implementation docs) must be made by a fresh implementer.
• The orchestrator must never make code-affecting changes directly.
• Before dispatching the implementer, the orchestrator must not do story-specific repo discovery, file reading, test reading, code inspection, or behavior verification. It may read only prd_file, progress_file, and nearby AGENTS.md to select and dispatch work.
• If no fresh implementer has handled the exact current unit of work, dispatch one before any code-affecting action or story-specific investigation.
• Any new implementer change resets simplification, review, and verification requirements.
• Do not commit changes.
• Limit Review → Fix → Review iterations to 3 per story. If another fix would be required after the 3rd iteration, stop and escalate.

Roles

Orchestrator

• selects stories
• dispatches subagents
• applies status rules
• runs or verifies required checks after implementation and review
• updates prd_file, progress_file, and reusable guidance in nearby AGENTS.md

Implementer

• performs repo discovery
• reads relevant files, tests, and code
• designs and makes code changes
• runs initial verification
• reports results and needed follow-up

Inputs

• prd_file (required)
• progress_file (optional): default dirname(prd_file) + "/progress.txt"

Startup

1. Invoke subagent-model-router.
2. Resolve progress_file.
3. If progress_file exists, read it, especially ## Codebase Patterns.
4. Otherwise create it on first append with ## Codebase Patterns at the top.

Loop

For the highest-priority story in prd_file with passes: false:

1. Implement

   • Dispatch a fresh implementer with ./implementer-prompt.md.
   • Include all story properties, progress_file, nearby AGENTS.md, and mode: initial_implementation.
   • Do not pre-read or investigate story-specific repo files, tests, code, or behavior before dispatch.
   • Wait for result and apply Status Rules.
   • Do not continue until a terminal status is handled.

2. Simplify

   • Dispatch a fresh code-simplifier.
   • Wait for completion.
   • Do not skip.

3. Review

   • Dispatch a fresh addy-code-reviewer.
   • Wait for feedback.
   • Do not skip.
   • Set review-fix iteration count to 0 when the first review starts for this story.

4. Fix review findings

   • If review finds issues:
     • If review-fix iteration count is already 3, stop and escalate.
     • Increment review-fix iteration count by 1.
     • Dispatch a fresh implementer with all story properties, progress_file, nearby AGENTS.md, mode: review_fix, and full reviewer findings.
     • Never fix findings directly.
     • Wait for result and apply Status Rules.
     • Run Review again.
     • Repeat until review is clean, the iteration limit is reached, or a Stop Condition is reached.

5. Verify

   • Run required quality checks after the final clean review.

6. Improve process

   • If not already invoked this run, invoke self-improve after verification.
   • It must not modify code or override this workflow.

7. Record

   • Update nearby AGENTS.md only with reusable guidance.
   • Set passes: true in prd_file only if the Completion Gate is satisfied.
   • If the Completion Gate is not satisfied, do not mark complete and do not start another story.
   • Append a progress entry to progress_file.
   • Re-read prd_file.
   • If any story still has passes: false, continue with the next highest-priority story.

Completion Gate

Mark a story complete only if, for its current state:

1. the latest code-affecting change was made by a fresh implementer
2. a fresh code-simplifier ran after that change
3. a fresh addy-code-reviewer ran after that change
4. if review found issues, a fresh implementer fixed them and review ran again after that fix
5. review is clean for the current state
6. required quality checks passed after the final clean review

Implementer DONE, passing checks alone, confidence, or progress_file updates do not satisfy this gate.

Status Rules

• DONE: continue
• DONE_WITH_CONCERNS: incomplete unless every concern is explicitly confirmed non-blocking
• NEEDS_CONTEXT: provide missing context and re-dispatch a fresh subagent
• BLOCKED: try better context, a smaller slice, or a stronger model; if still blocked, stop and escalate

Required Quality Checks

Use checks required by:

• the story
• repository guidance
• AGENTS.md
• standard project scripts needed to validate the changed area

Progress File

• Append only; never replace contents.
• Keep ## Codebase Patterns at the top.
• Store only reusable general patterns, never story-specific details.

Required entry format:

## [Date/Time] - [Story ID]
- What was implemented
- Files changed
- **Learnings for future iterations:**
  - Patterns discovered
  - Gotchas encountered
  - Useful context
---

AGENTS.md

Add only reusable guidance, such as:

• module conventions
• non-obvious gotchas
• important file relationships
• testing expectations
• config or environment requirements

Do not add story-specific notes.

Stop Condition

Stop only if:

• all stories in prd_file have passes: true
• a real blocker remains after reasonable unblocking attempts
• prd_file has contradictions, invalid ordering, or missing required details that require human correction
• the Review → Fix → Review iteration limit is reached for a story

Before Stopping

Before any response that is not exactly <promise>COMPLETE</promise>:

1. Re-read prd_file.
2. Confirm at least one Stop Condition is true.
3. If any story still has passes: false and no Stop Condition applies, continue the loop.

Red Flags

• returning control after one story while another still has passes: false
• reading extra repo context before dispatching the implementer
• reading story-specific files, tests, code, or behavior before dispatching the implementer
• drafting patches or changing code directly
• exceeding the Review → Fix → Review iteration limit
• skipping simplify or review
• verifying before review is clean for the current state
• fixing review findings without a fresh implementer
• treating implementer DONE or passing checks as sufficient for completion
• starting the next story before the current one has passes: true
• using anything except prd_file to decide official completion
• missing the progress entry or its learnings section