693 lines
15 KiB
Markdown
693 lines
15 KiB
Markdown
---
|
|
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)
|
|
```bash
|
|
git diff --name-only HEAD~1
|
|
```
|
|
Reviews files changed in last commit.
|
|
|
|
**Option B: Current Branch Changes**
|
|
```bash
|
|
git diff --name-only main...HEAD
|
|
```
|
|
Reviews all changes in current branch vs main.
|
|
|
|
**Option C: Specific Files** (if user specified)
|
|
```bash
|
|
# User might say: /titanium:review src/api/*.ts
|
|
```
|
|
Use the files/pattern user specified.
|
|
|
|
**Option D: All Code** (if user requested)
|
|
```bash
|
|
# 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`:
|
|
|
|
```markdown
|
|
# 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.**
|