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

description

description
Run comprehensive multi-agent quality review

Titanium Review Command

You are coordinating a comprehensive quality review of the codebase. This command launches multiple specialized review agents in parallel, aggregates their findings, and creates a detailed review report.

Orchestration Model: You launch 3 review agents simultaneously in separate context windows. Each agent has specialized skills and reviews from their domain expertise. They run in parallel for efficiency.

Review Agents & Their Skills:

• @code-reviewer: code-quality-standards, security-checklist, testing-strategy
• @security-scanner: security-checklist, code-quality-standards
• @tdd-specialist: testing-strategy, code-quality-standards

Why Parallel: Review agents are independent - they don't need each other's results. Running in parallel saves 60-70% time compared to sequential reviews.

Overview

This review process:

1. Identifies what code to review
2. Launches 3 review agents in parallel (single message, multiple Task calls)
3. Aggregates and categorizes findings from all agents
4. Uses vibe-check for meta-review
5. Creates comprehensive review report
6. Stores findings in Pieces LTM
7. Presents actionable summary with severity-based recommendations

---

Step 1: Identify Review Scope

Determine What to Review

Option A: Recent Changes (default)

git diff --name-only HEAD~1

Reviews files changed in last commit.

Option B: Current Branch Changes

git diff --name-only main...HEAD

Reviews all changes in current branch vs main.

Option C: Specific Files (if user specified)

# User might say: /titanium:review src/api/*.ts

Use the files/pattern user specified.

Option D: All Code (if user requested)

