fix(quick-dev): correct commit ordering, add loopback directive, fix typo (#1876)

* fix(quick-dev): correct commit ordering, add loopback directive, fix typo

- step-05: set spec status to done before committing so the commit
  captures the final state
- step-04: add explicit read-and-follow directive to intent_gap loopback
  matching the pattern used by bad_spec
- SKILL.md: fix missing apostrophe in description

* fix(quick-dev): remove stray commit instruction from review step

The review step (step-04) had a bare "4. Commit." line that conflicted
with commit responsibility belonging solely to step-05-present.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-quick-dev-new-preview
-description: 'Implements any user intent, requirement, story, bug fix or change request by producing clean working code artifacts that follow the projects existing architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any code, component or feature.'
+description: 'Implements any user intent, requirement, story, bug fix or change request by producing clean working code artifacts that follow the project''s existing architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any code, component or feature.'
 ---
 
 Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-04-review.md

@@ -43,13 +43,11 @@ Do NOT `git add` anything — this is read-only inspection.
    - **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, HALT and escalate to the human. On any loopback, re-evaluate routing — if scope has grown beyond one-shot, escalate `execution_mode` to plan-code-review.
-   - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve, then re-run steps 2–4.
+   - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `./steps/step-02-plan.md` to re-run steps 2–4.
    - **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 `./steps/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 to `{deferred_work_file}`.
    - **reject** — Drop silently.
-4. Commit.
-
 ## NEXT
 
 Read fully and follow `./steps/step-05-present.md`

src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-05-present.md

@@ -12,8 +12,8 @@ description: 'Present findings, get approval, create PR'
 
 ## INSTRUCTIONS
 
-1. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title.
-2. Change `{spec_file}` status to `done` in the frontmatter.
+1. Change `{spec_file}` status to `done` in the frontmatter.
+2. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title.
 3. Display summary of your work to the user, including the commit hash if one was created. Advise on how to review the changes. Offer to push and/or create a pull request.
 
 Workflow complete.

src/core/module-help.csv

@@ -2,7 +2,7 @@ module,phase,name,code,sequence,workflow-file,command,required,agent,options,des
 core,anytime,Brainstorming,BSP,,_bmad/core/workflows/brainstorming/workflow.md,bmad-brainstorming,false,analyst,,"Generate diverse ideas through interactive techniques. Use early in ideation phase or when stuck generating ideas.",{output_folder}/brainstorming/brainstorming-session-{{date}}.md,,
 core,anytime,Party Mode,PM,,_bmad/core/workflows/party-mode/workflow.md,bmad-party-mode,false,party-mode facilitator,,"Orchestrate multi-agent discussions. Use when you need multiple agent perspectives or want agents to collaborate.",,
 core,anytime,bmad-help,BH,,skill:bmad-help,bmad-help,false,,,"Get unstuck by showing what workflow steps come next or answering BMad Method questions.",,
-core,anytime,Index Docs,ID,,_bmad/core/tasks/index-docs.xml,bmad-index-docs,false,,,"Create lightweight index for quick LLM scanning. Use when LLM needs to understand available docs without loading everything.",,
+core,anytime,Index Docs,ID,,skill:bmad-index-docs,bmad-index-docs,false,,,"Create lightweight index for quick LLM scanning. Use when LLM needs to understand available docs without loading everything.",,
 core,anytime,Shard Document,SD,,_bmad/core/tasks/shard-doc.xml,bmad-shard-doc,false,,,"Split large documents into smaller files by sections. Use when doc becomes too large (>500 lines) to manage effectively.",,
 core,anytime,Editorial Review - Prose,EP,,skill:bmad-editorial-review-prose,bmad-editorial-review-prose,false,,,"Review prose for clarity, tone, and communication issues. Use after drafting to polish written content.",report located with target document,"three-column markdown table with suggested fixes",
 core,anytime,Editorial Review - Structure,ES,,skill:bmad-editorial-review-structure,bmad-editorial-review-structure,false,,,"Propose cuts, reorganization, and simplification while preserving comprehension. Use when doc produced from multiple subprocesses or needs structural improvement.",report located with target document,

src/core/tasks/bmad-index-docs/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-index-docs
+description: 'Generates or updates an index.md to reference all docs in the folder. Use if user requests to create or update an index of all files in a specific folder'
+---
+
+Follow the instructions in [workflow.md](workflow.md).

src/core/tasks/bmad-index-docs/bmad-skill-manifest.yaml

@@ -0,0 +1 @@
+type: skill

src/core/tasks/bmad-index-docs/workflow.md

@@ -0,0 +1,61 @@
+# Index Docs
+
+**Goal:** Generate or update an index.md to reference all docs in a target folder.
+
+
+## EXECUTION
+
+### Step 1: Scan Directory
+
+- List all files and subdirectories in the target location
+
+### Step 2: Group Content
+
+- Organize files by type, purpose, or subdirectory
+
+### Step 3: Generate Descriptions
+
+- Read each file to understand its actual purpose and create brief (3-10 word) descriptions based on the content, not just the filename
+
+### Step 4: Create/Update Index
+
+- Write or update index.md with organized file listings
+
+
+## OUTPUT FORMAT
+
+```markdown
+# Directory Index
+
+## Files
+
+- **[filename.ext](./filename.ext)** - Brief description
+- **[another-file.ext](./another-file.ext)** - Brief description
+
+## Subdirectories
+
+### subfolder/
+
+- **[file1.ext](./subfolder/file1.ext)** - Brief description
+- **[file2.ext](./subfolder/file2.ext)** - Brief description
+
+### another-folder/
+
+- **[file3.ext](./another-folder/file3.ext)** - Brief description
+```
+
+
+## HALT CONDITIONS
+
+- HALT if target directory does not exist or is inaccessible
+- HALT if user does not have write permissions to create index.md
+
+
+## VALIDATION
+
+- Use relative paths starting with ./
+- Group similar files together
+- Read file contents to generate accurate descriptions - don't guess from filenames
+- Keep descriptions concise but informative (3-10 words)
+- Sort alphabetically within groups
+- Skip hidden files (starting with .) unless specified

src/core/tasks/bmad-skill-manifest.yaml

@@ -1,8 +1,3 @@
-index-docs.xml:
-  canonicalId: bmad-index-docs
-  type: task
-  description: "Generates or updates an index.md to reference all docs in the folder"
-
 shard-doc.xml:
   canonicalId: bmad-shard-doc
   type: task

src/core/tasks/index-docs.xml

@@ -1,65 +0,0 @@
-<task id="_bmad/core/tasks/index-docs" name="Index Docs"
-  description="Generates or updates an index.md to reference all docs in the folder. Use if user requests to create or update an index of all files in a specific folder">
-  <llm critical="true">
-    <i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
-    <i>DO NOT skip steps or change the sequence</i>
-    <i>HALT immediately when halt-conditions are met</i>
-    <i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
-    <i>Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution</i>
-  </llm>
-
-  <flow>
-    <step n="1" title="Scan Directory">
-      <i>List all files and subdirectories in the target location</i>
-    </step>
-
-    <step n="2" title="Group Content">
-      <i>Organize files by type, purpose, or subdirectory</i>
-    </step>
-
-    <step n="3" title="Generate Descriptions">
-      <i>Read each file to understand its actual purpose and create brief (3-10 word) descriptions based on the content, not just the
-        filename</i>
-    </step>
-
-    <step n="4" title="Create/Update Index">
-      <i>Write or update index.md with organized file listings</i>
-    </step>
-  </flow>
-
-  <output-format>
-    <example>
-      # Directory Index
-
-      ## Files
-
-      - **[filename.ext](./filename.ext)** - Brief description
-      - **[another-file.ext](./another-file.ext)** - Brief description
-
-      ## Subdirectories
-
-      ### subfolder/
-
-      - **[file1.ext](./subfolder/file1.ext)** - Brief description
-      - **[file2.ext](./subfolder/file2.ext)** - Brief description
-
-      ### another-folder/
-
-      - **[file3.ext](./another-folder/file3.ext)** - Brief description
-    </example>
-  </output-format>
-
-  <halt-conditions critical="true">
-    <i>HALT if target directory does not exist or is inaccessible</i>
-    <i>HALT if user does not have write permissions to create index.md</i>
-  </halt-conditions>
-
-  <validation>
-    <i>Use relative paths starting with ./</i>
-    <i>Group similar files together</i>
-    <i>Read file contents to generate accurate descriptions - don't guess from filenames</i>
-    <i>Keep descriptions concise but informative (3-10 words)</i>
-    <i>Sort alphabetically within groups</i>
-    <i>Skip hidden files (starting with .) unless specified</i>
-  </validation>
-</task>