5-phase-workflow 1.0.1 → 1.1.0

package/src/agents/step-executor.md

@@ -3,6 +3,7 @@ name: step-executor
 description: Executes all components of a single implementation step by following pre-built prompts. Runs in forked context with haiku for token efficiency.
 tools: Skill, Read, Write, Edit, Glob, Grep, mcp__jetbrains__get_file_problems, mcp__jetbrains__rename_refactoring
 model: haiku
+color: green
 ---
 
 # Step Executor Agent

package/src/agents/step-fixer.md

@@ -3,6 +3,7 @@ name: step-fixer
 description: Diagnoses and fixes errors reported by step-verifier after a failed step execution. Analyzes root cause, applies targeted fixes, and runs local verification. Runs in forked context.
 tools: Read, Edit, Write, Glob, Grep, mcp__jetbrains__get_file_problems, mcp__jetbrains__rename_refactoring
 model: sonnet
+color: red
 ---
 
 # Step Fixer Agent

package/src/agents/step-verifier.md

@@ -3,6 +3,7 @@ name: step-verifier
 description: Compiles affected modules and checks new files for problems after a step execution. Runs in forked context.
 tools: Bash, Read, Glob, Skill, mcp__jetbrains__get_file_problems
 model: sonnet
+color: yellow
 ---
 
 # Step Verifier Agent

package/src/agents/verification-agent.md

@@ -3,6 +3,7 @@ name: verification-agent
 description: Performs complete verification of a feature implementation including file existence, problem detection, compilation, and tests. Runs in forked context.
 tools: Bash, Read, Glob, Skill, mcp__jetbrains__get_file_problems
 model: sonnet
+color: cyan
 ---
 
 # Verification Agent
@@ -17,41 +18,59 @@ The spawning command provides:
 
 ```
 Feature Name: {feature-name}
-Implementation Plan Path: .5/{feature-name}/plan.md
+Implementation Plan Path: .5/{feature-name}/plan/
 Expected Files:
 - {path/to/file1.{ext}}
 - {path/to/file2.{ext}}
 - {path/to/file3.{ext}}
+(aggregated from all step files by verify-implementation command)
 Affected Modules:
 - {module-path-1}
 - {module-path-2}
+(from verification.md)
 Test Modules:
 - {module-path-for-tests}
+(from verification.md)
+Build Command: {from verification.md}
+Test Command: {from verification.md}
 ```
 
 ## Process
 
 ### 0. Parse Implementation Plan
 
-Read the implementation plan from the provided path and extract:
+Read the implementation plan from the provided path (`.5/{feature-name}/plan/`) and extract:
 
-**Component Checklist:**
-- Parse each step and task
-- Extract expected files, method signatures, expected logic
-- Identify checkboxes that should be completed
+**Plan Metadata:**
+- Read `plan/meta.md` for overview and risks
+
+**Component Checklist (from each step file):**
+- For each step file (`plan/step-1.md`, `plan/step-2.md`, etc.):
+  - Parse YAML frontmatter for step metadata
+  - Extract YAML components block
+  - Parse each component's expected action, file, and prompt
+  - Extract "Expected Outputs" section for files created/modified
+  - Note any specific implementation requirements or test coverage expectations
 
 **Verification Steps:**
-- Extract the numbered verification steps from the plan
-- These define what needs to be verified after implementation
+- Read `plan/verification.md` for:
+  - Build command
+  - Test command
+  - Expected new files
+  - Expected modified files
+  - Build targets
+  - Test modules
 
 **Acceptance Criteria:**
-- Look for AC (Acceptance Criteria) references in the plan
+- Look for AC (Acceptance Criteria) references in component prompts
 - Extract expected behavior that needs to be verified through tests
 
 **Technical Decisions:**
-- Note any key implementation requirements or constraints
+- Note any key implementation requirements or constraints from component prompts
 - These inform what to look for in the code
 
+**Note:** The verify-implementation command aggregates expected files and passes them to you, so you can use that list directly rather than reading all step files yourself. However, reading step files is useful for understanding detailed requirements in component prompts.
+
 Store this information for use in subsequent verification steps.
 
 ### 1. Check File Existence
@@ -393,12 +412,27 @@ When verifying implementation completeness:
 
 ### Reading Implementation Plans
 
