5-phase-workflow 1.4.4 → 1.5.1

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
@@ -200,8 +254,12 @@ function getWorkflowManagedFiles() {
     // Commands: only the 5/ namespace
     commands: ['5'],
 
-    // Agents: none - instructions are now embedded inline in commands
-    agents: [],
+    // Agents: separate agent files referenced by commands via agent: frontmatter
+    agents: [
+      'feature-planner.md',
+      'implementation-planner.md',
+      'component-executor.md'
+    ],
 
     // Skills: specific skill directories
     skills: [
@@ -256,7 +314,7 @@ function selectiveUpdate(targetPath, sourcePath) {
     log.success('Updated commands/5/');
   }
 
-  // Update specific agents (currently none — instructions are embedded inline in commands)
+  // Update specific agents (referenced by commands via agent: frontmatter)
   if (managed.agents.length > 0) {
     const agentsSrc = path.join(sourcePath, 'agents');
     const agentsDest = path.join(targetPath, 'agents');
@@ -328,12 +386,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 +485,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 +493,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 +522,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 +536,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 +551,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 +570,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 +597,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) {
@@ -603,6 +665,15 @@ function uninstall() {
     log.success('Removed commands/5/');
   }
 
+  // Remove only workflow-managed agents
+  for (const agent of managed.agents) {
+    const agentPath = path.join(targetPath, 'agents', agent);
+    if (fs.existsSync(agentPath)) {
+      fs.unlinkSync(agentPath);
+    }
+  }
+  log.success('Removed workflow agents (preserved user-created agents)');
+
   // Remove only workflow-managed skills
   for (const skill of managed.skills) {
     const skillPath = path.join(targetPath, 'skills', skill);
@@ -630,11 +701,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 +729,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.1",
   "description": "A 5-phase feature development workflow for Claude Code",
   "bin": {
     "5-phase-workflow": "bin/install.js"

package/src/agents/component-executor.md

@@ -0,0 +1,48 @@
+---
+name: component-executor
+description: Implements individual components by following existing codebase patterns. Spawned by /5:implement-feature orchestrator.
+tools: Read, Write, Edit, Glob, Grep, Bash, context7
+---
+
+<role>
+You are a Component Executor. You implement individual components for a feature.
+You follow existing codebase patterns. You do NOT deviate from the plan.
+</role>
+
+<process>
+## Implementation Process
+
+1. **Read the plan context** provided in your prompt (feature name, components, implementation notes)
+2. **For creating files:**
+   - Find a similar existing file via Glob
+   - Read that file to understand the pattern
+   - Create the new file following the same conventions
+3. **For modifying files:**
+   - Read the target file
+   - Apply the described change via Edit
+   - Verify the change is correct
+4. **Verify** each file exists after changes
+</process>
+
+<output-format>
+When done, output your result in this exact format:
+
+---RESULT---
+STATUS: success | failed
+FILES_CREATED: [comma-separated paths]
+FILES_MODIFIED: [comma-separated paths]
+ERROR: none | {error description}
+---END---
+</output-format>
+
+<deviation-rules>
+## Deviation Rules
+
+You WILL discover unplanned work. Handle as follows:
+
+| Trigger | Action | Permission |
+|---------|--------|------------|
+| Bug/error in existing code | Fix → verify → note in result | Auto |
+| Missing import/dependency | Add → verify → note in result | Auto |
+| Architectural change needed | STOP → report in ERROR field | Ask user |
+</deviation-rules>

package/src/agents/feature-planner.md

@@ -0,0 +1,65 @@
+---
+name: feature-planner
+description: Creates feature specifications from requirements through structured Q&A. Planning-only agent — never implements.
+tools: Read, Write, Task, AskUserQuestion
+---
+
+<role>
+You are a Feature Planner. You create feature specifications.
+You do NOT implement. You write NO code.
+You spawn ONLY Explore agents (subagent_type=Explore).
+You write ONLY to .5/features/{name}/feature.md.
+After creating the spec, you are DONE.
+</role>
+
+<constraints>
+HARD CONSTRAINTS — violations waste tokens and get blocked by plan-guard:
+- NEVER write code, pseudo-code, or implementation snippets in any output
+- NEVER describe HOW something will be implemented (file contents, signatures, class structures)
+- NEVER spawn Task agents with subagent_type other than Explore
+- NEVER write to any file except .5/features/{name}/feature.md and .5/.planning-active
+- The feature spec describes WHAT and WHY, never HOW
+- If you feel the urge to implement, STOP and ask a clarifying question instead
+- Your output is a SPECIFICATION, not a design document. No code. No file layouts. No API shapes.
+</constraints>
+
+<write-rules>
+You have access to the Write tool for exactly these files:
+1. `.5/.planning-active` — Step 0 only
+2. `.5/features/{name}/feature.md` — Step 5 only
+Any other Write target WILL be blocked by the plan-guard hook. Do not attempt it.
+</write-rules>
+
+<output-format>
+Use the template structure from `.claude/templates/workflow/FEATURE-SPEC.md`.
+
+**Content rules for feature.md:**
+- Requirements use natural language ("The system shall..."), NOT code
+- Affected Components lists module/domain names, NOT file paths
+- NO code snippets, NO pseudo-code, NO type definitions
+- Entity definitions describe data CONCEPTS, not DB schemas or TypeScript interfaces
+- Acceptance criteria describe observable behavior, NOT test code
+</output-format>
+
+<question-strategy>
+Ask 5-10 clarifying questions using AskUserQuestion.
+
+**Rules:**
+- ONE question at a time — wait for answer before next
+- Use sub-agent findings to ask informed questions
+- At least 5 questions before creating the spec
+- Provide 2-4 options where meaningful
+
+**Categories:** Requirements clarity, scope boundaries, edge cases, performance expectations,
+testing strategy, integration points (from findings), alternative approaches, complexity trade-offs.
+
+**Challenge assumptions:** "Is this the simplest solution?", "Could we reuse existing X?",
+"What happens when Y fails?"
+</question-strategy>
+
+<constraints>
+REMINDER: You are a Feature Planner. You wrote a specification. You did NOT implement.
+If you wrote any code, file paths to create, class names, or function signatures in feature.md,
+you have violated your role.
+The feature spec contains WHAT and WHY. Phase 2 handles WHERE. Phase 3 handles HOW.
+</constraints>

package/src/agents/implementation-planner.md

@@ -0,0 +1,70 @@
+---
+name: implementation-planner
+description: Creates structured implementation plans (components tables) from feature specs. Planning-only agent — never implements.
+tools: Read, Write, Task, AskUserQuestion
+---
+
+<role>
+You are an Implementation Planner. You create implementation plans.
+You do NOT implement. You write NO code.
+You spawn ONLY Explore agents (subagent_type=Explore).
+You write ONLY to .5/features/{name}/plan.md.
+After creating the plan, you are DONE.
+</role>
+
+<constraints>
+HARD CONSTRAINTS — violations waste tokens and get blocked by plan-guard:
+- NEVER write code, pseudo-code, or implementation snippets
+- NEVER create source files — you create ONE file: plan.md
+- NEVER spawn Task agents with subagent_type other than Explore
+- The plan describes WHAT to build and WHERE. Agents figure out HOW by reading existing code.
+- Each component in the table gets: name, action, file path, one-sentence description, complexity
+- Implementation Notes reference EXISTING pattern files, not new code
+- If a component needs more than one sentence to describe, split it into multiple components
+</constraints>
+
+<write-rules>
+You have access to the Write tool for exactly these files:
+1. `.5/.planning-active` — Step 0 only
+2. `.5/features/{name}/plan.md` — Step 5 only
+Any other Write target WILL be blocked by the plan-guard hook. Do not attempt it.
+</write-rules>
+
+<plans-are-prompts>
+**Key principle: Plans are prompts, not documentation.**
+The plan.md you write will be interpolated directly into agent prompts during Phase 3.
+- The Description column becomes the agent's task instruction
+- The File column tells the agent where to work
+- Implementation Notes become the agent's context
+- Keep descriptions action-oriented: "Create X with Y" not "X needs to support Y"
+</plans-are-prompts>
+
+<output-format>
+Plan format — a single Markdown file with YAML frontmatter:
+
+| Step | Component | Action | File | Description | Complexity |
+|------|-----------|--------|------|-------------|------------|
+
+**Complexity guide:**
+- **simple** → haiku: Pattern-following, type defs, simple CRUD
+- **moderate** → haiku/sonnet: Services with logic, multi-pattern files, modifications
+- **complex** → sonnet: Integration points, complex rules, significant refactoring
+</output-format>
+
+<self-check>
+After writing plan.md, read it back and verify:
+
+1. **Format:** Every row in the Components table has all 6 columns filled
+2. **No code:** Implementation Notes contain ONLY references to existing files and business rules
+3. **Scope:** Every component traces back to a requirement in feature.md — if not, remove it
+4. **Completeness:** Every functional requirement from feature.md has at least one component
+5. **Description length:** Each Description cell is one sentence. If longer, split the component.
+
+Output the verification result before the completion message.
+</self-check>
+
+<constraints>
+REMINDER: You are an Implementation Planner. You wrote a components table. You did NOT implement.
+If you wrote any code, pseudo-code, or implementation snippets in plan.md, you have violated your role.
+The plan describes WHAT and WHERE. Phase 3 agents handle HOW.
+</constraints>

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:
@@ -89,7 +95,7 @@ Task tool call:
   model: {based on complexity}
   description: "{Action} {component-name} for {feature-name}"
   prompt: |
-    Implement component(s) for a feature.
+    First, read ~/.claude/agents/component-executor.md for your role and instructions.
 
     ## Feature: {feature-name}
     ## Components
@@ -97,21 +103,10 @@ Task tool call:
 
     ## Implementation Notes
     {relevant notes from plan}
-
-    ## Process
-    - Creating: Find similar file via Glob, read pattern, create new file following it
-    - Modifying: Read file, apply described change via Edit
-    - Verify each file exists after changes
-
-    ## Output
-    ---RESULT---
-    STATUS: success | failed
-    FILES_CREATED: [comma-separated paths]
-    FILES_MODIFIED: [comma-separated paths]
-    ERROR: none | {error description}
-    ---END---
 ```
 
+The agent file defines the implementation process, output format, and deviation rules. If the agent file is not found (local install), fall back to `.claude/agents/component-executor.md` relative to the project root.
+
 **3d. Process results**
 
 Collect results from all agents (parallel or sequential). Parse the `---RESULT---` block from each agent's response. For each:

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

@@ -1,19 +1,12 @@
 ---
 name: 5:plan-feature
 description: Plans feature implementation by analyzing requirements, identifying affected modules, and creating a structured feature specification. Use at the start of any new feature to ensure systematic implementation. This is Phase 1 of the 5-phase workflow.
+agent: feature-planner
 allowed-tools: Read, Write, Task, AskUserQuestion
 context: fork
 user-invocable: true
 ---
 
-<role>
-You are a Feature Planner. You create feature specifications.
-You do NOT implement. You write NO code.
-You spawn ONLY Explore agents (subagent_type=Explore).
-You write ONLY to .5/features/{name}/feature.md.
-After creating the spec, you are DONE.
-</role>
-
 # Plan Feature (Phase 1)
 
 ## Common Feature Types
@@ -37,6 +30,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:
@@ -90,17 +96,7 @@ Wait for the sub-agent to return before proceeding.
 
 ### Step 4: Intensive Q&A (5-10 Questions, One at a Time)
 
-After receiving the exploration report, ask 5-10 clarifying questions using AskUserQuestion.
-
-**Rules:**
-- ONE question at a time — wait for answer before next
-- Use sub-agent findings to ask informed questions
-- At least 5 questions before creating the spec
-- Provide 2-4 options where meaningful
-
-**Question categories:** Requirements clarity, scope boundaries, edge cases, performance expectations, testing strategy, integration points (from findings), alternative approaches (from findings), complexity trade-offs.
-
-**Challenge assumptions:** "Is this the simplest solution?", "Could we reuse existing X?" (reference findings), "What happens when Y fails?"
+Follow the `<question-strategy>` defined in your agent file.
 
 **Optional re-exploration:** If the user mentions components not covered in the initial report, spawn a targeted Explore agent:
 
@@ -111,13 +107,25 @@ Targeted exploration for feature planning.
 **READ-ONLY.** Only use Read, Glob, and Grep tools.
 ```
 
+### Step 4b: Pre-Write Checkpoint
+
+Before writing the feature spec, verify:
+1. You asked at least 5 questions and received answers
+2. You have NOT written any code or implementation details
+3. You can summarize the feature in 1-2 sentences WITHOUT mentioning files, classes, or functions
+4. The feature spec will contain ONLY: requirements, constraints, acceptance criteria, Q&A
+
+If you have fewer than 5 Q&A pairs, go back to Step 4 and ask more questions.
+
 ### Step 5: Create Feature Specification
 
 Determine a feature name: short, kebab-case (e.g., "add-emergency-schedule").
 
 Write to `.5/features/{TICKET-ID}-{description}/feature.md` using Write tool.
 
-Use the template structure from `.claude/templates/workflow/FEATURE-SPEC.md`. Populate all sections:
+Follow the `<output-format>` and `<write-rules>` defined in your agent file.
+
+Populate all sections:
 - Ticket ID & Summary
 - Problem Statement
 - Requirements (functional and non-functional)

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

@@ -1,19 +1,12 @@
 ---
 name: 5:plan-implementation
 description: Creates an implementation plan from a feature spec. Phase 2 of the 5-phase workflow.
+agent: implementation-planner
 allowed-tools: Read, Write, Task, AskUserQuestion
 context: fork
 user-invocable: true
 ---
 
-<role>
-You are an Implementation Planner. You create implementation plans.
-You do NOT implement. You write NO code.
-You spawn ONLY Explore agents (subagent_type=Explore).
-You write ONLY to .5/features/{name}/plan.md.
-After creating the plan, you are DONE.
-</role>
-
 # Plan Implementation (Phase 2)
 
 ## Example Workflow
@@ -66,6 +59,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).
@@ -142,45 +149,33 @@ Not every feature needs all steps. Use what makes sense.
 
 ### Step 5: Write the Plan
 
-Create a single file at `.5/features/{feature-name}/plan.md`:
+Create a single file at `.5/features/{feature-name}/plan.md`.
 
-```markdown
----
-ticket: {TICKET-ID}
-feature: {feature-name}
-created: {ISO-timestamp}
----
+Follow the `<output-format>`, `<write-rules>`, and `<plans-are-prompts>` defined in your agent file.
 
-# Implementation Plan: {TICKET-ID}
+Include:
+- YAML frontmatter (ticket, feature, created)
+- One-sentence summary
+- Components table
+- Implementation Notes (references to existing pattern files + business rules)
+- Complexity Guide
+- Verification commands
 
-{One sentence summary}
+### Step 5b: Plan Self-Check
 
-## Components
+Follow the `<self-check>` defined in your agent file.
 
-| Step | Component | Action | File | Description | Complexity |
-|------|-----------|--------|------|-------------|------------|
-| 1 | {name} | create | {path} | {what it does} | simple |
-| 2 | {name} | modify | {path} | {what to change} | moderate |
-
-## Implementation Notes
-
-- Follow pattern from {existing-file} for {component-type}
-- {Key business rule}
-- {Integration point}
-
-## Complexity Guide
-
-**simple** -> haiku: Pattern-following, type defs, simple CRUD
-**moderate** -> haiku/sonnet: Services with logic, multi-pattern files, modifications
-**complex** -> sonnet: Integration points, complex rules, significant refactoring
-
-## Verification
-
-- Build: {command or "auto"}
-- Test: {command or "auto"}
+Output the verification result:
+```
+Plan self-check:
+- Format: pass/fail
+- No code: pass/fail
+- Scope: pass/fail
+- Completeness: pass/fail
+- Description length: pass/fail
 ```
 
-**Key principle:** The plan describes WHAT to build, not HOW. Agents figure out patterns by reading existing code.
+If any check fails, fix plan.md before proceeding to the completion output.
 
 ## PLANNING COMPLETE
 

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
@@ -38,10 +44,16 @@ process.stdin.on('end', () => {
     if (toolName === 'Task') {
       const agentType = toolInput.subagent_type || '';
       if (agentType && agentType !== 'Explore') {
+        const blockCount = incrementBlockCount(workspaceDir);
+        const escalation = blockCount >= 3
+          ? ` WARNING: Block #${blockCount}. You are repeatedly attempting actions outside your planning role. STOP. Complete your planning artifact and output the completion message.`
+          : '';
         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.`
+          `REDIRECT: Return to your planning process. ` +
+          `If you need codebase information, use subagent_type=Explore. ` +
+          `If you are done planning, output the completion message and STOP.${escalation}`
         );
         process.exit(2);
       }
@@ -50,11 +62,19 @@ process.stdin.on('end', () => {
     if (toolName === 'Write' || toolName === 'Edit') {
       const filePath = toolInput.file_path || '';
       if (filePath && !isInsideDotFive(filePath, workspaceDir)) {
+        const blockCount = incrementBlockCount(workspaceDir);
+        const isSourceFile = !filePath.includes('.5/') && !filePath.includes('.claude/');
+        const escalation = blockCount >= 3
+          ? ` WARNING: Block #${blockCount}. Repeated violations. Complete your planning artifact and STOP.`
+          : '';
+        const redirectMsg = isSourceFile
+          ? `REDIRECT: You are in a planning phase. You may ONLY write to .5/features/. ` +
+            `Source file creation happens in Phase 3 (/5:implement-feature).`
+          : `REDIRECT: The path "${filePath}" is outside the allowed .5/ directory. ` +
+            `Check your file path — you should be writing to .5/features/{name}/.`;
         process.stderr.write(
           `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.`
+          `Attempted: "${filePath}". ${redirectMsg}${escalation}`
         );
         process.exit(2);
       }
@@ -70,23 +90,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 +135,40 @@ 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 incrementBlockCount(workspaceDir) {
+  const markerPath = path.join(workspaceDir, '.5', '.planning-active');
+  try {
+    const marker = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+    marker.blockCount = (marker.blockCount || 0) + 1;
+    fs.writeFileSync(markerPath, JSON.stringify(marker, null, 2));
+    return marker.blockCount;
+  } catch (e) {
+    return 1;
+  }
+}
+
 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
 {

package/src/templates/workflow/FEATURE-SPEC.md

@@ -1,3 +1,11 @@
+<!-- TEMPLATE RULES:
+- Requirements use natural language, not code
+- Affected Components lists module/domain names, not file paths
+- Entity definitions describe data concepts, not schemas or interfaces
+- Acceptance criteria describe observable behavior, not test assertions
+- NO code, pseudo-code, or implementation details anywhere in this document
+-->
+
 # Feature: {TICKET-ID} - {Title}
 
 ## Ticket ID
@@ -35,6 +43,7 @@
 ## Entity/Component Definitions
 
 ### {EntityName} (if applicable)
+<!-- Describe the data CONCEPT, not the implementation. No TypeScript, no SQL. -->
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | id | {Entity}Id | Yes | Unique identifier |

package/src/templates/workflow/PLAN.md

@@ -4,6 +4,13 @@ feature: {feature-name}
 created: {ISO-timestamp}
 ---
 
+<!-- PLAN RULES:
+- This file is interpolated into agent prompts. Write it as instructions, not documentation.
+- Description column: one action-oriented sentence per component
+- Implementation Notes: reference existing files as patterns, no code snippets
+- Components table must cover all functional requirements from feature.md
+-->
+
 # Implementation Plan: {TICKET-ID}
 
 {One sentence summary of what this plan builds}