5-phase-workflow 1.7.2 → 1.8.1

package/bin/install.js

@@ -256,8 +256,6 @@ function getWorkflowManagedFiles() {
 
     // Agents: separate agent files referenced by commands via agent: frontmatter
     agents: [
-      'feature-planner.md',
-      'implementation-planner.md',
       'component-executor.md'
     ],
 
@@ -278,6 +276,11 @@ function getWorkflowManagedFiles() {
       'config-guard.js'
     ],
 
+    // References: lookup tables and schemas read on-demand by commands
+    references: [
+      'configure-tables.md'
+    ],
+
     // Templates: specific template files
     templates: [
       // Project documentation templates
@@ -384,6 +387,23 @@ function selectiveUpdate(targetPath, sourcePath) {
     }
   }
   log.success('Updated templates/ (workflow files only)');
+
+  // Update specific references
+  if (managed.references && managed.references.length > 0) {
+    const referencesSrc = path.join(sourcePath, 'references');
+    const referencesDest = path.join(targetPath, 'references');
+    if (!fs.existsSync(referencesDest)) {
+      fs.mkdirSync(referencesDest, { recursive: true });
+    }
+    for (const ref of managed.references) {
+      const src = path.join(referencesSrc, ref);
+      const dest = path.join(referencesDest, ref);
+      if (fs.existsSync(src)) {
+        fs.copyFileSync(src, dest);
+      }
+    }
+    log.success('Updated references/ (workflow files only)');
+  }
 }
 
 // Ensure .5/.gitignore exists and contains .update-cache.json
@@ -522,7 +542,7 @@ function performFreshInstall(targetPath, sourcePath, isGlobal) {
   }
 
   // Copy directories
