diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 92f36240..563dfcd8 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 29 specialized agents, 24 commands, and 18 skills.", - "version": "2.31.0", + "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 29 specialized agents, 22 commands, and 19 skills.", + "version": "2.33.0", "author": { "name": "Kieran Klaassen", "url": "https://github.com/kieranklaassen", diff --git a/plugins/compound-engineering/commands/release-docs.md b/.claude/commands/release-docs.md similarity index 99% rename from plugins/compound-engineering/commands/release-docs.md rename to .claude/commands/release-docs.md index 6f96e09c..903d6aeb 100644 --- a/plugins/compound-engineering/commands/release-docs.md +++ b/.claude/commands/release-docs.md @@ -2,7 +2,6 @@ name: release-docs description: Build and update the documentation site with current plugin components argument-hint: "[optional: --dry-run to preview changes without writing]" -disable-model-invocation: true --- # Release Documentation Command diff --git a/docs/index.html b/docs/index.html index ec26ee37..08021995 100644 --- a/docs/index.html +++ b/docs/index.html @@ -4,7 +4,7 @@ Compounding Engineering - AI-Powered Development Tools for Claude Code - + @@ -12,7 +12,7 @@ - + @@ -155,13 +155,13 @@
- Version 2.28.0 released! + Version 2.32.2 released!

Your Code Reviews Just Got 12 Expert Opinions. In 30 Seconds.

- Here's what happened when we shipped yesterday: security audit, performance analysis, architectural review, pattern detection, and eight more specialized checks—all running in parallel. No meetings. No waiting. Just answers. That's compounding engineering: 28 specialized agents, 24 workflow commands, and 15 skills that make today's work easier than yesterday's. + Here's what happened when we shipped yesterday: security audit, performance analysis, architectural review, pattern detection, and eight more specialized checks—all running in parallel. No meetings. No waiting. Just answers. That's compounding engineering: 29 specialized agents, 23 workflow commands, and 18 skills that make today's work easier than yesterday's.

@@ -179,17 +179,17 @@

-
28
+
29
Specialized Agents
-
24
+
23
Slash Commands
-
15
+
18
Intelligent Skills
@@ -244,7 +244,7 @@

Delegate

The security-sentinel has checked 10,000 PRs for SQL injection. The kieran-rails-reviewer never approves a controller with business logic. They don't get tired, don't skip Friday afternoon reviews, don't forget the conventions you agreed on in March. Run /work and watch your plan execute with quality gates that actually enforce your standards—every single time.

- 27 specialized agents + 29 specialized agents /work dhh-rails-style skill git-worktree skill @@ -292,7 +292,7 @@

Compound

- 27 Specialized Agents + 29 Specialized Agents

Think of them as coworkers who never quit. The security-sentinel has seen every SQL injection variant. The kieran-rails-reviewer enforces conventions with zero compromise. The performance-oracle spots N+1 queries while you're still reading the PR. Run them solo or launch twelve in parallel—your choice. @@ -531,7 +531,7 @@

Documentation Agent (1)

- 19 Powerful Commands + 23 Powerful Commands

Slash commands that replace entire workflows. /review is your code review committee. /plan is your research team. /triage sorts 50 todos in the time it takes you to read five. Each one automates hours of work into a single line. @@ -683,7 +683,7 @@

Utility Commands

- 12 Intelligent Skills + 18 Intelligent Skills

Domain expertise on tap. Need to write a Ruby gem? The andrew-kane-gem-writer knows the patterns Andrew uses in 50+ popular gems. Building a Rails app? The dhh-rails-style enforces 37signals conventions. Generating images? The gemini-imagegen has Google's AI on speed dial. Just invoke the skill and watch it work. @@ -825,7 +825,7 @@

Image Generation

- Two MCP Servers + 1 MCP Server

Playwright gives Claude a browser—it can click buttons, take screenshots, fill forms, and validate what your users actually see. Context7 gives it instant access to docs for 100+ frameworks. Need to know how Next.js handles dynamic routes? Context7 fetches the answer in real-time instead of hallucinating from outdated training data. @@ -989,7 +989,7 @@

Frequently Asked Questions

Free & Open Source

Install Once. Compound Forever.

- Your next code review takes 30 seconds. The one after that? Even faster. That's compounding. Get 27 expert agents, 19 workflow commands, and 12 specialized skills working for you right now. + Your next code review takes 30 seconds. The one after that? Even faster. That's compounding. Get 29 expert agents, 23 workflow commands, and 18 specialized skills working for you right now.