# Find all source files
find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.rb" \) -not -path "*/node_modules/*" -not -path "*/venv/*"

Build File List

Create list of files to review. Store in memory for agent prompts.

Example:

Files to review:
- src/api/auth.ts
- src/middleware/jwt.ts
- src/routes/users.ts
- tests/api/auth.test.ts

---

Step 2: Launch Review Agents in Parallel

CRITICAL: Launch all three agents in a SINGLE message with multiple Task calls.

This enables parallel execution for faster reviews.

Agent 1: Code Reviewer

[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"

Agent 2: Security Scanner

[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

Severity mapping for aggregation:
- Critical → Critical (must fix)
- High → Important (should fix)
- Medium → Nice-to-have (optional)
- Low → Nice-to-have (optional)"

Agent 3: Test Coverage Specialist

[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"

---

Step 3: Wait for All Agents

All three agents will run in parallel. Wait for all to complete before proceeding.

Voice hooks will announce: "Review agents completed"

---

Step 4: Aggregate Findings

Collect All Findings

Gather results from all three agents:

• Code quality findings from @code-reviewer
• Security findings from @security-scanner
• Test coverage findings from @tdd-specialist

Categorize by Severity

🔴 Critical Issues (must fix before deployment):

• Security vulnerabilities (Critical/High)
• Code that will cause bugs or crashes
• Core functionality with no tests

🟡 Important Issues (should fix soon):

• Security issues (Medium)
• Code quality problems that impact maintainability
• Important features with incomplete tests
• Performance issues

🟢 Nice-to-have (optional improvements):

• Code style improvements
• Refactoring opportunities
• Additional test coverage
• Documentation gaps

Count Issues

Total findings:
- Critical: [X]
- Important: [Y]
- Nice-to-have: [Z]

By source:
- Code quality: [N] findings
- Security: [M] findings
- Test coverage: [P] findings

---

Step 5: Meta-Review with vibe-check

Use vibe-check to provide AI oversight of the review:

mcp__vibe-check__vibe_check(
  goal: "Quality review of codebase changes",
  plan: "Ran parallel review: @code-reviewer, @security-scanner, @tdd-specialist",
  progress: "Review complete. Findings: [X] critical, [Y] important, [Z] minor.

Critical issues found:
[List each critical issue briefly]

Important issues found:
[List each important issue briefly]

Test coverage: approximately [X]%",
  uncertainties: [
    "Are there systemic quality issues we're missing?",
    "Is the security approach sound?",
    "Are we testing the right things?",
    "Any architectural concerns?"
  ]
)

Process vibe-check response:

• If vibe-check identifies systemic issues → Include in recommendations
• If vibe-check suggests additional areas to review → Note in report
• Include vibe-check insights in final report

---

Step 6: Create Review Report

Write comprehensive report to .titanium/review-report.md:

# Quality Review Report

**Date**: [current date and time]
**Project**: [project name or goal if known]
**Reviewers**: @code-reviewer, @security-scanner, @tdd-specialist

## Executive Summary

- 🔴 Critical issues: [X]
- 🟡 Important issues: [Y]
- 🟢 Nice-to-have: [Z]
- 📊 Test coverage: ~[X]%

**Overall Assessment**: [Brief 1-2 sentence assessment]

---

## Critical Issues 🔴

### 1. [Issue Title]

**Category**: [Code Quality | Security | Testing]
**File**: `path/to/file.ext:line`
**Severity**: Critical

**Issue**:
[Clear description of what's wrong]

**Risk/Impact**:
[Why this is critical]

**Recommendation**:
```[language]
// Show example fix if applicable
[code example]

Steps to Fix:

1. [Step 1]
2. [Step 2]
3. [Step 3]

---

2. [Next Critical Issue]

[... repeat structure ...]

---

Important Issues 🟡

1. [Issue Title]

Category: [Code Quality | Security | Testing] File: path/to/file.ext:line Severity: Important

Issue: [Description]

Impact: [Why this matters]

Recommendation: [How to address it]

---

2. [Next Important Issue]

[... repeat structure ...]

---

Nice-to-have Improvements 🟢

Code Quality

• [Improvement 1 with file reference]
• [Improvement 2 with file reference]

Testing

• [Test improvement 1]
• [Test improvement 2]

Documentation

• [Doc improvement 1]
• [Doc improvement 2]

---

Test Coverage Analysis

Overall Coverage: ~[X]%

Files with Insufficient Coverage (<80%):

• file1.ts - ~[X]% coverage
• file2.ts - ~[Y]% coverage

Untested Critical Functions:

• functionName() in file.ts:line
• anotherFunction() in file.ts:line

Missing Test Categories:

• Error condition tests
• Edge case tests
• Integration tests
• E2E tests for critical flows

Recommendations:

1. [Priority test to add]
2. [Second priority test]
3. [Third priority test]

---

Security Analysis

Vulnerabilities Found: [X] Security Best Practices Violations: [Y]

Key Security Concerns:

1. [Concern 1]
2. [Concern 2]

Security Recommendations:

1. [Priority 1 security fix]
2. [Priority 2 security fix]

---

vibe-check Meta-Review

[Paste vibe-check assessment here]

Systemic Issues Identified: [Any patterns or systemic problems vibe-check identified]

Additional Recommendations: [Any suggestions from vibe-check that weren't captured by agents]

---

Recommendations Priority List

Must Do (Critical):

1. [Critical fix 1] - File: path/to/file.ext:line
2. [Critical fix 2] - File: path/to/file.ext:line

Should Do (Important):

1. [Important fix 1] - File: path/to/file.ext:line
2. [Important fix 2] - File: path/to/file.ext:line
3. [Important fix 3] - File: path/to/file.ext:line

Nice to Do (Optional):

1. [Optional improvement 1]
2. [Optional improvement 2]

---

Files Reviewed

Total files: [X]

Source Files ([N] files):

• path/to/file1.ext
• path/to/file2.ext

Test Files ([M] files):

• path/to/test1.test.ext
• path/to/test2.test.ext

---

Next Steps

1. Address all critical issues immediately
2. Plan to fix important issues in next sprint
3. Consider nice-to-have improvements for tech debt backlog
4. Re-run review after fixes: /titanium:review

---

## Step 7: Store Review in Pieces

mcp__Pieces__create_pieces_memory( summary_description: "Quality review findings for [project/files]", summary: "Comprehensive quality review completed by @code-reviewer, @security-scanner, @tdd-specialist.

Findings:

• Critical issues: [X] - [briefly list each critical issue]
• Important issues: [Y] - [briefly describe categories]
• Nice-to-have: [Z]

Test coverage: approximately [X]%

Security assessment: [summary - no vulnerabilities / minor issues / concerns found]

Code quality assessment: [summary - excellent / good / needs improvement]

vibe-check meta-review: [brief summary of vibe-check insights]

Key recommendations:

1. [Top priority recommendation]
2. [Second priority]
3. [Third priority]

All findings documented in .titanium/review-report.md with file:line references and fix recommendations.", files: [ ".titanium/review-report.md", "list all reviewed source files", "list all test files" ], project: "$(pwd)" )

---

## Step 8: Present Summary to User

🔍 Quality Review Complete

📊 Summary:

• 🔴 [X] Critical Issues
• 🟡 [Y] Important Issues
• 🟢 [Z] Nice-to-have Improvements
• 📈 Test Coverage: ~[X]%

📄 Full Report: .titanium/review-report.md

---

⚠️ Critical Issues (must fix):

1. [Issue 1 title] File: path/to/file.ext:line [Brief description]

2. [Issue 2 title] File: path/to/file.ext:line [Brief description]

[... list all critical issues ...]

---

💡 Top Recommendations:

1. [Priority 1 action item]
2. [Priority 2 action item]
3. [Priority 3 action item]

---

🤖 vibe-check Assessment: [Brief quote or summary from vibe-check]

---

Would you like me to:

1. Fix the critical issues now
2. Create GitHub issues for these findings
3. Provide more details on any specific issue
4. Skip and continue (not recommended if critical issues exist)

### Handle User Response

**If user wants fixes**:
- Address critical issues one by one
- After each fix, run relevant tests
- Re-run review to verify fixes
- Update review report

**If user wants GitHub issues**:
- Create issues for each critical and important finding
- Include all details from review report
- Provide issue URLs

**If user wants more details**:
- Read specific sections of review report
- Explain the issue and fix in more detail

**If user says continue**:
- Acknowledge and complete
- Remind that issues are documented in review report

---

## Error Handling

### If No Files to Review

⚠️ No files found to review.

This could mean:

• No changes since last commit
• Working directory is clean
• Specified files don't exist

Would you like to:

1. Review all source files
2. Specify which files to review
3. Cancel review

### If Review Agents Fail

❌ Review failed

Agent @[agent-name] encountered an error: [error]

Continuing with other review agents...

[Proceed with available results]

### If vibe-check Not Available

Note: vibe-check MCP is not available. Proceeding without meta-review.

To enable AI-powered meta-review:

1. Create ~/.vibe-check/.env
2. Add API key (GEMINI_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY)
3. Restart Claude Code

---

## Integration with Workflow

**After /titanium:work**:

User: /titanium:work [... implementation completes ...] User: /titanium:review [... review runs ...]

**Standalone Usage**:

User: /titanium:review

Reviews recent changes

**With File Specification**:

User: /titanium:review src/api/*.ts

Reviews only specified files

**Before Committing**:

User: I'm about to commit. Can you review my changes? Claude: /titanium:review [... review runs on uncommitted changes ...]

---

## Voice Feedback

Voice hooks automatically announce:
- "Starting quality review" (at start)
- "Review agents completed" (after parallel execution)
- "Review complete: [X] issues found" (at end)

No additional voice calls needed.

---

## Example Outputs

### Example 1: No Issues Found

🔍 Quality Review Complete

📊 Summary:

• 🔴 0 Critical Issues
• 🟡 0 Important Issues
• 🟢 3 Nice-to-have Improvements
• 📈 Test Coverage: ~92%

✅ No critical or important issues found!

💡 Optional Improvements:

1. Consider extracting duplicated validation logic in auth.ts and users.ts
2. Add JSDoc comments to public API methods
3. Increase test coverage for edge cases in payment module

Code quality: Excellent Security: No vulnerabilities found Testing: Comprehensive coverage

📄 Full details: .titanium/review-report.md

### Example 2: Critical Issues Found

🔍 Quality Review Complete

📊 Summary:

• 🔴 2 Critical Issues
• 🟡 5 Important Issues
• 🟢 12 Nice-to-have Improvements
• 📈 Test Coverage: ~65%

⚠️ CRITICAL ISSUES (must fix):

1. SQL Injection Vulnerability File: src/api/users.ts:45 User input concatenated directly into SQL query Risk: Attacker could read/modify database

2. Missing Authentication Check File: src/api/admin.ts:23 Admin endpoint has no auth middleware Risk: Unauthorized access to admin functions

💡 MUST DO:

1. Use parameterized queries for all SQL
2. Add authentication middleware to admin routes
3. Add tests for authentication flows

Would you like me to fix these critical issues now?

---

**This command provides comprehensive multi-agent quality review with actionable findings and clear priorities.**