docs: clarify dev auto customization comments

Replace internal merge jargon and stale workflow comments with plain descriptions of the customization file behavior.

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.
 

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
 

src/bmm-skills/4-implementation/bmad-dev-auto/SKILL.md

@@ -9,11 +9,29 @@ description: 'One iteration of an unattended development loop. Use when invoked
 
 **CRITICAL:** If a step says "read fully and follow step-XX", you read and follow step-XX. No exceptions.
 
-Using subagents when instructed is mandatory. If you cannot, record `no subagents` in the result artifact and end the run.
+## HALT
 
-## Result Artifact
+To HALT with a final status and optional blocking condition:
 
-The result artifact is `{spec_file}` once it is known. If `{spec_file}` is unknown, create `{implementation_artifacts}/bmad-dev-auto-result-{slug-or-timestamp}.md`.
+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-<slug-or-timestamp>.md` with:
+   ```markdown
+   ---
+   status: <final status>
+   ---
+
+   # BMad Dev Auto Result
+
+   Status: <final status>
+   Blocking condition: <blocking condition, if any>
+   ```
+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
 
@@ -74,10 +92,10 @@ Execute each entry in `{workflow.activation_steps_append}` in order.
 
 Activation is complete after all activation steps have run.
 
-## WORKFLOW EXECUTION
+## 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
+## First workflow step
 
 Read fully and follow: `./step-01-clarify-and-route.md` to begin the workflow.

src/bmm-skills/4-implementation/bmad-dev-auto/customize.toml

@@ -1,41 +1,33 @@
 # DO NOT EDIT -- overwritten on every update.
 #
-# Workflow customization surface for bmad-dev-auto. Mirrors the
-# agent customization shape under the [workflow] namespace.
+# 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]
 
-# --- Configurable below. Overrides merge per BMad structural rules: ---
-#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
-#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
-
-# Steps to run before the standard activation (config load).
-# Overrides append. Use for pre-flight loads, compliance checks, etc.
+# Extra instructions to run before config is loaded.
 
 activation_steps_prepend = []
 
-# Steps to run after activation but before the workflow begins.
-# Overrides append. Use for context-heavy setup that should happen
-# once the user has been acknowledged.
+# Extra instructions to run after config is loaded and before step 01.
 
 activation_steps_append = []
 
-# Persistent facts the workflow keeps in mind for the whole run
-# (standards, compliance constraints, stylistic guardrails).
-# Distinct from the runtime memory sidecar — these are static context
-# loaded on activation. Overrides append.
-#
-# Each entry is either:
-#   - a literal sentence, e.g. "All stories must include testable acceptance criteria."
-#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
-#     (glob patterns are supported; the file's contents are loaded and treated as facts).
+# 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",
 ]
 
-# Scalar: executed when the workflow reaches its final step,
-# after implementation is complete and explanations are provided. Override wins.
-# Leave empty for no custom post-completion behavior.
+# Instruction run by HALT after writing the terminal result.
+# Empty means no extra terminal behavior.
 
 on_complete = ""

src/bmm-skills/4-implementation/bmad-dev-auto/spec-template.md

@@ -3,6 +3,7 @@ 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
 ---
@@ -12,7 +13,7 @@ warnings: [] # optional: machine-readable warnings for orchestration, e.g. overs
      Cohesive cross-layer stories (DB+BE+UI) stay in ONE file.
      IMPORTANT: Remove all HTML comments when filling this template. -->
 
-<frozen-after-approval reason="invocation-owned intent — do not modify unless a later invocation replaces it">
+<intent-contract>
 
 ## Intent
 
@@ -29,7 +30,7 @@ warnings: [] # optional: machine-readable warnings for orchestration, e.g. overs
 **Always:** INVARIANT_RULES
 
 **Block If:** DECISIONS_REQUIRING_HUMAN_INPUT
-<!-- Agent: if any of these trigger during execution, write the blocked condition to the result artifact and terminate cleanly. -->
+<!-- Agent: if any of these trigger during execution, HALT with status blocked and the blocking condition. -->
 
 **Never:** NON_GOALS_AND_FORBIDDEN_APPROACHES
 
@@ -39,10 +40,10 @@ warnings: [] # optional: machine-readable warnings for orchestration, e.g. overs
 
 | Scenario | Input / State | Expected Output / Behavior | Error Handling |
 |----------|--------------|---------------------------|----------------|
-| HAPPY_PATH | INPUT | OUTCOME | N/A |
+| HAPPY_PATH | INPUT | OUTCOME | No error expected |
 | ERROR_CASE | INPUT | OUTCOME | ERROR_HANDLING |
 
-</frozen-after-approval>
+</intent-contract>
 
 ## Code Map
 

src/bmm-skills/4-implementation/bmad-dev-auto/step-01-clarify-and-route.md

@@ -10,7 +10,6 @@ spec_file: '' # set at runtime for both routes before leaving this step
 - 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.
-- **BLOCKED EXIT** means: write the blocked reason to the result artifact and end the run.
 
 ## Intent check (do this first)
 
@@ -20,10 +19,11 @@ If the invocation prompt explicitly points to an existing spec file with recogni
 - `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, write `unclear intent` to the result artifact and **BLOCKED EXIT**.
+If the invocation prompt does not contain enough intent to identify what to implement, HALT with status `blocked` and blocking condition `unclear intent`.
 
 ## INSTRUCTIONS
 