diff --git a/docs/pages/changelog.html b/docs/pages/changelog.html index 7cf731cf..dd0c72dc 100644 --- a/docs/pages/changelog.html +++ b/docs/pages/changelog.html @@ -48,6 +48,8 @@

Resources

On This Page

    +
  • v2.32.2
    • +
  • v2.32.1
  • v2.6.0
  • v2.5.0
  • v2.4.1
    • @@ -86,6 +88,43 @@

    Changelog

    Keep a Changelog conventions.

    + +
    +
    +

    v2.32.2

    + 2026-02-12 +
    + +
    +

    Changed

    +
      +
    • + /release-docs command moved from plugin to local .claude/commands/ - + This is a repository maintenance command and should not be distributed to users. Command count reduced from 24 to 23. +
      • +
    +
    +
    + + +
    +
    +

    v2.32.1

    + 2026-02-12 +
    + +
    +

    Changed

    +
      +
    • + /workflows:review command - Added learnings-researcher + agent to the parallel review phase. The review now searches docs/solutions/ for past + issues related to the PR's modules and patterns, surfacing "Known Pattern" findings during synthesis. +
      • +
    +
    +
    +
    diff --git a/docs/plans/2026-02-08-feat-convert-local-md-settings-for-opencode-codex-plan.md b/docs/plans/2026-02-08-feat-convert-local-md-settings-for-opencode-codex-plan.md new file mode 100644 index 00000000..c477abe7 --- /dev/null +++ b/docs/plans/2026-02-08-feat-convert-local-md-settings-for-opencode-codex-plan.md @@ -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. diff --git a/docs/plans/2026-02-08-feat-simplify-plugin-settings-plan.md b/docs/plans/2026-02-08-feat-simplify-plugin-settings-plan.md new file mode 100644 index 00000000..e619a98a --- /dev/null +++ b/docs/plans/2026-02-08-feat-simplify-plugin-settings-plan.md @@ -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 diff --git a/plugins/compound-engineering/.claude-plugin/plugin.json b/plugins/compound-engineering/.claude-plugin/plugin.json index 382bb8a3..a74039ac 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.31.1", - "description": "AI-powered development tools. 29 agents, 24 commands, 18 skills, 1 MCP server for code review, research, design, and workflow automation.", + "version": "2.33.0", + "description": "AI-powered development tools. 29 agents, 22 commands, 19 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 cc21da61..b80621c6 100644 --- a/plugins/compound-engineering/CHANGELOG.md +++ b/plugins/compound-engineering/CHANGELOG.md @@ -5,6 +5,30 @@ 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.33.0] - 2026-02-12 + +### Added + +- **`setup` skill** — Interactive configurator for review agents + - Auto-detects project type (Rails, Python, TypeScript, etc.) + - Two paths: "Auto-configure" (one click) or "Customize" (pick stack, focus areas, depth) + - Writes `compound-engineering.local.md` in project root (tool-agnostic — works for Claude, Codex, OpenCode) + - Invoked automatically by `/workflows:review` when no settings file exists +- **`learnings-researcher` in `/workflows:review`** — Always-run agent that searches `docs/solutions/` for past issues related to the PR +- **`schema-drift-detector` wired into `/workflows:review`** — Conditional agent for PRs with migrations + +### Changed + +- **`/workflows:review`** — Now reads review agents from `compound-engineering.local.md` settings file. Falls back to invoking setup skill if no file exists. +- **`/workflows:work`** — Review agents now configurable via settings file +- **`/release-docs` command** — Moved from plugin to local `.claude/commands/` (repo maintenance, not distributed) + +### Removed + +- **`/technical_review` command** — Superseded by configurable review agents + +--- + ## [2.32.0] - 2026-02-11 ### Added diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index 0aa55435..ec1ad83b 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -7,8 +7,8 @@ AI-powered development tools that get smarter with every use. Make each unit of | Component | Count | |-----------|-------| | Agents | 29 | -| Commands | 25 | -| Skills | 16 | +| Commands | 22 | +| Skills | 19 | | MCP Servers | 1 | ## Agents @@ -94,7 +94,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 | -| `/technical_review` | Multi-agent technical/architecture review in parallel | +| `/sync` | Sync Claude Code config across machines | | `/report-bug` | Report a bug in the plugin | | `/reproduce-bug` | Reproduce bugs using logs and console | | `/resolve_parallel` | Resolve TODO comments in parallel | @@ -134,6 +134,8 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in | `every-style-editor` | Review copy for Every's style guide compliance | | `file-todos` | File-based todo tracking system | | `git-worktree` | Manage Git worktrees for parallel development | +| `resolve-pr-parallel` | Resolve PR review comments in parallel | +| `setup` | Configure which review agents run for your project | ### Multi-Agent Orchestration diff --git a/plugins/compound-engineering/commands/technical_review.md b/plugins/compound-engineering/commands/technical_review.md deleted file mode 100644 index 7298df40..00000000 --- a/plugins/compound-engineering/commands/technical_review.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -name: technical_review -description: Have multiple specialized agents review the technical approach and architecture of a plan in parallel -argument-hint: "[plan file path or plan content]" -disable-model-invocation: true ---- - -Have @agent-dhh-rails-reviewer @agent-kieran-rails-reviewer @agent-code-simplicity-reviewer review the technical approach in this plan in parallel. diff --git a/plugins/compound-engineering/commands/workflows/brainstorm.md b/plugins/compound-engineering/commands/workflows/brainstorm.md index b9432db8..b4f3a0f6 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: @@ -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":** diff --git a/plugins/compound-engineering/commands/workflows/compound.md b/plugins/compound-engineering/commands/workflows/compound.md index 7f647d2f..9dffc1a4 100644 --- a/plugins/compound-engineering/commands/workflows/compound.md +++ b/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 diff --git a/plugins/compound-engineering/commands/workflows/review.md b/plugins/compound-engineering/commands/workflows/review.md index e6593034..d0ba78f4 100644 --- a/plugins/compound-engineering/commands/workflows/review.md +++ b/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. +#### 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: -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 +Run all configured review agents in parallel using Task tool. For each agent in the `review_agents` list: + +``` +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 @@ -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. - [ ] 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) diff --git a/plugins/compound-engineering/commands/workflows/work.md b/plugins/compound-engineering/commands/workflows/work.md index 230300c3..625889b6 100644 --- a/plugins/compound-engineering/commands/workflows/work.md +++ b/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: ` + ## 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 diff --git a/plugins/compound-engineering/skills/setup/SKILL.md b/plugins/compound-engineering/skills/setup/SKILL.md new file mode 100644 index 00000000..239739a4 --- /dev/null +++ b/plugins/compound-engineering/skills/setup/SKILL.md @@ -0,0 +1,168 @@ +--- +name: setup +description: Configure which review agents run for your project. Auto-detects stack and writes compound-engineering.local.md. +disable-model-invocation: true +--- + +# Compound Engineering Setup + +Interactive setup for `compound-engineering.local.md` — configures which agents run during `/workflows:review` and `/workflows:work`. + +## Step 1: Check Existing Config + +Read `compound-engineering.local.md` in the project root. If it exists, display current settings summary and use AskUserQuestion: + +``` +question: "Settings file already exists. What would you like to do?" +header: "Config" +options: + - label: "Reconfigure" + description: "Run the interactive setup again from scratch" + - label: "View current" + description: "Show the file contents, then stop" + - label: "Cancel" + description: "Keep current settings" +``` + +If "View current": read and display the file, then stop. +If "Cancel": stop. + +## Step 2: Detect and Ask + +Auto-detect the project stack: + +```bash +test -f Gemfile && test -f config/routes.rb && echo "rails" || \ +test -f Gemfile && echo "ruby" || \ +test -f tsconfig.json && echo "typescript" || \ +test -f package.json && echo "javascript" || \ +test -f pyproject.toml && echo "python" || \ +test -f requirements.txt && echo "python" || \ +echo "general" +``` + +Use AskUserQuestion: + +``` +question: "Detected {type} project. How would you like to configure?" +header: "Setup" +options: + - label: "Auto-configure (Recommended)" + description: "Use smart defaults for {type}. Done in one click." + - label: "Customize" + description: "Choose stack, focus areas, and review depth." +``` + +### If Auto-configure → Skip to Step 4 with 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, architecture-strategist]` + +### If Customize → Step 3 + +## Step 3: Customize (3 questions) + +**a. Stack** — confirm or override: + +``` +question: "Which stack should we optimize for?" +header: "Stack" +options: + - label: "{detected_type} (Recommended)" + description: "Auto-detected from project files" + - label: "Rails" + description: "Ruby on Rails — adds DHH-style and Rails-specific reviewers" + - label: "Python" + description: "Python — adds Pythonic pattern reviewer" + - label: "TypeScript" + description: "TypeScript — adds type safety reviewer" +``` + +Only show options that differ from the detected type. + +**b. Focus areas** — multiSelect: + +``` +question: "Which review areas matter most?" +header: "Focus" +multiSelect: true +options: + - label: "Security" + description: "Vulnerability scanning, auth, input validation (security-sentinel)" + - label: "Performance" + description: "N+1 queries, memory leaks, complexity (performance-oracle)" + - label: "Architecture" + description: "Design patterns, SOLID, separation of concerns (architecture-strategist)" + - label: "Code simplicity" + description: "Over-engineering, YAGNI violations (code-simplicity-reviewer)" +``` + +**c. Depth:** + +``` +question: "How thorough should reviews be?" +header: "Depth" +options: + - label: "Thorough (Recommended)" + description: "Stack reviewers + all selected focus agents." + - label: "Fast" + description: "Stack reviewers + code simplicity only. Less context, quicker." + - label: "Comprehensive" + description: "All above + git history, data integrity, agent-native checks." +``` + +## Step 4: Build Agent List and Write File + +**Stack-specific agents:** +- Rails → `kieran-rails-reviewer, dhh-rails-reviewer` +- Python → `kieran-python-reviewer` +- TypeScript → `kieran-typescript-reviewer` +- General → (none) + +**Focus area agents:** +- Security → `security-sentinel` +- Performance → `performance-oracle` +- Architecture → `architecture-strategist` +- Code simplicity → `code-simplicity-reviewer` + +**Depth:** +- Thorough: stack + selected focus areas +- Fast: stack + `code-simplicity-reviewer` only +- Comprehensive: all above + `git-history-analyzer, data-integrity-guardian, agent-native-reviewer` + +**Plan review agents:** stack-specific reviewer + `code-simplicity-reviewer`. + +Write `compound-engineering.local.md`: + +```markdown +--- +review_agents: [{computed agent list}] +plan_review_agents: [{computed plan agent list}] +--- + +# Review Context + +Add project-specific review instructions here. +These notes are passed to all review agents during /workflows:review and /workflows:work. + +Examples: +- "We use Turbo Frames heavily — check for frame-busting issues" +- "Our API is public — extra scrutiny on input validation" +- "Performance-critical: we serve 10k req/s on this endpoint" +``` + +## Step 5: Confirm + +``` +Saved to compound-engineering.local.md + +Stack: {type} +Review depth: {depth} +Agents: {count} configured + {agent list, one per line} + +Tip: Edit the "Review Context" section to add project-specific instructions. + Re-run this setup anytime to reconfigure. +``` diff --git a/src/converters/claude-to-codex.ts b/src/converters/claude-to-codex.ts index 2b12daaf..c98eedb1 100644 --- a/src/converters/claude-to-codex.ts +++ b/src/converters/claude-to-codex.ts @@ -46,7 +46,7 @@ function convertAgent(agent: ClaudeAgent, usedNames: Set): CodexGenerate ) const frontmatter: Record = { name, description } - let body = agent.body.trim() + let body = transformContentForCodex(agent.body.trim()) if (agent.capabilities && agent.capabilities.length > 0) { const capabilities = agent.capabilities.map((capability) => `- ${capability}`).join("\n") body = `## Capabilities\n${capabilities}\n\n${body}`.trim() @@ -121,7 +121,12 @@ function transformContentForCodex(body: string): string { return `/prompts:${normalizedName}` }) - // 3. Transform @agent-name references + // 3. Rewrite .claude/ paths to .codex/ + result = result + .replace(/~\/\.claude\//g, "~/.codex/") + .replace(/\.claude\//g, ".codex/") + + // 4. Transform @agent-name references // Match: @agent-name in text (not emails) const agentRefPattern = /@([a-z][a-z0-9-]*-(?:agent|reviewer|researcher|analyst|specialist|oracle|sentinel|guardian|strategist))/gi result = result.replace(agentRefPattern, (_match, agentName: string) => { diff --git a/src/converters/claude-to-opencode.ts b/src/converters/claude-to-opencode.ts index 5d675f96..9d871a8a 100644 --- a/src/converters/claude-to-opencode.ts +++ b/src/converters/claude-to-opencode.ts @@ -103,7 +103,7 @@ function convertAgent(agent: ClaudeAgent, options: ClaudeToOpenCodeOptions) { } } - const content = formatFrontmatter(frontmatter, agent.body) + const content = formatFrontmatter(frontmatter, rewriteClaudePaths(agent.body)) return { name: agent.name, @@ -117,7 +117,7 @@ function convertCommands(commands: ClaudeCommand[]): Record { + const plugin: ClaudePlugin = { + ...fixturePlugin, + commands: [ + { + name: "review", + description: "Review command", + body: `Read \`compound-engineering.local.md\` in the project root. + +If no settings file exists, auto-detect project type. + +Run \`/compound-engineering-setup\` to create a settings file.`, + sourcePath: "/tmp/plugin/commands/review.md", + }, + ], + agents: [], + skills: [], + } + + const bundle = convertClaudeToCodex(plugin, { + agentMode: "subagent", + inferTemperature: false, + permissions: "none", + }) + + const commandSkill = bundle.generatedSkills.find((s) => s.name === "review") + expect(commandSkill).toBeDefined() + const parsed = parseFrontmatter(commandSkill!.content) + + // Tool-agnostic path in project root — no rewriting needed + expect(parsed.body).toContain("compound-engineering.local.md") + }) + + test("rewrites .claude/ paths in agent skill bodies", () => { + const plugin: ClaudePlugin = { + ...fixturePlugin, + commands: [], + skills: [], + agents: [ + { + name: "config-reader", + description: "Reads config", + body: "Read `compound-engineering.local.md` for config.", + sourcePath: "/tmp/plugin/agents/config-reader.md", + }, + ], + } + + const bundle = convertClaudeToCodex(plugin, { + agentMode: "subagent", + inferTemperature: false, + permissions: "none", + }) + + const agentSkill = bundle.generatedSkills.find((s) => s.name === "config-reader") + expect(agentSkill).toBeDefined() + const parsed = parseFrontmatter(agentSkill!.content) + + // Tool-agnostic path in project root — no rewriting needed + expect(parsed.body).toContain("compound-engineering.local.md") + }) + test("truncates generated skill descriptions to Codex limits and single line", () => { const longDescription = `Line one\nLine two ${"a".repeat(2000)}` const plugin: ClaudePlugin = { diff --git a/tests/converter.test.ts b/tests/converter.test.ts index 71aedad0..87d87aee 100644 --- a/tests/converter.test.ts +++ b/tests/converter.test.ts @@ -3,6 +3,7 @@ import path from "path" import { loadClaudePlugin } from "../src/parsers/claude" import { convertClaudeToOpenCode } from "../src/converters/claude-to-opencode" import { parseFrontmatter } from "../src/utils/frontmatter" +import type { ClaudePlugin } from "../src/types/claude" const fixtureRoot = path.join(import.meta.dir, "fixtures", "sample-plugin") @@ -183,4 +184,64 @@ describe("convertClaudeToOpenCode", () => { // Normal commands should still be present expect(bundle.config.command?.["workflows:review"]).toBeDefined() }) + + test("rewrites .claude/ paths to .opencode/ in command bodies", () => { + const plugin: ClaudePlugin = { + root: "/tmp/plugin", + manifest: { name: "fixture", version: "1.0.0" }, + agents: [], + commands: [ + { + name: "review", + description: "Review command", + body: `Read \`compound-engineering.local.md\` in the project root. + +If no settings file exists, auto-detect project type. + +Run \`/compound-engineering-setup\` to create a settings file.`, + sourcePath: "/tmp/plugin/commands/review.md", + }, + ], + skills: [], + } + + const bundle = convertClaudeToOpenCode(plugin, { + agentMode: "subagent", + inferTemperature: false, + permissions: "none", + }) + + const template = bundle.config.command?.["review"]?.template ?? "" + + // Tool-agnostic path in project root — no rewriting needed + expect(template).toContain("compound-engineering.local.md") + }) + + test("rewrites .claude/ paths in agent bodies", () => { + const plugin: ClaudePlugin = { + root: "/tmp/plugin", + manifest: { name: "fixture", version: "1.0.0" }, + agents: [ + { + name: "test-agent", + description: "Test agent", + body: "Read `compound-engineering.local.md` for config.", + sourcePath: "/tmp/plugin/agents/test-agent.md", + }, + ], + commands: [], + skills: [], + } + + const bundle = convertClaudeToOpenCode(plugin, { + agentMode: "subagent", + inferTemperature: false, + permissions: "none", + }) + + const agentFile = bundle.agents.find((a) => a.name === "test-agent") + expect(agentFile).toBeDefined() + // Tool-agnostic path in project root — no rewriting needed + expect(agentFile!.content).toContain("compound-engineering.local.md") + }) })