From f79f5b94fa15a14294bfff46066fcc1598075cc1 Mon Sep 17 00:00:00 2001 From: Kieran Klaassen Date: Sun, 25 Jan 2026 23:13:55 -0500 Subject: [PATCH 1/7] 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/7] 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/7] 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/7] 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/7] 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/7] 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. From 045c2795a1b079718c9130a591314f71b560c4e5 Mon Sep 17 00:00:00 2001 From: Kieran Klaassen Date: Wed, 28 Jan 2026 06:04:00 -0800 Subject: [PATCH 7/7] [2.29.1] Improve /workflows:brainstorm question flow - Add "Ask more questions" option at handoff phase - Clarify that Claude should ask the user questions (not wait for user) - Require resolving ALL open questions before offering to proceed Co-Authored-By: Claude Opus 4.5 --- .../compound-engineering/.claude-plugin/plugin.json | 2 +- plugins/compound-engineering/CHANGELOG.md | 11 +++++++++++ .../commands/workflows/brainstorm.md | 9 +++++++-- 3 files changed, 19 insertions(+), 3 deletions(-) diff --git a/plugins/compound-engineering/.claude-plugin/plugin.json b/plugins/compound-engineering/.claude-plugin/plugin.json index a9f29f92..20f67369 100644 --- a/plugins/compound-engineering/.claude-plugin/plugin.json +++ b/plugins/compound-engineering/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "compound-engineering", - "version": "2.29.0", + "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", diff --git a/plugins/compound-engineering/CHANGELOG.md b/plugins/compound-engineering/CHANGELOG.md index 06dd4a64..0d7cdcc5 100644 --- a/plugins/compound-engineering/CHANGELOG.md +++ b/plugins/compound-engineering/CHANGELOG.md @@ -5,6 +5,17 @@ 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 diff --git a/plugins/compound-engineering/commands/workflows/brainstorm.md b/plugins/compound-engineering/commands/workflows/brainstorm.md index 3cb204d7..578eba62 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