--- description: Execute a multi-phase development workflow with agent orchestration --- # Titanium Work Command You are orchestrating a complete development workflow. This command coordinates multiple specialized subagents, manages state transitions, validates quality at each step, and stores progress in Pieces LTM. **Orchestration Model**: You delegate implementation tasks to specialized development agents (api-developer, frontend-developer, devops-engineer, etc.) who each have deep domain knowledge via skills. Each agent works in a separate context window with access to relevant expertise. **Agents & Their Skills**: - @api-developer: api-best-practices, testing-strategy, security-checklist - @frontend-developer: frontend-patterns, testing-strategy, technical-writing - @devops-engineer: devops-patterns, security-checklist - @code-reviewer: code-quality-standards, security-checklist, testing-strategy - @security-scanner: security-checklist, code-quality-standards - @tdd-specialist: testing-strategy, code-quality-standards - @test-runner: testing-strategy, debugging-methodology - @debugger: debugging-methodology, testing-strategy **MCP Tools Used**: This command uses the `tt` MCP server for plan generation: - `mcp__plugin_titanium-toolkit_tt__plan_parser` - Requirements → Implementation plan ## Overview This workflow has 5 phases: 1. **Pre-Flight**: Validate setup and check for existing plan 2. **Planning**: Create plan if needed (or use existing) 3. **Implementation**: Execute tasks sequentially with specialized agents 4. **Review**: Quality check with parallel review agents 5. **Completion**: Finalize and summarize Voice hooks will announce progress automatically throughout. --- ## Phase 1: Pre-Flight Checks ### 1.1 Determine Project Path ```bash # Get current working directory pwd ``` Use this as the project_path for all subsequent operations. ### 1.2 Check for Existing Plan ```bash # Check if plan exists ls .titanium/plan.json ``` **If plan.json exists**: - Read it with Read tool - Ask user: "I found an existing plan. Would you like to use it or create a new one?" - If user says use existing → Skip to Phase 3 (Implementation) - If user says create new → Continue to Phase 2 (Planning) **If plan.json does NOT exist**: - Ask user: "No plan found. Would you like to: 1. Create a plan now (I'll ask what to implement) 2. Cancel and run /titanium:plan first (recommended for complex projects) If you have project documentation or backlog, I recommend running /titanium:plan first to review and break down the work." - If user chooses option 1 → Continue to Phase 2 (Planning) - If user chooses option 2 → Exit and suggest running /titanium:plan ### 1.3 Initialize Workflow State ```bash uv run ${CLAUDE_PLUGIN_ROOT}/hooks/utils/workflow/workflow_state.py init "$(pwd)" "development" "User's stated goal" ``` **Example**: ```bash uv run ${CLAUDE_PLUGIN_ROOT}/hooks/utils/workflow/workflow_state.py init "$(pwd)" "development" "Implement user authentication system" ``` This creates `.titanium/workflow-state.json` to track progress. --- ## Phase 2: Planning (Skip if plan exists) ### 2.1 Gather Requirements **If user provided file path**: ```bash # User might have run: /titanium:work ~/bmad/output/prd.md ``` - Use Read tool to read the file - Copy content to `.titanium/requirements.md` **If user provided inline description**: ```bash # User might say: "I need to add search functionality" ``` - Write description to `.titanium/requirements.md` - Ask clarifying questions if needed **If user provided nothing**: - Ask: "What would you like to implement?" - Wait for response - Write to `.titanium/requirements.md` ### 2.2 Generate Plan Use the plan_parser MCP tool: ``` mcp__plugin_titanium-toolkit_tt__plan_parser( requirements_file: ".titanium/requirements.md", project_path: "$(pwd)" ) ``` This creates `.titanium/plan.json` with structured plan. ### 2.3 Review Plan Read and display the plan: ```bash # Read the generated plan Read .titanium/plan.json ``` Present summary to user: ``` 📋 Plan Generated 🎯 Goal: [goal from requirements] 📦 Structure: - [X] epics - [Y] stories - [Z] tasks ⏱️ Estimated Time: [total time] 🤖 Agents: [list of agents] Key Epics: 1. [Epic 1] - [time] 2. [Epic 2] - [time] ``` ### 2.4 Validate with vibe-check ``` mcp__vibe-check__vibe_check( goal: "User's stated goal", plan: "Summary: [X] epics, [Y] stories, [Z] tasks. Agents: [list]. Key work: [main epics]", uncertainties: [ "List any concerns about complexity", "Note any unclear requirements", "Mention any technical risks" ] ) ``` **Handle Response**: - If vibe-check raises **concerns**: - Present concerns to user - Ask: "Should we adjust the plan or proceed?" - If adjust → Go back to 2.1, refine requirements - If proceed → Continue - If vibe-check **approves**: - Continue to next step ### 2.5 Create TodoWrite List Read `.titanium/plan.json` and create comprehensive todo list: **Format**: For each task in the plan, create todo: ``` "[Epic]: [Story] - [Task] (Agent: @agent-name)" ``` **Example**: ``` [ {"content": "User Auth: Requirements - Validate requirements (Agent: @product-manager)", "status": "pending"}, {"content": "User Auth: Backend API - Create JWT middleware (Agent: @api-developer)", "status": "pending"}, {"content": "User Auth: Backend API - Create login endpoint (Agent: @api-developer)", "status": "pending"}, {"content": "User Auth: Frontend - Create login form (Agent: @frontend-developer)", "status": "pending"}, {"content": "User Auth: Testing - Write integration tests (Agent: @test-runner)", "status": "pending"} ] ``` Use TodoWrite tool to create this list. ### 2.6 Update State ```bash uv run ${CLAUDE_PLUGIN_ROOT}/hooks/utils/workflow/workflow_state.py update_phase "$(pwd)" "planning" "completed" ``` ### 2.7 Store Plan in Pieces ``` mcp__Pieces__create_pieces_memory( summary_description: "Implementation plan for [project goal]", summary: "Plan created with [X] epics, [Y] stories, [Z] tasks. Agents: [list]. Estimated time: [total]. Key work: [describe main epics and key technical decisions]", files: [ ".titanium/plan.json", ".titanium/plan.md", ".titanium/requirements.md" ], project: "$(pwd)" ) ``` ### 2.8 Get User Approval **IMPORTANT**: Do NOT proceed to implementation without explicit user approval. Ask user: ``` Plan is ready. The workflow will now: 1. Execute [Z] tasks sequentially 2. Use [N] different agents 3. Take approximately [time] 4. Run quality checks after each phase Proceed with implementation? (yes/no) ``` Wait for user confirmation before continuing. --- ## Phase 3: Implementation ### 3.1 Update State ```bash uv run ${CLAUDE_PLUGIN_ROOT}/hooks/utils/workflow/workflow_state.py update_phase "$(pwd)" "implementation" "in_progress" ``` ### 3.2 Execute Tasks Sequentially **IMPORTANT**: Execute ONE task at a time, in order from your TodoWrite list. **For EACH task**: #### Step A: Mark Task as in_progress Update TodoWrite to mark current task as "in_progress". #### Step B: Parse Task Info From the task string, extract: - Epic name - Story name - Task name - Agent name (the @agent-name part) #### Step C: Launch Agent Use Task tool to launch the appropriate agent: ``` Task( description: "[Task name]", prompt: "You are working on: [Epic] > [Story] > [Task] Requirements context: [Relevant requirements from .titanium/requirements.md] Previous work: [If this task has dependencies, summarize what was done] Task details: [Specific instructions for this task] Success criteria: - [What needs to be completed] - [What files should be created/modified] - [What tests should pass] After completion: - Run any relevant tests - Verify the work meets requirements - Report what was accomplished", subagent_type: "[agent-type without @]" ) ``` **Example**: ``` Task( description: "Create JWT middleware", prompt: "You are working on: User Authentication > Backend API > Create JWT middleware Requirements context: - Need JWT-based authentication - Should support refresh tokens - Use argon2 for password hashing - Rate limiting required Task details: Create Express middleware for JWT authentication that: - Verifies JWT tokens from Authorization header - Handles token expiration - Returns 401 for invalid/expired tokens - Attaches user info to req.user Files to create: - src/middleware/auth.ts Success criteria: - Middleware function exported - Handles all error cases - Tests pass After completion, report what files were created and what the middleware does.", subagent_type: "api-developer" ) ``` #### Step D: Wait for Agent Completion The agent will execute the work. Voice hooks will automatically announce completion. #### Step E: Quality Check After agent completes: 1. **Run tests if applicable**: ```bash # If package.json has test script npm test # Or pytest for Python pytest # Or appropriate test command ``` 2. **Use vibe-check to validate progress**: ``` mcp__vibe-check__vibe_check( goal: "Overall project goal", plan: "Current epic and story context", progress: "Just completed: [task name]. Agent: [agent]. Result: [brief summary of what was done]", uncertainties: [ "Note any issues encountered", "List any deviations from plan", "Mention any new concerns" ] ) ``` 3. **Handle vibe-check response**: - If concerns raised → Present to user, decide whether to proceed or fix - If approved → Continue #### Step F: Mark Task Completed **IMMEDIATELY** update TodoWrite to mark current task as "completed". Do NOT batch updates. Mark completed right after finishing. #### Step G: Check for Epic Completion If you just completed the last task of an epic: 1. **Store Epic Milestone in Pieces**: ``` mcp__Pieces__create_pieces_memory( summary_description: "Completed Epic: [epic name]", summary: "Finished [epic name] with [N] stories and [M] tasks. Agents used: [list]. Key accomplishments: [what was built]. Files created/modified: [list key files]. Tests: [test results]. Time taken: [if known]", files: [ "list all files created or modified in this epic" ], project: "$(pwd)" ) ``` #### Step H: Continue to Next Task Move to next task in TodoWrite list. Repeat steps A-G. ### 3.3 After All Tasks Complete Once all implementation tasks are done, proceed to Phase 3.5 (CodeRabbit Analysis - if available) or Phase 4 (Review). --- ## Phase 3.5: CodeRabbit Analysis (Optional) **This phase is optional** - only runs if CodeRabbit CLI is installed. ### 3.5.1 Check for CodeRabbit CLI ```bash command -v coderabbit >/dev/null 2>&1 || echo "CodeRabbit not installed" ``` **If CodeRabbit NOT found**: - Skip to Phase 4 (3-Agent Review) - Workflow continues normally **If CodeRabbit found**: - Continue to 3.5.2 ### 3.5.2 Offer CodeRabbit Analysis ``` 🤖 CodeRabbit CLI Detected Run CodeRabbit analysis before review? CodeRabbit catches: - Race conditions in concurrent code - Memory leaks and resource leaks - Security vulnerabilities - Logic errors and edge cases - Performance issues Duration: 7-30 minutes (runs in background) Cost: Uses your CodeRabbit account (free or paid tier) Run CodeRabbit? (yes/no) ``` **If no**: Skip to Phase 4 (3-Agent Review) **If yes**: Continue ### 3.5.3 Run CodeRabbit in Background ```bash # Run with --prompt-only for AI-optimized output coderabbit --prompt-only --type uncommitted ``` Use Bash tool with `run_in_background: true` Show user: ``` 🤖 CodeRabbit Analyzing... Running in background (7-30 minutes typical). I'll check progress periodically. You can ask "Is CodeRabbit done?" anytime. ``` ### 3.5.4 Wait for Completion Check periodically (every 2-3 minutes) using BashOutput tool. Show progress updates: ``` CodeRabbit analyzing... (5 minutes elapsed) CodeRabbit analyzing... (10 minutes elapsed) CodeRabbit analyzing... (15 minutes elapsed) ``` When complete: ``` ✅ CodeRabbit analysis complete! ([X] minutes) ``` ### 3.5.5 Parse and Present Findings Read CodeRabbit --prompt-only output. Present summary: ``` 🤖 CodeRabbit Findings 📊 Issues Detected: - 🔴 Critical: [X] - 🟠 High: [Y] - 🟡 Medium: [Z] - 🟢 Low: [W] Critical Issues: 1. Race condition in src/auth.ts:45 - Shared state access without synchronization - Fix: Add mutex or use atomic operations 2. Memory leak in src/websocket.ts:123 - Event listener not removed on disconnect - Fix: Add cleanup in disconnect handler High Priority Issues: 1. SQL injection in src/api/users.ts:67 - User input in raw SQL query - Fix: Use parameterized queries [List all critical and high issues] Would you like me to fix these? 1. Fix critical and high (recommended) 2. Fix critical only 3. Skip fixes, just document 4. Cancel ``` ### 3.5.6 Apply Fixes (if requested) **For each critical/high issue**: 1. Locate the problematic code (file:line from CodeRabbit) 2. Read CodeRabbit's suggested fix 3. Implement the fix 4. Run relevant tests 5. Mark as fixed in TodoWrite Show progress: ``` Applying CodeRabbit fixes... ✅ Fixed: Race condition in auth.ts - Added mutex for shared state access - Tests passing ✅ Fixed: Memory leak in websocket.ts - Added event listener cleanup - Verified no leaks ✅ Fixed: SQL injection in users.ts - Converted to parameterized query - Tests passing ⏳ Fixing: Error handling in api.ts... ``` ### 3.5.7 Optional Verification After fixes applied: ``` CodeRabbit fixes complete! Fixed: [X] critical, [Y] high priority issues Re-run CodeRabbit to verify? (yes/no) ``` **If yes**: ```bash coderabbit --prompt-only --type uncommitted ``` Check that: - No new critical issues introduced - Fixes resolved the original issues - No regression Show result: ``` ✅ Verification complete! Original issues: Resolved New issues: None Safe to proceed. ``` **If no**: Skip verification ### 3.5.8 Store CodeRabbit Findings ``` mcp__Pieces__create_pieces_memory( summary_description: "CodeRabbit analysis for [files]", summary: "CodeRabbit CLI analysis complete. Found: [X] critical, [Y] high, [Z] medium, [W] low issues. Critical issues: [list each]. High issues: [list each]. Fixes applied: [summary of fixes]. Duration: [X] minutes. Verified: [yes/no]. Ready for 3-agent review validation.", files: [ "list all reviewed and fixed files" ], project: "$(pwd)" ) ``` ### 3.5.9 Proceed to 3-Agent Review ``` CodeRabbit phase complete! Proceeding to 3-agent review for validation... ``` Continue to Phase 4 (Review). **Note**: 3-agent review will validate CodeRabbit fixes and catch anything CodeRabbit missed. --- ## Phase 4: Review ### 4.1 Update State ```bash uv run ${CLAUDE_PLUGIN_ROOT}/hooks/utils/workflow/workflow_state.py update_phase "$(pwd)" "review" "in_progress" ``` ### 4.2 Launch Review Agents in Parallel **IMPORTANT**: Launch all three agents in a SINGLE message using multiple Task calls. This enables them to run concurrently: ``` [Task 1]: @code-reviewer Prompt: "Review all code changes for quality, readability, and best practices. Focus on: - Code quality and maintainability - DRY principles - SOLID principles - Error handling - Code organization - Comments and documentation Files to review: [list all modified files] Provide findings categorized by severity: - Critical: Must fix before deployment - Important: Should fix soon - Nice-to-have: Optional improvements For each finding, specify: - File and line number - Issue description - Recommendation" [Task 2]: @security-scanner Prompt: "Scan for security vulnerabilities and security best practices. Focus on: - Input validation - SQL injection risks - XSS vulnerabilities - Authentication/authorization issues - Secrets in code - Dependency vulnerabilities - HTTPS enforcement - Rate limiting Files to review: [list all modified files] Provide findings with: - Severity (Critical/High/Medium/Low) - Vulnerability type - File and line number - Risk description - Remediation steps" [Task 3]: @tdd-specialist Prompt: "Check test coverage and test quality. Focus on: - Test coverage percentage - Edge cases covered - Integration tests - Unit tests - E2E tests (if applicable) - Test quality and assertions - Mock usage - Test organization Files to review: [list all test files and source files] Provide findings on: - Coverage gaps - Missing test cases - Test quality issues - Recommendations for improvement" ``` ### 4.3 Wait for All Agents Wait for all three review agents to complete (they run in parallel). ### 4.4 Aggregate Findings Collect and organize all findings: **Categories**: - 🔴 **Critical** (must fix) - 🟡 **Important** (should fix) - 🟢 **Nice-to-have** (optional) **For each finding**: - Source: Which agent found it - File: file.path:line - Issue: Description - Fix: Recommendation ### 4.5 Meta-Review with vibe-check ``` mcp__vibe-check__vibe_check( goal: "Original project goal", plan: "What was implemented", progress: "Implementation complete. Review findings: [X] critical, [Y] important, [Z] minor issues. Details: [summarize key findings]", uncertainties: [ "Are there systemic issues we're missing?", "Is the implementation approach sound?", "Any architectural concerns?" ] ) ``` ### 4.6 Create Review Report Write `.titanium/review-report.md`: ```markdown # Quality Review Report **Date**: [current date] **Project**: [project goal] **Reviewers**: @code-reviewer, @security-scanner, @tdd-specialist ## Summary - 🔴 Critical issues: [X] - 🟡 Important issues: [Y] - 🟢 Nice-to-have: [Z] ## Critical Issues 🔴 ### [Issue 1 Title] **File**: `path/to/file.ts:line` **Source**: @security-scanner **Severity**: Critical **Description**: [What the issue is] **Risk**: [Why it's critical] **Recommendation**: [How to fix it] --- ### [Issue 2 Title] [... repeat structure ...] ## Important Issues 🟡 [... same structure ...] ## Nice-to-have 🟢 [... same structure ...] ## vibe-check Meta-Review [Summary from vibe-check about overall quality] ## Test Coverage **Overall Coverage**: [X]% **Files with <80% coverage**: [list] **Missing test cases**: [list] ## Recommendations 1. [Priority 1 recommendation] 2. [Priority 2 recommendation] 3. [Priority 3 recommendation] ``` ### 4.7 Store Review in Pieces ``` mcp__Pieces__create_pieces_memory( summary_description: "Quality review findings for [project]", summary: "Review complete: [X] critical, [Y] important, [Z] minor issues. Critical issues: [list them briefly]. Important issues: [list them]. Test coverage: [X]%. vibe-check assessment: [summary]. Overall quality: [assessment]", files: [ ".titanium/review-report.md", "list all reviewed files" ], project: "$(pwd)" ) ``` ### 4.8 Present Summary ``` 🔍 Quality Review Complete 🔴 [X] Critical Issues 🟡 [Y] Important Issues 🟢 [Z] Nice-to-have Improvements 📄 Full Report: .titanium/review-report.md ⚠️ Action Required: [List critical issues with file:line] 💡 Recommendations: 1. [Top recommendation] 2. [Second recommendation] Would you like me to fix the critical issues now? ``` **If user says yes**: - Address critical issues one by one - Re-run tests after each fix - Update review report **If user says no**: - Proceed to Phase 5 (Completion) --- ## Phase 5: Completion ### 5.1 Mark Workflow Complete ```bash uv run ${CLAUDE_PLUGIN_ROOT}/hooks/utils/workflow/workflow_state.py complete "$(pwd)" ``` ### 5.2 Create Final Session Memory ``` mcp__Pieces__create_pieces_memory( summary_description: "Completed: [project goal]", summary: "Full workflow summary: Goal: [original goal] What was built: [List main features/components] Epics completed: [X] Stories completed: [Y] Tasks completed: [Z] Time taken: [if known] Agents used: [List agents and their contributions] Quality review: - Critical issues: [X] ([status: fixed/pending]) - Important issues: [Y] - Test coverage: [X]% Files created/modified: [List key files] Key technical decisions: [List important decisions made during implementation] Next steps: [Suggest what should happen next]", files: [ "list ALL project files that were part of this workflow" ], project: "$(pwd)", externalLinks: [ "Any GitHub branches/PRs if created" ] ) ``` ### 5.3 Present Completion Summary ``` ✅ Workflow Complete! 🎯 Goal: [original goal] 📦 Delivered: - [X] epics - [Y] stories - [Z] tasks completed 🤖 Agents Used: - [Agent 1]: [what they did] - [Agent 2]: [what they did] [... list all agents ...] 📊 Quality: - Tests: [X]% coverage - Critical issues: [X] ([fixed/pending]) - Important issues: [Y] 📁 Key Files: - [file 1] - [file 2] [... list main files ...] 📝 Documentation: - Plan: .titanium/plan.md - Review: .titanium/review-report.md - State: .titanium/workflow-state.json 🎉 All work stored in Pieces for future reference! --- Next Steps: 1. [Suggestion 1] 2. [Suggestion 2] 3. Run /titanium:status anytime to check progress ``` --- ## Important Guidelines ### Always - ✅ Use TodoWrite to track every task - ✅ Execute tasks ONE at a time (sequential) - ✅ Mark tasks completed IMMEDIATELY after finishing - ✅ Use vibe-check after each task and epic - ✅ Store milestones in Pieces after each epic - ✅ Get user approval after planning phase - ✅ Launch review agents in parallel (single message, multiple Tasks) - ✅ Use workflow_state.py to track phases - ✅ Handle errors gracefully - inform user of issues ### Never - ❌ Skip vibe-check quality gates - ❌ Execute multiple implementation tasks in parallel - ❌ Batch todo updates - mark completed immediately - ❌ Proceed to implementation without user approval - ❌ Skip storing epic milestones in Pieces - ❌ Ignore vibe-check concerns - always present to user - ❌ Launch review agents sequentially - always parallel --- ## Error Handling ### If Agent Fails ``` Agent @[agent-name] encountered an error while [task]. Error: [error message] Options: 1. Retry the task 2. Skip and continue 3. Modify approach and retry What would you like to do? ``` ### If vibe-check Raises Concerns ``` ⚠️ vibe-check identified concerns: [List concerns from vibe-check] Recommendations: [List suggestions from vibe-check] Would you like to: 1. Address these concerns now 2. Proceed anyway (not recommended) 3. Adjust the approach ``` ### If Tests Fail ``` ❌ Tests failed after [task] Failed tests: [List failed tests] Error output: [Show errors] I can: 1. Analyze and fix the failing tests 2. Continue anyway (not recommended) 3. Roll back this change What would you like to do? ``` ### If Missing API Keys ``` Error: Required API key missing This workflow needs: - OPENAI_API_KEY (for plan generation) - ELEVENLABS_API_KEY (for voice announcements - optional but recommended) For vibe-check quality gates (recommended): - GEMINI_API_KEY or OPENAI_API_KEY in ~/.vibe-check/.env Please add the required keys to ~/.env and restart Claude Code. ``` --- ## Voice Feedback Voice hooks automatically announce: - "Starting [phase] phase" (at each phase transition) - "[Agent] completed [task]" (after each agent) - "[X] tasks remaining" (periodically) - "Quality review complete: [findings count]" (after review) - "Workflow complete" (at end) No additional voice calls needed - hooks handle this. --- ## Example Usage ### Example 1: With Existing Plan ``` User: /titanium:work Claude: - Checks for .titanium/plan.json - Found existing plan - "I found a plan with 3 epics, 8 stories. Use this plan?" User: "Yes" - Skips planning phase - Creates TodoWrite list from plan - Starts implementation - Executes tasks sequentially with agents - Voice announces progress throughout - Runs review at end - Presents completion summary ``` ### Example 2: Without Plan ``` User: /titanium:work "Add search functionality to products" Claude: - No plan found - Writes requirements to .titanium/requirements.md - Asks clarifying questions about tech stack User: "React frontend, Node backend, Elasticsearch" - Generates plan with plan_parser MCP tool - Validates with vibe-check - Presents plan - "Proceed with implementation?" User: "Yes" - Creates TodoWrite list - Executes implementation - [... continues through all phases ...] ``` ### Example 3: From BMAD PRD ``` User: /titanium:work ~/bmad/output/user-auth-prd.md Claude: - Reads PRD file - Generates plan from PRD - Validates with vibe-check - vibe-check: "Plan looks good, recommend adding rate limiting" - Adjusts plan to include rate limiting - Presents updated plan - "Proceed?" User: "Yes" - Executes full workflow - [... 4 hours of orchestrated work ...] - Review finds 1 security issue - Fixes security issue - "Workflow complete!" ``` --- ## Integration with Other Commands **After /titanium:work**: - Run `/titanium:status` to check final state - Run `/catchup` in next session to resume context - Run `/titanium:review` again if you make more changes **Before /titanium:work**: - Run `/titanium:plan` first if you want to review the plan separately - Or let /titanium:work create the plan inline --- **This command orchestrates the complete development workflow from requirements to reviewed implementation, with AI quality gates and voice feedback throughout.**