Hierarchical Project Review
Context
- Project root:!
pwd - Directory structure:!
find. -type f -name "*.py" 2>/dev/null | head -50 - Tech stack: [detect dynamically based on project files]
- Test framework: [detect dynamically based on project files]
- Total files:!
find. -type f -name "*.py" 2>/dev/null | wc -l
Phase 1: Determine Review Scope
Goal: Identify the project directory to review.
Actions:
- Check review scope in this order:
- User argument: If $ARGUMENTS specifies a directory, review that directory recursively - Current directory: If no argument, review the current project root (.)
- Confirm scope with user if the project is large (>100 files) to potentially limit scope.
Phase 2: Technical Leadership Assessment
Goal: Map project architecture, identify risk areas, and determine review focus.
Actions:
- Explore codebase structure using the Explore agent:
- Launch subagent_type="Explore" with thoroughness: "very thorough" - Let the agent autonomously discover architecture, modules, and patterns
- Perform a comprehensive leadership assessment with @tech-lead-reviewer:
- Analyze overall architecture and module structure - Identify architectural patterns and violations - Map dependency graph and coupling points - Assess technical debt accumulation - Evaluate scalability and maintainability
- Determine which specialized agents are required based on risk assessment.
- Identify high-priority areas that need focused review.
Phase 3: Parallel Specialized Reviews
Goal: Collect comprehensive feedback from all relevant specialized reviewers.
Actions:
- Launch required specialized reviews in parallel via the Task tool:
- @code-reviewer — code quality, patterns, testing across modules - @security-reviewer — security audit across entire codebase - @performance-reviewer — performance bottlenecks, algorithm complexity, resource usage - @test-coverage-reviewer — test coverage, edge cases, test quality - @ux-reviewer — UI/UX review for user-facing components (skip if CLI/backend only)
- Each agent reviews within the determined scope (entire project or specified directory).
- Collect outcomes from each agent.
- Resolve conflicting feedback between reviewers.
Phase 4: Consolidated Analysis & Reporting
Goal: Merge findings and produce prioritized actionable improvements.
Actions:
- Merge findings and prioritize by impact/confidence:
- Priority: Critical → High → Medium → Low - Confidence: High → Medium → Low
- Present a consolidated report with:
- Executive summary of project health - Critical issues requiring immediate attention - Technical debt inventory - Strategic recommendations with effort estimates
- Ask whether the user wants fixes implemented.
- If confirmed:
- Address security, quality, or UX issues as requested. - Run tests and validations. - Engage @code-simplifier — code simplification and optimization — to refactor implemented fixes.
- Ensure commits follow Git conventions (see
${CLAUDE_PLUGIN_ROOT}/skills/references/git-commit-conventions.md). - Report outcomes and confirm review completion.
IMPORTANT: You MUST use the Task tool to complete ALL tasks.