5-phase-workflow 1.2.2 → 1.4.0

package/src/commands/5/plan-feature.md

@@ -1,13 +1,34 @@
 ---
 name: 5:plan-feature
 description: Plans feature implementation by analyzing requirements, identifying affected modules, and creating a structured feature specification. Use at the start of any new feature to ensure systematic implementation. This is Phase 1 of the 5-phase workflow.
-allowed-tools: Read, Glob, Grep, Task, AskUserQuestion
+allowed-tools: Bash, Write, Task, AskUserQuestion
 context: fork
 user-invocable: true
 ---
 
 # Plan Feature Implementation (Phase 1)
 
+## Prerequisites Check
+
+**CRITICAL: Check for configuration before proceeding**
+
+```bash
+if [ ! -f ".claude/.5/config.json" ]; then
+  echo "❌ Configuration not found"
+  echo ""
+  echo "Please run /5:configure first to set up your project."
+  echo ""
+  echo "The configure command will:"
+  echo "  • Detect your project type and build commands"
+  echo "  • Set up ticket tracking conventions"
+  echo "  • Generate documentation (CLAUDE.md)"
+  echo "  • Create project-specific skills"
+  exit 1
+fi
+```
+
+**If config doesn't exist, STOP IMMEDIATELY. Do not proceed with the workflow.**
+
 ## Overview
 
 This skill is the **first phase** of the 5-phase workflow:
@@ -19,13 +40,26 @@ This skill is the **first phase** of the 5-phase workflow:
 
 This skill guides intensive collaboration with the developer to understand requirements, challenge assumptions, and create a comprehensive feature specification.
 
+## ⚠️ CRITICAL ARCHITECTURE
+
+**This command uses a READ-ONLY sub-agent for codebase exploration.**
+
+You (the main agent) orchestrate the process:
+- You ask questions via AskUserQuestion
+- You spawn a read-only Explore agent to analyze the codebase
+- You receive findings from the sub-agent
+- You create the feature.md file
+- You inform the user of next steps
+
+**The sub-agent CANNOT write files or implement anything. It can only read and report.**
+
 ## ⚠️ CRITICAL SCOPE CONSTRAINT
 
 **THIS COMMAND ONLY CREATES THE FEATURE SPECIFICATION. IT DOES NOT IMPLEMENT.**
 
 Your job in this phase:
 ✅ Ask questions
-✅ Explore codebase
+✅ Spawn read-only sub-agent to explore codebase
 ✅ Create feature.md file
 ✅ Tell user to run /5:plan-implementation
 
@@ -80,35 +114,84 @@ Automatically extract the ticket ID from the current git branch:
 - Ask the developer if the ticket ID is correct
 - If no ticket ID found, ask developer for it
 
-### Step 3: Analyze Existing Codebase
+### Step 3: Spawn Read-Only Explore Agent
+
+**CRITICAL: Delegate ALL codebase exploration to a sub-agent.**
 
-Explore the codebase to understand existing patterns and identify affected modules:
+Spawn a Task with `subagent_type=Explore` with the following prompt structure:
 
 ```
-1. Explore the project structure to identify modules/components
-   - Use Glob to discover relevant directories
-   - Look for patterns that indicate module organization
+Analyze the codebase for a feature planning session.
 
-2. Check existing implementations in relevant modules
-   - Search for similar features or components
-   - Identify coding patterns and conventions
+**Feature Description:** {paste the user's feature description here}
 
-3. Check for similar patterns across the codebase
-   - Search for class/function patterns that might be reusable
+**Your Task:**
+1. Explore the project structure to identify modules/components
+2. Find existing implementations similar to this feature
+3. Identify coding patterns and conventions used
+4. Find reusable components or patterns
+5. Identify which existing files/modules would be affected
+
+**Report Format:**
+Return a structured report with:
+- Project structure overview
+- Relevant existing patterns found
+- Similar implementations discovered
+- Affected modules/files
+- Reusable components identified
+- Potential integration points
+
+**IMPORTANT:** You are a READ-ONLY agent. Only use Read, Glob, and Grep tools. Do NOT suggest implementations or write any code.
 ```
 
-Use Task tool with subagent_type=Explore for complex exploration.
-
-**Goal:** Understand what already exists so you can ask informed questions.
+**Wait for the sub-agent to return its findings before proceeding.**
 
 ### Step 4: Intensive Collaboration (5-10 Questions, ONE AT A TIME)
 