-Plans may have different structures. Look for:
-- Sections titled "Component Checklist", "Tasks", "Waves"
-- Numbered verification steps
+**Atomic Plan Structure (Format Version 2.0):**
+
+The plan is organized as a directory (`.5/{feature-name}/plan/`) with multiple files:
+- `meta.md`: YAML frontmatter with feature metadata + risks section
+- `step-N.md` files: Each contains YAML frontmatter + components YAML block + expected outputs
+- `verification.md`: Build/test commands and expected file lists
+
+To extract information:
+1. Read `meta.md` YAML frontmatter for: feature, ticket, total_steps, total_components
+2. For each step file:
+   - Parse YAML frontmatter: step, name, mode, components (count)
+   - Extract components YAML block (between ` ```yaml` and ` ``` `)
+   - Parse components array with: id, action, file, skill, depends_on, prompt
+   - Read "Expected Outputs" section for created/modified files
+3. Read `verification.md` for build/test config
+
+Look for in component prompts:
 - Acceptance criteria (often labeled AC1, AC2, etc.)
 - Method signatures in code blocks
 - Technical decisions that constrain implementation
+- Test coverage expectations
 
 ## DO NOT
 

package/src/commands/5/configure.md

@@ -254,8 +254,10 @@ Each skill should:
 Tell the user:
 
 1. "Configuration feature planned at `.5/CONFIGURE/feature.md`"
-2. "Next: Run `/5:plan-implementation CONFIGURE`"
-3. "Then: `/5:implement-feature CONFIGURE` -> `/5:verify-implementation` -> `/5:review-code`"
+2. "Next steps:"
+   - "Run `/clear` to reset context"
+   - "Then run `/5:plan-implementation CONFIGURE`"
+3. "After that: Continue with `/5:implement-feature CONFIGURE` -> `/5:verify-implementation` -> `/5:review-code` (clearing context between each phase)"
 
 ## DO NOT
 
@@ -298,7 +300,7 @@ User: "Use these"
 
 Claude: [Writes .5/CONFIGURE/feature.md]
 Claude: "Configuration feature planned at `.5/CONFIGURE/feature.md`"
-Claude: "Next: Run `/5:plan-implementation CONFIGURE`"
+Claude: "Next: Run `/clear` followed by `/5:plan-implementation CONFIGURE`"
 ```
 
 ## Related Documentation

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

@@ -190,8 +190,8 @@ After updating the spec, tell the developer:
    - "Modified: {Y}"
    - "Removed: {Z}"
 3. Ask: "Would you like to:"
-   - "Discuss more (run /discuss-feature again)"
-   - "Proceed to implementation planning (run /plan-implementation {feature-name})"
+   - "Discuss more (run /5:discuss-feature again)"
+   - "Proceed to implementation planning (run `/clear` followed by `/5:plan-implementation {feature-name}`)"
    - "Review the updated spec first"
 
 ## Instructions Summary
@@ -299,7 +299,7 @@ Skill: [Updates Requirements and Acceptance Criteria sections]
 Skill: "Feature specification updated. Changes:
 - Clarified: Single emergency window per product (not multiple)
 - Added: Full CRUD operations for emergency windows
-Would you like to proceed to implementation planning? Run: /plan-implementation PROJ-1234-add-feature"
+Would you like to proceed to implementation planning? Run `/clear` followed by `/5:plan-implementation PROJ-1234-add-feature`"
 ```
 
 ### Example 2: Adding Requirements
@@ -341,7 +341,7 @@ Skill: [Updates Acceptance Criteria, adds notification verification]
 Skill: "Feature specification updated. Changes:
 - Added: Email notification when emergency window starts
 - Added: Integration with email service
-Review the changes and run: /plan-implementation 12345-implement-your-new-feature when ready"
+Review the changes and run `/clear` followed by `/5:plan-implementation PROJ-1234-add-feature` when ready"
 ```
 
 ### Example 3: Simplification

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

@@ -35,7 +35,10 @@ This command is a **thin orchestrator** that:
 
 Before using this skill, ensure:
 1. Feature spec exists at `.5/{TICKET-ID}-{description}/feature.md`
-2. Implementation plan exists at `.5/{TICKET-ID}-{description}/plan.md`
+2. Implementation plan exists at `.5/{TICKET-ID}-{description}/plan/` directory with:
+   - plan/meta.md (metadata)
+   - plan/step-N.md files (one per step)
+   - plan/verification.md (verification config)
 3. Implementation plan has been reviewed and approved by developer
 4. You have the feature name (e.g., "PROJ-1234-add-emergency-schedule") ready
 
@@ -43,14 +46,23 @@ Before using this skill, ensure:
 
 ### Step 1: Load Implementation Plan
 
-Read the implementation plan from `.5/{feature-name}/plan.md` where `{feature-name}` is the argument provided by the user.
+Read the implementation plan metadata from `.5/{feature-name}/plan/meta.md` where `{feature-name}` is the argument provided by the user.
 
-The plan uses a structured format. Extract:
-- From `## Meta`: feature name, ticket ID, total_steps, total_components
-- From `## Steps`: each step block with its components, modes, and pre-built prompts
-- From `## Verification`: build_command, test_command, expected file lists
+**Error Handling:** If the plan directory or meta.md file is missing:
+- Report error immediately: "Error: Implementation plan not found at `.5/{feature-name}/plan/`. Please run /5:plan-implementation first."
+- Do not proceed to Step 2
 
