gh-webdevtodayjason-titanium-plugins-plugins-titanium-toolkit/commands/titanium-plan.md

---
description: Analyze requirements and create detailed implementation plan
---

# Titanium Plan Command

You are creating a structured implementation plan from requirements. Follow this systematic process to break down work into actionable tasks with agent assignments.

**MCP Tools Used**: This command uses the `tt` MCP server (Titanium Toolkit) which provides:
- `mcp__plugin_titanium-toolkit_tt__plan_parser` - Generates structured implementation plans from requirements

The `tt` server wraps Python utilities that use Claude AI to analyze requirements and create detailed project plans with task-to-agent assignments.

**Agent Assignment**: The plan_parser automatically assigns tasks to appropriate specialized agents based on task type (API work → @api-developer, UI work → @frontend-developer, etc.). These assignments are used by `/titanium:work` to delegate implementation.

## Process Overview

This command will:
1. Gather and validate requirements
2. Use Claude (via `plan_parser` MCP tool) to generate structured plan
3. Validate plan with vibe-check
4. Create human-readable documentation
5. Store plan in Pieces for future reference

## Step 1: Gather Requirements

**If user provides a file path:**
```bash
# User might say: /titanium:plan ~/bmad/output/user-auth-prd.md
```
- Use Read tool to read the file
- Extract requirements text

**If user provides inline description:**
```bash
# User might say: /titanium:plan
# Then describe: "I need to add JWT authentication with login, register, password reset"
```
- Write description to `.titanium/requirements.md` using Write tool
- Ask clarifying questions if needed:
  - What tech stack? (Node.js, Python, Ruby, etc.)
  - What database? (PostgreSQL, MongoDB, etc.)
  - Any specific libraries or frameworks?
  - Security requirements?
  - Performance requirements?

## Step 2: Generate Structured Plan

Use the `plan_parser` MCP tool to generate the plan:

```
mcp__plugin_titanium-toolkit_tt__plan_parser(
  requirements_file: ".titanium/requirements.md",
  project_path: "$(pwd)"
)
```

This will:
- Call Claude with the requirements
- Generate structured JSON plan with:
  - Epics (major features)
  - Stories (user-facing functionality)
  - Tasks (implementation steps)
  - Agent assignments
  - Time estimates
  - Task dependencies
- Save to `.titanium/plan.json`
- Return the JSON plan directly to Claude

**Important**: The plan_parser tool needs ANTHROPIC_API_KEY environment variable. If it fails with an API key error, inform the user they need to add it to ~/.env

## Step 3: Review the Generated Plan

Read and analyze `.titanium/plan.json`:

```bash
# Read the plan
Read .titanium/plan.json
```

Check that the plan:
- Has reasonable epics (1-5 major features)
- Each epic has logical stories (1-5 per epic)
- Each story has actionable tasks (2-10 per story)
- Agent assignments are appropriate
- Time estimates seem realistic
- Dependencies make sense

**Common issues to watch for:**
- Tasks assigned to wrong agents (e.g., frontend work to @api-developer)
- Missing testing tasks
- Missing documentation tasks
- Unrealistic time estimates
- Circular dependencies

If the plan needs adjustments:
- Edit `.titanium/requirements.md` to add clarifications
- Re-run the `plan_parser` tool
- Review again

## Step 4: Validate Plan with vibe-check

Use vibe-check to validate the plan quality:

```
mcp__vibe-check__vibe_check(
  goal: "User's stated goal from requirements",
  plan: "Summary of the generated plan - list epics, key stories, agents involved, total time",
  uncertainties: [
    "List any concerns about complexity",
    "Note any ambiguous requirements",
    "Mention any technical risks"
  ]
)
```

**Example**:
```
mcp__vibe-check__vibe_check(
  goal: "Implement JWT authentication system with login, register, and password reset",
  plan: "2 epics: Backend API (JWT middleware, 3 endpoints, database) and Frontend UI (login/register forms, password reset flow). Agents: @product-manager, @api-developer, @frontend-developer, @test-runner, @security-scanner. Total: 4 hours",
  uncertainties: [
    "Should we use refresh tokens or just access tokens?",
    "Password hashing algorithm not specified - suggest argon2",
    "Rate limiting strategy needs clarification"
  ]
)
```

**Handle vibe-check response:**
- If vibe-check raises **concerns**:
  - Review the concerns carefully
  - Update requirements or plan approach
  - Re-run the `plan_parser` tool with adjustments
  - Validate again with vibe-check
- If vibe-check **approves**:
  - Continue to next step

## Step 5: Create Human-Readable Plan

Write a markdown version of the plan to `.titanium/plan.md`:

```markdown
# Implementation Plan: [Project Goal]

**Created**: [Date]
**Estimated Time**: [Total time from plan.json]

## Goal
[User's goal statement]

## Tech Stack
[List technologies mentioned in requirements]

## Epics

### Epic 1: [Epic Name]
**Description**: [Epic description]
**Estimated Time**: [Sum of all story times]

#### Story 1.1: [Story Name]
**Description**: [Story description]
**Tasks**:
1. [Task 1 name] - [@agent-name] - [time estimate]
2. [Task 2 name] - [@agent-name] - [time estimate]

#### Story 1.2: [Story Name]
**Description**: [Story description]
**Tasks**:
1. [Task 1 name] - [@agent-name] - [time estimate]
2. [Task 2 name] - [@agent-name] - [time estimate]

### Epic 2: [Epic Name]
[... repeat structure ...]

## Agents Involved
- **@product-manager**: Requirements validation
- **@api-developer**: Backend implementation
- **@frontend-developer**: UI development
- **@test-runner**: Testing
- **@doc-writer**: Documentation

## Dependencies
[List any major dependencies between epics/stories]

## Next Steps
Ready to execute? Run: `/titanium:work`
```

