5-phase-workflow 1.4.3 → 1.5.0

package/src/hooks/check-updates.js

@@ -23,7 +23,7 @@ process.stdin.on('end', () => {
 });
 
 async function checkForUpdates(workspaceDir) {
-  const versionFile = path.join(workspaceDir, '.claude', '.5', 'version.json');
+  const versionFile = path.join(workspaceDir, '.5', 'version.json');
 
   // Check if version.json exists
   if (!fs.existsSync(versionFile)) {
@@ -104,9 +104,10 @@ async function getLatestVersion() {
 }
 
 // Compare semver versions
+// Uses parseInt to handle pre-release tags (e.g., "2-beta" → 2)
 function compareVersions(v1, v2) {
-  const parts1 = v1.split('.').map(Number);
-  const parts2 = v2.split('.').map(Number);
+  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;

package/src/hooks/config-guard.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const cwd = data.cwd || process.cwd();
+    const configFile = path.join(cwd, '.5', 'config.json');
+
+    if (fs.existsSync(configFile)) {
+      process.exit(0);
+    }
+
+    // No config — block with helpful message
+    process.stderr.write(
+      'Configuration not found. Please run /5:configure first to set up your project.\n\n' +
+      'The configure command will:\n' +
+      '  - Detect your project type and build commands\n' +
+      '  - Set up ticket tracking conventions\n' +
+      '  - Write project configuration'
+    );
+    process.exit(2);
+  } catch (e) {
+    process.exit(0); // Silent failure — don't block on parse errors
+  }
+});

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,24 @@ 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();
+
+    // If no planning phase is active, allow all tools
+    if (!isPlanningActive(workspaceDir)) {
+      process.exit(0);
+    }
+
     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
@@ -40,20 +47,22 @@ process.stdin.on('end', () => {
         process.stderr.write(
           `BLOCKED: Only Explore agents are allowed during planning phases. ` +
           `Attempted: subagent_type="${agentType}". ` +
-          `To use other agent types, start implementation with /5:implement-feature.`
+          `To use other agent types, start implementation with /5:implement-feature. ` +
+          `If you're not in a planning phase, run /5:unlock to clear the planning lock.`
         );
         process.exit(2);
       }
     }
 
-    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. ` +
+          `If you're not in a planning phase, run /5:unlock to clear the planning lock.`
         );
         process.exit(2);
       }
@@ -69,35 +78,73 @@ process.stdin.on('end', () => {
 function isInsideDotFive(filePath, workspaceDir) {
   const resolved = path.resolve(workspaceDir, filePath);
   const dotFiveDir = path.join(workspaceDir, '.5');
-  const claudeDotFiveDir = path.join(workspaceDir, '.claude', '.5');
   return resolved.startsWith(dotFiveDir + path.sep) ||
-         resolved.startsWith(claudeDotFiveDir + path.sep) ||
-         resolved === dotFiveDir ||
-         resolved === claudeDotFiveDir;
+         resolved === dotFiveDir;
 }
 
-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".
-  const featuresDir = path.join(workspaceDir, '.claude', '.5', 'features');
+function getTargetFeature(toolName, toolInput, workspaceDir) {
+  // Extract the feature name from the tool input context
+  const featuresDir = path.join(workspaceDir, '.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: .5/features/{feature-name}/...
+      const relative = resolved.slice(featuresDir.length + 1);
+      const featureName = relative.split(path.sep)[0];
+      if (featureName) return featureName;
+    }
   }
 
+  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
+    }
+  }
+
+  return null;
+}
+
+function isPlanningActive(workspaceDir) {
+  const markerPath = path.join(workspaceDir, '.5', '.planning-active');
+  if (!fs.existsSync(markerPath)) return false;
   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;
+    const marker = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+    if (marker.startedAt) {
+      const elapsed = Date.now() - new Date(marker.startedAt).getTime();
+      if (elapsed > 4 * 60 * 60 * 1000) {
+        try { fs.unlinkSync(markerPath); } catch (e) {}
+        return false;
       }
     }
+    return true;
   } catch (e) {
-    // Can't read features dir - assume planning mode (safe default)
+    return true; // Unreadable marker → fail-safe, assume active
   }
+}
 
-  return false;
+function isFeatureInImplementationMode(workspaceDir, featureName) {
+  // Check if this specific feature has a state.json (created in Phase 3)
+  const stateFile = path.join(
+    workspaceDir, '.5', 'features', featureName, 'state.json'
+  );
+  return fs.existsSync(stateFile);
 }

package/src/hooks/statusline.js

@@ -46,7 +46,7 @@ process.stdin.on('end', () => {
     // Check for available update
     let updateIndicator = '';
     try {
-      const versionFile = path.join(dir, '.claude', '.5', 'version.json');
+      const versionFile = path.join(dir, '.5', 'version.json');
       const versionData = JSON.parse(fs.readFileSync(versionFile, 'utf8'));
       const latest = versionData.latestAvailableVersion;
       const installed = versionData.installedVersion;
@@ -67,9 +67,10 @@ process.stdin.on('end', () => {
 });
 
 // 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(Number);
-  const parts2 = v2.split('.').map(Number);
+  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;

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

@@ -17,7 +17,7 @@ This skill executes build tasks with auto-detection of the build system and suff
 
 The skill automatically detects the build system using:
 
-1. **Config file** (`.claude/.5/config.json`) - if `build.command` is specified
+1. **Config file** (`.5/config.json`) - if `build.command` is specified
 2. **Auto-detection** - by examining project files:
    - `package.json` → npm/yarn/pnpm
    - `build.gradle` or `build.gradle.kts` → Gradle
@@ -46,7 +46,7 @@ When invoked, the skill expects:
 
 ### 1. Load Configuration
 
-Read `.claude/.5/config.json` if it exists:
+Read `.5/config.json` if it exists:
 
 ```json
 {
@@ -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