Titanium Toolkit - Getting Started Guide

Welcome to Titanium Toolkit! This guide explains the complete workflow from idea to implementation, including where documentation lives and what commands to use.

---

Complete Project Workflow

The Big Picture

Idea
  ↓
Project Documentation (backlog/)
  ↓
Implementation Plan (.titanium/)
  ↓
Code Implementation
  ↓
Quality Review
  ↓
Done!

Each phase has specific commands and folder structures.

---

Phase 1: Project Documentation (Coming Soon!)

Where Documentation Lives

Folder: backlog/ or bmad-backlog/ in your project root

your-project/
├── backlog/
│   ├── product-brief.md       # High-level vision
│   ├── prd.md                 # Product Requirements Document
│   ├── architecture.md        # Technical architecture
│   └── epics/
│       ├── epic-001.md        # Foundation Infrastructure
│       ├── epic-002.md        # User Management
│       └── ...
└── (source code will go here)

Future Commands (In Development)

These BMAD document generation commands are coming:

/bmad:brief - Generate project brief

/bmad:brief "AI-powered precious metals research platform"
# → Creates backlog/product-brief.md

/bmad:prd - Generate Product Requirements Document

/bmad:prd
# → Reads product-brief.md
# → Creates backlog/prd.md with complete requirements

/bmad:epic - Generate epic breakdown

/bmad:epic "Foundation Infrastructure"
# → Creates backlog/epics/epic-001.md
# → Breaks down into user stories

/bmad:architecture - Generate technical architecture

/bmad:architecture
# → Reads PRD
# → Creates backlog/architecture.md

Vision: /bmad:brief → /bmad:prd → /bmad:epic → /bmad:architecture → Complete backlog!

Status: These commands are planned for future release. For now, you can:

• Create backlog/ folder manually
• Write documentation yourself
• Or use external BMAD-METHOD tool: npx bmad-method

---

Phase 2: Implementation Planning

Current State: Planning Commands Available Now

Once you have requirements (from backlog/ or your head), create an implementation plan:

/titanium:plan - Create implementation plan

# From backlog documentation
/titanium:plan backlog/epics/epic-001.md

# From inline description
/titanium:plan "Implement user authentication with JWT"

# From BMAD PRD (if using external BMAD tool)
/titanium:plan ~/bmad/output/project-prd.md

What it creates:

.titanium/
├── requirements.md        # Your input requirements
├── plan.json              # Structured plan (for Claude)
└── plan.md                # Human-readable plan (for you)

What the plan includes:

• Epics (major features)
• Stories (user functionality)
• Tasks (implementation steps)
• Agent assignments (@api-developer, @frontend-developer, etc.)
• Time estimates
• Dependencies between tasks

Output example:

📋 Implementation Plan Created

🎯 Goal: Implement Foundation Infrastructure

📦 Structure:
- 1 epic
- 4 stories
- 12 tasks

⏱️  Estimated Time: 3 hours

🤖 Agents:
- @devops-engineer (infrastructure)
- @api-developer (backend setup)
- @doc-writer (documentation)

Ready to execute? Run: /titanium:work

---

Phase 3: Implementation

Execute Your Plan

/titanium:work - Orchestrate complete implementation

# If you already ran /titanium:plan
/titanium:work

# Or create plan + execute in one step
/titanium:work "Implement user authentication"

What happens:

Step 1: Planning (if no plan exists)

• Asks what to implement
• Generates plan with Claude
• Shows you the plan
• Waits for your approval

Step 2: Implementation

• Creates todo list from plan
• Launches agents sequentially:
  • @product-manager validates requirements
  • @api-developer builds backend
  • @frontend-developer builds UI
  • @test-runner ensures quality
• Voice announces each step
• vibe-check validates after each task
• Stores progress in Pieces

Step 3: Review

• Launches 3 review agents in parallel:
  • @code-reviewer (code quality)
  • @security-scanner (security)
  • @tdd-specialist (test coverage)
• Creates review report
• Shows findings with file:line references

Step 4: Completion

• Presents summary
• Stores everything in Pieces
• You're done!

Voice announcements throughout:

