5-phase-workflow 1.2.2 → 1.3.0

package/README.md

@@ -33,22 +33,36 @@ npx 5-phase-workflow --global
 ```
 
 The installer will:
-- Auto-detect your project type (JavaScript, Python, Java, etc.)
 - Copy workflow commands, agents, and skills to `.claude/`
-- Create a config file at `.claude/.5/config.json`
-- Configure build and test commands for your project
+- Set up hooks and settings
+- Create `.5/features/` directory for feature tracking
 
-## Quick Start
+**After installation, you must configure your project:**
 
-After installation, configure the workflow for your project:
+## Required: Configure Your Project
 
 ```bash
 # Open Claude Code in your project
-# Run the configuration wizard
 /5:configure
 ```
 
-Then start your first feature:
+This will:
+- Auto-detect your project type (JavaScript, Python, Java, etc.)
+- Set up build and test commands
+- Configure ticket tracking patterns
+- Generate comprehensive CLAUDE.md documentation
+- Create project-specific skills (create-component, create-service, etc.)
+
+Follow the standard workflow after `/5:configure`:
+1. `/5:plan-implementation CONFIGURE` - Plan the configuration
+2. `/5:implement-feature CONFIGURE` - Execute configuration
+3. `/5:verify-implementation` - Verify setup
+
+**The workflow is ready to use after completing configuration.**
+
+## Start Your First Feature
+
+After configuration is complete, start your first feature:
 
 ```bash
 # Phase 1: Plan the feature
@@ -178,10 +192,10 @@ Claude maps your feature to technical components:
 - Maps components to implementation steps
 - Creates dependency graph
 
-The output is an **atomic plan structure** at `.5/{ticket-id}/plan/`:
-- `meta.md` - Feature metadata and risks
-- `step-1.md`, `step-2.md`, ... - Per-step components with pre-built prompts (YAML format)
-- `verification.md` - Build/test configuration
+The output is an **atomic plan structure** at `.5/features/{ticket-id}/`:
+- `feature.md` - Feature specification (Phase 1)
+- `plan.md` - Implementation plan (Phase 2)
+- `state.json` - Implementation state tracking (Phase 3)
 
 Each step file is self-contained and independently loadable, making large plans manageable and improving agent efficiency.
 

package/bin/install.js

@@ -467,6 +467,13 @@ function initializeConfig(targetPath) {
     fs.mkdirSync(configDir, { recursive: true });
   }
 
+  // Create features subdirectory
+  const featuresDir = path.join(configDir, 'features');
+  if (!fs.existsSync(featuresDir)) {
+    fs.mkdirSync(featuresDir, { recursive: true });
+    log.success('Created .5/features/ directory');
+  }
+
   const projectType = detectProjectType();
   const config = getDefaultConfig(projectType);
 
@@ -583,15 +590,21 @@ function performFreshInstall(targetPath, sourcePath, isGlobal) {
   // Merge settings
   mergeSettings(targetPath, sourcePath);
 
-  // Initialize config (local only)
-  if (!isGlobal) {
-    initializeConfig(targetPath);
-  }
-
   // Initialize version tracking
   initializeVersionJson(targetPath, isGlobal);
 
   log.header('Installation Complete!');
+  log.info('');
+  log.info('Next step: Configure your project');
+  log.info('Run: /5:configure');
+  log.info('');
+  log.info('This will:');
+  log.info('  • Detect your project type and build commands');
+  log.info('  • Set up ticket tracking conventions');
+  log.info('  • Generate comprehensive documentation (CLAUDE.md)');
+  log.info('  • Create project-specific skills');
+  log.info('');
+
   showCommandsHelp(targetPath);
 }
 
@@ -631,6 +644,14 @@ function performUpdate(targetPath, sourcePath, isGlobal, versionInfo) {
   }
   fs.writeFileSync(versionFile, JSON.stringify(versionData, null, 2));
 
