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>
This commit is contained in:
Kieran Klaassen
2026-02-12 11:43:16 -06:00
committed by GitHub
parent fbae146ba9
commit 56b174a056
19 changed files with 787 additions and 69 deletions

View File

@@ -0,0 +1,143 @@
---
title: Convert .local.md Settings for OpenCode and Codex
type: feat
date: 2026-02-08
---
# Convert .local.md Settings for OpenCode and Codex
## Overview
PR #124 introduces `.claude/compound-engineering.local.md` — a YAML frontmatter settings file that workflow commands (`review.md`, `work.md`) read at runtime to decide which agents to run. The conversion script already handles agents, commands, skills, hooks, and MCP servers. It does **not** handle `.local.md` settings files.
The question: can OpenCode and Codex support this same pattern? And what does the converter need to do?
## Analysis: What `.local.md` Actually Does
The settings file does two things:
1. **YAML frontmatter** with structured config: `review_agents: [list]`, `plan_review_agents: [list]`
2. **Markdown body** with free-text instructions passed to review agents as context
The commands (`review.md`, `work.md`) read this file at runtime using the Read tool and use the values to decide which Task agents to spawn. This is **prompt-level logic** — it's instructions in the command body telling the AI "read this file, parse it, act on it."
## Key Insight: This Already Works
The converter already converts `review.md` and `work.md` command bodies verbatim (for OpenCode) or as generated skills (for Codex). The instructions that say "Read `.claude/compound-engineering.local.md`" are just markdown text inside the command body. When the converter outputs them:
- **OpenCode**: The command template includes the full body. The AI reads it, follows the instructions, reads the settings file.
- **Codex**: The command becomes a prompt + generated skill. The skill body includes the instructions. The AI reads it, follows the instructions, reads the settings file.
**The `.local.md` file itself is not a plugin component** — it's a runtime artifact created per-project by the user (via `/compound-engineering-setup`). The converter doesn't need to bundle it.
## What Needs Attention
### 1. Setup Command Has `disable-model-invocation: true`
`setup.md` has `disable-model-invocation: true`. The converter already handles this correctly:
- **OpenCode** (`claude-to-opencode.ts:117`): Skips commands with `disableModelInvocation`
- **Codex** (`claude-to-codex.ts:22`): Filters them out of prompts and generated skills
This means `/compound-engineering-setup` won't be auto-invocable in either target. That's correct — it's a deliberate user action. But it also means users of the converted plugin have **no way to run setup**. They'd need to manually create the `.local.md` file.
### 2. The `.local.md` File Path Is Claude-Specific
The commands reference `.claude/compound-engineering.local.md`. In OpenCode, the equivalent directory is `.opencode/`. In Codex, it's `.codex/`. The converter currently does **no text rewriting** of file paths inside command bodies.
### 3. Slash Command References in Config-Aware Sections
The commands say things like "Run `/compound-engineering-setup` to create a settings file." The Codex converter already transforms `/command-name``/prompts:command-name`, but since setup has `disable-model-invocation`, there's no matching prompt. This reference becomes a dead link.
### 4. `Task {agent-name}(...)` Syntax in Review Commands
`review.md` uses `Task {agent-name}(PR content)` — the Codex converter already transforms these to `$skill-name` references. OpenCode passes them through as template text.
## Proposed Solution
### Phase 1: Add Settings File Path Rewriting to Converters
Both converters should rewrite `.claude/` paths inside command bodies to the target-appropriate directory.
**File:** `src/converters/claude-to-opencode.ts`
Add a `transformContentForOpenCode(body)` function that replaces:
- `.claude/compound-engineering.local.md``.opencode/compound-engineering.local.md`
- `~/.claude/compound-engineering.local.md``~/.config/opencode/compound-engineering.local.md`
Apply it in `convertCommands()` to the command body before storing as template.
**File:** `src/converters/claude-to-codex.ts`
Extend `transformContentForCodex(body)` to also replace:
- `.claude/compound-engineering.local.md``.codex/compound-engineering.local.md`
- `~/.claude/compound-engineering.local.md``~/.codex/compound-engineering.local.md`
### Phase 2: Generate Setup Equivalent for Each Target
Since `setup.md` is excluded by `disable-model-invocation`, the converter should generate a **target-native setup instruction** that tells users how to create the settings file.
**Option A: Include setup as a non-auto-invocable command anyway** (recommended)
Change the converters to include `disable-model-invocation` commands but mark them appropriately:
- **OpenCode**: Include in command map but add a `manual: true` flag or comment
- **Codex**: Include as a prompt (user can still invoke it manually via `/prompts:compound-engineering-setup`)
This is the simplest approach — the setup instructions are useful even if not auto-triggered.
**Option B: Generate a README/instructions file**
Create a `compound-engineering-settings.md` file in the output that documents how to create the settings file for the target platform. More complex, less useful.
**Recommendation: Option A** — just stop filtering out `disable-model-invocation` commands entirely. Both OpenCode and Codex support user-invoked commands/prompts. The flag exists to prevent Claude from auto-invoking during conversation, not to hide the command entirely.
### Phase 3: Update Tests
**File:** `tests/converter.test.ts`
- Add test that `.claude/` paths in command bodies are rewritten to `.opencode/` paths
- Update existing `disable-model-invocation` test to verify the command IS included (if Option A)
**File:** `tests/codex-converter.test.ts`
- Add test that `.claude/` paths are rewritten to `.codex/` paths
- Add test that setup command is included as a prompt (if Option A)
- Add test that slash command references to setup are preserved correctly
### Phase 4: Add Fixture for Settings-Aware Command
**File:** `tests/fixtures/sample-plugin/commands/settings-aware-command.md`
```markdown
---
name: workflows:review
description: Run comprehensive code reviews
---
Read `.claude/compound-engineering.local.md` for agent config.
If not found, use defaults.
Run `/compound-engineering-setup` to create settings.
```
Test that the converter rewrites the paths and command references correctly.
## Acceptance Criteria
- [ ] OpenCode converter rewrites `.claude/``.opencode/` in command bodies
- [ ] Codex converter rewrites `.claude/``.codex/` in command/skill bodies
- [ ] Global path `~/.claude/` rewritten to target-appropriate global path
- [ ] `disable-model-invocation` commands are included (not filtered) in both targets
- [ ] Tests cover path rewriting for both targets
- [ ] Tests cover setup command inclusion
- [ ] Existing tests still pass
## What We're NOT Doing
- Not bundling the `.local.md` file itself (it's user-created per-project)
- Not converting YAML frontmatter format (both targets can read `.md` files with YAML)
- Not adding target-specific setup wizards (the instructions in the command body work across all targets)
- Not rewriting `AskUserQuestion` tool references (all three platforms support equivalent interactive tools)
## Complexity Assessment
This is a **small change** — mostly string replacement in the converters plus updating the `disable-model-invocation` filter. The `.local.md` pattern is prompt-level instructions, not a proprietary API. It works anywhere an AI can read a file and follow instructions.

View File

@@ -0,0 +1,195 @@
---
title: Simplify Plugin Settings with .local.md Pattern
type: feat
date: 2026-02-08
---
# Simplify Plugin Settings
## Overview
Replace the 486-line `/compound-engineering-setup` wizard and JSON config with the `.local.md` plugin-settings pattern. Make agent configuration dead simple: a YAML frontmatter file users edit directly, with a lightweight setup command that generates the template.
## Problem Statement
The current branch (`feat/compound-engineering-setup`) has:
- A 486-line setup command with Quick/Advanced/Minimal modes, add/remove loops, custom agent discovery
- JSON config file (`.claude/compound-engineering.json`) — not the plugin-settings convention
- Config-loading boilerplate that would be duplicated across 4 workflow commands
- Over-engineered for "which agents should review my code?"
Meanwhile, the workflow commands on main have hardcoded agent lists that can't be customized per-project.
## Proposed Solution
Use `.claude/compound-engineering.local.md` with YAML frontmatter. Three simple changes:
1. **Rewrite `setup.md`** (486 → ~60 lines) — detect project type, create template file
2. **Add config reading to workflow commands** (~5 lines each) — read file, fall back to defaults
3. **Config is optional** — everything works without it via auto-detection
### Settings File Format
```markdown
---
review_agents: [kieran-rails-reviewer, code-simplicity-reviewer, security-sentinel]
plan_review_agents: [kieran-rails-reviewer, code-simplicity-reviewer]
---
# Review Context
Any extra instructions for review agents go here.
Focus on N+1 queries — we've had issues in the brief system.
Skip agent-native checks for internal admin pages.
```
That's it. No `conditionalAgents`, no `options`, no `customAgents` mapping. Conditional agents (migration, frontend, architecture, data) stay hardcoded in the review command — they trigger based on file patterns, not config.
## Implementation Plan
### Phase 1: Rewrite setup.md
**File:** `plugins/compound-engineering/commands/setup.md`
**From:** 486 lines → **To:** ~60 lines
The setup command should:
- [x] Detect project type (Gemfile+Rails, tsconfig, pyproject.toml, etc.)
- [x] Check if `.claude/compound-engineering.local.md` already exists
- [x] If exists: show current config, ask if user wants to regenerate
- [x] If not: create `.claude/compound-engineering.local.md` with smart defaults for detected type
- [x] Display the file path and tell user they can edit it directly
- [x] No wizard, no multi-step AskUserQuestion flows, no modify loops
**Default agents by project type:**
| 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, architecture-strategist |
### Phase 2: Update review.md
**File:** `plugins/compound-engineering/commands/workflows/review.md`
**Change:** Replace hardcoded agent list (lines 64-81) with config-aware section
Add before the parallel agents section (~5 lines):
```markdown
#### Load Review Agents
Read `.claude/compound-engineering.local.md` (project) or `~/.claude/compound-engineering.local.md` (global).
If found, use `review_agents` from YAML frontmatter. If not found, auto-detect project type and use defaults:
- 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
Run all review agents in parallel using Task tool.
```
**Keep conditional agents hardcoded** — they trigger on file patterns (db/migrate, *.ts, etc.), not user preference. This is correct behavior.
**Add `schema-drift-detector` as a conditional agent** — currently exists as an agent but isn't wired into any command. Add it to the migrations conditional block:
```markdown
**MIGRATIONS: If PR contains database migrations or schema.rb changes:**
- Task schema-drift-detector(PR content) - Detects unrelated schema.rb changes (run FIRST)
- Task data-migration-expert(PR content) - Validates ID mappings, rollback safety
- Task deployment-verification-agent(PR content) - Go/No-Go deployment checklist
**When to run:** PR includes `db/migrate/*.rb` OR `db/schema.rb`
```
`schema-drift-detector` should run first per its own docs — catches drift before other DB reviewers waste time on unrelated changes.
### Phase 3: Update work.md
**File:** `plugins/compound-engineering/commands/workflows/work.md`
**Change:** Replace hardcoded agent list in "Consider Reviewer Agents" section (lines 180-193)
Replace with:
```markdown
If review agents are needed, read from `.claude/compound-engineering.local.md` frontmatter (`review_agents`).
If no config, use project-appropriate defaults. Run in parallel with Task tool.
```
### Phase 4: Update compound.md
**File:** `plugins/compound-engineering/commands/workflows/compound.md`
**Change:** Update Phase 3 "Optional Enhancement" (lines 92-98) and "Applicable Specialized Agents" section (lines 214-234)
The specialized agents in compound.md are problem-type-based (performance → performance-oracle, security → security-sentinel). These should stay hardcoded — they're not "review agents", they're domain experts triggered by problem category. No config needed.
**Only change:** Add a note that users can customize review agents via `/compound-engineering-setup`, but don't add config-reading logic here.
## Acceptance Criteria
- [ ] `setup.md` is under 80 lines
- [ ] Running `/compound-engineering-setup` creates `.claude/compound-engineering.local.md` with correct defaults
- [ ] Running `/compound-engineering-setup` when config exists shows current config and asks before overwriting
- [ ] `/workflows:review` reads agents from `.local.md` when present
- [ ] `/workflows:review` falls back to auto-detected defaults when no config
- [ ] `/workflows:work` reads agents from `.local.md` when present
- [ ] `compound.md` unchanged except for a reference to the setup command
- [ ] No JSON config files — only `.local.md`
- [ ] Config file is optional — everything works without it
- [ ] Conditional agents (migrations, frontend, architecture, data) remain hardcoded in review.md
### Phase 5: Structural Cleanup
**5a. Delete `technical_review.md`**
`commands/technical_review.md` is a one-line command (`Have @agent-dhh-rails-reviewer @agent-kieran-rails-reviewer @agent-code-simplicity-reviewer review...`) with `disable-model-invocation: true`. It duplicates the `/plan_review` skill. Delete it.
- [x] Delete `plugins/compound-engineering/commands/technical_review.md`
**5b. Add `disable-model-invocation: true` to `setup.md`**
The setup command is deliberate — users run it explicitly. It should not be auto-invoked.
- [x] Add `disable-model-invocation: true` to `setup.md` frontmatter
**5c. Update component counts**
After changes: 29 agents, 24 commands (25 - 1 deleted technical_review), 18 skills, 1 MCP.
Wait — with setup.md added and technical_review.md deleted: 25 - 1 = 24. Same as main. Verify actual count after changes.
- [x] Update `plugin.json` description with correct counts
- [x] Update `marketplace.json` description with correct counts
- [x] Update `README.md` component counts table
**5d. Update CHANGELOG.md**
- [x] Add entry for v2.32.0 documenting: settings support, schema-drift-detector wired in, technical_review removed
## Acceptance Criteria
- [ ] `setup.md` is under 80 lines
- [ ] `setup.md` has `disable-model-invocation: true`
- [ ] Running `/compound-engineering-setup` creates `.claude/compound-engineering.local.md` with correct defaults
- [ ] Running `/compound-engineering-setup` when config exists shows current config and asks before overwriting
- [ ] `/workflows:review` reads agents from `.local.md` when present
- [ ] `/workflows:review` falls back to auto-detected defaults when no config
- [ ] `/workflows:review` runs `schema-drift-detector` for PRs with migrations or schema.rb
- [ ] `/workflows:work` reads agents from `.local.md` when present
- [ ] `compound.md` unchanged except for a reference to the setup command
- [ ] `technical_review.md` deleted
- [ ] No JSON config files — only `.local.md`
- [ ] Config file is optional — everything works without it
- [ ] Conditional agents (migrations, frontend, architecture, data) remain hardcoded in review.md
- [ ] Component counts match across plugin.json, marketplace.json, and README.md
## What We're NOT Doing
- No multi-step wizard (users edit the file directly)
- No custom agent discovery (users add agent names to the YAML list)
- No `conditionalAgents` config (stays hardcoded by file pattern)
- No `options` object (agentNative, parallelReviews — not needed)
- No global vs project distinction in the command (just check both paths)
- No config-loading boilerplate duplicated across commands