5-phase-workflow 1.2.2 → 1.4.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

@@ -373,7 +373,11 @@ function getDefaultConfig(projectType) {
       command: 'auto',
       testCommand: 'auto'
     },
-    reviewTool: 'claude'
+    reviewTool: 'claude',
+    git: {
+      autoCommit: false,
+      commitMessage: { pattern: '{ticket-id} {short-description}' }
+    }
   };
 
   // Project-specific overrides
@@ -467,6 +471,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 +594,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 +648,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,12 +1,15 @@
 {
   "name": "5-phase-workflow",
-  "version": "1.2.2",
+  "version": "1.4.0",
   "description": "A 5-phase feature development workflow for Claude Code",
   "bin": {
     "5-phase-workflow": "bin/install.js"
   },
   "scripts": {
-    "test": "bash test/verify-install-js.sh",
+    "test": "bash test/verify-install-js.sh && bash test/test-check-updates-hook.sh && bash test/test-update-system.sh",
+    "test:install": "bash test/verify-install-js.sh",
+    "test:hook": "bash test/test-check-updates-hook.sh",
+    "test:update": "bash test/test-update-system.sh",
     "verify": "bash test/verify-install-js.sh"
   },
   "files": [

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
 ```
 
@@ -141,6 +145,9 @@ if command -v coderabbit &> /dev/null; then
 fi
 
 # IDE MCP (JetBrains) - check if MCP tools are available
+
+# Context7 - up-to-date documentation MCP server
+# Check if context7 tools are available (resolve-library-id, query-docs)
 ```
 
 **1e. Check CLAUDE.md:**
@@ -275,9 +282,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?"
@@ -307,7 +329,21 @@ Only include patterns/commands that are actually detected.
 - "Suggested test command: `{command}`. Use this?"
   - Options: "Yes (recommended)", "Customize", "None (no test step)"
 
-**2f. Review tool preference:**
+**2f. Auto-commit during implementation:**
+- "Should Claude make atomic commits during implementation? This creates a commit after each step, enabling progress tracking and easy rollback."
+  - Options:
+    1. "No (recommended)" → `git.autoCommit: false`
+    2. "Yes - commit after each implementation step" → `git.autoCommit: true`
+
+**2g. Commit message pattern (only if auto-commit = Yes):**
+- "What commit message format would you like?"
+  - Options:
+    1. "Default: `{ticket-id} {short-description}` (Recommended)"
+    2. "Conventional: `feat({ticket-id}): {short-description}`"
+    3. "Custom pattern" → free text
+- Note: "Body will automatically include bullet points of changes."
+
+**2h. Review tool preference:**
 - "Which code review tool would you like to use?"
   - Options:
     1. "Claude (built-in, no setup needed)" — always available
@@ -320,11 +356,24 @@ Only include patterns/commands that are actually detected.
     - Then: `coderabbit auth login`
   - Record the preference as `coderabbit` regardless (will prompt at review time if still missing)
 
-**2g. Confirm CLAUDE.md generation:**
+**2i. Context7 documentation plugin:**
+
+Context7 provides up-to-date, version-specific documentation and code examples directly in your prompts. It solves a common problem with LLMs: outdated training data leading to hallucinated APIs and deprecated code patterns.
+
+- If Context7 was detected in Step 1d (resolve-library-id and query-docs tools available):
+  - "Context7 is already installed. ✓"
+- If Context7 was NOT detected:
+  - "Would you like to install Context7? It provides up-to-date, version-specific documentation directly in prompts — helping avoid hallucinated APIs and deprecated patterns."
+  - Options:
+    1. "Install now (recommended)" — run `claude mcp add context7 -- npx -y @anthropic-ai/claude-code-mcp-server-context7` via Bash
+    2. "Skip"
+  - If user selects "Install now": execute the install command
+
+**2j. Confirm CLAUDE.md generation:**
 - "Generate/update CLAUDE.md? This will analyze your codebase to document structure and conventions."
   - Options: "Yes (recommended)", "Skip"
 
-**2h. Review detected patterns for skill generation:**
+**2k. Review detected patterns for skill generation:**
 
 Present ONLY patterns that were actually detected in steps 1g and 1h.
 
@@ -389,7 +438,10 @@ Create `.claude/.5/config.json` with the following values:
 - Test timeout: 300000ms
 - CodeRabbit: {available/not-available}, authenticated: {yes/no}
 - IDE integration: {available/not-available}, type: {type}
+- Context7: {available/not-available}
 - Review tool: {claude/coderabbit/none}
+- Auto-commit: {yes/no}
+- Commit message pattern: {pattern or "default"}
 
 ### Requirement 2: Generate Documentation Files
 Analyze the codebase and generate modular documentation:
@@ -491,13 +543,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`"
@@ -536,6 +588,12 @@ User: "Yes"
 Claude: "Test command: `npm test`. Use this?"
 User: "Yes"
 
+Claude: "Should Claude make atomic commits during implementation?"
+User: "No"
+
+Claude: "Which code review tool would you like to use?"
+User: "Claude (built-in)"
+
 Claude: "Generate CLAUDE.md with codebase analysis?"
 User: "Yes"
 
@@ -561,8 +619,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

@@ -1,13 +1,34 @@
 ---
 name: 5:implement-feature
 description: Executes an implementation plan by delegating to agents. Phase 3 of the 5-phase workflow.
-allowed-tools: Task, Read, Write, Glob, Grep
+allowed-tools: Task, Read, Write, Glob, Grep, Bash
 context: fork
 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
@@ -25,9 +46,9 @@ Do NOT write code directly. Spawn agents to do the work.
 
 ## Process
 
-### Step 1: Load Plan
+### Step 1: Load Plan and Config
 
-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
@@ -37,9 +58,13 @@ Parse:
 
 If the plan doesn't exist, tell the user to run `/5:plan-implementation` first.
 
+Also read `.claude/.5/config.json` and extract:
+- `git.autoCommit` (boolean, default `false`)
+- `git.commitMessage.pattern` (string, default `{ticket-id} {short-description}`)
+
 ### Step 2: Initialize State
 
-Create `.5/{feature-name}/state.json`:
+Create `.5/features/{feature-name}/state.json`:
 
 ```json
 {
@@ -159,7 +184,39 @@ Update state.json:
 }
 ```
 
-**3e. Handle failures**
+**3e. Auto-Commit Step (if enabled)**
+
+Only fires if `git.autoCommit: true` AND at least one component in the step succeeded.
+
+1. Stage **only** the specific files from the plan's components table for this step (never `git add .`)
+2. Commit using the configured `git.commitMessage.pattern`:
+   - `{ticket-id}` → ticket ID from plan frontmatter
+   - `{short-description}` → auto-generated summary of the step (imperative mood, max 50 chars for the full first line)
+   - Body: one bullet per completed component
+
+```bash
+# Stage only specific files from this step's components
+git add {file-1} {file-2} ...
+
+# Commit with configured pattern + body
+git commit -m "{ticket-id} {short-description}
+
+- {concise change 1}
+- {concise change 2}"
+```
+
+3. If commit fails → log warning, record in `state.json` under `commitResults` array, continue
+4. If all components in the step failed → skip commit entirely
+
+**Example commit:**
+```
+PROJ-1234 add schedule model and types
+
+- Create Schedule.ts entity model
+- Create schedule.ts type definitions
+```
+
+**3f. Handle failures**
 
 If any component failed:
 - Log the failure in state.json
@@ -202,6 +259,7 @@ Implementation complete!
 - {N} components created/modified
 - Build: {status}
 - Tests: {status}
+{If git.autoCommit was true: "- Commits: {N} atomic commits created"}
 
 {If any failures: list them}