From f79f5b94fa15a14294bfff46066fcc1598075cc1 Mon Sep 17 00:00:00 2001 From: Kieran Klaassen Date: Sun, 25 Jan 2026 23:13:55 -0500 Subject: [PATCH 1/6] feat(commands): add /compound-engineering-setup for configurable agents MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a new setup command that allows users to configure which review agents to use instead of hardcoding them in workflows. This enables: - Multi-step onboarding with AskUserQuestion for easy setup - Auto-detection of project type (Rails, Python, TypeScript, etc.) - Three setup modes: Quick (smart defaults), Advanced, and Minimal - Configuration stored in .claude/compound-engineering.json - Support for both global (~/.claude/) and project-specific config Updated workflows to read from config: - /workflows:review - reads reviewAgents from config - /plan_review - reads planReviewAgents from config - /workflows:work - references config for reviewer agents - /workflows:compound - references config for specialized agents πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .claude-plugin/marketplace.json | 4 +- .../.claude-plugin/plugin.json | 4 +- plugins/compound-engineering/CHANGELOG.md | 35 ++ plugins/compound-engineering/README.md | 7 +- .../commands/plan_review.md | 60 ++- .../compound-engineering/commands/setup.md | 456 ++++++++++++++++++ .../commands/workflows/compound.md | 27 +- .../commands/workflows/review.md | 67 ++- .../commands/workflows/work.md | 20 +- 9 files changed, 631 insertions(+), 49 deletions(-) create mode 100644 plugins/compound-engineering/commands/setup.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 4e22718b..d4cf1dc4 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 97ea7426..a9f29f92 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.0", + "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 dd1c7f9e..c8d162c0 100644 --- a/plugins/compound-engineering/CHANGELOG.md +++ b/plugins/compound-engineering/CHANGELOG.md @@ -5,6 +5,41 @@ 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.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/`) + +### 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 +{ + "projectType": "rails", + "reviewAgents": ["kieran-rails-reviewer", "code-simplicity-reviewer", "security-sentinel"], + "planReviewAgents": ["kieran-rails-reviewer", "code-simplicity-reviewer"], + "conditionalAgents": { + "migrations": ["data-migration-expert", "deployment-verification-agent"], + "frontend": ["julik-frontend-races-reviewer"] + } +} +``` + +--- + ## [2.28.0] - 2026-01-21 ### Added diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index b1a710d3..9660ad8d 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 70ef5ddc..feeb0b04 100644 --- a/plugins/compound-engineering/commands/plan_review.md +++ b/plugins/compound-engineering/commands/plan_review.md @@ -4,4 +4,62 @@ 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 + + + +Check for configuration file: + +```bash +# Check project config first, then global +if [ -f .claude/compound-engineering.json ]; then + CONFIG_FILE=".claude/compound-engineering.json" +elif [ -f ~/.claude/compound-engineering.json ]; then + CONFIG_FILE="~/.claude/compound-engineering.json" +else + CONFIG_FILE="" +fi +``` + +**If config exists:** Read `planReviewAgents` array from the config file. + +**If no config exists:** Use these defaults: +- `code-simplicity-reviewer` +- `architecture-strategist` + +Or prompt: "No configuration found. Run `/compound-engineering-setup` to configure agents, or use defaults?" + + + +## 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 00000000..f417cade --- /dev/null +++ b/plugins/compound-engineering/commands/setup.md @@ -0,0 +1,456 @@ +--- +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. + +## Detect Configuration Location + + + +Check if user passed `--global` argument: +- **If `--global`**: Configure at `~/.claude/compound-engineering.json` (applies to all projects) +- **Otherwise**: Configure at `.claude/compound-engineering.json` (project-specific) + +Check if configuration already exists: +```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" +``` + +If config exists, offer to edit existing or start fresh. + + + +## Step 1: Detect Project Type + + + +Detect the primary language/framework automatically: + +```bash +# Check for common project indicators +ls -la Gemfile package.json requirements.txt pyproject.toml Cargo.toml go.mod pom.xml 2>/dev/null +ls -la *.xcodeproj *.xcworkspace Package.swift 2>/dev/null +``` + +**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** +- `*.xcodeproj` OR `Package.swift` β†’ **Swift/iOS** +- None of the above β†’ **General** + +Store detected type for recommendations. + + + +## Step 2: Quick vs Advanced Setup + + + +Use AskUserQuestion to determine setup mode: + +``` +AskUserQuestion: + questions: + - question: "How would you like to configure compound-engineering?" + header: "Setup mode" + options: + - label: "Quick Setup (Recommended)" + description: "Use smart defaults based on your project type. Best for most users." + - label: "Advanced Setup" + description: "Manually select each agent and configure options. For power users." + - label: "Minimal Setup" + description: "Only essential agents (security + code quality). Fastest reviews." +``` + + + +## Step 3A: Quick Setup Flow + + + +If user chose "Quick Setup": + +### Rails Projects +Default config: +```json +{ + "projectType": "rails", + "reviewAgents": [ + "kieran-rails-reviewer", + "dhh-rails-reviewer", + "code-simplicity-reviewer", + "security-sentinel", + "performance-oracle" + ], + "planReviewAgents": [ + "kieran-rails-reviewer", + "code-simplicity-reviewer" + ], + "conditionalAgents": { + "migrations": ["data-migration-expert", "deployment-verification-agent"], + "frontend": ["julik-frontend-races-reviewer"], + "architecture": ["architecture-strategist", "pattern-recognition-specialist"] + } +} +``` + +### Python Projects +Default config: +```json +{ + "projectType": "python", + "reviewAgents": [ + "kieran-python-reviewer", + "code-simplicity-reviewer", + "security-sentinel", + "performance-oracle" + ], + "planReviewAgents": [ + "kieran-python-reviewer", + "code-simplicity-reviewer" + ], + "conditionalAgents": { + "architecture": ["architecture-strategist", "pattern-recognition-specialist"] + } +} +``` + +### TypeScript Projects +Default config: +```json +{ + "projectType": "typescript", + "reviewAgents": [ + "kieran-typescript-reviewer", + "code-simplicity-reviewer", + "security-sentinel", + "performance-oracle" + ], + "planReviewAgents": [ + "kieran-typescript-reviewer", + "code-simplicity-reviewer" + ], + "conditionalAgents": { + "frontend": ["julik-frontend-races-reviewer"], + "architecture": ["architecture-strategist", "pattern-recognition-specialist"] + } +} +``` + +### General/Other Projects +Default config: +```json +{ + "projectType": "general", + "reviewAgents": [ + "code-simplicity-reviewer", + "security-sentinel", + "performance-oracle" + ], + "planReviewAgents": [ + "code-simplicity-reviewer" + ], + "conditionalAgents": { + "architecture": ["architecture-strategist", "pattern-recognition-specialist"] + } +} +``` + + + +## Step 3B: Advanced Setup Flow + + + +If user chose "Advanced Setup", walk through each category: + +### Question 1: Primary Code Review Agents + +``` +AskUserQuestion: + questions: + - question: "Which code review agents should run on every PR?" + header: "Review agents" + multiSelect: true + options: + - label: "kieran-rails-reviewer" + description: "Rails conventions, naming, clarity (Rails projects)" + - 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 from DHH's perspective" +``` + +### Question 2: Quality & Security Agents + +``` +AskUserQuestion: + questions: + - question: "Which quality and security agents should run?" + header: "Quality agents" + 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: "architecture-strategist" + description: "Architectural patterns and design decisions" +``` + +### Question 3: Plan Review Agents + +``` +AskUserQuestion: + questions: + - question: "Which agents should review implementation plans?" + header: "Plan reviewers" + multiSelect: true + options: + - label: "Use same as code review (Recommended)" + description: "Reuse your code review agent selection" + - label: "code-simplicity-reviewer only" + description: "Lightweight plan reviews focused on simplicity" + - label: "Custom selection" + description: "Choose specific agents for plan reviews" +``` + +### Question 4: Conditional Agents + +``` +AskUserQuestion: + questions: + - question: "Enable conditional agents that run based on file changes?" + header: "Smart agents" + multiSelect: true + options: + - label: "Migration agents (Recommended)" + description: "data-migration-expert + deployment-verification for DB changes" + - label: "Frontend agents" + description: "julik-frontend-races-reviewer for JS/Stimulus code" + - label: "Architecture agents" + description: "pattern-recognition-specialist for structural changes" + - label: "None" + description: "Only run configured review agents" +``` + + + +## Step 3C: Minimal Setup Flow + + + +If user chose "Minimal Setup": + +```json +{ + "projectType": "{detected}", + "reviewAgents": [ + "code-simplicity-reviewer", + "security-sentinel" + ], + "planReviewAgents": [ + "code-simplicity-reviewer" + ], + "conditionalAgents": {} +} +``` + + + +## Step 4: Additional Options + + + +For all setup modes, ask: + +``` +AskUserQuestion: + questions: + - question: "Include agent-native-reviewer to verify features are accessible to AI agents?" + header: "Agent-native" + options: + - label: "Yes (Recommended)" + description: "Ensures new features can be used by Claude and other AI tools" + - label: "No" + description: "Skip agent accessibility checks" +``` + +If "Yes", add `"agent-native-reviewer"` to reviewAgents. + + + +## Step 5: Write Configuration + + + +Create the configuration file: + +```bash +# Ensure .claude directory exists +mkdir -p .claude + +# Write configuration (or to ~/.claude/ if --global) +``` + +Write the JSON configuration: + +```json +{ + "$schema": "https://raw.githubusercontent.com/EveryInc/compound-engineering-plugin/main/schemas/compound-engineering.schema.json", + "version": "1.0", + "projectType": "{detected_type}", + "reviewAgents": [ + // Selected agents + ], + "planReviewAgents": [ + // Selected agents + ], + "conditionalAgents": { + "migrations": ["data-migration-expert", "deployment-verification-agent"], + "frontend": ["julik-frontend-races-reviewer"], + "architecture": ["architecture-strategist", "pattern-recognition-specialist"] + }, + "options": { + "agentNative": true, + "parallelReviews": true + } +} +``` + + + +## Step 6: Confirm and Summarize + + + +Present the configuration summary: + +```markdown +## Configuration Complete + +**Location:** `.claude/compound-engineering.json` +**Project Type:** {type} + +### Review Agents (run on every PR) +- {agent1} +- {agent2} +- ... + +### Plan Review Agents +- {agent1} +- ... + +### Conditional Agents +- **Migrations:** {agents or "disabled"} +- **Frontend:** {agents or "disabled"} +- **Architecture:** {agents or "disabled"} + +### Options +- Agent-native reviews: {enabled/disabled} +- Parallel reviews: {enabled/disabled} + +--- + +**Next steps:** +1. Run `/workflows:review` to test your configuration +2. Run `/compound-engineering-setup` again to modify settings +3. Commit `.claude/compound-engineering.json` to share with your team +``` + + + +## Configuration File Reference + + + +### Full Schema + +```json +{ + "$schema": "https://raw.githubusercontent.com/EveryInc/compound-engineering-plugin/main/schemas/compound-engineering.schema.json", + "version": "1.0", + "projectType": "rails|python|typescript|javascript|rust|go|swift|general", + + "reviewAgents": [ + "kieran-rails-reviewer", + "dhh-rails-reviewer", + "code-simplicity-reviewer", + "security-sentinel", + "performance-oracle" + ], + + "planReviewAgents": [ + "kieran-rails-reviewer", + "code-simplicity-reviewer" + ], + + "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, + "autoFix": false + } +} +``` + +### Available 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 + +**Specialized:** +- `data-migration-expert` - Database migration safety +- `deployment-verification-agent` - Deployment checklists +- `data-integrity-guardian` - Data model integrity +- `julik-frontend-races-reviewer` - JavaScript race conditions +- `agent-native-reviewer` - AI accessibility + + + +## Fallback Behavior + + + +If no configuration file exists when running `/workflows:review` or `/plan_review`: + +1. Check for `.claude/compound-engineering.json` +2. Check for `~/.claude/compound-engineering.json` +3. If neither exists, prompt: "No configuration found. Run `/compound-engineering-setup` to configure agents, or use defaults?" +4. If user chooses defaults, use the General project defaults + + diff --git a/plugins/compound-engineering/commands/workflows/compound.md b/plugins/compound-engineering/commands/workflows/compound.md index 40426855..c5b4a2ab 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 282c9f0a..6fdaa59c 100644 --- a/plugins/compound-engineering/commands/workflows/review.md +++ b/plugins/compound-engineering/commands/workflows/review.md @@ -48,25 +48,54 @@ Ensure that the code is ready for analysis (either in worktree or on current bra +#### Load Review Configuration + + + +Check for configuration file: + +```bash +# Check project config first, then global +if [ -f .claude/compound-engineering.json ]; then + CONFIG_FILE=".claude/compound-engineering.json" +elif [ -f ~/.claude/compound-engineering.json ]; then + CONFIG_FILE="~/.claude/compound-engineering.json" +else + CONFIG_FILE="" +fi +``` + +**If config exists:** Read agents from the configuration: +- `reviewAgents` - Primary agents to run on every PR +- `conditionalAgents` - Agents triggered by file patterns +- `options.agentNative` - Whether to include agent-native-reviewer + +**If no config exists:** Prompt user: +> "No configuration found. Run `/compound-engineering-setup` to configure agents, or use defaults for this review?" + + + #### 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 @@ -367,12 +396,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 36f95ae7..d92bda68 100644 --- a/plugins/compound-engineering/commands/workflows/work.md +++ b/plugins/compound-engineering/commands/workflows/work.md @@ -175,21 +175,25 @@ 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:** Use these defaults based on 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" ``` + **Tip:** Run `/compound-engineering-setup` to configure your preferred review agents. + Present findings to user and address critical issues. 3. **Final Validation** From 304c58d2174948d7a8535537965a12153c2bffe8 Mon Sep 17 00:00:00 2001 From: Kieran Klaassen Date: Sun, 25 Jan 2026 23:15:32 -0500 Subject: [PATCH 2/6] feat: auto-trigger setup when no config exists Workflows now detect missing config and offer inline quick setup: - "Quick Setup" - auto-detect project type, create config, continue - "Full Setup" - run /compound-engineering-setup for customization - "Skip" - use defaults just this once This ensures users get onboarded automatically when running any workflow for the first time, without needing to know about the setup command beforehand. Co-Authored-By: Claude Opus 4.5 --- .../commands/plan_review.md | 46 +++++++++++------ .../commands/workflows/review.md | 49 +++++++++++++------ .../commands/workflows/work.md | 17 +++++-- 3 files changed, 79 insertions(+), 33 deletions(-) diff --git a/plugins/compound-engineering/commands/plan_review.md b/plugins/compound-engineering/commands/plan_review.md index feeb0b04..4f739ca3 100644 --- a/plugins/compound-engineering/commands/plan_review.md +++ b/plugins/compound-engineering/commands/plan_review.md @@ -8,30 +8,46 @@ argument-hint: "[plan file path or plan content]" Review a plan using configured agents from `.claude/compound-engineering.json`. -## Load Configuration +## Load Configuration (Auto-Setup if Missing) -Check for configuration file: +**Step 1: Check for configuration file:** ```bash -# Check project config first, then global -if [ -f .claude/compound-engineering.json ]; then - CONFIG_FILE=".claude/compound-engineering.json" -elif [ -f ~/.claude/compound-engineering.json ]; then - CONFIG_FILE="~/.claude/compound-engineering.json" -else - CONFIG_FILE="" -fi +test -f .claude/compound-engineering.json && echo "project" || \ +test -f ~/.claude/compound-engineering.json && echo "global" || echo "none" ``` -**If config exists:** Read `planReviewAgents` array from the config file. +**Step 2: If config exists** β†’ Read `planReviewAgents` array and proceed. -**If no config exists:** Use these defaults: -- `code-simplicity-reviewer` -- `architecture-strategist` +**Step 3: If NO config exists** β†’ Run inline quick setup: -Or prompt: "No configuration found. Run `/compound-engineering-setup` to configure agents, or use defaults?" +``` +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` diff --git a/plugins/compound-engineering/commands/workflows/review.md b/plugins/compound-engineering/commands/workflows/review.md index 6fdaa59c..063f5424 100644 --- a/plugins/compound-engineering/commands/workflows/review.md +++ b/plugins/compound-engineering/commands/workflows/review.md @@ -48,30 +48,49 @@ Ensure that the code is ready for analysis (either in worktree or on current bra -#### Load Review Configuration +#### Load Review Configuration (Auto-Setup if Missing) -Check for configuration file: +**Step 1: Check for configuration file:** ```bash # Check project config first, then global -if [ -f .claude/compound-engineering.json ]; then - CONFIG_FILE=".claude/compound-engineering.json" -elif [ -f ~/.claude/compound-engineering.json ]; then - CONFIG_FILE="~/.claude/compound-engineering.json" -else - CONFIG_FILE="" -fi +test -f .claude/compound-engineering.json && echo "project" || \ +test -f ~/.claude/compound-engineering.json && echo "global" || echo "none" ``` -**If config exists:** Read agents from the configuration: -- `reviewAgents` - Primary agents to run on every PR -- `conditionalAgents` - Agents triggered by file patterns -- `options.agentNative` - Whether to include agent-native-reviewer +**Step 2: If config exists** β†’ Read agents from configuration and proceed. -**If no config exists:** Prompt user: -> "No configuration found. Run `/compound-engineering-setup` to configure agents, or use defaults for this review?" +**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 diff --git a/plugins/compound-engineering/commands/workflows/work.md b/plugins/compound-engineering/commands/workflows/work.md index d92bda68..814aaf08 100644 --- a/plugins/compound-engineering/commands/workflows/work.md +++ b/plugins/compound-engineering/commands/workflows/work.md @@ -179,7 +179,20 @@ This command takes a work document (plan, specification, or todo file) and execu **If config exists:** Use agents from `reviewAgents` array. - **If no config:** Use these defaults based on project type: + **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` @@ -192,8 +205,6 @@ This command takes a work document (plan, specification, or todo file) and execu Task(code-simplicity-reviewer): "Review for simplicity" ``` - **Tip:** Run `/compound-engineering-setup` to configure your preferred review agents. - Present findings to user and address critical issues. 3. **Final Validation** From 898604c019cc03a12de310c59a83c1321b43bdac Mon Sep 17 00:00:00 2001 From: Kieran Klaassen Date: Sun, 25 Jan 2026 23:28:52 -0500 Subject: [PATCH 3/6] feat(review): wire all conditionalAgents categories Extended /workflows:review to invoke conditional agents for: - migrations (existing) - frontend (new): JS/TS/Stimulus changes - architecture (new): structural changes, 10+ files - data (new): model/ActiveRecord changes Each category reads from conditionalAgents.* config key and runs appropriate specialized agents when file patterns match. Resolves: todos/001-ready-p2-conditional-agents-not-invoked.md Co-Authored-By: Claude Opus 4.5 --- .../commands/workflows/review.md | 68 ++++++++++++++++++- 1 file changed, 65 insertions(+), 3 deletions(-) diff --git a/plugins/compound-engineering/commands/workflows/review.md b/plugins/compound-engineering/commands/workflows/review.md index 063f5424..16feebc6 100644 --- a/plugins/compound-engineering/commands/workflows/review.md +++ b/plugins/compound-engineering/commands/workflows/review.md @@ -124,10 +124,14 @@ Run all configured review agents in parallel. Example defaults: 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:** -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 +From `conditionalAgents.migrations` in config (defaults: `data-migration-expert`, `deployment-verification-agent`) + +- 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` @@ -140,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 From 246823a1b400917b1f4b98a12f63b04644e35f9b Mon Sep 17 00:00:00 2001 From: Kieran Klaassen Date: Sun, 25 Jan 2026 23:29:08 -0500 Subject: [PATCH 4/6] chore: mark todo #001 as complete --- ...plete-p2-conditional-agents-not-invoked.md | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 todos/001-complete-p2-conditional-agents-not-invoked.md diff --git a/todos/001-complete-p2-conditional-agents-not-invoked.md b/todos/001-complete-p2-conditional-agents-not-invoked.md new file mode 100644 index 00000000..a308ea4f --- /dev/null +++ b/todos/001-complete-p2-conditional-agents-not-invoked.md @@ -0,0 +1,91 @@ +--- +status: complete +priority: p2 +issue_id: "001" +tags: [code-review, architecture, quality, docs] +dependencies: [] +--- + +# Wire conditionalAgents into /workflows:review + +## Problem Statement + +The new setup command defines `conditionalAgents` (frontend, architecture, data), but `/workflows:review` only references migrations and ignores other conditional categories. This creates a configuration contract that is not actually executed during reviews. + +## Findings + +- `plugins/compound-engineering/commands/setup.md` introduces `conditionalAgents` keys beyond migrations. +- `plugins/compound-engineering/commands/workflows/review.md` contains no logic that reads or runs non-migration conditional agents. +- Result: users can configure conditional agents that never run. + +## Proposed Solutions + +### Option 1: Add explicit conditional agent rules to review workflow + +**Approach:** Extend `/workflows:review` with conditional checks for frontend, architecture, and data changes, then invoke configured agents. + +**Pros:** +- Aligns behavior with the new configuration surface. +- Preserves the documented β€œsmart agents” promise. + +**Cons:** +- Adds more workflow logic to maintain. + +**Effort:** Medium + +**Risk:** Low + +--- + +### Option 2: Restrict config to migrations only + +**Approach:** Remove non-migration categories from setup defaults and docs until the workflow supports them. + +**Pros:** +- Minimal change. +- Prevents misleading configuration. + +**Cons:** +- Reduces flexibility and value of the new setup command. + +**Effort:** Small + +**Risk:** Low + +--- + +### Option 3: Document non-migration conditionals as future/optional + +**Approach:** Keep config shape but explicitly mark non-migration categories as not yet wired. + +**Pros:** +- Sets correct expectations quickly. + +**Cons:** +- Still leaves dead config keys. + +**Effort:** Small + +**Risk:** Medium + +## Recommended Action + +## Technical Details + +Affected files: +- `plugins/compound-engineering/commands/setup.md` +- `plugins/compound-engineering/commands/workflows/review.md` + +## Resources + +- PR: https://github.com/EveryInc/compound-engineering-plugin/pull/124 + +## Acceptance Criteria + +- [ ] `/workflows:review` invokes configured conditional agents beyond migrations, or docs/config are narrowed to match reality. +- [ ] Behavior is documented with clear, testable trigger rules. + +## Work Log + +- 2026-01-26: Identified config/workflow mismatch during PR #124 review. +- 2026-01-25: **Approved for work** during triage session. Status: pending β†’ ready. From b7db6e71c55988e30bf1f59d35522dbe96623c38 Mon Sep 17 00:00:00 2001 From: Kieran Klaassen Date: Sun, 25 Jan 2026 23:33:36 -0500 Subject: [PATCH 5/6] feat(setup): add custom agent discovery and modify flow - Auto-detect custom agents in .claude/agents/ and ~/.claude/agents/ - Add modify existing config flow (add/remove agents, view config) - Include guide for creating custom review agents - Add customAgents mapping in config to track agent file paths - Update changelog with new config schema including customAgents Co-Authored-By: Claude Opus 4.5 --- plugins/compound-engineering/CHANGELOG.md | 13 +- .../compound-engineering/commands/setup.md | 558 +++++++++--------- 2 files changed, 305 insertions(+), 266 deletions(-) diff --git a/plugins/compound-engineering/CHANGELOG.md b/plugins/compound-engineering/CHANGELOG.md index c8d162c0..06dd4a64 100644 --- a/plugins/compound-engineering/CHANGELOG.md +++ b/plugins/compound-engineering/CHANGELOG.md @@ -15,6 +15,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - 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 @@ -28,12 +31,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 New config file format (`.claude/compound-engineering.json`): ```json { + "version": "1.0", "projectType": "rails", - "reviewAgents": ["kieran-rails-reviewer", "code-simplicity-reviewer", "security-sentinel"], + "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"] + "frontend": ["julik-frontend-races-reviewer"], + "architecture": ["architecture-strategist"], + "data": ["data-integrity-guardian"] } } ``` diff --git a/plugins/compound-engineering/commands/setup.md b/plugins/compound-engineering/commands/setup.md index f417cade..b94e8396 100644 --- a/plugins/compound-engineering/commands/setup.md +++ b/plugins/compound-engineering/commands/setup.md @@ -8,37 +8,93 @@ argument-hint: "[--global to configure globally]" Configure which review agents and workflows to use for this project. Creates a `.claude/compound-engineering.json` configuration file. -## Detect Configuration Location +## Step 0: Detect Existing Config & Custom Agents - + -Check if user passed `--global` argument: -- **If `--global`**: Configure at `~/.claude/compound-engineering.json` (applies to all projects) -- **Otherwise**: Configure at `.claude/compound-engineering.json` (project-specific) +### Check for existing configuration: -Check if configuration already exists: ```bash # Check project config -test -f .claude/compound-engineering.json && echo "Project config exists" +test -f .claude/compound-engineering.json && echo "PROJECT_CONFIG_EXISTS" # Check global config -test -f ~/.claude/compound-engineering.json && echo "Global config exists" +test -f ~/.claude/compound-engineering.json && echo "GLOBAL_CONFIG_EXISTS" ``` -If config exists, offer to edit existing or start fresh. +### 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 +``` -## Step 1: Detect Project Type +**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" +``` - + -Detect the primary language/framework automatically: +## 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 -la Gemfile package.json requirements.txt pyproject.toml Cargo.toml go.mod pom.xml 2>/dev/null -ls -la *.xcodeproj *.xcworkspace Package.swift 2>/dev/null +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:** @@ -49,285 +105,252 @@ ls -la *.xcodeproj *.xcworkspace Package.swift 2>/dev/null - `requirements.txt` OR `pyproject.toml` β†’ **Python** - `Cargo.toml` β†’ **Rust** - `go.mod` β†’ **Go** -- `*.xcodeproj` OR `Package.swift` β†’ **Swift/iOS** -- None of the above β†’ **General** - -Store detected type for recommendations. - - +- None β†’ **General** -## Step 2: Quick vs Advanced Setup - - - -Use AskUserQuestion to determine setup mode: +### Choose Setup Mode ``` AskUserQuestion: questions: - - question: "How would you like to configure compound-engineering?" + - question: "How would you like to configure review agents?" header: "Setup mode" options: - label: "Quick Setup (Recommended)" - description: "Use smart defaults based on your project type. Best for most users." + description: "Smart defaults for {detected_type} + any custom agents found" - label: "Advanced Setup" - description: "Manually select each agent and configure options. For power users." + description: "Manually select each agent including custom ones" - label: "Minimal Setup" - description: "Only essential agents (security + code quality). Fastest reviews." + description: "Only essential agents (security + simplicity)" ``` - +### Quick Setup - Apply Defaults + Custom Agents -## Step 3A: Quick Setup Flow +**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 user chose "Quick Setup": +**If custom agents were discovered:** -### Rails Projects -Default config: -```json -{ - "projectType": "rails", - "reviewAgents": [ - "kieran-rails-reviewer", - "dhh-rails-reviewer", - "code-simplicity-reviewer", - "security-sentinel", - "performance-oracle" - ], - "planReviewAgents": [ - "kieran-rails-reviewer", - "code-simplicity-reviewer" - ], - "conditionalAgents": { - "migrations": ["data-migration-expert", "deployment-verification-agent"], - "frontend": ["julik-frontend-races-reviewer"], - "architecture": ["architecture-strategist", "pattern-recognition-specialist"] - } -} ``` - -### Python Projects -Default config: -```json -{ - "projectType": "python", - "reviewAgents": [ - "kieran-python-reviewer", - "code-simplicity-reviewer", - "security-sentinel", - "performance-oracle" - ], - "planReviewAgents": [ - "kieran-python-reviewer", - "code-simplicity-reviewer" - ], - "conditionalAgents": { - "architecture": ["architecture-strategist", "pattern-recognition-specialist"] - } -} -``` - -### TypeScript Projects -Default config: -```json -{ - "projectType": "typescript", - "reviewAgents": [ - "kieran-typescript-reviewer", - "code-simplicity-reviewer", - "security-sentinel", - "performance-oracle" - ], - "planReviewAgents": [ - "kieran-typescript-reviewer", - "code-simplicity-reviewer" - ], - "conditionalAgents": { - "frontend": ["julik-frontend-races-reviewer"], - "architecture": ["architecture-strategist", "pattern-recognition-specialist"] - } -} -``` - -### General/Other Projects -Default config: -```json -{ - "projectType": "general", - "reviewAgents": [ - "code-simplicity-reviewer", - "security-sentinel", - "performance-oracle" - ], - "planReviewAgents": [ - "code-simplicity-reviewer" - ], - "conditionalAgents": { - "architecture": ["architecture-strategist", "pattern-recognition-specialist"] - } -} +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" ``` - - -## Step 3B: Advanced Setup Flow - - +Add selected custom agents to `reviewAgents` array. -If user chose "Advanced Setup", walk through each category: +### Advanced Setup - Manual Selection -### Question 1: Primary Code Review Agents +**Question 1: Built-in Review Agents** ``` AskUserQuestion: questions: - - question: "Which code review agents should run on every PR?" - header: "Review agents" + - 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 (Rails projects)" + 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 from DHH's perspective" + description: "Opinionated Rails style" ``` -### Question 2: Quality & Security Agents +**Question 2: Custom Agents (if any discovered)** ``` AskUserQuestion: questions: - - question: "Which quality and security agents should run?" - header: "Quality agents" + - question: "Which of your custom agents should run on every PR?" + header: "Your agents" 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: "architecture-strategist" - description: "Architectural patterns and design decisions" + - label: "{custom_agent_1_name}" + description: "{custom_agent_1_description} ({path})" + - label: "{custom_agent_2_name}" + description: "{custom_agent_2_description} ({path})" ``` -### Question 3: Plan Review Agents +**Question 3: Quality & Security** ``` AskUserQuestion: questions: - - question: "Which agents should review implementation plans?" - header: "Plan reviewers" + - question: "Which quality and security agents should run?" + header: "Quality" multiSelect: true options: - - label: "Use same as code review (Recommended)" - description: "Reuse your code review agent selection" - - label: "code-simplicity-reviewer only" - description: "Lightweight plan reviews focused on simplicity" - - label: "Custom selection" - description: "Choose specific agents for plan reviews" + - 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 +**Question 4: Conditional Agents** ``` AskUserQuestion: questions: - - question: "Enable conditional agents that run based on file changes?" - header: "Smart agents" + - question: "Enable smart agents that run based on what files changed?" + header: "Conditional" multiSelect: true options: - label: "Migration agents (Recommended)" - description: "data-migration-expert + deployment-verification for DB changes" + description: "data-migration-expert for DB changes" - label: "Frontend agents" - description: "julik-frontend-races-reviewer for JS/Stimulus code" + description: "julik-frontend-races-reviewer for JS/TS" - label: "Architecture agents" - description: "pattern-recognition-specialist for structural changes" - - label: "None" - description: "Only run configured review agents" + description: "architecture-strategist for structural changes" + - label: "Data agents" + description: "data-integrity-guardian for model changes" ``` - + -## Step 3C: Minimal Setup Flow +## Step 2B: Modify Existing Config - + -If user chose "Minimal Setup": +Read current configuration and present current state: -```json -{ - "projectType": "{detected}", - "reviewAgents": [ - "code-simplicity-reviewer", - "security-sentinel" - ], - "planReviewAgents": [ - "code-simplicity-reviewer" - ], - "conditionalAgents": {} -} +```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: -## Step 4: Additional Options +``` +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 -For all setup modes, ask: +Show agents currently IN config: ``` AskUserQuestion: questions: - - question: "Include agent-native-reviewer to verify features are accessible to AI agents?" - header: "Agent-native" + - question: "Select agents to REMOVE from your configuration:" + header: "Remove agents" + multiSelect: true options: - - label: "Yes (Recommended)" - description: "Ensures new features can be used by Claude and other AI tools" - - label: "No" - description: "Skip agent accessibility checks" + - label: "kieran-rails-reviewer" + description: "Currently enabled - will be removed" + - label: "security-sentinel" + description: "Currently enabled - will be removed" ``` -If "Yes", add `"agent-native-reviewer"` to reviewAgents. +After each modification, loop back to "What would you like to modify?" until user selects "Done". - + -## Step 5: Write Configuration +## Step 3: Write Configuration -Create the configuration file: +**Determine target path:** +- If `--global`: `~/.claude/compound-engineering.json` +- Otherwise: `.claude/compound-engineering.json` +**Create directory if needed:** ```bash -# Ensure .claude directory exists -mkdir -p .claude - -# Write configuration (or to ~/.claude/ if --global) +mkdir -p .claude # or ~/.claude for global ``` -Write the JSON configuration: +**Write JSON configuration:** ```json { - "$schema": "https://raw.githubusercontent.com/EveryInc/compound-engineering-plugin/main/schemas/compound-engineering.schema.json", "version": "1.0", "projectType": "{detected_type}", "reviewAgents": [ - // Selected agents + "kieran-rails-reviewer", + "code-simplicity-reviewer", + "security-sentinel", + "my-custom-reviewer" ], "planReviewAgents": [ - // Selected agents + "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"] + "architecture": ["architecture-strategist", "pattern-recognition-specialist"], + "data": ["data-integrity-guardian"] }, "options": { "agentNative": true, @@ -336,89 +359,109 @@ Write the JSON configuration: } ``` +**Note:** The `customAgents` object maps custom agent names to their file paths, so workflows know where to find them. + -## Step 6: Confirm and Summarize +## Step 4: Summary -Present the configuration summary: - ```markdown -## Configuration Complete +## Configuration Complete! -**Location:** `.claude/compound-engineering.json` -**Project Type:** {type} +**Saved to:** `.claude/compound-engineering.json` +**Project Type:** Rails ### Review Agents (run on every PR) -- {agent1} -- {agent2} -- ... +**Built-in:** +- kieran-rails-reviewer +- code-simplicity-reviewer +- security-sentinel -### Plan Review Agents -- {agent1} -- ... +**Custom:** +- my-custom-reviewer (.claude/agents/) -### Conditional Agents -- **Migrations:** {agents or "disabled"} -- **Frontend:** {agents or "disabled"} -- **Architecture:** {agents or "disabled"} +### Plan Review Agents +- kieran-rails-reviewer +- code-simplicity-reviewer -### Options -- Agent-native reviews: {enabled/disabled} -- Parallel reviews: {enabled/disabled} +### 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 | --- -**Next steps:** +**What's next:** 1. Run `/workflows:review` to test your configuration -2. Run `/compound-engineering-setup` again to modify settings +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. ``` -## Configuration File Reference +## Creating Custom Agents - + -### Full Schema +To create your own review agent that gets auto-discovered: -```json -{ - "$schema": "https://raw.githubusercontent.com/EveryInc/compound-engineering-plugin/main/schemas/compound-engineering.schema.json", - "version": "1.0", - "projectType": "rails|python|typescript|javascript|rust|go|swift|general", +### 1. Create the agent file - "reviewAgents": [ - "kieran-rails-reviewer", - "dhh-rails-reviewer", - "code-simplicity-reviewer", - "security-sentinel", - "performance-oracle" - ], +**Project-level:** `.claude/agents/my-reviewer.md` +**Global:** `~/.claude/agents/my-reviewer.md` - "planReviewAgents": [ - "kieran-rails-reviewer", - "code-simplicity-reviewer" - ], +### 2. Use this template: - "conditionalAgents": { - "migrations": ["data-migration-expert", "deployment-verification-agent"], - "frontend": ["julik-frontend-races-reviewer"], - "architecture": ["architecture-strategist", "pattern-recognition-specialist"], - "data": ["data-integrity-guardian"] - }, +```markdown +--- +name: my-team-reviewer +description: Reviews code for our team's specific conventions +--- - "options": { - "agentNative": true, - "parallelReviews": true, - "autoFix": false - } -} +# 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. ``` -### Available Agents +### 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 @@ -432,25 +475,12 @@ Present the configuration summary: - `performance-oracle` - Performance optimization - `architecture-strategist` - Architectural patterns - `pattern-recognition-specialist` - Code patterns and anti-patterns +- `agent-native-reviewer` - AI accessibility verification -**Specialized:** +**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 -- `agent-native-reviewer` - AI accessibility - - - -## Fallback Behavior - - - -If no configuration file exists when running `/workflows:review` or `/plan_review`: - -1. Check for `.claude/compound-engineering.json` -2. Check for `~/.claude/compound-engineering.json` -3. If neither exists, prompt: "No configuration found. Run `/compound-engineering-setup` to configure agents, or use defaults?" -4. If user chooses defaults, use the General project defaults - + From a1413c912706d774621d07151f0c02dcdacfb340 Mon Sep 17 00:00:00 2001 From: Kieran Klaassen Date: Sun, 25 Jan 2026 23:42:55 -0500 Subject: [PATCH 6/6] chore: remove completed todos directory Co-Authored-By: Claude Opus 4.5 --- ...plete-p2-conditional-agents-not-invoked.md | 91 ------------------- 1 file changed, 91 deletions(-) delete mode 100644 todos/001-complete-p2-conditional-agents-not-invoked.md diff --git a/todos/001-complete-p2-conditional-agents-not-invoked.md b/todos/001-complete-p2-conditional-agents-not-invoked.md deleted file mode 100644 index a308ea4f..00000000 --- a/todos/001-complete-p2-conditional-agents-not-invoked.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -status: complete -priority: p2 -issue_id: "001" -tags: [code-review, architecture, quality, docs] -dependencies: [] ---- - -# Wire conditionalAgents into /workflows:review - -## Problem Statement - -The new setup command defines `conditionalAgents` (frontend, architecture, data), but `/workflows:review` only references migrations and ignores other conditional categories. This creates a configuration contract that is not actually executed during reviews. - -## Findings - -- `plugins/compound-engineering/commands/setup.md` introduces `conditionalAgents` keys beyond migrations. -- `plugins/compound-engineering/commands/workflows/review.md` contains no logic that reads or runs non-migration conditional agents. -- Result: users can configure conditional agents that never run. - -## Proposed Solutions - -### Option 1: Add explicit conditional agent rules to review workflow - -**Approach:** Extend `/workflows:review` with conditional checks for frontend, architecture, and data changes, then invoke configured agents. - -**Pros:** -- Aligns behavior with the new configuration surface. -- Preserves the documented β€œsmart agents” promise. - -**Cons:** -- Adds more workflow logic to maintain. - -**Effort:** Medium - -**Risk:** Low - ---- - -### Option 2: Restrict config to migrations only - -**Approach:** Remove non-migration categories from setup defaults and docs until the workflow supports them. - -**Pros:** -- Minimal change. -- Prevents misleading configuration. - -**Cons:** -- Reduces flexibility and value of the new setup command. - -**Effort:** Small - -**Risk:** Low - ---- - -### Option 3: Document non-migration conditionals as future/optional - -**Approach:** Keep config shape but explicitly mark non-migration categories as not yet wired. - -**Pros:** -- Sets correct expectations quickly. - -**Cons:** -- Still leaves dead config keys. - -**Effort:** Small - -**Risk:** Medium - -## Recommended Action - -## Technical Details - -Affected files: -- `plugins/compound-engineering/commands/setup.md` -- `plugins/compound-engineering/commands/workflows/review.md` - -## Resources - -- PR: https://github.com/EveryInc/compound-engineering-plugin/pull/124 - -## Acceptance Criteria - -- [ ] `/workflows:review` invokes configured conditional agents beyond migrations, or docs/config are narrowed to match reality. -- [ ] Behavior is documented with clear, testable trigger rules. - -## Work Log - -- 2026-01-26: Identified config/workflow mismatch during PR #124 review. -- 2026-01-25: **Approved for work** during triage session. Status: pending β†’ ready.