5-phase-workflow 1.4.4 → 1.5.0

package/README.md

@@ -126,10 +126,11 @@ All commands are available under the `/5:` namespace:
 | `/5:verify-implementation` | 4 | Verify completeness and correctness |
 | `/5:review-code` | 5 | AI-powered code review (CodeRabbit) |
 | `/5:quick-implement` | Fast | Streamlined workflow for small tasks |
+| `/5:unlock` | Utility | Remove planning guard lock |
 
 ## Configuration
 
-The workflow is configured via `.claude/.5/config.json`. Here's an example:
+The workflow is configured via `.5/config.json`. Here's an example:
 
 ```json
 {
@@ -181,7 +182,7 @@ Claude asks 5-10 clarifying questions to understand your requirements:
 - How will we verify it works?
 - Are there simpler alternatives?
 
-The output is a comprehensive feature spec at `.claude/.features/{ticket-id}.md`.
+The output is a comprehensive feature spec at `.5/features/{ticket-id}/feature.md`.
 
 ### Phase 2: Implementation Planning
 
@@ -207,7 +208,7 @@ Claude executes the plan using specialized agents:
 - **step-verifier**: Compiles and checks for errors after each step
 - **integration-agent**: Wires components and registers routes
 
-State is tracked in `.claude/.implementations/state/{ticket-id}.json` for resumability.
+State is tracked in `.5/features/{ticket-id}/state.json` for resumability.
 
 ### Phase 4: Verify Implementation
 
@@ -234,9 +235,12 @@ Automated review using CodeRabbit (if installed):
 After installation, your `.claude/` directory will contain:
 
 ```
+.5/
+├── config.json               # Project configuration
+├── version.json              # Version tracking
+└── features/                 # Feature tracking
+
 .claude/
-├── .5/
-│   └── config.json           # Project configuration
 ├── commands/5/               # Workflow commands
 │   ├── plan-feature.md
 │   ├── plan-implementation.md
@@ -245,13 +249,17 @@ After installation, your `.claude/` directory will contain:
 │   ├── review-code.md
 │   ├── discuss-feature.md
 │   ├── quick-implement.md
-│   └── configure.md
+│   ├── configure.md
+│   └── unlock.md
 ├── skills/                   # Atomic operations
 │   ├── build-project/
 │   ├── run-tests/
 │   └── generate-readme/
 ├── hooks/
-│   └── statusline.js         # Status line integration
+│   ├── statusline.js         # Status line integration
+│   ├── check-updates.js      # Update notifications
+│   ├── plan-guard.js         # Planning phase edit guard
+│   └── config-guard.js       # Configuration guard
 └── settings.json             # Claude Code settings
 ```
 
@@ -293,7 +301,7 @@ After installation, your `.claude/` directory will contain:
 
 1. Run `/5:configure` to verify configuration
 2. Test commands manually in terminal
-3. Update `.claude/.5/config.json` with correct commands
+3. Update `.5/config.json` with correct commands
 
 ### "Cannot find project type"
 
@@ -303,7 +311,7 @@ The auto-detection failed. Run `/5:configure` and manually select your project t
 
 If implementation gets stuck:
 
-1. Check `.claude/.implementations/state/{ticket-id}.json`
+1. Check `.5/features/{ticket-id}/state.json`
 2. Note the `currentStep` value
 3. Run `/5:implement-feature` again - it will resume from that step
 
@@ -338,7 +346,7 @@ npx 5-phase-workflow
 ```
 
 **Note:** During updates:
-- Config files in `.claude/.5/` are preserved
+- Config files in `.5/` are preserved
 - User-created commands, agents, skills, hooks, and templates are preserved
 - Only workflow-managed files are updated
 

package/bin/install.js

@@ -35,8 +35,8 @@ function compareVersions(v1, v2) {
 }
 
 // Get installed version from .5/version.json
