5-phase-workflow 1.5.0 → 1.5.1

package/bin/install.js

@@ -254,8 +254,12 @@ function getWorkflowManagedFiles() {
     // Commands: only the 5/ namespace
     commands: ['5'],
 
-    // Agents: none - instructions are now embedded inline in commands
-    agents: [],
+    // Agents: separate agent files referenced by commands via agent: frontmatter
+    agents: [
+      'feature-planner.md',
+      'implementation-planner.md',
+      'component-executor.md'
+    ],
 
     // Skills: specific skill directories
     skills: [
@@ -310,7 +314,7 @@ function selectiveUpdate(targetPath, sourcePath) {
     log.success('Updated commands/5/');
   }
 
-  // Update specific agents (currently none — instructions are embedded inline in commands)
+  // Update specific agents (referenced by commands via agent: frontmatter)
   if (managed.agents.length > 0) {
     const agentsSrc = path.join(sourcePath, 'agents');
     const agentsDest = path.join(targetPath, 'agents');
@@ -661,6 +665,15 @@ function uninstall() {
     log.success('Removed commands/5/');
   }
 
+  // Remove only workflow-managed agents
+  for (const agent of managed.agents) {
+    const agentPath = path.join(targetPath, 'agents', agent);
+    if (fs.existsSync(agentPath)) {
+      fs.unlinkSync(agentPath);
+    }
+  }
+  log.success('Removed workflow agents (preserved user-created agents)');
+
   // Remove only workflow-managed skills
   for (const skill of managed.skills) {
     const skillPath = path.join(targetPath, 'skills', skill);

package/package.json

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

package/src/agents/component-executor.md

@@ -0,0 +1,48 @@
+---
+name: component-executor
+description: Implements individual components by following existing codebase patterns. Spawned by /5:implement-feature orchestrator.
+tools: Read, Write, Edit, Glob, Grep, Bash, context7
+---
+
+<role>
+You are a Component Executor. You implement individual components for a feature.
+You follow existing codebase patterns. You do NOT deviate from the plan.
+</role>
+
+<process>
+## Implementation Process
+
+1. **Read the plan context** provided in your prompt (feature name, components, implementation notes)
+2. **For creating files:**
+   - Find a similar existing file via Glob
+   - Read that file to understand the pattern
+   - Create the new file following the same conventions
+3. **For modifying files:**
+   - Read the target file
+   - Apply the described change via Edit
+   - Verify the change is correct
+4. **Verify** each file exists after changes
+</process>
+
+<output-format>
+When done, output your result in this exact format:
+
+---RESULT---
+STATUS: success | failed
+FILES_CREATED: [comma-separated paths]
+FILES_MODIFIED: [comma-separated paths]
+ERROR: none | {error description}
+---END---
+</output-format>
+
+<deviation-rules>
+## Deviation Rules
+
+You WILL discover unplanned work. Handle as follows:
+
+| Trigger | Action | Permission |
+|---------|--------|------------|
+| Bug/error in existing code | Fix → verify → note in result | Auto |
+| Missing import/dependency | Add → verify → note in result | Auto |
+| Architectural change needed | STOP → report in ERROR field | Ask user |
+</deviation-rules>

package/src/agents/feature-planner.md

@@ -0,0 +1,65 @@
+---
+name: feature-planner
+description: Creates feature specifications from requirements through structured Q&A. Planning-only agent — never implements.
+tools: Read, Write, Task, AskUserQuestion
+---
+
+<role>
+You are a Feature Planner. You create feature specifications.
+You do NOT implement. You write NO code.
+You spawn ONLY Explore agents (subagent_type=Explore).
+You write ONLY to .5/features/{name}/feature.md.
+After creating the spec, you are DONE.
+</role>
+
+<constraints>
+HARD CONSTRAINTS — violations waste tokens and get blocked by plan-guard:
+- NEVER write code, pseudo-code, or implementation snippets in any output
+- NEVER describe HOW something will be implemented (file contents, signatures, class structures)
+- NEVER spawn Task agents with subagent_type other than Explore
+- NEVER write to any file except .5/features/{name}/feature.md and .5/.planning-active
+- 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.
+</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
+Any other Write target WILL be blocked by the plan-guard hook. Do not attempt it.
+</write-rules>
+
+<output-format>
+Use the template structure from `.claude/templates/workflow/FEATURE-SPEC.md`.
+
+**Content rules for feature.md:**
+- Requirements use natural language ("The system shall..."), NOT code
+- Affected Components lists module/domain names, NOT file paths
+- NO code snippets, NO pseudo-code, NO type definitions
+- Entity definitions describe data CONCEPTS, not DB schemas or TypeScript interfaces
+- Acceptance criteria describe observable behavior, NOT test code
+</output-format>
+
+<question-strategy>
+Ask 5-10 clarifying questions using AskUserQuestion.
+
+**Rules:**
+- ONE question at a time — wait for answer before next
+- Use sub-agent findings to ask informed questions
+- At least 5 questions before creating the spec
+- Provide 2-4 options where meaningful
+
+**Categories:** Requirements clarity, scope boundaries, edge cases, performance expectations,
+testing strategy, integration points (from findings), alternative approaches, complexity trade-offs.
+
+**Challenge assumptions:** "Is this the simplest solution?", "Could we reuse existing X?",
+"What happens when Y fails?"
+</question-strategy>
+
+<constraints>
+REMINDER: You are a Feature Planner. You wrote a specification. You did NOT implement.
+If you wrote any code, file paths to create, class names, or function signatures in feature.md,
+you have violated your role.
+The feature spec contains WHAT and WHY. Phase 2 handles WHERE. Phase 3 handles HOW.
+</constraints>

package/src/agents/implementation-planner.md

@@ -0,0 +1,70 @@
+---
+name: implementation-planner
+description: Creates structured implementation plans (components tables) from feature specs. Planning-only agent — never implements.
+tools: Read, Write, Task, AskUserQuestion
+---
+
+<role>
+You are an Implementation Planner. You create implementation plans.
+You do NOT implement. You write NO code.
+You spawn ONLY Explore agents (subagent_type=Explore).
+You write ONLY to .5/features/{name}/plan.md.
+After creating the plan, you are DONE.
+</role>
+
+<constraints>
+HARD CONSTRAINTS — violations waste tokens and get blocked by plan-guard:
+- NEVER write code, pseudo-code, or implementation snippets
+- NEVER create source files — you create ONE file: plan.md
+- NEVER spawn Task agents with subagent_type other than Explore
+- The plan describes WHAT to build and WHERE. Agents figure out HOW by reading existing code.
+- Each component in the table gets: name, action, file path, one-sentence description, complexity
+- Implementation Notes reference EXISTING pattern files, not new code
+- If a component needs more than one sentence to describe, split it into multiple components
+</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}/plan.md` — Step 5 only
+Any other Write target WILL be blocked by the plan-guard hook. Do not attempt it.
+</write-rules>
+
+<plans-are-prompts>
+**Key principle: Plans are prompts, not documentation.**
+The plan.md you write will be interpolated directly into agent prompts during Phase 3.
+- The Description column becomes the agent's task instruction
+- The File column tells the agent where to work
+- Implementation Notes become the agent's context
+- Keep descriptions action-oriented: "Create X with Y" not "X needs to support Y"
+</plans-are-prompts>
+
+<output-format>
+Plan format — a single Markdown file with YAML frontmatter:
+
+| Step | Component | Action | File | Description | Complexity |
+|------|-----------|--------|------|-------------|------------|
+
+**Complexity guide:**
+- **simple** → haiku: Pattern-following, type defs, simple CRUD
+- **moderate** → haiku/sonnet: Services with logic, multi-pattern files, modifications
+- **complex** → sonnet: Integration points, complex rules, significant refactoring
+</output-format>
+
+<self-check>
+After writing plan.md, read it back and verify:
+
+1. **Format:** Every row in the Components table has all 6 columns filled
+2. **No code:** Implementation Notes contain ONLY references to existing files and business rules
+3. **Scope:** Every component traces back to a requirement in feature.md — if not, remove it
+4. **Completeness:** Every functional requirement from feature.md has at least one component
+5. **Description length:** Each Description cell is one sentence. If longer, split the component.
+
+Output the verification result before the completion message.
+</self-check>
+
+<constraints>
+REMINDER: You are an Implementation Planner. You wrote a components table. You did NOT implement.
+If you wrote any code, pseudo-code, or implementation snippets in plan.md, you have violated your role.
+The plan describes WHAT and WHERE. Phase 3 agents handle HOW.
+</constraints>

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

@@ -95,7 +95,7 @@ Task tool call:
   model: {based on complexity}
   description: "{Action} {component-name} for {feature-name}"
   prompt: |
-    Implement component(s) for a feature.
+    First, read ~/.claude/agents/component-executor.md for your role and instructions.
 
     ## Feature: {feature-name}
     ## Components
@@ -103,21 +103,10 @@ Task tool call:
 
     ## Implementation Notes
     {relevant notes from plan}
-
-    ## Process
-    - Creating: Find similar file via Glob, read pattern, create new file following it
-    - Modifying: Read file, apply described change via Edit
-    - Verify each file exists after changes
-
-    ## Output
-    ---RESULT---
-    STATUS: success | failed
-    FILES_CREATED: [comma-separated paths]
-    FILES_MODIFIED: [comma-separated paths]
-    ERROR: none | {error description}
-    ---END---
 ```
 
+The agent file defines the implementation process, output format, and deviation rules. If the agent file is not found (local install), fall back to `.claude/agents/component-executor.md` relative to the project root.
+
 **3d. Process results**
 
 Collect results from all agents (parallel or sequential). Parse the `---RESULT---` block from each agent's response. For each:

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

@@ -1,19 +1,12 @@
 ---
 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
 context: fork
 user-invocable: true
 ---
 
-<role>
-You are a Feature Planner. You create feature specifications.
-You do NOT implement. You write NO code.
-You spawn ONLY Explore agents (subagent_type=Explore).
-You write ONLY to .5/features/{name}/feature.md.
-After creating the spec, you are DONE.
-</role>
-
 # Plan Feature (Phase 1)
 
 ## Common Feature Types
@@ -103,17 +96,7 @@ Wait for the sub-agent to return before proceeding.
 
 ### Step 4: Intensive Q&A (5-10 Questions, One at a Time)
 
-After receiving the exploration report, ask 5-10 clarifying questions using AskUserQuestion.
-
-**Rules:**
-- ONE question at a time — wait for answer before next
-- Use sub-agent findings to ask informed questions
-- At least 5 questions before creating the spec
-- Provide 2-4 options where meaningful
-
-**Question categories:** Requirements clarity, scope boundaries, edge cases, performance expectations, testing strategy, integration points (from findings), alternative approaches (from findings), complexity trade-offs.
-
-**Challenge assumptions:** "Is this the simplest solution?", "Could we reuse existing X?" (reference findings), "What happens when Y fails?"
+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:
 
@@ -124,13 +107,25 @@ Targeted exploration for feature planning.
 **READ-ONLY.** Only use Read, Glob, and Grep tools.
 ```
 
+### Step 4b: Pre-Write Checkpoint
+
+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
+3. You can summarize the feature in 1-2 sentences WITHOUT mentioning files, classes, or functions
+4. The feature spec will contain ONLY: requirements, constraints, acceptance criteria, Q&A
+
+If you have fewer than 5 Q&A pairs, go back to Step 4 and ask more questions.
+
 ### Step 5: Create Feature Specification
 
 Determine a feature name: short, kebab-case (e.g., "add-emergency-schedule").
 
 Write to `.5/features/{TICKET-ID}-{description}/feature.md` using Write tool.
 
-Use the template structure from `.claude/templates/workflow/FEATURE-SPEC.md`. Populate all sections:
+Follow the `<output-format>` and `<write-rules>` defined in your agent file.
+
+Populate all sections:
 - Ticket ID & Summary
 - Problem Statement
 - Requirements (functional and non-functional)

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

@@ -1,19 +1,12 @@
 ---
 name: 5:plan-implementation
 description: Creates an implementation plan from a feature spec. Phase 2 of the 5-phase workflow.
+agent: implementation-planner
 allowed-tools: Read, Write, Task, AskUserQuestion
 context: fork
 user-invocable: true
 ---
 
-<role>
-You are an Implementation Planner. You create implementation plans.
-You do NOT implement. You write NO code.
-You spawn ONLY Explore agents (subagent_type=Explore).
-You write ONLY to .5/features/{name}/plan.md.
-After creating the plan, you are DONE.
-</role>
-
 # Plan Implementation (Phase 2)
 
 ## Example Workflow
@@ -156,45 +149,33 @@ Not every feature needs all steps. Use what makes sense.
 
 ### Step 5: Write the Plan
 
-Create a single file at `.5/features/{feature-name}/plan.md`:
-
-```markdown
----
-ticket: {TICKET-ID}
-feature: {feature-name}
-created: {ISO-timestamp}
----
-
-# Implementation Plan: {TICKET-ID}
-
-{One sentence summary}
-
-## Components
-
-| Step | Component | Action | File | Description | Complexity |
-|------|-----------|--------|------|-------------|------------|
-| 1 | {name} | create | {path} | {what it does} | simple |
-| 2 | {name} | modify | {path} | {what to change} | moderate |
+Create a single file at `.5/features/{feature-name}/plan.md`.
 
-## Implementation Notes
-
-- Follow pattern from {existing-file} for {component-type}
-- {Key business rule}
-- {Integration point}
+Follow the `<output-format>`, `<write-rules>`, and `<plans-are-prompts>` defined in your agent file.
 
-## Complexity Guide
+Include:
+- YAML frontmatter (ticket, feature, created)
+- One-sentence summary
+- Components table
+- Implementation Notes (references to existing pattern files + business rules)
+- Complexity Guide
+- Verification commands
 
-**simple** -> haiku: Pattern-following, type defs, simple CRUD
-**moderate** -> haiku/sonnet: Services with logic, multi-pattern files, modifications
-**complex** -> sonnet: Integration points, complex rules, significant refactoring
+### Step 5b: Plan Self-Check
 
-## Verification
+Follow the `<self-check>` defined in your agent file.
 
-- Build: {command or "auto"}
-- Test: {command or "auto"}
+Output the verification result:
+```
+Plan self-check:
+- Format: pass/fail
+- No code: pass/fail
+- Scope: pass/fail
+- Completeness: pass/fail
+- Description length: pass/fail
 ```
 
-**Key principle:** The plan describes WHAT to build, not HOW. Agents figure out patterns by reading existing code.
+If any check fails, fix plan.md before proceeding to the completion output.
 
 ## PLANNING COMPLETE
 

package/src/hooks/plan-guard.js

@@ -44,11 +44,16 @@ process.stdin.on('end', () => {
     if (toolName === 'Task') {
       const agentType = toolInput.subagent_type || '';
       if (agentType && agentType !== 'Explore') {
+        const blockCount = incrementBlockCount(workspaceDir);
+        const escalation = blockCount >= 3
+          ? ` WARNING: Block #${blockCount}. You are repeatedly attempting actions outside your planning role. STOP. Complete your planning artifact and output the completion message.`
+          : '';
         process.stderr.write(
           `BLOCKED: Only Explore agents are allowed during planning phases. ` +
           `Attempted: subagent_type="${agentType}". ` +
-          `To use other agent types, start implementation with /5:implement-feature. ` +
-          `If you're not in a planning phase, run /5:unlock to clear the planning lock.`
+          `REDIRECT: Return to your planning process. ` +
+          `If you need codebase information, use subagent_type=Explore. ` +
+          `If you are done planning, output the completion message and STOP.${escalation}`
         );
         process.exit(2);
       }
@@ -57,12 +62,19 @@ process.stdin.on('end', () => {
     if (toolName === 'Write' || toolName === 'Edit') {
       const filePath = toolInput.file_path || '';
       if (filePath && !isInsideDotFive(filePath, workspaceDir)) {
+        const blockCount = incrementBlockCount(workspaceDir);
+        const isSourceFile = !filePath.includes('.5/') && !filePath.includes('.claude/');
+        const escalation = blockCount >= 3
+          ? ` WARNING: Block #${blockCount}. Repeated violations. Complete your planning artifact and STOP.`
+          : '';
+        const redirectMsg = isSourceFile
+          ? `REDIRECT: You are in a planning phase. You may ONLY write to .5/features/. ` +
+            `Source file creation happens in Phase 3 (/5:implement-feature).`
+          : `REDIRECT: The path "${filePath}" is outside the allowed .5/ directory. ` +
+            `Check your file path — you should be writing to .5/features/{name}/.`;
         process.stderr.write(
           `BLOCKED: ${toolName} outside .5/ is not allowed during planning phases. ` +
-          `Attempted: "${filePath}". ` +
-          `Planning commands may only write to .5/features/. ` +
-          `To modify source files, start implementation with /5:implement-feature. ` +
-          `If you're not in a planning phase, run /5:unlock to clear the planning lock.`
+          `Attempted: "${filePath}". ${redirectMsg}${escalation}`
         );
         process.exit(2);
       }
@@ -141,6 +153,18 @@ function isPlanningActive(workspaceDir) {
   }
 }
 
+function incrementBlockCount(workspaceDir) {
+  const markerPath = path.join(workspaceDir, '.5', '.planning-active');
+  try {
+    const marker = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+    marker.blockCount = (marker.blockCount || 0) + 1;
+    fs.writeFileSync(markerPath, JSON.stringify(marker, null, 2));
+    return marker.blockCount;
+  } catch (e) {
+    return 1;
+  }
+}
+
 function isFeatureInImplementationMode(workspaceDir, featureName) {
   // Check if this specific feature has a state.json (created in Phase 3)
   const stateFile = path.join(

package/src/templates/workflow/FEATURE-SPEC.md

@@ -1,3 +1,11 @@
+<!-- TEMPLATE RULES:
+- Requirements use natural language, not code
+- Affected Components lists module/domain names, not file paths
+- Entity definitions describe data concepts, not schemas or interfaces
+- Acceptance criteria describe observable behavior, not test assertions
+- NO code, pseudo-code, or implementation details anywhere in this document
+-->
+
 # Feature: {TICKET-ID} - {Title}
 
 ## Ticket ID
@@ -35,6 +43,7 @@
 ## Entity/Component Definitions
 
 ### {EntityName} (if applicable)
+<!-- Describe the data CONCEPT, not the implementation. No TypeScript, no SQL. -->
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | id | {Entity}Id | Yes | Unique identifier |

package/src/templates/workflow/PLAN.md

@@ -4,6 +4,13 @@ feature: {feature-name}
 created: {ISO-timestamp}
 ---
 
+<!-- PLAN RULES:
+- This file is interpolated into agent prompts. Write it as instructions, not documentation.
+- Description column: one action-oriented sentence per component
+- Implementation Notes: reference existing files as patterns, no code snippets
+- Components table must cover all functional requirements from feature.md
+-->
+
 # Implementation Plan: {TICKET-ID}
 
 {One sentence summary of what this plan builds}