Add configurable review agents via setup skill and compound-engineering.local.md (#124)

* feat(commands): add /compound-engineering-setup for configurable agents

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 <noreply@anthropic.com>

* 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 <noreply@anthropic.com>

* 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 <noreply@anthropic.com>

* chore: mark todo #001 as complete

* 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 <noreply@anthropic.com>

* chore: remove completed todos directory

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* [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 <noreply@anthropic.com>

* Simplify plugin settings: replace 486-line wizard with .local.md pattern

- Rewrite setup.md (486 → 95 lines): detect project type, create
  .claude/compound-engineering.local.md with smart defaults
- Make review.md and work.md config-aware: read agents from .local.md
  frontmatter, fall back to auto-detected defaults
- Wire schema-drift-detector into review.md migrations conditional block
- Delete technical_review.md (duplicated /plan_review)
- Add disable-model-invocation to setup.md
- Bump to v2.32.0

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Rewrite .claude/ paths for OpenCode/Codex targets, add npm publish workflow

- Converters now rewrite .claude/ → .opencode/ (OpenCode) and .codex/ (Codex)
  in command bodies and agent bodies so .local.md settings work cross-platform
- Apply transformContentForCodex to agent bodies (was only commands before)
- Add GitHub Action to auto-publish to npm on version bump merge to main
- Bump to v0.4.0

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(workflows-work): require post-deploy monitoring section

Add a mandatory Post-Deploy Monitoring & Validation section to the /workflows:work PR template, include no-impact fallback guidance, and enforce it in the quality checklist.

* Add learnings-researcher to review workflow, fix docs site counts

- Add learnings-researcher as parallel agent #14 in /workflows:review
  so past solutions from docs/solutions/ are surfaced during code review
- Make /release-docs command invocable (remove disable-model-invocation)
- Fix stale counts across docs site (agents 28→29, commands 19→24,
  skills 15→18, MCP servers 2→1)
- Bump version to 2.32.1

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Move /release-docs to local .claude/commands/, bump to 2.32.2

Repo maintenance command doesn't need to be distributed to plugin users.
Update command count 24 → 23 across plugin.json, marketplace.json, and docs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Move settings to project root: compound-engineering.local.md

Tool-agnostic location — works for Claude, Codex, OpenCode without
path rewriting. No global fallback, just project root.

Update commands (setup, review, work) and converter tests.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Make /compound-engineering-setup interactive with auto-detect fast path

Two paths: "Auto-configure" (one click, smart defaults) or "Customize"
(pick stack, focus areas, review depth). Uses AskUserQuestion throughout.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Replace /compound-engineering-setup command with setup skill

Setup is now a skill invoked on-demand when compound-engineering.local.md
doesn't exist. Review and work commands just say "invoke the setup skill"
instead of inlining the full setup flow.

- Remove commands/setup.md (command)
- Add skills/setup/SKILL.md (skill with interactive AskUserQuestion flow)
- Simplify review.md and work.md to reference the skill
- Counts: 29 agents, 22 commands, 19 skills

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Prepare v2.33.0 release: setup skill, configurable review agents

- Bump version to 2.33.0
- Consolidate CHANGELOG entries for this branch
- Fix README: update counts (29/22/19), add setup + resolve-pr-parallel skills
- Remove stale /compound-engineering-setup command reference

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

plugins/compound-engineering/commands/workflows/brainstorm.md

@@ -78,6 +78,8 @@ Write a brainstorm document to `docs/brainstorms/YYYY-MM-DD-<topic>-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:
@@ -87,7 +89,10 @@ Use **AskUserQuestion tool** to present next steps:
 **Options:**
 1. **Review and refine** - Improve the document through structured self-review
 2. **Proceed to planning** - Run `/workflows:plan` (will auto-detect this brainstorm)
-3. **Done for now** - Return later
+3. **Ask more questions** - I have more questions to clarify before moving on
+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.
 
 **If user selects "Review and refine":**
 

plugins/compound-engineering/commands/workflows/compound.md

@@ -232,6 +232,7 @@ Based on problem type, these agents can enhance documentation:
 ### When to Invoke
 - **Auto-triggered** (optional): Agents can run post-documentation for enhancement
 - **Manual trigger**: User can invoke agents after /workflows:compound completes for deeper review
+- **Customize agents**: Edit `compound-engineering.local.md` or invoke the `setup` skill to configure which review agents are used across all workflows
 
 ## Related Commands
 

plugins/compound-engineering/commands/workflows/review.md

@@ -59,25 +59,25 @@ The following paths are compound-engineering pipeline artifacts and must never b
 If a review agent flags any file in these directories for cleanup or removal, discard that finding during synthesis. Do not create a todo for it.
 </protected_artifacts>
 
+#### Load Review Agents
+
+Read `compound-engineering.local.md` in the project root. If found, use `review_agents` from YAML frontmatter. If the markdown body contains review context, pass it to each agent as additional instructions.
+
+If no settings file exists, invoke the `setup` skill to create one. Then read the newly created file and continue.
+
 #### Parallel Agents to review the PR:
 
 <parallel_tasks>
 
-Run ALL or most of these agents at the same time:
+Run all configured review agents in parallel using Task tool. For each agent in the `review_agents` list:
 
-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
+```
+Task {agent-name}(PR content + review context from settings body)
+```
+
+Additionally, always run these regardless of settings:
+- Task agent-native-reviewer(PR content) - Verify new features are agent-accessible
+- Task learnings-researcher(PR content) - Search docs/solutions/ for past issues related to this PR's modules and patterns
 
 </parallel_tasks>
 
@@ -87,19 +87,20 @@ Run ALL or most of these agents at the same time:
 
 These agents are run ONLY when the PR matches specific criteria. Check the PR files list to determine if they apply:
 
-**If PR contains database migrations (db/migrate/*.rb files) or data backfills:**
+**MIGRATIONS: If PR contains database migrations, schema.rb, 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
+- Task schema-drift-detector(PR content) - Detects unrelated schema.rb changes by cross-referencing against included migrations (run FIRST)
+- 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`
+**When to run:**
+- PR includes files matching `db/migrate/*.rb` or `db/schema.rb`
 - PR modifies columns that store IDs, enums, or mappings
 - PR includes data backfill scripts or rake tasks
-- PR changes how data is read/written (e.g., changing from FK to string column)
 - PR title/body mentions: migration, backfill, data transformation, ID mapping
 
 **What these agents check:**
+- `schema-drift-detector`: Cross-references schema.rb changes against PR migrations to catch unrelated columns/indexes from local database state
 - `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
 
@@ -218,6 +219,7 @@ Remove duplicates, prioritize by severity and impact.
 <synthesis_tasks>
 
 - [ ] Collect findings from all parallel agents
+- [ ] Surface learnings-researcher results: if past solutions are relevant, flag them as "Known Pattern" with links to docs/solutions/ files
 - [ ] Discard any findings that recommend deleting or gitignoring files in `docs/plans/` or `docs/solutions/` (see Protected Artifacts above)
 - [ ] Categorize by type: security, performance, architecture, quality, etc.
 - [ ] Assign severity levels: 🔴 CRITICAL (P1), 🟡 IMPORTANT (P2), 🔵 NICE-TO-HAVE (P3)

plugins/compound-engineering/commands/workflows/work.md

@@ -175,22 +175,9 @@ 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. Read agents from `compound-engineering.local.md` frontmatter (`review_agents`). If no settings file, invoke the `setup` skill to create one.
 
-   - **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)
-
-   Run reviewers in parallel with Task tool:
-
-   ```
-   Task(code-simplicity-reviewer): "Review changes for simplicity"
-   Task(kieran-rails-reviewer): "Check Rails conventions"
-   ```
-
-   Present findings to user and address critical issues.
+   Run configured agents in parallel with Task tool. Present findings and address critical issues.
 
 3. **Final Validation**
    - All TodoWrite tasks marked completed
@@ -200,6 +187,16 @@ This command takes a work document (plan, specification, or todo file) and execu
    - Figma designs match (if applicable)
    - No console errors or warnings
 
+4. **Prepare Operational Validation Plan** (REQUIRED)
+   - Add a `## Post-Deploy Monitoring & Validation` section to the PR description for every change.
+   - Include concrete:
+     - Log queries/search terms
+     - Metrics or dashboards to watch
+     - Expected healthy signals
+     - Failure signals and rollback/mitigation trigger
+     - Validation window and owner
+   - If there is truly no production/runtime impact, still include the section with: `No additional operational monitoring required` and a one-line reason.
+
 ### Phase 4: Ship It
 
 1. **Create Commit**
@@ -269,6 +266,22 @@ This command takes a work document (plan, specification, or todo file) and execu
    - Tests added/modified
    - Manual testing performed
 
+   ## Post-Deploy Monitoring & Validation
+   - **What to monitor/search**
+     - Logs:
+     - Metrics/Dashboards:
+   - **Validation checks (queries/commands)**
+     - `command or query here`
+   - **Expected healthy behavior**
+     - Expected signal(s)
+   - **Failure signal(s) / rollback trigger**
+     - Trigger + immediate action
+   - **Validation window & owner**
+     - Window:
+     - Owner:
+   - **If no operational impact**
+     - `No additional operational monitoring required: <reason>`
+
    ## Before / After Screenshots
    | Before | After |
    |--------|-------|
@@ -407,6 +420,7 @@ Before creating PR, verify:
 - [ ] Figma designs match implementation (if applicable)
 - [ ] Before/after screenshots captured and uploaded (for UI changes)
 - [ ] Commit messages follow conventional format
+- [ ] PR description includes Post-Deploy Monitoring & Validation section (or explicit no-impact rationale)
 - [ ] PR description includes summary, testing notes, and screenshots
 - [ ] PR description includes Compound Engineered badge