-  const dirs = ['commands', 'agents', 'skills', 'hooks', 'templates'];
+  const dirs = ['commands', 'agents', 'skills', 'hooks', 'templates', 'references'];
   for (const dir of dirs) {
     const src = path.join(sourcePath, dir);
     const dest = path.join(targetPath, dir);
@@ -550,6 +570,7 @@ function performFreshInstall(targetPath, sourcePath, isGlobal) {
   log.info('  • Generate comprehensive documentation (CLAUDE.md)');
   log.info('  • Create project-specific skills');
   log.info('');
+  log.info('Tip: Configure will offer to install helpful plugins like skill-creator');
 
   showCommandsHelp(isGlobal);
 }
@@ -712,6 +733,17 @@ function uninstall() {
   }
   log.success('Removed workflow templates (preserved user-created templates)');
 
+  // Remove only workflow-managed references
+  if (managed.references) {
+    for (const ref of managed.references) {
+      const refPath = path.join(targetPath, 'references', ref);
+      if (fs.existsSync(refPath)) {
+        fs.unlinkSync(refPath);
+      }
+    }
+    log.success('Removed workflow references (preserved user-created references)');
+  }
+
   // Remove data directory (.5/)
   const dataDir = getDataPath(false);
   if (fs.existsSync(dataDir)) {

package/package.json

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

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

@@ -2,10 +2,10 @@
 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__*
-model: sonnet
-context: fork
 user-invocable: true
 disable-model-invocation: true
+model: sonnet
+context: fork
 ---
 
 <role>
@@ -36,8 +36,6 @@ Check if the command was invoked with `--github`.
 
 Regardless of mode, read `.5/features/*/state.json` using Glob to find all state files. Select the one with the most recent `startedAt` (or `lastUpdated` if present).
 
-Read `.5/features/*/state.json` using Glob to find all state files. Select the one with the most recent `startedAt` (or `lastUpdated` if present).
-
 Extract:
 - `feature` — feature directory name
 - `ticket` — ticket ID

package/src/commands/5/configure.md

@@ -2,11 +2,19 @@
 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
-context: inherit
 user-invocable: true
 disable-model-invocation: true
+model: opus
+context: fork
 ---
 
+<role>
+You are a Project Configurator. You analyze a project, gather preferences, and write config.json plus a feature spec.
+You do NOT generate CLAUDE.md, documentation files, or skills directly — those are Phase 3's job.
+You write ONLY to: .5/config.json, .5/version.json, .5/features/CONFIGURE/feature.md, and .gitignore.
+After writing config.json and the feature spec, you are DONE. Exit immediately.
+</role>
+
 # Configure (Phase 1 - Plan Feature for Project Configuration)
 
 ## Overview
@@ -59,40 +67,9 @@ else
 fi
 ```
 
-**1b. Detect project type** by checking files (first match wins):
-
-| File Present | Dependency / Sub-check | Type |
-|---|---|---|
-| `package.json` | `next` | nextjs |
-| `package.json` | `@nestjs/core` | nestjs |
-| `package.json` | `express` | express |
-| `package.json` | `react` | react |
-| `package.json` | `vue` | vue |
-| `package.json` | *(none matched)* | javascript |
-| `build.gradle(.kts)` | — | gradle-java |
-| `pom.xml` | — | maven-java |
-| `requirements.txt` / `pyproject.toml` | + `manage.py` | django |
-| `requirements.txt` / `pyproject.toml` | + `app.py`/`wsgi.py` | flask |
-| `requirements.txt` / `pyproject.toml` | *(none matched)* | python |
-| `Cargo.toml` | — | rust |
-| `go.mod` | — | go |
-| `Gemfile` | + `config/routes.rb` | rails |
-| `Gemfile` | *(none matched)* | ruby |
-
-**1c. Detect build/test commands** based on project type:
-
-| Type | Build Command | Test Command |
-|------|--------------|--------------|
-| javascript | `npm run build` | `npm test` |
-| nextjs | `npm run build` | `npm test` |
-| nestjs | `npm run build` | `npm test` |
-| express | `npm run build \|\| tsc` | `npm test` |
-| gradle-java | `./gradlew build -x test -x javadoc --offline` | `./gradlew test --offline` |
-| maven-java | `mvn package -DskipTests` | `mvn test` |
-| python | `python -m py_compile **/*.py` | `pytest` |
-| django | `python manage.py check` | `python manage.py test` |
-| rust | `cargo build` | `cargo test` |
-| go | `go build ./...` | `go test ./...` |
+**1b. Detect project type** — Read `.claude/references/configure-tables.md` section "Project Type Detection" for the lookup table.
+
+**1c. Detect build/test commands** — Read `.claude/references/configure-tables.md` section "Build/Test Commands by Type" for the lookup table.
 
 **1d. Detect available tools:**
 
@@ -109,6 +86,11 @@ fi
 
 # Context7 - up-to-date documentation MCP server
 # Check if context7 tools are available (resolve-library-id, query-docs)
+
+# skill-creator plugin — helps create better project-specific skills
+# Check if skill-creator tools are available by looking for known tool names
+# in the current session (e.g., create-skill, scaffold-skill).
+# Set skill_creator_available=true if any skill-creator tool is found.
 ```
 
 **1e. Check CLAUDE.md:**
@@ -117,33 +99,9 @@ fi
 **1f. Scan existing skills:**
 - Check `.claude/skills/` for existing project-specific skills
 
-**1g. Detect codebase patterns** for potential skills:
-
-Use Glob to scan for architectural patterns. For each, check both suffix-based (`*{Pattern}.{ts,js,java,py,rb}`) and directory-based (`{patterns}/**`) globs.
-
-**Pattern categories to scan:**
-- **Core:** Controllers, Services, Repositories, Models/Entities, Handlers
-- **Data Transfer:** DTOs, Requests, Responses, Mappers, Validators, Schemas
-- **Frontend:** Components, Hooks, Contexts, Stores, Pages, Layouts
-- **API/Routes:** API Routes, Middleware, Guards, Interceptors, Filters
-- **Testing:** Tests/Specs, Fixtures, Factories, Mocks
-- **Utilities:** Utils, Helpers, Constants, Types/Interfaces, Config
-- **Framework-Specific:** Modules, Pipes, Decorators, Blueprints, Views, Serializers
-- **Background/Async:** Jobs, Workers, Events, Listeners, Commands
-- **Database:** Migrations, Seeds
-- **Error Handling:** Exceptions, Errors
-
-For each pattern found: count matching files, identify primary location, sample 1 filename.
-
-**1h. Detect runnable commands** for potential command skills:
-
-Scan config files (`package.json` scripts, `Makefile` targets, `pyproject.toml` scripts, `Cargo.toml`, `build.gradle` tasks, `composer.json` scripts, `Rakefile` tasks) for commands in these categories:
-
-Build, Test, Lint, Format, Type Check, Dev Server, Database (migrate/seed), Docker, Deploy, Clean, Generate
+**1g. Detect codebase patterns** — Read `.claude/references/configure-tables.md` section "Codebase Pattern Categories to Scan" for the full list and scanning approach.
 
-Skill naming: `run-{category}` (e.g., `run-build`, `run-tests`, `run-lint`).
-
-For each command found: record exact syntax, note variants (e.g., `test:unit`, `test:e2e`), and environment requirements. Only include commands that are actually detected.
+**1h. Detect runnable commands** — Read `.claude/references/configure-tables.md` section "Runnable Command Categories" for categories and scanning approach.
 
 ### Step 2: Gather User Preferences (interactive via AskUserQuestion)
 
@@ -235,11 +193,26 @@ Context7 provides up-to-date, version-specific documentation and code examples d
     2. "Skip"
   - If user selects "Install now": execute the install command
 
-**2j. Confirm CLAUDE.md generation:**
+**2j. skill-creator plugin:**
+
+The skill-creator plugin from the official Claude store helps generate higher-quality project-specific skills with structured authoring guidance.
+
+- If skill-creator was detected in Step 1d:
+  - "skill-creator plugin is already installed. ✓"
+  - Set `tools.skillCreator.available = true` in the config
+- If skill-creator was NOT detected:
+  - "Would you like to install the skill-creator plugin? It helps generate higher-quality project-specific skills."
+  - Options:
+    1. "Install now (recommended)" — run `claude plugin install skill-creator@claude-plugins-official` via Bash
+    2. "Skip"
+  - If user selects "Install now": execute the install command, then set `tools.skillCreator.available = true` in the config
+  - If user selects "Skip": `tools.skillCreator.available` remains `false`
+
+**2k. Confirm CLAUDE.md generation:**
 - "Generate/update CLAUDE.md? This will analyze your codebase to document structure and conventions."
   - Options: "Yes (recommended)", "Skip"
 
-**2k. Review detected patterns for skill generation:**
+**2l. Review detected patterns for skill generation:**
 
 Present ONLY patterns that were actually detected in steps 1g and 1h.
 
@@ -280,7 +253,7 @@ If no patterns/commands detected:
 - Inform user: "No common patterns detected. Would you like to specify patterns manually?"
 - Allow manual entry of pattern names/locations or command names
 
-**2l. Git-ignore `.5/features/` folder:**
+**2m. Git-ignore `.5/features/` folder:**
 - "The `.5/features/` folder will contain feature specs, implementation plans, and state files. Would you like to add it to `.gitignore`?"
   - Options:
     1. "Yes, add to .gitignore (recommended)" — workflow artifacts stay local, not tracked in version control
@@ -298,53 +271,7 @@ Using the values gathered from Steps 1 and 2, write `.5/config.json` directly.
 mkdir -p .5
 ```
 
-**Schema:**
-
-```json
-{
-  "projectType": "{type}",
-  "ticket": {
-    "pattern": "{regex-pattern-or-null}",
-    "extractFromBranch": true
-  },
-  "branch": {
-    "convention": "{convention}"
-  },
-  "build": {
-    "command": "{build-command}",
-    "testCommand": "{test-command}",
-    "timeout": {
-      "compile": 120000,
-      "test": 300000
-    }
-  },
-  "tools": {
-    "coderabbit": {
-      "available": false,
-      "authenticated": false
-    },
-    "ide": {
-      "available": false,
-      "type": null
-    },
-    "context7": {
-      "available": false
-    }
-  },
-  "reviewTool": "claude",
-  "git": {
-    "autoCommit": false,
-    "commitMessage": {
-      "pattern": "{ticket-id} {short-description}"
-    }
-  },
-  "dotFiveFolder": {
-    "gitignore": true
-  }
-}
-```
-
-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. Write with pretty-printed JSON. Read back to verify correctness.
 
 **Update `.5/version.json` with configure timestamp:**
 

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

@@ -2,11 +2,19 @@
 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
-context: inherit
 user-invocable: true
 disable-model-invocation: true
+model: opus
+context: inherit
 ---
 
+<role>
+You are a Feature Discussion Facilitator. You refine existing feature specifications through Q&A.
+You do NOT create new feature specs, create implementation plans, write code, or start implementation.
+You read an existing feature.md, discuss it with the user, and update only the changed sections.
+After updating the spec and informing the user, you are DONE.
+</role>
+
 # Discuss Feature Specification (Phase 1 - Optional Iteration)
 
 ## Overview
@@ -126,37 +134,7 @@ Use Task tool with subagent_type=Explore for complex exploration.
 
 Based on the discussion topic, ask targeted follow-up questions using AskUserQuestion.
 
-**Question types by topic:**
-
-**Clarify Requirements:**
-- "The current requirement says X. Should it also handle Y scenario?"
-- "How should the system behave when Z happens?"
-- "Are there edge cases we haven't considered?"
-
-**Add Requirements:**
-- "What is the expected behavior for this new requirement?"
-- "How does this interact with existing requirement X?"
-- "Should this be in scope or future work?"
-
-**Simplify/Remove:**
-- "If we remove X, what's the minimum viable version?"
-- "Can we defer Y to a future iteration?"
-- "Would simpler approach Z meet the core need?"
-
-**Change Approach:**
-- "What are the pros/cons of approach A vs B?"
-- "Have you considered alternative C?"
-- "What's the trade-off we're trying to optimize?"
-
-**Technical Constraints:**
-- "Is performance constraint X realistic?"
-- "Should we use existing component Y instead?"
-- "How will this integrate with system Z?"
-
-**Acceptance Criteria:**
-- "How will we verify requirement X is met?"
-- "What does success look like for this feature?"
-- "Are there specific test scenarios?"
+Ask targeted follow-up questions informed by the feature spec and any codebase exploration. Focus on: requirements clarity, scope boundaries, edge cases, technical constraints, and acceptance criteria. Challenge assumptions constructively — suggest simpler alternatives when appropriate.
 
 ### Step 6: Iterative Refinement
 
@@ -217,38 +195,4 @@ After updating the spec, tell the developer:
    - "Proceed to implementation planning (run `/clear` followed by `/5:plan-implementation {feature-name}`)"
    - "Review the updated spec first"
 
-## Key Principles
-
-1. **User-driven** - Follow user's focus areas, don't prescribe
-2. **Iterative** - Allow multiple discussion rounds
-3. **Contextual** - Explore codebase when relevant
-4. **Challenge constructively** - Question complexity, suggest alternatives
-5. **Document evolution** - Track how requirements changed
-6. **Preserve history** - Keep previous Q&A, add new discussions
-7. **Clear next steps** - Guide user on what to do next
 
-
-## Example Workflow
-
-```
-User: /discuss-feature PROJ-1234-add-feature
-
-Skill: [Reads feature spec]
-Skill: "What would you like to discuss or change about this feature?"
-User: "Clarify existing requirements"
-
-Skill: "The current spec mentions 'emergency schedule window'. Should this support single or multiple windows? Recurring schedules?"
-User: "Just single window per product for now"
-
-Skill: "Should we support updating/deleting the window after it's set?"
-User: "Yes, full CRUD"
-
-Skill: "Would you like to discuss anything else?"
-User: "No, update the spec"
-
-Skill: [Updates Requirements and Acceptance Criteria sections]
-Skill: "Feature spec updated. Changes:
-- Clarified: Single emergency window per product
-- Added: Full CRUD operations
-Next: /clear then /5:plan-implementation PROJ-1234-add-feature"
-```

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

@@ -2,11 +2,19 @@
 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
-context: fork
 user-invocable: true
 disable-model-invocation: true
+model: opus
+context: fork
 ---
 
+<role>
+You are an Implementation Orchestrator. You delegate work to agents — you do not write code directly.
+You read the plan, spawn agents per step, track state, and report completion.
+You NEVER write source code yourself. You NEVER skip state file updates between steps.
+After all steps complete and you report to the user, you are DONE.
+</role>
+
 # Implement Feature (Phase 3)
 
 Execute an implementation plan by delegating work to agents.
@@ -22,19 +30,14 @@ You are a thin orchestrator:
 - Track progress
 - Report completion
 
-**DO NOT:**
-- Write code directly — spawn agents
-- Skip state file updates between steps
-- Mark a step complete before writing state
-- Proceed to next step if state write fails
-- Use `git add .` at any point
-
 **Key Principles:**
 - Thin orchestrator: read, delegate, track, report
 - 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
 
+**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)**.
+
 ## Process
 
 ### Step 1: Load Plan and Config
@@ -88,8 +91,7 @@ Create `.5/features/{feature-name}/state.json` with the full components table pa
 
 `pendingComponents` is populated by parsing the full components table from plan.md at startup — one entry per row.
 
-**MANDATORY VERIFICATION:** Read state.json back immediately after writing. Confirm `status` is `"in-progress"` and `pendingComponents` is non-empty.
-If the read fails or content is wrong, stop: "Failed to initialize state file. Cannot proceed safely."
+**(verify write)** — confirm `status` is `"in-progress"` and `pendingComponents` is non-empty.
 
 Then remove the planning guard marker (planning is over, implementation is starting):
 
@@ -170,8 +172,7 @@ Update state.json:
 - Increment `currentStep`
 - Update `lastUpdated`
 
-**MANDATORY VERIFICATION:** Read state.json back and confirm `lastUpdated` changed.
-If verify fails, stop: "State write failed after step {N}. Cannot proceed safely."
+**(verify write)** — confirm `lastUpdated` changed.
 
 Mark the current step's TaskCreate task as `completed`. Mark the next step's task as `in_progress`.
 
@@ -247,7 +248,7 @@ For each non-test component with action "create" that contains logic:
 - Check if its corresponding test component exists in the plan
 - If a test was planned but is in `failedAttempts`, flag it prominently
 
-**MANDATORY VERIFICATION:** Read state.json back and confirm `verificationResults.builtAt` is set.
+**(verify write)** — confirm `verificationResults.builtAt` is set.
 
 If build or tests fail:
 - Record in state.json
@@ -266,8 +267,7 @@ Update state.json:
 }
 ```
 
-**MANDATORY VERIFICATION:** Read state.json back and confirm `status` is `"completed"`.
-If read fails, warn the user but do not re-attempt — the implementation work is done; only tracking failed.
+**(verify write)** — confirm `status` is `"completed"`. If this one fails, warn the user but continue — the implementation work is done.
 
 Tell the user:
 ```
@@ -299,39 +299,3 @@ If implementation is interrupted, the state file enables resuming:
 4. Skip steps where ALL components are in `completedComponents` AND their files are verified present on disk
 5. Write reconciled state (update `lastUpdated`) before re-executing any steps
 
-## Example Flow
-
-```
-Step 1: 2 simple components → 2 parallel haiku agents → update state → verify write
-Step 2: 2 moderate components → 2 parallel agents → update state → verify write
-Step 3: 1 complex component → 1 sonnet agent → update state → verify write
-Step 4: Verify (build + test) → update verificationResults → verify write → report
-```
-
-## Instructions Summary
-
-### Before starting:
-1. Check for existing state.json → handle resume / restart / completed cases
-2. Read plan.md → parse components table, implementation notes, verification commands
-3. Read config.json → extract `git.autoCommit`, `git.commitMessage.pattern`
-4. Initialize state.json with richer schema → **MANDATORY: verify write**
-5. Create TaskCreate tasks for all steps + verification → mark step 1 `in_progress`
-
-### For each step:
-1. Determine parallelism (same-step components = parallel)
-2. Determine model per component (simple→haiku, complex→sonnet)
-3. Spawn agents (one per component, parallel when possible)
-4. Collect results, parse `---RESULT---` blocks
-5. Run per-step file existence check (Glob) on `FILES_CREATED`
-6. Run retry logic for failures (max 2 retries per component)
-7. Update state.json → **MANDATORY: verify write**
-8. Run auto-commit if enabled and step had successes (stage specific files only)
-9. Mark step task `completed`, mark next step task `in_progress`
-
-### After all steps:
-1. Run build command
-2. Run test command
-3. Update `verificationResults` in state.json → **verify write**
-4. Update `status: "completed"` in state.json → **MANDATORY: verify write**
-5. Mark verification task `completed`
-6. Report to user