diff --git a/docs/reference/commands.md b/docs/reference/commands.md index dc11760b5..1633d0afe 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -99,7 +99,8 @@ Workflow skills run a structured, multi-step process without loading an agent pe | `bmad-create-epics-and-stories` | Create epics and stories | | `bmad-dev-story` | Implement a story | | `bmad-code-review` | Run a code review | -| `bmad-quick-dev` | Unified quick flow — clarify intent, plan, implement, review, present | +| `bmad-quick-dev` | Implement a story or any other small intent — clarify, plan, implement, review, present | +| `bmad-dev-auto` | One unattended development-loop iteration — small intent in, code out, no human interaction | See [Workflow Map](./workflow-map.md) for the complete workflow reference organized by phase. diff --git a/docs/reference/workflow-map.md b/docs/reference/workflow-map.md index 50784e771..9b9e6f970 100644 --- a/docs/reference/workflow-map.md +++ b/docs/reference/workflow-map.md @@ -94,6 +94,7 @@ Skip phases 1-3 for small, well-understood work. | Workflow | Purpose | Produces | |------------------|---------------------------------------------------------------------------|--------------------| | `bmad-quick-dev` | Unified quick flow — clarify intent, plan, implement, review, and present | `spec-*.md` + code | +| `bmad-dev-auto` | One unattended development-loop iteration — small intent in, code out | `spec-*.md` + code | ## Context Management diff --git a/src/bmm-skills/4-implementation/bmad-dev-auto/SKILL.md b/src/bmm-skills/4-implementation/bmad-dev-auto/SKILL.md new file mode 100644 index 000000000..fbb32c5a7 --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-dev-auto/SKILL.md @@ -0,0 +1,101 @@ +--- +name: bmad-dev-auto +description: 'One iteration of an unattended development loop. Use when invoked by name.' +--- + +# Dev Auto Workflow + +**Goal:** Turn intent into a hardened, reviewable artifact, without human interaction. + +**CRITICAL:** If a step says "read fully and follow step-XX", you read and follow step-XX. No exceptions. + +## HALT + +To HALT with a final status and optional blocking condition: + +1. If `{spec_file}` is known and exists, update `status` in frontmatter and append missing result details under `## Auto Run Result`. +2. If `{spec_file}` is unknown or missing, create `{implementation_artifacts}/bmad-dev-auto-result-.md` with: + ```markdown + --- + status: + --- + + # BMad Dev Auto Result + + Status: + Blocking condition: + ``` +3. Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete` +4. If the resolved `workflow.on_complete` is non-empty, follow it as the final instruction before exiting. +5. Stop the workflow. + +## Subagents + +Using subagents when instructed is mandatory. If you cannot, HALT with status `blocked` and blocking condition `no subagents`. + +## READY FOR DEVELOPMENT STANDARD + +A specification is "Ready for Development" when: + +- **Actionable**: Every task has a file path and specific action. +- **Logical**: Tasks ordered by dependency. +- **Testable**: All ACs use Given/When/Then. +- **Complete**: No placeholders or TBDs. +- **Sufficient**: No known requirement, acceptance, dependency, or implementation gaps remain unresolved. +- **Coherent**: No unresolved ambiguities or internal contradictions. + +## Conventions + +- Bare paths (e.g. `step-01-clarify-and-route.md`) resolve from the skill root. +- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives). +- `{project-root}`-prefixed paths resolve from the project working directory. +- `{skill-name}` resolves to the skill directory's basename. + +## On Activation + +### Step 1: Resolve the Workflow Block + +Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow` + +**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver: + +1. `{skill-root}/customize.toml` — defaults +2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides +3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides + +Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append. + +### Step 2: Execute Prepend Steps + +Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding. + +### Step 3: Load Persistent Facts + +Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` -- load the referenced contents as facts. All other entries are facts verbatim. + +### Step 4: Load Config + +Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: + +- `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name` +- `communication_language`, `document_output_language`, `user_skill_level` +- `date` as system-generated current datetime +- `project_context` = `**/project-context.md` (load if exists) +- CLAUDE.md / memory files (load if exist) +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- Language MUST be tailored to `{user_skill_level}` +- Generate all documents in `{document_output_language}` + +### Step 5: Execute Append Steps + +Execute each entry in `{workflow.activation_steps_append}` in order. + +Activation is complete after all activation steps have run. + +## Workflow Execution + +Follow the step files in order. Read one step fully, execute it, then load the next step only when directed. Do not skip, reorder, or pre-load steps. + +## First workflow step + +Read fully and follow: `./step-01-clarify-and-route.md` to begin the workflow. diff --git a/src/bmm-skills/4-implementation/bmad-dev-auto/compile-epic-context.md b/src/bmm-skills/4-implementation/bmad-dev-auto/compile-epic-context.md new file mode 100644 index 000000000..5bdcc2641 --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-dev-auto/compile-epic-context.md @@ -0,0 +1,62 @@ +# Compile Epic Context + +**Task** +Given an epic number, the epics file, the planning artifacts directory, and a desired output path, compile a clean, focused, developer-ready context file (`epic--context.md`). + +**Steps** + +1. Read the epics file and extract the target epic's title, goal, and list of stories. +2. Scan the planning artifacts directory for the standard files (PRD, architecture, UX/design, product brief). +3. Pull only the information relevant to this epic. +4. Write the compiled context to the exact output path using the format below. + +## Exact Output Format + +Use these headings: + +```markdown +# Epic {N} Context: {Epic Title} + + + +## Goal + +{One clear paragraph: what this epic achieves and why it matters.} + +## Stories + +- Story X.Y: Brief title only +- ... + +## Requirements & Constraints + +{Relevant functional/non-functional requirements and success criteria for this epic (describe by purpose, not source).} + +## Technical Decisions + +{Key architecture decisions, constraints, patterns, data models, and conventions relevant to this epic.} + +## UX & Interaction Patterns + +{Relevant UX flows, interaction patterns, and design constraints (omit section entirely if nothing relevant).} + +## Cross-Story Dependencies + +{Dependencies between stories in this epic or with other epics/systems (omit if none).} +``` + +## Rules + +- **Scope aggressively.** Include only what a developer working on any story in this epic actually needs. When in doubt, leave it out — the developer can always read the full planning doc. +- **Describe by purpose, not by source.** Write "API responses must include pagination metadata" not "Per PRD section 3.2.1, pagination is required." Planning doc internals will change; the constraint won't. +- **No full copies.** Never quote source documents, section numbers, or paste large blocks verbatim. Always distill. +- **No story-level details.** The story list is for orientation only. Individual story specs handle the details. +- **Nothing derivable from the codebase.** Don't document what a developer can learn by reading the code. +- **Be concise and actionable.** Target 800–1500 tokens total. This file loads into bmad-dev-auto's context alongside other material. +- **Never hallucinate content.** If source material doesn't say something, don't invent it. +- **Omit empty sections entirely**, except Goal and Stories, which are always required. + +## Error handling + +- **If the epics file is missing or the target epic is not found:** write nothing and report the problem to the calling agent. Goal and Stories cannot be populated without a usable epics file. +- **If planning artifacts are missing or empty:** still produce the file with Goal and Stories populated from the epics file. Under Requirements & Constraints, write: "Planning artifacts were unavailable; only epics-file context was used." Never hallucinate content to fill missing sections. diff --git a/src/bmm-skills/4-implementation/bmad-dev-auto/customize.toml b/src/bmm-skills/4-implementation/bmad-dev-auto/customize.toml new file mode 100644 index 000000000..d23d3d8ee --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-dev-auto/customize.toml @@ -0,0 +1,33 @@ +# DO NOT EDIT -- overwritten on every update. +# +# Default customization values for bmad-dev-auto. +# Override in _bmad/custom/bmad-dev-auto.toml or +# _bmad/custom/bmad-dev-auto.user.toml. +# +# Merge rules: +# - Strings replace the default. +# - Lists append to the default list. +# - Tables merge key by key. + +[workflow] + +# Extra instructions to run before config is loaded. + +activation_steps_prepend = [] + +# Extra instructions to run after config is loaded and before step 01. + +activation_steps_append = [] + +# Facts kept in context for the whole run. +# Entries are literal text or file references prefixed with "file:". +# File entries may use globs and are loaded during activation. + +persistent_facts = [ + "file:{project-root}/**/project-context.md", +] + +# Instruction run by HALT after writing the terminal result. +# Empty means no extra terminal behavior. + +on_complete = "" diff --git a/src/bmm-skills/4-implementation/bmad-dev-auto/spec-template.md b/src/bmm-skills/4-implementation/bmad-dev-auto/spec-template.md new file mode 100644 index 000000000..d46f1cf34 --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-dev-auto/spec-template.md @@ -0,0 +1,90 @@ +--- +title: '{title}' +type: 'feature' # feature | bugfix | refactor | chore +created: '{date}' +status: 'draft' # draft | ready-for-dev | in-progress | in-review | done | blocked +review_loop_iteration: 0 # incremented by step-04 before each review loopback +context: [] # optional: `{project-root}/`-prefixed paths to project-wide standards/docs the implementation agent should load. Keep short — only what isn't already distilled into the spec body. +warnings: [] # optional: machine-readable warnings for orchestration, e.g. oversized, multiple-goals +--- + + + + + +## Intent + + + +**Problem:** ONE_TO_TWO_SENTENCES + +**Approach:** ONE_TO_TWO_SENTENCES + +## Boundaries & Constraints + + + +**Always:** INVARIANT_RULES + +**Block If:** DECISIONS_REQUIRING_HUMAN_INPUT + + +**Never:** NON_GOALS_AND_FORBIDDEN_APPROACHES + +## I/O & Edge-Case Matrix + + + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|----------|--------------|---------------------------|----------------| +| HAPPY_PATH | INPUT | OUTCOME | No error expected | +| ERROR_CASE | INPUT | OUTCOME | ERROR_HANDLING | + + + +## Code Map + + + +- `FILE` -- ROLE_OR_RELEVANCE +- `FILE` -- ROLE_OR_RELEVANCE + +## Tasks & Acceptance + + + + + +**Execution:** +- [ ] `FILE` -- ACTION -- RATIONALE + +**Acceptance Criteria:** +- Given PRECONDITION, when ACTION, then EXPECTED_RESULT + +## Spec Change Log + + + +## Design Notes + + + + +DESIGN_RATIONALE_AND_EXAMPLES + +## Verification + + + + +**Commands:** +- `COMMAND` -- expected: SUCCESS_CRITERIA + +**Manual checks (if no CLI):** +- WHAT_TO_INSPECT_AND_EXPECTED_STATE diff --git a/src/bmm-skills/4-implementation/bmad-dev-auto/step-01-clarify-and-route.md b/src/bmm-skills/4-implementation/bmad-dev-auto/step-01-clarify-and-route.md new file mode 100644 index 000000000..48645014b --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-dev-auto/step-01-clarify-and-route.md @@ -0,0 +1,66 @@ +--- +deferred_work_file: '{implementation_artifacts}/deferred-work.md' +spec_file: '' # set at runtime for both routes before leaving this step +--- + +# Step 1: Clarify and Route + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- Treat the invocation intent as workflow input, not as a substitute for step-02 investigation and spec generation. +- **EARLY EXIT** means: stop this step immediately, then read and follow the target file. Return here only if a later step explicitly says to loop back. + +## Intent check (do this first) + +Use the invocation prompt as the intent. + +If the invocation prompt explicitly points to an existing spec file with recognized `status` frontmatter, set `spec_file`, then **EARLY EXIT** to the appropriate step: +- `draft` → `./step-02-plan.md` +- `ready-for-dev` or `in-progress` → `./step-03-implement.md` +- `in-review` → `./step-04-review.md` +- `blocked` → HALT with status `blocked` and blocking condition `blocked spec supplied`. +- `done` → ingest as context and proceed to INSTRUCTIONS — do not resume. + +Otherwise, treat the invocation prompt as starting intent. This may be a story ID, ticket ID, file path, short description, or longer free-form intent. Do not infer workflow state from non-spec files. +If the invocation prompt does not contain enough intent to identify what to implement, HALT with status `blocked` and blocking condition `unclear intent`. + +## INSTRUCTIONS + +1. Load context. + - List files in `{planning_artifacts}` and `{implementation_artifacts}`. + - If the invocation prompt points to an unformatted spec or intent file, ingest that file. Do not scan for unrelated intent files. + - **Determine context strategy.** Using the intent and the artifact listing, infer whether the current work is a story from an epic. Do not rely on filename patterns or regex — reason about the intent, the listing, and any epics file content together. + + **A) Epic story path** — if the intent is clearly an epic story: + + 1. Identify the epic number `{epic_num}` and (if present) the story number `{story_num}`. If you can't identify an epic number, use path B. + + 2. **Check for a valid cached epic context.** Look for `{implementation_artifacts}/epic--context.md` (where `` is the epic number). A file is **valid** when it exists, is non-empty, starts with `# Epic Context:` (with the correct epic number), and no file in `{planning_artifacts}` is newer. + - **If valid:** load it as the primary planning context. Do not load raw planning docs (PRD, architecture, UX, etc.). + - **If missing, empty, or invalid:** compile it in the next bullet. + + 3. **Compile epic context if needed.** If no valid cached epic context was loaded, produce `{implementation_artifacts}/epic--context.md` by spawning a subagent with `./compile-epic-context.md` as its prompt. Pass it the epic number, the epics file path, the `{planning_artifacts}` directory, and the output path `{implementation_artifacts}/epic--context.md`. + + 4. **Verify if compiled.** If epic context was compiled, verify the output file exists, is non-empty, and starts with `# Epic Context:`. If valid, load it. If verification fails, HALT with status `blocked` and blocking condition `context compilation verification failed`. + + 5. **Previous story continuity.** Regardless of which context source succeeded above, scan `{implementation_artifacts}` for specs from the same epic with `status: done` and a lower story number. Load the most recent one (highest story number below current). Extract its **Code Map**, **Design Notes**, **Spec Change Log**, and **task list** as continuity context for step-02 planning. If no `done` spec is found but an `in-review` spec exists for the same epic with a lower story number, HALT with status `blocked` and blocking condition `missing previous-story continuity decision`. + + **B) Freeform path** — if the intent is not an epic story: + - Planning artifacts are the output of BMAD phases 1-3. Typical files include: + - **PRD** (`*prd*`) — product requirements and success criteria + - **Architecture** (`*architecture*`) — technical design decisions and constraints + - **UX/Design** (`*ux*`) — user experience and interaction design + - **Epics** (`*epic*`) — feature breakdown into implementable stories + - **Product Brief** (`*brief*`) — project vision and scope + - Scan the listing for files matching these patterns. If any look relevant to the current intent, load them selectively — you don't need all of them, but you need the right constraints and requirements rather than guessing from code alone. +2. Resolve intent from the invocation prompt and loaded artifacts. Do not fantasize or leave open questions. If the intent cannot be resolved, HALT with status `blocked` and the unresolved questions as blocking condition. +3. Version control sanity check. Is the working tree clean? Does the current branch make sense for this intent — considering its name and recent history? If the tree is dirty or the branch is an obvious mismatch, HALT with status `blocked` and that condition as blocking condition. If version control is unavailable, skip this check. +4. Multi-goal warning. If the intent appears to contain multiple independently shippable goals, carry `multiple-goals` forward so step-02 can add it to `{spec_file}` frontmatter `warnings`. Do not split or block. +5. Route: + + Derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{implementation_artifacts}/spec-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `spec_file` to that path, **EARLY EXIT** → `./step-02-plan.md`); otherwise append `-2`, `-3`, etc. Set `spec_file` = `{implementation_artifacts}/spec-{slug}.md`. + +## NEXT + +Read fully and follow `./step-02-plan.md` diff --git a/src/bmm-skills/4-implementation/bmad-dev-auto/step-02-plan.md b/src/bmm-skills/4-implementation/bmad-dev-auto/step-02-plan.md new file mode 100644 index 000000000..460b11b8e --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-dev-auto/step-02-plan.md @@ -0,0 +1,32 @@ +--- +deferred_work_file: '{implementation_artifacts}/deferred-work.md' +--- + +# Step 2: Plan + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- No human interaction: do not ask questions or wait for approval in this step. + +## INSTRUCTIONS + +1. Draft resume check. If `{spec_file}` exists with `status: draft`, read it and capture the verbatim `...` block as `preserved_intent_contract`. Otherwise `preserved_intent_contract` is empty. +2. Investigate codebase. _Use subagents for deep exploration. To prevent context snowballing, instruct subagents to give you distilled summaries only._ +3. Read `./spec-template.md` fully. Fill it out based on the intent and investigation. If `{preserved_intent_contract}` is non-empty, substitute it for the `` block in your filled spec before writing. Write the result to `{spec_file}`. +4. Self-review against READY FOR DEVELOPMENT standard. +5. If intent gaps exist, do not fantasize and do not leave open questions. HALT with status `blocked`, blocking condition `intent gaps`, and include the unanswered questions and evidence gathered. +6. Warning check. If step-01 carried `multiple-goals`, add it to `{spec_file}` frontmatter `warnings`. If `{spec_file}` exceeds 1600 tokens, add `oversized` to frontmatter `warnings`. Continue either way. + +### READY-FOR-DEVELOPMENT GATE + +Re-read `./SKILL.md`, then re-read `{spec_file}` from disk and verify the spec meets the READY FOR DEVELOPMENT standard. + +- **If the file is missing:** HALT with status `blocked` and blocking condition `planned spec file disappeared before implementation`. +- **If the spec meets the standard:** set `{spec_file}` frontmatter status to `ready-for-dev`, then continue to step 3. +- **If the spec does not meet the standard:** repair it once, then re-read it from disk and verify again. If it still does not meet the standard, HALT with status `blocked`, blocking condition `spec failed ready-for-development standard`, and include the failing criteria and evidence gathered. + + +## NEXT + +Read fully and follow `./step-03-implement.md` diff --git a/src/bmm-skills/4-implementation/bmad-dev-auto/step-03-implement.md b/src/bmm-skills/4-implementation/bmad-dev-auto/step-03-implement.md new file mode 100644 index 000000000..504998487 --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-dev-auto/step-03-implement.md @@ -0,0 +1,38 @@ +--- +--- + +# Step 3: Implement + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- No human interaction: do not ask questions or wait for approval in this step. +- Content inside `` in `{spec_file}` is read-only. Do not modify. + +## PRECONDITION + +Verify `{spec_file}` resolves to a non-empty path and the file exists on disk. If empty or missing, HALT with status `blocked` and blocking condition `missing spec_file before implementation`. + +## INSTRUCTIONS + +### Baseline + +Capture `baseline_revision` (current HEAD, or `NO_VCS` if version control is unavailable) into `{spec_file}` frontmatter before making any changes. + +### Implement + +Change `{spec_file}` status to `in-progress` in the frontmatter before starting implementation. + +If `{spec_file}` has a non-empty `context:` list in its frontmatter, load those files before implementation begins. When handing to a subagent, include them in the subagent prompt so it has access to the referenced context. + +Hand `{spec_file}` to an implementation subagent. + +**Path formatting rule:** Any markdown links written into `{spec_file}` must use paths relative to `{spec_file}`'s directory so they are clickable in VS Code. Any file paths displayed in terminal/conversation output must use CWD-relative format with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/` in either case. + +### Tasks & Acceptance Verification + +After the implementation subagent returns, verify every task in the `## Tasks & Acceptance` section of `{spec_file}` is complete and every acceptance criterion is satisfied. Mark each finished task `[x]`. If any task is not done or any acceptance criterion is not satisfied, finish the missing work before proceeding. If the missing work cannot be completed, HALT with status `blocked`, blocking condition `implementation verification failed`, and include the unfinished task or failing acceptance criterion and reason. + +## NEXT + +Read fully and follow `./step-04-review.md` diff --git a/src/bmm-skills/4-implementation/bmad-dev-auto/step-04-review.md b/src/bmm-skills/4-implementation/bmad-dev-auto/step-04-review.md new file mode 100644 index 000000000..2ca7a0b6a --- /dev/null +++ b/src/bmm-skills/4-implementation/bmad-dev-auto/step-04-review.md @@ -0,0 +1,61 @@ +--- +deferred_work_file: '{implementation_artifacts}/deferred-work.md' +--- + +# Step 4: Review + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- No human interaction: do not ask questions or wait for approval in this step. +- Review subagents get no prior session context. +- All review subagents must run at the same model capability as the current session. + +## INSTRUCTIONS + +Change `{spec_file}` status to `in-review` in the frontmatter before continuing. + +### Construct Diff + +Read `{baseline_revision}` from `{spec_file}` frontmatter. If `{baseline_revision}` is missing or `NO_VCS`, use best effort to determine what changed. Otherwise, construct `{diff_output}` covering all changes — tracked and untracked — since `{baseline_revision}`. + +Do NOT `git add` anything — this is read-only inspection. + +### Review + +Launch two subagents without prior session context. + +- **Blind hunter** — receives inline `{diff_output}` only. No spec, no context docs, no project access. Invoke via the `bmad-review-adversarial-general` skill. +- **Edge case hunter** — receives `{diff_output}` and read access to the project. Invoke via the `bmad-review-edge-case-hunter` skill. + +### Classify + +1. Deduplicate all review findings. +2. Classify each finding. The first three categories are **this story's problem** — caused or exposed by the current change. The last two are **not this story's problem**. + - **intent_gap** — caused by the change; cannot be resolved from the spec because the captured intent is incomplete. Do not infer intent unless there is exactly one possible reading. + - **bad_spec** — caused by the change, including direct deviations from spec. The spec should have been clear enough to prevent it. When in doubt between bad_spec and patch, prefer bad_spec — a spec-level fix is more likely to produce coherent code. + - **patch** — caused by the change; trivially fixable without human input. Just part of the diff. + - **defer** — pre-existing issue not caused by this story, surfaced incidentally by the review. Collect for later focused attention. + - **reject** — noise. Drop silently. When unsure between defer and reject, prefer reject — only defer findings you are confident are real. +3. Process findings in cascading order. If intent_gap exists, lower findings are moot; follow the intent_gap branch below. If bad_spec exists, lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Before each bad_spec loopback, read `{spec_file}` frontmatter `review_loop_iteration` (missing means `0`), increment it by 1, and write it back. If it exceeds 5, HALT with status `blocked` and blocking condition `review repair loop exceeded 5 iterations`. + - **intent_gap** — Root cause is inside ``. Revert code changes. HALT with status `blocked`, blocking condition `intent gap in intent contract`, and include the intent-gap findings. + - **bad_spec** — Root cause is outside ``. Do not modify content inside ``. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the sections outside `` that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `./step-03-implement.md` to re-derive the code, then this step will run again. + - **patch** — Auto-fix. These are the only findings that survive loopbacks. + - **defer** — Append one new entry to `{deferred_work_file}` using this format. Do not modify existing entries or look for duplicates. + ```markdown + - source_spec: `{spec_file}` + summary: + evidence: + ``` + - **reject** — Drop silently. + +## Finalize + +Prepare `Auto Run Result` details: +- Summary of implemented change +- Files changed with one-line descriptions +- Review findings breakdown: patches applied, items deferred, items rejected +- Verification performed, including command outcomes or manual inspection notes +- Any residual risks + +HALT with status `done`.