5-phase-workflow 1.8.4 → 1.8.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "5-phase-workflow",
-  "version": "1.8.4",
+  "version": "1.8.5",
   "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:**
 
@@ -347,6 +352,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 +377,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/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/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

@@ -327,6 +327,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 +434,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 +442,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 +450,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