-**CRITICAL:** After exploring the codebase, engage in intensive Q&A. This is NOT optional.
+**CRITICAL:** After receiving the exploration report, engage in intensive Q&A. This is NOT optional.
 
 - Ask 5-10 clarifying questions using AskUserQuestion
 - **ONE question at a time** - wait for answer before next question
 - Do NOT list multiple questions in one message
 - Do NOT skip to creating feature.md before asking at least 5 questions
+- **Use the sub-agent's findings to inform your questions**
+
+#### Step 4b: Optional Targeted Re-Exploration
+
+During Q&A, the user may mention components, modules, or patterns that weren't covered in the initial exploration. You MAY spawn additional targeted Explore agents to gather more specific information.
+
+**When to trigger re-exploration:**
+- User mentions a specific file, module, or service by name that wasn't in the initial report
+- User's answer reveals a dependency or integration point not previously identified
+- User asks "have you looked at X?" or "what about the Y module?"
+- Understanding a specific component is critical for accurate feature specification
+
+**How to re-explore:**
+
+Spawn a targeted Task with `subagent_type=Explore`:
+
+```
+Targeted exploration for feature planning.
+
+**Context:** During Q&A, the user mentioned {specific component/module/pattern}.
+
+**Focused Task:**
+1. Find and analyze {specific component} mentioned by user
+2. Understand how it works and its patterns
+3. Identify how it might relate to the planned feature
+
+**Report:** Provide a focused summary of:
+- How this component works
+- Relevant patterns or conventions
+- How it could integrate with the planned feature
+
+**IMPORTANT:** READ-ONLY. Only use Read, Glob, and Grep tools.
+```
+
+**Guidelines:**
+- Keep re-explorations focused and specific (not broad searches)
+- Use findings to ask better follow-up questions
+- Document relevant discoveries in the final feature spec
 
 **Question categories to explore:**
 
@@ -137,12 +220,12 @@ Use Task tool with subagent_type=Explore for complex exploration.
    - What are the acceptance criteria?
    - What test scenarios should be covered?
 
-6. **Integration Points**
+6. **Integration Points** (informed by sub-agent findings)
    - Which existing components/modules are affected?
    - Are there API changes?
    - How does this interact with existing features?
 
-7. **Alternative Approaches**
+7. **Alternative Approaches** (informed by sub-agent findings)
    - Have you considered approach X instead?
    - Is this the simplest solution?
    - Could we reuse existing components?
@@ -156,7 +239,7 @@ Use Task tool with subagent_type=Explore for complex exploration.
 - "Is this the simplest solution?"
 - "Have you considered X alternative?"
 - "What happens when Y fails?"
-- "Could we use existing Z component instead?"
+- "Could we use existing Z component instead?" (reference sub-agent findings)
 - "Is a full factory needed or just simple creation?"
 
 **Ask questions ONE AT A TIME.** Use AskUserQuestion for each question. For clarifying questions, provide 2-4 options where meaningful. Wait for the user's answer before asking the next question. Open questions (like feature description) can use free text.
@@ -169,7 +252,7 @@ Based on the feature description and discussion:
 
 ### Step 6: Create Feature Specification
 
-Write a comprehensive feature spec to `.5/{TICKET-ID}-{description}/feature.md` using the template structure.
+Write a comprehensive feature spec to `.5/features/{TICKET-ID}-{description}/feature.md` using the Write tool.
 
 **THIS IS YOUR FINAL OUTPUT. After creating this file, proceed immediately to Step 7.**
 
@@ -182,7 +265,7 @@ Key sections to populate:
 - **Problem Statement** - Why this feature is needed
 - **Requirements** - Functional and non-functional requirements from discussion
 - **Constraints** - Business, technical, and time constraints identified
-- **Affected Components** - Discovered from codebase exploration
+- **Affected Components** - From sub-agent exploration report
 - **Entity Definitions** - If the feature involves new data structures
 - **Acceptance Criteria** - Verifiable criteria for success
 - **Alternatives Considered** - Options discussed and why chosen approach was selected
@@ -195,11 +278,12 @@ Follow these steps **IN ORDER** and **STOP after step 8**:
 
 1. **Ask for feature description** - Request task description and additional information from developer
 2. **Extract Ticket ID** - Get current branch name and extract ticket ID using configured pattern
