5-phase-workflow 1.8.1 → 1.8.4

package/bin/install.js

@@ -248,6 +248,19 @@ function removeDir(dir) {
   }
 }
 
+// Files removed from the package before manifest tracking existed.
+// This list is frozen — future removals are handled by manifest diffing.
+const LEGACY_REMOVED_FILES = [
+  'agents/feature-planner.md',
+  'agents/implementation-planner.md',
+  'agents/review-processor.md',
+  'agents/step-executor.md',
+  'agents/integration-agent.md',
+  'agents/step-fixer.md',
+  'agents/step-verifier.md',
+  'agents/verification-agent.md'
+];
+
 // Get list of workflow-owned files/directories (not user-created)
 function getWorkflowManagedFiles() {
   return {
@@ -303,6 +316,46 @@ function getWorkflowManagedFiles() {
   };
 }
 
+// Flatten getWorkflowManagedFiles() into a list of relative paths (relative to .claude/)
+function getFileManifest() {
+  const managed = getWorkflowManagedFiles();
+  const manifest = [];
+
+  // Commands are directories
+  for (const cmd of managed.commands) {
+    manifest.push(`commands/${cmd}`);
+  }
+
+  // Agents are files
+  for (const agent of managed.agents) {
+    manifest.push(`agents/${agent}`);
+  }
+
+  // Skills are directories
+  for (const skill of managed.skills) {
+    manifest.push(`skills/${skill}`);
+  }
+
+  // Hooks are files
+  for (const hook of managed.hooks) {
+    manifest.push(`hooks/${hook}`);
+  }
+
+  // Templates are files (may include nested paths like workflow/FEATURE-SPEC.md)
+  for (const template of managed.templates) {
+    manifest.push(`templates/${template}`);
+  }
+
+  // References are files
+  if (managed.references) {
+    for (const ref of managed.references) {
+      manifest.push(`references/${ref}`);
+    }
+  }
+
+  return manifest;
+}
+
 // Selectively update only workflow-managed files, preserve user content
 function selectiveUpdate(targetPath, sourcePath) {
   const managed = getWorkflowManagedFiles();
@@ -406,6 +459,50 @@ function selectiveUpdate(targetPath, sourcePath) {
   }
 }
 
+// Clean up files that were previously installed but are no longer managed
+function cleanupOrphanedFiles(targetPath, dataDir) {
+  const versionFile = path.join(dataDir, 'version.json');
+  const currentManifest = getFileManifest();
+  const currentSet = new Set(currentManifest);
+
+  let oldManifest = null;
+  if (fs.existsSync(versionFile)) {
+    try {
+      const data = JSON.parse(fs.readFileSync(versionFile, 'utf8'));
+      oldManifest = data.manifest || null;
+    } catch (e) {
+      // Corrupted file, treat as no manifest
+    }
+  }
+
+  if (oldManifest) {
+    // Manifest exists: diff old vs current, delete orphans
+    for (const entry of oldManifest) {
+      if (!currentSet.has(entry)) {
+        const fullPath = path.join(targetPath, entry);
+        if (fs.existsSync(fullPath)) {
+          const stat = fs.statSync(fullPath);
+          if (stat.isDirectory()) {
+            removeDir(fullPath);
+          } else {
+            fs.unlinkSync(fullPath);
+          }
+          log.info(`Removed orphaned: ${entry}`);
+        }
+      }
+    }
+  } else {
+    // No manifest (legacy upgrade): use static legacy removals list
+    for (const entry of LEGACY_REMOVED_FILES) {
+      const fullPath = path.join(targetPath, entry);
+      if (fs.existsSync(fullPath)) {
+        fs.unlinkSync(fullPath);
+        log.info(`Removed legacy orphan: ${entry}`);
+      }
+    }
+  }
+}
+
 // Ensure .5/.gitignore exists and contains .update-cache.json
 function ensureDotFiveGitignore(dataDir) {
   const gitignorePath = path.join(dataDir, '.gitignore');
@@ -436,7 +533,8 @@ function initializeVersionJson(isGlobal) {
     packageVersion: version,
     installedAt: now,
     lastUpdated: now,
-    installationType: isGlobal ? 'global' : 'local'
+    installationType: isGlobal ? 'global' : 'local',
+    manifest: getFileManifest()
   };
 
   fs.writeFileSync(versionFile, JSON.stringify(versionData, null, 2));
@@ -583,11 +681,14 @@ function performUpdate(targetPath, sourcePath, isGlobal, versionInfo) {
   // Selectively update only workflow-managed files (preserves user content)
   selectiveUpdate(targetPath, sourcePath);
 
+  // Clean up orphaned files from previous versions
+  const dataDir = getDataPath(isGlobal);
+  cleanupOrphanedFiles(targetPath, dataDir);
+
   // Merge settings (deep merge preserves user customizations)
   mergeSettings(targetPath, sourcePath);
 
   // Update version.json
-  const dataDir = getDataPath(isGlobal);
   const versionFile = path.join(dataDir, 'version.json');
   const now = new Date().toISOString();
 
@@ -598,7 +699,8 @@ function performUpdate(targetPath, sourcePath, isGlobal, versionInfo) {
     packageVersion: versionInfo.available,
     installedAt: existing.installedAt || now,
     lastUpdated: now,
-    installationType: existing.installationType || (isGlobal ? 'global' : 'local')
+    installationType: existing.installationType || (isGlobal ? 'global' : 'local'),
+    manifest: getFileManifest()
   };
 
   if (!fs.existsSync(dataDir)) {
@@ -690,6 +792,15 @@ function uninstall() {
 
   const managed = getWorkflowManagedFiles();
 
+  // Remove legacy orphaned files that may still exist from older versions
+  for (const entry of LEGACY_REMOVED_FILES) {
+    const fullPath = path.join(targetPath, entry);
+    if (fs.existsSync(fullPath)) {
+      fs.unlinkSync(fullPath);
+      log.info(`Removed legacy orphan: ${entry}`);
+    }
+  }
+
   // Remove commands/5/ (workflow namespace only)
   const commands5 = path.join(targetPath, 'commands', '5');
   if (fs.existsSync(commands5)) {

package/package.json

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

package/src/agents/component-executor.md

@@ -12,16 +12,16 @@ You follow existing codebase patterns. You do NOT deviate from the plan.
 <process>
 ## Implementation Process
 
-1. **Read the plan context** provided in your prompt (feature name, components, implementation notes)
+1. **Read required files FIRST** — If your prompt includes a `Pattern File` or `Read First` field, you MUST read every listed file before writing any code. This establishes ground truth and prevents assumptions about conventions, naming, or structure.
 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
+   - Read the pattern file (from step 1) to understand conventions
+   - Create the new file following the same patterns exactly
+   - If no pattern file was provided, find a similar existing file via Glob and read it
 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
+4. **Run verify command** — If your prompt includes a `Verify` field, run that command and confirm it passes. If it fails, fix the issue (subject to the 3-attempt limit). If no verify command was provided, verify each file exists after changes.
 </process>
 
 <output-format>
@@ -31,6 +31,8 @@ When done, output your result in this exact format:
 STATUS: success | failed
 FILES_CREATED: [comma-separated paths]
 FILES_MODIFIED: [comma-separated paths]
+VERIFY: passed | failed | skipped
+DEVIATIONS: none | {brief list of auto-fixes applied}
 ERROR: none | {error description}
 ---END---
 </output-format>
@@ -44,5 +46,12 @@ You WILL discover unplanned work. Handle as follows:
 |---------|--------|------------|
 | 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 |
+| Missing validation/auth/logging | Add → verify → note in result | Auto |
+| Blocking issue (prevents task completion) | Fix → verify → note in result | Auto |
+| Architectural change needed (new DB table, schema change, service switch) | STOP → report in ERROR field | Ask user |
+| Auth error ("401", "Not authenticated", "Set ENV_VAR") | STOP → report as AUTH_GATE in ERROR | Ask user |
+
+**Priority:** Architectural/Auth (ask) > Auto-fix rules > Unsure (treat as architectural, ask)
+
+**3-attempt limit:** If you have attempted 3 auto-fixes on a SINGLE issue and it still fails, STOP. Report the issue in the ERROR field with `ATTEMPTS_EXHAUSTED: {description}`. Do not keep trying — the orchestrator will handle it.
 </deviation-rules>

package/src/commands/5/address-review-findings.md

@@ -3,7 +3,6 @@ name: 5:address-review-findings
 description: Applies annotated review findings and/or addresses GitHub PR review comments. Use --github to process PR comments only.
 allowed-tools: Bash, Read, Edit, Write, Glob, Grep, AskUserQuestion, Task, Skill, mcp__jetbrains__*
 user-invocable: true
-disable-model-invocation: true
 model: sonnet
 context: fork
 ---

package/src/commands/5/configure.md

@@ -3,7 +3,6 @@ name: 5:configure
 description: Configures the project. Analyzes project, gathers preferences, writes config.json, and creates feature spec for remaining setup. Follow up with /5:plan-implementation CONFIGURE.
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
-disable-model-invocation: true
 model: opus
 context: fork
 ---

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

@@ -3,7 +3,6 @@ name: 5:discuss-feature
 description: Discusses and refines an existing feature specification through iterative Q&A. Use after /plan-feature when requirements need clarification or changes. Updates the feature spec based on discussion.
 allowed-tools: Read, Write, Glob, Grep, Task, AskUserQuestion
 user-invocable: true
-disable-model-invocation: true
 model: opus
 context: inherit
 ---

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

@@ -3,7 +3,6 @@ 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, TaskCreate, TaskUpdate, TaskList
 user-invocable: true
-disable-model-invocation: true
 model: opus
 context: fork
 ---
@@ -35,6 +34,15 @@ You are a thin orchestrator:
 - 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
+- Context budget: keep orchestrator lean — delegate ALL implementation to agents
+
+**Context Budget Rules:**
+Your context window is shared across all steps. To avoid running out of context on large features:
+- NEVER read source files yourself — that's the executor agent's job
+- NEVER paste full agent outputs into your reasoning — extract only the `---RESULT---` block
+- Keep state.json updates minimal — write only changed fields
+- If an agent returns a very long response, parse the RESULT block and discard the rest
+- For features with 10+ components: after processing each step's results, summarize the step outcome in one line and move on. Do NOT accumulate detailed logs across steps.
 
 **State verification rule:** After every state.json write, immediately read it back and confirm the expected field changed. If verification fails, stop with an error message. This applies to every state write below — marked as **(verify write)**.
 
@@ -99,6 +107,37 @@ Then remove the planning guard marker (planning is over, implementation is start
 rm -f .5/.planning-active
 ```
 
+### Step 2c: Regression Baseline
+
+Before spawning any agents, establish a baseline by running the project's build and test commands:
+
+```bash
+# Build command from plan (or auto-detect)
+{build-command}
+
+# Test command from plan (or auto-detect)
+{test-command}
+```
+
+Record the results in state.json as `baseline`:
+```json
+{
+  "baseline": {
+    "buildStatus": "success|failed",
+    "testStatus": "success|failed|skipped",
+    "checkedAt": "{ISO-timestamp}"
+  }
+}
+```
+
+**(verify write)** — confirm `baseline.checkedAt` is set.
+
+**If the baseline build fails:** Warn the user: `"⚠ Build fails BEFORE implementation. Any post-implementation build failures may be pre-existing."` Continue — don't block on pre-existing failures.
+
+**If baseline tests fail:** Warn the user: `"⚠ {N} tests fail BEFORE implementation. These will be excluded from regression comparison."` Record the failing test names/patterns if available, so Step 4 can distinguish pre-existing failures from new ones.
+
+This baseline enables Step 4 to detect regressions: tests that passed before but fail after implementation.
+
 ### Step 2b: Create Progress Checklist
 
 Before executing any steps, create one TaskCreate entry per step:
@@ -115,6 +154,19 @@ Then mark the task for Step 1 as `in_progress`.
 
 Group components by step number from the plan. For each step (starting from `currentStep` in state.json):
 
+**3pre. Pre-step dependency check (steps 2+)**
+
+Before executing step N (where N > 1), verify that prior steps' outputs exist on disk:
+
+1. For each component in `completedComponents` from prior steps: use Glob to confirm every file in `filesCreated` and `filesModified` still exists
+2. If ANY file is missing:
+   - Log: `"⚠ Pre-step check: {file} from step {M} component {name} not found on disk"`
+   - Move the component back from `completedComponents` to `pendingComponents`
+   - STOP execution for this step. Report to user: `"Step {N} blocked: prior step output missing. Re-run step {M} or fix manually."`
+3. If all files verified, proceed to 3a
+
+This prevents cascading failures where step N assumes step N-1's outputs exist but they don't.
+
 **3a. Analyze step for parallel execution**
 
 Components within the same step are independent by design. For steps with multiple components:
@@ -145,7 +197,13 @@ Task tool call:
 
     ## Feature: {feature-name}
     ## Components
-    {component(s) from plan table: name, action, file, description}
+    {component(s) from plan table: name, action, file, description, complexity}
+
+    ## Read First
+    {Pattern File value(s) from plan table — executor MUST read these before writing any code}
+
+    ## Verify
+    {Verify command(s) from plan table — executor runs these after implementation}
 
     ## Implementation Notes
     {relevant notes from plan}
@@ -153,9 +211,9 @@ Task tool call:
 
 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**
+**3d. Process results (context-lean)**
 
-Collect results from all agents (parallel or sequential). Parse the `---RESULT---` block from each agent's response. For each:
+Collect results from all agents (parallel or sequential). Parse ONLY the `---RESULT---` block from each agent's response — do NOT retain the full agent output in your context. For each:
 - 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
@@ -251,8 +309,13 @@ For each non-test component with action "create" that contains logic:
 **(verify write)** — confirm `verificationResults.builtAt` is set.
 
 If build or tests fail:
+- Compare against `baseline` in state.json:
+  - If build failed in baseline AND still fails → report as `"Pre-existing build failure (not a regression)"`
+  - If build passed in baseline BUT fails now → report as `"⚠ REGRESSION: Build broke during implementation"`
+  - If tests that passed in baseline now fail → report as `"⚠ REGRESSION: {N} tests broke during implementation: {test names}"`
+  - If tests that failed in baseline still fail → report as `"Pre-existing test failure (not a regression)"`
 - Record in state.json
-- Report to user with error details
+- Report to user with error details and regression classification
 
 Mark the "Run verification" TaskCreate task as `completed`.
 

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

@@ -3,7 +3,6 @@ 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.
 allowed-tools: Read, Write, Task, AskUserQuestion
 user-invocable: true
-disable-model-invocation: true
 model: opus
 context: fork
 ---
@@ -22,6 +21,8 @@ HARD CONSTRAINTS — violations waste tokens and get blocked by plan-guard:
 - NEVER spawn Task agents with subagent_type other than Explore
 - NEVER write to any file except .5/features/{name}/feature.md (where {name} may include a ticket prefix) and .5/.planning-active
 - NEVER call EnterPlanMode — the workflow has its own planning process
+- NEVER use Bash to create, write, or modify files — this bypasses the plan-guard and is a constraint violation
+- NEVER continue past the completion message — when you output "Feature spec created at...", you are DONE
 - 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.
@@ -30,7 +31,8 @@ HARD CONSTRAINTS — violations waste tokens and get blocked by plan-guard:
 <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 4 only
+2. `.5/features/{name}/codebase-scan.md` — Step 2 only (Explore agent results cache)
+3. `.5/features/{name}/feature.md` — Step 4 only
 Any other Write target WILL be blocked by the plan-guard hook. Do not attempt it.
 </write-rules>
 
@@ -63,6 +65,20 @@ testing strategy, integration points (from findings), alternative approaches, co
 
 # Plan Feature (Phase 1)
 
+## Progress Checklist
+
+Follow these steps IN ORDER. Do NOT skip steps. Do NOT proceed to a later step until the current one is complete. After completing each step, output a status line: `✓ Step N complete`.
+
+- [ ] Step 0: Activate planning guard — write `.5/.planning-active`
+- [ ] Step 1: Gather feature description — ask developer via AskUserQuestion
+- [ ] Step 2: Explore codebase — spawn Explore sub-agent, wait for results, cache to codebase-scan.md
+- [ ] Step 3: Ask 5+ clarifying questions — one at a time, minimum 5 before proceeding
+- [ ] Step 3b: Pre-write checkpoint — verify ≥5 Q&A pairs exist, no code in spec
+- [ ] Step 4: Write feature specification — create `.5/features/{name}/feature.md`
+- [ ] Output completion message and STOP
+
+> **MANDATORY:** After each step, output `✓ Step N complete` before moving on. This is your progress anchor — if you cannot say which step you just completed, you are skipping ahead. If Step 3b fails (< 5 Q&A), return to Step 3.
+
 ## Process
 
 ### Step 0: Activate Planning Guard
@@ -82,17 +98,19 @@ This activates the plan-guard hook which prevents accidental source file edits d
 
 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."
+"Please describe the feature you want to specify. Paste the full ticket description or explain it in your own words."
 
 - Expect free-text answer, do NOT provide options
 - Do NOT ask follow-up questions yet
 
 ### Step 2: Spawn Explore Agent for Codebase Analysis
 
+> **ROLE CHECK:** You are a Feature Planner. Your ONLY output is feature.md. If you are tempted to write code or create files, STOP and return to the next question in Step 3.
+
 Spawn a Task with `subagent_type=Explore`:
 
 ```
-Analyze the codebase for a feature planning session.
+Analyze the codebase for a feature specification session.
 
 **Feature Description:** {paste the user's feature description}
 
@@ -118,7 +136,11 @@ Analyze the codebase for a feature planning session.
 
 Wait for the sub-agent to return before proceeding.
 
-### Step 3: Intensive Q&A (5-10 Questions, One at a Time)
+**Cache the results:** Write the Explore agent's full output to `.5/features/{name}/codebase-scan.md` using the Write tool. This saves Phase 2 from re-scanning the same codebase and saves significant tokens.
+
+### Step 3: Intensive Q&A
+
+> **ROLE CHECK:** You are gathering requirements, NOT designing solutions. Questions ask WHAT and WHY, never HOW.
 
 Ask 5-10 clarifying questions using AskUserQuestion. ONE question at a time — wait for the answer before asking the next. Use the sub-agent findings to inform questions. Cover: requirements clarity, scope boundaries, edge cases, performance expectations, testing strategy, integration points, alternative approaches, and complexity trade-offs. Challenge assumptions: "Is this the simplest solution?", "Could we reuse existing X?", "What happens when Y fails?"
 
@@ -141,6 +163,8 @@ If you have fewer than 5 Q&A pairs, go back to Step 3 and ask more questions.
 
 ### Step 4: Create Feature Specification
 
+> **ROLE CHECK:** You are writing a SPECIFICATION (WHAT/WHY), not a design document (HOW). Zero code, zero file paths to create, zero signatures. After writing feature.md you are DONE — do NOT proceed to implementation planning or coding.
+
 **Extract ticket ID from git branch:**
 - The Explore agent from Step 2 already ran `git branch --show-current` — find the branch name in its results
 - Use the configurable ticket pattern from `.5/config.json` (e.g., `PROJ-\d+`) to extract the ticket ID from the branch name
@@ -163,7 +187,13 @@ Populate all sections:
 - Affected Components (from exploration)
 - Acceptance Criteria
 - Alternatives Considered
-- Questions & Answers (from Q&A session)
+- Decisions (from Q&A session) — label each with **[DECIDED]**, **[FLEXIBLE]**, or **[DEFERRED]**
+
+**Decision labeling rules:**
+- **[DECIDED]**: The user gave a clear, specific answer → Phase 2 planner and Phase 3 agents MUST honor exactly
+- **[FLEXIBLE]**: The user said "up to you", "whatever works", or didn't express a strong preference → planner chooses
+- **[DEFERRED]**: The user explicitly said "not now", "later", "skip this" → planner MUST NOT include in the plan
+- When in doubt, label as **[DECIDED]** — it's safer to honor a decision than to override it
 
 ## PLANNING COMPLETE
 

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

@@ -3,7 +3,6 @@ name: 5:plan-implementation
 description: Creates an implementation plan from a feature spec. Phase 2 of the 5-phase workflow.
 allowed-tools: Read, Write, Task, AskUserQuestion
 user-invocable: true
-disable-model-invocation: true
 model: opus
 context: fork
 ---
@@ -21,8 +20,12 @@ HARD CONSTRAINTS — violations get blocked by plan-guard:
 - NEVER create source files — you create ONE file: plan.md
 - NEVER call EnterPlanMode — the workflow has its own planning process
 - NEVER spawn Task agents with subagent_type other than Explore
+- NEVER use Bash to create, write, or modify files — this bypasses the plan-guard and is a constraint violation
+- NEVER continue past the completion message — when you output "Plan created at...", you are DONE
 - 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
+- Each component in the table gets: name, action, file path, one-sentence description, pattern file, verify command, complexity
+- **Pattern File** (required for "create" actions): Path to an existing file the executor reads before implementing. For "modify" actions, this is the target file itself. Helps executor match conventions exactly.
+- **Verify** (required): A concrete command or grep check the executor runs after implementing. Examples: `grep -q 'export class UserService' src/services/user.service.ts`, `npm test -- --testPathPattern=user`, `npx tsc --noEmit`. Never use vague checks like "works correctly".
 - If a component needs more than one sentence to describe, split it into multiple components
 - Implementation Notes reference EXISTING pattern files, not new code
 - Every component with action "create" that contains logic (services, controllers, repositories, hooks, utilities, helpers) MUST have a corresponding test component. Declarative components (types, interfaces, models without logic, route registrations, config files) are exempt. When uncertain, include the test.
@@ -31,7 +34,8 @@ HARD CONSTRAINTS — violations get blocked by plan-guard:
 <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
+2. `.5/features/{name}/codebase-scan.md` — Step 2 only (if fresh scan was needed)
+3. `.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>
 
@@ -58,6 +62,22 @@ Assign complexity per component using this rubric:
 
 # Plan Implementation (Phase 2)
 
+## Progress Checklist
+
+Follow these steps IN ORDER. Do NOT skip steps. Do NOT proceed to a later step until the current one is complete. After completing each step, output a status line: `✓ Step N complete`.
+
+- [ ] Step 0: Activate planning guard — write `.5/.planning-active`
+- [ ] Step 1: Load feature spec — read `.5/features/{name}/feature.md`
+- [ ] Step 1b: Load project configuration — read `.5/config.json` if it exists
+- [ ] Step 2: Load or generate codebase scan — reuse cached scan from Phase 1, or spawn Explore if missing
+- [ ] Step 3: Ask 2-3 technical questions — one at a time via AskUserQuestion
+- [ ] Step 4: Design components — identify files, order, step grouping
+- [ ] Step 5: Write the plan — create `.5/features/{name}/plan.md`
+- [ ] Step 5b: Plan self-check — verify format, no code, scope, completeness, tests
+- [ ] Output completion message and STOP
+
+> **MANDATORY:** After each step, output `✓ Step N complete` before moving on. This is your progress anchor — if you cannot say which step you just completed, you are skipping ahead. If Step 5b fails, fix plan.md before outputting completion.
+
 ## Output Format
 
 Read the plan template at `.claude/templates/workflow/PLAN.md` for the exact structure and rules. Your output must follow that template precisely — fill in the placeholders with real values from the feature spec and codebase scan.
@@ -82,7 +102,12 @@ This activates (or refreshes) the plan-guard hook which prevents accidental sour
 
 Read `.5/features/{feature-name}/feature.md` (where `{feature-name}` is the argument provided).
 
-Extract: Ticket ID, requirements (functional and non-functional), acceptance criteria, affected components.
+Extract: Ticket ID, requirements (functional and non-functional), acceptance criteria, affected components, and **decisions**.
+
+**Decision labels from feature spec:**
+- **[DECIDED]** items are locked — your plan MUST honor them exactly. Do not override or reinterpret.
+- **[FLEXIBLE]** items are your discretion — choose the best approach based on codebase patterns.
+- **[DEFERRED]** items are out of scope — do NOT plan components for them. If a deferred item is needed as a dependency, flag it in Implementation Notes.
 
 If the file doesn't exist, tell the user to run `/5:plan-feature` first.
 
@@ -95,7 +120,15 @@ Read `.5/config.json` if it exists. Extract:
 
 If config.json doesn't exist, proceed without it.
 
-### Step 2: Spawn Explore Agent for Codebase Scan
+### Step 2: Load or Generate Codebase Scan
+
+> **ROLE CHECK:** You are an Implementation Planner. Your ONLY output is plan.md. You do NOT write code, create source files, or start implementation. If you feel the urge to implement, STOP — that is Phase 3's job.
+
+**First, check for a cached scan from Phase 1:**
+
+Read `.5/features/{feature-name}/codebase-scan.md`. If it exists and is non-empty, use it as the codebase scan results. This was generated during Phase 1 (`/5:plan-feature`) and contains project structure, naming conventions, pattern files, and test framework detection.
+
+**If `codebase-scan.md` does NOT exist** (e.g., user skipped Phase 1 or ran an older version), spawn a fresh Explore agent:
 
 Spawn a Task with `subagent_type=Explore`:
 
@@ -136,6 +169,8 @@ Focus scan on {projectType}-relevant directories and patterns.
 
 Wait for the sub-agent to return before proceeding.
 
+**If a fresh scan was spawned**, write the results to `.5/features/{feature-name}/codebase-scan.md` for future reference.
+
 ### Step 3: Ask 2-3 Technical Questions (One at a Time)
 
 Use AskUserQuestion to clarify:
@@ -159,6 +194,8 @@ Targeted scan for implementation planning.
 
 ### Step 4: Design Components
 
+> **ROLE CHECK:** You are identifying WHAT and WHERE — component names, actions, file paths, one-sentence descriptions. You are NOT writing code, pseudo-code, or implementation details. The HOW is figured out by Phase 3 agents reading existing code.
+
 Based on feature spec and codebase scan, identify:
 - Files to create
 - Files to modify
@@ -195,6 +232,8 @@ Not every feature needs all non-test steps. Use what makes sense. But testable c
 
 ### Step 5: Write the Plan
 
+> **ROLE CHECK:** You are writing plan.md — a components table with descriptions, NOT code. After writing and verifying, output the completion message and STOP. Do NOT continue to implementation.
+
 Create a single file at `.5/features/{feature-name}/plan.md`.
 
 Include:
@@ -212,22 +251,26 @@ Include:
 
 Read plan.md back and verify:
 
-1. **Format:** Every row in the Components table has all 6 columns filled
+1. **Format:** Every row in the Components table has all 8 columns filled (Step, Component, Action, File, Description, Pattern File, Verify, Complexity)
 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.
-6. **Unit test coverage:** Every "create" component with logic has a corresponding unit test component. Declarative-only components (types, interfaces, route wiring) are exempt.
-7. **Integration/e2e coverage:** If the explore agent detected integration or e2e frameworks AND the feature touches endpoints or cross-module flows, verify at least one integration or e2e test component is planned.
+6. **Pattern files:** Every "create" component has a Pattern File pointing to an existing file. Verify these files exist via Glob.
+7. **Verify commands:** Every component has a concrete Verify command (grep, test, build). No vague checks.
+8. **Unit test coverage:** Every "create" component with logic has a corresponding unit test component. Declarative-only components (types, interfaces, route wiring) are exempt.
+9. **Integration/e2e coverage:** If the explore agent detected integration or e2e frameworks AND the feature touches endpoints or cross-module flows, verify at least one integration or e2e test component is planned.
 
 Output the verification result:
 ```
 Plan self-check:
-- Format: pass/fail
+- Format (8 columns): pass/fail
 - No code: pass/fail
 - Scope: pass/fail
 - Completeness: pass/fail
 - Description length: pass/fail
+- Pattern files exist: pass/fail
+- Verify commands concrete: pass/fail
 - Unit test coverage: pass/fail
 - Integration/e2e coverage: pass/fail/n-a
 ```

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

@@ -3,7 +3,6 @@ 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, TaskCreate, TaskUpdate, TaskList, mcp__jetbrains__*
 user-invocable: true
-disable-model-invocation: true
 context: fork
 ---
 
@@ -25,6 +24,7 @@ Fast path for small, well-understood tasks (1-5 files). Skips extensive planning
 Your job in this command:
 ✅ Get task description
 ✅ Extract ticket ID
+✅ Scope check (>5 files or >3 modules → redirect to full workflow)
 ✅ Create quick plan (max 5 components)
 ✅ Get user approval on plan
 ✅ Initialize state tracking
@@ -90,12 +90,23 @@ Check if `.5/features/${feature_name}/state.json` already exists:
   - 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
+### Step 4: Analyze and Scope Check
 
 1. **Identify affected files** using Glob and Grep
 2. **Determine skills needed** based on task type
 3. **List components** (max 5 for quick mode)
 
+**Scope gate — check BEFORE planning:**
+
+Count the number of files that will be created or modified and the number of distinct modules/directories involved. Apply these rules:
+
+- **>5 files** → STOP. Tell the user: `"This task affects {N} files, which exceeds quick-implement's scope (max 5). Use the full workflow instead: /5:plan-feature"`. Do NOT continue.
+- **>3 distinct modules/directories** → STOP. Tell the user: `"This task spans {N} modules ({list}), which is too broad for quick-implement. Use the full workflow: /5:plan-feature"`. Do NOT continue.
+- **Involves database schema changes, new API endpoints with auth, or architectural decisions** → STOP. Tell the user: `"This task involves {reason}, which needs proper planning. Use: /5:plan-feature"`. Do NOT continue.
+- **≤5 files AND ≤3 modules AND no architectural changes** → Proceed to Step 5.
+
+This gate prevents quick-implement from being used for tasks that should go through full planning, where the absence of a feature spec and structured plan leads to poor results.
+
 **If unclear about implementation details**, ask 2-3 focused questions using AskUserQuestion:
 - What validation rules apply?
 - Which existing patterns to follow?

package/src/commands/5/reconfigure.md

@@ -3,7 +3,6 @@ name: 5:reconfigure
 description: Lightweight refresh of project documentation and skills without full Q&A. Re-detects codebase changes, regenerates .5/*.md docs, updates CLAUDE.md, and refreshes all skills.
 allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
 user-invocable: true
-disable-model-invocation: true
 context: fork
 ---
 

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

@@ -3,7 +3,6 @@ name: 5:review-code
 description: Reviews code changes using Claude (built-in) or CodeRabbit CLI. Categorizes findings and saves them for /5:address-review-findings.
 allowed-tools: Bash, Read, Glob, Grep, AskUserQuestion, Task, mcp__jetbrains__*
 user-invocable: true
-disable-model-invocation: true
 model: sonnet
 context: fork
 ---

package/src/commands/5/unlock.md

@@ -3,7 +3,6 @@ name: 5:unlock
 description: Remove the planning guard lock to allow edits outside the workflow
 allowed-tools: Bash
 user-invocable: true
-disable-model-invocation: true
 context: inherit
 ---
 

package/src/commands/5/update.md

@@ -3,7 +3,6 @@ name: 5:update
 description: Update the 5-Phase Workflow to the latest version
 allowed-tools: Bash, Read, AskUserQuestion
 user-invocable: true
-disable-model-invocation: true
 model: haiku
 context: fork
 ---

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

@@ -3,7 +3,6 @@ name: 5:verify-implementation
 description: Verifies a feature implementation is complete and working with multi-layer checks. Phase 4 of the 5-phase workflow.
 allowed-tools: Read, Glob, Grep, Bash, Write, Task, AskUserQuestion
 user-invocable: true
-disable-model-invocation: true
 model: sonnet
 context: fork
 ---

package/src/hooks/plan-guard.js

@@ -20,8 +20,8 @@ process.stdin.on('end', () => {
     const data = JSON.parse(input);
     const toolName = data.tool_name || '';
 
-    // Short-circuit: only check Task, Write, Edit, and EnterPlanMode tools
-    if (toolName !== 'Task' && toolName !== 'Write' && toolName !== 'Edit' && toolName !== 'EnterPlanMode') {
+    // Short-circuit: only check Task, Write, Edit, EnterPlanMode, and Bash tools
+    if (toolName !== 'Task' && toolName !== 'Write' && toolName !== 'Edit' && toolName !== 'EnterPlanMode' && toolName !== 'Bash') {
       process.exit(0);
     }
 
@@ -43,13 +43,15 @@ process.stdin.on('end', () => {
     // Planning mode enforcement
     if (toolName === 'EnterPlanMode') {
       const blockCount = incrementBlockCount(workspaceDir);
+      const phase = getPlanningPhase(workspaceDir);
       const escalation = blockCount >= 3
-        ? ` WARNING: Block #${blockCount}. Repeated violations. Complete your planning artifact and STOP.`
+        ? ` CRITICAL: Block #${blockCount}. You have attempted to break out of planning ${blockCount} times. You MUST return to your current step in the Progress Checklist, complete your planning artifact, output the completion message, and STOP. Do NOT attempt any other action.`
         : '';
       process.stderr.write(
         `BLOCKED: EnterPlanMode is not allowed during workflow planning phases. ` +
         `The 5-phase workflow has its own planning process. ` +
-        `REDIRECT: Continue with your current planning task. ` +
+        `REDIRECT: You are in ${phase || 'a planning phase'}. Return to your Progress Checklist. ` +
+        `Find the last "✓ Step N complete" you output, then continue with Step N+1. ` +
         `Write your output to .5/features/{name}/ and output the completion message when done.${escalation}`
       );
       process.exit(2);
@@ -59,13 +61,15 @@ process.stdin.on('end', () => {
       const agentType = toolInput.subagent_type || '';
       if (agentType && agentType !== 'Explore') {
         const blockCount = incrementBlockCount(workspaceDir);
+        const phase = getPlanningPhase(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.`
+          ? ` CRITICAL: Block #${blockCount}. You are a planner, NOT an implementer. You have attempted to spawn non-Explore agents ${blockCount} times. This is Phase 1 or 2 — implementation happens in Phase 3. Return to your Progress Checklist immediately, complete your planning artifact, and STOP.`
           : '';
         process.stderr.write(
           `BLOCKED: Only Explore agents are allowed during planning phases. ` +
           `Attempted: subagent_type="${agentType}". ` +
-          `REDIRECT: Return to your planning process. ` +
+          `You are in ${phase || 'a planning phase'}. Implementation agents are Phase 3 only. ` +
+          `REDIRECT: Return to your Progress Checklist. Find your last "✓ Step N complete" and continue with Step N+1. ` +
           `If you need codebase information, use subagent_type=Explore. ` +
           `If you are done planning, output the completion message and STOP.${escalation}`
         );
@@ -73,17 +77,39 @@ process.stdin.on('end', () => {
       }
     }
 
+    if (toolName === 'Bash') {
+      const command = toolInput.command || '';
+      // Detect file-writing shell commands that bypass Write/Edit guards
+      const writePatterns = /\b(cat\s*>|cat\s*<<|echo\s.*>|tee\s|printf\s.*>|cp\s|mv\s|mkdir\s.*&&.*>|sed\s+-i|awk\s.*>|touch\s|install\s)/;
+      if (writePatterns.test(command)) {
+        const blockCount = incrementBlockCount(workspaceDir);
+        const phase = getPlanningPhase(workspaceDir);
+        const escalation = blockCount >= 3
+          ? ` CRITICAL: Block #${blockCount}. You are repeatedly attempting to write files via Bash to bypass planning guards. STOP immediately.`
+          : '';
+        process.stderr.write(
+          `BLOCKED: File-writing Bash commands are not allowed during planning phases. ` +
+          `You are in ${phase || 'a planning phase'}. ` +
+          `REDIRECT: Return to your Progress Checklist. Planners do not create or modify source files. ` +
+          `Complete your planning artifact and output the completion message.${escalation}`
+        );
+        process.exit(2);
+      }
+    }
+
     if (toolName === 'Write' || toolName === 'Edit') {
       const filePath = toolInput.file_path || '';
       if (filePath && !isInsideDotFive(filePath, workspaceDir)) {
         const blockCount = incrementBlockCount(workspaceDir);
+        const phase = getPlanningPhase(workspaceDir);
         const isSourceFile = !filePath.includes('.5/') && !filePath.includes('.claude/');
         const escalation = blockCount >= 3
-          ? ` WARNING: Block #${blockCount}. Repeated violations. Complete your planning artifact and STOP.`
+          ? ` CRITICAL: Block #${blockCount}. You have attempted to write source files ${blockCount} times. You are a PLANNER, not an implementer. Writing source code is Phase 3's job. Return to your Progress Checklist, finish 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: You are in ${phase || 'a planning phase'}. You may ONLY write to .5/features/. ` +
+            `Source file creation happens in Phase 3 (/5:implement-feature). ` +
+            `Return to your Progress Checklist — find your last "✓ Step N complete" and continue with Step N+1.`
           : `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(
@@ -179,6 +205,16 @@ function incrementBlockCount(workspaceDir) {
   }
 }
 
+function getPlanningPhase(workspaceDir) {
+  const markerPath = path.join(workspaceDir, '.5', '.planning-active');
+  try {
+    const marker = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+    return marker.phase || null;
+  } catch (e) {
+    return null;
+  }
+}
+
 function isFeatureInImplementationMode(workspaceDir, featureName) {
   // Check if this specific feature has a state.json (created in Phase 3)
   const stateFile = path.join(

package/src/settings.json

@@ -38,7 +38,7 @@
         ]
       },
       {
-        "matcher": "Task|Write|Edit|EnterPlanMode",
+        "matcher": "Task|Write|Edit|EnterPlanMode|Bash",
         "hooks": [
           {
             "type": "command",

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

@@ -76,13 +76,22 @@
 ### Chosen Approach: {Selected approach}
 **Rationale:** {Why this approach was chosen}
 
-## Questions & Answers
+## Decisions
+
+<!-- Tag every Q&A with exactly one of: [DECIDED], [FLEXIBLE], [DEFERRED]
+  - [DECIDED]: Locked decision — Phase 2 planner and Phase 3 agents MUST honor exactly
+  - [FLEXIBLE]: Claude's discretion — planner chooses the best approach
+  - [DEFERRED]: Explicitly out of scope — planner MUST NOT include in the plan
+-->
 
 ### Q1: {Question from collaboration phase}
-**A:** {Answer from developer}
+**A:** {Answer from developer} **[DECIDED]**
 
 ### Q2: {Question}
-**A:** {Answer}
+**A:** {Answer} **[FLEXIBLE]**
+
+### Q3: {Question about a nice-to-have}
+**A:** {Answer — let's skip this for now} **[DEFERRED]**
 
 ...
 

package/src/templates/workflow/PLAN.md

@@ -8,6 +8,8 @@ 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
+- Pattern File column: path to an existing file the executor MUST read before implementing (establishes conventions)
+- Verify column: a concrete command or check the executor runs after implementing (grep pattern, test command, build check)
 - Implementation Notes: reference existing files as patterns, no code snippets
 - Components table must cover all functional requirements from feature.md
 - Three test tiers: unit (always required for logic), integration (when framework detected + cross-module/DB/API), e2e (when framework detected + endpoints/UI flows)
@@ -22,16 +24,16 @@ created: {ISO-timestamp}
 
 ## Components
 
-| Step | Component | Action | File | Description | Complexity |
-|------|-----------|--------|------|-------------|------------|
-| 1 | {name} | create | {path} | {what it does} | simple |
-| 1 | {name} | create | {path} | {what it does} | simple |
-| 2 | {name} | create | {path} | {what it does} | moderate |
-| 2 | {name} | modify | {path} | {what to change} | moderate |
-| 3 | {name} | create | {path} | {what it does} | complex |
-| 4 | {name} unit tests | create | {test-path} | Test {what it tests} | moderate |
-| 4 | {name} integration tests | create | {test-path} | Test {cross-module interaction} | moderate |
-| 4 | {name} e2e tests | create | {test-path} | Test {user-facing flow end-to-end} | moderate |
+| Step | Component | Action | File | Description | Pattern File | Verify | Complexity |
+|------|-----------|--------|------|-------------|-------------|--------|------------|
+| 1 | {name} | create | {path} | {what it does} | {existing file to read first} | {grep/test command} | simple |
+| 1 | {name} | create | {path} | {what it does} | {pattern} | {verify} | simple |
+| 2 | {name} | create | {path} | {what it does} | {pattern} | {verify} | moderate |
+| 2 | {name} | modify | {path} | {what to change} | {target file} | {verify} | moderate |
+| 3 | {name} | create | {path} | {what it does} | {pattern} | {verify} | complex |
+| 4 | {name} unit tests | create | {test-path} | Test {what it tests} | {existing test} | {test command} | moderate |
+| 4 | {name} integration tests | create | {test-path} | Test {cross-module interaction} | {existing test} | {test command} | moderate |
+| 4 | {name} e2e tests | create | {test-path} | Test {user-facing flow end-to-end} | {existing test} | {test command} | moderate |
 
 ## Testing Strategy