-Each step block contains complete, self-contained component prompts ready to pass directly to haiku agents.
+Parse the YAML frontmatter from meta.md to extract:
+- `feature`: feature name
+- `ticket`: ticket ID
+- `total_steps`: number of steps in the plan
+- `total_components`: total component count
+- `new_files`: count of new files
+- `modified_files`: count of modified files
+
+Store this metadata for state file initialization.
+
+**Note:** Individual step files (plan/step-N.md) will be loaded on-demand during Step 4 when executing each step.
 
 ### Step 2: Initialize State Tracking (MANDATORY)
 
@@ -89,15 +101,39 @@ Create TaskCreate entries for all steps defined in the implementation plan. Step
 
 ### Step 4: Execute Steps via Agents
 
-For each step defined in the plan, follow this pattern:
+For each step (1 to total_steps from meta.md), follow this pattern:
+
+#### 4a. Load and Parse Step File
+
+For the current step number N:
+
+1. **Read step file:** `.5/{feature-name}/plan/step-{N}.md`
 
-#### 4a. Extract Step Block
+   **Error Handling:** If the step file is missing:
+   - Report error: "Error: Step {N} plan file not found at `.5/{feature-name}/plan/step-{N}.md`. Plan may be incomplete."
+   - Stop execution and escalate to user
 
-From the plan, extract the step block verbatim. The plan already contains the structured format that step-executor expects:
-- Step number, name, mode
-- Components with action, file, skill, depends_on, and complete prompt
+2. **Parse YAML frontmatter** (between `---` markers):
+   - Extract: `step`, `name`, `mode`, `components` (count)
 
-No transformation needed - the plan format matches the step-executor input contract.
+3. **Extract YAML components block:**
+   - Find the `## Components` section
+   - Extract the YAML block (between ` ```yaml` and ` ``` `)
+   - Parse the YAML to get the `components` array
+
+   **Error Handling:** If YAML parsing fails:
+   - Report error: "Error: Malformed step plan file at `.5/{feature-name}/plan/step-{N}.md`. Check YAML syntax in components block."
+   - Stop execution and escalate to user
+
+4. **Build step block object:**
+   ```yaml
+   step: {from frontmatter}
+   name: "{from frontmatter}"
+   mode: {from frontmatter}
+   components: {from YAML block}
+   ```
+
+This step block is now ready to pass to the step-executor agent (same format as before).
 
 #### 4b. Spawn step-executor Agent (haiku)
 
@@ -230,6 +266,12 @@ If a step-executor or step-verifier reports failure:
 
 3. **Spawn step-fixer agent** (sonnet) — read `.claude/agents/step-fixer.md` for agent instructions, then spawn via Task tool:
 