-3. **Explore the codebase** - Understand existing patterns and affected modules
-4. **Ask 5-10 clarifying questions** - Based on findings, ask informed questions using AskUserQuestion - This is MANDATORY
+3. **Spawn Explore sub-agent** - Delegate codebase analysis to read-only agent, wait for report
+4. **Ask 5-10 clarifying questions** - Based on sub-agent findings, ask informed questions using AskUserQuestion - This is MANDATORY
+   - **4b. Re-explore as needed** - If user mentions unknown components during Q&A, spawn targeted Explore agents
 5. **Challenge assumptions** - Present alternatives, question complexity
 6. **Determine feature name** - Create short kebab-case description
-7. **Create feature specification** in `.5/{TICKET-ID}-{description}/feature.md`
+7. **Create feature specification** in `.5/features/{TICKET-ID}-{description}/feature.md` using Write tool
 8. **Inform the developer** to review the spec, run `/clear` to reset context, and then run `/5:plan-implementation {TICKET-ID}-{description}`
 
 **🛑 STOP HERE. YOUR JOB IS COMPLETE. DO NOT PROCEED TO IMPLEMENTATION.**
@@ -208,12 +292,13 @@ Follow these steps **IN ORDER** and **STOP after step 8**:
 
 1. **Feature description first** - Get context before asking detailed questions
 2. **Auto-extract ticket ID** - Parse from branch name automatically
-3. **Explore before questioning** - Understand codebase to ask informed questions
-4. **Challenge assumptions** - Don't accept requirements at face value
-5. **Explore alternatives** - Present options and trade-offs
-6. **Document decisions** - Capture why choices were made
-7. **Structured output** - Use the feature spec template consistently
-8. **Clear handoff** - Tell developer what to do next
+3. **Delegate exploration** - Use read-only sub-agent for codebase analysis
+4. **Explore before questioning** - Wait for sub-agent report before asking questions
+5. **Challenge assumptions** - Don't accept requirements at face value
+6. **Explore alternatives** - Present options and trade-offs
+7. **Document decisions** - Capture why choices were made
+8. **Structured output** - Use the feature spec template consistently
+9. **Clear handoff** - Tell developer what to do next
 
 
 ## Common Feature Types
@@ -236,16 +321,21 @@ Follow these steps **IN ORDER** and **STOP after step 8**:
 
 ## Example Workflow
 
-1. User runs: `/plan-feature`
-2. Skill asks: "Please describe the feature you want to develop"
+1. User runs: `/5:plan-feature`
+2. Main agent asks: "Please describe the feature you want to develop"
 3. User: "I want to add emergency schedule tracking to products. It should allow marking products as emergency and setting a schedule window."