• "Starting implementation phase"
• "API endpoints created, 8 tests passing"
• "Review complete: 1 security issue found"
• "Workflow complete!"

---

Phase 4: Quality & Status

Check Progress Anytime

/titanium:status - See where you are

/titanium:status

Shows:

• Current phase (planning/implementation/review/completed)
• Progress: 67% (8/12 tasks)
• Current task
• Time remaining
• Recent work from Pieces
• Next steps

Use this:

• Mid-workflow to check progress
• After lunch to remember where you were
• Next day to resume work
• Before meetings to report status

Review Code Quality

/titanium:review - Run quality review

# Review recent changes
/titanium:review

# Review specific files
/titanium:review src/api/*.ts

# Review everything
/titanium:review --all

What it does:

• 3 agents review in parallel (fast!)
• Finds issues: Critical, Important, Nice-to-have
• Creates .titanium/review-report.md
• Shows actionable recommendations

Use this:

• After implementation
• Before committing
• Before pull requests
• Periodic code reviews

---

Common Workflows

Workflow 1: Brand New Project (No Documentation Yet)

You have: Just an idea Goal: Build the project

Steps:

# 1. Create project directory
mkdir my-new-project
cd my-new-project
git init

# 2. (Future) Generate documentation with BMAD commands
# /bmad:brief "AI todo app with voice input"
# /bmad:prd
# /bmad:epic "Core Features"
# → Creates backlog/ with all documentation

# 3. (For now) Plan directly from idea
/titanium:plan "Build AI todo app with voice input and smart scheduling"

# 4. Execute
/titanium:work

# 5. Review
/titanium:review

# Done! Your project is implemented with tests.

Timeline: Can go from idea to working code in one session!

---

Workflow 2: Existing Project with Backlog Documentation

You have: Project documentation in backlog/ or similar Goal: Implement next epic

Steps:

cd my-project

# 1. Plan from backlog
/titanium:plan backlog/epics/epic-003-user-profiles.md

# 2. Review the plan
# Claude shows: "3 stories, 8 tasks, 2 hours"

# 3. Approve and execute
/titanium:work

# 4. Review quality
/titanium:review

# Done!

Timeline: Each epic typically takes 2-6 hours depending on complexity.

---

Workflow 3: Quick Feature Addition

You have: Working project Goal: Add small feature quickly

Steps:

cd my-project

# One command - plan + execute
/titanium:work "Add search functionality to product catalog"

# Claude:
# - Creates quick plan (1 epic, 2 stories)
# - Shows you the plan
# - Asks approval
# - Implements
# - Reviews
# - Done!

# Timeline: 30 minutes to 1 hour

---

Workflow 4: Bug Fix

You have: Bug to fix Goal: Systematic fix with tests

Steps:

cd my-project

# Plan the fix
/titanium:plan "Fix: Login fails when email has uppercase letters"

# Execute
/titanium:work

# Claude:
# - @debugger reproduces bug
# - @api-developer fixes issue
# - @tdd-specialist adds test
# - Reviews fix
# - Done!

# Timeline: 15-30 minutes

---

Workflow 5: Resume After Interruption

You have: Incomplete workflow Goal: Continue where you left off

Steps:

# Next session, different day
cd my-project

# 1. Recover context
/catchup
# → Pieces: "You were implementing authentication. Backend complete..."

# 2. Check status
/titanium:status
# → Shows: "Phase: Implementation, 60% complete, Current: Register endpoint"

# 3. Continue work
/titanium:work
# → Resumes from current state
# → Completes remaining tasks
# → Done!

---

Folder Structure Reference

During Development

Your project will have these folders:

my-project/
├── backlog/                    # Project documentation (you create this)
│   ├── product-brief.md        # Vision and goals
│   ├── prd.md                  # Product requirements
│   ├── architecture.md         # Technical architecture
│   └── epics/
│       ├── epic-001.md         # Epic breakdowns
│       ├── epic-002.md
│       └── ...
│
├── .titanium/                  # Workflow state (created automatically)
│   ├── workflow-state.json     # Current workflow state
│   ├── plan.json               # Implementation plan
│   ├── plan.md                 # Readable plan
│   ├── requirements.md         # Input requirements
│   └── review-report.md        # Quality findings
│
├── src/                        # Your source code (created during /titanium:work)
│   ├── api/
│   ├── components/
│   └── ...
│
├── tests/                      # Your tests (created during /titanium:work)
│   └── ...
│
└── docs/                       # Technical docs (created during /titanium:work)
    └── ...

Folder Purposes

backlog/ (you create):

• High-level project documentation
• Product requirements
• Epic breakdowns
• Architecture decisions
• Lives forever - your project's source of truth

.titanium/ (created automatically):

• Workflow execution data
• Implementation plans
• Review reports
• Created per workflow - can be regenerated

src/, tests/, docs/ (created during implementation):

• Your actual code
• Created by agents during /titanium:work

---

The 6 Titanium Commands

1. /titanium:getting-started (This Guide)

Use when: Learning the system Shows: Complete workflow guide

2. /titanium:plan

Use when: Starting new work Creates: Implementation plan from requirements Input: File path or inline description

3. /titanium:work

Use when: Ready to implement Does: Complete orchestration from plan to tested code Can include: Inline planning if no plan exists

4. /titanium:review

Use when: Code review needed Does: 3-agent parallel quality review Output: Review report with findings

5. /titanium:status

Use when: Checking progress Shows: Current state, progress %, next steps Works: Across sessions

6. /catchup (Pieces Integration)

Use when: Resuming work in new session Shows: Context from previous sessions Requires: Pieces OS + CLI

---

Starting a Brand New Project

Option A: With BMAD Documentation (Future)

When BMAD commands are available:

# 1. Create project
mkdir my-new-app
cd my-new-app
git init

# 2. Generate documentation
/bmad:brief "Social media app for developers"
# → Creates backlog/product-brief.md

/bmad:prd
# → Creates backlog/prd.md

/bmad:epic "User Profiles"
/bmad:epic "Feed System"
/bmad:epic "Real-time Chat"
# → Creates backlog/epics/*.md

/bmad:architecture
# → Creates backlog/architecture.md

# 3. Implement first epic
/titanium:plan backlog/epics/epic-001.md
/titanium:work

# 4. Continue with more epics
/titanium:plan backlog/epics/epic-002.md
/titanium:work

# etc...

Option B: Without BMAD (Available Now)

If you don't have documentation yet:

# 1. Create project
mkdir my-new-app
cd my-new-app
git init

# 2. Create backlog folder manually
mkdir backlog

# 3. Write your PRD (can be simple)
cat > backlog/prd.md << 'EOF'
# My Todo App

## Vision
AI-powered todo app with voice input and smart scheduling.

## Core Features
- Voice input for tasks
- AI categorization
- Smart scheduling suggestions
- Calendar integration

## Tech Stack
- React + TypeScript frontend
- Node.js + Express backend
- PostgreSQL database
EOF

# 4. Plan implementation
/titanium:plan backlog/prd.md

# 5. Execute
/titanium:work

# Done! You have a working app.

Option C: Skip Documentation Entirely (Quick Projects)

For small projects or experiments:

# 1. Create project
mkdir quick-experiment
cd quick-experiment
git init

# 2. Just describe what you want
/titanium:work "Build a REST API for managing books with title, author, ISBN"

# Claude:
# - Creates plan inline
# - Implements
# - Tests
# - Done!

# Timeline: 30 minutes - 1 hour

---

Starting with Existing Project

If You Already Have Code

cd existing-project

# 1. Create backlog documentation (optional but recommended)
mkdir backlog
cat > backlog/next-features.md << 'EOF'
# Next Features

## User Authentication
- JWT-based auth
- Login/register
- Password reset
EOF

# 2. Plan from backlog
/titanium:plan backlog/next-features.md

# 3. Execute
/titanium:work

# Adds features to existing codebase

If You Have Backlog Documentation Already

cd my-project
# You have: backlog/epics/epic-003.md

# 1. Plan next epic
/titanium:plan backlog/epics/epic-003.md

# 2. Execute
/titanium:work

# Continues building on existing code

---

Daily Development Workflow

Morning

# 1. Resume context
/catchup
# → Pieces: "Yesterday you implemented authentication backend..."

# 2. Check status
/titanium:status
# → "Phase: Implementation, 60% complete, Current: Login form"

# 3. Continue work
/titanium:work
# → Resumes from current state

Midday

# Check progress
/titanium:status
# → "80% complete, 2 tasks remaining"

End of Day

# Final check
/titanium:status
# → "100% complete, ready for review"

/titanium:review
# → Quality review runs
# → "1 security issue found in auth.ts:45"

# Fix the issue
# Claude fixes it

# Commit
git add .
git commit -m "feat: Add user authentication"

# Session ends
# Voice: "I implemented user authentication with JWT, fixed one security issue, all tests passing"

Next Morning

# New session
/catchup
# → "Yesterday: Completed authentication. All tests passing. Ready for next epic."

/titanium:plan backlog/epics/epic-002.md
# → Plan next feature

---

Command Decision Tree

Starting a new project?

Do you have documentation?
├─ Yes (backlog/*.md exists)
│  └─ /titanium:plan backlog/epics/epic-001.md
│     └─ /titanium:work
│
└─ No (just an idea)
   ├─ Simple project?
   │  └─ /titanium:work "description"
   │
   └─ Complex project?
      ├─ (Future) /bmad:prd → /bmad:epic → /titanium:plan
      └─ (Now) Write backlog/*.md manually → /titanium:plan

Adding to existing project?

Do you have a plan?
├─ Yes (.titanium/plan.json exists)
│  └─ /titanium:work
│
└─ No
   └─ /titanium:plan "feature description"
      └─ /titanium:work

Need to review code?

/titanium:review

Lost track of progress?

/catchup        # Get context from Pieces
/titanium:status # See current state

---

Recommended Folder Structure

For Serious Projects

my-project/
├── backlog/                           # Documentation (manual or /bmad:*)
│   ├── product-brief.md              # Vision
│   ├── prd.md                        # Requirements
│   ├── architecture.md               # Technical decisions
│   └── epics/
│       ├── epic-001-foundation.md
│       ├── epic-002-auth.md
│       └── epic-003-profiles.md
│
├── .titanium/                        # Workflow state (auto-created)
│   ├── workflow-state.json
│   ├── plan.json
│   └── review-report.md
│
├── src/                               # Source code
├── tests/                             # Tests
├── docs/                              # Technical docs
├── .env.example                       # Example env vars
├── README.md                          # Project readme
└── package.json                       # Dependencies

For Quick Projects

quick-project/
├── .titanium/         # Auto-created by /titanium:plan or /titanium:work
├── src/               # Your code
└── tests/             # Your tests

No backlog/ needed for simple projects!

---

Best Practices

1. Start with Planning

Recommended:

/titanium:plan "feature description"
/titanium:work

Why: See the plan before execution, understand scope, get time estimates.

2. Review Before Committing

Recommended:

/titanium:review
# Fix any critical issues
git commit

Why: Catch issues early, maintain quality.

3. Use Backlog for Documentation

Create:

backlog/
├── prd.md
└── epics/
    └── *.md

Why: Organized documentation, easy to plan from, version controlled.

4. Check Status Regularly

During long workflows:

/titanium:status

Why: Stay informed, know what's next, track time.

5. Use /catchup Between Sessions

Every new session:

/catchup

Why: Never lose context, resume instantly.

---

What You Don't Need

❌ Don't need to create .titanium/ folder manually ❌ Don't need to write plan.json yourself ❌ Don't need to install Python packages (UV handles it) ❌ Don't need to manage agents manually ❌ Don't need to coordinate workflows yourself

Titanium does all of this for you!

---

Tips & Tricks

Tip 1: Keep Backlog Documentation Simple

Your backlog/prd.md can be very simple:

# Project: Todo App

## Goal
Personal todo app with AI assistance

## Features
- Add/edit/delete todos
- Voice input
- AI categorization
- Due date suggestions

## Tech Stack
- React frontend
- Node.js backend
- SQLite database

That's enough! /titanium:plan will break it down.

Tip 2: Iterate on Plans

/titanium:plan "Add authentication"
# Review the plan
# Not quite right?

# Create new plan
/titanium:plan "Add JWT authentication with refresh tokens and email verification"
# Better!

/titanium:work

Plans are cheap (~$0.01). Iterate until right.

Tip 3: Use Status During Long Workflows

/titanium:work "Complex feature"
# ... 2 hours pass ...
/titanium:status
# "67% complete, 2 hours remaining"

Know when to take breaks!

Tip 4: Store Backlog in Git

git add backlog/
git commit -m "docs: Add product backlog"

Version your documentation. See how it evolves.

Tip 5: Use Review Standalone

# Before committing
/titanium:review

# Fix issues
/titanium:review  # Run again to verify

Can use review without running full workflow.

---

Understanding Cost

Per workflow (~4 hour implementation):

• Plan generation (Claude): $0.01
• vibe-check gates (5x): $0.0005
• Voice announcements (10x): $0.09
• Total: ~$0.10

Very affordable! Less than a cup of coffee per feature.

Optional:

• Skip voice (use macOS say): Save $0.09
• Skip vibe-check: Save $0.0005 (but lose quality gates)

Minimum cost: $0.01 per workflow (Claude planning only)

---

When Things Go Wrong

"No plan found" when running /titanium:work

Solution: Run /titanium:plan first, or provide description inline:

/titanium:work "what to implement"

"OPENAI_API_KEY not found"

Solution: Add to ~/.env:

echo 'OPENAI_API_KEY=sk-your-key' >> ~/.env

Restart Claude Code.

"Workflow stuck at X%"

Solution: Check status:

/titanium:status

If truly stuck, restart workflow:

rm -rf .titanium/
/titanium:work "description"

"Review found critical issues"

Solution: Fix them!

# Claude can fix them for you
User: "Fix the SQL injection in users.ts:45"

# Or do manually, then review again
/titanium:review

---

Getting Help

Documentation

• This Guide: /titanium:getting-started (you are here!)
• Full Architecture: docs/ORCHESTRATION_PLAN.md
• Dependencies: docs/DEPENDENCIES.md

Verification

# Run verification script
curl -o verify.sh https://raw.githubusercontent.com/webdevtodayjason/titanium-plugins/main/verify-installation.sh
chmod +x verify.sh
./verify.sh

Support

• Issues: https://github.com/webdevtodayjason/titanium-plugins/issues
• Discussions: https://github.com/webdevtodayjason/titanium-plugins/discussions

---

Quick Reference Card

┌─────────────────────────────────────────────────┐
│ Titanium Toolkit Quick Reference                │
├─────────────────────────────────────────────────┤
│                                                  │
│ Get Started:                                     │
│   /titanium:getting-started                     │
│                                                  │
│ Plan Work:                                       │
│   /titanium:plan "what to build"                │
│   /titanium:plan backlog/epics/epic-001.md     │
│                                                  │
│ Execute:                                         │
│   /titanium:work                                │
│   /titanium:work "quick feature"               │
│                                                  │
│ Check Progress:                                  │
│   /titanium:status                              │
│   /catchup                                      │
│                                                  │
│ Review Quality:                                  │
│   /titanium:review                              │
│                                                  │
│ Folders:                                         │
│   backlog/      - Your documentation           │
│   .titanium/    - Workflow state (auto)        │
│   src/          - Code (created by agents)     │
│                                                  │
│ Files Created:                                   │
│   .titanium/plan.json       - Plan             │
│   .titanium/workflow-state.json - State        │
│   .titanium/review-report.md - Findings        │
│                                                  │
└─────────────────────────────────────────────────┘

---

What's Next?

Ready to Start?

Simple project:

/titanium:work "your idea here"

Complex project:

# 1. Create backlog documentation
mkdir backlog
# Write backlog/prd.md

# 2. Plan
/titanium:plan backlog/prd.md

# 3. Execute
/titanium:work

Want BMAD Documentation Generation?

BMAD slash commands (/bmad:prd, /bmad:epic, etc.) are coming soon!

Meanwhile, you can:

• Write backlog/ docs manually (simple markdown)
• Use external BMAD tool: npx bmad-method
• Or skip documentation for simple projects

---

You're ready to orchestrate! Pick a workflow above and start building. 🚀