5-phase-workflow 1.5.2 → 1.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "5-phase-workflow",
-  "version": "1.5.2",
+  "version": "1.5.4",
   "description": "A 5-phase feature development workflow for Claude Code",
   "bin": {
     "5-phase-workflow": "bin/install.js"

package/src/agents/feature-planner.md

@@ -1,7 +1,7 @@
 ---
 name: feature-planner
 description: Creates feature specifications from requirements through structured Q&A. Planning-only agent — never implements.
-tools: Read, Write, Task, AskUserQuestion
+tools: Read, Write, Task, AskUserQuestion, TaskCreate, TaskUpdate, TaskList, TaskGet
 ---
 
 <role>
@@ -21,12 +21,15 @@ HARD CONSTRAINTS — violations waste tokens and get blocked by plan-guard:
 - The feature spec describes WHAT and WHY, never HOW
 - If you feel the urge to implement, STOP and ask a clarifying question instead
 - Your output is a SPECIFICATION, not a design document. No code. No file layouts. No API shapes.
+- ALWAYS track progress using TaskCreate/TaskUpdate/TaskList. Mark each task `in_progress` before starting and `completed` when done. NEVER skip tasks. NEVER work on a later task while an earlier task is still pending.
+- Before writing feature.md, call TaskList and verify tasks 1-6 are all `completed`. If any are not, go back and complete them.
 </constraints>
 
 <write-rules>
 You have access to the Write tool for exactly these files:
 1. `.5/.planning-active` — Step 0 only
 2. `.5/features/{name}/feature.md` — Step 5 only
+3. Task tracking tools (TaskCreate, TaskUpdate, TaskList, TaskGet) — used throughout to track progress
 Any other Write target WILL be blocked by the plan-guard hook. Do not attempt it.
 </write-rules>
 

package/src/commands/5/configure.md

@@ -421,8 +421,4 @@ Tell the user:
 4. "After that: Continue with `/5:implement-feature CONFIGURE` -> `/5:verify-implementation` -> `/5:review-code` (clearing context between each phase)"
 
 ## Related Documentation
-
-- [5-Phase Workflow Guide](../../docs/workflow-guide.md)
 - [configure-project skill](../../skills/configure-project/SKILL.md)
-- [/5:plan-feature command](./plan-feature.md)
-- [/5:plan-implementation command](./plan-implementation.md)

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

@@ -251,9 +251,3 @@ Skill: "Feature spec updated. Changes:
 - Added: Full CRUD operations
 Next: /clear then /5:plan-implementation PROJ-1234-add-feature"
 ```
-
-## Related Documentation
-
-- [5-Phase Workflow Guide](../docs/workflow-guide.md)
-- [plan-feature command](./plan-feature.md)
-- [plan-implementation command](./plan-implementation.md)

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

@@ -1,7 +1,7 @@
 ---
 name: 5:implement-feature
 description: Executes an implementation plan by delegating to agents. Phase 3 of the 5-phase workflow.
-allowed-tools: Task, Read, Write, Glob, Grep, Bash
+allowed-tools: Task, Read, Write, Glob, Grep, Bash, TaskCreate, TaskUpdate, TaskList
 context: fork
 user-invocable: true
 ---
@@ -21,7 +21,18 @@ You are a thin orchestrator:
 - Track progress
 - Report completion
 
-Do NOT write code directly. Spawn agents to do the work.
+**DO NOT:**
+- Write code directly — spawn agents
+- Skip state file updates between steps
+- Mark a step complete before writing state
+- Proceed to next step if state write fails
+- Use `git add .` at any point
+
+**Key Principles:**
+- Thin orchestrator: read, delegate, track, report
+- State is the source of truth: write it before moving on
+- Forward progress: failed components are logged, not blocking
+- Resumable: state enables restart from any interrupted step
 
 ## Process
 
@@ -43,9 +54,17 @@ Also read `.5/config.json` and extract:
 - `git.autoCommit` (boolean, default `false`)
 - `git.commitMessage.pattern` (string, default `{ticket-id} {short-description}`)
 
+**Check for existing state.json** at `.5/features/{feature-name}/state.json`:
+
+- **`status: "completed"`** → Tell the user "This feature is already implemented." Suggest `/5:verify-implementation {feature-name}`. Stop.
+- **`status: "in-progress"`** → Tell the user "Resuming from step {currentStep}." Skip Step 2 initialization; go directly to Step 2b (recreate TaskCreate tasks) and Step 3 (resume from `currentStep`).
+- **`status: "failed"`** → Use AskUserQuestion: "Implementation previously failed at step {currentStep}. How would you like to proceed?" with options: "Resume from step {currentStep}" / "Restart from the beginning"
+  - If Resume: proceed as in-progress case above
+  - If Restart: delete state.json, proceed normally from Step 2
+
 ### Step 2: Initialize State
 
-Create `.5/features/{feature-name}/state.json`:
+Create `.5/features/{feature-name}/state.json` with the full components table parsed from the plan:
 
 ```json
 {
@@ -53,21 +72,45 @@ Create `.5/features/{feature-name}/state.json`:
   "feature": "{feature-name}",
   "status": "in-progress",
   "currentStep": 1,
-  "completed": [],
-  "failed": [],
-  "startedAt": "{ISO-timestamp}"
+  "totalSteps": "{N from plan}",
+  "pendingComponents": [
+    { "name": "{component-name}", "step": 1, "file": "{file-path}" }
+  ],
+  "completedComponents": [],
+  "failedAttempts": [],
+  "verificationResults": {},
+  "commitResults": [],
+  "startedAt": "{ISO-timestamp}",
+  "lastUpdated": "{ISO-timestamp}"
 }
 ```
 
+`pendingComponents` is populated by parsing the full components table from plan.md at startup — one entry per row.
+
+**MANDATORY VERIFICATION:** Read state.json back immediately after writing. Confirm `status` is `"in-progress"` and `pendingComponents` is non-empty.
+If the read fails or content is wrong, stop: "Failed to initialize state file. Cannot proceed safely."
+
 Then remove the planning guard marker (planning is over, implementation is starting):
 
 ```bash
 rm -f .5/.planning-active
 ```
 
+### Step 2b: Create Progress Checklist
+
+Before executing any steps, create one TaskCreate entry per step:
+- Subject: `"Step {N}: {comma-separated component names}"`
+- activeForm: `"Executing step {N}"`
+
+Plus one final task:
+- Subject: `"Run verification"`
+- activeForm: `"Running build and tests"`
+
+Then mark the task for Step 1 as `in_progress`.
+
 ### Step 3: Execute Steps
 
-Group components by step number from the plan. For each step:
+Group components by step number from the plan. For each step (starting from `currentStep` in state.json):
 
 **3a. Analyze step for parallel execution**
 
@@ -110,32 +153,69 @@ The agent file defines the implementation process, output format, and deviation
 **3d. Process results**
 
 Collect results from all agents (parallel or sequential). Parse the `---RESULT---` block from each agent's response. For each:
-- If `STATUS: success` → mark components as completed, note files from `FILES_CREATED`/`FILES_MODIFIED`
-- If `STATUS: failed` → mark components as failed, log the `ERROR` message
-- If no `---RESULT---` block found → treat the response as success if the agent reported creating/modifying files, otherwise treat as failed
+- If `STATUS: success` → component succeeded; note files from `FILES_CREATED`/`FILES_MODIFIED`
+- If `STATUS: failed` → component failed; log the `ERROR` message
+- If no `---RESULT---` block found → treat as success if the agent reported creating/modifying files, otherwise treat as failed
 
 Update state.json:
-```json
-{
-  "currentStep": {N+1},
-  "completed": [...previous, ...newlyCompleted],
-  "failed": [...previous, ...newlyFailed]
-}
-```
+- Move succeeded components: remove from `pendingComponents`, append to `completedComponents` as:
+  ```json
+  { "name": "{name}", "step": {N}, "timestamp": "{ISO}", "filesCreated": [...], "filesModified": [...] }
+  ```
+- Move failed components: append to `failedAttempts` as:
+  ```json
+  { "component": "{name}", "step": {N}, "error": "{message}", "timestamp": "{ISO}", "retryCount": 0 }
+  ```
+- Increment `currentStep`
+- Update `lastUpdated`
+
+**MANDATORY VERIFICATION:** Read state.json back and confirm `lastUpdated` changed.
+If verify fails, stop: "State write failed after step {N}. Cannot proceed safely."
+
+Mark the current step's TaskCreate task as `completed`. Mark the next step's task as `in_progress`.
+
+**3d2. Retry failed components (max 2 retries)**
+
+For each component that returned `STATUS: failed`:
+
+1. **Assess the error:**
+   - **Small fix** (missing import, wrong path, syntax error): Fix with Edit tool directly in main context. Mark as completed. This counts as retry 1.
+   - **Large fix** (logic error, wrong pattern, missing context): Re-spawn the component-executor agent with the same prompt plus an `## Error Context` block describing the previous failure. This counts as retry 1.
+
+2. If the retry also fails:
+   - Update `retryCount: 2` in the component's `failedAttempts` entry
+   - Use AskUserQuestion: "Component '{name}' failed twice. Error: {error}. How would you like to proceed?"
+     Options: "Skip and continue" / "I'll fix manually — pause"
+   - If "Skip": log the skip, move on
+   - If "Pause": update state.json with current progress, stop and wait for user
+
+Never retry more than 2 times per component.
+
+**3d3. Per-step file existence check**
+
+For each file listed in `FILES_CREATED` from successful agents: use Glob to verify the file exists on disk.
+
+If a reported file is missing:
+- Remove the component from `completedComponents`
+- Return it to `pendingComponents`
+- Add a `failedAttempts` entry: `{ "component": "{name}", "step": {N}, "error": "File not found after creation: {path}", "timestamp": "{ISO}", "retryCount": 0 }`
+- Apply retry logic from 3d2
 
 **3e. Auto-Commit Step (if enabled)**
 
-Only fires if `git.autoCommit: true` AND at least one component succeeded. Stage only the step's specific files (never `git add .`), commit with configured `git.commitMessage.pattern` (body: one bullet per component). If commit fails, log warning in `state.json` `commitResults` and continue.
+Only fires if `git.autoCommit: true` AND at least one component succeeded in this step. Stage only the step's specific files (from `FILES_CREATED`/`FILES_MODIFIED`; never `git add .`), commit with configured `git.commitMessage.pattern` (body: one bullet per component). If commit fails, append a warning entry to `commitResults` in state.json and continue.
 
 **3f. Handle failures**
 
-If any component failed:
-- Log the failure in state.json
+If any component failed after retries exhausted:
+- Entry remains in `failedAttempts` with `retryCount: 2`
 - Continue to next step (don't block on failures)
-- Report failures at the end
+- Failures are reported in the completion report
 
 ### Step 4: Run Verification
 
+Mark the "Run verification" TaskCreate task as `in_progress`.
+
 After all steps complete, run build and test:
 
 ```bash
@@ -146,10 +226,24 @@ After all steps complete, run build and test:
 {test-command}
 ```
 
+Update `verificationResults` in state.json:
+```json
+{
+  "buildStatus": "success|failed",
+  "testStatus": "success|skipped|failed",
+  "builtAt": "{ISO-timestamp}"
+}
+```
+Also update `lastUpdated`.
+
+**MANDATORY VERIFICATION:** Read state.json back and confirm `verificationResults.builtAt` is set.
+
 If build or tests fail:
 - Record in state.json
 - Report to user with error details
 
+Mark the "Run verification" TaskCreate task as `completed`.
+
 ### Step 5: Update State and Report
 
 Update state.json:
@@ -157,22 +251,25 @@ Update state.json:
 {
   "status": "completed",
   "completedAt": "{ISO-timestamp}",
-  "buildStatus": "success|failed",
-  "testStatus": "success|failed"
+  "lastUpdated": "{ISO-timestamp}"
 }
 ```
 
+**MANDATORY VERIFICATION:** Read state.json back and confirm `status` is `"completed"`.
+If read fails, warn the user but do not re-attempt — the implementation work is done; only tracking failed.
+
 Tell the user:
 ```
 Implementation complete!
 
 {ticket}: {feature-name}
 - {N} components created/modified
+- {M} components skipped (failures that exhausted retries)
 - Build: {status}
 - Tests: {status}
 {If git.autoCommit was true: "- Commits: {N} atomic commits created"}
 
-{If any failures: list them}
+{If any failures: list them with errors}
 
 Next steps:
 1. Run `/clear` to reset context (recommended between phases)
@@ -181,18 +278,47 @@ Next steps:
 
 ## Handling Interruptions
 
-If implementation is interrupted, the state file allows resuming:
-- Read state.json
-- For each step marked as completed, verify the output files still exist on disk using Glob
-- If any completed files are missing, move those components back to pending and re-run them
-- Skip steps where all components are in `completed` AND their files verified to exist
-- Resume from `currentStep`
+If implementation is interrupted, the state file enables resuming:
+
+1. Read state.json; note `currentStep`, `pendingComponents`, `completedComponents`, `lastUpdated`
+2. For each component in `completedComponents`: use Glob to verify its files still exist on disk
+3. If any file is missing: move the component back to `pendingComponents`, remove from `completedComponents`, adjust `currentStep` if all components for that step are now pending
+4. Skip steps where ALL components are in `completedComponents` AND their files are verified present on disk
+5. Write reconciled state (update `lastUpdated`) before re-executing any steps
 
 ## Example Flow
 
 ```
-Step 1: 2 simple components → 2 parallel haiku agents → update state
-Step 2: 2 moderate components → 2 parallel agents → update state
-Step 3: 1 complex component → 1 sonnet agent → update state
-Step 4: Verify (build + test) → update state → report
+Step 1: 2 simple components → 2 parallel haiku agents → update state → verify write
+Step 2: 2 moderate components → 2 parallel agents → update state → verify write
+Step 3: 1 complex component → 1 sonnet agent → update state → verify write
+Step 4: Verify (build + test) → update verificationResults → verify write → report
 ```
+
+## Instructions Summary
+
+### Before starting:
+1. Check for existing state.json → handle resume / restart / completed cases
+2. Read plan.md → parse components table, implementation notes, verification commands
+3. Read config.json → extract `git.autoCommit`, `git.commitMessage.pattern`
+4. Initialize state.json with richer schema → **MANDATORY: verify write**
+5. Create TaskCreate tasks for all steps + verification → mark step 1 `in_progress`
+
+### For each step:
+1. Determine parallelism (same-step components = parallel)
+2. Determine model per component (simple→haiku, complex→sonnet)
+3. Spawn agents (one per component, parallel when possible)
+4. Collect results, parse `---RESULT---` blocks
+5. Run per-step file existence check (Glob) on `FILES_CREATED`
+6. Run retry logic for failures (max 2 retries per component)
+7. Update state.json → **MANDATORY: verify write**
+8. Run auto-commit if enabled and step had successes (stage specific files only)
+9. Mark step task `completed`, mark next step task `in_progress`
+
+### After all steps:
+1. Run build command
+2. Run test command
+3. Update `verificationResults` in state.json → **verify write**
+4. Update `status: "completed"` in state.json → **MANDATORY: verify write**
+5. Mark verification task `completed`
+6. Report to user

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

@@ -2,7 +2,7 @@
 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.
 agent: feature-planner
-allowed-tools: Read, Write, Task, AskUserQuestion
+allowed-tools: Read, Write, Task, AskUserQuestion, TaskCreate, TaskUpdate, TaskList, TaskGet
 context: fork
 user-invocable: true
 ---
@@ -43,8 +43,29 @@ Write the planning guard marker to `.5/.planning-active` using the Write tool:
 
 This activates the plan-guard hook which prevents accidental source file edits during planning. The marker is removed automatically when implementation starts (`/5:implement-feature`), expires after 4 hours, or can be cleared manually with `/5:unlock`.
 
+### Step 0b: Create Progress Checklist
+
+Create a progress checklist using TaskCreate. Create all 8 tasks in order:
+
+| # | Subject | activeForm | Description |
+|---|---------|------------|-------------|
+| 1 | Activate planning guard | Activating planning guard | Write `.5/.planning-active` marker |
+| 2 | Gather feature description | Gathering feature description | Ask developer for feature description via AskUserQuestion |
+| 3 | Extract ticket ID from branch | Extracting ticket ID | Extract from git branch, sanitize, confirm with developer |
+| 4 | Explore codebase for patterns | Exploring codebase | Spawn Explore sub-agent for project analysis |
+| 5 | Ask 5+ clarifying questions (one at a time) | Asking clarifying questions | Min. 5 questions, one at a time, via AskUserQuestion |
+| 6 | Pre-write checkpoint | Running pre-write checkpoint | Verify 5+ Q&A, no code, spec contains only WHAT/WHY |
+| 7 | Write feature specification | Writing feature specification | Create `.5/features/{ID}-{desc}/feature.md` |
+| 8 | Output completion message and STOP | Completing planning phase | Output message, then STOP |
+
+After creating all 8 tasks: Mark task 1 as `completed` (Step 0 is already done). Mark task 2 as `in_progress`.
+
+> **MANDATORY:** Before starting ANY step, mark the corresponding task as `in_progress`. After completing, mark as `completed`. Never skip a task.
+
 ### Step 1: Gather Feature Description
 
+> Task tracking: Mark "Gather feature description" → `in_progress` before, `completed` after.
+
 Ask the developer for the feature description using AskUserQuestion:
 
 "Please describe the feature you want to develop. Paste the full ticket description or explain it in your own words."
@@ -54,6 +75,8 @@ Ask the developer for the feature description using AskUserQuestion:
 
 ### Step 2: Extract Ticket ID
 
+> Task tracking: Mark "Extract ticket ID" → `in_progress`/`completed`.
+
 Extract the ticket ID from the current git branch:
 - Use `git branch --show-current` via a Bash-free approach: spawn a quick Explore agent if needed
 - Branch format: `{TICKET-ID}-description`
@@ -65,6 +88,8 @@ Extract the ticket ID from the current git branch:
 
 ### Step 3: Spawn Explore Agent for Codebase Analysis
 
+> Task tracking: Mark "Explore codebase for patterns" → `in_progress`/`completed` when sub-agent returns.
+
 Spawn a Task with `subagent_type=Explore`:
 
 ```
@@ -96,6 +121,8 @@ Wait for the sub-agent to return before proceeding.
 
 ### Step 4: Intensive Q&A (5-10 Questions, One at a Time)
 
+> Task tracking: Mark "Ask 5+ clarifying questions" → `in_progress`. Do NOT mark `completed` until 5+ answers received.
+
 Follow the `<question-strategy>` defined in your agent file.
 
 **Optional re-exploration:** If the user mentions components not covered in the initial report, spawn a targeted Explore agent:
@@ -109,6 +136,8 @@ Targeted exploration for feature planning.
 
 ### Step 4b: Pre-Write Checkpoint
 
+> Task tracking: Mark "Pre-write checkpoint" → `in_progress`. If fails (< 5 Q&A), mark questions task back to `in_progress` and return to Step 4.
+
 Before writing the feature spec, verify:
 1. You asked at least 5 questions and received answers
 2. You have NOT written any code or implementation details
@@ -119,6 +148,8 @@ If you have fewer than 5 Q&A pairs, go back to Step 4 and ask more questions.
 
 ### Step 5: Create Feature Specification
 
+> Task tracking: Mark "Write feature specification" → `in_progress`/`completed`.
+
 Determine a feature name: short, kebab-case (e.g., "add-emergency-schedule").
 
 Write to `.5/features/{TICKET-ID}-{description}/feature.md` using Write tool.
@@ -137,6 +168,8 @@ Populate all sections:
 
 ## PLANNING COMPLETE
 
+> Task tracking: Mark "Output completion message and STOP" → `in_progress`. Before stopping, call TaskList to verify ALL 8 tasks are `completed`.
+
 After writing feature.md, output exactly:
 
 ```

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

@@ -1,7 +1,7 @@
 ---
 name: 5:quick-implement
 description: Execute small, focused implementations quickly with state tracking and atomic commits. Skips extensive planning phases and verification agents - use for tasks where you know exactly what to do.
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion, Skill, mcp__jetbrains__*
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion, Skill, TaskCreate, TaskUpdate, TaskList, mcp__jetbrains__*
 context: fork
 user-invocable: true
 ---
@@ -30,6 +30,18 @@ Your job is NOT:
 ❌ Create feature spec files
 ❌ Commit without config (only if git.autoCommit is enabled)
 
+**DO NOT:**
+- Write code directly without using a Skill or spawning an agent
+- Skip state file updates after each component
+- Mark a component complete before writing state
+- Proceed if a state write fails
+- Use `git add .` at any point
+
+**Key Principles:**
+- Small scope: 1-5 files, treated as a single logical step
+- State is the source of truth: write it after every component
+- Resumable: state enables restart from the last completed component
+
 ## Process
 
 ### Step 1: Get Task Description
@@ -66,6 +78,15 @@ Generate a slug from `$DESCRIPTION` using string manipulation (do NOT use bash f
 
 Set `feature_name` to `${TICKET_ID}-${slug}`.
 
+### Step 3b: Check for Existing State
+
+Check if `.5/features/${feature_name}/state.json` already exists:
+
+- **`status: "completed"`** → Tell the user "This task is already implemented." Suggest `/clear` before starting a new task. Stop.
+- **`status: "in-progress"`** → Use AskUserQuestion: "A previous run was interrupted at component '{last completed}'. How would you like to proceed?" Options: "Resume from where I left off" / "Restart from the beginning"
+  - If Resume: skip Steps 4–7 initialization; go directly to Step 7b (recreate TaskCreate tasks) and Step 8 (resume remaining `pendingComponents`)
+  - If Restart: delete state.json, proceed normally from Step 4
+
 ### Step 4: Analyze and Plan
 
 1. **Identify affected files** using Glob and Grep
@@ -124,9 +145,32 @@ Use AskUserQuestion:
 
 **CRITICAL**: You MUST create the state file before starting implementation. This enables resumability if work is interrupted.
 
-Create state file at `.5/features/${feature_name}/state.json` with fields: `ticket`, `feature`, `phase: "quick-implementation"`, `status: "in-progress"`, `currentStep: 1`, `totalSteps: 1`, `completed: []`, `pending: [from plan]`, `failed: []`, `verificationResults: {}`, `startedAt`, `lastUpdated`.
+Create state file at `.5/features/${feature_name}/state.json`:
+
+```json
+{
+  "ticket": "{ticket-id}",
+  "feature": "{feature_name}",
+  "phase": "quick-implementation",
+  "status": "in-progress",
+  "currentStep": 1,
+  "totalSteps": 1,
+  "pendingComponents": [
+    { "name": "{component-name}", "step": 1, "file": "{file-path}" }
+  ],
+  "completedComponents": [],
+  "failedAttempts": [],
+  "verificationResults": {},
+  "commitResults": [],
+  "startedAt": "{ISO-timestamp}",
+  "lastUpdated": "{ISO-timestamp}"
+}
+```
+
+`pendingComponents` is populated from the approved plan's components table — one entry per row.
 
-Verify the file was written correctly with Read tool. If creation fails, stop and report error.
+**MANDATORY VERIFICATION:** Read state.json back immediately after writing. Confirm `status` is `"in-progress"` and `pendingComponents` is non-empty.
+If the read fails or content is wrong, stop: "Failed to initialize state file. Cannot proceed safely."
 
 Then remove the planning guard marker (implementation is starting):
 
@@ -134,26 +178,51 @@ Then remove the planning guard marker (implementation is starting):
 rm -f .5/.planning-active
 ```
 
+### Step 7b: Create Progress Checklist
+
+Create one TaskCreate entry per component:
+- Subject: `"Implement {component-name}"`
+- activeForm: `"Implementing {component-name}"`
+
+Plus one final task:
+- Subject: `"Run verification"`
+- activeForm: `"Running build and tests"`
+
+Mark the first component's task as `in_progress`.
+
 ### Step 8: Execute Implementation
 
 **Decision criteria for execution approach:**
 
 - **Direct execution** (1-2 components, simple edits): Execute skills directly in current context
-- **Step-executor** (3+ components or complex work): Spawn step-executor agent
+- **Agent delegation** (3+ components or complex work): Spawn a general-purpose agent
 
 #### Direct Execution
 
-For each component:
+For each component in `pendingComponents`:
 1. Invoke appropriate skill using Skill tool
-2. **Update state file after each component** (MANDATORY):
+2. Use Glob to verify `FILES_CREATED` exist on disk
+3. **Update state file after each component** (MANDATORY):
    - Read current state file
-   - Move component from `pending` to `completed`
+   - Move component from `pendingComponents` to `completedComponents`:
+     ```json
+     { "name": "{name}", "step": 1, "timestamp": "{ISO}", "filesCreated": [...], "filesModified": [...] }
+     ```
    - Update `lastUpdated` timestamp
    - Write back to state file
-   - Verify write succeeded
-3. Track created/modified files
+   - **Verify write:** Read state.json back and confirm `lastUpdated` changed. If verify fails, stop.
+4. Mark component's TaskCreate task as `completed`. Mark next component's task as `in_progress`.
+
+**If a component fails:**
+- **Small fix** (syntax, import, path): Apply fix with Edit tool directly, retry the skill. Count as retry 1.
+- **Large fix** (logic error, wrong pattern): Re-invoke skill with additional context. Count as retry 1.
+- If retry also fails: Use AskUserQuestion: "Component '{name}' failed twice. Error: {error}. How to proceed?" Options: "Skip and continue" / "I'll fix manually — pause"
+- Never retry more than 2 times. Record failures in `failedAttempts`:
+  ```json
+  { "component": "{name}", "step": 1, "error": "{message}", "timestamp": "{ISO}", "retryCount": {0|1|2} }
+  ```
 
-#### Step-Executor Delegation
+#### Agent Delegation
 
 Determine the model based on the highest complexity in the plan's components:
 - All components `simple` → `haiku`
@@ -191,8 +260,12 @@ Task tool call:
     3. Verify the change
 
     ## Output
-    Report what you created/modified:
-    - {path}: {brief description}
+    End your response with a ---RESULT--- block:
+    ---RESULT---
+    STATUS: success|failed
+    FILES_CREATED: path/to/file1, path/to/file2
+    FILES_MODIFIED: path/to/file3
+    ERROR: {error message if failed}
 
     ## Rules
     - Find patterns from existing code, don't invent conventions
@@ -200,16 +273,22 @@ Task tool call:
     - Don't interact with user - just execute and report
 ```
 
-Process results and **update state file** (MANDATORY):
-- Read current state file
-- Move completed components from `pending` to `completed`
-- Record any failures in `failed`
-- Update `lastUpdated` timestamp
-- Write back to state file
-- Verify write succeeded
+After the agent returns:
+1. Parse the `---RESULT---` block. If missing, treat as success if files were mentioned, otherwise failed.
+2. **File existence check:** Use Glob to verify each file in `FILES_CREATED` exists on disk. If a file is missing, treat that component as failed.
+3. **Retry logic:** For any `STATUS: failed` component or missing file, re-spawn the agent with an `## Error Context` block (counts as retry 1). If retry fails again, use AskUserQuestion as in direct execution.
+4. **Update state file** (MANDATORY):
+   - Move succeeded components: remove from `pendingComponents`, append to `completedComponents` with structured object
+   - Move failed components: append to `failedAttempts` with `retryCount`
+   - Update `lastUpdated`
+   - Write back to state file
+   - **Verify write:** Read state.json back and confirm `lastUpdated` changed. If verify fails, stop.
+5. Mark TaskCreate tasks: completed components → `completed`, remaining → adjust `in_progress`.
 
 ### Step 9: Verification
 
+Mark the "Run verification" TaskCreate task as `in_progress`.
+
 Run build verification if a build skill is configured:
 
 **If build skill is available:**
@@ -232,17 +311,39 @@ Skill tool call:
   args: "{affected test modules}"
 ```
 
+Update `verificationResults` in state.json:
+```json
+{
+  "buildStatus": "success|failed",
+  "testStatus": "success|skipped|failed",
+  "builtAt": "{ISO-timestamp}"
+}
+```
+Also update `lastUpdated`. **Verify write:** Read state.json back and confirm `verificationResults.builtAt` is set.
+
+Mark the "Run verification" TaskCreate task as `completed`.
+
 ### Step 9b: Auto-Commit (if enabled)
 
-Only fires if `git.autoCommit: true` AND build passed. Creates a single commit: stage only plan files (never `git add .`), commit with configured `git.commitMessage.pattern` (body: one bullet per component). If commit fails, log warning and continue.
+Only fires if `git.autoCommit: true` AND build passed. Stage only the component files (from `FILES_CREATED`/`FILES_MODIFIED`; never `git add .`), commit with configured `git.commitMessage.pattern` (body: one bullet per component). If commit fails, append a warning entry to `commitResults` in state.json and continue.
 
 ### Step 10: Update State and Report (MANDATORY)
 
 **CRITICAL**: You MUST update the state file to mark completion.
 
-Update state file to `status: "completed"`, `phase: "completed"`, with `verificationResults` (buildStatus, testStatus, timestamp), `completedAt`, `lastUpdated`. Verify the write.
+Update state file:
+```json
+{
+  "status": "completed",
+  "completedAt": "{ISO-timestamp}",
+  "lastUpdated": "{ISO-timestamp}"
+}
+```
+
+**MANDATORY VERIFICATION:** Read state.json back and confirm `status` is `"completed"`.
+If read fails, warn the user but do not re-attempt — the implementation work is done; only tracking failed.
 
-Report: ticket, description, files created/modified, build/test status, commit status (if auto-commit), and next steps (commit if needed, `/clear` before new task).
+Report: ticket, description, files created/modified, build/test status, commit status (if auto-commit), skipped components (if any), and next steps (manual commit if needed, `/clear` before new task).
 
 **🛑 YOUR JOB IS COMPLETE. DO NOT START NEW TASKS.**
 
@@ -260,3 +361,30 @@ Skills are project-specific and should be configured in your project's `.claude/
 | Tests | Project-specific test skill |
 | Simple edits | Edit tool directly |
 
+## Instructions Summary
+
+### Before starting:
+1. Get task description from user
+2. Extract and sanitize ticket ID from branch name
+3. Generate `feature_name` slug
+4. Check for existing state.json → handle resume / restart / completed cases
+5. Analyze codebase, identify components (max 5)
+6. Create plan.md → get user approval (iterate if needed)
+7. Initialize state.json with richer schema → **MANDATORY: verify write**
+8. Create TaskCreate tasks for all components + verification → mark first component `in_progress`
+
+### For each component:
+1. Invoke skill or spawn agent
+2. Verify files exist on disk (Glob)
+3. Apply retry logic if failed (max 2 retries per component)
+4. Update state.json → **MANDATORY: verify write**
+5. Mark component task `completed`, mark next task `in_progress`
+
+### After all components:
+1. Run build skill (if configured)
+2. Run test skill (if affected)
+3. Update `verificationResults` in state.json → **verify write**
+4. Auto-commit if enabled (stage specific files only)
+5. Update `status: "completed"` in state.json → **MANDATORY: verify write**
+6. Mark verification task `completed`
+7. Report to user

package/src/templates/workflow/STATE.json

@@ -3,7 +3,12 @@
   "feature": "{feature-name}",
   "status": "in-progress",
   "currentStep": 1,
-  "completed": [],
-  "failed": [],
-  "startedAt": "{ISO-timestamp}"
+  "totalSteps": 0,
+  "pendingComponents": [],
+  "completedComponents": [],
+  "failedAttempts": [],
+  "verificationResults": {},
+  "commitResults": [],
+  "startedAt": "{ISO-timestamp}",
+  "lastUpdated": "{ISO-timestamp}"
 }