5-phase-workflow 1.0.0

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

@@ -0,0 +1,285 @@
+---
+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
+context: fork
+user-invocable: true
+---
+
+# Plan Feature Implementation (Phase 1)
+
+## Overview
+
+This skill is the **first phase** of the 5-phase workflow:
+1. **Feature Planning** (this skill) - Understand requirements, create feature spec
+2. **Implementation Planning** - Map to technical components and skills
+3. **Orchestrated Implementation** - Execute with state tracking
+4. **Verify Implementation** - Check completeness and correctness
+5. **Code Review** - Apply automated quality improvements
+
+This skill guides intensive collaboration with the developer to understand requirements, challenge assumptions, and create a comprehensive feature specification.
+
+## Planning Process
+
+### Step 1: Gather Feature Description
+
+**FIRST ACTION:** Ask the developer for the feature description using AskUserQuestion.
+
+- Expect a **free-text answer**
+- Do NOT provide options
+- Do NOT ask follow-up questions yet
+- This input may be multiple paragraphs
+
+Prompt to use:
+
+"Please describe the feature you want to develop. Paste the full ticket description or explain it in your own words."
+
+Do NOT ask for ticket ID - it will be extracted from the branch name automatically.
+
+### Step 2: Extract Ticket ID from Branch Name
+
+Automatically extract the ticket ID from the current git branch:
+- Branch format: `{TICKET-ID}-description` (ticket is prefix)
+- Use `git branch --show-current` to get branch name
+- Extract ticket ID using configurable pattern from config (e.g., `PROJ-\d+` or `\d+`)
+- Ask the developer if the ticket ID is correct
+- If no ticket ID found, ask developer for it
+
+### Step 3: Analyze Existing Codebase
+
+Explore the codebase to understand existing patterns and identify affected modules:
+
+```
+1. Explore the project structure to identify modules/components
+   - Use Glob to discover relevant directories
+   - Look for patterns that indicate module organization
+
+2. Check existing implementations in relevant modules
+   - Search for similar features or components
+   - Identify coding patterns and conventions
+
+3. Check for similar patterns across the codebase
+   - Search for class/function patterns that might be reusable
+```
+
+Use Task tool with subagent_type=Explore for complex exploration.
+
+**Goal:** Understand what already exists so you can ask informed questions.
+
+### Step 4: Intensive Collaboration (5-10 Questions)
+
+**CRITICAL:** After exploring the codebase, engage in intensive Q&A using the AskUserQuestion tool. Ask 5-10 clarifying questions based on your findings. This is NOT optional.
+
+**Question categories to explore:**
+
+1. **Requirements Clarity**
+   - What exactly should this feature do?
+   - What is the expected user experience?
+   - What are the inputs and outputs?
+
+2. **Scope Boundaries**
+   - What is explicitly IN scope?
+   - What is explicitly OUT of scope?
+   - Are there any constraints or limitations?
+
+3. **Edge Cases**
+   - What happens when X fails?
+   - How should the system handle invalid inputs?
+   - What are the boundary conditions?
+
+4. **Performance Expectations**
+   - Are there performance requirements?
+   - How much data needs to be handled?
+   - Are there concurrency concerns?
+
+5. **Testing Strategy**
+   - How will we verify this works?
+   - What are the acceptance criteria?
+   - What test scenarios should be covered?
+
+6. **Integration Points**
+   - Which existing components/modules are affected?
+   - Are there API changes?
+   - How does this interact with existing features?
+
+7. **Alternative Approaches**
+   - Have you considered approach X instead?
+   - Is this the simplest solution?
+   - Could we reuse existing components?
+
+8. **Complexity Trade-offs**
+   - What is the complexity vs value trade-off?
+   - Should this be broken into smaller features?
+   - Are there simpler alternatives?
+
+**Challenge assumptions:**
+- "Is this the simplest solution?"
+- "Have you considered X alternative?"
+- "What happens when Y fails?"
+- "Could we use existing Z component instead?"
+- "Is a full factory needed or just simple creation?"
+
+Use AskUserQuestion to present options and trade-offs. Multiple questions can be asked in batches.
+
+### Step 5: Determine Feature Name
+
+Based on the feature description and discussion:
+- Create a short, kebab-case description (e.g., "add-emergency-schedule")
+- This will be used for the feature spec filename: `{TICKET-ID}-{description}.md`
+
+### Step 6: Create Feature Specification
+
+Write a comprehensive feature spec to `.5/{TICKET-ID}-{description}/feature.md` with the following structure:
+
+```markdown
+# Feature: {TICKET-ID} - {Title}
+
+## Ticket ID
+{TICKET-ID}
+
+## Summary
+{1-2 sentence overview of what will be implemented}
+
+## Problem Statement
+{Why is this feature needed? What problem does it solve?}
+
+## Requirements
+
+### Functional Requirements
+- {Requirement 1}
+- {Requirement 2}
+- ...
+
+### Non-Functional Requirements
+- {Performance requirements}
+- {Compatibility requirements}
+- ...
+
+## Constraints
+- {Business constraints}
+- {Technical constraints}
+- {Time/resource constraints}
+
+## Affected Components
+- **{component/module-1}** - {What changes here}
+- **{component/module-2}** - {What changes here}
+- **{component/module-3}** - {What changes here}
+- ...
+
+## Entity/Component Definitions
+
+### {EntityName} (if applicable)
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | {Entity}Id | Yes | Unique identifier |
+| name | String | Yes | Entity name |
+| ... | ... | ... | ... |
+
+### Business Rules
+- {Rule 1}
+- {Rule 2}
+- ...
+
+## Acceptance Criteria
+- [ ] {Criterion 1 - how to verify success}
+- [ ] {Criterion 2}
+- [ ] {Criterion 3}
+- ...
+
+## Alternatives Considered
+
+### Option 1: {Alternative approach}
+**Pros:** {Benefits}
+**Cons:** {Drawbacks}
+**Decision:** Rejected because {reason}
+
+### Option 2: {Another alternative}
+**Pros:** {Benefits}
+**Cons:** {Drawbacks}
+**Decision:** Rejected because {reason}
+
+### Chosen Approach: {Selected approach}
+**Rationale:** {Why this approach was chosen}
+
+## Questions & Answers
+
+### Q1: {Question from collaboration phase}
+**A:** {Answer from developer}
+
+### Q2: {Question}
+**A:** {Answer}
+
+...
+
+## Next Steps
+After approval, run: `/plan-implementation {TICKET-ID}-{description}`
+```
+
+## Instructions
+
+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
+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`
+8. **Inform the developer** to review the spec and then run `/plan-implementation {TICKET-ID}-{description}`
+
+## Key Principles
+
+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
+
+## DO NOT in This Skill
+
+- DO NOT ask for ticket ID (extract from branch name automatically)
+- DO NOT skip asking for feature description first
+- DO NOT ask questions before exploring the codebase
+- DO NOT create TodoWrite task lists (that's Phase 2's job)
+- DO NOT map components to skills (that's Phase 2's job)
+- DO NOT start implementation (that's Phase 3's job)
+- DO NOT skip the intensive Q&A phase
+- DO NOT accept vague requirements
+
+## Common Feature Types
+
+### New Component/Module
+- Requires: Core logic, data structures, tests
+- Questions: Validation rules? Business logic? API design?
+
+### Extend Existing Component
+- Requires: Update existing code, maintain compatibility
+- Questions: Breaking change? Migration needed? Impact on existing functionality?
+
+### Add Business Rule
+- Requires: Logic implementation, validation
+- Questions: When is rule enforced? What are edge cases?
+
+### API Endpoint
+- Requires: Endpoint implementation, request/response handling
+- Questions: API design? Error handling? Authentication?
+
+## Example Workflow
+
+1. User runs: `/plan-feature`
+2. Skill 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. Please review and then run `/plan-implementation PROJ-1234-add-emergency-schedule`"
+11. Skill tells user: "If the feature needs refinements, run `/discuss-feature PROJ-1234-add-emergency-schedule`"
+
+## Related Documentation
+
+- [5-Phase Workflow Guide](../docs/workflow-guide.md)

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

@@ -0,0 +1,376 @@
+---
+name: 5:plan-implementation
+description: Creates a precise, AI-executable implementation plan. Performs all codebase analysis upfront and produces self-contained component prompts that can be executed by haiku without exploration. Phase 2 of the 5-phase workflow.
+allowed-tools: Read, Glob, Grep, Task, AskUserQuestion, Write
+context: fork
+user-invocable: true
+---
+
+# Plan Implementation (Phase 2)
+
+## Overview
+
+This skill is the **second phase** of the 5-phase workflow:
+1. **Feature Planning** - Understand requirements, create feature spec (completed)
+2. **Implementation Planning** (this skill) - Analyze codebase, produce AI-executable plan
+3. **Orchestrated Implementation** - Execute plan with haiku agents
+4. **Verify Implementation** - Check completeness and correctness
+5. **Code Review** - Apply automated quality improvements
+
+**Critical design constraint:** The plan must be executable by haiku-model agents without any codebase exploration. This means YOU must do all analysis upfront and embed everything into the plan: exact file paths, exact code patterns, reference snippets, imports, and complete instructions.
+
+## Prerequisites
+
+Before invoking this skill, ensure:
+1. Feature spec exists at `.5/{TICKET-ID}-{description}/feature.md`
+2. Feature spec has been reviewed and approved by developer
+3. You have the feature name/ticket ID ready
+
+## Planning Process
+
+### Step 1: Read Feature Specification
+
+Read the feature spec from `.5/{feature-name}/feature.md`.
+
+Extract:
+- Ticket ID
+- Summary
+- Requirements (functional and non-functional)
+- Affected domains
+- Entity definitions
+- Business rules
+- Acceptance criteria
+
+### Step 2: Deep Codebase Analysis
+
+**This is the most important step.** You must gather all context that the executor agents will need, because they cannot explore the codebase themselves.
+
+**2a. Project structure:**
+- Use Glob to map the directory structure
+- Identify source directories, test directories, config locations
+- Understand module/package organization
+
+**2b. Existing patterns (read actual files):**
+- Find 1-2 existing examples of each component type needed (e.g., an existing service, model, controller)
+- Read them fully to extract:
+  - Import statements and patterns
+  - Class/function structure
+  - Naming conventions (file names, variable names, export style)
+  - Error handling patterns
+  - Test patterns
+
+**2c. Dependencies and integration points:**
+- Read registration files, route files, module declarations
+- Understand how new components get wired in
+- Identify exact locations where modifications are needed (file path + line context)
+
+**2d. Build/test configuration:**
+- Read `.claude/.5/config.json` for build commands
+- Read available skills from `.claude/skills/`
+
+### Step 3: Technical Collaboration (3-5 Questions)
+
+Ask targeted technical questions using AskUserQuestion:
+- Data layer decisions (persistence, query patterns)
+- Validation requirements
+- API design choices
+- Whether to create new vs extend existing components
+- Challenge the approach: suggest simpler alternatives
+
+### Step 4: Map Components to Skills
+
+For each component, determine:
+- Which skill creates it (from `.claude/skills/`)
+- Or `null` if no matching skill exists (component will be created directly via Write/Edit)
+
+### Step 5: Determine Dependency Steps
+
+Group components by dependencies:
+1. Components with no dependencies → first step (parallel)
+2. Components depending on step 1 → second step
+3. Continue until all assigned
+4. Name steps based on content
+
+### Step 6: Build Component Prompts
+
+**For each component, create a complete, self-contained execution prompt.** This prompt must contain everything a haiku agent needs to create the file without exploring anything.
+
+**For `action: create` components, the prompt must include:**
+- The complete file content to write, OR
+- A reference snippet from an existing file + clear instructions on what to change
+- All import statements
+- All type definitions needed
+- Exact file path
+
+**For `action: modify` components, the prompt must include:**
+- The exact file path
+- The exact `old_string` to find (copied from the actual file)
+- The exact `new_string` to replace it with
+- Context about what's above/below to ensure uniqueness
+
+**Prompt quality checklist:**
+- Could a developer who has never seen this codebase execute this prompt? If no, add more context.
+- Are all imports specified? If the component imports from other new components in this plan, are those paths correct?
+- Is the file path correct relative to the project root?
+- For modifications: is the old_string unique in the file?
+
+### Step 7: Write Implementation Plan
+
+Write the plan to `.5/{feature-name}/plan.md` using this exact format:
+
+```markdown
+# Plan: {TICKET-ID} - {Title}
+
+## Meta
+feature: {feature-name}
+ticket: {ticket-id}
+total_steps: {N}
+total_components: {N}
+new_files: {N}
+modified_files: {N}
+
+## Summary
+{1-2 sentences: what this plan builds and why}
+
+## Steps
+
+### step: 1
+name: "{descriptive name}"
+mode: parallel | sequential
+
+#### component: {component-id}
+action: create | modify
+file: "{exact/path/to/file.ext}"
+skill: "{skill-name}" | null
+depends_on: []
+prompt: |
+  {Complete, self-contained execution instructions.
+  For create: include full file content or reference snippet + modifications.
+  For modify: include exact old_string and new_string.
+  Include all imports. Include all types.
+  This prompt is passed directly to a haiku agent that cannot explore the codebase.}
+
+#### component: {component-id-2}
+action: create | modify
+file: "{exact/path/to/file.ext}"
+skill: "{skill-name}" | null
+depends_on: []
+prompt: |
+  {Complete instructions}
+
+### step: 2
+name: "{descriptive name}"
+mode: parallel | sequential
+
+#### component: {component-id-3}
+action: create | modify
+file: "{exact/path/to/file.ext}"
+skill: null
+depends_on: ["{component-id}", "{component-id-2}"]
+prompt: |
+  {Complete instructions}
+
+## Verification
+build_command: "{from config}"
+test_command: "{from config}"
+expected_new_files:
+  - "{path1}"
+  - "{path2}"
+expected_modified_files:
+  - "{path3}"
+
+## Risks
+- "{risk 1}: {mitigation}"
+- "{risk 2}: {mitigation}"
+```
+
+### Step 8: Inform Developer
+
+After creating the implementation plan, tell the developer:
+
+1. "Implementation plan created at `.5/{feature-name}/plan.md`"
+2. "{N} components across {M} steps"
+3. "Each component has a self-contained execution prompt for haiku agents"
+4. "Please review, then run: `/5:implement-feature {feature-name}`"
+
+## Component Prompt Examples
+
+### Example: Create a new TypeScript service
+
+```
+#### component: schedule-service
+action: create
+file: "src/services/ScheduleService.ts"
+skill: null
+depends_on: ["schedule-model"]
+prompt: |
+  Create file `src/services/ScheduleService.ts` with this content:
+
+  ```typescript
+  import { Schedule } from '../models/Schedule';
+  import { ScheduleRepository } from '../repositories/ScheduleRepository';
+  import { ValidationError } from '../errors/ValidationError';
+
+  export class ScheduleService {
+    constructor(private readonly repo: ScheduleRepository) {}
+
+    async create(data: { name: string; startDate: Date; endDate: Date }): Promise<Schedule> {
+      if (data.endDate <= data.startDate) {
+        throw new ValidationError('endDate must be after startDate');
+      }
+      return this.repo.save(new Schedule(data));
+    }
+
+    async findById(id: string): Promise<Schedule | null> {
+      return this.repo.findById(id);
+    }
+
+    async delete(id: string): Promise<void> {
+      return this.repo.delete(id);
+    }
+  }
+  ```
+
+  This follows the pattern from `src/services/UserService.ts`.
+```
+
+### Example: Modify an existing router file
+
+```
+#### component: register-schedule-routes
+action: modify
+file: "src/routes/index.ts"
+skill: null
+depends_on: ["schedule-controller"]
+prompt: |
+  Modify file `src/routes/index.ts`.
+
+  Find this exact string:
+  ```
+  // Route registrations
+  app.use('/api/users', userRoutes);
+  ```
+
+  Replace with:
+  ```
+  // Route registrations
+  app.use('/api/users', userRoutes);
+  app.use('/api/schedules', scheduleRoutes);
+  ```
+
+  Also add this import at the top of the file, after the existing imports:
+  Find: `import { userRoutes } from './userRoutes';`
+  Replace with:
+  ```
+  import { userRoutes } from './userRoutes';
+  import { scheduleRoutes } from './scheduleRoutes';
+  ```
+```
+
+### Example: Create a test file
+
+```
+#### component: schedule-service-test
+action: create
+file: "src/services/__tests__/ScheduleService.test.ts"
+skill: null
+depends_on: ["schedule-service"]
+prompt: |
+  Create file `src/services/__tests__/ScheduleService.test.ts` with this content:
+
+  ```typescript
+  import { ScheduleService } from '../ScheduleService';
+  import { ScheduleRepository } from '../../repositories/ScheduleRepository';
+  import { ValidationError } from '../../errors/ValidationError';
+
+  describe('ScheduleService', () => {
+    let service: ScheduleService;
+    let mockRepo: jest.Mocked<ScheduleRepository>;
+
+    beforeEach(() => {
+      mockRepo = {
+        save: jest.fn(),
+        findById: jest.fn(),
+        delete: jest.fn(),
+      } as any;
+      service = new ScheduleService(mockRepo);
+    });
+
+    describe('create', () => {
+      it('creates a schedule with valid dates', async () => {
+        const data = {
+          name: 'Test',
+          startDate: new Date('2026-01-01'),
+          endDate: new Date('2026-01-31'),
+        };
+        mockRepo.save.mockResolvedValue({ id: '1', ...data } as any);
+        const result = await service.create(data);
+        expect(mockRepo.save).toHaveBeenCalled();
+        expect(result).toBeDefined();
+      });
+
+      it('throws if endDate <= startDate', async () => {
+        const data = {
+          name: 'Test',
+          startDate: new Date('2026-01-31'),
+          endDate: new Date('2026-01-01'),
+        };
+        await expect(service.create(data)).rejects.toThrow(ValidationError);
+      });
+    });
+  });
+  ```
+
+  This follows the test pattern from `src/services/__tests__/UserService.test.ts`.
+```
+
+## Instructions Summary
+
+1. **Read feature spec** from `.5/{feature-name}/feature.md`
+2. **Deep codebase analysis** - Read actual files, extract patterns, imports, conventions. This is the critical step.
+3. **Ask 3-5 technical questions** - Clarify implementation details
+4. **Map components to skills** - Check `.claude/skills/` for available skills
+5. **Group into dependency steps** - Based on component dependencies
+6. **Build self-contained prompts** - Each prompt must be executable by haiku without exploration
+7. **Write plan** to `.5/{feature-name}/plan.md` in the structured format
+8. **Inform developer** to review and run `/5:implement-feature`
+
+## Key Principles
+
+1. **Haiku-ready prompts** - Every component prompt is self-contained with all context baked in
+2. **No exploration by executors** - All codebase analysis happens here in Phase 2
+3. **Exact file paths** - No guessing, no pattern matching needed
+4. **Reference code inline** - Include actual snippets, not "look at file X"
+5. **Dependency-driven steps** - Step grouping from component dependencies
+6. **Verify prompt quality** - Could someone with no codebase knowledge execute it?
+
+## DO NOT
+
+- DO NOT start implementation (that's Phase 3's job)
+- DO NOT create state files (that's `/implement-feature`'s job)
+- DO NOT write vague prompts like "follow existing patterns" without including the pattern
+- DO NOT skip codebase analysis - reading actual files is mandatory
+- DO NOT leave file paths ambiguous
+- DO NOT write prompts that require the executor to read other files to understand what to do
+- DO NOT assume the executor can figure things out - be explicit
+
+## Example Usage
+
+```
+User: /plan-implementation PROJ-1234-add-emergency-schedule
+
+Skill:
+1. Reads .5/PROJ-1234-add-emergency-schedule/feature.md
+2. Explores codebase: reads existing models, services, routes, tests
+3. Extracts patterns: import style, naming, structure, test framework
+4. Asks technical questions about validation, persistence, API
+5. Maps components to skills (or null for direct execution)
+6. Groups into steps by dependencies
+7. Builds self-contained prompts with inline code and exact paths
+8. Creates .5/PROJ-1234-add-emergency-schedule/plan.md
+9. Tells user: "Plan created with 7 components across 3 steps. Review and run /5:implement-feature"
+```
+
+## Related Documentation
+
+- [5-Phase Workflow Guide](../docs/workflow-guide.md)