5-phase-workflow 1.8.4 → 1.8.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "5-phase-workflow",
-  "version": "1.8.4",
+  "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

@@ -211,6 +211,11 @@ The skill-creator plugin from the official Claude store helps generate higher-qu
 - "Generate/update CLAUDE.md? This will analyze your codebase to document structure and conventions."
   - Options: "Yes (recommended)", "Skip"
 
+**2k2. Confirm rules generation:**
+- "Generate `.claude/rules/` files? These are scoped instruction files that automatically load when Claude works with matching file types (e.g., testing rules load only when editing test files, code-style rules load only for source files)."
+  - Options: "Yes (recommended)", "Skip"
+- Note: Rules complement CLAUDE.md — they provide focused, file-type-scoped directives derived from your project's actual conventions.
+
 **2l. Review detected patterns for skill generation:**
 
 Present ONLY patterns that were actually detected in steps 1g and 1h.
@@ -270,7 +275,7 @@ Using the values gathered from Steps 1 and 2, write `.5/config.json` directly.
 mkdir -p .5
 ```
 
-**Schema:** Read `.claude/references/configure-tables.md` section "Config Schema" for the full JSON structure. Fill all values from user responses. Write with pretty-printed JSON. Read back to verify correctness.
+**Schema:** Read `.claude/references/configure-tables.md` section "Config Schema" for the full JSON structure. Fill all values from user responses (including `rules.generate` from step 2k2). Write with pretty-printed JSON. Read back to verify correctness.
 
 **Update `.5/version.json` with configure timestamp:**
 
@@ -322,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
@@ -347,6 +359,15 @@ Analyze the codebase and generate modular documentation:
 
 Include only patterns/commands where user selected "Generate".
 
+### Requirement 3: Generate Scoped Rules (if selected)
+Generate `.claude/rules/` files with project-specific conventions scoped to relevant file types.
+Rules are concise directives (15-40 lines, NOT documentation) derived from codebase analysis.
+Only generate rules for patterns that were actually detected:
+- `code-style.md` — naming, formatting, import conventions (scoped to source files)
+- `testing.md` — test patterns, mocking, fixtures (scoped to test files)
+- `api-patterns.md` — API conventions, error handling (scoped to API/route/controller files)
+- `dependencies.md` — dependency usage patterns, env var conventions (unconditional)
+
 ## Acceptance Criteria
 - [ ] `.5/` directory created
 - [ ] All 7 documentation files exist and are populated:
@@ -363,6 +384,10 @@ Include only patterns/commands where user selected "Generate".
 - [ ] All specified project-specific skills are generated in `.claude/skills/`
 - [ ] Generated skills reference actual project conventions
 - [ ] If CLAUDE.md existed before, user-written sections are preserved
+- [ ] `.claude/rules/` directory exists with scoped rule files (if rules generation selected)
+- [ ] Generated rules use `paths:` frontmatter for scoping where applicable
+- [ ] Rules contain concise directives, not documentation
+- [ ] No rules generated for undetected patterns
 ```
 
 **Important:** Use `mkdir -p .5/features/CONFIGURE` before writing the feature spec.

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/commands/5/reconfigure.md

@@ -90,6 +90,11 @@ Perform the same detection as configure Steps 1b-1h:
 - Read each skill's SKILL.md frontmatter
 - Categorize as workflow-generated (create-*, run-*) or user-created
 
+**2f. Scan existing rules** — list ALL rule files in `.claude/rules/`:
+- Read each `.md` file
+- Note which are workflow-generated (code-style, testing, api-patterns, dependencies) vs user-created
+- User-created rules are never modified or removed
+
 ### Step 3: Compare and Prepare Summary
 
 Use the existing skills in `.claude/skills/` (from Step 2e) as the source of truth — not config.json. Compare what's installed with what's detected in the codebase:
@@ -102,14 +107,22 @@ Use the existing skills in `.claude/skills/` (from Step 2e) as the source of tru
 - **Stale commands**: a `run-*` skill exists but the command is no longer detected → offer to remove or keep
 - **User-created skills** (not matching `create-*` or `run-*` naming) → always refresh with current conventions, never remove
 
