Initial commit
This commit is contained in:
Zhongwei Li
692
commands/titanium-review.md
Normal file
692
commands/titanium-review.md
Normal file
@@ -0,0 +1,692 @@
|
||||
---
|
||||
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.**
|
||||
Reference in New Issue
Block a user