diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 4e22718..d4cf1dc 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,8 +11,8 @@ "plugins": [ { "name": "compound-engineering", - "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 28 specialized agents, 24 commands, and 15 skills.", - "version": "2.28.0", + "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 28 specialized agents, 25 commands, and 15 skills.", + "version": "2.29.0", "author": { "name": "Kieran Klaassen", "url": "https://github.com/kieranklaassen", diff --git a/plugins/compound-engineering/.claude-plugin/plugin.json b/plugins/compound-engineering/.claude-plugin/plugin.json index 97ea742..20f6736 100644 --- a/plugins/compound-engineering/.claude-plugin/plugin.json +++ b/plugins/compound-engineering/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "compound-engineering", - "version": "2.28.0", - "description": "AI-powered development tools. 28 agents, 24 commands, 15 skills, 1 MCP server for code review, research, design, and workflow automation.", + "version": "2.29.1", + "description": "AI-powered development tools. 28 agents, 25 commands, 15 skills, 1 MCP server for code review, research, design, and workflow automation.", "author": { "name": "Kieran Klaassen", "email": "kieran@every.to", diff --git a/plugins/compound-engineering/CHANGELOG.md b/plugins/compound-engineering/CHANGELOG.md index dd1c7f9..0d7cdcc 100644 --- a/plugins/compound-engineering/CHANGELOG.md +++ b/plugins/compound-engineering/CHANGELOG.md @@ -5,6 +5,61 @@ All notable changes to the compound-engineering plugin will be documented in thi The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [2.29.1] - 2026-01-28 + +### Improved + +- **`/workflows:brainstorm` command** - Better question flow + - Added "Ask more questions" option at handoff phase + - Clarified that Claude should ask the user questions (not wait for user to ask) + - Added requirement to resolve ALL open questions before offering to proceed to planning + +--- + +## [2.29.0] - 2026-01-25 + +### Added + +- **`/compound-engineering-setup` command** - Configure plugin agents and preferences + - Multi-step onboarding with AskUserQuestion for easy setup + - Auto-detects project type (Rails, Python, TypeScript, etc.) + - Three setup modes: Quick (smart defaults), Advanced (manual selection), Minimal + - Creates `.claude/compound-engineering.json` config file + - Supports global config (`~/.claude/`) or project-specific (`.claude/`) + - **Custom agent discovery**: Auto-detects agents in `.claude/agents/` and `~/.claude/agents/` + - **Modify flow**: Re-run setup to add/remove agents from existing config + - **Custom agent guide**: Instructions for creating your own review agents + +### Changed + +- **`/workflows:review`** - Now reads review agents from config file instead of hardcoding +- **`/plan_review`** - Now reads plan review agents from config file +- **`/workflows:work`** - References config for optional reviewer agents +- **`/workflows:compound`** - References config for specialized agent invocation + +### Configuration + +New config file format (`.claude/compound-engineering.json`): +```json +{ + "version": "1.0", + "projectType": "rails", + "reviewAgents": ["kieran-rails-reviewer", "code-simplicity-reviewer", "my-custom-reviewer"], + "planReviewAgents": ["kieran-rails-reviewer", "code-simplicity-reviewer"], + "customAgents": { + "my-custom-reviewer": ".claude/agents/my-custom-reviewer.md" + }, + "conditionalAgents": { + "migrations": ["data-migration-expert", "deployment-verification-agent"], + "frontend": ["julik-frontend-races-reviewer"], + "architecture": ["architecture-strategist"], + "data": ["data-integrity-guardian"] + } +} +``` + +--- + ## [2.28.0] - 2026-01-21 ### Added diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index b1a710d..9660ad8 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -6,9 +6,9 @@ AI-powered development tools that get smarter with every use. Make each unit of | Component | Count | |-----------|-------| -| Agents | 27 | -| Commands | 20 | -| Skills | 14 | +| Agents | 28 | +| Commands | 25 | +| Skills | 15 | | MCP Servers | 1 | ## Agents @@ -90,6 +90,7 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in | `/create-agent-skill` | Create or edit Claude Code skills | | `/generate_command` | Generate new slash commands | | `/heal-skill` | Fix skill documentation issues | +| `/compound-engineering-setup` | Configure plugin agents and preferences | | `/plan_review` | Multi-agent plan review in parallel | | `/report-bug` | Report a bug in the plugin | | `/reproduce-bug` | Reproduce bugs using logs and console | diff --git a/plugins/compound-engineering/commands/plan_review.md b/plugins/compound-engineering/commands/plan_review.md index 70ef5dd..4f739ca 100644 --- a/plugins/compound-engineering/commands/plan_review.md +++ b/plugins/compound-engineering/commands/plan_review.md @@ -4,4 +4,78 @@ description: Have multiple specialized agents review a plan in parallel argument-hint: "[plan file path or plan content]" --- -Have @agent-dhh-rails-reviewer @agent-kieran-rails-reviewer @agent-code-simplicity-reviewer review this plan in parallel. +# Plan Review + +Review a plan using configured agents from `.claude/compound-engineering.json`. + +## Load Configuration (Auto-Setup if Missing) + + + +**Step 1: Check for configuration file:** + +```bash +test -f .claude/compound-engineering.json && echo "project" || \ +test -f ~/.claude/compound-engineering.json && echo "global" || echo "none" +``` + +**Step 2: If config exists** → Read `planReviewAgents` array and proceed. + +**Step 3: If NO config exists** → Run inline quick setup: + +``` +AskUserQuestion: + questions: + - question: "No agent configuration found. How would you like to configure plan review agents?" + header: "Quick Setup" + options: + - label: "Quick Setup - Use smart defaults (Recommended)" + description: "Auto-detect project type and use appropriate agents." + - label: "Full Setup - Customize everything" + description: "Run /compound-engineering-setup for detailed configuration." + - label: "Skip - Use defaults just this once" + description: "Use general defaults for this review only." +``` + +**If "Quick Setup":** +1. Detect project type +2. Create `.claude/compound-engineering.json` with smart defaults +3. Continue with plan review using new config + +**If "Full Setup":** +1. Run `/compound-engineering-setup` +2. After setup, continue with plan review + +**If "Skip":** +1. Use defaults: `code-simplicity-reviewer`, `architecture-strategist` + + + +## Execute Review + +For each agent in `planReviewAgents`: + +``` +Task {agent-name}("Review this plan: {plan content}") +``` + +Run all agents in parallel using multiple Task tool calls in a single message. + +## Example Config + +```json +{ + "planReviewAgents": [ + "kieran-rails-reviewer", + "code-simplicity-reviewer" + ] +} +``` + +## Fallback Defaults + +If no config and user wants defaults: +- **Rails projects**: `kieran-rails-reviewer`, `code-simplicity-reviewer` +- **Python projects**: `kieran-python-reviewer`, `code-simplicity-reviewer` +- **TypeScript projects**: `kieran-typescript-reviewer`, `code-simplicity-reviewer` +- **General**: `code-simplicity-reviewer`, `architecture-strategist` diff --git a/plugins/compound-engineering/commands/setup.md b/plugins/compound-engineering/commands/setup.md new file mode 100644 index 0000000..b94e839 --- /dev/null +++ b/plugins/compound-engineering/commands/setup.md @@ -0,0 +1,486 @@ +--- +name: compound-engineering-setup +description: Configure compound-engineering plugin agents and preferences for your project +argument-hint: "[--global to configure globally]" +--- + +# Compound Engineering Setup + +Configure which review agents and workflows to use for this project. Creates a `.claude/compound-engineering.json` configuration file. + +## Step 0: Detect Existing Config & Custom Agents + + + +### Check for existing configuration: + +```bash +# Check project config +test -f .claude/compound-engineering.json && echo "PROJECT_CONFIG_EXISTS" + +# Check global config +test -f ~/.claude/compound-engineering.json && echo "GLOBAL_CONFIG_EXISTS" +``` + +### Scan for custom local agents: + +```bash +# Project-level custom agents +ls .claude/agents/*.md 2>/dev/null | head -20 + +# Global custom agents +ls ~/.claude/agents/*.md 2>/dev/null | head -20 + +# Project-level custom skills (that might be reviewers) +ls .claude/skills/*/SKILL.md 2>/dev/null | head -20 +``` + +**For each discovered agent/skill file:** +1. Read the file's YAML frontmatter or first few lines +2. Extract `name` and `description` +3. Check if name contains "review" or description mentions "code review" +4. Store as `customAgents[]` array for later + +**Example discovered agents:** +``` +Found 3 custom agents: +- my-team-reviewer (.claude/agents/my-team-reviewer.md) - "Team-specific Rails conventions" +- api-reviewer (.claude/agents/api-reviewer.md) - "REST API design review" +- test-coverage-checker (~/.claude/agents/test-coverage-checker.md) - "Verify test coverage" +``` + + + +## Step 1: Determine Setup Mode (New vs Modify) + + + +**If config already exists:** + +``` +AskUserQuestion: + questions: + - question: "Configuration found. What would you like to do?" + header: "Setup" + options: + - label: "Modify existing config" + description: "Add/remove agents from your current configuration" + - label: "Start fresh" + description: "Delete current config and set up from scratch" + - label: "View current config" + description: "Show what's currently configured" +``` + +**If "View current config":** +1. Read and display the current `.claude/compound-engineering.json` +2. Show which agents are configured for each category +3. Ask again what they want to do + +**If "Modify existing config":** → Go to Step 2B (Modify Flow) + +**If "Start fresh":** → Go to Step 2A (New Setup Flow) + +**If no config exists:** → Go to Step 2A (New Setup Flow) + + + +## Step 2A: New Setup Flow + + + +### Detect Project Type + +```bash +# Check for common project indicators +ls Gemfile package.json requirements.txt pyproject.toml Cargo.toml go.mod 2>/dev/null +test -f config/routes.rb && echo "RAILS" +test -f tsconfig.json && echo "TYPESCRIPT" +``` + +**Detection Rules:** +- `Gemfile` + `config/routes.rb` → **Rails** +- `Gemfile` without Rails → **Ruby** +- `package.json` + `tsconfig.json` → **TypeScript** +- `package.json` without TypeScript → **JavaScript** +- `requirements.txt` OR `pyproject.toml` → **Python** +- `Cargo.toml` → **Rust** +- `go.mod` → **Go** +- None → **General** + +### Choose Setup Mode + +``` +AskUserQuestion: + questions: + - question: "How would you like to configure review agents?" + header: "Setup mode" + options: + - label: "Quick Setup (Recommended)" + description: "Smart defaults for {detected_type} + any custom agents found" + - label: "Advanced Setup" + description: "Manually select each agent including custom ones" + - label: "Minimal Setup" + description: "Only essential agents (security + simplicity)" +``` + +### Quick Setup - Apply Defaults + Custom Agents + +**For detected project type, use these defaults:** + +| Project Type | Review Agents | Plan Review Agents | +|--------------|---------------|-------------------| +| Rails | kieran-rails-reviewer, dhh-rails-reviewer, code-simplicity-reviewer, security-sentinel, performance-oracle | kieran-rails-reviewer, code-simplicity-reviewer | +| Python | kieran-python-reviewer, code-simplicity-reviewer, security-sentinel, performance-oracle | kieran-python-reviewer, code-simplicity-reviewer | +| TypeScript | kieran-typescript-reviewer, code-simplicity-reviewer, security-sentinel, performance-oracle | kieran-typescript-reviewer, code-simplicity-reviewer | +| General | code-simplicity-reviewer, security-sentinel, performance-oracle | code-simplicity-reviewer | + +**If custom agents were discovered:** + +``` +AskUserQuestion: + questions: + - question: "Found {N} custom agents. Add them to your review configuration?" + header: "Custom agents" + multiSelect: true + options: + - label: "{custom_agent_1_name}" + description: "{custom_agent_1_description}" + - label: "{custom_agent_2_name}" + description: "{custom_agent_2_description}" + - label: "Skip - don't add custom agents" + description: "Only use built-in agents" +``` + +Add selected custom agents to `reviewAgents` array. + +### Advanced Setup - Manual Selection + +**Question 1: Built-in Review Agents** + +``` +AskUserQuestion: + questions: + - question: "Which built-in review agents should run on every PR?" + header: "Built-in agents" + multiSelect: true + options: + - label: "kieran-rails-reviewer" + description: "Rails conventions, naming, clarity" + - label: "kieran-typescript-reviewer" + description: "TypeScript best practices, type safety" + - label: "kieran-python-reviewer" + description: "Python patterns, typing, best practices" + - label: "dhh-rails-reviewer" + description: "Opinionated Rails style" +``` + +**Question 2: Custom Agents (if any discovered)** + +``` +AskUserQuestion: + questions: + - question: "Which of your custom agents should run on every PR?" + header: "Your agents" + multiSelect: true + options: + - label: "{custom_agent_1_name}" + description: "{custom_agent_1_description} ({path})" + - label: "{custom_agent_2_name}" + description: "{custom_agent_2_description} ({path})" +``` + +**Question 3: Quality & Security** + +``` +AskUserQuestion: + questions: + - question: "Which quality and security agents should run?" + header: "Quality" + multiSelect: true + options: + - label: "code-simplicity-reviewer (Recommended)" + description: "Ensures code is as simple as possible" + - label: "security-sentinel (Recommended)" + description: "Security vulnerabilities and OWASP compliance" + - label: "performance-oracle" + description: "Performance issues and optimization" + - label: "agent-native-reviewer" + description: "Verify features are AI-accessible" +``` + +**Question 4: Conditional Agents** + +``` +AskUserQuestion: + questions: + - question: "Enable smart agents that run based on what files changed?" + header: "Conditional" + multiSelect: true + options: + - label: "Migration agents (Recommended)" + description: "data-migration-expert for DB changes" + - label: "Frontend agents" + description: "julik-frontend-races-reviewer for JS/TS" + - label: "Architecture agents" + description: "architecture-strategist for structural changes" + - label: "Data agents" + description: "data-integrity-guardian for model changes" +``` + + + +## Step 2B: Modify Existing Config + + + +Read current configuration and present current state: + +```markdown +## Current Configuration + +**Project Type:** {type} + +**Review Agents ({count}):** +- ✓ kieran-rails-reviewer +- ✓ code-simplicity-reviewer +- ✓ security-sentinel +- ✓ my-custom-reviewer (custom) + +**Plan Review Agents ({count}):** +- ✓ kieran-rails-reviewer +- ✓ code-simplicity-reviewer + +**Conditional Agents:** +- Migrations: data-migration-expert, deployment-verification-agent +- Frontend: julik-frontend-races-reviewer +- Architecture: (none) +- Data: (none) +``` + +``` +AskUserQuestion: + questions: + - question: "What would you like to modify?" + header: "Modify" + options: + - label: "Add agents" + description: "Add more agents to your configuration" + - label: "Remove agents" + description: "Remove agents you don't want" + - label: "Change conditional agents" + description: "Modify which agents run for specific file types" + - label: "Done" + description: "Save and exit" +``` + +### Add Agents Flow + +Show agents NOT currently in config: + +``` +AskUserQuestion: + questions: + - question: "Select agents to ADD to your configuration:" + header: "Add agents" + multiSelect: true + options: + - label: "dhh-rails-reviewer" + description: "Opinionated Rails style (not currently enabled)" + - label: "performance-oracle" + description: "Performance issues (not currently enabled)" + - label: "{new_custom_agent}" + description: "Your custom agent (discovered in .claude/agents/)" +``` + +### Remove Agents Flow + +Show agents currently IN config: + +``` +AskUserQuestion: + questions: + - question: "Select agents to REMOVE from your configuration:" + header: "Remove agents" + multiSelect: true + options: + - label: "kieran-rails-reviewer" + description: "Currently enabled - will be removed" + - label: "security-sentinel" + description: "Currently enabled - will be removed" +``` + +After each modification, loop back to "What would you like to modify?" until user selects "Done". + + + +## Step 3: Write Configuration + + + +**Determine target path:** +- If `--global`: `~/.claude/compound-engineering.json` +- Otherwise: `.claude/compound-engineering.json` + +**Create directory if needed:** +```bash +mkdir -p .claude # or ~/.claude for global +``` + +**Write JSON configuration:** + +```json +{ + "version": "1.0", + "projectType": "{detected_type}", + "reviewAgents": [ + "kieran-rails-reviewer", + "code-simplicity-reviewer", + "security-sentinel", + "my-custom-reviewer" + ], + "planReviewAgents": [ + "kieran-rails-reviewer", + "code-simplicity-reviewer" + ], + "customAgents": { + "my-custom-reviewer": ".claude/agents/my-custom-reviewer.md", + "api-reviewer": "~/.claude/agents/api-reviewer.md" + }, + "conditionalAgents": { + "migrations": ["data-migration-expert", "deployment-verification-agent"], + "frontend": ["julik-frontend-races-reviewer"], + "architecture": ["architecture-strategist", "pattern-recognition-specialist"], + "data": ["data-integrity-guardian"] + }, + "options": { + "agentNative": true, + "parallelReviews": true + } +} +``` + +**Note:** The `customAgents` object maps custom agent names to their file paths, so workflows know where to find them. + + + +## Step 4: Summary + + + +```markdown +## Configuration Complete! + +**Saved to:** `.claude/compound-engineering.json` +**Project Type:** Rails + +### Review Agents (run on every PR) +**Built-in:** +- kieran-rails-reviewer +- code-simplicity-reviewer +- security-sentinel + +**Custom:** +- my-custom-reviewer (.claude/agents/) + +### Plan Review Agents +- kieran-rails-reviewer +- code-simplicity-reviewer + +### Conditional Agents (run when relevant files change) +| Trigger | Agents | +|---------|--------| +| DB Migrations | data-migration-expert, deployment-verification-agent | +| Frontend (JS/TS) | julik-frontend-races-reviewer | +| Architecture | architecture-strategist | +| Data/Models | data-integrity-guardian | + +--- + +**What's next:** +1. Run `/workflows:review` to test your configuration +2. Run `/compound-engineering-setup` to modify settings anytime +3. Commit `.claude/compound-engineering.json` to share with your team + +**Add more custom agents:** +Create `.claude/agents/my-agent.md` with your custom review logic, +then re-run `/compound-engineering-setup` to add it to your config. +``` + + + +## Creating Custom Agents + + + +To create your own review agent that gets auto-discovered: + +### 1. Create the agent file + +**Project-level:** `.claude/agents/my-reviewer.md` +**Global:** `~/.claude/agents/my-reviewer.md` + +### 2. Use this template: + +```markdown +--- +name: my-team-reviewer +description: Reviews code for our team's specific conventions +--- + +# My Team Reviewer + +You are a code reviewer specializing in our team's conventions. + +## Review Checklist + +- [ ] Check naming conventions match our style guide +- [ ] Verify error handling follows our patterns +- [ ] Ensure logging is consistent +- [ ] Check for proper documentation + +## When reviewing, focus on: + +1. **Naming**: We use snake_case for methods, PascalCase for classes +2. **Errors**: All errors should be logged with context +3. **Tests**: Every public method needs a test + +## Output format + +Provide findings as a bulleted list with file:line references. +``` + +### 3. Re-run setup + +```bash +/compound-engineering-setup +``` + +Your agent will be discovered and offered as an option! + + + +## Available Built-in Agents + + + +**Code Review (language-specific):** +- `kieran-rails-reviewer` - Rails conventions and best practices +- `kieran-python-reviewer` - Python patterns and typing +- `kieran-typescript-reviewer` - TypeScript type safety +- `dhh-rails-reviewer` - Opinionated Rails style + +**Quality & Security:** +- `code-simplicity-reviewer` - Code simplicity and YAGNI +- `security-sentinel` - Security vulnerabilities +- `performance-oracle` - Performance optimization +- `architecture-strategist` - Architectural patterns +- `pattern-recognition-specialist` - Code patterns and anti-patterns +- `agent-native-reviewer` - AI accessibility verification + +**Specialized (conditional):** +- `data-migration-expert` - Database migration safety +- `deployment-verification-agent` - Deployment checklists +- `data-integrity-guardian` - Data model integrity +- `julik-frontend-races-reviewer` - JavaScript race conditions + + diff --git a/plugins/compound-engineering/commands/workflows/brainstorm.md b/plugins/compound-engineering/commands/workflows/brainstorm.md index 3cb204d..578eba6 100644 --- a/plugins/compound-engineering/commands/workflows/brainstorm.md +++ b/plugins/compound-engineering/commands/workflows/brainstorm.md @@ -78,6 +78,8 @@ Write a brainstorm document to `docs/brainstorms/YYYY-MM-DD--brainstorm.m Ensure `docs/brainstorms/` directory exists before writing. +**IMPORTANT:** Before proceeding to Phase 4, check if there are any Open Questions listed in the brainstorm document. If there are open questions, YOU MUST ask the user about each one using AskUserQuestion before offering to proceed to planning. Move resolved questions to a "Resolved Questions" section. + ### Phase 4: Handoff Use **AskUserQuestion tool** to present next steps: @@ -86,8 +88,11 @@ Use **AskUserQuestion tool** to present next steps: **Options:** 1. **Proceed to planning** - Run `/workflows:plan` (will auto-detect this brainstorm) -2. **Refine design further** - Continue exploring -3. **Done for now** - Return later +2. **Ask more questions** - I have more questions to clarify before moving on +3. **Refine design further** - Continue exploring the design +4. **Done for now** - Return later + +**If user selects "Ask more questions":** YOU (Claude) return to Phase 1.2 (Collaborative Dialogue) and continue asking the USER questions one at a time to further refine the design. The user wants YOU to probe deeper - ask about edge cases, constraints, preferences, or areas not yet explored. Continue until the user is satisfied, then return to Phase 4. ## Output Summary diff --git a/plugins/compound-engineering/commands/workflows/compound.md b/plugins/compound-engineering/commands/workflows/compound.md index 4042685..c5b4a2a 100644 --- a/plugins/compound-engineering/commands/workflows/compound.md +++ b/plugins/compound-engineering/commands/workflows/compound.md @@ -62,12 +62,14 @@ This command launches multiple specialized subagents IN PARALLEL to maximize eff - Creates the file in correct location ### 7. **Optional: Specialized Agent Invocation** (Post-Documentation) - Based on problem type detected, automatically invoke applicable agents: - - **performance_issue** → `performance-oracle` - - **security_issue** → `security-sentinel` - - **database_issue** → `data-integrity-guardian` - - **test_failure** → `cora-test-reviewer` - - Any code-heavy issue → `kieran-rails-reviewer` + `code-simplicity-reviewer` + Based on problem type detected, invoke agents from `.claude/compound-engineering.json` config: + - **performance_issue** → `performance-oracle` (if configured) + - **security_issue** → `security-sentinel` (if configured) + - **database_issue** → `data-integrity-guardian` (if in `conditionalAgents.data`) + - **test_failure** → test reviewer (if configured) + - Any code-heavy issue → agents from `reviewAgents` + `code-simplicity-reviewer` + + **Note:** If no config exists, use project-appropriate defaults or prompt to run `/compound-engineering-setup`. ## What It Captures @@ -174,17 +176,18 @@ Build → Test → Find Issue → Research → Improve → Document → Validate ## Applicable Specialized Agents -Based on problem type, these agents can enhance documentation: +Based on problem type, agents from `.claude/compound-engineering.json` config enhance documentation. + +**Configure via:** `/compound-engineering-setup` -### Code Quality & Review -- **kieran-rails-reviewer**: Reviews code examples for Rails best practices +### Code Quality & Review (from `reviewAgents`) +- Language-specific reviewer (e.g., `kieran-rails-reviewer`, `kieran-python-reviewer`) - **code-simplicity-reviewer**: Ensures solution code is minimal and clear - **pattern-recognition-specialist**: Identifies anti-patterns or repeating issues -### Specific Domain Experts +### Specific Domain Experts (from `conditionalAgents`) - **performance-oracle**: Analyzes performance_issue category solutions - **security-sentinel**: Reviews security_issue solutions for vulnerabilities -- **cora-test-reviewer**: Creates test cases for prevention strategies - **data-integrity-guardian**: Reviews database_issue migrations and queries ### Enhancement & Documentation @@ -193,7 +196,7 @@ Based on problem type, these agents can enhance documentation: - **framework-docs-researcher**: Links to Rails/gem documentation references ### When to Invoke -- **Auto-triggered** (optional): Agents can run post-documentation for enhancement +- **Auto-triggered** (optional): Agents from config run post-documentation for enhancement - **Manual trigger**: User can invoke agents after /workflows:compound completes for deeper review ## Related Commands diff --git a/plugins/compound-engineering/commands/workflows/review.md b/plugins/compound-engineering/commands/workflows/review.md index 282c9f0..16feebc 100644 --- a/plugins/compound-engineering/commands/workflows/review.md +++ b/plugins/compound-engineering/commands/workflows/review.md @@ -48,25 +48,73 @@ Ensure that the code is ready for analysis (either in worktree or on current bra +#### Load Review Configuration (Auto-Setup if Missing) + + + +**Step 1: Check for configuration file:** + +```bash +# Check project config first, then global +test -f .claude/compound-engineering.json && echo "project" || \ +test -f ~/.claude/compound-engineering.json && echo "global" || echo "none" +``` + +**Step 2: If config exists** → Read agents from configuration and proceed. + +**Step 3: If NO config exists** → Run inline quick setup: + +``` +AskUserQuestion: + questions: + - question: "No agent configuration found. How would you like to configure review agents?" + header: "Quick Setup" + options: + - label: "Quick Setup - Use smart defaults (Recommended)" + description: "Auto-detect project type and use appropriate agents. Takes 5 seconds." + - label: "Full Setup - Customize everything" + description: "Run /compound-engineering-setup for detailed configuration." + - label: "Skip - Use defaults just this once" + description: "Use general defaults for this review only, don't save config." +``` + +**If "Quick Setup":** +1. Detect project type (check for Gemfile+Rails, package.json+tsconfig, etc.) +2. Create `.claude/compound-engineering.json` with smart defaults for detected type +3. Inform user: "Created config for {project_type}. Run `/compound-engineering-setup` anytime to customize." +4. Continue with review using new config + +**If "Full Setup":** +1. Run `/compound-engineering-setup` (the full interactive flow) +2. After setup completes, continue with review + +**If "Skip":** +1. Use general defaults for this review only +2. Don't create config file + + + #### Parallel Agents to review the PR: -Run ALL or most of these agents at the same time: - -1. Task kieran-rails-reviewer(PR content) -2. Task dhh-rails-reviewer(PR title) -3. If turbo is used: Task rails-turbo-expert(PR content) -4. Task git-history-analyzer(PR content) -5. Task dependency-detective(PR content) -6. Task pattern-recognition-specialist(PR content) -7. Task architecture-strategist(PR content) -8. Task code-philosopher(PR content) -9. Task security-sentinel(PR content) -10. Task performance-oracle(PR content) -11. Task devops-harmony-analyst(PR content) -12. Task data-integrity-guardian(PR content) -13. Task agent-native-reviewer(PR content) - Verify new features are agent-accessible +**From `reviewAgents` in config** (or defaults if no config): + +Run all configured review agents in parallel. Example defaults: +- Task {first-configured-reviewer}(PR content) +- Task {second-configured-reviewer}(PR content) +- Task code-simplicity-reviewer(PR content) +- Task security-sentinel(PR content) +- Task performance-oracle(PR content) + +**Default reviewAgents (if no config):** +- Rails: `kieran-rails-reviewer`, `dhh-rails-reviewer`, `code-simplicity-reviewer`, `security-sentinel`, `performance-oracle` +- Python: `kieran-python-reviewer`, `code-simplicity-reviewer`, `security-sentinel`, `performance-oracle` +- TypeScript: `kieran-typescript-reviewer`, `code-simplicity-reviewer`, `security-sentinel`, `performance-oracle` +- General: `code-simplicity-reviewer`, `security-sentinel`, `performance-oracle` + +**If `options.agentNative` is true (default):** +- Task agent-native-reviewer(PR content) - Verify new features are agent-accessible @@ -76,10 +124,14 @@ Run ALL or most of these agents at the same time: These agents are run ONLY when the PR matches specific criteria. Check the PR files list to determine if they apply: -**If PR contains database migrations (db/migrate/*.rb files) or data backfills:** +--- + +**MIGRATIONS: If PR contains database migrations or data backfills:** + +From `conditionalAgents.migrations` in config (defaults: `data-migration-expert`, `deployment-verification-agent`) -14. Task data-migration-expert(PR content) - Validates ID mappings match production, checks for swapped values, verifies rollback safety -15. Task deployment-verification-agent(PR content) - Creates Go/No-Go deployment checklist with SQL verification queries +- Task data-migration-expert(PR content) - Validates ID mappings match production, checks for swapped values, verifies rollback safety +- Task deployment-verification-agent(PR content) - Creates Go/No-Go deployment checklist with SQL verification queries **When to run migration agents:** - PR includes files matching `db/migrate/*.rb` @@ -92,6 +144,64 @@ These agents are run ONLY when the PR matches specific criteria. Check the PR fi - `data-migration-expert`: Verifies hard-coded mappings match production reality (prevents swapped IDs), checks for orphaned associations, validates dual-write patterns - `deployment-verification-agent`: Produces executable pre/post-deploy checklists with SQL queries, rollback procedures, and monitoring plans +--- + +**FRONTEND: If PR contains JavaScript/TypeScript or frontend files:** + +From `conditionalAgents.frontend` in config (defaults: `julik-frontend-races-reviewer`) + +- Task julik-frontend-races-reviewer(PR content) - Reviews for race conditions, async issues, and frontend performance problems + +**When to run frontend agents:** +- PR includes files matching `*.js`, `*.ts`, `*.jsx`, `*.tsx` +- PR includes files in `app/javascript/**`, `app/assets/javascripts/**` +- PR includes files in `frontend/**`, `src/**` (for JS-heavy projects) +- PR modifies Stimulus controllers, Turbo frames, or Hotwire components +- PR includes CSS/SCSS changes with JavaScript interactions + +**What these agents check:** +- `julik-frontend-races-reviewer`: Detects async race conditions, improper event handling, memory leaks, Turbo/Stimulus lifecycle issues, and JavaScript performance anti-patterns + +--- + +**ARCHITECTURE: If PR contains significant structural changes:** + +From `conditionalAgents.architecture` in config (defaults: `architecture-strategist`, `pattern-recognition-specialist`) + +- Task architecture-strategist(PR content) - Evaluates architectural decisions, coupling, and system design +- Task pattern-recognition-specialist(PR content) - Identifies anti-patterns, code smells, and architectural drift + +**When to run architecture agents:** +- PR creates new directories or major new components +- PR changes 10+ files across multiple directories +- PR introduces new gems, packages, or dependencies +- PR modifies core infrastructure (config, initializers, middleware) +- PR refactors or moves significant code between modules +- PR title/body mentions: refactor, restructure, architecture, reorganize + +**What these agents check:** +- `architecture-strategist`: Evaluates separation of concerns, dependency direction, module boundaries, and long-term maintainability +- `pattern-recognition-specialist`: Identifies recurring anti-patterns, code duplication across the PR, and violations of established project patterns + +--- + +**DATA: If PR contains model or data-related changes:** + +From `conditionalAgents.data` in config (defaults: `data-integrity-guardian`) + +- Task data-integrity-guardian(PR content) - Reviews data integrity, validation, and query safety + +**When to run data agents:** +- PR includes files matching `app/models/*.rb`, `app/models/**/*.rb` +- PR includes concerns in `app/models/concerns/**` +- PR modifies ActiveRecord associations, validations, or callbacks +- PR includes changes to database queries or scopes +- PR modifies serializers, decorators, or data transformation logic +- PR title/body mentions: model, validation, association, query optimization + +**What these agents check:** +- `data-integrity-guardian`: Validates referential integrity, N+1 query risks, proper use of transactions, data consistency across associations, and safe handling of nullable fields + ### 4. Ultra-Thinking Deep Dive Phases @@ -367,12 +477,8 @@ After creating all todo files, present comprehensive summary: ### Review Agents Used: -- kieran-rails-reviewer -- security-sentinel -- performance-oracle -- architecture-strategist -- agent-native-reviewer -- [other agents] +- {List agents from config or defaults used} +- (configured via `.claude/compound-engineering.json`) ### Next Steps: diff --git a/plugins/compound-engineering/commands/workflows/work.md b/plugins/compound-engineering/commands/workflows/work.md index 36f95ae..814aaf0 100644 --- a/plugins/compound-engineering/commands/workflows/work.md +++ b/plugins/compound-engineering/commands/workflows/work.md @@ -175,19 +175,34 @@ This command takes a work document (plan, specification, or todo file) and execu 2. **Consider Reviewer Agents** (Optional) - Use for complex, risky, or large changes: + Use for complex, risky, or large changes. Agents are configured via `.claude/compound-engineering.json`. - - **code-simplicity-reviewer**: Check for unnecessary complexity - - **kieran-rails-reviewer**: Verify Rails conventions (Rails projects) - - **performance-oracle**: Check for performance issues - - **security-sentinel**: Scan for security vulnerabilities - - **cora-test-reviewer**: Review test quality (Rails projects with comprehensive test coverage) + **If config exists:** Use agents from `reviewAgents` array. + + **If no config exists and user wants reviewers:** + ``` + AskUserQuestion: + questions: + - question: "No config found. Set up review agents now?" + header: "Setup" + options: + - label: "Quick Setup (Recommended)" + description: "Create config with smart defaults for your project type" + - label: "Skip - Use defaults this time" + description: "Use general defaults without saving" + ``` + + **Default agents by project type:** + - **Rails**: `kieran-rails-reviewer`, `code-simplicity-reviewer` + - **Python**: `kieran-python-reviewer`, `code-simplicity-reviewer` + - **TypeScript**: `kieran-typescript-reviewer`, `code-simplicity-reviewer` + - **General**: `code-simplicity-reviewer`, `security-sentinel` Run reviewers in parallel with Task tool: ``` - Task(code-simplicity-reviewer): "Review changes for simplicity" - Task(kieran-rails-reviewer): "Check Rails conventions" + Task({configured-agent}): "Review changes" + Task(code-simplicity-reviewer): "Review for simplicity" ``` Present findings to user and address critical issues.