claude-engineering-plugin/docs/plans/2026-02-08-feat-simplify-plugin-settings-plan.md

title, type, date

title	type	date
Simplify Plugin Settings with .local.md Pattern	feat	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

---
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:

• Detect project type (Gemfile+Rails, tsconfig, pyproject.toml, etc.)
• Check if .claude/compound-engineering.local.md already exists
• If exists: show current config, ask if user wants to regenerate
• If not: create .claude/compound-engineering.local.md with smart defaults for detected type
• Display the file path and tell user they can edit it directly
• 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):

#### 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:

**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:

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.

• 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.

• 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.

• Update plugin.json description with correct counts
• Update marketplace.json description with correct counts
• Update README.md component counts table

5d. Update CHANGELOG.md

• 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