5-phase-workflow 1.8.5 → 1.8.6

package/package.json

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

package/src/commands/5/configure.md

@@ -327,6 +327,13 @@ Analyze the codebase and generate modular documentation:
 - Quick reference section with links to all `.5/*.md` files
 - Project overview and build commands
 - "Getting Started" guide with references to appropriate files
+- Workflow rules section (verbatim):
+  ```
+  ## Workflow Rules
+  When running `/5:` workflow commands, follow the command instructions exactly as written.
+  Do not skip steps, combine phases, or proceed to actions not specified in the current command.
+  Each phase produces a specific artifact — do not create artifacts belonging to other phases.
+  ```
 - Mandatory coding guidelines:
   1. Types should be clear and types should be available when possible
   2. Use doc (jsdoc, javadoc, pydoc, etc) concisely. No doc is better than meaningless doc

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

@@ -8,24 +8,27 @@ context: fork
 ---
 
 <role>
-You are a Feature Planner. Your only output is a feature specification file.
-You do NOT implement code. You write NO code. You spawn ONLY Explore agents (subagent_type=Explore).
-You write ONLY to .5/.planning-active and .5/features/{name}/feature.md.
-After creating the spec, you are DONE. Do not continue into implementation planning or coding.
+You are a Feature Planner. Your ONLY deliverable is a feature specification file (feature.md).
+You do NOT implement code. You do NOT create implementation plans. You spawn ONLY Explore agents (subagent_type=Explore).
+You write ONLY to .5/.planning-active, .5/features/{name}/codebase-scan.md, and .5/features/{name}/feature.md.
+After creating the spec, you are FINISHED. You do not continue. You do not offer to continue.
 </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 create an implementation plan, file list, component breakdown, or step-by-step build guide — that is Phase 2's job
+- NEVER suggest "shall I continue with implementation planning?" or "let me create the plan" — you are DONE after feature.md
+- NEVER offer to proceed to the next phase — the user will invoke `/5:plan-implementation` themselves
 - 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 write to any file except .5/.planning-active, .5/features/{name}/codebase-scan.md, and .5/features/{name}/feature.md
 - 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
+- NEVER continue past the completion message — when you output "Feature spec created at...", you are FINISHED
 - 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.
+- If you feel the urge to plan implementation or write code, STOP — ask a clarifying question instead
+- Your output is a SPECIFICATION, not a design document. No code. No file layouts. No API shapes. No implementation plans.
 </constraints>
 
 <write-rules>
@@ -195,24 +198,23 @@ Populate all sections:
 - **[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
+## PLANNING COMPLETE — MANDATORY STOP
 
-After writing feature.md, output exactly:
+After writing feature.md, output ONLY this message — no additional text, no suggestions, no offers to continue:
 
 ```
-Feature spec created at `.5/features/{name}/feature.md`
+✓ Feature spec created at `.5/features/{name}/feature.md`
 
-Next steps:
-1. Review the feature spec
-2. If changes needed: /5:discuss-feature {name}
-3. If approved: /clear then /5:plan-implementation {name}
+To review or refine: /5:discuss-feature {name}
+To proceed: /clear → /5:plan-implementation {name}
 ```
 
-STOP. You are a planner. Your job is done. Do not implement.
+**YOU ARE NOW FINISHED.** This is a hard stop. Do not:
+- Suggest next steps beyond the message above
+- Offer to create an implementation plan
+- Offer to continue with any phase
+- Write any additional files
+- Provide a summary of what could be implemented
+- Ask "shall I proceed with..." or "would you like me to..."
 
-<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>
+If the user asks you to continue or implement, respond: "Phase 1 is complete. Please run `/5:plan-implementation {name}` to continue."

package/src/hooks/plan-guard.js

@@ -99,9 +99,15 @@ process.stdin.on('end', () => {
 
     if (toolName === 'Write' || toolName === 'Edit') {
       const filePath = toolInput.file_path || '';
-      if (filePath && !isInsideDotFive(filePath, workspaceDir)) {
+      if (!filePath) {
+        process.exit(0);
+      }
+
+      const phase = getPlanningPhase(workspaceDir);
+
+      // First check: block anything outside .5/
+      if (!isInsideDotFive(filePath, workspaceDir)) {
         const blockCount = incrementBlockCount(workspaceDir);
-        const phase = getPlanningPhase(workspaceDir);
         const isSourceFile = !filePath.includes('.5/') && !filePath.includes('.claude/');
         const escalation = blockCount >= 3
           ? ` 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.`
@@ -118,6 +124,22 @@ process.stdin.on('end', () => {
         );
         process.exit(2);
       }
+
+      // Second check: during plan-feature, only allow specific files
+      if (phase === 'plan-feature' && !isAllowedPlanFeatureFile(filePath, workspaceDir)) {
+        const blockCount = incrementBlockCount(workspaceDir);
+        const escalation = blockCount >= 3
+          ? ` CRITICAL: Block #${blockCount}. You are attempting to create implementation artifacts during Phase 1. Phase 1 ONLY produces feature.md. STOP and output your completion message.`
+          : '';
+        process.stderr.write(
+          `BLOCKED: During plan-feature (Phase 1), you may only write to .planning-active, codebase-scan.md, and feature.md. ` +
+          `Attempted: "${filePath}". ` +
+          `You are creating implementation artifacts (e.g., plan.md) which belongs to Phase 2. ` +
+          `REDIRECT: If you have already written feature.md, output the completion message and STOP. ` +
+          `Do NOT create implementation plans, file lists, or any other artifacts.${escalation}`
+        );
+        process.exit(2);
+      }
     }
 
     process.exit(0);
@@ -127,6 +149,23 @@ process.stdin.on('end', () => {
   }
 });
 
+function isAllowedPlanFeatureFile(filePath, workspaceDir) {
+  const resolved = path.resolve(workspaceDir, filePath);
+  const dotFiveDir = path.join(workspaceDir, '.5');
+
+  // Allow .5/.planning-active
+  if (resolved === path.join(dotFiveDir, '.planning-active')) return true;
+
+  // Allow .5/features/{name}/feature.md and .5/features/{name}/codebase-scan.md
+  const featuresDir = path.join(dotFiveDir, 'features');
+  if (resolved.startsWith(featuresDir + path.sep)) {
+    const basename = path.basename(resolved);
+    if (basename === 'feature.md' || basename === 'codebase-scan.md') return true;
+  }
+
+  return false;
+}
+
 function isInsideDotFive(filePath, workspaceDir) {
   const resolved = path.resolve(workspaceDir, filePath);
   const dotFiveDir = path.join(workspaceDir, '.5');

package/src/skills/configure-project/SKILL.md

@@ -166,6 +166,13 @@ CLAUDE.md structure:
 - **Quick Reference:** Links to all 7 `.5/*.md` files (STACK, STRUCTURE, ARCHITECTURE, CONVENTIONS, TESTING, INTEGRATIONS, CONCERNS)
 - **Project Overview:** 1-2 paragraphs from README/package.json
 - **Build & Run Commands:** Build, test, and other detected commands
+- **Workflow Rules:** Include this section verbatim:
+  ```
+  ## Workflow Rules
+  When running `/5:` workflow commands, follow the command instructions exactly as written.
+  Do not skip steps, combine phases, or proceed to actions not specified in the current command.
+  Each phase produces a specific artifact — do not create artifacts belonging to other phases.
+  ```
 - **Coding Guidelines:** The 6 mandatory principles (types, concise docs, short files, extract methods, SRP/DRY, maintainable/modular)
 - **Getting Started:** Links to relevant `.5/` files for new devs and specific tasks