## Step 6: Store Plan in Pieces

Store the plan in Pieces LTM for future reference:

```
mcp__Pieces__create_pieces_memory(
  summary_description: "Implementation plan for [project name/goal]",
  summary: "Plan created with [X] epics, [Y] stories, [Z] tasks. Agents: [list agents]. Estimated time: [total time]. Key features: [brief list of main epics]. vibe-check validation: [summary of validation results]",
  files: [
    ".titanium/plan.json",
    ".titanium/plan.md",
    ".titanium/requirements.md"
  ],
  project: "$(pwd)"
)
```

**Example**:
```
mcp__Pieces__create_pieces_memory(
  summary_description: "Implementation plan for JWT authentication system",
  summary: "Plan created with 2 epics, 5 stories, 12 tasks. Agents: @product-manager, @api-developer, @frontend-developer, @test-runner, @security-scanner. Estimated time: 4 hours. Key features: JWT middleware with refresh tokens, login/register/reset endpoints, frontend auth forms, comprehensive testing. vibe-check validation: Plan structure is sound, recommended argon2 for password hashing, suggested rate limiting on auth endpoints.",
  files: [
    ".titanium/plan.json",
    ".titanium/plan.md",
    ".titanium/requirements.md"
  ],
  project: "/Users/username/projects/my-app"
)
```

## Step 7: Present Plan to User

Format the output in a clear, organized way:

```
📋 Implementation Plan Created

🎯 Goal: [User's goal]

📦 Structure:
- [X] epics
- [Y] stories
- [Z] implementation tasks

⏱️  Estimated Time: [total time]

🤖 Agents Involved:
- @agent-name (role description)
- @agent-name (role description)
- [... list all agents ...]

📁 Plan saved to:
- .titanium/plan.json (structured data)
- .titanium/plan.md (readable format)

✅ vibe-check validated: [Brief summary of validation results]

📝 Key Epics:
1. [Epic 1 name] - [time estimate]
2. [Epic 2 name] - [time estimate]
[... list all epics ...]

---

Ready to execute this plan?

Run: /titanium:work

This will orchestrate the implementation using the plan,
with voice announcements and quality gates throughout.
```

## Important Guidelines

**Always:**
- ✅ Use the `plan_parser` MCP tool (don't try to generate plans manually)
- ✅ Validate with vibe-check before finalizing
- ✅ Store the plan in Pieces
- ✅ Create both JSON (for machines) and Markdown (for humans)
- ✅ Get user approval before they proceed to /titanium:work
- ✅ Be specific about agent roles in the summary

**Never:**
- ❌ Skip vibe-check validation
- ❌ Generate plans without using the `plan_parser` tool
- ❌ Proceed to implementation without user approval
- ❌ Ignore vibe-check concerns
- ❌ Create plans without clear task assignments

## Error Handling

**If ANTHROPIC_API_KEY is missing:**
```
Error: The plan_parser tool needs an Anthropic API key to generate plans.

Please add your API key to ~/.env:
  echo 'ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.env
  chmod 600 ~/.env

Then restart Claude Code and try again.
```

**If vibe-check is not available:**
```
Warning: vibe-check MCP is not available. Proceeding without quality validation.

Consider setting up vibe-check for AI-powered quality gates:
  1. Create ~/.vibe-check/.env
  2. Add at least one API key (GEMINI_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY)
  3. Restart Claude Code
```

**If requirements are unclear:**
```
The requirements need more detail. Let me ask some questions:

1. [Specific question about tech stack]
2. [Specific question about features]
3. [Specific question about constraints]

Once I have this information, I'll create a detailed plan.
```

**If plan generation fails:**
```
The plan generation failed. This could be due to:
- Invalid requirements format
- API rate limits
- Network issues

Let me try again with simplified requirements.
[Retry with more basic prompt]
```

## Example Usage

**Example 1: With BMAD PRD file**
```
User: /titanium:plan ~/bmad/output/user-auth-prd.md

Claude:
- Reads PRD file
- Calls plan_parser tool
- Reviews generated plan
- Validates with vibe-check
- Creates plan.md
- Stores in Pieces
- Presents formatted summary to user
```

**Example 2: With inline description**
```
User: /titanium:plan

Claude: "What would you like to implement?"

User: "Add a search feature to filter products by name and category"

Claude:
- Writes description to .titanium/requirements.md
- Asks: "What's your tech stack?"
User: "React frontend, Node.js backend with PostgreSQL"
- Calls plan_parser tool with complete requirements
- Generates plan with appropriate tech stack
- Validates with vibe-check
- Presents plan to user
```

**Example 3: Complex feature with multiple clarifications**
```
User: /titanium:plan "Build a payment processing system"

Claude: "I need more details:
1. Which payment provider? (Stripe, PayPal, etc.)
2. What types of payments? (One-time, subscriptions, both?)
3. Currency support? (Single, multiple?)
4. Security requirements? (PCI compliance needed?)
5. Refund handling?"

User: "Stripe, one-time payments only, USD, yes PCI compliance, yes refunds"

Claude:
- Writes complete requirements
- Generates comprehensive plan
- vibe-check raises concern about PCI compliance complexity
- Adjusts plan to include @security-scanner more heavily
- Re-validates with vibe-check
- Presents approved plan
```

## Voice Feedback

The voice hooks will automatically announce:
- "Starting plan generation" (when script is called)
- "Plan created with [X] epics" (when complete)
- "vibe-check validation complete" (after validation)

No additional voice calls needed - the hooks handle this automatically.

## Next Command

After creating the plan, the user should run:
```
/titanium:work
```

This will execute the plan with orchestrated agent coordination.