+   To retrieve the original component prompt:
+   - Read `.5/{feature-name}/plan/step-{N}.md`
+   - Parse the YAML components block
+   - Find the component by ID
+   - Extract the `prompt` field
+
    ```
    Task tool call:
      subagent_type: general-purpose
@@ -247,7 +289,7 @@ If a step-executor or step-verifier reports failure:
        Attempt: {M}
 
        Original Prompt:
-       {The component prompt from the plan that step-executor used}
+       {The component prompt extracted from plan/step-{N}.md}
 
        Step Verifier Output:
        {Complete output from step-verifier}
@@ -330,7 +372,9 @@ Tell the developer:
 3. "Compilation: Successful"
 4. "Tests: All passing ({N} tests)"
 5. **"State file: `.5/{feature-name}/state.json`"** (this is critical for resume capability)
-6. "Next step: Run `/verify-implementation` to validate completeness"
+6. "Next steps:"
+   - "Run `/clear` to reset context"
+   - "Then run `/5:verify-implementation {feature-name}` to validate completeness"
 
 **Note:** The verification step will automatically prompt the developer to commit changes, which is recommended before running CodeRabbit review.
 
@@ -423,17 +467,19 @@ User: /implement-feature PROJ-1234-add-emergency-schedule
 
 ## Instructions Summary
 
-1. **Load implementation plan** from `.5/{feature-name}/plan.md`
+1. **Load implementation plan metadata** from `.5/{feature-name}/plan/meta.md` - parse YAML frontmatter for total_steps, total_components
 2. **Initialize state file** (MANDATORY) in `.5/{feature-name}/state.json` - verify creation
 3. **Create tasks** for all steps defined in the plan
-4. **For each step:**
-   - Spawn step-executor
+4. **For each step (1 to total_steps):**
+   - Load and parse step file: `.5/{feature-name}/plan/step-{N}.md` (parse YAML frontmatter + components block)
+   - Build step block object from parsed data
+   - Spawn step-executor with step block
    - Process results
    - Spawn step-verifier
    - Process results
    - **Update state file** (MANDATORY - Step 4f) - verify update
 5. **For final integration step (if configured):** Spawn integration-agent, process results, **update state file** (MANDATORY)
-6. **Handle failures** - record in state file (MANDATORY), spawn step-fixer to diagnose and fix, re-verify after fix, escalate if stuck
+6. **Handle failures** - record in state file (MANDATORY), extract original prompt from plan/step-{N}.md, spawn step-fixer to diagnose and fix, re-verify after fix, escalate if stuck
 7. **Monitor context** - warn at 50%, stop at 80%
 8. **Update state file to completed** (MANDATORY - Step 8) - verify final update
 9. **Report completion** with summary including state file location

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

@@ -212,7 +212,9 @@ Write a comprehensive feature spec to `.5/{TICKET-ID}-{description}/feature.md`
 ...
 
 ## Next Steps
-After approval, run: `/plan-implementation {TICKET-ID}-{description}`
+After approval:
+1. Run `/clear` to reset context
+2. Run `/5:plan-implementation {TICKET-ID}-{description}`
 ```
 
 ## Instructions
@@ -277,8 +279,8 @@ After approval, run: `/plan-implementation {TICKET-ID}-{description}`
 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. Please review and then run `/plan-implementation PROJ-1234-add-emergency-schedule`"
-11. Skill tells user: "If the feature needs refinements, run `/discuss-feature PROJ-1234-add-emergency-schedule`"
+10. Skill tells user: "Feature spec created. Please review and then run `/clear` followed by `/5:plan-implementation PROJ-1234-add-emergency-schedule`"
+11. Skill tells user: "If the feature needs refinements, run `/5:discuss-feature PROJ-1234-add-emergency-schedule`"
 
 ## Related Documentation
 

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

@@ -116,82 +116,142 @@ Group components by dependencies:
 
 ### Step 7: Write Implementation Plan
 
-Write the plan to `.5/{feature-name}/plan.md` using this exact format:
+Create the plan directory `.5/{feature-name}/plan/` and write atomic plan files:
 
-```markdown
-# Plan: {TICKET-ID} - {Title}
+#### 7a. Create plan directory
+
+Use Bash to create the directory:
+```bash
+mkdir -p .5/{feature-name}/plan
+```
+
+#### 7b. Write plan/meta.md
+
+Write metadata file using this format:
 
-## Meta
+```markdown
+---
 feature: {feature-name}
 ticket: {ticket-id}
 total_steps: {N}
 total_components: {N}
 new_files: {N}
 modified_files: {N}
+created_at: {ISO timestamp}
+format_version: "2.0"
+---
 
-## Summary
-{1-2 sentences: what this plan builds and why}
+# Plan Metadata: {TICKET-ID} - {Title}
 
-## Steps
+{1-2 sentence summary of what this plan builds}
 
-### step: 1
-name: "{descriptive name}"
-mode: parallel | sequential
+## Steps Overview
+- Step 1: {Name} ({N} components)
+- Step 2: {Name} ({N} components)
+- Step N: {Name} ({N} components)
 
-#### component: {component-id}
-action: create | modify
-file: "{exact/path/to/file.ext}"
-skill: "{skill-name}" | null
-depends_on: []
-prompt: |
-  {Complete, self-contained execution instructions.
-  For create: include full file content or reference snippet + modifications.
-  For modify: include exact old_string and new_string.
-  Include all imports. Include all types.
-  This prompt is passed directly to a haiku agent that cannot explore the codebase.}
-
-#### component: {component-id-2}
-action: create | modify
-file: "{exact/path/to/file.ext}"
-skill: "{skill-name}" | null
-depends_on: []
-prompt: |
-  {Complete instructions}
+## Risks
+- {risk 1}: {mitigation}
+- {risk 2}: {mitigation}
+```
+
+#### 7c. Write plan/step-N.md files (one per step)
 
-### step: 2
-name: "{descriptive name}"
+For each step, create a separate file `plan/step-{N}.md` using this format:
+
+```markdown
+---
+step: {N}
+feature: {feature-name}
+name: "{Step Name}"
 mode: parallel | sequential
