5-phase-workflow 1.2.1 → 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.1",
+  "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
 ```
 
@@ -149,12 +153,150 @@ fi
 **1f. Scan existing skills:**
 - Check `.claude/skills/` for existing project-specific skills
 
+**1g. Detect codebase patterns** for potential skills:
+
+Use Glob to count files matching common architectural patterns:
+
+| Pattern | Glob Patterns                                                                 | Typical Location |
+|---------|-------------------------------------------------------------------------------|------------------|
+| **Core Architecture** |                                                                               | |
+| Controllers | `**/*Controller.{ts,js,java,py,rb}`, `**/controllers/**`                      | src/controllers/ |
+| Services | `**/*Service.{ts,js,java,py,rb}`, `**/services/**`                            | src/services/ |
+| Repositories | `**/*Repository.{ts,js,java,py}`, `**/repositories/**`                        | src/repositories/ |
+| Models/Entities | `**/*Model.{ts,js}`, `**/*Entity.java`, `**/models/**`                        | src/models/ |
+| Handlers | `**/*Handler.{ts,js,java,go}`, `**/handlers/**`                               | src/handlers/ |
+| **Data Transfer** |                                                                               | |
+| DTOs | `**/*Dto.{ts,js,java}`, `**/*DTO.{ts,js,java}`, `**/dto/**`                   | src/dto/ |
+| Requests | `**/*Request.{ts,js,java}`, `**/requests/**`                                  | src/requests/ |
+| Responses | `**/*Response.{ts,js,java}`, `**/responses/**`                                | src/responses/ |
+| Mappers | `**/*Mapper.{ts,js,java}`, `**/mappers/**`                                    | src/mappers/ |
+| Validators | `**/*Validator.{ts,js,java}`, `**/validators/**`                              | src/validators/ |
+| Schemas | `**/*Schema.{ts,js}`, `**/schemas/**`                                         | src/schemas/ |
+| **Frontend (React/Vue)** |                                                                               | |
+| Components | `**/components/**/*.{tsx,jsx,vue}`                                            | src/components/ |
+| Hooks | `**/hooks/**/*.{ts,js}`, `**/use*.{ts,js}`                                    | src/hooks/ |
+| Contexts | `**/contexts/**/*.{tsx,jsx}`, `**/*Context.{tsx,jsx}`                         | src/contexts/ |
+| Stores | `**/stores/**/*.{ts,js}`, `**/*Store.{ts,js}`                                 | src/stores/ |
+| Pages | `**/pages/**/*.{tsx,jsx}`, `**/app/**/page.{tsx,jsx}`                         | pages/, app/ |
+| Layouts | `**/layouts/**/*.{tsx,jsx,vue}`, `**/*Layout.{tsx,jsx}`                       | src/layouts/ |
+| **API/Routes** |                                                                               | |
+| API Routes | `**/api/**/*.{ts,js}`, `**/routes/**`                                         | src/api/, pages/api/ |
+| Middleware | `**/*Middleware.{ts,js,java}`, `**/middleware/**`                             | src/middleware/ |
+| Guards | `**/*.guard.{ts,js}`, `**/guards/**`                                          | src/guards/ |
+| Interceptors | `**/*.interceptor.{ts,js}`, `**/interceptors/**`                              | src/interceptors/ |
+| Filters | `**/*.filter.{ts,js}`, `**/*Filter.java`                                      | src/filters/ |
+| **Testing** |                                                                               | |
+| Tests | `**/*.test.{ts,js,tsx,jsx}`, `**/*.spec.{ts,js,tsx,jsx}`, `**/tests/**`       | src/, tests/ |
+| Specs | `**/*_spec.rb`, `**/spec/**/*.rb`, `**/*_test.go`, `**/test_*.py`             | spec/, tests/ |
+| Test Fixtures | `**/fixtures/**`,`**/testFixtures/**`, `**/__fixtures__/**`, `**/testdata/**` | fixtures/, testdata/ |
+| Factories | `**/*Factory.{ts,js,java,rb}`, `**/factories/**`                              | factories/ |
+| Mocks | `**/__mocks__/**`, `**/mocks/**`, `**/*Mock.{ts,js}`                          | __mocks__/, mocks/ |
+| **Utilities** |                                                                               | |
+| Utils | `**/utils/**/*.{ts,js,java,py}`, `**/*Utils.{ts,js,java}`                     | src/utils/ |
+| Helpers | `**/helpers/**/*.{ts,js,java,py,rb}`, `**/*Helper.{ts,js,java}`               | src/helpers/ |
+| Constants | `**/constants/**/*.{ts,js}`, `**/*Constants.{ts,js}`                          | src/constants/ |
+| Types/Interfaces | `**/types/**/*.{ts,js}`, `**/interfaces/**/*.{ts,java}`                       | src/types/ |
+| Config | `**/config/**/*.{ts,js,py}`, `**/*Config.{ts,js}`                             | src/config/ |
+| **Framework-Specific** |                                                                               | |
+| Modules (NestJS/Angular) | `**/*.module.{ts,js}`                                                         | src/modules/ |
+| Pipes (NestJS) | `**/*.pipe.{ts,js}`, `**/pipes/**`                                            | src/pipes/ |
+| Decorators | `**/decorators/**/*.{ts,js}`, `**/*.decorator.{ts,js}`                        | src/decorators/ |
+| Blueprints (Flask) | `**/blueprints/**/*.py`                                                       | blueprints/ |
+| Views (Django) | `**/views.py`, `**/views/**/*.py`                                             | app/views/ |
+| Serializers (Django) | `**/serializers.py`, `**/serializers/**/*.py`                                 | app/serializers/ |
+| **Background/Async** |                                                                               | |
+| Jobs | `**/jobs/**/*.{ts,js,rb}`, `**/*Job.{ts,js,rb}`                               | src/jobs/ |
+| Workers | `**/workers/**/*.{ts,js}`, `**/*Worker.{ts,js}`                               | src/workers/ |
+| Events | `**/events/**/*.{ts,js,java}`, `**/*Event.{ts,js,java}`                       | src/events/ |
+| Listeners | `**/listeners/**/*.{ts,js,java}`, `**/*Listener.{ts,js}`                      | src/listeners/ |
+| Commands (CLI) | `**/commands/**/*.{ts,js,java}`, `**/*Command.{ts,js}`                        | src/commands/ |
+| **Database** |                                                                               | |
+| Migrations | `**/migrations/**/*.{ts,js,sql,rb,py}`                                        | migrations/ |
+| Seeds | `**/seeds/**/*.{ts,js,rb}`, `**/seeders/**`                                   | seeds/ |
+| **Error Handling** |                                                                               | |
+| Exceptions | `**/exceptions/**/*.{ts,js,java}`, `**/*Exception.{ts,js,java}`               | src/exceptions/ |
+| Errors | `**/errors/**/*.{ts,js}`, `**/*Error.{ts,js}`                                 | src/errors/ |
+
+For each pattern found:
+- Count matching files
+- Identify primary location (most common directory)
+- Sample 1 file name to show convention
+
+**1h. Detect runnable commands** for potential command skills:
+
+Scan project configuration files for commands that can become skills:
+
+| Source | How to Detect | Example Commands |
+|--------|---------------|------------------|
+| package.json | Read `scripts` object | build, test, lint, format, dev, start, typecheck |
+| Makefile | Grep for targets (lines ending with `:`) | build, test, lint, clean, docker-build |
+| pyproject.toml | Read `[tool.poetry.scripts]` or `[project.scripts]` | test, lint, format, typecheck |
+| Cargo.toml | Check for `[[bin]]` sections, common cargo commands | build, test, clippy, fmt |
+| build.gradle | Grep for `task` definitions | build, test, lint, spotlessApply |
+| composer.json | Read `scripts` object | test, lint, format, analyse |
+| Rakefile | Grep for `task :name` patterns | test, lint, db:migrate, db:seed |
+
+**Common command categories to detect:**
+
+| Category | Common Names | Skill Name |
+|----------|--------------|------------|
+| **Build** | build, compile, bundle, pack | run-build |
+| **Test** | test, test:unit, test:integration, test:e2e, spec | run-tests |
+| **Lint** | lint, eslint, pylint, rubocop, clippy | run-lint |
+| **Format** | format, prettier, fmt, black, gofmt | run-format |
+| **Type Check** | typecheck, tsc, mypy, type-check | run-typecheck |
+| **Dev Server** | dev, start, serve, watch | run-dev |
+| **Database** | db:migrate, migrate, db:seed, seed, db:reset | run-db-migrate, run-db-seed |
+| **Docker** | docker:build, docker:up, docker:down, compose | run-docker |
+| **Deploy** | deploy, release, publish | run-deploy |
+| **Clean** | clean, reset, purge | run-clean |
+| **Generate** | generate, codegen, gen | run-generate |
+
+For each command found:
+- Record the exact command syntax
+- Identify any required environment or flags
+- Note if it has watch/CI variants
+
+Store results internally as:
+```json
+{
+  "detectedPatterns": {
+    "controller": { "count": 12, "location": "src/controllers/", "example": "UserController.ts" },
+    "service": { "count": 8, "location": "src/services/", "example": "AuthService.ts" },
+    "component": { "count": 25, "location": "src/components/", "example": "Button.tsx" }
+  },
+  "detectedCommands": {
+    "build": { "source": "package.json", "command": "npm run build", "variants": ["build:prod", "build:dev"] },
+    "test": { "source": "package.json", "command": "npm test", "variants": ["test:unit", "test:e2e"] },
+    "lint": { "source": "package.json", "command": "npm run lint", "variants": ["lint:fix"] },
+    "format": { "source": "package.json", "command": "npm run format", "variants": [] }
+  }
+}
+```
+
+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?"
@@ -201,10 +343,46 @@ fi
 - "Generate/update CLAUDE.md? This will analyze your codebase to document structure and conventions."
   - Options: "Yes (recommended)", "Skip"
 
-**2h. Confirm project-specific skills:**
-- Present proposed skills based on detected project type (see skill table in configure-project/SKILL.md)
-- "These project-specific skills were detected for your {project-type} project: {skill-list}. Confirm or customize?"
-  - Options: "Use these (recommended)", "Customize", "Skip skill generation"
+**2h. Review detected patterns for skill generation:**
+
+Present ONLY patterns that were actually detected in steps 1g and 1h.
+
+**Part 1: Architectural patterns (create-* skills)**
+
+"I analyzed your codebase and found these architectural patterns:
+
+| Pattern | Files Found | Location | Example |
+|---------|-------------|----------|---------|
+| Controller | 12 files | src/controllers/ | UserController.ts |
+| Service | 8 files | src/services/ | AuthService.ts |
+| Component | 25 files | src/components/ | Button.tsx |
+
+Which patterns would you like `create-*` skills generated for?"
+
+- Options: Multi-select checkboxes for each detected pattern (use AskUserQuestion with multiSelect: true)
+- Include descriptions like: "Controller (12 files) - Generate `create-controller` skill"
+- Plus "Other" option for patterns not detected but desired
+
+**Part 2: Command skills (run-* skills)**
+
+"I also found these runnable commands:
+
+| Command | Source | Full Command | Variants |
+|---------|--------|--------------|----------|
+| build | package.json | npm run build | build:prod, build:dev |
+| test | package.json | npm test | test:unit, test:e2e |
+| lint | package.json | npm run lint | lint:fix |
+| format | Makefile | make format | - |
+
+Which commands would you like `run-*` skills generated for?"
+
+- Options: Multi-select checkboxes for each detected command
+- Include descriptions like: "test - Generate `run-tests` skill"
+- Plus "Other" option for commands not detected
+
+If no patterns/commands detected:
+- Inform user: "No common patterns detected. Would you like to specify patterns manually?"
+- Allow manual entry of pattern names/locations or command names
 
 ### Step 3: Create Feature Spec
 
@@ -260,18 +438,59 @@ Analyze the codebase and generate modular documentation:
 - If CLAUDE.md already exists, preserve user-written custom sections
 
 ### Requirement 3: Generate Project-Specific Skills
-Generate the following skills in `.claude/skills/`:
-{List of confirmed skills, e.g.:}
-- create-component: Creates a React component following project conventions
-- create-hook: Creates a custom React hook following project conventions
-- create-context: Creates a React context provider following project conventions
 
-Each skill should:
+#### 3a. Create-* Skills (Architectural Patterns)
+
+Generate skills based on detected file patterns:
+
+| Pattern | Files | Location | Skill Name | Generate |
+|---------|-------|----------|------------|----------|
+| Controller | {count} | {location} | create-controller | ✓ |
+| Service | {count} | {location} | create-service | ✓ |
+| Component | {count} | {location} | create-component | ✓ |
+| {pattern} | {count} | {location} | create-{pattern} | ✗ (user skipped) |
+
+{Include only patterns where user selected "Generate = ✓"}
+
+For each selected pattern skill:
+1. Analyze 2-3 existing files from the pattern location
+2. Extract naming conventions, file structure, imports
+3. Generate SKILL.md with project-specific template
+
+Each create-* skill should:
 - Follow standard SKILL.md frontmatter pattern
+- Set `user-invocable: true` so users can invoke directly (e.g., `/create-controller UserController`)
+- Set `model: haiku` for fast, cheap pattern-following
 - Derive patterns from existing code in the project
 - Include file naming and location conventions
 - Include template/pattern based on existing examples
 
+#### 3b. Run-* Skills (Command Skills)
+
+Generate skills based on detected commands:
+
+| Command | Source | Full Command | Skill Name | Generate |
+|---------|--------|--------------|------------|----------|
+| build | {source} | {command} | run-build | ✓ |
+| test | {source} | {command} | run-tests | ✓ |
+| lint | {source} | {command} | run-lint | ✓ |
+| {command} | {source} | {full-command} | run-{command} | ✗ (user skipped) |
+
+{Include only commands where user selected "Generate = ✓"}
+
+For each selected command skill:
+1. Document the exact command and any variants
+2. Include common flags and options
+3. Document expected output and error handling
+
+Each run-* skill should:
+- Follow standard SKILL.md frontmatter pattern
+- Set `user-invocable: true` so users can invoke directly (e.g., `/run-tests`, `/run-lint`)
+- Set `model: haiku` for simple command execution
+- Include the exact command syntax
+- Document any environment requirements
+- Include common options/flags
+
 ## Acceptance Criteria
 - [ ] `.claude/.5/config.json` exists with correct values (no `steps` array)
 - [ ] `.5/` directory created
@@ -291,13 +510,13 @@ Each 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`"
@@ -339,11 +558,30 @@ User: "Yes"
 Claude: "Generate CLAUDE.md with codebase analysis?"
 User: "Yes"
 
-Claude: "Proposed skills for Next.js: create-page, create-api-route, create-component. Confirm?"
-User: "Use these"
-
-Claude: [Writes .5/CONFIGURE/feature.md]
-Claude: "Configuration feature planned at `.5/CONFIGURE/feature.md`"
+Claude: "I analyzed your codebase and found these patterns:
+| Pattern | Files | Location | Example |
+|---------|-------|----------|---------|
+| Component | 25 files | src/components/ | Button.tsx |
+| Hook | 8 files | src/hooks/ | useAuth.ts |
+| API Route | 12 files | pages/api/ | users.ts |
+| Page | 15 files | pages/ | index.tsx |
+
+Which patterns would you like `create-*` skills generated for?"
+User: [Selects Component, Hook, API Route]
+
+Claude: "I also found these runnable commands:
+| Command | Source | Full Command |
+|---------|--------|--------------|
+| build | package.json | npm run build |
+| test | package.json | npm test |
+| lint | package.json | npm run lint |
+| typecheck | package.json | npm run typecheck |
+
+Which commands would you like `run-*` skills generated for?"
+User: [Selects test, lint]
+
+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