plan generated by qwest

gistfile1.txt

# Add Slash Commands: /spec and /plan

## Overview

This design document outlines the addition of two new built-in slash commands to Takumi's command system: `/spec` and `/plan`. These commands enhance the AI-assisted development workflow by providing structured approaches to idea refinement and implementation planning.

**Purpose:**

- `/spec`: Interactive brainstorming command that helps transform rough ideas into fully-formed design specifications through guided questioning
- `/plan`: Planning command that generates comprehensive, bite-sized implementation plans from specifications

**Target Users:**
Developers who need AI assistance to:

- Refine vague ideas into concrete technical specifications
- Generate detailed implementation roadmaps
- Ensure thorough planning before code implementation

## Command Specifications

### /spec Command (Brainstorm Type)

**Command Definition:**

| Property         | Value                                                                     |
| ---------------- | ------------------------------------------------------------------------- |
| Name             | `spec`                                                                    |
| Type             | `prompt`                                                                  |
| Description      | Transform ideas into fully-formed designs through interactive questioning |
| Progress Message | Analyzing your idea and preparing questions...                            |

**Behavioral Characteristics:**

1. **Context-Aware Analysis**

   - Analyzes current project structure and codebase state before questioning
   - Identifies relevant patterns, technologies, and architectural constraints
   - Uses project context to ask informed, specific questions

2. **Questioning Strategy**

   - Asks one question at a time to avoid overwhelming the user
   - Prioritizes multiple-choice questions when feasible for faster iteration
   - Falls back to open-ended questions when necessary for complex topics
   - Sequences questions logically from high-level to implementation details

3. **Question Categories**
   | Category | Purpose | Example Questions |
   |----------|---------|-------------------|
   | Scope Definition | Establish feature boundaries | "Is this for CLI, browser, or both interfaces?" |
   | User Experience | Clarify interaction patterns | "Should this be interactive or batch-processed?" |
   | Technical Approach | Identify implementation strategy | "Will this use existing tools or require new ones?" |
   | Integration Points | Map dependencies | "Which existing components will this interact with?" |
   | Data & State | Define data requirements | "What data needs to persist? What's ephemeral?" |
   | Validation | Establish acceptance criteria | "How will users know this succeeded?" |

4. **Design Presentation**

   - After gathering sufficient information, stops questioning
   - Presents the design in structured sections (200-300 words each)
   - Waits for user confirmation after each section
   - Iterates on sections based on user feedback
   - Continues until user approves the complete design

5. **Output Format**
   - Natural language descriptions organized by logical sections
   - Tables for structured data (parameters, options, states)
   - Mermaid diagrams for flows and architecture when beneficial
   - No code implementation details (stays at design level)

**Prompt Template Structure:**

The prompt instructs the AI to:

- Examine the working directory to understand current project state
- Extract context about existing patterns, tools, and conventions
- Ask focused questions one at a time
- Prioritize multiple-choice format
- Present design incrementally with section-by-section confirmation
- Avoid premature implementation discussions

### /plan Command (Write-Plans Type)

**Command Definition:**

| Property         | Value                                                           |
| ---------------- | --------------------------------------------------------------- |
| Name             | `plan`                                                          |
| Type             | `prompt`                                                        |
| Description      | Generate comprehensive implementation plans as bite-sized tasks |
| Progress Message | Creating detailed implementation plan...                        |

**Behavioral Characteristics:**

1. **Audience Assumption**

   - Assumes engineer has zero codebase context
   - Assumes skilled developer with questionable taste
   - Assumes limited knowledge of toolset and problem domain
   - Assumes weak test design understanding

2. **Plan Granularity**

   - Breaks work into bite-sized, independently completable tasks
   - Each task targets 15-45 minutes of focused work
   - Tasks ordered to enable incremental testing and validation
   - Emphasizes frequent commits after each completed task

