5-phase-workflow 1.5.4 → 1.6.0

package/bin/install.js

@@ -273,6 +273,7 @@ function getWorkflowManagedFiles() {
     hooks: [
       'statusline.js',
       'check-updates.js',
+      'check-reconfig.js',
       'plan-guard.js',
       'config-guard.js'
     ],
@@ -491,6 +492,7 @@ function showCommandsHelp(isGlobal) {
   log.info('  /5:verify-implementation - Verify implementation (Phase 4)');
   log.info('  /5:review-code          - Code review (Phase 5)');
   log.info('  /5:configure            - Interactive project setup');
+  log.info('  /5:reconfigure          - Refresh docs/skills (no Q&A)');
   log.info('  /5:unlock               - Remove planning guard lock');
   log.info('');
   log.info(`Config file: ${path.join(getDataPath(isGlobal), 'config.json')}`);

package/package.json

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

package/src/commands/5/configure.md

@@ -279,6 +279,12 @@ 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:**
+- "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
+    2. "No, track in git" — useful if you want to share specs and plans with your team
+
 ### Step 2.5: Write config.json
 
 Using the values gathered from Steps 1 and 2, write `.5/config.json` directly.
@@ -330,12 +336,37 @@ mkdir -p .5
     "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.
 
+**Update `.5/version.json` with configure timestamp:**
+
+After writing config.json, update `.5/version.json` so the reconfigure reminder can track staleness:
+1. Read `.5/version.json` (if it exists)
+2. Set `configuredAt` to the current ISO timestamp (`new Date().toISOString()`)
+3. Set `configuredAtCommit` to the current short commit hash (run `git rev-parse --short HEAD`)
+4. Write back `.5/version.json` preserving all other fields
+
+**Apply `.gitignore` if selected:**
+
+If the user chose to gitignore the `.5/features/` folder:
+1. Check if `.gitignore` exists in the project root
+2. If it exists, check if `.5/features/` is already listed — if not, append `.5/features/` on a new line
+3. If `.gitignore` does not exist, create it with `.5/features/` as the first entry
+4. Inform the user: "Added `.5/features/` to `.gitignore`"
+
+**Always gitignore `.5/.reconfig-reminder`:**
+
+Ensure `.5/.reconfig-reminder` is gitignored (it's a transient runtime flag that should never be committed):
+1. Check if `.gitignore` exists in the project root — create it if not
+2. Check if `.5/.reconfig-reminder` is already listed — if not, append `.5/.reconfig-reminder` on a new line
+
 ### Step 3: Create Feature Spec
 
 Write `.5/features/CONFIGURE/feature.md` containing all gathered data:

package/src/commands/5/reconfigure.md

@@ -0,0 +1,155 @@
+---
+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
+context: fork
+user-invocable: true
+---
+
+# Reconfigure (Lightweight Refresh)
+
+## Overview
+
+Single-command refresh that skips the full Q&A of `/5:configure`. Re-detects codebase state, regenerates documentation and skills based on existing `config.json` preferences.
+
+**When to use which:**
+
+| Scenario | Command |
+|----------|---------|
+| First-time setup | `/5:configure` |
+| Change preferences (ticket pattern, review tool, etc.) | `/5:configure` |
+| Codebase evolved, refresh docs/skills | **`/5:reconfigure`** |
+| Add new skill patterns | `/5:configure` |
+
+## ⚠️ CRITICAL SCOPE CONSTRAINT
+
+**THIS COMMAND REGENERATES DOCS AND SKILLS. IT DOES NOT CHANGE USER PREFERENCES.**
+
+Your job:
+✅ Validate that config.json exists
+✅ Re-detect codebase patterns and commands (same as configure Steps 1b-1h)
+✅ Compare detected state with config.json skill selections
+✅ Show summary and ask for confirmation
+✅ Invoke configure-project skill in refresh mode
+✅ Update version.json with artifacts and timestamps
+✅ Clean up .reconfig-reminder flag
+✅ Report what was updated
+
+Your job is NOT:
+❌ Ask preference questions (ticket pattern, branch convention, review tool, etc.)
+❌ Modify config.json preferences (only the `skills` section may be updated if user confirms new patterns)
+❌ Skip confirmation — always show what will be regenerated
+
+## Process
+
+### Step 1: Validate Config
+
+Read `.5/config.json`. If it does not exist:
+- Tell the user: "No configuration found. Please run `/5:configure` first to set up your project."
+- **EXIT IMMEDIATELY**
+
+Read `.5/version.json` for current state (configuredAt, configuredAtCommit).
+
+### Step 2: Re-detect Codebase State
+
+Perform the same detection as configure Steps 1b-1h:
+
+**2a. Detect project type** — same table as configure Step 1b (package.json deps, build files, etc.)
+
+**2b. Detect build/test commands** — same as configure Step 1c
+
+**2c. Detect codebase patterns** — same as configure Step 1g:
+- Scan for architectural patterns (Controllers, Services, Components, etc.)
+- Use both suffix-based and directory-based globs
+- For each pattern: count files, identify location, sample filename
+
+**2d. Detect runnable commands** — same as configure Step 1h:
+- Scan package.json scripts, Makefile targets, etc.
+- Categorize: Build, Test, Lint, Format, Type Check, etc.
+
+**2e. Scan existing skills** — list ALL skills in `.claude/skills/`:
+- Read each skill's SKILL.md frontmatter
+- Categorize as workflow-generated (create-*, run-*) or user-created
+
+### 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:
+
+- **Existing `create-*` skills** — extract the pattern name from each (e.g., `create-controller` → `controller`)
+- **Existing `run-*` skills** — extract the command name from each (e.g., `run-tests` → `tests`)
+- **New patterns**: detected in codebase (Step 2c) but no matching `create-*` skill exists → offer to create
+- **Stale patterns**: a `create-*` skill exists but the pattern is no longer detected in the codebase → offer to remove or keep
+- **New commands**: detected (Step 2d) but no matching `run-*` skill exists → offer to create
+- **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
+
+### 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?"
+
+Options:
+- "Proceed with refresh" — regenerate everything as shown
+- "Cancel" — exit without changes
+
+If there are new or stale patterns, use additional `AskUserQuestion` calls with multiSelect to let the user pick which new patterns to add and which stale patterns to remove.
+
+New skills will be created and stale skills removed based on the user's choices.
+
+### Step 5: Regenerate
+
+Invoke the `configure-project` skill in **refresh mode** via the Task tool:
+
+```
+Task prompt: "Run configure-project skill in REFRESH MODE.
+
+Refresh ALL existing skills in .claude/skills/:
+- Existing create-* skills: [list from Step 2e]
+- Existing run-* skills: [list from Step 2e]
+- User-created skills: [list from Step 2e]
+- New skills to create: [list from user confirmation, if any]
+- Skills to remove: [list from user confirmation, if any]
+
+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"
+```
+
+Use `subagent_type: "general-purpose"` for the Task.
+
+### Step 6: Track
+
+After the skill completes, update `.5/version.json`:
+
+1. Read current version.json
+2. Set `configuredAt` to current ISO timestamp
+3. Set `configuredAtCommit` to current short commit hash (`git rev-parse --short HEAD`)
+4. Write back version.json preserving all other fields
+
+### Step 7: Clean Up
+
+Remove the `.5/.reconfig-reminder` flag file if it exists:
+```bash
+rm -f .5/.reconfig-reminder
+```
+
+### Step 8: Report
+
+Show the user a summary:
+- List of documentation files updated
+- List of skills refreshed
+- List of new skills created (if any)
+- List of skills removed (if any)
+- Timestamp of reconfiguration
+- Suggest running `/clear` to reset context
+
+## Related Documentation
+- [configure command](./configure.md) — full Q&A configuration
+- [configure-project skill](../../skills/configure-project/SKILL.md) — the skill that does the heavy lifting

package/src/hooks/check-reconfig.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Read JSON from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    let workspaceDir = process.cwd();
+    if (input.trim()) {
+      const data = JSON.parse(input);
+      workspaceDir = data.cwd || data.workspace?.current_dir || workspaceDir;
+    }
+
+    checkReconfigure(workspaceDir);
+  } catch (e) {
+    // Silent failure - don't block on errors
+    process.exit(0);
+  }
+});
+
+function checkReconfigure(workspaceDir) {
+  const versionFile = path.join(workspaceDir, '.5', 'version.json');
+  const flagFile = path.join(workspaceDir, '.5', '.reconfig-reminder');
+
+  if (!fs.existsSync(versionFile)) {
+    process.exit(0);
+  }
+
+  let versionData;
+  try {
+    versionData = JSON.parse(fs.readFileSync(versionFile, 'utf8'));
+  } catch (e) {
+    process.exit(0);
+  }
+
+  const { configuredAt, configuredAtCommit } = versionData;
+
+  // No configure data yet - skip (user hasn't run /5:configure)
+  if (!configuredAt) {
+    process.exit(0);
+  }
+
+  // Calculate days elapsed
+  let daysElapsed = 0;
+  try {
+    daysElapsed = Math.floor((Date.now() - new Date(configuredAt).getTime()) / (1000 * 60 * 60 * 24));
+  } catch (e) {
+    process.exit(0);
+  }
+
+  // Count commits since configured
+  let commitCount = 0;
+  if (configuredAtCommit) {
+    try {
+      const result = execSync(`git rev-list --count ${configuredAtCommit}..HEAD`, {
+        cwd: workspaceDir,
+        timeout: 3000,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+      commitCount = parseInt(result.trim(), 10) || 0;
+    } catch (e) {
+      // Git command failed (commit not found, not a repo, etc.) - skip
+    }
+  }
+
+  // Write or remove temp flag file (never touches version.json)
+  const COMMIT_THRESHOLD = 50;
+  const DAYS_THRESHOLD = 30;
+  const shouldRemind = daysElapsed >= DAYS_THRESHOLD || commitCount >= COMMIT_THRESHOLD;
+
+  try {
+    if (shouldRemind) {
+      fs.writeFileSync(flagFile, '1');
+    } else if (fs.existsSync(flagFile)) {
+      fs.unlinkSync(flagFile);
+    }
+  } catch (e) {
+    // Can't write/delete temp file - skip
+  }
+
+  process.exit(0);
+}

package/src/hooks/statusline.js

@@ -43,22 +43,31 @@ process.stdin.on('end', () => {
     // Shorten directory path for display
     const shortDir = dir.replace(os.homedir(), '~');
 
-    // Check for available update
+    // Check for available update and reconfigure reminder
     let updateIndicator = '';
+    let reconfigIndicator = '';
     try {
       const versionFile = path.join(dir, '.5', 'version.json');
       const versionData = JSON.parse(fs.readFileSync(versionFile, 'utf8'));
+
+      // Update check
       const latest = versionData.latestAvailableVersion;
       const installed = versionData.installedVersion;
       if (latest && installed && compareVersions(installed, latest) < 0) {
         updateIndicator = ` | \x1b[33m↑${latest} → /5:update\x1b[0m`;
       }
+
+      // Reconfigure check (reads flag file in .5/, gitignored)
+      const flagFile = path.join(dir, '.5', '.reconfig-reminder');
+      if (fs.existsSync(flagFile)) {
+        reconfigIndicator = ` | \x1b[35m↻ /5:reconfigure\x1b[0m`;
+      }
     } catch (e) {
       // No version file or parse error — no indicator
     }
 
-    // Build and output statusline: model | directory | context | update
-    const statusline = `\x1b[36m${model}\x1b[0m | \x1b[90m${shortDir}\x1b[0m${ctx}${updateIndicator}`;
+    // Build and output statusline: model | directory | context | update | reconfig
+    const statusline = `\x1b[36m${model}\x1b[0m | \x1b[90m${shortDir}\x1b[0m${ctx}${updateIndicator}${reconfigIndicator}`;
     process.stdout.write(statusline);
 
   } catch (e) {

package/src/settings.json

@@ -14,6 +14,16 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/check-reconfig.js",
+            "timeout": 10
+          }
+        ]
       }
     ],
     "PreToolUse": [

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

@@ -22,6 +22,29 @@ Note: config.json is written directly by `/5:configure` during the Q&A phase.
 
 ---
 
+## Modes
+
+This skill supports two modes. The analysis (A1), template filling (A2-A3), CLAUDE.md update (A4-A5), and skill generation (B) logic is the same in both modes — only the **input source** changes.
+
+### Full Mode (default)
+
+Used by `/5:configure` → `/5:implement-feature CONFIGURE` flow.
+
+- **Input:** Pattern/command selections from feature spec (`.5/features/CONFIGURE/feature.md`)
+- **Behavior:** Creates everything from scratch based on feature spec requirements
+
+### Refresh Mode
+
+Used by `/5:reconfigure` for lightweight refresh.
+
+- **Input:** The Task prompt lists which skills to refresh, create, and remove (determined by `/5:reconfigure` after scanning `.claude/skills/` and comparing with detected codebase patterns)
+- **Behavior:** Re-analyzes codebase, overwrites docs and refreshes/creates/removes skills as specified
+- **Trigger:** Task prompt includes "REFRESH MODE"
+
+In both modes, the analysis and generation logic is identical — only where the skill list comes from differs.
+
+---
+
 ## A. Analyze Codebase and Create/Update CLAUDE.md
 
 **Process:**