+**Rules comparison** (if `rules.generate` is `true` in config.json):
+- **Existing workflow rules** (from Step 2f) — code-style, testing, api-patterns, dependencies
+- **Stale rules**: a workflow rule exists but its prerequisite patterns are no longer detected → offer to remove
+- **New rules**: patterns detected that could benefit from a rule but none exists yet → offer to create
+- **User-created rules** → never modify or remove
+
 ### Step 4: Confirm with User
 
 Use `AskUserQuestion` to show a summary and get confirmation. Present:
 
 1. **Documentation files that will be rewritten** — list all 7 `.5/*.md` files + CLAUDE.md
 2. **Skills that will be refreshed** — list ALL skills found in `.claude/skills/` (both workflow-generated and user-created)
-3. **New patterns detected** (if any) — "These patterns were found in your codebase but don't have skills yet: [list]. Create skills for them?"
-4. **Stale patterns** (if any) — "These patterns are in your config but weren't found in the codebase: [list]. Remove them?"
+3. **Rules that will be refreshed** (if rules enabled) — list workflow-generated rule files in `.claude/rules/`
+4. **New patterns detected** (if any) — "These patterns were found in your codebase but don't have skills yet: [list]. Create skills for them?"
+5. **Stale patterns** (if any) — "These patterns are in your config but weren't found in the codebase: [list]. Remove them?"
+6. **Stale rules** (if any) — "These rule files no longer have matching patterns in the codebase: [list]. Remove them?"
 
 Options:
 - "Proceed with refresh" — regenerate everything as shown
@@ -133,12 +146,20 @@ Refresh ALL existing skills in .claude/skills/:
 - New skills to create: [list from user confirmation, if any]
 - Skills to remove: [list from user confirmation, if any]
 
