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

description

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

# Get current working directory
pwd

Use this as the project_path for all subsequent operations.

1.2 Check for Existing Plan

# 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

uv run ${CLAUDE_PLUGIN_ROOT}/hooks/utils/workflow/workflow_state.py init "$(pwd)" "development" "User's stated goal"

Example:

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:

# 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:

# 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:

# 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

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

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:

   # 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

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

# 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:

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

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:

# 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

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.