-function getInstalledVersion(targetPath) {
-  const versionFile = path.join(targetPath, '.5', 'version.json');
+function getInstalledVersion(isGlobal) {
+  const versionFile = path.join(getDataPath(isGlobal), 'version.json');
   if (!fs.existsSync(versionFile)) return null;
 
   try {
@@ -55,13 +55,13 @@ function getPackageVersion() {
 }
 
 // Get full version info
-function getVersionInfo(targetPath) {
+function getVersionInfo(targetPath, isGlobal) {
   const exists = checkExistingInstallation(targetPath);
   if (!exists) {
     return { exists: false };
   }
 
-  const installed = getInstalledVersion(targetPath);
+  const installed = getInstalledVersion(isGlobal);
   const available = getPackageVersion();
 
   if (!installed) {
@@ -139,7 +139,7 @@ Examples:
 `);
 }
 
-// Get installation target path
+// Get installation target path (.claude/ directory)
 function getTargetPath(isGlobal) {
   if (isGlobal) {
     const homeDir = process.env.HOME || process.env.USERPROFILE;
@@ -148,6 +148,60 @@ function getTargetPath(isGlobal) {
   return path.join(process.cwd(), '.claude');
 }
 
+// Get data path (.5/ directory for config, version, features)
+// Local installs: <project>/.5 (project root)
+// Global installs: ~/.claude/.5 (alongside global install)
+function getDataPath(isGlobal) {
+  if (isGlobal) {
+    return path.join(getTargetPath(true), '.5');
+  }
+  return path.join(process.cwd(), '.5');
+}
+
+// Migrate data from old .claude/.5/ to new .5/ location (local installs only)
+// This runs during upgrades so existing users don't lose config/features/version data.
+function migrateDataDir(isGlobal) {
+  // Global installs: old and new paths are both ~/.claude/.5 — no migration needed
+  if (isGlobal) return;
+
+  const oldDir = path.join(process.cwd(), '.claude', '.5');
+  const newDir = getDataPath(false); // <project>/.5
+
+  if (!fs.existsSync(oldDir)) return;
+
+  // If new dir doesn't exist, move everything over
+  if (!fs.existsSync(newDir)) {
+    fs.mkdirSync(newDir, { recursive: true });
+  }
+
+  // Copy all files/dirs from old to new (skip files that already exist in new)
+  copyDirMerge(oldDir, newDir);
+
+  // Remove old directory
+  removeDir(oldDir);
+  log.success('Migrated .claude/.5/ → .5/');
+}
+
+// Copy directory recursively, skipping files that already exist at destination
+function copyDirMerge(src, dest) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirMerge(srcPath, destPath);
+    } else if (!fs.existsSync(destPath)) {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
 // Get source path (package installation directory)
 function getSourcePath() {
   // When installed via npm, __dirname is <install-location>/bin
@@ -328,12 +382,12 @@ function selectiveUpdate(targetPath, sourcePath) {
 }
 
 // Initialize version.json after successful install
-function initializeVersionJson(targetPath, isGlobal) {
-  const configDir = path.join(targetPath, '.5');
-  const versionFile = path.join(configDir, 'version.json');
+function initializeVersionJson(isGlobal) {
+  const dataDir = getDataPath(isGlobal);
+  const versionFile = path.join(dataDir, 'version.json');
 
-  if (!fs.existsSync(configDir)) {
-    fs.mkdirSync(configDir, { recursive: true });
+  if (!fs.existsSync(dataDir)) {
+    fs.mkdirSync(dataDir, { recursive: true });
   }
 
   const version = getPackageVersion();
@@ -427,7 +481,7 @@ function checkExistingInstallation(targetPath) {
 }
 
 // Helper to show commands
-function showCommandsHelp(targetPath) {
+function showCommandsHelp(isGlobal) {
   log.info('Available commands:');
   log.info('  /5:plan-feature          - Start feature planning (Phase 1)');
   log.info('  /5:plan-implementation   - Create implementation plan (Phase 2)');
@@ -435,8 +489,9 @@ function showCommandsHelp(targetPath) {
   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:unlock               - Remove planning guard lock');
   log.info('');
-  log.info(`Config file: ${path.join(targetPath, '.5', 'config.json')}`);
+  log.info(`Config file: ${path.join(getDataPath(isGlobal), 'config.json')}`);
 }
 
 // Fresh installation
@@ -463,7 +518,7 @@ function performFreshInstall(targetPath, sourcePath, isGlobal) {
   mergeSettings(targetPath, sourcePath);
 
   // Initialize version tracking
-  initializeVersionJson(targetPath, isGlobal);
+  initializeVersionJson(isGlobal);
 
   log.header('Installation Complete!');
   log.info('');
@@ -477,10 +532,10 @@ function performFreshInstall(targetPath, sourcePath, isGlobal) {
   log.info('  • Create project-specific skills');
   log.info('');
 
-  showCommandsHelp(targetPath);
+  showCommandsHelp(isGlobal);
 }
 
-// Perform update (preserves .5/ directory and user-created files)
+// Perform update (preserves user-created files, updates .5/ data directory)
 function performUpdate(targetPath, sourcePath, isGlobal, versionInfo) {
   log.header(`Updating from ${versionInfo.installed || 'legacy'} to ${versionInfo.available}`);
   log.info('Preserving user-created commands, agents, skills, and hooks');
@@ -492,8 +547,8 @@ function performUpdate(targetPath, sourcePath, isGlobal, versionInfo) {
   mergeSettings(targetPath, sourcePath);
 
   // Update version.json
-  const configDir = path.join(targetPath, '.5');
-  const versionFile = path.join(configDir, 'version.json');
+  const dataDir = getDataPath(isGlobal);
+  const versionFile = path.join(dataDir, 'version.json');
 
   let versionData;
   if (fs.existsSync(versionFile)) {
@@ -511,22 +566,22 @@ function performUpdate(targetPath, sourcePath, isGlobal, versionInfo) {
   versionData.installedVersion = versionInfo.available;
   versionData.lastUpdated = new Date().toISOString();
 
-  if (!fs.existsSync(configDir)) {
-    fs.mkdirSync(configDir, { recursive: true });
+  if (!fs.existsSync(dataDir)) {
+    fs.mkdirSync(dataDir, { recursive: true });
   }
   fs.writeFileSync(versionFile, JSON.stringify(versionData, null, 2));
 
   // Create features directory if it doesn't exist
-  const featuresDir = path.join(configDir, 'features');
+  const featuresDir = path.join(dataDir, 'features');
   if (!fs.existsSync(featuresDir)) {
     fs.mkdirSync(featuresDir, { recursive: true });
-    log.info('📁 Feature folders now nest under .5/features/');
-    log.info('📋 See RELEASE_NOTES.md for migration if you have in-progress features');
+    log.info('Feature folders nest under .5/features/');
+    log.info('See RELEASE_NOTES.md for migration if you have in-progress features');
   }
 
   log.header('Update Complete!');
   log.success(`Now running version ${versionInfo.available}`);
-  showCommandsHelp(targetPath);
+  showCommandsHelp(isGlobal);
 }
 
 // Perform installation
@@ -538,8 +593,11 @@ function install(isGlobal, forceUpgrade = false) {
   log.info(`Target: ${targetPath}`);
   log.info(`Source: ${sourcePath}`);
 
+  // Migrate data from old .claude/.5/ to new .5/ location
+  migrateDataDir(isGlobal);
+
   // Check for existing installation and version
-  const versionInfo = getVersionInfo(targetPath);
+  const versionInfo = getVersionInfo(targetPath, isGlobal);
 
   if (versionInfo.exists) {
     if (versionInfo.legacy) {
@@ -630,11 +688,18 @@ function uninstall() {
   }
   log.success('Removed workflow templates (preserved user-created templates)');
 
-  // Remove config
-  const configDir = path.join(targetPath, '.5');
-  if (fs.existsSync(configDir)) {
-    removeDir(configDir);
-    log.success('Removed .5/ config directory');
+  // Remove data directory (.5/)
+  const dataDir = getDataPath(false);
+  if (fs.existsSync(dataDir)) {
+    removeDir(dataDir);
+    log.success('Removed .5/ data directory');
+  }
+
+  // Also clean up old .claude/.5/ if it still exists
+  const oldDataDir = path.join(targetPath, '.5');
+  if (fs.existsSync(oldDataDir)) {
+    removeDir(oldDataDir);
+    log.success('Removed legacy .claude/.5/ directory');
   }
 
   log.header('Uninstallation Complete!');
@@ -651,7 +716,8 @@ function main() {
 
   if (options.check) {
     const targetPath = getTargetPath(options.global);
-    const versionInfo = getVersionInfo(targetPath);
+    migrateDataDir(options.global);
+    const versionInfo = getVersionInfo(targetPath, options.global);
 
     if (!versionInfo.exists) {
       log.info('Not installed');

package/docs/workflow-guide.md

@@ -72,7 +72,7 @@ The installer copies workflow files to `.claude/` directory. **It does NOT creat
 4. **Phase 4** (`/5:verify-implementation`): Verifies configuration
 
 After completing these steps, you have:
-- `.claude/.5/config.json` with your project settings
+- `.5/config.json` with your project settings
 - `CLAUDE.md` with comprehensive project documentation
 - `.5/STRUCTURE.md`, `.5/STACK.md`, etc. with modular documentation
 - Project-specific skills in `.claude/skills/`
@@ -295,7 +295,7 @@ Map feature requirements to technical components, skills, and dependency steps.
    - **Step 2 (Logic)**: Business logic, services, handlers (sequential if needed)
    - **Step 3 (Integration)**: API routes, wiring, tests (sequential for integration)
 
-   Note: Step count and organization is configurable in `.claude/.5/config.json`
+   Note: Step count and organization is configurable in `.5/config.json`
 
 6. **Implementation Plan Creation**: Claude writes an **atomic plan structure** to:
    ```
@@ -997,7 +997,7 @@ If working on multiple features:
 
 ## Configuring for Different Tech Stacks
 
-The 5-phase workflow is designed to work with any technology stack. Configuration is stored in `.claude/.5/config.json` and can be customized using the `/5:configure` command.
+The 5-phase workflow is designed to work with any technology stack. Configuration is stored in `.5/config.json` and can be customized using the `/5:configure` command.
 
 ### Quick Setup
 
@@ -1096,7 +1096,7 @@ You can override auto-detected values in the config file.
 
 ### Further Customization
 
-See the `/5:configure` command for interactive configuration, or manually edit `.claude/.5/config.json` to customize:
+See the `/5:configure` command for interactive configuration, or manually edit `.5/config.json` to customize:
 - Ticket ID patterns
 - Branch naming conventions
 - Build and test commands

package/package.json

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

package/src/commands/5/configure.md

@@ -26,7 +26,7 @@ After running this command, proceed through the standard phases:
 Your job in this command:
 ✅ Analyze project (detect type, build commands, etc.)
 ✅ Gather user preferences via questions
-✅ Write `.claude/.5/config.json` directly
+✅ Write `.5/config.json` directly
 ✅ Create feature spec at `.5/features/CONFIGURE/feature.md` for remaining work
 ✅ Tell user to run /5:plan-implementation CONFIGURE
 
@@ -49,7 +49,7 @@ Perform all detection silently, collecting results for Step 2.
 
 **1a. Check for existing config:**
 ```bash
-if [ -f ".claude/.5/config.json" ]; then
+if [ -f ".5/config.json" ]; then
   # Config exists - will ask user in Step 2 what to do
   config_exists=true
 else
@@ -155,7 +155,7 @@ For each command found: record exact syntax, note variants (e.g., `test:unit`, `
 
 If "Start fresh" selected:
 - Confirm: "This will delete existing config. Are you sure?"
-- If confirmed: delete .claude/.5/config.json
+- If confirmed: delete .5/config.json
 - Proceed to detection and questions
 
 If "Update existing configuration":
@@ -281,14 +281,14 @@ If no patterns/commands detected:
 
 ### Step 2.5: Write config.json
 
-Using the values gathered from Steps 1 and 2, write `.claude/.5/config.json` directly.
+Using the values gathered from Steps 1 and 2, write `.5/config.json` directly.
 
 **If "Update existing" flow:** Read current config, merge updated values.
 **If "Start fresh" or new install:** Write new config.
 
 **Ensure directory exists:**
 ```bash
-mkdir -p .claude/.5
+mkdir -p .5
 ```
 
 **Schema:**
@@ -413,7 +413,7 @@ Include only patterns/commands where user selected "Generate".
 
 Tell the user:
 
-1. "Configuration saved to `.claude/.5/config.json`"
+1. "Configuration saved to `.5/config.json`"
 2. "Configuration feature planned at `.5/features/CONFIGURE/feature.md`"
 3. "Next steps:"
    - "Run `/clear` to reset context"

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

@@ -39,7 +39,7 @@ Parse:
 
 If the plan doesn't exist, tell the user to run `/5:plan-implementation` first.
 
-Also read `.claude/.5/config.json` and extract:
+Also read `.5/config.json` and extract:
 - `git.autoCommit` (boolean, default `false`)
 - `git.commitMessage.pattern` (string, default `{ticket-id} {short-description}`)
 
@@ -59,6 +59,12 @@ Create `.5/features/{feature-name}/state.json`:
 }
 ```
 
+Then remove the planning guard marker (planning is over, implementation is starting):
+
+```bash
+rm -f .5/.planning-active
+```
+
 ### Step 3: Execute Steps
 
 Group components by step number from the plan. For each step:

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

@@ -37,6 +37,19 @@ After creating the spec, you are DONE.
 
 ## Process
 
+### Step 0: Activate Planning Guard
+
+Write the planning guard marker to `.5/.planning-active` using the Write tool:
+
+```json
+{
+  "phase": "plan-feature",
+  "startedAt": "{ISO-timestamp}"
+}
+```
+
+This activates the plan-guard hook which prevents accidental source file edits during planning. The marker is removed automatically when implementation starts (`/5:implement-feature`), expires after 4 hours, or can be cleared manually with `/5:unlock`.
+
 ### Step 1: Gather Feature Description
 
 Ask the developer for the feature description using AskUserQuestion:

package/src/commands/5/plan-implementation.md

@@ -66,6 +66,20 @@ Add emergency schedule tracking to products with date validation.
 
 ## Process
 
+### Step 0: Activate Planning Guard
+
+Write (or refresh) the planning guard marker to `.5/.planning-active` using the Write tool:
+
+```json
+{
+  "phase": "plan-implementation",
+  "feature": "{feature-name}",
+  "startedAt": "{ISO-timestamp}"
+}
+```
+
+This activates (or refreshes) the plan-guard hook which prevents accidental source file edits during planning. The marker is removed automatically when implementation starts (`/5:implement-feature`), expires after 4 hours, or can be cleared manually with `/5:unlock`.
+
 ### Step 1: Load Feature Spec
 
 Read `.5/features/{feature-name}/feature.md` (where `{feature-name}` is the argument provided).

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

@@ -51,7 +51,7 @@ Extract ticket ID using configurable pattern from config (e.g., `PROJ-\d+` or `\
 
 **Sanitize the ticket ID:** Only allow alphanumeric characters, dashes (`-`), and underscores (`_`). Strip any other characters (especially `/`, `..`, `~`, spaces). If the sanitized result is empty, ask the user for a valid ticket ID.
 
-Also read `.claude/.5/config.json` and extract:
+Also read `.5/config.json` and extract:
 - `git.autoCommit` (boolean, default `false`)
 - `git.commitMessage.pattern` (string, default `{ticket-id} {short-description}`)
 
@@ -128,6 +128,12 @@ Create state file at `.5/features/${feature_name}/state.json` with fields: `tick
 
 Verify the file was written correctly with Read tool. If creation fails, stop and report error.
 
+Then remove the planning guard marker (implementation is starting):
+
+```bash
+rm -f .5/.planning-active
+```
+
 ### Step 8: Execute Implementation
 
 **Decision criteria for execution approach:**

package/src/commands/5/review-code.md

@@ -20,7 +20,7 @@ After saving the review report, you are DONE.
 
 ## Review Tools
 
-Two review tools are supported (configured in `.claude/.5/config.json` field `reviewTool`):
+Two review tools are supported (configured in `.5/config.json` field `reviewTool`):
 
 - **Claude** (default) — Built-in, zero setup. A fresh-context agent reviews code blind.
 - **CodeRabbit** — External CLI. Requires `coderabbit` installed and authenticated.
@@ -31,7 +31,7 @@ Both produce the same structured output format.
 
 ### Step 1: Determine Review Tool
 
-Read `.claude/.5/config.json` and check the `reviewTool` field.
+Read `.5/config.json` and check the `reviewTool` field.
 
 - If not set or missing, default to `"claude"`
 - If `"none"`, inform user that automated review is disabled and STOP

package/src/commands/5/unlock.md

@@ -0,0 +1,23 @@
+---
+name: 5:unlock
+description: Remove the planning guard lock to allow edits outside the workflow
+allowed-tools: Bash
+context: inherit
+user-invocable: true
+---
+
+# Unlock Planning Guard
+
+Remove the `.planning-active` marker file that restricts Write/Edit operations during planning phases.
+
+## Process
+
+Run this bash command to check and remove the marker in one step:
+
+```bash
+if [ -f .5/.planning-active ]; then rm .5/.planning-active && echo "REMOVED"; else echo "ABSENT"; fi
+```
+
+Based on the output, confirm to the user:
+- If output contains "REMOVED": "Planning guard removed. You can now edit files freely."
+- If output contains "ABSENT": "No planning guard was active. You're already free to edit files."

package/src/commands/5/update.md

@@ -1,17 +1,54 @@
 ---
 name: 5:update
 description: Update the 5-Phase Workflow to the latest version
-allowed-tools: Bash
+allowed-tools: Bash, Read, AskUserQuestion
 context: inherit
 user-invocable: true
 ---
 
 # Update 5-Phase Workflow
 
-Run the upgrade command to update to the latest version:
+## Step 1: Check Current Version
+
+Read `.5/version.json` and note the current `installedVersion`.
+
+## Step 2: Run Upgrade
 
 ```bash
-npx 5-phase-workflow --upgrade
+npx 5-phase-workflow@latest --upgrade
 ```
 
-After the upgrade completes, confirm the new version was installed by checking `.claude/.5/version.json`.
+## Step 3: Confirm Upgrade
+
+Read `.5/version.json` again. Compare the new `installedVersion` to the previous one.
+
+- If the version **did not change**: tell the user they're already on the latest version. Stop here.
+- If the version **changed**: continue to Step 4.
+
+## Step 4: Show What Changed
+
+Run `git status` to show the files modified by the upgrade. Summarize the changes for the user (e.g., "Updated 12 files in `.claude/commands/5/`, `.claude/skills/`, `.claude/hooks/`").
+
+## Step 5: Ask to Commit
+
+Ask the user: "Would you like to commit the upgraded workflow files?"
+
+Options:
+1. **Yes** - commit the changes
+2. **No** - leave changes uncommitted
+
+If the user chooses **No**, stop here.
+
+## Step 6: Commit
+
+Read `.5/config.json` if it exists and extract `git.commitMessage.pattern` (default: `{ticket-id} {short-description}`).
+
+Build the commit message by applying the pattern:
+- Replace `{ticket-id}` with an empty string (no ticket for upgrades) and trim any leading/trailing whitespace
+- Replace `{short-description}` with `update 5-Phase Workflow to {new-version}`
+- If the pattern is the conventional format (`feat({ticket-id}): {short-description}`), use: `chore: update 5-Phase Workflow to {new-version}`
+- If no config or no pattern, use: `update 5-Phase Workflow to {new-version}`
+
+Stage **only** the workflow-managed files shown in `git status` (inside `.claude/commands/5/`, `.claude/skills/`, `.claude/hooks/`, `.claude/templates/`, `.claude/settings.json`, and `.5/version.json`). Never use `git add .` or `git add -A`.
+
+Create the commit. Report success to the user.

package/src/commands/5/verify-implementation.md

@@ -49,7 +49,7 @@ Note: feature.md not found — skipping feature completeness checks.
 This is normal for quick-implement workflows. Infrastructure and quality checks will still run.
 ```
 
-Also read `.claude/.5/config.json` and extract:
+Also read `.5/config.json` and extract:
 - `git.autoCommit` (boolean, default `false`)
 - `git.commitMessage.pattern` (string, default `{ticket-id} {short-description}`)
 
@@ -70,7 +70,7 @@ For each component in the plan:
 
 #### 2b. Run Build
 
-Execute the build command from the plan (or auto-detect from `.claude/.5/config.json`):
+Execute the build command from the plan (or auto-detect from `.5/config.json`):
 
 ```bash
 {build-command}

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)) {

package/src/hooks/config-guard.js

@@ -9,7 +9,7 @@ process.stdin.on('end', () => {
   try {
     const data = JSON.parse(input);
     const cwd = data.cwd || process.cwd();
-    const configFile = path.join(cwd, '.claude', '.5', 'config.json');
+    const configFile = path.join(cwd, '.5', 'config.json');
 
     if (fs.existsSync(configFile)) {
       process.exit(0);

package/src/hooks/plan-guard.js

@@ -26,6 +26,12 @@ process.stdin.on('end', () => {
     }
 
     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 || {};
 
     // Determine which feature is being targeted and check its state
@@ -41,7 +47,8 @@ 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);
       }
@@ -54,7 +61,8 @@ process.stdin.on('end', () => {
           `BLOCKED: ${toolName} outside .5/ is not allowed during planning phases. ` +
           `Attempted: "${filePath}". ` +
           `Planning commands may only write to .5/features/. ` +
-          `To modify 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);
       }
@@ -70,23 +78,20 @@ 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 getTargetFeature(toolName, toolInput, workspaceDir) {
   // Extract the feature name from the tool input context
-  const featuresDir = path.join(workspaceDir, '.claude', '.5', 'features');
+  const featuresDir = path.join(workspaceDir, '.5', 'features');
 
   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}/...
+      // 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;
@@ -118,10 +123,28 @@ function getTargetFeature(toolName, toolInput, workspaceDir) {
   return null;
 }
 
+function isPlanningActive(workspaceDir) {
+  const markerPath = path.join(workspaceDir, '.5', '.planning-active');
+  if (!fs.existsSync(markerPath)) return false;
+  try {
+    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) {
+    return true; // Unreadable marker → fail-safe, assume active
+  }
+}
+
 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'
+    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;

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
 {

package/src/skills/run-tests/SKILL.md

@@ -17,7 +17,7 @@ This skill executes test tasks with auto-detection of the test runner and suffic
 
 The skill automatically detects the test runner using:
 
-1. **Config file** (`.claude/.5/config.json`) - if `build.testCommand` is specified
+1. **Config file** (`.5/config.json`) - if `build.testCommand` is specified
 2. **Auto-detection** - by examining project files and package.json scripts:
    - `package.json` with jest/vitest/mocha → npm test
    - `pytest.ini` or test files → pytest
@@ -49,7 +49,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
 {