+components: {N}
+---
 
-#### component: {component-id-3}
-action: create | modify
-file: "{exact/path/to/file.ext}"
-skill: null
-depends_on: ["{component-id}", "{component-id-2}"]
-prompt: |
-  {Complete instructions}
+# Step {N}: {Step Name}
+
+{Brief description of what this step accomplishes}
+
+## Components
+
+```yaml
+components:
+  - id: {component-id}
+    action: create | modify
+    file: "{exact/path/to/file.ext}"
+    skill: "{skill-name}" | null
+    depends_on: []
+    prompt: |
+      {Complete, self-contained execution instructions.
+
+      For create: include full file content or reference snippet.
+      For modify: include exact old_string and new_string.
+      Include all imports, types, and context.}
+
+  - id: {component-id-2}
+    action: create | modify
+    file: "{exact/path/to/file.ext}"
+    skill: "{skill-name}" | null
+    depends_on: ["{component-id}"]
+    prompt: |
+      {Complete instructions}
+```
+
+## Expected Outputs
+**Files Created:**
+- {path1}
+- {path2}
+
+**Files Modified:**
+- {path3}
+
+## Verification Targets
+**Build Targets:**
+- {module1}
+- {module2}
+
+**Test Targets:**
+- {test-module-1}
+```
+
+**Important:** Use YAML block within Markdown for components. This provides easy parsing while maintaining readability.
+
+#### 7d. Write plan/verification.md
+
+Write verification configuration file:
+
+```markdown
+# Verification Configuration
 
-## Verification
 build_command: "{from config}"
 test_command: "{from config}"
-expected_new_files:
-  - "{path1}"
-  - "{path2}"
-expected_modified_files:
-  - "{path3}"
 
-## Risks
-- "{risk 1}: {mitigation}"
-- "{risk 2}: {mitigation}"
+## Expected New Files
+- {path1}
+- {path2}
+
+## Expected Modified Files
+- {path3}
+- {path4}
+
+## Build Targets
+- {module1}
+- {module2}
+
+## Test Modules
+- {test-module-1}
 ```
 
 ### Step 8: Inform Developer
 
 After creating the implementation plan, tell the developer:
 
-1. "Implementation plan created at `.5/{feature-name}/plan.md`"
+1. "Implementation plan created at `.5/{feature-name}/plan/`"
 2. "{N} components across {M} steps"
-3. "Each component has a self-contained execution prompt for haiku agents"
-4. "Please review, then run: `/5:implement-feature {feature-name}`"
+3. "Atomic plan structure: meta.md, step-1.md, step-2.md, ..., verification.md"
+4. "Each component has a self-contained execution prompt for haiku agents"
+5. "Please review the plan files"
+6. "Then run `/clear` followed by `/5:implement-feature {feature-name}`"
 
 ## Component Prompt Examples
 
@@ -367,8 +427,11 @@ Skill:
 5. Maps components to skills (or null for direct execution)
 6. Groups into steps by dependencies
 7. Builds self-contained prompts with inline code and exact paths
-8. Creates .5/PROJ-1234-add-emergency-schedule/plan.md
-9. Tells user: "Plan created with 7 components across 3 steps. Review and run /5:implement-feature"
+8. Creates .5/PROJ-1234-add-emergency-schedule/plan/ directory
+9. Writes plan/meta.md with metadata and risks
+10. Writes plan/step-1.md, plan/step-2.md, plan/step-3.md with YAML components
+11. Writes plan/verification.md with build/test config
+12. Tells user: "Plan created with 7 components across 3 steps. Atomic plan structure at `.5/PROJ-1234-add-emergency-schedule/plan/`. Review the plan files, then run `/clear` followed by `/5:implement-feature PROJ-1234-add-emergency-schedule`"
 ```
 
 ## Related Documentation

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

@@ -236,6 +236,10 @@ Build: Success
 Tests: {Success | Skipped}
 
 State: .5/${feature_name}/state.json
+
+Next steps:
+- Review and commit changes
+- For a new task, run `/clear` before starting
 ```
 
 ## Skill Mappings

package/src/commands/5/review-code.md

@@ -557,10 +557,11 @@ Action: Please review the suggested fix manually.
 ```
 1. Make code changes
 2. Stage changes: git add .
-3. Run review: /review-code
-4. Address manual issues if needed
-5. Verify: /verify-implementation (if part of feature workflow)
+3. Run `/clear` to reset context
+4. Run review: /5:review-code
+5. Address manual issues if needed
 6. Commit: git commit -m "message"
+7. For next feature: Run `/clear` before starting /5:plan-feature
 ```
 
 ## Configuration