5-phase-workflow 1.1.1 → 1.2.0

package/README.md

@@ -67,6 +67,8 @@ Then start your first feature:
 /5:review-code
 ```
 
+**Tip:** Running `/clear` between phases resets context and keeps conversations focused. Each phase reads necessary artifacts from previous phases, so no context is lost.
+
 ## Supported Tech Stacks
 
 The workflow auto-detects and supports:
@@ -230,12 +232,6 @@ After installation, your `.claude/` directory will contain:
 │   ├── discuss-feature.md
 │   ├── quick-implement.md
 │   └── configure.md
-├── agents/                   # Specialized agents
-│   ├── step-executor.md
-│   ├── step-verifier.md
-│   ├── integration-agent.md
-│   ├── verification-agent.md
-│   └── review-processor.md
 ├── skills/                   # Atomic operations
 │   ├── build-project/
 │   ├── run-tests/
@@ -368,11 +364,6 @@ When adding new commands, agents, skills, hooks, or templates:
 
 See `CLAUDE.md` for detailed development guidelines.
 
-## Contributing
-
-Found a bug or have a suggestion? Please open an issue or PR at:
-https://github.com/anthropics/claude-code/issues
-
 ## License
 
 MIT
@@ -381,8 +372,3 @@ MIT
 
 - [Full Workflow Guide](./docs/workflow-guide.md) - Detailed documentation
 - [Claude Code Docs](https://docs.anthropic.com/claude/docs/claude-code) - Claude Code features
-- [Examples](./docs/examples/) - Real-world usage examples
-
-## Credits
-
-Built with [Claude Code](https://claude.com/claude-code) by Anthropic.

package/bin/install.js

@@ -199,15 +199,8 @@ function getWorkflowManagedFiles() {
     // Commands: only the 5/ namespace
     commands: ['5'],
 
-    // Agents: specific agent files
-    agents: [
-      'step-executor.md',
-      'step-verifier.md',
-      'integration-agent.md',
-      'verification-agent.md',
-      'review-processor.md',
-      'step-fixer.md'
-    ],
+    // Agents: none - instructions are now embedded inline in commands
+    agents: [],
 
     // Skills: specific skill directories
     skills: [
@@ -225,13 +218,23 @@ function getWorkflowManagedFiles() {
 
     // Templates: specific template files
     templates: [
+      // Project documentation templates
       'ARCHITECTURE.md',
       'CONCERNS.md',
       'CONVENTIONS.md',
       'INTEGRATIONS.md',
       'STACK.md',
       'STRUCTURE.md',
-      'TESTING.md'
+      'TESTING.md',
+      // Workflow output templates
+      'workflow/FEATURE-SPEC.md',
+      'workflow/PLAN.md',
+      'workflow/STATE.json',
+      'workflow/VERIFICATION-REPORT.md',
+      'workflow/REVIEW-FINDINGS.md',
+      'workflow/REVIEW-SUMMARY.md',
+      'workflow/QUICK-PLAN.md',
+      'workflow/FIX-PLAN.md'
     ]
   };
 }
@@ -299,7 +302,7 @@ function selectiveUpdate(targetPath, sourcePath) {
   }
   log.success('Updated hooks/ (workflow files only)');
 
-  // Update specific templates
+  // Update specific templates (including nested directories like workflow/)
   const templatesSrc = path.join(sourcePath, 'templates');
   const templatesDest = path.join(targetPath, 'templates');
   if (!fs.existsSync(templatesDest)) {
@@ -309,6 +312,11 @@ function selectiveUpdate(targetPath, sourcePath) {
     const src = path.join(templatesSrc, template);
     const dest = path.join(templatesDest, template);
     if (fs.existsSync(src)) {
+      // Ensure parent directory exists for nested paths (e.g., workflow/FEATURE-SPEC.md)
+      const destDir = path.dirname(dest);
+      if (!fs.existsSync(destDir)) {
+        fs.mkdirSync(destDir, { recursive: true });
+      }
       fs.copyFileSync(src, dest);
     }
   }
@@ -365,7 +373,7 @@ function getDefaultConfig(projectType) {
       command: 'auto',
       testCommand: 'auto'
     },
-    reviewTool: 'auto'
+    reviewTool: 'claude'
   };
 
   // Project-specific overrides

package/docs/findings.md

@@ -0,0 +1,361 @@
+# Critical Analysis: 5-Phase Workflow System
+
+## Executive Summary
+
+The 5-Phase Workflow is an ambitious, well-intentioned system for structured AI-assisted feature development. While it demonstrates sophisticated architectural thinking, it suffers from significant over-engineering and complexity that may undermine its practical utility. This analysis identifies strengths, weaknesses, and concrete opportunities for improvement.
+
+---
+
+## Strengths
+
+### 1. Sound Architectural Foundation
+The 4-layer architecture (Commands → Agents → Skills → Tools) is a solid design:
+- **Clear separation of concerns**: Commands orchestrate, agents execute, skills encapsulate
+- **Token efficiency**: Haiku model for executors, forked contexts for heavy work
+- **Modularity**: Each layer can be modified independently
+
+### 2. State Tracking and Resumability
+The state file system (`state.json`) enables:
+- Resuming interrupted work across sessions
+- Debugging by inspecting progress
+- Clear audit trail of what was completed
+
+### 3. Selective Update System
+The `getWorkflowManagedFiles()` approach in the installer:
+- Preserves user-created content during upgrades
+- Allows customization without fear of losing changes
+- Deep merge for settings.json maintains user preferences
+
+### 4. Clear Scope Boundaries
+Each phase has explicit boundaries with "DO NOT" sections:
+- Prevents scope creep during execution
+- Makes behavior predictable
+- Reduces chance of phases interfering with each other
+
+### 5. Good Documentation Discipline
+- Each file has clear purpose and input/output contracts
+- Examples are provided in most commands
+- Related documentation is cross-referenced
+
+---
+
+## Criticisms and Issues
+
+### 1. Excessive Complexity and Over-Engineering
+
+**Phase 2 (`plan-implementation.md`) is 400+ lines of instructions.**
+
+This phase requires:
+- Reading feature spec
+- Deep codebase analysis
+- Asking 3-5 technical questions
+- Mapping components to skills
+- Determining dependency steps
+- Building "haiku-ready prompts" with complete code
+- Writing meta.md, step-N.md files, verification.md
+
+For a system designed to help developers, Phase 2 demands more effort to create "AI-executable prompts" than it would take to just implement the feature manually.
+
+**The "Haiku-Ready Prompts" Concept is Impractical**
+
+The plan-implementation phase must create prompts containing:
+- Complete file content to write
+- All import statements
+- All type definitions
+- Exact `old_string` and `new_string` for modifications
+
+This essentially means writing the code twice - once in the prompt, then the agent copies it to a file. The value proposition is unclear.
+
+### 2. Redundant Work and Token Waste
+
+**Commands re-read files that agents will also read:**
+- `implement-feature` reads `plan/meta.md`, then spawns agents that read the same files
+- `verify-implementation` aggregates expected files, then agents parse the same plan files again
+- Agent instructions (`.claude/agents/*.md`) are read fresh for every agent spawn
+
+**Template References Without Actual Use:**
+- Commands say "Use the structure from `.claude/templates/workflow/FEATURE-SPEC.md`"
+- But agents never actually load these templates - they're just prose descriptions
+- These templates add confusion about what format to use
+
+**Verification Agent Duplicates Parent Work:**
+```markdown
+# From verification-agent.md
+## Process
+### 0. Parse Implementation Plan
+Read the implementation plan from the provided path...
+```
+The verify-implementation command already parsed this and passed it to the agent. Why parse again?
+
+### 3. Inconsistent Token Efficiency Claims
+
+The system claims to be designed for token efficiency, but:
+
+**Context monitoring is aspirational, not real:**
+```markdown
+### Step 7: Monitor Context Usage
+After each step, estimate context usage:
+- Warn developer at 50% usage
+- Stop at 80% usage
+```
+There's no actual mechanism to measure context usage. This is theater.
+
+**Agents load large instructions unnecessarily:**
+- step-executor.md: 110 lines of instructions for what could be 30 lines
+- verification-agent.md: 446 lines when verification could be much simpler
+
+### 4. Fragile Design Assumptions
+
+**YAML Parsing Requirements Are Error-Prone:**
+
+Step files require parsing:
+1. YAML frontmatter (between `---` markers)
+2. YAML block (between ` ```yaml` and ` ``` `)
+3. Markdown sections for expected outputs
+
+Any formatting error breaks the entire system. LLMs generating YAML are notoriously unreliable.
+
+**Ticket ID Extraction Assumes Branch Naming:**
+```markdown
+Branch format: `{TICKET-ID}-description` (ticket is prefix)
+```
+Many teams don't follow this convention. The fallback of "ask the developer" is weak.
+
+**CodeRabbit Dependency in Phase 5:**
+Phase 5 requires CodeRabbit CLI to be installed and authenticated. If it's not available, Phase 5 is useless.
+
+### 5. User Experience Issues
+
+**Mandatory `/clear` Between Phases:**
+```markdown
+Run `/clear` followed by `/5:implement-feature {feature-name}`
+```
+This friction adds nothing and breaks flow. If context management is the concern, handle it automatically.
+
+**Excessive "CRITICAL" and "MANDATORY" Warnings:**
+The documentation is filled with shouty warnings:
+- "⚠️ CRITICAL SCOPE CONSTRAINT"
+- "**CRITICAL**: You MUST create the state file"
+- "🛑 STOP HERE. YOUR JOB IS COMPLETE."
+
+This reads as defensive documentation rather than helpful guidance.
+
+**No Flexibility or Customization:**
+- Can't skip phases
+- Can't customize the 5-phase flow
+- Can't choose which agents to use
+- Must follow the rigid structure even for simple features
+
+### 6. The Quick-Implement Escape Hatch Isn't Enough
+
+`quick-implement` exists for "1-5 files" but still requires:
+- State file initialization
+- Plan creation
+- Plan approval
+- Skill mappings
+- State updates after each component
+- Verification
+
+For a "quick" path, this is still heavyweight.
+
+---
+
+## What Doesn't Work Well
+
+### 1. Project Type Detection
+The detection in `bin/install.js` is basic:
+```javascript
+if (pkg.dependencies?.['next']) return 'nextjs';
+if (pkg.dependencies?.['express']) return 'express';
+```
+- Misses monorepos with multiple project types
+- Doesn't handle mixed stacks (Next.js + Express in same repo)
+- No way to specify project type manually during install
+
+### 2. Build Command Assumptions
+Default commands like:
+```javascript
+'gradle-java': {
+  build: { command: './gradlew build -x test -x javadoc --offline' }
+}
+```
+- `--offline` fails if dependencies aren't cached
+- No awareness of CI vs local environments
+- No incremental build support
+
+### 3. Agent Model Selection
+```markdown
+model: haiku
+```
+Haiku is specified for step-executor, but:
+- Haiku may not exist or be available to all users
+- No fallback if haiku fails
+- No ability to override per-project
+
+### 4. The Atomic Plan Structure Creates File Sprawl
+A single feature creates:
+```
+.5/{feature-name}/
+├── feature.md
+├── state.json
+├── verification.md
+└── plan/
+    ├── meta.md
+    ├── step-1.md
+    ├── step-2.md
+    ├── step-3.md
+    └── verification.md
+```
+For a 7-component feature, you have 8+ files just for planning/state.
+
+---
+
+## Token Usage Improvements
+
+### 1. Embed Agent Instructions Instead of Reading Files
+Instead of:
+```markdown
+Read `.claude/agents/step-executor.md` for agent instructions, then spawn...
+```
+Embed the essential instructions directly in the Task prompt. Agent files are ~100-400 lines when 20-30 lines would suffice.
+
+### 2. Don't Parse the Same Files Multiple Times
+The parent command should do all parsing and pass structured data to agents:
+```yaml
+# Good: Parent passes structured data
+components:
+  - id: schedule-service
+    action: create
+    file: src/services/ScheduleService.ts
+    content: |
+      // Complete file content here
+
+# Bad: Agent re-parses plan files
+```
+
+### 3. Lazy Load Step Files
+Don't load all step files upfront. Load only the current step when executing.
+
+### 4. Simplify Verification
+Instead of a 446-line verification agent:
+1. Check files exist (Glob)
+2. Run build command
+3. Run test command
+4. Report results
+
+That's 4 steps, not 8 elaborate sections.
+
+### 5. Remove Template Reference Indirection
+Either:
+- Make templates actual template files that get loaded and filled
+- Or remove template references and inline the expected format
+
+---
+
+## Performance Improvements
+
+### 1. Parallel Execution by Default
+The system has `mode: parallel | sequential` but defaults to being conservative. Many steps could run in parallel.
+
+### 2. Incremental Verification
+After implementing Step 2, don't rebuild everything from Step 1. Build only affected modules.
+
+### 3. Cache Build Results
+If build passed in step-verifier, don't rebuild in verification-agent.
+
+### 4. Skip Redundant Agent Spawns
+If step-executor reports success with no issues, skip step-verifier.
+
+---
+
+## Simplification Opportunities
+
+### 1. Collapse Agents
+**Current:** step-executor → step-verifier → (on failure) step-fixer
+**Simpler:** step-executor with built-in verification and retry
+
+### 2. Remove Mandatory 5-Phase Constraint
+Let users:
+- Run just Phase 1 for spec creation
+- Skip directly to implementation if they have a clear plan
+- Skip code review if not using CodeRabbit
+
+### 3. Simplify State File
+Current state file has:
+- ticketId, featureName, phase, status, currentStep, totalSteps
+- completedComponents (array of objects)
+- pendingComponents (array of objects)
+- failedAttempts (array of objects)
+- verificationResults (object)
+- contextUsage, contextWarningIssued
+- startedAt, lastUpdated, completedAt
+
+Simpler version:
+```json
+{
+  "step": 2,
+  "completed": ["component-1", "component-2"],
+  "failed": ["component-3"],
+  "timestamp": "2026-01-28T10:30:00Z"
+}
+```
+
+### 4. Merge Plan Files
+Instead of meta.md + step-1.md + step-2.md + verification.md:
+One `plan.yaml` file:
+```yaml
+feature: add-emergency-schedule
+ticket: PROJ-1234
+steps:
+  - name: Foundation
+    components:
+      - id: schedule-model
+        file: src/models/Schedule.ts
+        prompt: |
+          Create file with this content...
+verification:
+  build: npm run build
+  test: npm test
+```
+
+### 5. Make Skills Optional
+Current: Skills are assumed to exist and match project patterns
+Better: If no matching skill, use direct Write/Edit with the prompt
+
+---
+
+## Recommendations Summary
+
+| Priority | Recommendation | Impact |
+|----------|---------------|--------|
+| High | Simplify Phase 2 prompt generation - don't require complete code | Major UX improvement |
+| High | Embed agent instructions inline instead of reading files | Token savings |
+| High | Remove mandatory `/clear` between phases | UX improvement |
+| High | Merge plan files into single YAML | Reduce file sprawl |
+| Medium | Add `--skip-phase` flags | Flexibility |
+| Medium | Make CodeRabbit optional in Phase 5 | Broader adoption |
+| Medium | Collapse step-executor + step-verifier | Simpler flow |
+| Medium | Implement actual context monitoring | Deliver on promise |
+| Low | Improve project type detection | Edge case handling |
+| Low | Add incremental verification | Performance |
+
+---
+
+## Conclusion
+
+The 5-Phase Workflow demonstrates thoughtful design around token efficiency, state management, and separation of concerns. However, it has evolved into an over-engineered system that creates more friction than it removes.
+
+The core insight - that AI-assisted development benefits from structured phases - is valid. But the implementation has become so complex that:
+
+1. Phase 2 requires as much effort as manual implementation
+2. The rigid 5-phase structure doesn't match real-world workflows
+3. Token efficiency claims are undermined by redundant file reading
+4. The system creates significant file overhead for tracking
+
+**The fundamental question to answer:** Is the overhead of learning and using this workflow justified by the benefits?
+
+For simple features (1-5 files): No. `quick-implement` still has too much ceremony.
+
+For complex features (10+ files): Possibly, but Phase 2's requirement to write "haiku-ready prompts" with complete code makes the planning phase as expensive as implementation.
+
+**The path forward** is simplification: fewer files, fewer phases, less ceremony, and letting the AI do more of the work rather than requiring developers to pre-compute everything in Phase 2.

package/docs/progress.md

@@ -0,0 +1,102 @@
+# Simplification Progress Tracker
+
+Tracking improvements based on `findings.md` analysis.
+
+---
+
+## Completed
+
+### 1. Merged Plan Files into Single Format
+- **Before:** `meta.md` + `step-1.md` + `step-2.md` + `verification.md` (8+ files per feature)
+- **After:** Single `plan.md` with YAML frontmatter + markdown table
+- **Commit:** b26aff7
+
+### 2. Removed "Haiku-Ready Prompts" Requirement
+- **Before:** Phase 2 required complete code in prompts (writing code twice)
+- **After:** Plan describes WHAT to build; agents figure out HOW
+- **Evidence:** plan-implementation.md lines 208-209 explicitly forbid this
+- **Commit:** b26aff7
+
+### 3. Consolidated Agents (6 → 2)
+- **Removed:** step-verifier.md (126 lines), step-fixer.md (133 lines), integration-agent.md (220 lines), verification-agent.md (446 lines)
+- **Remaining at that point:** step-executor.md (75 lines), review-processor.md (161 lines)
+- **Commit:** b26aff7
+
+### 4. Simplified plan-implementation.md
+- **Before:** 457 lines
+- **After:** 213 lines (53% reduction)
+- **Commit:** b26aff7
+
+### 5. Simplified step-executor.md
+- **Before:** 118 lines
+- **After:** 75 lines (36% reduction)
+- **Commit:** b26aff7
+
+### 6. Simplified verify-implementation.md
+- **Before:** 446 lines (via verification-agent.md)
+- **After:** 138 lines, handles verification directly
+- **Commit:** b26aff7
+
+### 7. Removed Mandatory `/clear` Between Phases
+- **Before:** Required `/clear` before each phase command
+- **After:** No longer required
+- **Commit:** b26aff7
+
+### 8. Simplified State File Format
+- **Before:** 10+ fields including contextUsage tracking
+- **After:** 7 essential fields (ticket, feature, status, currentStep, completed, failed, startedAt)
+- **Commit:** b26aff7
+
+### 9. Added Parallel Component Execution
+- **Before:** Sequential execution only
+- **After:** Components within same step run in parallel
+- **Commit:** 9106b6a
+
+### 10. Removed Template Indirection for Workflows
+- **Before:** Commands referenced templates that were never loaded
+- **After:** Clean workflow templates in src/templates/workflow/
+- **Commit:** 027faa2, b26aff7
+
+### 11. Embedded Agent Instructions Inline (2 → 0 agent files)
+- **Before:** Commands read separate agent .md files on every spawn (step-executor.md, review-processor.md)
+- **After:** Instructions embedded directly in Task prompts within commands
+- **Files removed:** `src/agents/step-executor.md`, `src/agents/review-processor.md`
+- **Updated commands:** `quick-implement.md`, `review-code.md`
+- **Token savings:** ~236 lines of agent instructions no longer read on each spawn
+
+---
+
+## Remaining (Not Yet Done)
+
+### Medium Priority
+
+| Item | Finding | Current State |
+|------|---------|---------------|
+| Add `--skip-phase` flags | Rigid 5-phase structure | No skip logic implemented |
+| Make CodeRabbit truly optional | Phase 5 centered on CodeRabbit | Still somewhat required |
+
+### Low Priority
+
+| Item | Finding | Current State |
+|------|---------|---------------|
+| Implement actual context monitoring | "Monitor at 50%" is aspirational | No real mechanism |
+| Incremental verification | Full rebuild each step | Runs full build/test |
+| Improve project type detection | Basic dependency checks | Misses monorepos |
+
+---
+
+## Metrics Summary
+
+| Metric | Before | After | Change |
+|--------|--------|-------|--------|
+| plan-implementation.md | 457 lines | 213 lines | -53% |
+| Agent files | 6 | 0 | -100% |
+| Files per feature | 8+ | ~3 | -60% |
+| Parallel execution | No | Yes | Added |
+
+---
+
+## Next Steps
+
+1. **Add phase skip flags** - Allow `/5:implement-feature --skip-planning` for users with existing plans
+2. **Make CodeRabbit optional** - Phase 5 should work without CodeRabbit installed

package/docs/workflow-guide.md

@@ -541,7 +541,11 @@ Claude: What's the ticket ID for this feature?
 You: PROJ-1234
 
 Claude: Feature spec created at .5/PROJ-1234-add-user-profile/feature.md
-Please review and then run: /plan-implementation PROJ-1234-add-user-profile
+
+Next steps:
+1. Review the feature spec
+2. Run `/clear` to reset context (recommended between phases)
+3. Then run `/5:plan-implementation PROJ-1234-add-user-profile`
 ```
 
 ### Step 2: Review Feature Spec
@@ -552,11 +556,14 @@ Open `.5/PROJ-1234-add-user-profile/feature.md` and review:
 - Acceptance criteria verifiable?
 - Alternatives make sense?
 
-If satisfied, proceed to next phase.
+If satisfied, clear context and proceed to next phase.
 
-### Step 3: Start Implementation Planning
+### Step 3: Clear Context and Start Implementation Planning
 
 ```bash
+You: /clear
+[Context cleared]
+
 You: /plan-implementation PROJ-1234-add-user-profile
 
 Claude: Reading feature spec...
@@ -591,12 +598,17 @@ Step 1 (Foundation): User model update, ProfileValidator
 Step 2 (Logic): ProfileService with business logic
 Step 3 (Integration): API route registration, tests
 
-Please review the plan files and then run: /implement-feature PROJ-1234-add-user-profile
+Review the plan, then:
+1. Run `/clear` to reset context (recommended between phases)
+2. Run `/5:implement-feature PROJ-1234-add-user-profile`
 ```
 
-### Step 4: Start Implementation (with Agents)
+### Step 4: Clear Context and Start Implementation (with Agents)
 
 ```bash
+You: /clear
+[Context cleared]
+
 You: /implement-feature PROJ-1234-add-user-profile
 
 Claude: Reading implementation plan...
@@ -629,11 +641,18 @@ Feature implementation complete!
 - All 4 components created/updated
 - State file updated
 - Ready for verification!
+
+Next steps:
+1. Run `/clear` to reset context (recommended between phases)
+2. Run `/5:verify-implementation PROJ-1234-add-user-profile`
 ```
 
-### Step 5: Verify Implementation
+### Step 5: Clear Context and Verify Implementation
 
 ```bash
+You: /clear
+[Context cleared]
+
 You: /verify-implementation
 
 Claude: Loading implementation state...
@@ -647,11 +666,18 @@ Claude: Loading implementation state...
 Verification Status: PASSED WITH WARNINGS
 
 Would you like to commit these changes now?
+
+Next steps:
+1. Run `/clear` to reset context (recommended between phases)
+2. Run `/5:review-code`
 ```
 
-### Step 6: Code Review
+### Step 6: Clear Context and Code Review
 
 ```bash
+You: /clear
+[Context cleared]
+
 You: /review-code
 
 Claude: Checking CodeRabbit CLI... installed
@@ -720,11 +746,12 @@ Tests: All passing
 
 ### General Tips
 
-1. **Use git branches**: Create feature branch before starting
-2. **Commit often**: Commit after Phase 3 completes successfully
-3. **Run verification manually**: Re-run /verify-implementation after fixes
-4. **Review state files**: Check `.5/{feature-name}/state.json` for progress tracking
-5. **Save verification reports**: Keep reports for documentation/debugging
+1. **Clear context between phases**: Run `/clear` before starting each new phase to reset context. This keeps conversations focused, prevents context pollution, and improves efficiency. Each phase reads necessary artifacts from previous phases.
+2. **Use git branches**: Create feature branch before starting
+3. **Commit often**: Commit after Phase 3 completes successfully
+4. **Run verification manually**: Re-run /verify-implementation after fixes
+5. **Review state files**: Check `.5/{feature-name}/state.json` for progress tracking
+6. **Save verification reports**: Keep reports for documentation/debugging
 
 ---
 

package/package.json

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