5-phase-workflow 1.4.2 → 1.4.4

package/src/hooks/plan-guard.js

@@ -3,11 +3,11 @@
 // Plan Guard - PreToolUse Hook
 // Prevents LLM breakout from planning phases by blocking:
 // - Task agents other than Explore (when not in implementation mode)
-// - Write operations outside .5/ (when not in implementation mode)
+// - Write/Edit operations outside .5/ (when not in implementation mode)
 //
-// Planning mode is detected by absence of any state.json in .5/features/.
-// Once state.json exists (created in Phase 3), the feature has passed planning
-// and all tools are allowed (implementation, verification, review phases).
+// Planning mode is detected per-feature by checking if that specific feature's
+// state.json exists. Only the feature in implementation mode gets unrestricted
+// tool access. Other features remain in planning mode.
 
 const fs = require('fs');
 const path = require('path');
@@ -20,17 +20,18 @@ process.stdin.on('end', () => {
     const data = JSON.parse(input);
     const toolName = data.tool_name || '';
 
-    // Short-circuit: only check Task and Write tools
-    if (toolName !== 'Task' && toolName !== 'Write') {
+    // Short-circuit: only check Task, Write, and Edit tools
+    if (toolName !== 'Task' && toolName !== 'Write' && toolName !== 'Edit') {
       process.exit(0);
     }
 
     const workspaceDir = data.cwd || data.workspace?.current_dir || process.cwd();
     const toolInput = data.tool_input || {};
 
-    // Check if any feature is in implementation mode
-    if (isImplementationMode(workspaceDir)) {
-      process.exit(0); // All tools allowed during implementation
+    // Determine which feature is being targeted and check its state
+    const targetFeature = getTargetFeature(toolName, toolInput, workspaceDir);
+    if (targetFeature && isFeatureInImplementationMode(workspaceDir, targetFeature)) {
+      process.exit(0); // Tools allowed for features in implementation mode
     }
 
     // Planning mode enforcement
@@ -46,14 +47,14 @@ process.stdin.on('end', () => {
       }
     }
 
-    if (toolName === 'Write') {
+    if (toolName === 'Write' || toolName === 'Edit') {
       const filePath = toolInput.file_path || '';
       if (filePath && !isInsideDotFive(filePath, workspaceDir)) {
         process.stderr.write(
-          `BLOCKED: Writing outside .5/ is not allowed during planning phases. ` +
+          `BLOCKED: ${toolName} outside .5/ is not allowed during planning phases. ` +
           `Attempted: "${filePath}". ` +
           `Planning commands may only write to .5/features/. ` +
-          `To write source files, start implementation with /5:implement-feature.`
+          `To modify source files, start implementation with /5:implement-feature.`
         );
         process.exit(2);
       }
@@ -76,28 +77,51 @@ function isInsideDotFive(filePath, workspaceDir) {
          resolved === claudeDotFiveDir;
 }
 
-function isImplementationMode(workspaceDir) {
-  // If any state.json exists, the feature has passed planning phases.
-  // state.json is created in Phase 3 (implement-feature) and persists
-  // through Phase 4 (verify) and Phase 5 (review) with status "completed".
+function getTargetFeature(toolName, toolInput, workspaceDir) {
+  // Extract the feature name from the tool input context
   const featuresDir = path.join(workspaceDir, '.claude', '.5', 'features');
 
-  if (!fs.existsSync(featuresDir)) {
-    return false;
+  if (toolName === 'Write' || toolName === 'Edit') {
+    // Check if the file path is inside a feature directory
+    const filePath = toolInput.file_path || '';
+    const resolved = path.resolve(workspaceDir, filePath);
+    if (resolved.startsWith(featuresDir + path.sep)) {
+      // Extract feature name: .claude/.5/features/{feature-name}/...
+      const relative = resolved.slice(featuresDir.length + 1);
+      const featureName = relative.split(path.sep)[0];
+      if (featureName) return featureName;
+    }
   }
 
-  try {
-    const features = fs.readdirSync(featuresDir, { withFileTypes: true });
-    for (const entry of features) {
-      if (!entry.isDirectory()) continue;
-      const stateFile = path.join(featuresDir, entry.name, 'state.json');
-      if (fs.existsSync(stateFile)) {
-        return true;
+  if (toolName === 'Task') {
+    // Check the task prompt for feature name references
+    const prompt = toolInput.prompt || '';
+    const desc = toolInput.description || '';
+    const combined = prompt + ' ' + desc;
+
+    // Try to match a feature directory that exists
+    try {
+      if (fs.existsSync(featuresDir)) {
+        const features = fs.readdirSync(featuresDir, { withFileTypes: true });
+        for (const entry of features) {
+          if (!entry.isDirectory()) continue;
+          if (combined.includes(entry.name)) {
+            return entry.name;
+          }
+        }
       }
+    } catch (e) {
+      // Ignore read errors
     }
-  } catch (e) {
-    // Can't read features dir - assume planning mode (safe default)
   }
 
-  return false;
+  return null;
+}
+
+function isFeatureInImplementationMode(workspaceDir, featureName) {
+  // Check if this specific feature has a state.json (created in Phase 3)
+  const stateFile = path.join(
+    workspaceDir, '.claude', '.5', 'features', featureName, 'state.json'
+  );
+  return fs.existsSync(stateFile);
 }

package/src/hooks/statusline.js

@@ -43,11 +43,37 @@ process.stdin.on('end', () => {
     // Shorten directory path for display
     const shortDir = dir.replace(os.homedir(), '~');
 
-    // Build and output statusline: model | directory | context
-    const statusline = `\x1b[36m${model}\x1b[0m | \x1b[90m${shortDir}\x1b[0m${ctx}`;
+    // Check for available update
+    let updateIndicator = '';
+    try {
+      const versionFile = path.join(dir, '.claude', '.5', 'version.json');
+      const versionData = JSON.parse(fs.readFileSync(versionFile, 'utf8'));
+      const latest = versionData.latestAvailableVersion;
+      const installed = versionData.installedVersion;
+      if (latest && installed && compareVersions(installed, latest) < 0) {
+        updateIndicator = ` | \x1b[33m↑${latest} → /5:update\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}`;
     process.stdout.write(statusline);
 
   } catch (e) {
     // Silent fail - don't break statusline on parse errors
   }
-});
+});
+
+// Compare semver versions: returns -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+// Uses parseInt to handle pre-release tags (e.g., "2-beta" → 2)
+function compareVersions(v1, v2) {
+  const parts1 = v1.split('.').map(p => parseInt(p, 10) || 0);
+  const parts2 = v2.split('.').map(p => parseInt(p, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    if (parts1[i] > parts2[i]) return 1;
+    if (parts1[i] < parts2[i]) return -1;
+  }
+  return 0;
+}

package/src/settings.json

@@ -18,7 +18,17 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "",
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/config-guard.js",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Task|Write|Edit",
         "hooks": [
           {
             "type": "command",

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

@@ -62,46 +62,7 @@ If commands are specified, use them. Otherwise, auto-detect.
 
 ### 2. Detect Build System
 
-If no config, examine project files to detect build system:
-
-```bash
-# Check for package.json
-if [ -f "package.json" ]; then
-  # Check for lock files to determine package manager
-  if [ -f "pnpm-lock.yaml" ]; then
-    BUILD_TOOL="pnpm"
-  elif [ -f "yarn.lock" ]; then
-    BUILD_TOOL="yarn"
-  else
-    BUILD_TOOL="npm"
-  fi
-fi
-
-# Check for Gradle
-if [ -f "build.gradle" ] || [ -f "build.gradle.kts" ]; then
-  BUILD_TOOL="gradle"
-fi
-
-# Check for Maven
-if [ -f "pom.xml" ]; then
-  BUILD_TOOL="mvn"
-fi
-
-# Check for Cargo
-if [ -f "Cargo.toml" ]; then
-  BUILD_TOOL="cargo"
-fi
-
-# Check for Go
-if [ -f "go.mod" ]; then
-  BUILD_TOOL="go"
-fi
-
-# Check for Make
-if [ -f "Makefile" ]; then
-  BUILD_TOOL="make"
-fi
-```
+If no config, detect by checking project files: `package.json` + lock files (npm/yarn/pnpm), `build.gradle` (gradle), `pom.xml` (mvn), `Cargo.toml` (cargo), `go.mod` (go), `Makefile` (make).
 
 ### 3. Determine Build Command
 
@@ -133,45 +94,7 @@ Execute the command and capture output.
 
 ### 5. Parse Build Output
 
-Analyze output to identify:
-
-#### Success Indicators
-
-Tool-specific success patterns:
-- npm/yarn/pnpm: No error messages, process exits with 0
-- Gradle: `BUILD SUCCESSFUL`
-- Maven: `BUILD SUCCESS`
-- Cargo: `Finished` or `Compiling`
-- Go: No error output
-- Make: No error messages
-
-#### Error Types
-
-**Compilation Errors**:
-```
-/path/to/file.ext:42: error: ...
-```
-Extract: file path, line number, error message
-
-**Dependency Issues**:
-```
-Could not resolve dependencies
-Module not found
-```
-Suggest: `npm install`, `./gradlew --refresh-dependencies`, etc.
-
-**Out of Memory**:
-```
-JavaScript heap out of memory
-Java heap space
-```
-Suggest: Increase memory allocation
-
-**Tool Not Found**:
-```
-command not found: npm
-```
-Suggest: Install the build tool
+Determine success/failure from tool-specific patterns (exit code, `BUILD SUCCESSFUL`, `BUILD SUCCESS`, `Finished`, etc.). For failures, extract file paths, line numbers, and error messages. Identify error type (compilation, dependency, memory, tool not found) and suggest appropriate fix.
 
 ### 6. Format Output
 
@@ -200,28 +123,6 @@ SUGGESTIONS:
 - {actionable suggestion based on error type}
 ```
 
-## Common Build Scenarios
-
-### First-Time Build
-
-May fail with dependency issues. Suggestions:
-- npm: `npm install`
-- gradle: Remove `--offline` flag temporarily
-- cargo: `cargo fetch`
-
-### Incremental Build Issues
-
-Stale cache or artifacts. Suggestions:
-- Try `clean` target
-- Clear cache manually
-
-### Memory Issues
-
-Build runs out of memory. Suggestions:
-- npm: `export NODE_OPTIONS="--max-old-space-size=4096"`
-- gradle: Add `org.gradle.jvmargs=-Xmx4g` to `gradle.properties`
-- maven: `export MAVEN_OPTS="-Xmx4g"`
-
 ## Error Handling
 
 - If build tool cannot be detected, return error with list of checked locations
@@ -237,38 +138,11 @@ Build runs out of memory. Suggestions:
 - DO NOT assume a specific build system - always detect or use config
 - DO NOT use overly short timeouts (builds can be slow)
 
-## Examples
-
-### Example 1: Auto-detect npm and build
+## Example
 
 ```
 User: /build-project
-
-Skill: [Detects package.json, uses npm]
-Skill: [Runs: npm run build]
-Skill: [Reports success with duration]
-```
-
-### Example 2: Gradle with module
-
-```
-User: /build-project module=user-service
-
-Skill: [Detects build.gradle]
-Skill: [Runs: ./gradlew :user-service:build -x test --offline]
-Skill: [Reports success]
-```
-
-### Example 3: Build failure
-
-```
-User: /build-project
-
-Skill: [Detects Cargo.toml]
-Skill: [Runs: cargo build]
-Skill: [Detects compilation error]
-Skill: [Reports: File src/main.rs:42, Error: mismatched types]
-Skill: [Suggests: Fix type error in src/main.rs:42]
+Skill: [Detects npm] → [Runs: npm run build] → [Reports success with duration]
 ```
 
 ## Related Documentation

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

@@ -1,6 +1,6 @@
 ---
 name: configure-project
-description: Creates project configuration files, analyzes codebase for CLAUDE.md, and generates project-specific skills. Used during /5:implement-feature CONFIGURE.
+description: Analyzes codebase for CLAUDE.md and generates project-specific skills. Used during /5:implement-feature CONFIGURE.
 allowed-tools: Read, Write, Bash, Glob, Grep
 model: sonnet
 context: fork
@@ -13,76 +13,20 @@ user-invocable: false
 
 This skill does the heavy lifting during Phase 3 (implement-feature) for the CONFIGURE feature. It is called by step-executor to create the actual configuration files.
 
-It handles three distinct tasks, invoked with different parameters per component:
+It handles two distinct tasks, invoked with different parameters per component:
 
-- **A. Write config.json** - Creates the project configuration file
-- **B. Analyze Codebase and Create/Update CLAUDE.md** - Maps codebase and documents conventions
-- **C. Generate Project-Specific Skills** - Creates SKILL.md files for common project patterns
+- **A. Analyze Codebase and Create/Update CLAUDE.md** - Maps codebase and documents conventions
+- **B. Generate Project-Specific Skills** - Creates SKILL.md files for common project patterns
 
----
-
-## A. Write config.json
-
-**Receives:** project type, ticket config, branch config, build/test commands, tool availability
-
-**Creates:** `.claude/.5/config.json`
-
-**Schema (no `steps` array):**
-
-```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" or "coderabbit" or "none",
-  "git": {
-    "autoCommit": false,
-    "commitMessage": {
-      "pattern": "{ticket-id} {short-description}"
-    }
-  }
-}
-```
-
-**Process:**
-1. Read all values from the feature spec (`.5/features/CONFIGURE/feature.md`), including `git.autoCommit` and `git.commitMessage.pattern`
-2. Ensure `.claude/.5/` directory exists (create with `mkdir -p` if needed)
-3. Write `config.json` with pretty-printed JSON
-4. Read back to verify correctness
+Note: config.json is written directly by `/5:configure` during the Q&A phase.
 
 ---
 
-## B. Analyze Codebase and Create/Update CLAUDE.md
+## A. Analyze Codebase and Create/Update CLAUDE.md
 
 **Process:**
 
-### B1. Unified Codebase Analysis
+### A1. Unified Codebase Analysis
 
 Perform comprehensive analysis once to gather data for ALL templates:
 
@@ -140,7 +84,7 @@ Perform comprehensive analysis once to gather data for ALL templates:
 - Identify deprecated dependencies (check for warnings in package manifests)
 - Look for complex code sections (deeply nested conditionals, long functions)
 
-### B2. Fill Templates
+### A2. Fill Templates
 
 For each template in `src/templates/`:
 
@@ -177,7 +121,7 @@ INTEGRATIONS.md:
 CONCERNS.md:
 - `{file paths}` → Actual file paths from grep results
 
-### B3. Write Documentation Files
+### A3. Write Documentation Files
 
 Write filled templates to `.5/` folder:
 
@@ -191,63 +135,18 @@ Write filled templates to `.5/` folder:
    - `.5/INTEGRATIONS.md`
    - `.5/CONCERNS.md`
 
-### B4. Create Master CLAUDE.md
+### A4. Create Master CLAUDE.md
 
 Generate CLAUDE.md as a navigation hub:
 
-```markdown
-# {Project Name}
-
-> Generated: {YYYY-MM-DD}
-> Documentation is organized into focused files for better maintainability
-
-## Quick Reference
-
-- [Technology Stack](./.5/STACK.md) - Languages, frameworks, dependencies
-- [Codebase Structure](./.5/STRUCTURE.md) - Directory layout and organization
-- [Architecture](./.5/ARCHITECTURE.md) - Patterns, layers, and data flow
-- [Coding Conventions](./.5/CONVENTIONS.md) - Naming, style, and patterns
-- [Testing Patterns](./.5/TESTING.md) - Test framework and patterns
-- [External Integrations](./.5/INTEGRATIONS.md) - APIs, databases, services
-- [Codebase Concerns](./.5/CONCERNS.md) - Tech debt, bugs, and risks
-
-## Project Overview
-
-{1-2 paragraph summary from README or package.json description}
-
-## Build & Run Commands
-
-- Build: `{build-command}`
-- Test: `{test-command}`
-- {Other detected scripts}
-
-## Coding Guidelines
-
-When working with this codebase, follow these principles:
-
-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
-3. Keep files short and structured
-4. Extract methods, classes
-5. Respect SRP and DRY
-6. Make code maintainable and modular
-
-## Getting Started
-
-**For new developers:**
-1. Review [Stack](./.5/STACK.md) for technology overview
-2. Read [Structure](./.5/STRUCTURE.md) to understand organization
-3. Study [Conventions](./.5/CONVENTIONS.md) for coding standards
-4. Check [Architecture](./.5/ARCHITECTURE.md) for design patterns
-
-**For specific tasks:**
-- Adding features → See [Architecture](./.5/ARCHITECTURE.md)
-- Writing tests → See [Testing](./.5/TESTING.md)
-- Integration work → See [Integrations](./.5/INTEGRATIONS.md)
-- Reviewing concerns → See [Concerns](./.5/CONCERNS.md)
-```
+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
+- **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
 
-### B5. Preserve Existing Content
+### A5. Preserve Existing Content
 
 If CLAUDE.md already exists:
 - Read current content
@@ -257,7 +156,7 @@ If CLAUDE.md already exists:
 
 ---
 
-## C. Generate Project-Specific Skills
+## B. Generate Project-Specific Skills
 
 **Reads:** Pattern selections from feature spec (`.5/CONFIGURE/feature.md`)
 
@@ -324,85 +223,11 @@ Based on {example-file}, new {patterns} should follow:
 
 ### Pattern to Skill Name Mapping
 
-| Detected Pattern | Skill Name |
-|------------------|------------|
-| **Core Architecture** | |
-| controller | create-controller |
-| service | create-service |
-| repository | create-repository |
-| model/entity | create-model |
-| handler | create-handler |
-| **Data Transfer** | |
-| dto | create-dto |
-| request | create-request |
-| response | create-response |
-| mapper | create-mapper |
-| validator | create-validator |
-| schema | create-schema |
-| **Frontend** | |
-| component | create-component |
-| hook | create-hook |
-| context | create-context |
-| store | create-store |
-| page | create-page |
-| layout | create-layout |
-| **API/Routes** | |
-| api-route | create-api-route |
-| middleware | create-middleware |
-| guard | create-guard |
-| interceptor | create-interceptor |
-| filter | create-filter |
-| **Testing** | |
-| test | create-test |
-| spec | create-spec |
-| fixture | create-fixture |
-| factory | create-factory |
-| mock | create-mock |
-| **Utilities** | |
-| util | create-util |
-| helper | create-helper |
-| constant | create-constant |
-| type | create-type |
-| config | create-config |
-| **Framework-Specific** | |
-| module | create-module |
-| pipe | create-pipe |
-| decorator | create-decorator |
-| blueprint | create-blueprint |
-| view | create-view |
-| serializer | create-serializer |
-| **Background/Async** | |
-| job | create-job |
-| worker | create-worker |
-| event | create-event |
-| listener | create-listener |
-| command | create-command |
-| **Database** | |
-| migration | create-migration |
-| seed | create-seed |
-| **Error Handling** | |
-| exception | create-exception |
-| error | create-error |
-
-### Why `user-invocable: true`
-
-Generated skills are user-invocable so users can invoke them directly:
-- `/create-controller UserController`
-- `/create-component Button`
-- `/create-service AuthService`
-
-This is more useful than internal-only skills.
-
-### Why `model: haiku`
-
-Pattern-following is simple once conventions are documented:
-- Faster and cheaper than sonnet
-- Deep analysis already happened during generation
-- The skill just needs to follow the documented template
+**Rule:** Skill name is `create-{pattern}` (e.g., `controller` → `create-controller`, `component` → `create-component`, `dto` → `create-dto`). For compound patterns, use the short form: `model/entity` → `create-model`, `api-route` → `create-api-route`.
 
 ---
 
-## C2. Generate Command Skills (run-*)
+## B2. Generate Command Skills (run-*)
 
 **Reads:** Command selections from feature spec (`.5/CONFIGURE/feature.md`)
 
@@ -469,20 +294,7 @@ Executes the project's {command} command.
 
 ### Command to Skill Name Mapping
 
-| Detected Command | Skill Name |
-|------------------|------------|
-| build | run-build |
-| test, spec | run-tests |
-| lint, eslint | run-lint |
-| format, prettier | run-format |
-| typecheck, tsc | run-typecheck |
-| dev, start | run-dev |
-| db:migrate, migrate | run-migrate |
-| db:seed, seed | run-seed |
-| docker:build | run-docker-build |
-| docker:up, compose up | run-docker-up |
-| clean | run-clean |
-| generate, codegen | run-generate |
+**Rule:** Skill name is `run-{category}` (e.g., `build` → `run-build`, `test`/`spec` → `run-tests`, `lint` → `run-lint`). Group variants under the primary category name.
 
 ---
 
@@ -491,8 +303,7 @@ Executes the project's {command} command.
 Returns structured results for each component:
 
 ```
-Component A (config.json): SUCCESS - Created .claude/.5/config.json
-Component B (Documentation): SUCCESS - Created 7 documentation files + index
+Component A (Documentation): SUCCESS - Created 7 documentation files + index
   - .5/ARCHITECTURE.md (Pattern: Layered, 4 layers identified)
   - .5/STACK.md (TypeScript + Express, 23 dependencies)
   - .5/STRUCTURE.md (8 top-level directories mapped)
@@ -501,15 +312,15 @@ Component B (Documentation): SUCCESS - Created 7 documentation files + index
   - .5/INTEGRATIONS.md (PostgreSQL, 2 APIs, GitHub Actions)
   - .5/CONCERNS.md (3 TODO items, 1 deprecated dependency)
   - CLAUDE.md (index with references)
-Component C (Pattern Skills): SUCCESS - Generated 3 create-* skills (create-component, create-hook, create-context)
-Component D (Command Skills): SUCCESS - Generated 2 run-* skills (run-tests, run-lint)
+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)
 ```
 
 Or on failure:
 
 ```
-Component A (config.json): FAILED - Permission denied writing to .claude/.5/
-Component B (Documentation): FAILED - Unable to read template files
+Component A (Documentation): FAILED - Unable to read template files
+Component B (Pattern Skills): FAILED - No patterns found in codebase
 ```
 
 ## DO NOT