@@ -40,11 +40,11 @@ If the invocation prompt does not contain enough intent to identify what to impl
         - **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-<N>-context.md` by spawning a sub-agent 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-<N>-context.md`. If sub-agents are unavailable, write `no subagents` to the result artifact and **BLOCKED EXIT**.
+     3. **Compile epic context if needed.** If no valid cached epic context was loaded, produce `{implementation_artifacts}/epic-<N>-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-<N>-context.md`.
 
-     4. **Verify if compiled.** If epic context was compiled, verify the output file exists, is non-empty, and starts with `# Epic <N> Context:`. If valid, load it. If verification fails, write the failed context-compilation condition to the result artifact and **BLOCKED EXIT**.
+     4. **Verify if compiled.** If epic context was compiled, verify the output file exists, is non-empty, and starts with `# Epic <N> 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, write the missing continuity decision to the result artifact and **BLOCKED EXIT**.
+     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:
@@ -54,8 +54,8 @@ If the invocation prompt does not contain enough intent to identify what to impl
        - **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. Clarify intent. Do not fantasize, do not leave open questions. If you must ask questions, write them as a blocked condition in the result artifact and **BLOCKED EXIT**.
-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, write the condition to the result artifact and **BLOCKED EXIT**. If version control is unavailable, skip this check.
+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:
 

src/bmm-skills/4-implementation/bmad-dev-auto/step-02-plan.md

@@ -11,20 +11,20 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 
 ## INSTRUCTIONS
 
-1. Draft resume check. If `{spec_file}` exists with `status: draft`, read it and capture the verbatim `<frozen-after-approval>...</frozen-after-approval>` block as `preserved_intent`. Otherwise `preserved_intent` is empty.
-2. Investigate codebase. _Isolate deep exploration in sub-agents/tasks where available. 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}` is non-empty, substitute it for the `<frozen-after-approval>` block in your filled spec before writing. Write the result to `{spec_file}`.
+1. Draft resume check. If `{spec_file}` exists with `status: draft`, read it and capture the verbatim `<intent-contract>...</intent-contract>` 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 `<intent-contract>` 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. Set `{spec_file}` frontmatter status to `blocked`, append `## Auto Run Result` with `Status: blocked`, the unanswered questions, and evidence gathered, then terminate cleanly.
+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 `{spec_file}` from disk and verify it meets the READY FOR DEVELOPMENT standard in `./SKILL.md`.
+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:** write a best-effort result artifact in `{implementation_artifacts}` with `Status: blocked`, `Blocking condition: planned spec file disappeared before implementation`, and terminate cleanly.
+- **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, set `{spec_file}` frontmatter status to `blocked`, append `## Auto Run Result` with `Status: blocked`, the failing criteria, and evidence gathered, then terminate cleanly.
+- **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

src/bmm-skills/4-implementation/bmad-dev-auto/step-03-implement.md

@@ -7,11 +7,11 @@
 
 - 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 `<frozen-after-approval>` in `{spec_file}` is read-only. Do not modify.
+- Content inside `<intent-contract>` 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, write a best-effort result artifact in `{implementation_artifacts}` with `Status: blocked`, `Blocking condition: missing spec_file before implementation`, and terminate cleanly.
+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
 
@@ -23,15 +23,15 @@ Capture `baseline_revision` (current HEAD, or `NO_VCS` if version control is una
 
 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 sub-agent, include them in the sub-agent prompt so it has access to the referenced context.
+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 a sub-agent/task and let it implement. If no sub-agents are available, set `{spec_file}` frontmatter status to `blocked`, append `## Auto Run Result` with `Status: blocked`, `Blocking condition: implementation subagent unavailable`, and terminate cleanly.
+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.
 
-### Self-Check
+### Tasks & Acceptance Verification
 
-Before leaving this step, verify every task in the `## Tasks & Acceptance` section of `{spec_file}` is complete. Mark each finished task `[x]`. If any task is not done, finish it before proceeding.
+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
 

src/bmm-skills/4-implementation/bmad-dev-auto/step-04-review.md

@@ -1,6 +1,5 @@
 ---
 deferred_work_file: '{implementation_artifacts}/deferred-work.md'
-specLoopIteration: 1
 ---
 
 # Step 4: Review
@@ -38,9 +37,9 @@ Launch two subagents without prior session context.
    - **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 or bad_spec findings exist, they trigger a loopback — lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Increment `{specLoopIteration}` on each loopback. If it exceeds 5, set `{spec_file}` frontmatter status to `blocked`, append `## Auto Run Result` with `Status: blocked`, `Blocking condition: review repair loop exceeded 5 iterations`, and terminate cleanly.
-   - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Set `{spec_file}` frontmatter status to `blocked`, append `## Auto Run Result` with `Status: blocked`, `Blocking condition: intent gap in frozen intent`, and the intent-gap findings, then terminate cleanly.
-   - **bad_spec** — Root cause is outside `<frozen-after-approval>`. 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 non-frozen sections 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.
+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 `<intent-contract>`. 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 `<intent-contract>`. Do not modify content inside `<intent-contract>`. 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 `<intent-contract>` 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
@@ -52,21 +51,11 @@ Launch two subagents without prior session context.
 
 ## Finalize
 
-Change `{spec_file}` status to `done` in the frontmatter.
-
-Append `## Auto Run Result` to `{spec_file}`. Include:
-
-- `Status: done`
+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
 
-Workflow complete.
-
-## On Complete
-
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
-
-If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.
+HALT with status `done`.