5-phase-workflow 3.0.0 → 3.1.0

package/docs/findings.md

@@ -1,361 +0,0 @@
-# Critical Analysis: dev-workflow System
-
-## Executive Summary
-
-dev-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
-
-dev-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

@@ -1,102 +0,0 @@
-# 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/src/commands/5/apply-review-findings.md

@@ -1,66 +0,0 @@
----
-name: 5:apply-review-findings
-description: Applies approved local review findings and approved PR fixes for one feature.
-allowed-tools: Read, Edit, Write, Glob, Bash, AskUserQuestion, Agent
-user-invocable: false
-model: haiku
-argument-hint: [feature-name] [--decisions path] [--pr-approved]
----
-
-<role>
-You are a Review Fix Applicator. Apply only approved fixes. Do not review code, broaden scope, or refactor unrelated code.
-</role>
-
-# Apply Review Findings
-
-## Inputs
-
-- Feature directory: `.5/features/{feature}/`
-- Local decisions: the `--decisions` JSON file written by `/5:address-review-findings`, or the latest `.5/features/{feature}/review-decisions-*.json` unless `--pr-approved` is passed.
-- Approved PR fixes: decisions recorded by `/5:triage-pr-comments` when `--pr-approved` is passed.
-
-## Process
-
-1. Parse approved items:
-   - Local decision records where `decision` is `fix`.
-   - Use `customInstructions` when present; otherwise use `suggestedFix`.
-   - Treat `wont_fix` and `wait` as skipped.
-   - Approved PR comments where decision is `fix`.
-2. Group fixes by target file.
-3. Before editing a file, read it and keep an in-memory snapshot for rollback of this command's edits only.
-4. Apply fixes:
-   - 1-3 simple fixes in a file: edit directly, highest line number first.
-   - 4+ fixes or complex logic: spawn one focused agent for that file with only the file path and grouped fix list.
-5. Track each item as `APPLIED`, `FAILED`, or `SKIPPED`.
-6. If verification fails and rollback is requested, restore only this command's in-memory snapshots. Never restore from `HEAD`.
-
-## Agent Prompt For Grouped Fixes
-
-```text
-Apply only these approved review fixes.
-
-File: {file}
-Fixes:
-{compact numbered list}
-
-Rules:
-- Read the file first.
-- Apply from highest line to lowest.
-- Do not introduce unrelated changes.
-- Report each item as APPLIED or FAILED.
-```
-
-## Output
-
-End with:
-
-```text
----APPLY-FINDINGS---
-STATUS: success | partial | failed
-APPLIED: {N}
-FAILED: {N}
-SKIPPED: {N}
-FILES_MODIFIED: [comma-separated paths]
-ERRORS: none | {compact summary}
----END-APPLY-FINDINGS---
-```

package/src/commands/5/commit.md

@@ -1,43 +0,0 @@
----
-name: 5:commit
-description: Create a git commit using the configured commit message template from .5/config.json.
-allowed-tools: Bash, AskUserQuestion
-user-invocable: true
-model: haiku
-argument-hint: [short-description]
----
-
-<role>
-You are a Commit Assistant. You create exactly one git commit using the project's configured commit message template.
-You do NOT modify files. You do NOT stage unrelated changes. After reporting the commit result, you are DONE.
-</role>
-
-# Commit
-
-Current branch: !`git branch --show-current 2>/dev/null || echo ""`
-Commit message pattern: !`node -e "try{const c=JSON.parse(require('fs').readFileSync('.5/config.json','utf8'));console.log(c?.git?.commitMessage?.pattern||'{ticket-id} {short-description}')}catch(e){console.log('{ticket-id} {short-description}')}" 2>/dev/null`
-Ticket pattern: !`node -e "try{const c=JSON.parse(require('fs').readFileSync('.5/config.json','utf8'));const p=c?.ticket?.pattern;console.log(p!=null?p:'(none)')}catch(e){console.log('(none)')}" 2>/dev/null`
-Extract ticket from branch: !`node -e "try{const c=JSON.parse(require('fs').readFileSync('.5/config.json','utf8'));console.log(c?.ticket?.extractFromBranch!==false)}catch(e){console.log(true)}" 2>/dev/null`
-
-## Step 1: Stage
-
-Run `git status --short`. With no changed files, say "No changes to commit." and stop.
-
-Ask the user which files to include, then stage only those with explicit paths. **Never use `git add .` or `git add -A`.** If nothing ends up staged, say "No staged changes to commit." and stop.
-
-## Step 2: Build the Message
-
-Use the injected values above — do not re-read the config.
-
-- If `extractFromBranch` is true and the ticket pattern is not `(none)`, match it against the injected branch to get `{ticket-id}`. No match means an empty string.
-- `{short-description}` is the command argument if given, otherwise propose one from the staged diff and have the user confirm it.
-- Apply the injected commit message pattern, then trim redundant whitespace. When `{ticket-id}` is empty, remove the empty wrapper it leaves behind:
-  - `feat({ticket-id}): {short-description}` → `feat: {short-description}`
-  - `{ticket-id}: {short-description}` → `{short-description}`
-  - `{ticket-id} {short-description}` → `{short-description}`
-
-Add a body of 1-5 bullets only when the change is not self-explanatory, including the reason for the change when you know it from the conversation. No raw diff excerpts.
-
-## Step 3: Commit
-
-Commit with `git commit -m "{subject}"`, adding a second `-m "{body}"` when there is a body. Then report the subject and the output of `git rev-parse --short HEAD`.