3. **Task Documentation Standards**

   Each task must specify:

   | Element               | Description                                      |
   | --------------------- | ------------------------------------------------ |
   | Task Title            | Clear, action-oriented description               |
   | Files to Touch        | Exact file paths to create or modify             |
   | Changes Required      | What to add, modify, or remove in each file      |
   | Testing Approach      | How to verify the change works                   |
   | Validation Criteria   | Specific checks before considering task complete |
   | Related Documentation | Docs or comments to review for context           |

4. **Development Principles**

   Plans must emphasize:

   | Principle                        | Application                                    |
   | -------------------------------- | ---------------------------------------------- |
   | DRY (Don't Repeat Yourself)      | Identify and extract repeated patterns         |
   | YAGNI (You Aren't Gonna Need It) | Avoid speculative features                     |
   | TDD (Test-Driven Development)    | Write tests before or alongside implementation |
   | Frequent Commits                 | Commit after each task completion              |

5. **Test Design Guidance**

   Since the engineer has weak test design skills, plans must include:

   - Specific test cases to write (not just "add tests")
   - Expected inputs and outputs for each test
   - Edge cases and error conditions to cover
   - Mock/stub requirements and setup instructions
   - Integration vs unit test recommendations

6. **Output Structure**

   Plans are documented in a structured format:

   ```
   Implementation Plan: [Feature Name]

   ## Overview
   [Brief summary of what will be built and why]

   ## Prerequisites
   - Required knowledge areas
   - Documentation to review
   - Tools or dependencies needed

   ## Task Breakdown

   ### Task 1: [Title]
   **Files:**
   - path/to/file1.ts
   - path/to/file2.ts

   **Changes:**
   [Detailed description of changes]

   **Testing:**
   [How to test this task]

   **Validation:**
   [Checklist before moving on]

   ### Task 2: [Title]
   ...

   ## Testing Strategy
   [Overall testing approach]

   ## Deployment Notes
   [Any deployment considerations]
   ```

**Prompt Template Structure:**

The prompt instructs the AI to:

- Analyze the current codebase structure
- Review existing patterns and conventions
- Create a comprehensive task list with full context
- Document every file to touch and why
- Provide explicit testing instructions
- Include validation criteria for each task
- Write the plan to a markdown file in `docs/plans/`

## Command Integration

### Registration Flow

```mermaid
flowchart TD
    A[createBuiltinCommands called] --> B[Create /spec command]
    A --> C[Create /plan command]
    B --> D[Register in builtin commands array]
    C --> D
    D --> E[SlashCommandManager loads commands]
    E --> F[Commands available to users]
```

### Command Discovery

Both commands will be:

- Automatically discovered via `/help` command
- Displayed in slash command autocomplete (when user types `/`)
- Categorized under "Built-in Commands" in help output
- Accessible from both CLI and browser interfaces

### Execution Context

**Available Context for Commands:**

| Context Property        | Usage in /spec               | Usage in /plan                |
| ----------------------- | ---------------------------- | ----------------------------- |
| `context.cwd`           | Analyze project files        | Understand codebase structure |
| `context.git`           | Check current branch, status | Identify files for commits    |
| `context.config`        | Read project configuration   | Understand build tools        |
| `context.slashCommands` | Reference other commands     | N/A                           |
| `context.tools`         | Access read/glob/grep tools  | Access read/glob/grep tools   |

## User Interaction Flow

### /spec Command Flow

```mermaid
sequenceDiagram
    participant U as User
    participant C as /spec Command
    participant AI as AI Agent
    participant FS as File System

    U->>C: /spec [initial idea]
    C->>FS: Analyze project structure
    FS-->>C: Project context
    C->>AI: Generate first question
    AI->>U: Present question (MC or open-ended)
    U->>AI: Answer

    loop Until sufficient info gathered
        AI->>U: Next question
        U->>AI: Answer
    end

    AI->>U: Present design section 1
    U->>AI: Feedback or approval

    loop Until design complete
        AI->>U: Present next section
        U->>AI: Feedback or approval
    end

    U->>AI: Final approval
```

### /plan Command Flow

```mermaid
sequenceDiagram
    participant U as User
    participant C as /plan Command
    participant AI as AI Agent
    participant FS as File System

    U->>C: /plan [feature description]
    C->>FS: Analyze codebase
    FS-->>C: File structure, patterns
    C->>AI: Generate implementation plan
    AI->>AI: Break into tasks
    AI->>AI: Add test guidance
    AI->>FS: Write to docs/plans/[feature].md
    FS-->>AI: File written
    AI->>U: Plan location and summary
```

## File Structure

### New Files to Create

| File Path                            | Purpose                      |
| ------------------------------------ | ---------------------------- |
| `src/slash-commands/builtin/spec.ts` | /spec command implementation |
| `src/slash-commands/builtin/plan.ts` | /plan command implementation |

### Files to Modify

| File Path                             | Modification                     |
| ------------------------------------- | -------------------------------- |
| `src/slash-commands/builtin/index.ts` | Import and register new commands |

## Implementation Details

### /spec Command Structure

**Command Factory Function:**

The command is created via a factory function that accepts options for customization.

**Function Signature:**

- Function name: `createSpecCommand`
- Parameters: none required (may accept options in future for extensibility)
- Returns: `PromptCommand` object

**Prompt Generation:**

The `getPromptForCommand` method receives optional initial idea as arguments and returns a message array with:

- Role: `user`
- Content: Comprehensive prompt with instructions for the AI

**Key Prompt Elements:**

1. Initial context gathering directive
2. Questioning strategy guidelines
3. Design presentation format instructions
4. Section-by-section approval workflow
5. Constraints on staying at design level (no code)

### /plan Command Structure

**Command Factory Function:**

The command is created via a factory function similar to `/spec`.

**Function Signature:**

- Function name: `createPlanCommand`
- Parameters: none required
- Returns: `PromptCommand` object

**Prompt Generation:**

The `getPromptForCommand` method receives feature description as arguments and returns a message array.

**Key Prompt Elements:**

1. Audience and assumption declarations
2. Task granularity guidelines
3. Documentation standards for each task
4. Development principles to follow
5. Test design instructions with examples
6. Output structure template
7. File writing directive for docs/plans/

## Command Registration

### Registration Location

Both commands are registered in `src/slash-commands/builtin/index.ts` within the `createBuiltinCommands` function.

### Registration Pattern

Commands are added to the returned array of slash commands. The registration order determines the display order in help output.

**Recommended Position:**
Place after `/review` command and before `/terminal-setup` command to group planning-related commands together.

### Dependency Injection

Neither command requires special options from the context, but follow the existing pattern of factory functions for consistency and future extensibility.

## Testing Approach

### Unit Testing

**Test Categories:**

| Test Type         | Coverage                                            |
| ----------------- | --------------------------------------------------- |
| Command Structure | Verify command properties (name, type, description) |
| Prompt Generation | Validate prompt content and structure               |
| Argument Handling | Test with various input arguments                   |

**Test File Location:**

- `src/slash-commands/builtin/spec.test.ts`
- `src/slash-commands/builtin/plan.test.ts`

### Integration Testing

**Validation Points:**

1. **Command Registration**

   - Verify commands appear in `/help` output
   - Confirm commands are autocomplete-enabled
   - Check commands execute without errors

2. **Context Access**

   - Verify access to file system tools
   - Confirm git context availability
   - Validate config access

3. **User Interaction**
   - Test multi-turn conversation flow for `/spec`
   - Verify file writing for `/plan`
   - Confirm progress messages display correctly

### Manual Testing Checklist

| Scenario          | Steps                                     | Expected Outcome                             |
| ----------------- | ----------------------------------------- | -------------------------------------------- |
| Basic spec flow   | Type `/spec I want to add authentication` | AI asks first question about the idea        |
| Spec with context | Run `/spec` in existing project           | AI references project structure in questions |
| Plan generation   | Type `/plan Add user authentication`      | Plan file created in docs/plans/             |
| Plan validation   | Review generated plan file                | Contains tasks, files, tests, validation     |
| Help integration  | Run `/help`                               | Both commands listed under Built-in Commands |
| Autocomplete      | Type `/sp`                                | `/spec` appears in suggestions               |

## Error Handling

### Potential Failure Modes

| Scenario                         | Handling Strategy                                          |
| -------------------------------- | ---------------------------------------------------------- |
| Empty user input                 | Gracefully prompt for more information                     |
| File system access errors (plan) | Return error message to user with specific issue           |
| Invalid project structure        | Proceed with generic questions, mention context limitation |
| Plan file already exists         | Append timestamp or version number to filename             |
| Incomplete answers               | Ask follow-up clarifying questions                         |

### User Feedback

Both commands use the `progressMessage` property to inform users while the AI processes:

- `/spec`: "Analyzing your idea and preparing questions..."
- `/plan`: "Creating detailed implementation plan..."

## Documentation Requirements

### User-Facing Documentation

**Help Text Updates:**

The built-in help command will automatically discover and display the new commands with their descriptions.

**Usage Examples to Document:**

```
Example 1: Start a brainstorming session
/spec I want to add a search feature to the UI

Example 2: Generate an implementation plan
/plan Implement user authentication with JWT

Example 3: Spec with initial detail
/spec Add a /export command that saves chat history to markdown

Example 4: Plan from existing spec
/plan [paste design from /spec output]
```

### Developer Documentation

**Knowledge Base Updates Needed:**

| Document                         | Section         | Content                                             |
| -------------------------------- | --------------- | --------------------------------------------------- |
| Built-in Slash Commands          | Command List    | Add /spec and /plan entries                         |
| Custom Slash Command Development | Examples        | Reference /spec and /plan as PromptCommand examples |
| Contributing                     | Adding Commands | Mention the new commands as test cases              |

## Design Rationale

### Why PromptCommand Type?

Both commands use `PromptCommand` type because:

1. They leverage AI capabilities for dynamic conversation and generation
2. They don't require custom UI components (LocalJSXCommand)
3. They produce text-based output suitable for the standard chat interface
4. They benefit from the streaming response capability

### Why Separate Commands?

Rather than combining into one command with modes:

1. **Clearer User Intent**: Distinct commands make the purpose immediately obvious
2. **Simpler Implementation**: Each command has focused responsibility
3. **Better Discoverability**: Two entries in autocomplete provide more context
4. **Workflow Separation**: Users may want spec without plan, or plan from external spec

### Why No UI Components?

Neither command needs LocalJSXCommand treatment because:

1. Conversational flow works well in standard chat interface
2. No interactive selection or complex input required
3. Markdown output suffices for both commands
4. Keeps implementation simpler and more maintainable

## Success Criteria

### Definition of Done

The implementation is complete when:

1. **Functional Requirements Met:**

   - `/spec` command engages in multi-turn conversation
   - `/spec` produces structured design output
   - `/plan` command generates task-based implementation plans
   - `/plan` writes output to docs/plans/ directory
   - Both commands registered and discoverable

2. **Quality Requirements Met:**

   - Commands follow existing code patterns
   - Prompts produce high-quality, relevant output
   - Error handling covers common failure scenarios
   - Tests validate core functionality

3. **Documentation Complete:**
   - User examples provided
   - Developer knowledge base updated
   - Help text accurately describes commands

### Acceptance Validation

**User Acceptance Test:**

1. Run `/spec` with a vague idea → receives structured questions
2. Answer questions → receives section-by-section design
3. Run `/plan` with the design → receives detailed task breakdown
4. Execute tasks from plan → successfully implements feature

**Quality Metrics:**

- Commands execute without errors in both CLI and browser
- `/spec` conversation completes within 5-10 exchanges
- `/plan` generates actionable tasks (validated by manual review)
- Integration with existing command system has no regressions