+Refresh rules in .claude/rules/ (if rules.generate is true):
+- Existing workflow rules: [list from Step 2f]
+- Rules to remove: [list from user confirmation, if any]
+- New rules to create: [if applicable]
+
 Re-analyze the entire codebase (A1 analysis) and:
 1. Rewrite all 7 .5/*.md documentation files
 2. Update CLAUDE.md (preserve user-written sections)
 3. Refresh ALL skills in .claude/skills/ — read current conventions from codebase and update each skill
 4. Create new skills for newly-added patterns
-5. Remove skills the user chose to drop"
+5. Remove skills the user chose to drop
+6. Refresh all workflow-generated rule files in .claude/rules/ with updated conventions
+7. Create new rule files for newly-detected patterns
+8. Remove rule files the user chose to drop"
 ```
 
 Use `subagent_type: "general-purpose"` for the Task.
@@ -166,6 +187,9 @@ Show the user a summary:
 - List of skills refreshed
 - List of new skills created (if any)
 - List of skills removed (if any)
+- List of rules refreshed (if any)
+- List of new rules created (if any)
+- List of rules removed (if any)
 - Timestamp of reconfiguration
 - Suggest running `/clear` to reset context
 

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/references/configure-tables.md

@@ -109,6 +109,9 @@ For each command found: record exact syntax, note variants (e.g., `test:unit`, `
   },
   "dotFiveFolder": {
     "gitignore": true
+  },
+  "rules": {
+    "generate": true
   }
 }
 ```

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
 
@@ -327,6 +334,97 @@ Executes the project's {command} command.
 
 ---
 
+## C. Generate Scoped Rules
+
+If `rules.generate` is `true` in `.5/config.json`, generate `.claude/rules/` files with project-specific conventions scoped to relevant file types.
+
+Rules are **concise directives** (15-40 lines each), NOT documentation. Documentation lives in `.5/*.md` files. Rules tell Claude what to do when working with specific file types.
+
+### C1. Determine Which Rules to Generate
+
+Based on the A1 analysis results, determine which rules apply:
+
+| Rule File | Generate When | Source Analysis |
+|-----------|---------------|-----------------|
+| `code-style.md` | Always (if source files exist) | Conventions Analysis |
+| `testing.md` | Test files detected | Testing Analysis |
+| `api-patterns.md` | Controller/route/handler patterns detected | Architecture Analysis |
+| `dependencies.md` | External integrations detected | Integration Analysis |
+
+**Skip** any rule whose prerequisite patterns were not detected. Do NOT generate empty or placeholder rule files.
+
+### C2. Extract Directives and Write Rules
+
+For each applicable rule:
+
+1. **Derive `paths:` globs** from detected file locations (e.g., if tests are at `src/**/*.test.ts` and `tests/**/*.spec.ts`, use those patterns)
+2. **Convert analysis observations into imperative directives** — "Use X", "Always Y", "Never Z"
+3. **Keep each file 15-40 lines** — be concise and actionable
+4. **Do NOT repeat** the 6 mandatory coding guidelines from CLAUDE.md
+
+Write files to `.claude/rules/`:
+
+```bash
+mkdir -p .claude/rules
+```
+
+### C3. Rule File Format
+
+Each rule file uses YAML frontmatter with `paths:` for scoping. Rules without `paths:` load unconditionally.
+
+**Example — `testing.md`:**
+
+```markdown
+---
+paths:
+  - "**/*.test.ts"
+  - "**/*.spec.ts"
+---
+
+# Testing Conventions
+
+- Use `describe`/`it` blocks with descriptive names
+- Mock external dependencies with jest.mock, never mock internal modules
+- Use factory functions from `tests/factories/` for test data
+- Each test file mirrors its source file path: `src/foo/Bar.ts` → `src/foo/__tests__/Bar.test.ts`
+- Assert one behavior per test
+```
+
+**Example — `code-style.md`:**
+
+```markdown
+---
+paths:
+  - "src/**/*.{ts,tsx}"
+---
+
+# Code Style
+
+- Use PascalCase for classes and types, camelCase for functions and variables
+- Import order: external packages → internal modules → relative imports
+- Use absolute imports with `@/` alias
+- Prefer named exports over default exports
+```
+
+**Example — `dependencies.md` (unconditional):**
+
+```markdown
+# Dependency Conventions
+
+- Database access through Prisma client only, never raw SQL
+- HTTP requests use axios instance from `src/lib/http.ts`
+- Environment variables accessed via `src/config/env.ts`, never `process.env` directly
+```
+
+### Refresh Mode Behavior for Rules
+
+When running in REFRESH MODE:
+- Re-analyze codebase and overwrite all existing rule files with updated directives
+- Remove rule files for patterns no longer detected in the codebase
+- Create new rule files if new patterns are detected that weren't present before
+
+---
+
 ## Output Contract
 
 Returns structured results for each component:
@@ -343,6 +441,7 @@ Component A (Documentation): SUCCESS - Created 7 documentation files + index
   - CLAUDE.md (index with references)
 Component B (Pattern Skills): SUCCESS - Generated 3 create-* skills (create-component, create-hook, create-context)
 Component C (Command Skills): SUCCESS - Generated 2 run-* skills (run-tests, run-lint)
+Component D (Rules): SUCCESS - Generated 3 rule files (code-style, testing, dependencies)
 ```
 
 Or on failure:
@@ -350,6 +449,7 @@ Or on failure:
 ```
 Component A (Documentation): FAILED - Unable to read template files
 Component B (Pattern Skills): FAILED - No patterns found in codebase
+Component D (Rules): SKIPPED - rules.generate is false in config
 ```
 
 ## DO NOT
@@ -357,7 +457,9 @@ Component B (Pattern Skills): FAILED - No patterns found in codebase
 - DO NOT overwrite existing user-written CLAUDE.md sections
 - DO NOT generate skills for patterns that don't exist in the project
 - DO NOT generate command skills for commands that don't exist in the project
+- DO NOT generate rules for patterns not detected in the codebase
 - DO NOT include `steps` in config.json
 - DO NOT hardcode conventions - always derive from actual project analysis
-- DO NOT generate empty or placeholder skill files
+- DO NOT generate empty or placeholder skill or rule files
 - DO NOT assume command syntax - always read from actual config files (package.json, Makefile, etc.)
+- DO NOT repeat the 6 mandatory coding guidelines from CLAUDE.md in rule files