+  // Create features directory if it doesn't exist
+  const featuresDir = path.join(configDir, '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.header('Update Complete!');
   log.success(`Now running version ${versionInfo.available}`);
   showCommandsHelp(targetPath);

package/docs/workflow-guide.md

@@ -48,6 +48,47 @@ For small, well-understood tasks (1-5 files). Uses same state tracking and skill
 
 ---
 
+## Getting Started
+
+### Installation
+
+```bash
+npx 5-phase-workflow
+```
+
+The installer copies workflow files to `.claude/` directory. **It does NOT create configuration.**
+
+### Required First Step: Configuration
+
+```bash
+/5:configure
+```
+
+**This is a required setup step.** The configure command uses the 5-phase workflow itself:
+
+1. **Phase 1** (`/5:configure`): Analyzes project, gathers preferences, creates feature spec
+2. **Phase 2** (`/5:plan-implementation CONFIGURE`): Creates implementation plan
+3. **Phase 3** (`/5:implement-feature CONFIGURE`): Executes configuration
+4. **Phase 4** (`/5:verify-implementation`): Verifies configuration
+
+After completing these steps, you have:
+- `.claude/.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/`
+
+**Without configuration, workflow commands will fail.**
+
+### Your First Feature
+
+After configuration is complete, start your first feature:
+
+```bash
+/5:plan-feature
+```
+
+---
+
 ## Architecture
 
 The workflow uses a **4-layer architecture**:
@@ -110,7 +151,7 @@ Commands used to call skills directly, consuming main context for heavy operatio
 |                                                                   |
 | Developer: /plan-feature                                         |
 | Claude: Asks 6-10 questions, challenges assumptions              |
-| Output: .5/{TICKET-ID}-{description}/feature.md                  |
+| Output: .5/features/{TICKET-ID}-{description}/feature.md                  |
 | Developer: Reviews and approves spec                              |
 +-----------------------------+-------------------------------------+
                               |
@@ -196,7 +237,7 @@ Understand requirements, challenge assumptions, and create a comprehensive featu
 
 5. **Feature Spec Creation**: Claude writes structured spec to:
    ```
-   .5/{TICKET-ID}-{description}/feature.md
+   .5/features/{TICKET-ID}-{description}/feature.md
    ```
 
 ### Your Role
@@ -258,7 +299,7 @@ Map feature requirements to technical components, skills, and dependency steps.
 
 6. **Implementation Plan Creation**: Claude writes an **atomic plan structure** to:
    ```
-   .5/{TICKET-ID}-{description}/plan/
+   .5/features/{TICKET-ID}-{description}/plan/
    ├── meta.md              # Feature metadata and risks
    ├── step-1.md            # Step 1 components (YAML format)
    ├── step-2.md            # Step 2 components
@@ -315,7 +356,7 @@ Execute the implementation plan with state tracking, using agents in forked cont
 
 2. **Initialize State File**: Creates tracking file
    ```
-   .5/{TICKET-ID}-{description}/state.json
+   .5/features/{TICKET-ID}-{description}/state.json
    ```
 
 3. **Create Task List**: One item per step (default 3 steps, configurable)
@@ -380,7 +421,7 @@ Tracks progress in JSON format:
 
 ### Output Files
 
-- **State file**: `.5/{ticket}/state.json`
+- **State file**: `.5/features/{ticket}/state.json`
 - **All created files**: As specified in implementation plan
 
 ### Next Steps
@@ -420,7 +461,7 @@ Systematically verify that the implementation is complete, correct, and ready fo
 4. **Process Results**: Command receives structured verification data
 
 5. **Save Report**: Writes verification report to:
-   `.5/{ticket}/verification.md`
+   `.5/features/{ticket}/verification.md`
 
 6. **Update State File**: Marks verification status
 
@@ -497,7 +538,7 @@ Use automated code review to catch quality issues, apply auto-fixes, and ensure
 
 8. **Verify**: Compile and test after applying fixes
 
-9. **Save Report**: Store review summary in `.5/{feature-name}/`
+9. **Save Report**: Store review summary in `.5/features/{feature-name}/`
 
 ### Your Role
 
@@ -750,7 +791,7 @@ Tests: All passing
 2. **Use git branches**: Create feature branch before starting
 3. **Commit often**: Commit after Phase 3 completes successfully
 4. **Run verification manually**: Re-run /verify-implementation after fixes
-5. **Review state files**: Check `.5/{feature-name}/state.json` for progress tracking
+5. **Review state files**: Check `.5/features/{feature-name}/state.json` for progress tracking
 6. **Save verification reports**: Keep reports for documentation/debugging
 
 ---
@@ -798,7 +839,7 @@ Tests: All passing
 **Symptom**: JSON parse error when reading state file
 
 **Solution**:
-1. Open `.5/{ticket}/state.json`
+1. Open `.5/features/{ticket}/state.json`
 2. Fix JSON syntax error
 3. Or delete and re-run /implement-feature (will restart from beginning)
 
@@ -835,7 +876,7 @@ Tests: All passing
 ### Resuming Interrupted Implementation
 
 If implementation was interrupted:
-1. Check state file: `.5/{ticket}/state.json`
+1. Check state file: `.5/features/{ticket}/state.json`
 2. Note `currentStep` value
 3. Re-run `/implement-feature {ticket}`
 4. Claude will resume from `currentStep`
@@ -930,11 +971,11 @@ If working on multiple features:
 
 | File | Purpose | Committed? |
 |------|---------|------------|
-| `.5/{ticket}/feature.md` | Feature spec | Yes (after approval) |
-| `.5/{ticket}/plan/` | Atomic implementation plan (meta.md, step-N.md, verification.md) | Yes (after approval) |
-| `.5/{ticket}/state.json` | Progress tracking | No (gitignored) |
-| `.5/{ticket}/verification.md` | Verification report | No (gitignored) |
-| `.5/{ticket}/review-{timestamp}.md` | CodeRabbit review report | No (gitignored) |
+| `.5/features/{ticket}/feature.md` | Feature spec | Yes (after approval) |
+| `.5/features/{ticket}/plan/` | Atomic implementation plan (meta.md, step-N.md, verification.md) | Yes (after approval) |
+| `.5/features/{ticket}/state.json` | Progress tracking | No (gitignored) |
+| `.5/features/{ticket}/verification.md` | Verification report | No (gitignored) |
+| `.5/features/{ticket}/review-{timestamp}.md` | CodeRabbit review report | No (gitignored) |
 
 ### State File Status Values
 

package/package.json

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

package/src/commands/5/configure.md

@@ -59,7 +59,11 @@ Perform all detection silently, collecting results for Step 2.
 **1a. Check for existing config:**
 ```bash
 if [ -f ".claude/.5/config.json" ]; then
-  # Config exists - will ask user in Step 2
+  # Config exists - will ask user in Step 2 what to do
+  config_exists=true
+else
+  # No config - this is expected for first run after installation
+  config_exists=false
 fi
 ```
 
@@ -275,9 +279,24 @@ Only include patterns/commands that are actually detected.
 ### Step 2: Gather User Preferences (interactive via AskUserQuestion)
 
 **2a. If config exists:**
-- "Configuration already exists. What would you like to do?"
-  - Options: "Update existing", "Start fresh", "Cancel"
-  - If Cancel: stop here
+"Configuration already exists. What would you like to do?"
+- Options:
+  - "Update existing configuration" (merge with current values)
+  - "Start fresh" (delete and reconfigure from scratch)
+  - "Cancel" (exit without changes)
+
+If "Start fresh" selected:
+- Confirm: "This will delete existing config. Are you sure?"
+- If confirmed: delete .claude/.5/config.json
+- Proceed to detection and questions
+
+If "Update existing configuration":
+- Read current values
+- Pre-fill questions with current values
+- Allow user to change any value
+- Merge updated values back
+
+If "Cancel": Exit immediately with message "Configuration unchanged."
 
 **2b. Confirm project type:**
 - "Detected project type: {detected-type}. Is this correct?"
@@ -491,13 +510,13 @@ Each run-* skill should:
 - [ ] If CLAUDE.md existed before, user-written sections are preserved
 ```
 
-**Important:** Use `mkdir -p .5/CONFIGURE` before writing the feature spec.
+**Important:** Use `mkdir -p .5/features/CONFIGURE` before writing the feature spec.
 
 ### Step 4: Guide User to Next Phase
 
 Tell the user:
 
-1. "Configuration feature planned at `.5/CONFIGURE/feature.md`"
+1. "Configuration feature planned at `.5/features/CONFIGURE/feature.md`"
 2. "Next steps:"
    - "Run `/clear` to reset context"
    - "Then run `/5:plan-implementation CONFIGURE`"
@@ -561,8 +580,8 @@ Claude: "I also found these runnable commands:
 Which commands would you like `run-*` skills generated for?"
 User: [Selects test, lint]
 
-Claude: [Writes .5/CONFIGURE/feature.md]
-Claude: "Configuration feature planned at `.5/CONFIGURE/feature.md`"
+Claude: [Writes .5/features/CONFIGURE/feature.md]
+Claude: "Configuration feature planned at `.5/features/CONFIGURE/feature.md`"
 Claude: "Next: Run `/clear` followed by `/5:plan-implementation CONFIGURE`"
 ```
 

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

@@ -76,7 +76,7 @@ Before invoking this skill, ensure:
 ### Step 1: Extract Feature Name
 
 If user provides only ticket ID (e.g., "PROJ-1234"), find the feature file:
-- Use Glob: `.5/{TICKET-ID}-*-*/feature.md` (pattern from config)
+- Use Glob: `.5/features/{TICKET-ID}-*/feature.md` (pattern from config)
 - Match the ticket ID
 - If multiple matches, ask user to specify
 - If no match found, inform user and suggest running `/plan-feature` first
@@ -85,7 +85,7 @@ If user provides full feature name (e.g., "PROJ-1234-add-feature"), use directly
 
 ### Step 2: Read Feature Specification
 
-Read the feature spec from `.5/{feature-name}/feature.md`.
+Read the feature spec from `.5/features/{feature-name}/feature.md`.
 
 Extract current state:
 - Ticket ID
@@ -184,7 +184,7 @@ Allow multiple rounds of discussion until user is satisfied.
 
 ### Step 7: Update Feature Specification
 
-When user indicates they're done discussing, update `.5/{feature-name}/feature.md`:
+When user indicates they're done discussing, update `.5/features/{feature-name}/feature.md`:
 
 **Update these sections based on discussion:**
 
@@ -219,7 +219,7 @@ When user indicates they're done discussing, update `.5/{feature-name}/feature.m
 
 After updating the spec, tell the developer:
 
-1. "Feature specification updated at `.5/{feature-name}/feature.md`"
+1. "Feature specification updated at `.5/features/{feature-name}/feature.md`"
 2. Summarize key changes:
    - "Added: {X}"
    - "Modified: {Y}"
@@ -234,7 +234,7 @@ After updating the spec, tell the developer:
 Follow these steps **IN ORDER** and **STOP after step 9**:
 
 1. **Extract feature name** - From user input or by matching ticket ID
-2. **Read feature spec** - Load current state from `.5/{feature-name}/feature.md`
+2. **Read feature spec** - Load current state from `.5/features/{feature-name}/feature.md`
 3. **Ask initial question** - What do they want to discuss?
 4. **Explore if needed** - Understand codebase context
 5. **Interactive Q&A** - Multiple rounds of clarifying questions

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

@@ -8,6 +8,27 @@ user-invocable: true
 
 # Implement Feature (Phase 3)
 
+## Prerequisites Check
+
+**CRITICAL: Check for configuration before proceeding**
+
+```bash
+if [ ! -f ".claude/.5/config.json" ]; then
+  echo "❌ Configuration not found"
+  echo ""
+  echo "Please run /5:configure first to set up your project."
+  echo ""
+  echo "The configure command will:"
+  echo "  • Detect your project type and build commands"
+  echo "  • Set up ticket tracking conventions"
+  echo "  • Generate documentation (CLAUDE.md)"
+  echo "  • Create project-specific skills"
+  exit 1
+fi
+```
+
+**If config doesn't exist, STOP IMMEDIATELY. Do not proceed with the workflow.**
+
 Execute an implementation plan by delegating work to agents.
 
 ## Scope
@@ -27,7 +48,7 @@ Do NOT write code directly. Spawn agents to do the work.
 
 ### Step 1: Load Plan
 
-Read `.5/{feature-name}/plan.md` (where `{feature-name}` is the argument provided).
+Read `.5/features/{feature-name}/plan.md` (where `{feature-name}` is the argument provided).
 
 Parse:
 - YAML frontmatter for ticket and feature name
@@ -39,7 +60,7 @@ If the plan doesn't exist, tell the user to run `/5:plan-implementation` first.
 
 ### Step 2: Initialize State
 
-Create `.5/{feature-name}/state.json`:
+Create `.5/features/{feature-name}/state.json`:
 
 ```json
 {

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

@@ -1,13 +1,34 @@
 ---
 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.
-allowed-tools: Read, Glob, Grep, Task, AskUserQuestion
+allowed-tools: Bash, Write, Task, AskUserQuestion
 context: fork
 user-invocable: true
 ---
 
 # Plan Feature Implementation (Phase 1)
 
+## Prerequisites Check
+
+**CRITICAL: Check for configuration before proceeding**
+
+```bash
+if [ ! -f ".claude/.5/config.json" ]; then
+  echo "❌ Configuration not found"
+  echo ""
+  echo "Please run /5:configure first to set up your project."
+  echo ""
+  echo "The configure command will:"
+  echo "  • Detect your project type and build commands"
+  echo "  • Set up ticket tracking conventions"
+  echo "  • Generate documentation (CLAUDE.md)"
+  echo "  • Create project-specific skills"
+  exit 1
+fi
+```
+
+**If config doesn't exist, STOP IMMEDIATELY. Do not proceed with the workflow.**
+
 ## Overview
 
 This skill is the **first phase** of the 5-phase workflow:
@@ -19,13 +40,26 @@ This skill is the **first phase** of the 5-phase workflow:
 
 This skill guides intensive collaboration with the developer to understand requirements, challenge assumptions, and create a comprehensive feature specification.
 
+## ⚠️ CRITICAL ARCHITECTURE
+
+**This command uses a READ-ONLY sub-agent for codebase exploration.**
+
+You (the main agent) orchestrate the process:
+- You ask questions via AskUserQuestion
+- You spawn a read-only Explore agent to analyze the codebase
+- You receive findings from the sub-agent
+- You create the feature.md file
+- You inform the user of next steps
+
+**The sub-agent CANNOT write files or implement anything. It can only read and report.**
+
 ## ⚠️ CRITICAL SCOPE CONSTRAINT
 
 **THIS COMMAND ONLY CREATES THE FEATURE SPECIFICATION. IT DOES NOT IMPLEMENT.**
 
 Your job in this phase:
 ✅ Ask questions
-✅ Explore codebase
+✅ Spawn read-only sub-agent to explore codebase
 ✅ Create feature.md file
 ✅ Tell user to run /5:plan-implementation
 
@@ -80,35 +114,84 @@ Automatically extract the ticket ID from the current git branch:
 - Ask the developer if the ticket ID is correct
 - If no ticket ID found, ask developer for it
 
-### Step 3: Analyze Existing Codebase
+### Step 3: Spawn Read-Only Explore Agent
+
+**CRITICAL: Delegate ALL codebase exploration to a sub-agent.**
 
-Explore the codebase to understand existing patterns and identify affected modules:
+Spawn a Task with `subagent_type=Explore` with the following prompt structure:
 
 ```
-1. Explore the project structure to identify modules/components
-   - Use Glob to discover relevant directories
-   - Look for patterns that indicate module organization
+Analyze the codebase for a feature planning session.
 
-2. Check existing implementations in relevant modules
-   - Search for similar features or components
-   - Identify coding patterns and conventions
+**Feature Description:** {paste the user's feature description here}
 
-3. Check for similar patterns across the codebase
-   - Search for class/function patterns that might be reusable
+**Your Task:**
+1. Explore the project structure to identify modules/components
+2. Find existing implementations similar to this feature
+3. Identify coding patterns and conventions used
+4. Find reusable components or patterns
+5. Identify which existing files/modules would be affected
+
+**Report Format:**
+Return a structured report with:
+- Project structure overview
+- Relevant existing patterns found
+- Similar implementations discovered
+- Affected modules/files
+- Reusable components identified
+- Potential integration points
+
+**IMPORTANT:** You are a READ-ONLY agent. Only use Read, Glob, and Grep tools. Do NOT suggest implementations or write any code.
 ```
 
-Use Task tool with subagent_type=Explore for complex exploration.
-
-**Goal:** Understand what already exists so you can ask informed questions.
+**Wait for the sub-agent to return its findings before proceeding.**
 
 ### Step 4: Intensive Collaboration (5-10 Questions, ONE AT A TIME)
 
-**CRITICAL:** After exploring the codebase, engage in intensive Q&A. This is NOT optional.
+**CRITICAL:** After receiving the exploration report, engage in intensive Q&A. This is NOT optional.
 
 - Ask 5-10 clarifying questions using AskUserQuestion
 - **ONE question at a time** - wait for answer before next question
 - Do NOT list multiple questions in one message
 - Do NOT skip to creating feature.md before asking at least 5 questions
+- **Use the sub-agent's findings to inform your questions**
+
+#### Step 4b: Optional Targeted Re-Exploration
+
+During Q&A, the user may mention components, modules, or patterns that weren't covered in the initial exploration. You MAY spawn additional targeted Explore agents to gather more specific information.
+
+**When to trigger re-exploration:**
+- User mentions a specific file, module, or service by name that wasn't in the initial report
+- User's answer reveals a dependency or integration point not previously identified
+- User asks "have you looked at X?" or "what about the Y module?"
+- Understanding a specific component is critical for accurate feature specification
+
+**How to re-explore:**
+
+Spawn a targeted Task with `subagent_type=Explore`:
+
+```
+Targeted exploration for feature planning.
+
+**Context:** During Q&A, the user mentioned {specific component/module/pattern}.
+
+**Focused Task:**
+1. Find and analyze {specific component} mentioned by user
+2. Understand how it works and its patterns
+3. Identify how it might relate to the planned feature
+
+**Report:** Provide a focused summary of:
+- How this component works
+- Relevant patterns or conventions
+- How it could integrate with the planned feature
+
+**IMPORTANT:** READ-ONLY. Only use Read, Glob, and Grep tools.
+```
+
+**Guidelines:**
+- Keep re-explorations focused and specific (not broad searches)
+- Use findings to ask better follow-up questions
+- Document relevant discoveries in the final feature spec
 
 **Question categories to explore:**
 
@@ -137,12 +220,12 @@ Use Task tool with subagent_type=Explore for complex exploration.
    - What are the acceptance criteria?
    - What test scenarios should be covered?
 
-6. **Integration Points**
+6. **Integration Points** (informed by sub-agent findings)
    - Which existing components/modules are affected?
    - Are there API changes?
    - How does this interact with existing features?
 
-7. **Alternative Approaches**
+7. **Alternative Approaches** (informed by sub-agent findings)
    - Have you considered approach X instead?
    - Is this the simplest solution?
    - Could we reuse existing components?
@@ -156,7 +239,7 @@ Use Task tool with subagent_type=Explore for complex exploration.
 - "Is this the simplest solution?"
 - "Have you considered X alternative?"
 - "What happens when Y fails?"
-- "Could we use existing Z component instead?"
+- "Could we use existing Z component instead?" (reference sub-agent findings)
 - "Is a full factory needed or just simple creation?"
 
 **Ask questions ONE AT A TIME.** Use AskUserQuestion for each question. For clarifying questions, provide 2-4 options where meaningful. Wait for the user's answer before asking the next question. Open questions (like feature description) can use free text.
@@ -169,7 +252,7 @@ Based on the feature description and discussion:
 
 ### Step 6: Create Feature Specification
 
-Write a comprehensive feature spec to `.5/{TICKET-ID}-{description}/feature.md` using the template structure.
+Write a comprehensive feature spec to `.5/features/{TICKET-ID}-{description}/feature.md` using the Write tool.
 
 **THIS IS YOUR FINAL OUTPUT. After creating this file, proceed immediately to Step 7.**
 
@@ -182,7 +265,7 @@ Key sections to populate:
 - **Problem Statement** - Why this feature is needed
 - **Requirements** - Functional and non-functional requirements from discussion
 - **Constraints** - Business, technical, and time constraints identified
-- **Affected Components** - Discovered from codebase exploration
+- **Affected Components** - From sub-agent exploration report
 - **Entity Definitions** - If the feature involves new data structures
 - **Acceptance Criteria** - Verifiable criteria for success
 - **Alternatives Considered** - Options discussed and why chosen approach was selected
@@ -195,11 +278,12 @@ Follow these steps **IN ORDER** and **STOP after step 8**:
 
 1. **Ask for feature description** - Request task description and additional information from developer
 2. **Extract Ticket ID** - Get current branch name and extract ticket ID using configured pattern
-3. **Explore the codebase** - Understand existing patterns and affected modules
-4. **Ask 5-10 clarifying questions** - Based on findings, ask informed questions using AskUserQuestion - This is MANDATORY
+3. **Spawn Explore sub-agent** - Delegate codebase analysis to read-only agent, wait for report
+4. **Ask 5-10 clarifying questions** - Based on sub-agent findings, ask informed questions using AskUserQuestion - This is MANDATORY
+   - **4b. Re-explore as needed** - If user mentions unknown components during Q&A, spawn targeted Explore agents
 5. **Challenge assumptions** - Present alternatives, question complexity
 6. **Determine feature name** - Create short kebab-case description
-7. **Create feature specification** in `.5/{TICKET-ID}-{description}/feature.md`
+7. **Create feature specification** in `.5/features/{TICKET-ID}-{description}/feature.md` using Write tool
 8. **Inform the developer** to review the spec, run `/clear` to reset context, and then run `/5:plan-implementation {TICKET-ID}-{description}`
 
 **🛑 STOP HERE. YOUR JOB IS COMPLETE. DO NOT PROCEED TO IMPLEMENTATION.**
@@ -208,12 +292,13 @@ Follow these steps **IN ORDER** and **STOP after step 8**:
 
 1. **Feature description first** - Get context before asking detailed questions
 2. **Auto-extract ticket ID** - Parse from branch name automatically
-3. **Explore before questioning** - Understand codebase to ask informed questions
-4. **Challenge assumptions** - Don't accept requirements at face value
-5. **Explore alternatives** - Present options and trade-offs
-6. **Document decisions** - Capture why choices were made
-7. **Structured output** - Use the feature spec template consistently
-8. **Clear handoff** - Tell developer what to do next
+3. **Delegate exploration** - Use read-only sub-agent for codebase analysis
+4. **Explore before questioning** - Wait for sub-agent report before asking questions
+5. **Challenge assumptions** - Don't accept requirements at face value
+6. **Explore alternatives** - Present options and trade-offs
+7. **Document decisions** - Capture why choices were made
+8. **Structured output** - Use the feature spec template consistently
+9. **Clear handoff** - Tell developer what to do next
 
 
 ## Common Feature Types
@@ -236,16 +321,21 @@ Follow these steps **IN ORDER** and **STOP after step 8**:
 
 ## Example Workflow
 
-1. User runs: `/plan-feature`
-2. Skill asks: "Please describe the feature you want to develop"
+1. User runs: `/5:plan-feature`
+2. Main agent asks: "Please describe the feature you want to develop"
 3. User: "I want to add emergency schedule tracking to products. It should allow marking products as emergency and setting a schedule window."
-4. Skill extracts: Ticket ID `PROJ-1234` from branch `PROJ-1234-add-emergency-schedule`
-5. Skill explores: Checks Product model, related components, existing scheduling infrastructure
-6. Skill asks 8 informed questions about requirements, scope, validation, API, etc.
-7. Skill challenges: "Could we reuse existing scheduling infrastructure instead of creating new one?"
-8. Skill determines: Feature name `add-emergency-schedule`
-9. Skill creates: `.5/PROJ-1234-add-emergency-schedule/feature.md`
-10. Skill tells user: "✅ Feature spec created at `.5/PROJ-1234-add-emergency-schedule/feature.md`
+4. Main agent extracts: Ticket ID `PROJ-1234` from branch `PROJ-1234-add-emergency-schedule`
+5. **Main agent spawns Explore sub-agent** with feature description
+6. **Sub-agent returns report:** Found Product model at src/models/Product.ts, existing ScheduleService at src/services/ScheduleService.ts, similar pattern in src/models/Promotion.ts...
+7. Main agent asks Question 1: "Should emergency schedules support recurring patterns or just one-time windows?"
+8. User answers: "One-time for now, but we have the NotificationService that should trigger alerts"
+9. **Main agent spawns targeted Re-Explore** for NotificationService (wasn't in initial report)
+10. **Sub-agent returns:** Found NotificationService at src/services/NotificationService.ts with event-based triggers...
+11. Main agent continues Q&A with better context about notifications
+12. Main agent challenges: "The sub-agent found existing ScheduleService - could we reuse it instead of creating new scheduling infrastructure?"
+13. Main agent determines: Feature name `add-emergency-schedule`
+14. Main agent creates: `.5/features/PROJ-1234-add-emergency-schedule/feature.md` using Write tool
+15. Main agent tells user: "✅ Feature spec created at `.5/features/PROJ-1234-add-emergency-schedule/feature.md`
 
     **Next steps:**
     1. Review the feature spec

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

@@ -1,26 +1,71 @@
 ---
 name: 5:plan-implementation
 description: Creates an implementation plan from a feature spec. Phase 2 of the 5-phase workflow.
-allowed-tools: Read, Glob, Grep, Task, AskUserQuestion, Write
+allowed-tools: Bash, Read, Write, Task, AskUserQuestion
 context: fork
 user-invocable: true
 ---
 
 # Plan Implementation (Phase 2)
 
+## Prerequisites Check
+
+**CRITICAL: Check for configuration before proceeding**
+
+```bash
+if [ ! -f ".claude/.5/config.json" ]; then
+  echo "❌ Configuration not found"
+  echo ""
+  echo "Please run /5:configure first to set up your project."
+  echo ""
+  echo "The configure command will:"
+  echo "  • Detect your project type and build commands"
+  echo "  • Set up ticket tracking conventions"
+  echo "  • Generate documentation (CLAUDE.md)"
+  echo "  • Create project-specific skills"
+  exit 1
+fi
+```
+
+**If config doesn't exist, STOP IMMEDIATELY. Do not proceed with the workflow.**
+
 Create an implementation plan that maps a feature spec to concrete components.
 
+## ⚠️ CRITICAL ARCHITECTURE
+
+**This command uses a READ-ONLY sub-agent for codebase exploration.**
+
+You (the main agent) orchestrate the process:
+- You read ONLY `.5/{feature-name}/feature.md` using Read tool
+- You spawn a read-only Explore agent to scan the codebase
+- You receive findings from the sub-agent
+- You ask 2-3 technical questions
+- You write ONLY `.5/{feature-name}/plan.md` using Write tool
+
+**The sub-agent CANNOT write files. It can only read and report.**
+
+**YOU may only write to `.5/{feature-name}/plan.md` - NO other files.**
+
 ## Scope
 
 **This command creates the plan. It does NOT implement.**
 
 After creating the plan, tell the user to run `/5:implement-feature`.
 
+## ❌ Boundaries
+
+- ❌ **Do NOT read source code files directly** - Use Explore sub-agent
+- ❌ **Do NOT write any file except plan.md** - No source code, no other files
+- ❌ **Do NOT start implementation** - That's Phase 3
+- ❌ **Do NOT write complete code in the plan** - Only describe WHAT to build
+
 ## Process
 
 ### Step 1: Load Feature Spec
 
-Read `.5/{feature-name}/feature.md` (where `{feature-name}` is the argument provided).
+Read `.5/features/{feature-name}/feature.md` (where `{feature-name}` is the argument provided).
+
+**This is the ONLY file you may read directly.**
 
 Extract:
 - Ticket ID
@@ -30,14 +75,36 @@ Extract:
 
 If the file doesn't exist, tell the user to run `/5:plan-feature` first.
 
-### Step 2: Quick Codebase Scan
+### Step 2: Spawn Read-Only Explore Agent for Codebase Scan
+
+**CRITICAL: Delegate ALL codebase exploration to a sub-agent.**
 
-Understand the project structure:
-- Use Glob to find source directories
-- Identify where similar components live (models, services, controllers, tests)
-- Note naming conventions from existing files
+Spawn a Task with `subagent_type=Explore` with the following prompt:
 
-This is a quick scan, not deep analysis. The executor agent will do detailed pattern matching.
+```
+Quick codebase scan for implementation planning.
+
+**Feature:** {one-line summary from feature.md}
+**Affected Components:** {list from feature.md}
+
+**Your Task:**
+1. Find source directories and understand project structure
+2. Identify where similar components live (models, services, controllers, tests)
+3. Note naming conventions from existing files
+4. Find example files that can serve as patterns for new components
+
+**Report Format:**
+Return a structured report with:
+- Project structure (key directories)
+- Naming conventions observed
+- Pattern files for each component type (e.g., "services follow pattern in src/services/UserService.ts")
+- Where new files should be placed
+
+**IMPORTANT:** This is a QUICK scan, not deep analysis. Focus on structure and patterns.
+**READ-ONLY:** Only use Read, Glob, and Grep tools.
+```
+
+**Wait for the sub-agent to return its findings before proceeding.**
 
 ### Step 3: Ask 2-3 Technical Questions (ONE AT A TIME)
 
@@ -54,11 +121,34 @@ Keep it brief. Don't over-question. Don't ask feature questions already answered
 
 - **ONE question at a time** - wait for answer before next question
 - Do NOT list multiple questions in one message
-- Do NOT skip to creating plan.md before asking your questions 
+- Do NOT skip to creating plan.md before asking your questions
+
+#### Step 3b: Optional Targeted Re-Exploration
+
+If during Q&A the user mentions specific patterns, files, or conventions not covered in the initial scan, you MAY spawn additional targeted Explore agents.
+
+**When to trigger:**
+- User mentions a specific file as a pattern to follow
+- User asks about a component not in the initial report
+- Understanding a specific pattern is critical for the plan
+
+**How to re-explore:**
+
+```
+Targeted scan for implementation planning.
+
+**Context:** User mentioned {specific pattern/file/convention}.
+
+**Task:** Find and analyze {specific target} to understand the pattern.
+
+**Report:** How this pattern works and how to apply it.
+
+**READ-ONLY:** Only use Read, Glob, and Grep tools.
+```
 
 ### Step 4: Design Components
 
-Based on the feature spec and codebase scan, identify:
+Based on the feature spec and sub-agent's codebase scan, identify:
 - What files need to be created
 - What files need to be modified
 - The order of implementation (dependencies)
@@ -73,7 +163,9 @@ Not every feature needs all steps. Use what makes sense.
 
 ### Step 5: Write the Plan
 
-Create a single file at `.5/{feature-name}/plan.md`:
+Create a single file at `.5/features/{feature-name}/plan.md`:
+
+**THIS IS THE ONLY FILE YOU MAY WRITE.**
 
 ```markdown
 ---
@@ -134,7 +226,7 @@ created: {ISO-timestamp}
 
 Tell the user:
 ```
-Plan created at `.5/{feature-name}/plan.md`
+Plan created at `.5/features/{feature-name}/plan.md`
 
 {N} components across {M} steps.
 
@@ -143,6 +235,23 @@ Review the plan, then:
 2. Run `/5:implement-feature {feature-name}`
 ```
 
+**🛑 STOP HERE. YOUR JOB IS COMPLETE. DO NOT PROCEED TO IMPLEMENTATION.**
+
+## Example Workflow
+
+1. User runs: `/5:plan-implementation PROJ-1234-add-emergency-schedule`
+2. Main agent reads: `.5/features/PROJ-1234-add-emergency-schedule/feature.md`
+3. **Main agent spawns Explore sub-agent** for codebase scan
+4. **Sub-agent returns:** Project uses src/{models,services,controllers}, services follow UserService.ts pattern...
+5. Main agent asks: "Should the schedule validation be in the service or a separate validator?"
+6. User: "In the service, like we do in OrderService"
+7. **Main agent spawns targeted Re-Explore** for OrderService pattern
+8. Main agent asks one more question about testing approach
+9. Main agent creates: `.5/features/PROJ-1234-add-emergency-schedule/plan.md`
+10. Main agent tells user the plan is ready and to run `/5:implement-feature`
+
+**🛑 COMMAND COMPLETE.**
+
 ## Example Plan
 
 ```markdown
@@ -215,8 +324,9 @@ Components in the same step run in parallel. Structure your plan accordingly:
 - Don't write complete code in the plan
 - Don't spend time on "haiku-ready prompts"
 - Don't create multiple plan files (meta.md, step-N.md, etc.)
-- Don't over-analyze the codebase - the executor will do detailed pattern matching
+- Don't read source code directly - use Explore sub-agent
 - Don't ask more than 3 questions
 - Don't create unnecessary sequential steps - group independent work together
 - **Don't skip to implementation** - This command ONLY creates the plan
 - **Don't batch questions** - Ask one question at a time
+- **Don't write any file except plan.md** - No source code files

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

@@ -8,6 +8,27 @@ user-invocable: true
 
 # Quick Implement
 
+## Prerequisites Check
+
+**CRITICAL: Check for configuration before proceeding**
+
+```bash
+if [ ! -f ".claude/.5/config.json" ]; then
+  echo "❌ Configuration not found"
+  echo ""
+  echo "Please run /5:configure first to set up your project."
+  echo ""
+  echo "The configure command will:"
+  echo "  • Detect your project type and build commands"
+  echo "  • Set up ticket tracking conventions"
+  echo "  • Generate documentation (CLAUDE.md)"
+  echo "  • Create project-specific skills"
+  exit 1
+fi
+```
+
+**If config doesn't exist, STOP IMMEDIATELY. Do not proceed with the workflow.**
+
 Fast path for small, well-understood tasks (1-5 files). Skips extensive planning phases but preserves state tracking and skill-based implementation.
 
 ## ⚠️ CRITICAL SCOPE CONSTRAINT
@@ -88,7 +109,7 @@ feature_name="${TICKET_ID}-${slug}"
 
 ### Step 5: Create Plan
 
-Write plan to `.5/${feature_name}/plan.md` using the template structure.
+Write plan to `.5/features/${feature_name}/plan.md` using the template structure.
 
 **Template Reference:** Use the structure from `.claude/templates/workflow/QUICK-PLAN.md`
 
@@ -130,7 +151,7 @@ Use AskUserQuestion:
 
 **CRITICAL**: You MUST create the state file before starting implementation. This enables resumability if work is interrupted.
 
-Create state file at `.5/${feature_name}/state.json` using Write tool:
+Create state file at `.5/features/${feature_name}/state.json` using Write tool:
 
 ```json
 {
@@ -283,7 +304,7 @@ Components created/modified:
 Build: Success
 Tests: {Success | Skipped}
 
-State: .5/${feature_name}/state.json
+State: .5/features/${feature_name}/state.json
 
 Next steps:
 1. Review and commit changes

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

@@ -9,6 +9,27 @@ user-invocable: true
 
 # Review Code (Phase 5)
 
+## Prerequisites Check
+
+**CRITICAL: Check for configuration before proceeding**
+
+```bash
+if [ ! -f ".claude/.5/config.json" ]; then
+  echo "❌ Configuration not found"
+  echo ""
+  echo "Please run /5:configure first to set up your project."
+  echo ""
+  echo "The configure command will:"
+  echo "  • Detect your project type and build commands"
+  echo "  • Set up ticket tracking conventions"
+  echo "  • Generate documentation (CLAUDE.md)"
+  echo "  • Create project-specific skills"
+  exit 1
+fi
+```
+
+**If config doesn't exist, STOP IMMEDIATELY. Do not proceed with the workflow.**
+
 ## Overview
 
 This command automates code review using a configurable review tool. The review tool is set in `.claude/.5/config.json` (`reviewTool` field). Two tools are supported:
@@ -27,7 +48,7 @@ Both tools produce the same structured output format, so all downstream steps (p
 6. Reports results
 
 **Workflow B: File-Based Annotation** (user preference)
-1. Runs review and saves findings to `.5/{feature-name}/review-{timestamp}-findings.md`
+1. Runs review and saves findings to `.5/features/{feature-name}/review-{timestamp}-findings.md`
 2. User edits the file to mark which findings to fix ([FIX], [SKIP], [MANUAL])
 3. User runs `/review-code apply` to read annotations and apply marked fixes
 
@@ -395,13 +416,13 @@ The template contains placeholders for:
 When user selects "Save to file", create a structured findings file that allows user annotation.
 
 **Determine feature name:**
-- Check most recent state file in `.5/*/state.json` to find current feature
+- Check most recent state file in `.5/features/*/state.json` to find current feature
 - Or ask user which feature they're reviewing
 - Use feature name for organizing review files
 
 **Create directory if needed:**
 ```bash
-mkdir -p .5/{feature-name}
+mkdir -p .5/features/{feature-name}
 ```
 
 **Generate timestamp:**
@@ -412,7 +433,7 @@ Example: 20260128-103045
 
 **File path:**
 ```
-.5/{feature-name}/review-{timestamp}-findings.md
+.5/features/{feature-name}/review-{timestamp}-findings.md
 ```
 
 **File format:**
@@ -433,7 +454,7 @@ The template contains:
 - **Next Steps:** Instructions to edit and run `/review-code apply`
 
 **After saving file:**
-- Inform user: "Findings saved to .5/{feature-name}/review-{timestamp}-findings.md"
+- Inform user: "Findings saved to .5/features/{feature-name}/review-{timestamp}-findings.md"
 - Provide instructions: "Edit the file to mark findings, then run: /review-code apply"
 - Skip remaining steps (don't apply fixes interactively)
 
@@ -442,13 +463,13 @@ The template contains:
 When user runs `/review-code apply`, read the most recent findings file and apply marked fixes.
 
 **Determine feature name:**
-- Check most recent state file in `.5/*/state.json` to find current feature
+- Check most recent state file in `.5/features/*/state.json` to find current feature
 - Or ask user which feature they're reviewing
 
 **Find the most recent findings file:**
 ```bash
 # Find most recent review findings file in the feature folder
-ls -t .5/{feature-name}/review-*-findings.md | head -1
+ls -t .5/features/{feature-name}/review-*-findings.md | head -1
 ```
 
 **If no findings file exists:**
@@ -528,7 +549,7 @@ After applying fixes from an annotated file, update the findings file with resul
 
 For interactive mode only, save the review summary to:
 ```
-.5/{feature-name}/review-{timestamp}.md
+.5/features/{feature-name}/review-{timestamp}.md
 ```
 
 ## Error Handling
@@ -614,7 +635,7 @@ Action: Please review the suggested fix manually.
 
 ## Configuration
 
-**Directory:** `.5/{feature-name}/` (organized by feature)
+**Directory:** `.5/features/{feature-name}/` (organized by feature)
 
 **File Types:**
 - `review-{timestamp}-findings.md` - Annotatable findings (file-based mode)
@@ -623,7 +644,7 @@ Action: Please review the suggested fix manually.
 **Timestamp Format:** Custom format `YYYYMMDD-HHmmss` (e.g., `20260128-103045`)
 
 **Feature Detection:** Review files are organized by feature. The command will:
-- Check most recent state file in `.5/*/state.json` to find current feature
+- Check most recent state file in `.5/features/*/state.json` to find current feature
 - Or ask user which feature they're reviewing if unclear
 
 ## Related Documentation

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

@@ -8,6 +8,27 @@ user-invocable: true
 
 # Verify Implementation (Phase 4)
 
+## Prerequisites Check
+
+**CRITICAL: Check for configuration before proceeding**
+
+```bash
+if [ ! -f ".claude/.5/config.json" ]; then
+  echo "❌ Configuration not found"
+  echo ""
+  echo "Please run /5:configure first to set up your project."
+  echo ""
+  echo "The configure command will:"
+  echo "  • Detect your project type and build commands"
+  echo "  • Set up ticket tracking conventions"
+  echo "  • Generate documentation (CLAUDE.md)"
+  echo "  • Create project-specific skills"
+  exit 1
+fi
+```
+
+**If config doesn't exist, STOP IMMEDIATELY. Do not proceed with the workflow.**
+
 Verify that an implementation is complete, correct, and meets feature requirements through multi-layer verification.
 
 ## Scope
@@ -26,11 +47,11 @@ If verification finds gaps, it generates a fix plan and offers to apply fixes au
 Read all workflow artifacts for the feature:
 
 **Required:**
-- `.5/{feature-name}/plan.md` — implementation plan (Phase 2)
-- `.5/{feature-name}/state.json` — implementation state (Phase 3)
+- `.5/features/{feature-name}/plan.md` — implementation plan (Phase 2)
+- `.5/features/{feature-name}/state.json` — implementation state (Phase 3)
 
 **Optional:**
-- `.5/{feature-name}/feature.md` — feature spec (Phase 1)
+- `.5/features/{feature-name}/feature.md` — feature spec (Phase 1)
 
 **If `plan.md` or `state.json` is missing:** hard stop.
 ```
@@ -198,7 +219,7 @@ Evaluate all three layers:
 
 ### Step 6: Generate Verification Report
 
-Write `.5/{feature-name}/verification.md` using the template structure from `.claude/templates/workflow/VERIFICATION-REPORT.md`.
+Write `.5/features/{feature-name}/verification.md` using the template structure from `.claude/templates/workflow/VERIFICATION-REPORT.md`.
 
 The report covers:
 - **Header:** ticket, feature, status, timestamp
@@ -209,7 +230,7 @@ The report covers:
 
 ### Step 7: Update State
 
-Update `.5/{feature-name}/state.json`:
+Update `.5/features/{feature-name}/state.json`:
 ```json
 {
   "verificationStatus": "passed | partial | failed",
@@ -264,7 +285,7 @@ Continue to Step 9.
 
 ### Step 9: Generate Fix Plan (PARTIAL or FAILED only)
 
-Write `.5/{feature-name}/fix-plan.md` using the template structure from `.claude/templates/workflow/FIX-PLAN.md`.
+Write `.5/features/{feature-name}/fix-plan.md` using the template structure from `.claude/templates/workflow/FIX-PLAN.md`.
 
 Build fix entries from verification results:
 

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

@@ -62,7 +62,7 @@ It handles three distinct tasks, invoked with different parameters per component
 ```
 
 **Process:**
-1. Read all values from the feature spec (`.5/CONFIGURE/feature.md`)
+1. Read all values from the feature spec (`.5/features/CONFIGURE/feature.md`)
 2. Ensure `.claude/.5/` directory exists (create with `mkdir -p` if needed)
 3. Write `config.json` with pretty-printed JSON
 4. Read back to verify correctness