-4. Skill extracts: Ticket ID `PROJ-1234` from branch `PROJ-1234-add-emergency-schedule`
-5. Skill explores: Checks Product model, related components, existing scheduling infrastructure
-6. Skill asks 8 informed questions about requirements, scope, validation, API, etc.
-7. Skill challenges: "Could we reuse existing scheduling infrastructure instead of creating new one?"
-8. Skill determines: Feature name `add-emergency-schedule`
-9. Skill creates: `.5/PROJ-1234-add-emergency-schedule/feature.md`
-10. Skill tells user: "✅ Feature spec created at `.5/PROJ-1234-add-emergency-schedule/feature.md`
+4. Main agent extracts: Ticket ID `PROJ-1234` from branch `PROJ-1234-add-emergency-schedule`
+5. **Main agent spawns Explore sub-agent** with feature description
+6. **Sub-agent returns report:** Found Product model at src/models/Product.ts, existing ScheduleService at src/services/ScheduleService.ts, similar pattern in src/models/Promotion.ts...
+7. Main agent asks Question 1: "Should emergency schedules support recurring patterns or just one-time windows?"
+8. User answers: "One-time for now, but we have the NotificationService that should trigger alerts"
+9. **Main agent spawns targeted Re-Explore** for NotificationService (wasn't in initial report)
+10. **Sub-agent returns:** Found NotificationService at src/services/NotificationService.ts with event-based triggers...
+11. Main agent continues Q&A with better context about notifications
+12. Main agent challenges: "The sub-agent found existing ScheduleService - could we reuse it instead of creating new scheduling infrastructure?"
+13. Main agent determines: Feature name `add-emergency-schedule`
+14. Main agent creates: `.5/features/PROJ-1234-add-emergency-schedule/feature.md` using Write tool
+15. Main agent tells user: "✅ Feature spec created at `.5/features/PROJ-1234-add-emergency-schedule/feature.md`
 
     **Next steps:**
     1. Review the feature spec

package/src/commands/5/plan-implementation.md

@@ -1,26 +1,71 @@
 ---
 name: 5:plan-implementation
 description: Creates an implementation plan from a feature spec. Phase 2 of the 5-phase workflow.
-allowed-tools: Read, Glob, Grep, Task, AskUserQuestion, Write
+allowed-tools: Bash, Read, Write, Task, AskUserQuestion
 context: fork
 user-invocable: true
 ---
 
 # Plan Implementation (Phase 2)
 
+## Prerequisites Check
+
+**CRITICAL: Check for configuration before proceeding**
+
+```bash
+if [ ! -f ".claude/.5/config.json" ]; then
+  echo "❌ Configuration not found"
+  echo ""
+  echo "Please run /5:configure first to set up your project."
+  echo ""
+  echo "The configure command will:"
+  echo "  • Detect your project type and build commands"
+  echo "  • Set up ticket tracking conventions"
+  echo "  • Generate documentation (CLAUDE.md)"
+  echo "  • Create project-specific skills"
+  exit 1
+fi
+```
+
+**If config doesn't exist, STOP IMMEDIATELY. Do not proceed with the workflow.**
+
 Create an implementation plan that maps a feature spec to concrete components.
 
+## ⚠️ CRITICAL ARCHITECTURE
+
+**This command uses a READ-ONLY sub-agent for codebase exploration.**
+
+You (the main agent) orchestrate the process:
+- You read ONLY `.5/{feature-name}/feature.md` using Read tool
+- You spawn a read-only Explore agent to scan the codebase
+- You receive findings from the sub-agent
+- You ask 2-3 technical questions
+- You write ONLY `.5/{feature-name}/plan.md` using Write tool
+
+**The sub-agent CANNOT write files. It can only read and report.**
+
+**YOU may only write to `.5/{feature-name}/plan.md` - NO other files.**
+
 ## Scope
 
 **This command creates the plan. It does NOT implement.**
 
 After creating the plan, tell the user to run `/5:implement-feature`.
 
+## ❌ Boundaries
+
+- ❌ **Do NOT read source code files directly** - Use Explore sub-agent
+- ❌ **Do NOT write any file except plan.md** - No source code, no other files
+- ❌ **Do NOT start implementation** - That's Phase 3
+- ❌ **Do NOT write complete code in the plan** - Only describe WHAT to build
+
 ## Process
 
 ### Step 1: Load Feature Spec
 
-Read `.5/{feature-name}/feature.md` (where `{feature-name}` is the argument provided).
+Read `.5/features/{feature-name}/feature.md` (where `{feature-name}` is the argument provided).
+
+**This is the ONLY file you may read directly.**
 
 Extract:
 - Ticket ID
@@ -30,14 +75,36 @@ Extract:
 
 If the file doesn't exist, tell the user to run `/5:plan-feature` first.
 
-### Step 2: Quick Codebase Scan
+### Step 2: Spawn Read-Only Explore Agent for Codebase Scan
+
+**CRITICAL: Delegate ALL codebase exploration to a sub-agent.**
 
-Understand the project structure:
-- Use Glob to find source directories
-- Identify where similar components live (models, services, controllers, tests)
-- Note naming conventions from existing files
+Spawn a Task with `subagent_type=Explore` with the following prompt:
 
-This is a quick scan, not deep analysis. The executor agent will do detailed pattern matching.
+```
+Quick codebase scan for implementation planning.
+
+**Feature:** {one-line summary from feature.md}
+**Affected Components:** {list from feature.md}
+
+**Your Task:**
+1. Find source directories and understand project structure
+2. Identify where similar components live (models, services, controllers, tests)
+3. Note naming conventions from existing files
+4. Find example files that can serve as patterns for new components
+
+**Report Format:**
+Return a structured report with:
+- Project structure (key directories)
+- Naming conventions observed
+- Pattern files for each component type (e.g., "services follow pattern in src/services/UserService.ts")
+- Where new files should be placed
+
+**IMPORTANT:** This is a QUICK scan, not deep analysis. Focus on structure and patterns.
+**READ-ONLY:** Only use Read, Glob, and Grep tools.
+```
+
+**Wait for the sub-agent to return its findings before proceeding.**
 
 ### Step 3: Ask 2-3 Technical Questions (ONE AT A TIME)
 
@@ -54,11 +121,34 @@ Keep it brief. Don't over-question. Don't ask feature questions already answered
 
 - **ONE question at a time** - wait for answer before next question
 - Do NOT list multiple questions in one message
-- Do NOT skip to creating plan.md before asking your questions 
+- Do NOT skip to creating plan.md before asking your questions
+
+#### Step 3b: Optional Targeted Re-Exploration
+
+If during Q&A the user mentions specific patterns, files, or conventions not covered in the initial scan, you MAY spawn additional targeted Explore agents.
+
+**When to trigger:**
+- User mentions a specific file as a pattern to follow
+- User asks about a component not in the initial report
+- Understanding a specific pattern is critical for the plan
+
+**How to re-explore:**
+
+```
+Targeted scan for implementation planning.
+
+**Context:** User mentioned {specific pattern/file/convention}.
+
+**Task:** Find and analyze {specific target} to understand the pattern.
+
+**Report:** How this pattern works and how to apply it.
+
+**READ-ONLY:** Only use Read, Glob, and Grep tools.
+```
 
 ### Step 4: Design Components
 
-Based on the feature spec and codebase scan, identify:
+Based on the feature spec and sub-agent's codebase scan, identify:
 - What files need to be created
 - What files need to be modified
 - The order of implementation (dependencies)
@@ -73,7 +163,9 @@ Not every feature needs all steps. Use what makes sense.
 
 ### Step 5: Write the Plan
 
-Create a single file at `.5/{feature-name}/plan.md`:
+Create a single file at `.5/features/{feature-name}/plan.md`:
+
+**THIS IS THE ONLY FILE YOU MAY WRITE.**
 
 ```markdown
 ---
@@ -134,7 +226,7 @@ created: {ISO-timestamp}
 
 Tell the user:
 ```
-Plan created at `.5/{feature-name}/plan.md`
+Plan created at `.5/features/{feature-name}/plan.md`
 
 {N} components across {M} steps.
 
@@ -143,6 +235,23 @@ Review the plan, then:
 2. Run `/5:implement-feature {feature-name}`
 ```
 
+**🛑 STOP HERE. YOUR JOB IS COMPLETE. DO NOT PROCEED TO IMPLEMENTATION.**
+
+## Example Workflow
+
+1. User runs: `/5:plan-implementation PROJ-1234-add-emergency-schedule`
+2. Main agent reads: `.5/features/PROJ-1234-add-emergency-schedule/feature.md`
+3. **Main agent spawns Explore sub-agent** for codebase scan
+4. **Sub-agent returns:** Project uses src/{models,services,controllers}, services follow UserService.ts pattern...
+5. Main agent asks: "Should the schedule validation be in the service or a separate validator?"
+6. User: "In the service, like we do in OrderService"
+7. **Main agent spawns targeted Re-Explore** for OrderService pattern
+8. Main agent asks one more question about testing approach
+9. Main agent creates: `.5/features/PROJ-1234-add-emergency-schedule/plan.md`
+10. Main agent tells user the plan is ready and to run `/5:implement-feature`
+
+**🛑 COMMAND COMPLETE.**
+
 ## Example Plan
 
 ```markdown
@@ -215,8 +324,9 @@ Components in the same step run in parallel. Structure your plan accordingly:
 - Don't write complete code in the plan
 - Don't spend time on "haiku-ready prompts"
 - Don't create multiple plan files (meta.md, step-N.md, etc.)
-- Don't over-analyze the codebase - the executor will do detailed pattern matching
+- Don't read source code directly - use Explore sub-agent
 - Don't ask more than 3 questions
 - Don't create unnecessary sequential steps - group independent work together
 - **Don't skip to implementation** - This command ONLY creates the plan
 - **Don't batch questions** - Ask one question at a time
+- **Don't write any file except plan.md** - No source code files

package/src/commands/5/quick-implement.md

@@ -8,6 +8,27 @@ user-invocable: true
 
 # Quick Implement
 
+## Prerequisites Check
+
+**CRITICAL: Check for configuration before proceeding**
+
+```bash
+if [ ! -f ".claude/.5/config.json" ]; then
+  echo "❌ Configuration not found"
+  echo ""
+  echo "Please run /5:configure first to set up your project."
+  echo ""
+  echo "The configure command will:"
+  echo "  • Detect your project type and build commands"
+  echo "  • Set up ticket tracking conventions"
+  echo "  • Generate documentation (CLAUDE.md)"
+  echo "  • Create project-specific skills"
+  exit 1
+fi
+```
+
+**If config doesn't exist, STOP IMMEDIATELY. Do not proceed with the workflow.**
+
 Fast path for small, well-understood tasks (1-5 files). Skips extensive planning phases but preserves state tracking and skill-based implementation.
 
 ## ⚠️ CRITICAL SCOPE CONSTRAINT
@@ -30,7 +51,7 @@ Your job is NOT:
 ❌ Skip clarifying questions if unclear
 ❌ Skip state file updates
 ❌ Create feature spec files (use full workflow)
-❌ Commit changes (user handles this)
+❌ Commit without config - Only commit if git.autoCommit is enabled
 
 **This is a FAST PATH for well-understood, small tasks. For anything complex, use the full workflow.**
 
@@ -42,7 +63,7 @@ Your job is NOT:
 - ❌ **Skip clarifying questions** - If implementation is unclear, ask first
 - ❌ **Skip state updates** - State file updates are MANDATORY
 - ❌ **Create feature specs** - This is for quick tasks, not full features
-- ❌ **Auto-commit** - User handles commits
+- ❌ **Commit without config** - Only commit if git.autoCommit is enabled
 - ❌ **Skip plan approval** - Always show plan and get user approval first
 
 **If the task involves more than 5 files or multiple domains, STOP and recommend the full workflow instead.**
@@ -58,7 +79,7 @@ Use AskUserQuestion:
 
 Store as `$DESCRIPTION`.
 
-### Step 2: Extract Ticket ID
+### Step 2: Extract Ticket ID and Load Config
 
 ```bash
 git branch --show-current
@@ -66,6 +87,10 @@ git branch --show-current
 
 Extract ticket ID using configurable pattern from config (e.g., `PROJ-\d+` or `\d+`). If not found, ask developer.
 
+Also read `.claude/.5/config.json` and extract:
+- `git.autoCommit` (boolean, default `false`)
+- `git.commitMessage.pattern` (string, default `{ticket-id} {short-description}`)
+
 ### Step 3: Generate Identifiers
 
 ```bash
@@ -88,7 +113,7 @@ feature_name="${TICKET_ID}-${slug}"
 
 ### Step 5: Create Plan
 
-Write plan to `.5/${feature_name}/plan.md` using the template structure.
+Write plan to `.5/features/${feature_name}/plan.md` using the template structure.
 
 **Template Reference:** Use the structure from `.claude/templates/workflow/QUICK-PLAN.md`
 
@@ -130,7 +155,7 @@ Use AskUserQuestion:
 
 **CRITICAL**: You MUST create the state file before starting implementation. This enables resumability if work is interrupted.
 
-Create state file at `.5/${feature_name}/state.json` using Write tool:
+Create state file at `.5/features/${feature_name}/state.json` using Write tool:
 
 ```json
 {
@@ -247,6 +272,32 @@ Skill tool call:
   args: "{affected test modules}"
 ```
 
+### Step 9b: Auto-Commit (if enabled)
+
+Only fires if `git.autoCommit: true` AND build passed in Step 9.
+
+Creates a **single commit** for all components (not per-component — quick-implement is for small tasks):
+
+1. Stage **only** the specific files from the plan's components (never `git add .`)
+2. Commit using the configured `git.commitMessage.pattern`:
+   - `{ticket-id}` → ticket ID
+   - `{short-description}` → auto-generated summary (imperative mood, max 50 chars for full first line)
+   - Body: one bullet per component
+
+```bash
+# Stage only specific files
+git add {file-1} {file-2} ...
+
+# Commit with configured pattern + body
+git commit -m "{ticket-id} {short-description}
+
+- {concise change 1}
+- {concise change 2}"
+```
+
+3. If commit fails → log warning, record in `state.json`, continue
+4. If build failed in Step 9 → skip commit entirely
+
 ### Step 10: Update State and Report (MANDATORY)
 
 **CRITICAL**: You MUST update the state file to mark completion.
@@ -282,10 +333,14 @@ Components created/modified:
 
 Build: Success
 Tests: {Success | Skipped}
+{If git.autoCommit was true: "Commit: {Success | Failed | Skipped (build failed)}"}
 
-State: .5/${feature_name}/state.json
+State: .5/features/${feature_name}/state.json
 
 Next steps:
+{If auto-commit fired successfully:}
+1. For a new task, run `/clear` before starting
+{If auto-commit not enabled or commit skipped:}
 1. Review and commit changes
 2. For a new task, run `/clear` before starting
 ```