Merge upstream v2.34.0 with FastAPI pivot (v2.35.0)

Incorporate 42 upstream commits while preserving the Ruby/Rails → Python/FastAPI
pivot. All 24 conflicting files individually triaged and resolved.

Key changes:
- Added tiangolo-fastapi-reviewer, python-package-readme-writer, fastapi-style,
  python-package-writer skills
- Removed Rails/Ruby agents and skills (DHH, Ankane, DSPy.rb, design agents)
- Merged pressure test into workflows/review, updated reviewer references
- Upstream additions: schema-drift-detector, slfg, setup skill, document-review,
  orchestrating-swarms, resolve-pr-parallel, new converter targets (cursor,
  gemini, droid, pi)
- Version 2.35.0: 25 agents, 23 commands, 18 skills

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

.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 27 specialized agents, 25 commands, and 15 skills.",
-      "version": "2.30.0",
+      "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 25 specialized agents, 23 commands, and 18 skills.",
+      "version": "2.35.0",
       "author": {
         "name": "Kieran Klaassen",
         "url": "https://github.com/kieranklaassen",

.claude/commands/triage-prs.md

@@ -0,0 +1,193 @@
+---
+name: triage-prs
+description: Triage all open PRs with parallel agents, label, group, and review one-by-one
+argument-hint: "[optional: repo owner/name or GitHub PRs URL]"
+disable-model-invocation: true
+allowed-tools: Bash(gh *), Bash(git log *)
+---
+
+# Triage Open Pull Requests
+
+Review, label, and act on all open PRs for a repository using parallel review agents. Produces a grouped triage report, applies labels, cross-references with issues, and walks through each PR for merge/comment decisions.
+
+## Step 0: Detect Repository
+
+Detect repo context:
+- Current repo: !`gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null || echo "no repo detected"`
+- Current branch: !`git branch --show-current 2>/dev/null`
+
+If `$ARGUMENTS` contains a GitHub URL or `owner/repo`, use that instead. Confirm the repo with the user if ambiguous.
+
+## Step 1: Gather Context (Parallel)
+
+Run these in parallel:
+
+1. **List all open PRs:**
+   ```bash
+   gh pr list --repo OWNER/REPO --state open --limit 50
+   ```
+
+2. **List all open issues:**
+   ```bash
+   gh issue list --repo OWNER/REPO --state open --limit 50
+   ```
+
+3. **List existing labels:**
+   ```bash
+   gh label list --repo OWNER/REPO --limit 50
+   ```
+
+4. **Check recent merges** (to detect duplicate/superseded PRs):
+   ```bash
+   git log --oneline -20 main
+   ```
+
+## Step 2: Batch PRs by Theme
+
+Group PRs into review batches of 4-6 based on apparent type:
+
+- **Bug fixes** - titles with `fix`, `bug`, error descriptions
+- **Features** - titles with `feat`, `add`, new functionality
+- **Documentation** - titles with `docs`, `readme`, terminology
+- **Configuration/Setup** - titles with `config`, `setup`, `install`
+- **Stale/Old** - PRs older than 30 days
+
+## Step 3: Parallel Review (Team of Agents)
+
+Spawn one review agent per batch using the Task tool. Each agent should:
+
+For each PR in their batch:
+1. Run `gh pr view --repo OWNER/REPO <number> --json title,body,files,additions,deletions,author,createdAt`
+2. Run `gh pr diff --repo OWNER/REPO <number>` (pipe to `head -200` for large diffs)
+3. Determine:
+   - **Description:** 1-2 sentence summary of the change
+   - **Label:** Which existing repo label fits best
+   - **Action:** merge / request changes / close / needs discussion
+   - **Related PRs:** Any PRs in this or other batches that touch the same files or feature
+   - **Quality notes:** Code quality, test coverage, staleness concerns
+
+Instruct each agent to:
+- Flag PRs that touch the same files (potential merge conflicts)
+- Flag PRs that duplicate recently merged work
+- Flag PRs that are part of a group solving the same problem differently
+- Report findings as a markdown table
+- Send findings back via message when done
+
+## Step 4: Cross-Reference Issues
+
+After all agents report, match issues to PRs:
+
+- Check if any PR title/body mentions `Fixes #X` or `Closes #X`
+- Check if any issue title matches a PR's topic
+- Look for duplicate issues (same bug reported twice)
+
+Build a mapping table:
+```
+| Issue | PR | Relationship |
+|-------|-----|--------------|
+| #158  | #159 | PR fixes issue |
+```
+
+## Step 5: Identify Themes
+
+Group all issues into themes (3-6 themes):
+- Count issues per theme
+- Note which themes have PRs addressing them and which don't
+- Flag themes with competing/overlapping PRs
+
+## Step 6: Compile Triage Report
+
+Present a single report with:
+
+1. **Summary stats:** X open PRs, Y open issues, Z themes
+2. **PR groups** with recommended actions:
+   - Group name and related PRs
+   - Per-PR: #, title, author, description, label, action
+3. **Issue-to-PR mapping**
+4. **Themes across issues**
+5. **Suggested cleanup:** spam issues, duplicates, stale items
+
+## Step 7: Apply Labels
+
+After presenting the report, ask user:
+
+> "Apply these labels to all PRs on GitHub?"
+
+If yes, run `gh pr edit --repo OWNER/REPO <number> --add-label "<label>"` for each PR.
+
+## Step 8: One-by-One Review
+
+Use **AskUserQuestion** to ask:
+
+> "Ready to walk through PRs one-by-one for merge/comment decisions?"
+
+Then for each PR, ordered by priority (bug fixes first, then docs, then features, then stale):
+
+### Show the PR:
+
+```
+### PR #<number> - <title>
+Author: <author> | Files: <count> | +<additions>/-<deletions> | <age>
+Label: <label>
+
+<1-2 sentence description>
+
+Fixes: <linked issues if any>
+Related: <related PRs if any>
+```
+
+Show the diff (trimmed to key changes if large).
+
+### Ask for decision:
+
+Use **AskUserQuestion**:
+- **Merge** - Merge this PR now
+- **Comment & skip** - Leave a comment explaining why not merging, keep open
+- **Close** - Close with a comment
+- **Skip** - Move to next without action
+
+### Execute decision:
+
+- **Merge:** `gh pr merge --repo OWNER/REPO <number> --squash`
+  - If PR fixes an issue, close the issue too
+- **Comment & skip:** `gh pr comment --repo OWNER/REPO <number> --body "<comment>"`
+  - Ask user what to say, or generate a grateful + specific comment
+- **Close:** `gh pr close --repo OWNER/REPO <number> --comment "<reason>"`
+- **Skip:** Move on
+
+## Step 9: Post-Merge Cleanup
+
+After all PRs are reviewed:
+
+1. **Close resolved issues** that were fixed by merged PRs
+2. **Close spam/off-topic issues** (confirm with user first)
+3. **Summary of actions taken:**
+   ```
+   ## Triage Complete
+
+   Merged: X PRs
+   Commented: Y PRs
+   Closed: Z PRs
+   Skipped: W PRs
+
+   Issues closed: A
+   Labels applied: B
+   ```
+
+## Step 10: Post-Triage Options
+
+Use **AskUserQuestion**:
+
+1. **Run `/release-docs`** - Update documentation site if components changed
+2. **Run `/changelog`** - Generate changelog for merged PRs
+3. **Commit any local changes** - If version bumps needed
+4. **Done** - Wrap up
+
+## Important Notes
+
+- **DO NOT merge without user approval** for each PR
+- **DO NOT force push or destructive actions**
+- Comments on declined PRs should be grateful and constructive
+- When PRs conflict with each other, note this and suggest merge order
+- When multiple PRs solve the same problem differently, flag for user to pick one
+- Use Haiku model for review agents to save cost (they're doing read-only analysis)

.github/workflows/ci.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2

.github/workflows/deploy-docs.yml

@@ -24,13 +24,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Pages
-        uses: actions/configure-pages@v4
+        uses: actions/configure-pages@v5
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v4
         with:
           path: 'plugins/compound-engineering/docs'
 

.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Run tests
+        run: bun test
+
+      - name: Setup Node.js for npm publish
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Publish to npm
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -2,3 +2,4 @@
 *.log
 node_modules/
 .codex/
+todos/

CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to the `@every-env/compound-plugin` CLI tool will be documented in this file.
+
+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).
+
+## [0.6.0] - 2026-02-12
+
+### Added
+
+- **Droid sync target** — `sync --target droid` symlinks personal skills to `~/.factory/skills/`
+- **Cursor sync target** — `sync --target cursor` symlinks skills to `.cursor/skills/` and merges MCP servers into `.cursor/mcp.json`
+- **Pi target** — First-class `--to pi` converter with MCPorter config and subagent compatibility ([#181](https://github.com/EveryInc/compound-engineering-plugin/pull/181)) — thanks [@gvkhosla](https://github.com/gvkhosla)!
+
+### Fixed
+
+- **Bare Claude model alias resolution** — Fixed OpenCode converter not resolving bare model aliases like `claude-sonnet-4-5-20250514` ([#182](https://github.com/EveryInc/compound-engineering-plugin/pull/182)) — thanks [@waltbeaman](https://github.com/waltbeaman)!
+
+### Changed
+
+- Extracted shared `expandHome` / `resolveTargetHome` helpers to `src/utils/resolve-home.ts`, removing duplication across `convert.ts`, `install.ts`, and `sync.ts`
+
+---
+
+## [0.5.2] - 2026-02-09
+
+### Fixed
+
+- Fix cursor install defaulting to cwd instead of opencode config dir
+
+## [0.5.1] - 2026-02-08
+
+- Initial npm publish

README.md

@@ -12,9 +12,9 @@ A Claude Code plugin marketplace featuring the **Compound Engineering Plugin**
 /plugin install compound-engineering
 ```
 
-## OpenCode + Codex (experimental) Install
+## OpenCode, Codex, Droid, Cursor, Pi & Gemini (experimental) Install
 
-This repo includes a Bun/TypeScript CLI that converts Claude Code plugins to OpenCode and Codex.
+This repo includes a Bun/TypeScript CLI that converts Claude Code plugins to OpenCode, Codex, Factory Droid, Cursor, Pi, and Gemini CLI.
 
 ```bash
 # convert the compound-engineering plugin into OpenCode format
@@ -22,6 +22,18 @@ bunx @every-env/compound-plugin install compound-engineering --to opencode
 
 # convert to Codex format
 bunx @every-env/compound-plugin install compound-engineering --to codex
+
+# convert to Factory Droid format
+bunx @every-env/compound-plugin install compound-engineering --to droid
+
+# convert to Cursor format
+bunx @every-env/compound-plugin install compound-engineering --to cursor
+
+# convert to Pi format
+bunx @every-env/compound-plugin install compound-engineering --to pi
+
+# convert to Gemini CLI format
+bunx @every-env/compound-plugin install compound-engineering --to gemini
 ```
 
 Local dev:
@@ -30,9 +42,41 @@ Local dev:
 bun run src/index.ts install ./plugins/compound-engineering --to opencode
 ```
 
-OpenCode output is written to `~/.opencode` by default, with `opencode.json` at the root and `agents/`, `skills/`, and `plugins/` alongside it.
-Both provider targets are experimental and may change as the formats evolve.
+OpenCode output is written to `~/.config/opencode` by default, with `opencode.json` at the root and `agents/`, `skills/`, and `plugins/` alongside it.
 Codex output is written to `~/.codex/prompts` and `~/.codex/skills`, with each Claude command converted into both a prompt and a skill (the prompt instructs Codex to load the corresponding skill). Generated Codex skill descriptions are truncated to 1024 characters (Codex limit).
+Droid output is written to `~/.factory/` with commands, droids (agents), and skills. Claude tool names are mapped to Factory equivalents (`Bash` → `Execute`, `Write` → `Create`, etc.) and namespace prefixes are stripped from commands.
+Cursor output is written to `.cursor/` with rules (`.mdc`), commands, skills, and `mcp.json`. Agents become "Agent Requested" rules (`alwaysApply: false`) so Cursor's AI activates them on demand. Works with both the Cursor IDE and Cursor CLI (`cursor-agent`) — they share the same `.cursor/` config directory.
+Pi output is written to `~/.pi/agent/` by default with prompts, skills, extensions, and `compound-engineering/mcporter.json` for MCPorter interoperability.
+Gemini output is written to `.gemini/` with skills (from agents), commands (`.toml`), and `settings.json` (MCP servers). Namespaced commands create directory structure (`workflows:plan` → `commands/workflows/plan.toml`). Skills use the identical SKILL.md standard and pass through unchanged.
+
+All provider targets are experimental and may change as the formats evolve.
+
+## Sync Personal Config
+
+Sync your personal Claude Code config (`~/.claude/`) to other AI coding tools:
+
+```bash
+# Sync skills and MCP servers to OpenCode
+bunx @every-env/compound-plugin sync --target opencode
+
+# Sync to Codex
+bunx @every-env/compound-plugin sync --target codex
+
+# Sync to Pi
+bunx @every-env/compound-plugin sync --target pi
+
+# Sync to Droid (skills only)
+bunx @every-env/compound-plugin sync --target droid
+
+# Sync to Cursor (skills + MCP servers)
+bunx @every-env/compound-plugin sync --target cursor
+```
+
+This syncs:
+- Personal skills from `~/.claude/skills/` (as symlinks)
+- MCP servers from `~/.claude/settings.json`
+
+Skills are symlinked (not copied) so changes in Claude Code are reflected immediately.
 
 ## Workflow
 

docs/index.html

@@ -4,7 +4,7 @@
 <head>
   <meta charset="utf-8" />
   <title>Compounding Engineering - AI-Powered Development Tools for Claude Code</title>
-  <meta content="Your code reviews just got 12 expert opinions in 30 seconds. 28 specialized agents, 24 workflow commands, and 15 skills that make today's work easier than yesterday's." name="description" />
+  <meta content="Your code reviews just got 12 expert opinions in 30 seconds. 29 specialized agents, 23 workflow commands, and 18 skills that make today's work easier than yesterday's." name="description" />
   <meta content="width=device-width, initial-scale=1" name="viewport" />
 
   <!-- Open Graph -->
@@ -12,7 +12,7 @@
   <meta property="og:site_name" content="Compounding Engineering" />
   <meta property="og:locale" content="en_US" />
   <meta property="og:title" content="Compounding Engineering - AI Development Tools" />
-  <meta property="og:description" content="Get 12 expert code reviews in 30 seconds. 28 specialized agents that make today's work easier than yesterday's." />
+  <meta property="og:description" content="Get 12 expert code reviews in 30 seconds. 29 specialized agents that make today's work easier than yesterday's." />
   <meta name="twitter:card" content="summary_large_image" />
   <meta name="twitter:title" content="Compounding Engineering" />
   <meta name="twitter:description" content="12 expert code reviews in 30 seconds. Make today's work easier than yesterday's." />
@@ -155,13 +155,13 @@
         <div class="hero-decoration"></div>
         <div class="heading hero centered">
           <a href="https://github.com/EveryInc/compound-engineering-plugin/releases" class="eyebrow">
-            <i class="fa-solid fa-rocket"></i> Version 2.28.0 released!
+            <i class="fa-solid fa-rocket"></i> Version 2.32.2 released!
           </a>
           <h1 class="balanced" style="margin-bottom: 32px;">
             Your Code Reviews Just Got 12 Expert Opinions. In 30 Seconds.
           </h1>
           <p class="paragraph m secondary balanced" style="margin-bottom: 32px;">
-            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.
           </p>
           <div class="button-group margin-paragraph centered">
             <a href="#install" class="button primary">
@@ -179,17 +179,17 @@
         <div class="stats-container">
           <div class="stat-card">
             <div class="stat-icon"><i class="fa-solid fa-users-gear"></i></div>
-            <div class="stat-number">28</div>
+            <div class="stat-number">29</div>
             <div class="stat-label">Specialized Agents</div>
           </div>
           <div class="stat-card">
             <div class="stat-icon"><i class="fa-solid fa-terminal"></i></div>
-            <div class="stat-number">24</div>
+            <div class="stat-number">23</div>
             <div class="stat-label">Slash Commands</div>
           </div>
           <div class="stat-card">
             <div class="stat-icon"><i class="fa-solid fa-wand-magic-sparkles"></i></div>
-            <div class="stat-number">15</div>
+            <div class="stat-number">18</div>
             <div class="stat-label">Intelligent Skills</div>
           </div>
           <div class="stat-card">
@@ -244,7 +244,7 @@
                 The <code>security-sentinel</code> has checked 10,000 PRs for SQL injection. The <code>kieran-rails-reviewer</code> 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 <code>/work</code> and watch your plan execute with quality gates that actually enforce your standards—every single time.
               </p>
               <div class="pillar-tools">
-                <span class="tool-tag">27 specialized agents</span>
+                <span class="tool-tag">29 specialized agents</span>
                 <span class="tool-tag">/work</span>
                 <span class="tool-tag">dhh-rails-style skill</span>
                 <span class="tool-tag">git-worktree skill</span>
@@ -292,7 +292,7 @@
       <section id="agents">
         <div class="heading">
           <h2 class="no-top-margin">
-            <i class="fa-solid fa-users-gear color-accent"></i> 27 Specialized Agents
+            <i class="fa-solid fa-users-gear color-accent"></i> 29 Specialized Agents
           </h2>
           <p class="paragraph m secondary">
             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 @@
       <section id="commands">
         <div class="heading">
           <h2 class="no-top-margin">
-            <i class="fa-solid fa-terminal color-accent"></i> 19 Powerful Commands
+            <i class="fa-solid fa-terminal color-accent"></i> 23 Powerful Commands
           </h2>
           <p class="paragraph m secondary">
             Slash commands that replace entire workflows. <code>/review</code> is your code review committee. <code>/plan</code> is your research team. <code>/triage</code> 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 @@
       <section id="skills">
         <div class="heading">
           <h2 class="no-top-margin">
-            <i class="fa-solid fa-wand-magic-sparkles color-accent"></i> 12 Intelligent Skills
+            <i class="fa-solid fa-wand-magic-sparkles color-accent"></i> 18 Intelligent Skills
           </h2>
           <p class="paragraph m secondary">
             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 @@
       <section id="mcp-servers">
         <div class="heading">
           <h2 class="no-top-margin">
-            <i class="fa-solid fa-server color-accent"></i> Two MCP Servers
+            <i class="fa-solid fa-server color-accent"></i> 1 MCP Server
           </h2>
           <p class="paragraph m secondary">
             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 @@ skill: gemini-imagegen</code></pre>
           <span class="cta-badge"><i class="fa-solid fa-bolt"></i> Free & Open Source</span>
           <h2>Install Once. Compound Forever.</h2>
           <p class="paragraph m cta-subheading">
-            <strong>Your next code review takes 30 seconds.</strong> 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.
+            <strong>Your next code review takes 30 seconds.</strong> 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.
           </p>
           <div class="button-group margin-paragraph centered">
             <a href="#install" class="button primary cta-primary">

docs/pages/changelog.html

@@ -48,6 +48,8 @@
         <div class="nav-section">
           <h3>On This Page</h3>
           <ul>
+            <li><a href="#v2.32.2">v2.32.2</a></li>
+            <li><a href="#v2.32.1">v2.32.1</a></li>
             <li><a href="#v2.6.0">v2.6.0</a></li>
             <li><a href="#v2.5.0">v2.5.0</a></li>
             <li><a href="#v2.4.1">v2.4.1</a></li>
@@ -86,6 +88,43 @@
           <a href="https://keepachangelog.com/">Keep a Changelog</a> conventions.
         </p>
 
+        <!-- Version 2.32.2 -->
+        <section id="v2.32.2" class="version-section">
+          <div class="version-header">
+            <h2>v2.32.2</h2>
+            <span class="version-date">2026-02-12</span>
+          </div>
+
+          <div class="changelog-category changed">
+            <h3><i class="fa-solid fa-arrows-rotate"></i> Changed</h3>
+            <ul>
+              <li>
+                <strong><code>/release-docs</code> command moved from plugin to local <code>.claude/commands/</code></strong> -
+                This is a repository maintenance command and should not be distributed to users. Command count reduced from 24 to 23.
+              </li>
+            </ul>
+          </div>
+        </section>
+
+        <!-- Version 2.32.1 -->
+        <section id="v2.32.1" class="version-section">
+          <div class="version-header">
+            <h2>v2.32.1</h2>
+            <span class="version-date">2026-02-12</span>
+          </div>
+
+          <div class="changelog-category changed">
+            <h3><i class="fa-solid fa-arrows-rotate"></i> Changed</h3>
+            <ul>
+              <li>
+                <strong><code>/workflows:review</code> command</strong> - Added <code>learnings-researcher</code>
+                agent to the parallel review phase. The review now searches <code>docs/solutions/</code> for past
+                issues related to the PR's modules and patterns, surfacing "Known Pattern" findings during synthesis.
+              </li>
+            </ul>
+          </div>
+        </section>
+
         <!-- Version 2.6.0 -->
         <section id="v2.6.0" class="version-section">
           <div class="version-header">

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.

docs/plans/2026-02-08-feat-pr-triage-and-merge-plan.md

@@ -0,0 +1,128 @@
+---
+title: PR Triage, Review & Merge
+type: feat
+date: 2026-02-08
+---
+
+# PR Triage, Review & Merge
+
+## Overview
+
+Review all 17 open PRs one-by-one. Merge the ones that look good, leave constructive comments on the ones we won't take (keeping them open for contributors to address). Close duplicates/spam.
+
+## Approach
+
+Show the diff for each PR, get a go/no-go, then either merge or comment. PRs are ordered by priority group.
+
+## Group 1: Bug Fixes (high confidence merges)
+
+### PR #159 - fix(git-worktree): detect worktrees where .git is a file
+- **Author:** dalley | **Files:** 1 | **+2/-2**
+- **What:** Changes `-d` to `-e` check in `worktree-manager.sh` so `list` and `cleanup` detect worktrees (`.git` is a file in worktrees, not a dir)
+- **Fixes:** Issue #158
+- **Action:** Review diff → merge
+
+### PR #144 - Remove confirmation prompt when creating git worktrees
+- **Author:** XSAM | **Files:** 1 | **+0/-8**
+- **What:** Removes interactive `read -r` confirmation that breaks Claude's ability to create worktrees
+- **Related:** Same file as #159 (merge #159 first)
+- **Action:** Review diff → merge
+
+### PR #150 - fix(compound): prevent subagents from writing intermediary files
+- **Author:** tmchow | **Files:** 1 | **+64/-27**
+- **What:** Restructures `/workflows:compound` into 2-phase orchestration to prevent subagents from writing temp files
+- **Action:** Review diff → merge
+
+### PR #148 - Fix: resolve_pr_parallel uses non-existent scripts
+- **Author:** ajrobertsonio | **Files:** 1 | **+20/-7**
+- **What:** Replaces references to non-existent `bin/get-pr-comments` with standard `gh` CLI commands
+- **Fixes:** Issues #147, #54
+- **Action:** Review diff → merge
+
+## Group 2: Documentation (clean, low-risk)
+
+### PR #133 - Fix terminology: third person → passive voice
+- **Author:** FauxReal9999 | **Files:** 13 | docs-only
+- **What:** Corrects "third person" to "passive voice" across docs (accurate fix)
+- **Action:** Review diff → merge
+
+### PR #108 - Note new repository URL
+- **Author:** akx | **Files:** 5 | docs-only
+- **What:** Updates URLs from `kieranklaassen/compound-engineering-plugin` to `EveryInc/compound-engineering-plugin`
+- **Action:** Review diff → merge
+
+### PR #113 - docs: add brainstorm command to workflow documentation
+- **Author:** tmchow | docs-only
+- **What:** Adds brainstorming skill and learnings-researcher agent to README, fixes component counts
+- **Action:** Review diff → merge
+
+### PR #80 - docs: Add LSP prioritization guidance
+- **Author:** kevinold | **Files:** 1 | docs-only
+- **What:** Adds docs showing users how to customize agent behavior via project CLAUDE.md to prioritize LSP
+- **Action:** Review diff → merge
+
+## Group 3: Enhancements (likely merge)
+
+### PR #119 - fix: backup existing config files before overwriting
+- **Author:** jzw | **Files:** 5 | **+90/-3** | has tests
+- **What:** Adds `backupFile()` utility to create timestamped backups before overwriting Codex/OpenCode configs
+- **Fixes:** Issue #125
+- **Action:** Review diff → merge
+
+### PR #112 - feat(skills): add document-review skill
+- **Author:** tmchow | enhancement
+- **What:** Adds document-review skill for brainstorm/plan refinement, renames `/plan_review` → `/technical_review`
+- **Note:** Breaking rename - needs review
+- **Action:** Review diff → decide
+
+## Group 4: Needs Discussion (comment and leave open)
+
+### PR #157 - Rewrite workflows:review with context-managed map-reduce
+- **Author:** Drewx-Design | large rewrite
+- **What:** Complete rewrite of review command with file-based map-reduce architecture
+- **Comment:** Acknowledge quality, note it's a big change that needs dedicated review session
+
+### PR #131 - feat: add vmark-mcp plugin
+- **Author:** xiaolai | new plugin
+- **What:** Adds entirely new VMark markdown editor plugin to marketplace
+- **Comment:** Ask for more context on fit with marketplace scope
+
+### PR #124 - feat(commands): add /compound-engineering-setup
+- **Author:** internal | config
+- **What:** Interactive setup command for configuring review agents per project
+- **Comment:** Note overlap with #103, needs unified config strategy
+
+### PR #123 - feat: Add sync command for Claude Code personal config
+- **Author:** terry-li-hm | config
+- **What:** Sync personal Claude config across machines/editors
+- **Comment:** Note overlap with #124 and #103, needs unified config strategy
+
+### PR #103 - Add /compound:configure with persistent user preferences
+- **Author:** aviflombaum | **+36,866** lines
+- **What:** Massive architectural change adding persistent config with build system
+- **Comment:** Too large, suggest breaking into smaller PRs
+
+## Group 5: Close
+
+### PR #122 - [EXPERIMENTAL] add /slfg and /swarm-status
+- **Label:** duplicate
+- **What:** Already merged in v2.30.0 (commit e4ff6a8)
+- **Action:** Comment explaining it's been superseded, close
+
+### PR #68 - Improve all 13 skills to 90%+ grades
+- **Label:** wontfix
+- **What:** Massive stale PR (Jan 6), based on 13 skills when we now have 16+
+- **Action:** Comment thanking contributor, suggest fresh PR against current main, close
+
+## Post-Merge Cleanup
+
+After merging:
+- [ ] Close issues fixed by merged PRs (#158, #147, #54, #125)
+- [ ] Close spam issues (#98, #56)
+- [ ] Run `/release-docs` to update documentation site with new component counts
+- [ ] Bump version in plugin.json if needed
+
+## References
+
+- PR list: https://github.com/EveryInc/compound-engineering-plugin/pulls
+- Issues: https://github.com/EveryInc/compound-engineering-plugin/issues

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

docs/plans/2026-02-08-refactor-reduce-plugin-context-token-usage-plan.md

@@ -0,0 +1,212 @@
+---
+title: Reduce compound-engineering plugin context token usage
+type: refactor
+date: 2026-02-08
+---
+
+# Reduce compound-engineering Plugin Context Token Usage
+
+## Overview
+
+The compound-engineering plugin is **overflowing the default context budget by ~3x**, causing Claude Code to silently drop components. The plugin consumes ~50,500 characters in always-loaded descriptions against a default budget of 16,000 characters (2% of context window). This means Claude literally doesn't know some agents/skills exist during sessions.
+
+## Problem Statement
+
+### How Context Loading Works
+
+Claude Code uses progressive disclosure for plugin content:
+
+| Level | What Loads | When |
+|-------|-----------|------|
+| **Always in context** | `description` frontmatter from skills, commands, and agents | Session startup (unless `disable-model-invocation: true`) |
+| **On invocation** | Full SKILL.md / command body / agent body | When triggered |
+| **On demand** | Reference files in skill directories | When Claude reads them |
+
+The total budget for ALL descriptions combined is **2% of context window** (~16,000 chars fallback). When exceeded, components are **silently excluded**.
+
+### Current State: 316% of Budget
+
+| Component | Count | Always-Loaded Chars | % of 16K Budget |
+|-----------|------:|--------------------:|----------------:|
+| Agent descriptions | 29 | ~41,400 | 259% |
+| Skill descriptions | 16 | ~5,450 | 34% |
+| Command descriptions | 24 | ~3,700 | 23% |
+| **Total** | **69** | **~50,500** | **316%** |
+
+### Root Cause: Bloated Agent Descriptions
+
+Agent `description` fields contain full `<example>` blocks with user/assistant dialog. These examples belong in the agent body (system prompt), not the description. The description's only job is **discovery** — helping Claude decide whether to delegate.
+
+Examples of the problem:
+
+- `design-iterator.md`: 2,488 chars in description (should be ~200)
+- `spec-flow-analyzer.md`: 2,289 chars in description
+- `security-sentinel.md`: 1,986 chars in description
+- `kieran-rails-reviewer.md`: 1,822 chars in description
+- Average agent description: ~1,400 chars (should be 100-250)
+
+Compare to Anthropic's official examples at 100-200 chars:
+
+```yaml
+# Official (140 chars)
+description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
+
+# Current plugin (1,822 chars)
+description: "Use this agent when you need to review Rails code changes with an extremely high quality bar...\n\nExamples:\n- <example>\n  Context: The user has just implemented..."
+```
+
+### Secondary Cause: No `disable-model-invocation` on Manual Commands
+
+Zero commands set `disable-model-invocation: true`. Commands like `/deploy-docs`, `/lfg`, `/slfg`, `/triage`, `/feature-video`, `/test-browser`, `/xcode-test` are manual workflows with side effects. Their descriptions consume budget unnecessarily.
+
+The official docs explicitly state:
+> Use `disable-model-invocation: true` for workflows with side effects: `/deploy`, `/commit`, `/triage-prs`. You don't want Claude deciding to deploy because your code looks ready.
+
+---
+
+## Proposed Solution
+
+Three changes, ordered by impact:
+
+### Phase 1: Trim Agent Descriptions (saves ~35,600 chars)
+
+For all 29 agents: move `<example>` blocks from the `description` field into the agent body markdown. Keep descriptions to 1-2 sentences (100-250 chars).
+
+**Before** (agent frontmatter):
+```yaml
+---
+name: kieran-rails-reviewer
+description: "Use this agent when you need to review Rails code changes with an extremely high quality bar. This agent should be invoked after implementing features, modifying existing code, or creating new Rails components. The agent applies Kieran's strict Rails conventions and taste preferences to ensure code meets exceptional standards.\n\nExamples:\n- <example>\n  Context: The user has just implemented a new controller action with turbo streams.\n  user: \"I've added a new update action to the posts controller\"\n  ..."
+---
+
+Detailed system prompt...
+```
+
+**After** (agent frontmatter):
+```yaml
+---
+name: kieran-rails-reviewer
+description: Review Rails code with Kieran's strict conventions. Use after implementing features, modifying code, or creating new Rails components.
+---
+
+<examples>
+<example>
+Context: The user has just implemented a new controller action with turbo streams.
+user: "I've added a new update action to the posts controller"
+...
+</example>
+</examples>
+
+Detailed system prompt...
+```
+
+The examples move into the body (which only loads when the agent is actually invoked).
+
+**Impact:** ~41,400 chars → ~5,800 chars (86% reduction)
+
+### Phase 2: Add `disable-model-invocation: true` to Manual Commands (saves ~3,100 chars)
+
+Commands that should only run when explicitly invoked by the user:
+
+| Command | Reason |
+|---------|--------|
+| `/deploy-docs` | Side effect: deploys |
+| `/release-docs` | Side effect: regenerates docs |
+| `/changelog` | Side effect: generates changelog |
+| `/lfg` | Side effect: autonomous workflow |
+| `/slfg` | Side effect: swarm workflow |
+| `/triage` | Side effect: categorizes findings |
+| `/resolve_parallel` | Side effect: resolves TODOs |
+| `/resolve_todo_parallel` | Side effect: resolves todos |
+| `/resolve_pr_parallel` | Side effect: resolves PR comments |
+| `/feature-video` | Side effect: records video |
+| `/test-browser` | Side effect: runs browser tests |
+| `/xcode-test` | Side effect: builds/tests iOS |
+| `/reproduce-bug` | Side effect: runs reproduction |
+| `/report-bug` | Side effect: creates bug report |
+| `/agent-native-audit` | Side effect: runs audit |
+| `/heal-skill` | Side effect: modifies skill files |
+| `/generate_command` | Side effect: creates files |
+| `/create-agent-skill` | Side effect: creates files |
+
+Keep these **without** the flag (Claude should know about them):
+- `/workflows:plan` — Claude might suggest planning
+- `/workflows:work` — Claude might suggest starting work
+- `/workflows:review` — Claude might suggest review
+- `/workflows:brainstorm` — Claude might suggest brainstorming
+- `/workflows:compound` — Claude might suggest documenting
+- `/deepen-plan` — Claude might suggest deepening a plan
+
+**Impact:** ~3,700 chars → ~600 chars for commands in context
+
+### Phase 3: Add `disable-model-invocation: true` to Manual Skills (saves ~1,000 chars)
+
+Skills that are manual workflows:
+
+| Skill | Reason |
+|-------|--------|
+| `skill-creator` | Only invoked manually |
+| `orchestrating-swarms` | Only invoked manually |
+| `git-worktree` | Only invoked manually |
+| `resolve-pr-parallel` | Side effect |
+| `compound-docs` | Only invoked manually |
+| `file-todos` | Only invoked manually |
+
+Keep without the flag (Claude should auto-invoke):
+- `dhh-rails-style` — Claude should use when writing Rails code
+- `frontend-design` — Claude should use when building UI
+- `brainstorming` — Claude should suggest before implementation
+- `agent-browser` — Claude should use for browser tasks
+- `gemini-imagegen` — Claude should use for image generation
+- `create-agent-skills` — Claude should use when creating skills
+- `every-style-editor` — Claude should use for editing
+- `dspy-ruby` — Claude should use for DSPy.rb
+- `agent-native-architecture` — Claude should use for agent-native design
+- `andrew-kane-gem-writer` — Claude should use for gem writing
+- `rclone` — Claude should use for cloud uploads
+- `document-review` — Claude should use for doc review
+
+**Impact:** ~5,450 chars → ~4,000 chars for skills in context
+
+---
+
+## Projected Result
+
+| Component | Before (chars) | After (chars) | Reduction |
+|-----------|---------------:|-------------:|-----------:|
+| Agent descriptions | ~41,400 | ~5,800 | -86% |
+| Command descriptions | ~3,700 | ~600 | -84% |
+| Skill descriptions | ~5,450 | ~4,000 | -27% |
+| **Total** | **~50,500** | **~10,400** | **-79%** |
+| **% of 16K budget** | **316%** | **65%** | -- |
+
+From 316% of budget (components silently dropped) to 65% of budget (room for growth).
+
+---
+
+## Acceptance Criteria
+
+- [x] All 29 agent description fields are under 250 characters
+- [x] All `<example>` blocks moved from description to agent body
+- [x] 18 manual commands have `disable-model-invocation: true`
+- [x] 6 manual skills have `disable-model-invocation: true`
+- [x] Total always-loaded description content is under 16,000 characters
+- [ ] Run `/context` to verify no "excluded skills" warnings
+- [x] All agents still function correctly (examples are in body, not lost)
+- [x] All commands still invocable via `/command-name`
+- [x] Update plugin version in plugin.json and marketplace.json
+- [x] Update CHANGELOG.md
+
+## Implementation Notes
+
+- Agent examples should use `<examples><example>...</example></examples>` tags in the body — Claude understands these natively
+- Description format: "[What it does]. Use [when/trigger condition]." — two sentences max
+- The `lint` agent at 115 words shows compact agents work great
+- Test with `claude --plugin-dir ./plugins/compound-engineering` after changes
+- The `SLASH_COMMAND_TOOL_CHAR_BUDGET` env var can override the default budget for testing
+
+## References
+
+- [Skills docs](https://code.claude.com/docs/en/skills) — "Skill descriptions are loaded into context... If you have many skills, they may exceed the character budget"
+- [Subagents docs](https://code.claude.com/docs/en/sub-agents) — description field used for automatic delegation
+- [Skills troubleshooting](https://code.claude.com/docs/en/skills#claude-doesnt-see-all-my-skills) — "The budget scales dynamically at 2% of the context window, with a fallback of 16,000 characters"

docs/plans/2026-02-09-refactor-dspy-ruby-skill-update-plan.md

@@ -0,0 +1,104 @@
+---
+title: "refactor: Update dspy-ruby skill to DSPy.rb v0.34.3 API"
+type: refactor
+date: 2026-02-09
+---
+
+# Update dspy-ruby Skill to DSPy.rb v0.34.3 API
+
+## Problem
+
+The `dspy-ruby` skill uses outdated API patterns (`.forward()`, `result[:field]`, inline `T.enum([...])`, `DSPy::Tool`) and is missing 10+ features (events, lifecycle callbacks, GEPA, evaluation framework, BAML/TOON, storage, etc.).
+
+## Solution
+
+Use the engineering skill as base (already has correct API), enhance with official docs content, rewrite all reference files and templates.
+
+### Source Priority (when conflicts arise)
+
+1. **Official docs** (`../dspy.rb/docs/src/`) — source of truth for API correctness
+2. **Engineering skill** (`../engineering/.../dspy-rb/SKILL.md`) — source of truth for structure/style
+3. **NavigationContext brainstorm** — for Typed Context pattern only
+
+## Files to Update
+
+### Core (SKILL.md)
+
+1. **`skills/dspy-ruby/SKILL.md`** — Copy from engineering base, then:
+   - Fix frontmatter: `name: dspy-rb` → `name: dspy-ruby`, keep long description format
+   - Add sections before "Guidelines for Claude": Events System, Lifecycle Callbacks, Fiber-Local LM Context, Evaluation Framework, GEPA Optimization, Typed Context Pattern, Schema Formats (BAML/TOON)
+   - Update Resources section with 5 references + 3 assets using markdown links
+   - Fix any backtick references to markdown link format
+
+### References (rewrite from themed doc batches)
+
+2. **`references/core-concepts.md`** — Rewrite
+   - Source: `core-concepts/signatures.md`, `modules.md`, `predictors.md`, `advanced/complex-types.md`
+   - Cover: signatures (Date/Time types, T::Enum, defaults, field descriptions, BAML/TOON, recursive types), modules (.call() API, lifecycle callbacks, instruction update contract), predictors (all 4 types, concurrent predictions), type system (discriminators, union types)
+
+3. **`references/toolsets.md`** — NEW
+   - Source: `core-concepts/toolsets.md`, `toolsets-guide.md`
+   - Cover: Tools::Base, Tools::Toolset DSL, type safety with Sorbet sigs, schema generation, built-in toolsets, testing
+
+4. **`references/providers.md`** — Rewrite
+   - Source: `llms.txt.erb`, engineering SKILL.md, `core-concepts/module-runtime-context.md`
+   - Cover: per-provider adapters, RubyLLM unified adapter, Rails initializer, fiber-local LM context (`DSPy.with_lm`), feature-flagged model selection, compatibility matrix
+
+5. **`references/optimization.md`** — Rewrite
+   - Source: `optimization/miprov2.md`, `gepa.md`, `evaluation.md`, `production/storage.md`
+   - Cover: MIPROv2 (dspy-miprov2 gem, AutoMode presets), GEPA (dspy-gepa gem, feedback maps), Evaluation (DSPy::Evals, built-in metrics, DSPy::Example), Storage (ProgramStorage)
+
+6. **`references/observability.md`** — NEW
+   - Source: `production/observability.md`, `core-concepts/events.md`, `advanced/observability-interception.md`
+   - Cover: event system (module-scoped + global), dspy-o11y gems, Langfuse (env vars), score reporting (DSPy.score()), observation types, DSPy::Context.with_span
+
+### Assets (rewrite to current API)
+
+7. **`assets/signature-template.rb`** — T::Enum classes, `description:` kwarg, Date/Time types, defaults, union types, `.call()` / `result.field` usage examples
+
+8. **`assets/module-template.rb`** — `.call()` API, `result.field`, Tools::Base, lifecycle callbacks, `DSPy.with_lm`, `configure_predictor`
+
+9. **`assets/config-template.rb`** — RubyLLM adapter, `structured_outputs: true`, `after_initialize` Rails pattern, dspy-o11y env vars, feature-flagged model selection
+
+### Metadata
+
+10. **`.claude-plugin/plugin.json`** — Version `2.31.0` → `2.31.1`
+
+11. **`CHANGELOG.md`** — Add `[2.31.1] - 2026-02-09` entry under `### Changed`
+
+## Verification
+
+```bash
+# No old API patterns
+grep -n '\.forward(\|result\[:\|T\.enum(\[\|DSPy::Tool[^s]' plugins/compound-engineering/skills/dspy-ruby/SKILL.md
+
+# No backtick references
+grep -E '`(references|assets|scripts)/' plugins/compound-engineering/skills/dspy-ruby/SKILL.md
+
+# Frontmatter correct
+head -4 plugins/compound-engineering/skills/dspy-ruby/SKILL.md
+
+# JSON valid
+cat plugins/compound-engineering/.claude-plugin/plugin.json | jq .
+
+# All files exist
+ls plugins/compound-engineering/skills/dspy-ruby/{references,assets}/
+```
+
+## Success Criteria
+
+- [x] All API patterns updated (`.call()`, `result.field`, `T::Enum`, `Tools::Base`)
+- [x] New features covered: events, callbacks, fiber-local LM, GEPA, evals, BAML/TOON, storage, score API, RubyLLM, typed context
+- [x] 5 reference files present (core-concepts, toolsets, providers, optimization, observability)
+- [x] 3 asset templates updated to current API
+- [x] YAML frontmatter: `name: dspy-ruby`, description has "what" and "when"
+- [x] All reference links use `[file.md](./references/file.md)` format
+- [x] Writing style: imperative form, no "you should"
+- [x] Version bumped to `2.31.1`, CHANGELOG updated
+- [x] Verification commands all pass
+
+## Source Materials
+
+- Engineering skill: `/Users/vicente/Workspaces/vicente.services/engineering/plugins/engineering-skills/skills/dspy-rb/SKILL.md`
+- Official docs: `/Users/vicente/Workspaces/vicente.services/dspy.rb/docs/src/`
+- NavigationContext brainstorm: `/Users/vicente/Workspaces/vicente.services/observo/observo-server/docs/brainstorms/2026-02-09-typed-navigation-context-brainstorm.md`

docs/plans/2026-02-12-feat-add-cursor-cli-target-provider-plan.md

@@ -0,0 +1,306 @@
+---
+title: Add Cursor CLI as a Target Provider
+type: feat
+date: 2026-02-12
+---
+
+# Add Cursor CLI as a Target Provider
+
+## Overview
+
+Add `cursor` as a fourth target provider in the converter CLI, alongside `opencode`, `codex`, and `droid`. This enables `--to cursor` for both `convert` and `install` commands, converting Claude Code plugins into Cursor-compatible format.
+
+Cursor CLI (`cursor-agent`) launched in August 2025 and supports rules (`.mdc`), commands (`.md`), skills (`SKILL.md` standard), and MCP servers (`.cursor/mcp.json`). The mapping from Claude Code is straightforward because Cursor adopted the open SKILL.md standard and has a similar command format.
+
+## Component Mapping
+
+| Claude Code | Cursor Equivalent | Notes |
+|---|---|---|
+| `agents/*.md` | `.cursor/rules/*.mdc` | Agents become "Agent Requested" rules (`alwaysApply: false`, `description` set) so the AI activates them on demand rather than flooding context |
+| `commands/*.md` | `.cursor/commands/*.md` | Plain markdown files; Cursor commands have no frontmatter support -- description becomes a markdown heading |
+| `skills/*/SKILL.md` | `.cursor/skills/*/SKILL.md` | **Identical standard** -- copy directly |
+| MCP servers | `.cursor/mcp.json` | Same JSON structure (`mcpServers` key), compatible format |
+| `hooks/` | No equivalent | Cursor has no hook system; emit `console.warn` and skip |
+| `.claude/` paths | `.cursor/` paths | Content rewriting needed |
+
+### Key Design Decisions
+
+**1. Agents use `alwaysApply: false` (Agent Requested mode)**
+
+With 29 agents, setting `alwaysApply: true` would flood every Cursor session's context. Instead, agents become "Agent Requested" rules: `alwaysApply: false` with a populated `description` field. Cursor's AI reads the description and activates the rule only when relevant -- matching how Claude Code agents are invoked on demand.
+
+**2. Commands are plain markdown (no frontmatter)**
+
+Cursor commands (`.cursor/commands/*.md`) are simple markdown files where the filename becomes the command name. Unlike Claude Code commands, they do not support YAML frontmatter. The converter emits the description as a leading markdown comment, then the command body.
+
+**3. Flattened command names with deduplication**
+
+Cursor uses flat command names (no namespaces). `workflows:plan` becomes `plan`. If two commands flatten to the same name, the `uniqueName()` pattern from the codex converter appends `-2`, `-3`, etc.
+
+### Rules (`.mdc`) Frontmatter Format
+
+```yaml
+---
+description: "What this rule does and when it applies"
+globs: ""
+alwaysApply: false
+---
+```
+
+- `description` (string): Used by the AI to decide relevance -- maps from agent `description`
+- `globs` (string): Comma-separated file patterns for auto-attachment -- leave empty for converted agents
+- `alwaysApply` (boolean): Set `false` for Agent Requested mode
+
+### MCP Servers (`.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "npx",
+      "args": ["-y", "package-name"],
+      "env": { "KEY": "value" }
+    }
+  }
+}
+```
+
+Supports both local (command-based) and remote (url-based) servers. Pass through `headers` for remote servers.
+
+## Acceptance Criteria
+
+- [x] `bun run src/index.ts convert --to cursor ./plugins/compound-engineering` produces valid Cursor config
+- [x] Agents convert to `.cursor/rules/*.mdc` with `alwaysApply: false` and populated `description`
+- [x] Commands convert to `.cursor/commands/*.md` as plain markdown (no frontmatter)
+- [x] Flattened command names that collide are deduplicated (`plan`, `plan-2`, etc.)
+- [x] Skills copied to `.cursor/skills/` (identical format)
+- [x] MCP servers written to `.cursor/mcp.json` with backup of existing file
+- [x] Content transformation rewrites `.claude/` and `~/.claude/` paths to `.cursor/` and `~/.cursor/`
+- [x] `/workflows:plan` transformed to `/plan` (flat command names)
+- [x] `Task agent-name(args)` transformed to natural-language skill reference
+- [x] Plugins with hooks emit `console.warn` about unsupported hooks
+- [x] Writer does not double-nest `.cursor/.cursor/` (follows droid writer pattern)
+- [x] `model` and `allowedTools` fields silently dropped (no Cursor equivalent)
+- [x] Converter and writer tests pass
+- [x] Existing tests still pass (`bun test`)
+
+## Implementation
+
+### Phase 1: Types
+
+**Create `src/types/cursor.ts`**
+
+```typescript
+export type CursorRule = {
+  name: string
+  content: string  // Full .mdc file with YAML frontmatter
+}
+
+export type CursorCommand = {
+  name: string
+  content: string  // Plain markdown (no frontmatter)
+}
+
+export type CursorSkillDir = {
+  name: string
+  sourceDir: string
+}
+
+export type CursorBundle = {
+  rules: CursorRule[]
+  commands: CursorCommand[]
+  skillDirs: CursorSkillDir[]
+  mcpServers?: Record<string, {
+    command?: string
+    args?: string[]
+    env?: Record<string, string>
+    url?: string
+    headers?: Record<string, string>
+  }>
+}
+```
+
+### Phase 2: Converter
+
+**Create `src/converters/claude-to-cursor.ts`**
+
+Core functions:
+
+1. **`convertClaudeToCursor(plugin, options)`** -- main entry point
+   - Convert each agent to a `.mdc` rule via `convertAgentToRule()`
+   - Convert each command (including `disable-model-invocation` ones) via `convertCommand()`
+   - Pass skills through as directory references
+   - Convert MCP servers to JSON-compatible object
+   - Emit `console.warn` if `plugin.hooks` has entries
+
+2. **`convertAgentToRule(agent, usedNames)`** -- agent -> `.mdc` rule
+   - Frontmatter fields: `description` (from agent description), `globs: ""`, `alwaysApply: false`
+   - Body: agent body with content transformations applied
+   - Prepend capabilities section if present
+   - Deduplicate names via `uniqueName()`
+   - Silently drop `model` field (no Cursor equivalent)
+
+3. **`convertCommand(command, usedNames)`** -- command -> plain `.md`
+   - Flatten namespace: `workflows:plan` -> `plan`
+   - Deduplicate flattened names via `uniqueName()`
+   - Emit as plain markdown: description as `<!-- description -->` comment, then body
+   - Include `argument-hint` as a `## Arguments` section if present
+   - Body: apply `transformContentForCursor()` transformations
+   - Silently drop `allowedTools` (no Cursor equivalent)
+
+4. **`transformContentForCursor(body)`** -- content rewriting
+   - `.claude/` -> `.cursor/` and `~/.claude/` -> `~/.cursor/`
+   - `Task agent-name(args)` -> `Use the agent-name skill to: args` (same as codex)
+   - `/workflows:command` -> `/command` (flatten slash commands)
+   - `@agent-name` references -> `the agent-name rule` (use codex's suffix-matching pattern)
+   - Skip file paths (containing `/`) and common non-command patterns
+
+5. **`convertMcpServers(servers)`** -- MCP config
+   - Map each `ClaudeMcpServer` entry to Cursor-compatible JSON
+   - Pass through: `command`, `args`, `env`, `url`, `headers`
+   - Drop `type` field (Cursor infers transport from `command` vs `url`)
+
+### Phase 3: Writer
+
+**Create `src/targets/cursor.ts`**
+
+Output structure:
+
+```
+.cursor/
+├── rules/
+│   ├── agent-name-1.mdc
+│   └── agent-name-2.mdc
+├── commands/
+│   ├── command-1.md
+│   └── command-2.md
+├── skills/
+│   └── skill-name/
+│       └── SKILL.md
+└── mcp.json
+```
+
+Core function: `writeCursorBundle(outputRoot, bundle)`
+
+- `resolveCursorPaths(outputRoot)` -- detect if path already ends in `.cursor` to avoid double-nesting (follow droid writer pattern at `src/targets/droid.ts:31-50`)
+- Write rules to `rules/` as `.mdc` files
+- Write commands to `commands/` as `.md` files
+- Copy skill directories to `skills/` via `copyDir()`
+- Write `mcp.json` via `writeJson()` with `backupFile()` for existing files
+
+### Phase 4: Wire into CLI
+
+**Modify `src/targets/index.ts`**
+
+```typescript
+import { convertClaudeToCursor } from "../converters/claude-to-cursor"
+import { writeCursorBundle } from "./cursor"
+import type { CursorBundle } from "../types/cursor"
+
+// Add to targets:
+cursor: {
+  name: "cursor",
+  implemented: true,
+  convert: convertClaudeToCursor as TargetHandler<CursorBundle>["convert"],
+  write: writeCursorBundle as TargetHandler<CursorBundle>["write"],
+},
+```
+
+**Modify `src/commands/convert.ts`**
+
+- Update `--to` description: `"Target format (opencode | codex | droid | cursor)"`
+- Add to `resolveTargetOutputRoot`: `if (targetName === "cursor") return path.join(outputRoot, ".cursor")`
+
+**Modify `src/commands/install.ts`**
+
+- Same two changes as convert.ts
+
+### Phase 5: Tests
+
+**Create `tests/cursor-converter.test.ts`**
+
+Test cases (use inline `ClaudePlugin` fixtures, following codex converter test pattern):
+
+- Agent converts to rule with `.mdc` frontmatter (`alwaysApply: false`, `description` populated)
+- Agent with empty description gets default description text
+- Agent with capabilities prepended to body
+- Agent `model` field silently dropped
+- Agent with empty body gets default body text
+- Command converts with flattened name (`workflows:plan` -> `plan`)
+- Command name collision after flattening is deduplicated (`plan`, `plan-2`)
+- Command with `disable-model-invocation` is still included
+- Command `allowedTools` silently dropped
+- Command with `argument-hint` gets Arguments section
+- Skills pass through as directory references
+- MCP servers convert to JSON config (local and remote)
+- MCP `headers` pass through for remote servers
+- Content transformation: `.claude/` paths -> `.cursor/`
+- Content transformation: `~/.claude/` paths -> `~/.cursor/`
+- Content transformation: `Task agent(args)` -> natural language
+- Content transformation: slash commands flattened
+- Hooks present -> `console.warn` emitted
+- Plugin with zero agents produces empty rules array
+- Plugin with only skills works correctly
+
+**Create `tests/cursor-writer.test.ts`**
+
+Test cases (use temp directories, following droid writer test pattern):
+
+- Full bundle writes rules, commands, skills, mcp.json
+- Rules written as `.mdc` files in `rules/` directory
+- Commands written as `.md` files in `commands/` directory
+- Skills copied to `skills/` directory
+- MCP config written as valid JSON `mcp.json`
+- Existing `mcp.json` is backed up before overwrite
+- Output root already ending in `.cursor` does NOT double-nest
+- Empty bundle (no rules, commands, skills, or MCP) produces no output
+
+### Phase 6: Documentation
+
+**Create `docs/specs/cursor.md`**
+
+Document the Cursor CLI spec as a reference, following `docs/specs/codex.md` pattern:
+
+- Rules format (`.mdc` with `description`, `globs`, `alwaysApply` frontmatter)
+- Commands format (plain markdown, no frontmatter)
+- Skills format (identical SKILL.md standard)
+- MCP server configuration (`.cursor/mcp.json`)
+- CLI permissions (`.cursor/cli.json` -- for reference, not converted)
+- Config file locations (project-level vs global)
+
+**Update `README.md`**
+
+Add `cursor` to the supported targets in the CLI usage section.
+
+## What We're NOT Doing
+
+- Not converting hooks (Cursor has no hook system -- warn and skip)
+- Not generating `.cursor/cli.json` permissions (user-specific, not plugin-scoped)
+- Not creating `AGENTS.md` (Cursor reads it natively, but not part of plugin conversion)
+- Not using `globs` field intelligently (would require analyzing agent content to guess file patterns)
+- Not adding sync support (follow-up task)
+- Not transforming content inside copied SKILL.md files (known limitation -- skills may reference `.claude/` paths internally)
+- Not clearing old output before writing (matches existing target behavior -- re-runs accumulate)
+
+## Complexity Assessment
+
+This is a **medium change**. The converter architecture is well-established with three existing targets, so this is mostly pattern-following. The key novelties are:
+
+1. The `.mdc` frontmatter format (different from all other targets)
+2. Agents map to "rules" rather than a direct equivalent
+3. Commands are plain markdown (no frontmatter) unlike other targets
+4. Name deduplication needed for flattened command namespaces
+
+Skills being identical across platforms simplifies things significantly. MCP config is nearly 1:1.
+
+## References
+
+- Cursor Rules: `.cursor/rules/*.mdc` with `description`, `globs`, `alwaysApply` frontmatter
+- Cursor Commands: `.cursor/commands/*.md` (plain markdown, no frontmatter)
+- Cursor Skills: `.cursor/skills/*/SKILL.md` (open standard, identical to Claude Code)
+- Cursor MCP: `.cursor/mcp.json` with `mcpServers` key
+- Cursor CLI: `cursor-agent` command (launched August 2025)
+- Existing codex converter: `src/converters/claude-to-codex.ts` (has `uniqueName()` deduplication pattern)
+- Existing droid writer: `src/targets/droid.ts` (has double-nesting guard pattern)
+- Existing codex plan: `docs/plans/2026-02-08-feat-convert-local-md-settings-for-opencode-codex-plan.md`
+- Target provider checklist: `AGENTS.md` section "Adding a New Target Provider"

docs/plans/2026-02-14-feat-add-gemini-cli-target-provider-plan.md

@@ -0,0 +1,370 @@
+---
+title: Add Gemini CLI as a Target Provider
+type: feat
+status: completed
+completed_date: 2026-02-14
+completed_by: "Claude Opus 4.6"
+actual_effort: "Completed in one session"
+date: 2026-02-14
+---
+
+# Add Gemini CLI as a Target Provider
+
+## Overview
+
+Add `gemini` as a sixth target provider in the converter CLI, alongside `opencode`, `codex`, `droid`, `cursor`, and `pi`. This enables `--to gemini` for both `convert` and `install` commands, converting Claude Code plugins into Gemini CLI-compatible format.
+
+Gemini CLI ([google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli)) is Google's open-source AI agent for the terminal. It supports GEMINI.md context files, custom commands (TOML format), agent skills (SKILL.md standard), MCP servers, and extensions -- making it a strong conversion target with good coverage of Claude Code plugin concepts.
+
+## Component Mapping
+
+| Claude Code | Gemini Equivalent | Notes |
+|---|---|---|
+| `agents/*.md` | `.gemini/skills/*/SKILL.md` | Agents become skills -- Gemini activates them on demand via `activate_skill` tool based on description matching |
+| `commands/*.md` | `.gemini/commands/*.toml` | TOML format with `prompt` and `description` fields; namespaced via directory structure |
+| `skills/*/SKILL.md` | `.gemini/skills/*/SKILL.md` | **Identical standard** -- copy directly |
+| MCP servers | `settings.json` `mcpServers` | Same MCP protocol; different config location (`settings.json` vs `.mcp.json`) |
+| `hooks/` | `settings.json` hooks | Gemini has hooks (`BeforeTool`, `AfterTool`, `SessionStart`, etc.) but different format; emit `console.warn` and skip for now |
+| `.claude/` paths | `.gemini/` paths | Content rewriting needed |
+
+### Key Design Decisions
+
+**1. Agents become skills (not GEMINI.md context)**
+
+With 29 agents, dumping them into GEMINI.md would flood every session's context. Instead, agents convert to skills -- Gemini autonomously activates them based on the skill description when relevant. This matches how Claude Code agents are invoked on demand via the Task tool.
+
+**2. Commands use TOML format with directory-based namespacing**
+
+Gemini CLI commands are `.toml` files where the path determines the command name: `.gemini/commands/git/commit.toml` becomes `/git:commit`. This maps cleanly from Claude Code's colon-namespaced commands (`workflows:plan` -> `.gemini/commands/workflows/plan.toml`).
+
+**3. Commands use `{{args}}` placeholder**
+
+Gemini's TOML commands support `{{args}}` for argument injection, mapping from Claude Code's `argument-hint` field. Commands with `argument-hint` get `{{args}}` appended to the prompt.
+
+**4. MCP servers go into project-level settings.json**
+
+Gemini CLI reads MCP config from `.gemini/settings.json` under the `mcpServers` key. The format is compatible -- same `command`, `args`, `env` fields, plus Gemini-specific `cwd`, `timeout`, `trust`, `includeTools`, `excludeTools`.
+
+**5. Skills pass through unchanged**
+
+Gemini adopted the same SKILL.md standard (YAML frontmatter with `name` and `description`, markdown body). Skills copy directly.
+
+### TOML Command Format
+
+```toml
+description = "Brief description of the command"
+prompt = """
+The prompt content that will be sent to Gemini.
+
+User request: {{args}}
+"""
+```
+
+- `description` (string): One-line description shown in `/help`
+- `prompt` (string): The prompt sent to the model; supports `{{args}}`, `!{shell}`, `@{file}` placeholders
+
+### Skill (SKILL.md) Format
+
+```yaml
+---
+name: skill-name
+description: When and how Gemini should use this skill
+---
+
+# Skill Title
+
+Detailed instructions...
+```
+
+Identical to Claude Code's format. The `description` field is critical -- Gemini uses it to decide when to activate the skill.
+
+### MCP Server Format (settings.json)
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "npx",
+      "args": ["-y", "package-name"],
+      "env": { "KEY": "value" }
+    }
+  }
+}
+```
+
+## Acceptance Criteria
+
+- [x] `bun run src/index.ts convert --to gemini ./plugins/compound-engineering` produces valid Gemini config
+- [x] Agents convert to `.gemini/skills/*/SKILL.md` with populated `description` in frontmatter
+- [x] Commands convert to `.gemini/commands/*.toml` with `prompt` and `description` fields
+- [x] Namespaced commands create directory structure (`workflows:plan` -> `commands/workflows/plan.toml`)
+- [x] Commands with `argument-hint` include `{{args}}` placeholder in prompt
+- [x] Commands with `disable-model-invocation: true` are still included (TOML commands are prompts, not code)
+- [x] Skills copied to `.gemini/skills/` (identical format)
+- [x] MCP servers written to `.gemini/settings.json` under `mcpServers` key
+- [x] Existing `.gemini/settings.json` is backed up before overwrite, and MCP config is merged (not clobbered)
+- [x] Content transformation rewrites `.claude/` and `~/.claude/` paths to `.gemini/` and `~/.gemini/`
+- [x] `/workflows:plan` transformed to `/workflows:plan` (Gemini preserves colon namespacing via directories)
+- [x] `Task agent-name(args)` transformed to `Use the agent-name skill to: args`
+- [x] Plugins with hooks emit `console.warn` about format differences
+- [x] Writer does not double-nest `.gemini/.gemini/`
+- [x] `model` and `allowedTools` fields silently dropped (no Gemini equivalent in skills/commands)
+- [x] Converter and writer tests pass
+- [x] Existing tests still pass (`bun test`)
+
+## Implementation
+
+### Phase 1: Types
+
+**Create `src/types/gemini.ts`**
+
+```typescript
+export type GeminiSkill = {
+  name: string
+  content: string // Full SKILL.md with YAML frontmatter
+}
+
+export type GeminiSkillDir = {
+  name: string
+  sourceDir: string
+}
+
+export type GeminiCommand = {
+  name: string       // e.g. "plan" or "workflows/plan"
+  content: string    // Full TOML content
+}
+
+export type GeminiBundle = {
+  generatedSkills: GeminiSkill[]     // From agents
+  skillDirs: GeminiSkillDir[]         // From skills (pass-through)
+  commands: GeminiCommand[]
+  mcpServers?: Record<string, {
+    command?: string
+    args?: string[]
+    env?: Record<string, string>
+    url?: string
+    headers?: Record<string, string>
+  }>
+}
+```
+
+### Phase 2: Converter
+
+**Create `src/converters/claude-to-gemini.ts`**
+
+Core functions:
+
+1. **`convertClaudeToGemini(plugin, options)`** -- main entry point
+   - Convert each agent to a skill via `convertAgentToSkill()`
+   - Convert each command via `convertCommand()`
+   - Pass skills through as directory references
+   - Convert MCP servers to settings-compatible object
+   - Emit `console.warn` if `plugin.hooks` has entries
+
+2. **`convertAgentToSkill(agent)`** -- agent -> SKILL.md
+   - Frontmatter: `name` (from agent name), `description` (from agent description, max ~300 chars)
+   - Body: agent body with content transformations applied
+   - Prepend capabilities section if present
+   - Silently drop `model` field (no Gemini equivalent)
+   - If description is empty, generate from agent name: `"Use this skill for ${agent.name} tasks"`
+
+3. **`convertCommand(command, usedNames)`** -- command -> TOML file
+   - Preserve namespace structure: `workflows:plan` -> path `workflows/plan`
+   - `description` field from command description
+   - `prompt` field from command body with content transformations
+   - If command has `argument-hint`, append `\n\nUser request: {{args}}` to prompt
+   - Body: apply `transformContentForGemini()` transformations
+   - Silently drop `allowedTools` (no Gemini equivalent)
+
+4. **`transformContentForGemini(body)`** -- content rewriting
+   - `.claude/` -> `.gemini/` and `~/.claude/` -> `~/.gemini/`
+   - `Task agent-name(args)` -> `Use the agent-name skill to: args`
+   - `@agent-name` references -> `the agent-name skill`
+   - Skip file paths (containing `/`) and common non-command patterns
+
+5. **`convertMcpServers(servers)`** -- MCP config
+   - Map each `ClaudeMcpServer` entry to Gemini-compatible JSON
+   - Pass through: `command`, `args`, `env`, `url`, `headers`
+   - Drop `type` field (Gemini infers transport)
+
+6. **`toToml(description, prompt)`** -- TOML serializer
+   - Escape TOML strings properly
+   - Use multi-line strings (`"""`) for prompt field
+   - Simple string for description
+
+### Phase 3: Writer
+
+**Create `src/targets/gemini.ts`**
+
+Output structure:
+
+```
+.gemini/
+├── commands/
+│   ├── plan.toml
+│   └── workflows/
+│       └── plan.toml
+├── skills/
+│   ├── agent-name-1/
+│   │   └── SKILL.md
+│   ├── agent-name-2/
+│   │   └── SKILL.md
+│   └── original-skill/
+│       └── SKILL.md
+└── settings.json          (only mcpServers key)
+```
+
+Core function: `writeGeminiBundle(outputRoot, bundle)`
+
+- `resolveGeminiPaths(outputRoot)` -- detect if path already ends in `.gemini` to avoid double-nesting (follow droid writer pattern)
+- Write generated skills to `skills/<name>/SKILL.md`
+- Copy original skill directories to `skills/` via `copyDir()`
+- Write commands to `commands/` as `.toml` files, creating subdirectories for namespaced commands
+- Write `settings.json` with `{ "mcpServers": {...} }` via `writeJson()` with `backupFile()` for existing files
+- If settings.json exists, read it first and merge `mcpServers` key (don't clobber other settings)
+
+### Phase 4: Wire into CLI
+
+**Modify `src/targets/index.ts`**
+
+```typescript
+import { convertClaudeToGemini } from "../converters/claude-to-gemini"
+import { writeGeminiBundle } from "./gemini"
+import type { GeminiBundle } from "../types/gemini"
+
+// Add to targets:
+gemini: {
+  name: "gemini",
+  implemented: true,
+  convert: convertClaudeToGemini as TargetHandler<GeminiBundle>["convert"],
+  write: writeGeminiBundle as TargetHandler<GeminiBundle>["write"],
+},
+```
+
+**Modify `src/commands/convert.ts`**
+
+- Update `--to` description: `"Target format (opencode | codex | droid | cursor | pi | gemini)"`
+- Add to `resolveTargetOutputRoot`: `if (targetName === "gemini") return path.join(outputRoot, ".gemini")`
+
+**Modify `src/commands/install.ts`**
+
+- Same two changes as convert.ts
+
+### Phase 5: Tests
+
+**Create `tests/gemini-converter.test.ts`**
+
+Test cases (use inline `ClaudePlugin` fixtures, following existing converter test patterns):
+
+- Agent converts to skill with SKILL.md frontmatter (`name` and `description` populated)
+- Agent with empty description gets default description text
+- Agent with capabilities prepended to body
+- Agent `model` field silently dropped
+- Agent with empty body gets default body text
+- Command converts to TOML with `prompt` and `description` fields
+- Namespaced command creates correct path (`workflows:plan` -> `workflows/plan`)
+- Command with `disable-model-invocation` is still included
+- Command `allowedTools` silently dropped
+- Command with `argument-hint` gets `{{args}}` placeholder in prompt
+- Skills pass through as directory references
+- MCP servers convert to settings.json-compatible config
+- Content transformation: `.claude/` paths -> `.gemini/`
+- Content transformation: `~/.claude/` paths -> `~/.gemini/`
+- Content transformation: `Task agent(args)` -> natural language skill reference
+- Hooks present -> `console.warn` emitted
+- Plugin with zero agents produces empty generatedSkills array
+- Plugin with only skills works correctly
+- TOML output is valid (description and prompt properly escaped)
+
+**Create `tests/gemini-writer.test.ts`**
+
+Test cases (use temp directories, following existing writer test patterns):
+
+- Full bundle writes skills, commands, settings.json
+- Generated skills written as `skills/<name>/SKILL.md`
+- Original skills copied to `skills/` directory
+- Commands written as `.toml` files in `commands/` directory
+- Namespaced commands create subdirectories (`commands/workflows/plan.toml`)
+- MCP config written as valid JSON `settings.json` with `mcpServers` key
+- Existing `settings.json` is backed up before overwrite
+- Output root already ending in `.gemini` does NOT double-nest
+- Empty bundle produces no output
+
+### Phase 6: Documentation
+
+**Create `docs/specs/gemini.md`**
+
+Document the Gemini CLI spec as reference, following existing `docs/specs/codex.md` pattern:
+
+- GEMINI.md context file format
+- Custom commands format (TOML with `prompt`, `description`)
+- Skills format (identical SKILL.md standard)
+- MCP server configuration (`settings.json`)
+- Extensions system (for reference, not converted)
+- Hooks system (for reference, format differences noted)
+- Config file locations (user-level `~/.gemini/` vs project-level `.gemini/`)
+- Directory layout conventions
+
+**Update `README.md`**
+
+Add `gemini` to the supported targets in the CLI usage section.
+
+## What We're NOT Doing
+
+- Not converting hooks (Gemini has hooks but different format -- `BeforeTool`/`AfterTool` with matchers -- warn and skip)
+- Not generating full `settings.json` (only `mcpServers` key -- user-specific settings like `model`, `tools.sandbox` are out of scope)
+- Not creating extensions (extension format is for distributing packages, not for converted plugins)
+- Not using `@{file}` or `!{shell}` placeholders in converted commands (would require analyzing command intent)
+- Not transforming content inside copied SKILL.md files (known limitation -- skills may reference `.claude/` paths internally)
+- Not clearing old output before writing (matches existing target behavior)
+- Not merging into existing settings.json intelligently beyond `mcpServers` key (too risky to modify user config)
+
+## Complexity Assessment
+
+This is a **medium change**. The converter architecture is well-established with five existing targets, so this is mostly pattern-following. The key novelties are:
+
+1. The TOML command format (unique among all targets -- need simple TOML serializer)
+2. Agents map to skills rather than a direct 1:1 concept (but this is the same pattern as codex)
+3. Namespaced commands use directory structure (new approach vs flattening in cursor/codex)
+4. MCP config goes into a broader `settings.json` file (need to merge, not clobber)
+
+Skills being identical across platforms simplifies things significantly. The TOML serialization is simple (only two fields: `description` string and `prompt` multi-line string).
+
+## References
+
+- [Gemini CLI Repository](https://github.com/google-gemini/gemini-cli)
+- [Gemini CLI Configuration](https://geminicli.com/docs/get-started/configuration/)
+- [Custom Commands (TOML)](https://geminicli.com/docs/cli/custom-commands/)
+- [Agent Skills](https://geminicli.com/docs/cli/skills/)
+- [Creating Skills](https://geminicli.com/docs/cli/creating-skills/)
+- [Extensions](https://geminicli.com/docs/extensions/writing-extensions/)
+- [MCP Servers](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html)
+- Existing cursor plan: `docs/plans/2026-02-12-feat-add-cursor-cli-target-provider-plan.md`
+- Existing codex converter: `src/converters/claude-to-codex.ts` (has `uniqueName()` and skill generation patterns)
+- Existing droid writer: `src/targets/droid.ts` (has double-nesting guard pattern)
+- Target registry: `src/targets/index.ts`
+
+## Completion Summary
+
+### What Was Delivered
+- [x] Phase 1: Types (`src/types/gemini.ts`)
+- [x] Phase 2: Converter (`src/converters/claude-to-gemini.ts`)
+- [x] Phase 3: Writer (`src/targets/gemini.ts`)
+- [x] Phase 4: CLI wiring (`src/targets/index.ts`, `src/commands/convert.ts`, `src/commands/install.ts`)
+- [x] Phase 5: Tests (`tests/gemini-converter.test.ts`, `tests/gemini-writer.test.ts`)
+- [x] Phase 6: Documentation (`docs/specs/gemini.md`, `README.md`)
+
+### Implementation Statistics
+- 10 files changed
+- 27 new tests added (129 total, all passing)
+- 148 output files generated from compound-engineering plugin conversion
+- 0 dependencies added
+
+### Git Commits
+- `201ad6d` feat(gemini): add Gemini CLI as sixth target provider
+- `8351851` docs: add Gemini CLI spec and update README with gemini target
+
+### Completion Details
+- **Completed By:** Claude Opus 4.6
+- **Date:** 2026-02-14
+- **Session:** Single session

docs/specs/cursor.md

@@ -0,0 +1,85 @@
+# Cursor Spec (Rules, Commands, Skills, MCP)
+
+Last verified: 2026-02-12
+
+## Primary sources
+
+```
+https://docs.cursor.com/context/rules
+https://docs.cursor.com/context/rules-for-ai
+https://docs.cursor.com/customize/model-context-protocol
+```
+
+## Config locations
+
+| Scope | Path |
+|-------|------|
+| Project rules | `.cursor/rules/*.mdc` |
+| Project commands | `.cursor/commands/*.md` |
+| Project skills | `.cursor/skills/*/SKILL.md` |
+| Project MCP | `.cursor/mcp.json` |
+| Project CLI permissions | `.cursor/cli.json` |
+| Global MCP | `~/.cursor/mcp.json` |
+| Global CLI config | `~/.cursor/cli-config.json` |
+| Legacy rules | `.cursorrules` (deprecated) |
+
+## Rules (.mdc files)
+
+- Rules are Markdown files with the `.mdc` extension stored in `.cursor/rules/`.
+- Each rule has YAML frontmatter with three fields: `description`, `globs`, `alwaysApply`.
+- Rules have four activation types based on frontmatter configuration:
+
+| Type | `alwaysApply` | `globs` | `description` | Behavior |
+|------|:---:|:---:|:---:|---|
+| Always | `true` | ignored | optional | Included in every conversation |
+| Auto Attached | `false` | set | optional | Included when matching files are in context |
+| Agent Requested | `false` | empty | set | AI decides based on description relevance |
+| Manual | `false` | empty | empty | Only included via `@rule-name` mention |
+
+- Precedence: Team Rules > Project Rules > User Rules > Legacy `.cursorrules` > `AGENTS.md`.
+
+## Commands (slash commands)
+
+- Custom commands are Markdown files stored in `.cursor/commands/`.
+- Commands are plain markdown with no YAML frontmatter support.
+- The filename (without `.md`) becomes the command name.
+- Commands are invoked by typing `/` in the chat UI.
+- Commands support parameterized arguments via `$1`, `$2`, etc.
+
+## Skills (Agent Skills)
+
+- Skills follow the open SKILL.md standard, identical to Claude Code and Codex.
+- A skill is a folder containing `SKILL.md` plus optional `scripts/`, `references/`, and `assets/`.
+- `SKILL.md` uses YAML frontmatter with required `name` and `description` fields.
+- Skills can be repo-scoped in `.cursor/skills/` or user-scoped in `~/.cursor/skills/`.
+- At startup, only each skill's name/description is loaded; full content is injected on invocation.
+
+## MCP (Model Context Protocol)
+
+- MCP configuration lives in `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global).
+- Each server is configured under the `mcpServers` key.
+- STDIO servers support `command` (required), `args`, and `env`.
+- Remote servers support `url` (required) and optional `headers`.
+- Cursor infers transport type from whether `command` or `url` is present.
+
+Example:
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "npx",
+      "args": ["-y", "package-name"],
+      "env": { "KEY": "value" }
+    }
+  }
+}
+```
+
+## CLI (cursor-agent)
+
+- Cursor CLI launched August 2025 as `cursor-agent`.
+- Supports interactive mode, headless mode (`-p`), and cloud agents.
+- Reads `.cursor/rules/`, `.cursorrules`, and `AGENTS.md` for instructions.
+- CLI permissions controlled via `.cursor/cli.json` with allow/deny lists.
+- Permission tokens: `Shell(command)`, `Read(path)`, `Write(path)`, `Delete(path)`, `Grep(path)`, `LS(path)`.

docs/specs/gemini.md

@@ -0,0 +1,122 @@
+# Gemini CLI Spec (GEMINI.md, Commands, Skills, MCP, Settings)
+
+Last verified: 2026-02-14
+
+## Primary sources
+
+```
+https://github.com/google-gemini/gemini-cli
+https://geminicli.com/docs/get-started/configuration/
+https://geminicli.com/docs/cli/custom-commands/
+https://geminicli.com/docs/cli/skills/
+https://geminicli.com/docs/cli/creating-skills/
+https://geminicli.com/docs/extensions/writing-extensions/
+https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html
+```
+
+## Config locations
+
+- User-level config: `~/.gemini/settings.json`
+- Project-level config: `.gemini/settings.json`
+- Project-level takes precedence over user-level for most settings.
+- GEMINI.md context file lives at project root (similar to CLAUDE.md).
+
+## GEMINI.md context file
+
+- A markdown file at project root loaded into every session's context.
+- Used for project-wide instructions, coding standards, and conventions.
+- Equivalent to Claude Code's CLAUDE.md.
+
+## Custom commands (TOML format)
+
+- Custom commands are TOML files stored in `.gemini/commands/`.
+- Command name is derived from the file path: `.gemini/commands/git/commit.toml` becomes `/git:commit`.
+- Directory-based namespacing: subdirectories create namespaced commands.
+- Each command file has two fields:
+  - `description` (string): One-line description shown in `/help`
+  - `prompt` (string): The prompt sent to the model
+- Supports placeholders:
+  - `{{args}}` — user-provided arguments
+  - `!{shell}` — output of a shell command
+  - `@{file}` — contents of a file
+- Example:
+
+```toml
+description = "Create a git commit with a good message"
+prompt = """
+Look at the current git diff and create a commit with a descriptive message.
+
+User request: {{args}}
+"""
+```
+
+## Skills (SKILL.md standard)
+
+- A skill is a folder containing `SKILL.md` plus optional supporting files.
+- Skills live in `.gemini/skills/`.
+- `SKILL.md` uses YAML frontmatter with `name` and `description` fields.
+- Gemini activates skills on demand via `activate_skill` tool based on description matching.
+- The `description` field is critical — Gemini uses it to decide when to activate the skill.
+- Format is identical to Claude Code's SKILL.md standard.
+- Example:
+
+```yaml
+---
+name: security-reviewer
+description: Review code for security vulnerabilities and OWASP compliance
+---
+
+# Security Reviewer
+
+Detailed instructions for security review...
+```
+
+## MCP server configuration
+
+- MCP servers are configured in `settings.json` under the `mcpServers` key.
+- Same MCP protocol as Claude Code; different config location.
+- Supports `command`, `args`, `env` for stdio transport.
+- Supports `url`, `headers` for HTTP/SSE transport.
+- Additional Gemini-specific fields: `cwd`, `timeout`, `trust`, `includeTools`, `excludeTools`.
+- Example:
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "url": "https://mcp.context7.com/mcp"
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/mcp-playwright"]
+    }
+  }
+}
+```
+
+## Hooks
+
+- Gemini supports hooks: `BeforeTool`, `AfterTool`, `SessionStart`, etc.
+- Hooks use a different format from Claude Code hooks (matchers-based).
+- Not converted by the plugin converter — a warning is emitted.
+
+## Extensions
+
+- Extensions are distributable packages for Gemini CLI.
+- They extend functionality with custom tools, hooks, and commands.
+- Not used for plugin conversion (different purpose from Claude Code plugins).
+
+## Settings.json structure
+
+```json
+{
+  "model": "gemini-2.5-pro",
+  "mcpServers": { ... },
+  "tools": {
+    "sandbox": true
+  }
+}
+```
+
+- Only the `mcpServers` key is written during plugin conversion.
+- Other settings (model, tools, sandbox) are user-specific and out of scope.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@every-env/compound-plugin",
-  "version": "0.1.1",
+  "version": "0.7.0",
   "type": "module",
   "private": false,
   "bin": {

plans/grow-your-own-garden-plugin-architecture.md

@@ -1,6 +1,6 @@
 # Grow Your Own Garden: Adaptive Agent Ecosystem
 
-> **Issue:** https://github.com/kieranklaassen/compound-engineering-plugin/issues/20
+> **Issue:** https://github.com/EveryInc/compound-engineering-plugin/issues/20
 
 ## The Idea
 

plugins/compound-engineering/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "compound-engineering",
-  "version": "2.30.0",
-  "description": "AI-powered development tools. 27 agents, 25 commands, 15 skills, 1 MCP server for code review, research, design, and workflow automation.",
+  "version": "2.35.0",
+  "description": "AI-powered development tools. 25 agents, 23 commands, 18 skills, 1 MCP server for code review, research, design, and workflow automation.",
   "author": {
     "name": "Kieran Klaassen",
     "email": "kieran@every.to",

plugins/compound-engineering/CHANGELOG.md

@@ -5,79 +5,149 @@ 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.30.0] - 2026-02-03
-
-### Added
-
-- **`/pr-comments-to-todos` command** - Fetch PR review comments and convert them into todo files for triage
-  - Fetches all comments from a GitHub PR using `gh` CLI
-  - Converts each actionable comment into a structured todo file following the file-todos skill format
-  - Assigns priority levels (P1/P2/P3) based on comment severity
-  - Creates todo files compatible with `/triage` command for approval workflow
-  - Skips non-actionable comments (LGTM, resolved threads, etc.)
-  - Supports PR number, GitHub URL, or "current" for current branch
-
-### Summary
-
-- 27 agents, 25 commands, 15 skills, 1 MCP server
-
----
-
-## [2.29.0] - 2026-01-26
+## [2.35.0] - 2026-02-16
 
 ### Changed
 
-- **Backend focus shift: Ruby/Rails → Python/FastAPI** - Comprehensive conversion of backend-focused components
+- **Backend focus shift: Ruby/Rails -> Python/FastAPI** - Comprehensive conversion of backend-focused components
   - All backend-related agents and skills now target Python/FastAPI instead of Ruby/Rails
   - TypeScript/React frontend components remain unchanged
 
 ### Added
 
 - **`tiangolo-fastapi-reviewer` agent** - FastAPI code review from Sebastián Ramírez's perspective
-  - Reviews for Pydantic model patterns, async/await discipline, dependency injection
-  - Identifies Flask/Django patterns contaminating FastAPI codebases
-  - Enforces OpenAPI schema design and type hints
-
 - **`python-package-readme-writer` agent** - Create concise READMEs for Python packages
-  - Follows modern Python packaging conventions (pyproject.toml, src layout)
-  - Targets PyPI publication with pip/uv/poetry installation instructions
-
 - **`fastapi-style` skill** - Write FastAPI code following opinionated best practices
-  - Thin routers, rich Pydantic models with validation
-  - SQLAlchemy 2.0 async patterns, dependency injection
-  - References for routers, models, database, testing, security, background tasks
-
 - **`python-package-writer` skill** - Write Python packages following production-ready patterns
-  - Modern packaging with pyproject.toml, src layout, pytest
-  - Zero or minimal dependencies philosophy
-  - Type hints, configuration patterns, FastAPI integration
-
-- **`dspy-python` skill** - Build LLM applications with DSPy framework
-  - Signature-based prompting, teleprompter optimization
-  - FastAPI integration patterns, pytest testing
-  - Replaced dspy-ruby skill
-
-- **Enhanced `kieran-python-reviewer` agent** - Now includes FastAPI-specific sections
-  - Pydantic model patterns, async/await discipline
-  - Dependency injection, OpenAPI schema design
-  - SQLAlchemy 2.0 async, router organization, security patterns
-
+- **Enhanced `kieran-python-reviewer` agent** - Now includes 9 FastAPI-specific convention sections
 - **Updated `lint` agent** - Now targets Python files
-  - Uses ruff for linting/formatting, mypy for type checking
-  - bandit for security scanning, djlint for Jinja2 templates
+- **`/pr-comments-to-todos` command** - Fetch PR review comments and convert them into todo files for triage
+- **Pressure Test framework** in workflows:review - Critical evaluation of agent findings before creating todos
 
 ### Removed
 
 - **`dhh-rails-reviewer` agent** - Replaced by tiangolo-fastapi-reviewer
 - **`kieran-rails-reviewer` agent** - Functionality merged into kieran-python-reviewer
 - **`ankane-readme-writer` agent** - Replaced by python-package-readme-writer
+- **3 design agents** - design-implementation-reviewer, design-iterator, figma-design-sync
 - **`dhh-rails-style` skill** - Replaced by fastapi-style
 - **`andrew-kane-gem-writer` skill** - Replaced by python-package-writer
-- **`dspy-ruby` skill** - Replaced by dspy-python
+- **`dspy-ruby` skill** - Removed (not used; LangChain/LangGraph is the actual stack)
+- **`dspy-python` skill** - Removed (not used; LangChain/LangGraph is the actual stack)
+- **`/plan_review` command** - Absorbed into workflows/plan via document-review skill
 
-### Summary
+---
 
-- 27 agents, 24 commands, 15 skills, 1 MCP server
+## [2.34.0] - 2026-02-14
+
+### Added
+
+- **Gemini CLI target** — New converter target for [Gemini CLI](https://github.com/google-gemini/gemini-cli). Install with `--to gemini` to convert agents to `.gemini/skills/*/SKILL.md`, commands to `.gemini/commands/*.toml` (TOML format with `description` + `prompt`), and MCP servers to `.gemini/settings.json`. Skills pass through unchanged (identical SKILL.md standard). Namespaced commands create directory structure (`workflows:plan` → `commands/workflows/plan.toml`). 29 new tests. ([#190](https://github.com/EveryInc/compound-engineering-plugin/pull/190))
+
+---
+
+## [2.33.1] - 2026-02-13
+
+### Changed
+
+- **`/workflows:plan` command** - All plan templates now include `status: active` in YAML frontmatter. Plans are created with `status: active` and marked `status: completed` when work finishes.
+- **`/workflows:work` command** - Phase 4 now updates plan frontmatter from `status: active` to `status: completed` after shipping. Agents can grep for status to distinguish current vs historical plans.
+
+---
+
+## [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
+
+- **Factory Droid target** — New converter target for [Factory Droid](https://docs.factory.ai). Install with `--to droid` to output agents, commands, and skills to `~/.factory/`. Includes tool name mapping (Claude → Factory), namespace prefix stripping, Task syntax conversion, and agent reference rewriting. 13 new tests (9 converter + 4 writer). ([#174](https://github.com/EveryInc/compound-engineering-plugin/pull/174))
+
+---
+
+## [2.31.1] - 2026-02-09
+
+### Changed
+
+- **`dspy-ruby` skill** — Complete rewrite to DSPy.rb v0.34.3 API: `.call()` / `result.field` patterns, `T::Enum` classes, `DSPy::Tools::Base` / `Toolset`. Added events system, lifecycle callbacks, fiber-local LM context, GEPA optimization, evaluation framework, typed context pattern, BAML/TOON schema formats, storage system, score reporting, RubyLLM adapter. 5 reference files (2 new: toolsets, observability), 3 asset templates rewritten.
+
+## [2.31.0] - 2026-02-08
+
+### Added
+
+- **`document-review` skill** — Brainstorm and plan refinement through structured review ([@Trevin Chow](https://github.com/trevin))
+- **`/sync` command** — Sync Claude Code personal config across machines ([@Terry Li](https://github.com/terryli))
+
+### Changed
+
+- **Context token optimization (79% reduction)** — Plugin was consuming 316% of the context description budget, causing Claude Code to silently exclude components. Now at 65% with room to grow:
+  - All 29 agent descriptions trimmed from ~1,400 to ~180 chars avg (examples moved to agent body)
+  - 18 manual commands marked `disable-model-invocation: true` (side-effect commands like `/lfg`, `/deploy-docs`, `/triage`, etc.)
+  - 6 manual skills marked `disable-model-invocation: true` (`orchestrating-swarms`, `git-worktree`, `skill-creator`, `compound-docs`, `file-todos`, `resolve-pr-parallel`)
+- **git-worktree**: Remove confirmation prompt for worktree creation ([@Sam Xie](https://github.com/samxie))
+- **Prevent subagents from writing intermediary files** in compound workflow ([@Trevin Chow](https://github.com/trevin))
+
+### Fixed
+
+- Fix crash when hook entries have no matcher ([@Roberto Mello](https://github.com/robertomello))
+- Fix git-worktree detection where `.git` is a file, not a directory ([@David Alley](https://github.com/davidalley))
+- Backup existing config files before overwriting in sync ([@Zac Williams](https://github.com/zacwilliams))
+- Note new repository URL ([@Aarni Koskela](https://github.com/aarnikoskela))
+- Plugin component counts corrected: 29 agents, 24 commands, 18 skills
+
+---
+
+## [2.30.0] - 2026-02-05
+
+### Added
+
+- **`orchestrating-swarms` skill** - Comprehensive guide to multi-agent orchestration
+  - Covers primitives: Agent, Team, Teammate, Leader, Task, Inbox, Message, Backend
+  - Documents two spawning methods: subagents vs teammates
+  - Explains all 13 TeammateTool operations
+  - Includes orchestration patterns: Parallel Specialists, Pipeline, Self-Organizing Swarm
+  - Details spawn backends: in-process, tmux, iterm2
+  - Provides complete workflow examples
+- **`/slfg` command** - Swarm-enabled variant of `/lfg` that uses swarm mode for parallel execution
+
+### Changed
+
+- **`/workflows:work` command** - Added optional Swarm Mode section for parallel execution with coordinated agents
+
+---
+
+## [2.29.0] - 2026-02-04
+
+### Added
+
+- **`schema-drift-detector` agent** - Detects unrelated schema.rb changes in PRs
+  - Compares schema.rb diff against migrations in the PR
+  - Catches columns, indexes, and tables from other branches
+  - Prevents accidental inclusion of local database state
+  - Provides clear fix instructions (checkout + migrate)
+  - Essential pre-merge check for any PR with database changes
 
 ---
 

plugins/compound-engineering/CLAUDE.md

@@ -59,7 +59,7 @@ When adding or modifying skills, verify compliance with skill-creator spec:
 ### YAML Frontmatter (Required)
 
 - [ ] `name:` present and matches directory name (lowercase-with-hyphens)
-- [ ] `description:` present and uses **third person** ("This skill should be used when..." NOT "Use this skill when...")
+- [ ] `description:` present and describes **what it does and when to use it** (per official spec: "Explains code with diagrams. Use when exploring how code works.")
 
 ### Reference Links (Required if references/ exists)
 
@@ -80,9 +80,8 @@ When adding or modifying skills, verify compliance with skill-creator spec:
 grep -E '`(references|assets|scripts)/[^`]+`' skills/*/SKILL.md
 # Should return nothing if all refs are properly linked
 
-# Check description format
-grep -E '^description:' skills/*/SKILL.md | grep -v 'This skill'
-# Should return nothing if all use third person
+# Check description format - should describe what + when
+grep -E '^description:' skills/*/SKILL.md
 ```
 
 ## Documentation

plugins/compound-engineering/README.md

@@ -6,16 +6,16 @@ AI-powered development tools that get smarter with every use. Make each unit of
 
 | Component | Count |
 |-----------|-------|
-| Agents | 27 |
-| Commands | 24 |
-| Skills | 15 |
+| Agents | 25 |
+| Commands | 23 |
+| Skills | 18 |
 | MCP Servers | 1 |
 
 ## Agents
 
 Agents are organized into categories for easier discovery.
 
-### Review (13)
+### Review (14)
 
 | Agent | Description |
 |-------|-------------|
@@ -25,13 +25,14 @@ Agents are organized into categories for easier discovery.
 | `data-integrity-guardian` | Database migrations and data integrity |
 | `data-migration-expert` | Validate ID mappings match production, check for swapped values |
 | `deployment-verification-agent` | Create Go/No-Go deployment checklists for risky data changes |
-| `kieran-python-reviewer` | Python/FastAPI code review with strict conventions |
+| `julik-frontend-races-reviewer` | Review JavaScript/Stimulus code for race conditions |
+| `kieran-python-reviewer` | Python code review with strict conventions |
 | `kieran-typescript-reviewer` | TypeScript code review with strict conventions |
-| `tiangolo-fastapi-reviewer` | FastAPI review from Sebastián Ramírez's perspective |
 | `pattern-recognition-specialist` | Analyze code for patterns and anti-patterns |
 | `performance-oracle` | Performance analysis and optimization |
+| `schema-drift-detector` | Detect unrelated schema changes in PRs |
 | `security-sentinel` | Security audits and vulnerability assessments |
-| `julik-frontend-races-reviewer` | Review JavaScript/Stimulus code for race conditions |
+| `tiangolo-fastapi-reviewer` | FastAPI code review from tiangolo's perspective |
 
 ### Research (5)
 
@@ -40,17 +41,9 @@ Agents are organized into categories for easier discovery.
 | `best-practices-researcher` | Gather external best practices and examples |
 | `framework-docs-researcher` | Research framework documentation and best practices |
 | `git-history-analyzer` | Analyze git history and code evolution |
-| `learnings-researcher` | Research and extract learnings from documentation |
+| `learnings-researcher` | Search institutional learnings for relevant past solutions |
 | `repo-research-analyst` | Research repository structure and conventions |
 
-### Design (3)
-
-| Agent | Description |
-|-------|-------------|
-| `design-implementation-reviewer` | Verify UI implementations match Figma designs |
-| `design-iterator` | Iteratively refine UI through systematic design iterations |
-| `figma-design-sync` | Synchronize web implementations with Figma designs |
-
 ### Workflow (5)
 
 | Agent | Description |
@@ -65,7 +58,7 @@ Agents are organized into categories for easier discovery.
 
 | Agent | Description |
 |-------|-------------|
-| `python-package-readme-writer` | Create concise READMEs for Python packages |
+| `python-package-readme-writer` | Create READMEs following concise documentation style for Python packages |
 
 ## Commands
 
@@ -85,25 +78,24 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in
 
 | Command | Description |
 |---------|-------------|
-| `/agent-native-audit` | Run comprehensive agent-native architecture review with scored principles |
+| `/lfg` | Full autonomous engineering workflow |
+| `/slfg` | Full autonomous workflow with swarm mode for parallel execution |
+| `/deepen-plan` | Enhance plans with parallel research agents for each section |
 | `/changelog` | Create engaging changelogs for recent merges |
 | `/create-agent-skill` | Create or edit Claude Code skills |
-| `/deepen-plan` | Enhance plans with parallel research agents for each section |
-| `/deploy-docs` | Validate and prepare documentation for GitHub Pages deployment |
-| `/feature-video` | Record video walkthroughs and add to PR description |
 | `/generate_command` | Generate new slash commands |
 | `/heal-skill` | Fix skill documentation issues |
-| `/lfg` | Full autonomous engineering workflow |
-| `/plan_review` | Multi-agent plan review in parallel |
-| `/release-docs` | Build and update the documentation site with current plugin components |
 | `/report-bug` | Report a bug in the plugin |
 | `/reproduce-bug` | Reproduce bugs using logs and console |
 | `/resolve_parallel` | Resolve TODO comments in parallel |
-| `/resolve_pr_parallel` | Resolve PR comments in parallel |
 | `/resolve_todo_parallel` | Resolve todos in parallel |
-| `/test-browser` | Run browser tests on PR-affected pages |
 | `/triage` | Triage and prioritize issues |
-| `/xcode-test` | Build and test iOS apps on simulator |
+| `/test-browser` | Run browser tests on PR-affected pages |
+| `/test-xcode` | Build and test iOS apps on simulator |
+| `/feature-video` | Record video walkthroughs and add to PR description |
+| `/agent-native-audit` | Run comprehensive agent-native architecture review |
+| `/deploy-docs` | Validate and prepare documentation for GitHub Pages |
+| `/pr-comments-to-todos` | Fetch PR comments and convert to todo files |
 
 ## Skills
 
@@ -119,8 +111,7 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in
 |-------|-------------|
 | `compound-docs` | Capture solved problems as categorized documentation |
 | `create-agent-skills` | Expert guidance for creating Claude Code skills |
-| `dspy-python` | Build LLM applications with DSPy framework |
-| `fastapi-style` | Write FastAPI code following opinionated best practices |
+| `fastapi-style` | Write Python/FastAPI code following opinionated best practices |
 | `frontend-design` | Create production-grade frontend interfaces |
 | `python-package-writer` | Write Python packages following production-ready patterns |
 | `skill-creator` | Guide for creating effective Claude Code skills |
@@ -129,10 +120,19 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in
 
 | Skill | Description |
 |-------|-------------|
-| `brainstorming` | Explore requirements and approaches before planning |
+| `brainstorming` | Explore requirements and approaches through collaborative dialogue |
+| `document-review` | Improve documents through structured self-review |
 | `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
+
+| Skill | Description |
+|-------|-------------|
+| `orchestrating-swarms` | Comprehensive guide to multi-agent swarm orchestration |
 
 ### File Transfer
 
@@ -174,7 +174,7 @@ Core workflow commands use `workflows:` prefix to avoid collisions with built-in
 - `resolve-library-id` - Find library ID for a framework/package
 - `get-library-docs` - Get documentation for a specific library
 
-Supports 100+ frameworks including Rails, React, Next.js, Vue, Django, Laravel, and more.
+Supports 100+ frameworks including FastAPI, React, Next.js, Vue, Django, SQLAlchemy, and more.
 
 MCP servers start automatically when the plugin is enabled.
 

plugins/compound-engineering/agents/research/best-practices-researcher.md

@@ -1,9 +1,24 @@
 ---
 name: best-practices-researcher
-description: "Use this agent when you need to research and gather external best practices, documentation, and examples for any technology, framework, or development practice. This includes finding official documentation, community standards, well-regarded examples from open source projects, and domain-specific conventions. The agent excels at synthesizing information from multiple sources to provide comprehensive guidance on how to implement features or solve problems according to industry standards. <example>Context: User wants to know the best way to structure GitHub issues for their FastAPI project. user: \"I need to create some GitHub issues for our project. Can you research best practices for writing good issues?\" assistant: \"I'll use the best-practices-researcher agent to gather comprehensive information about GitHub issue best practices, including examples from successful projects and FastAPI-specific conventions.\" <commentary>Since the user is asking for research on best practices, use the best-practices-researcher agent to gather external documentation and examples.</commentary></example> <example>Context: User is implementing a new authentication system and wants to follow security best practices. user: \"We're adding JWT authentication to our FastAPI API. What are the current best practices?\" assistant: \"Let me use the best-practices-researcher agent to research current JWT authentication best practices, security considerations, and FastAPI-specific implementation patterns.\" <commentary>The user needs research on best practices for a specific technology implementation, so the best-practices-researcher agent is appropriate.</commentary></example>"
+description: "Researches and synthesizes external best practices, documentation, and examples for any technology or framework. Use when you need industry standards, community conventions, or implementation guidance."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: User wants to know the best way to structure GitHub issues for their FastAPI project.
+user: "I need to create some GitHub issues for our project. Can you research best practices for writing good issues?"
+assistant: "I'll use the best-practices-researcher agent to gather comprehensive information about GitHub issue best practices, including examples from successful projects and FastAPI-specific conventions."
+<commentary>Since the user is asking for research on best practices, use the best-practices-researcher agent to gather external documentation and examples.</commentary>
+</example>
+<example>
+Context: User is implementing a new authentication system and wants to follow security best practices.
+user: "We're adding JWT authentication to our FastAPI API. What are the current best practices?"
+assistant: "Let me use the best-practices-researcher agent to research current JWT authentication best practices, security considerations, and FastAPI-specific implementation patterns."
+<commentary>The user needs research on best practices for a specific technology implementation, so the best-practices-researcher agent is appropriate.</commentary>
+</example>
+</examples>
+
 **Note: The current year is 2026.** Use this when searching for recent documentation and best practices.
 
 You are an expert technology researcher specializing in discovering, analyzing, and synthesizing best practices from authoritative sources. Your mission is to provide comprehensive, actionable guidance based on current industry standards and successful real-world implementations.
@@ -21,7 +36,7 @@ Before going online, check if curated knowledge already exists in skills:
 
 2. **Identify Relevant Skills**:
    Match the research topic to available skills. Common mappings:
-   - Rails/Ruby → `dhh-rails-style`, `andrew-kane-gem-writer`, `dspy-ruby`
+   - Python/FastAPI → `fastapi-style`, `python-package-writer`
    - Frontend/Design → `frontend-design`, `swiss-design`
    - TypeScript/React → `react-best-practices`
    - AI/Agents → `agent-native-architecture`, `create-agent-skills`
@@ -79,7 +94,7 @@ Only after checking skills AND verifying API availability, gather additional inf
 
 2. **Organize Discoveries**:
    - Organize into clear categories (e.g., "Must Have", "Recommended", "Optional")
-   - Clearly indicate source: "From skill: dhh-rails-style" vs "From official docs" vs "Community consensus"
+   - Clearly indicate source: "From skill: fastapi-style" vs "From official docs" vs "Community consensus"
    - Provide specific examples from real projects when possible
    - Explain the reasoning behind each best practice
    - Highlight any technology-specific or domain-specific considerations
@@ -102,7 +117,7 @@ For GitHub issue best practices specifically, you will research:
 ## Source Attribution
 
 Always cite your sources and indicate the authority level:
-- **Skill-based**: "The dhh-rails-style skill recommends..." (highest authority - curated)
+- **Skill-based**: "The fastapi-style skill recommends..." (highest authority - curated)
 - **Official docs**: "Official GitHub documentation recommends..."
 - **Community**: "Many successful projects tend to..."
 

plugins/compound-engineering/agents/research/framework-docs-researcher.md

@@ -1,9 +1,24 @@
 ---
 name: framework-docs-researcher
-description: "Use this agent when you need to gather comprehensive documentation and best practices for frameworks, libraries, or dependencies in your project. This includes fetching official documentation, exploring source code, identifying version-specific constraints, and understanding implementation patterns. <example>Context: The user needs to understand how to properly implement a new feature using a specific library. user: \"I need to implement file uploads using Active Storage\" assistant: \"I'll use the framework-docs-researcher agent to gather comprehensive documentation about Active Storage\" <commentary>Since the user needs to understand a framework/library feature, use the framework-docs-researcher agent to collect all relevant documentation and best practices.</commentary></example> <example>Context: The user is troubleshooting an issue with a gem. user: \"Why is the turbo-rails gem not working as expected?\" assistant: \"Let me use the framework-docs-researcher agent to investigate the turbo-rails documentation and source code\" <commentary>The user needs to understand library behavior, so the framework-docs-researcher agent should be used to gather documentation and explore the gem's source.</commentary></example>"
+description: "Gathers comprehensive documentation and best practices for frameworks, libraries, or dependencies. Use when you need official docs, version-specific constraints, or implementation patterns."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user needs to understand how to properly implement a new feature using a specific library.
+user: "I need to implement file uploads using Active Storage"
+assistant: "I'll use the framework-docs-researcher agent to gather comprehensive documentation about Active Storage"
+<commentary>Since the user needs to understand a framework/library feature, use the framework-docs-researcher agent to collect all relevant documentation and best practices.</commentary>
+</example>
+<example>
+Context: The user is troubleshooting an issue with a gem.
+user: "Why is the turbo-rails gem not working as expected?"
+assistant: "Let me use the framework-docs-researcher agent to investigate the turbo-rails documentation and source code"
+<commentary>The user needs to understand library behavior, so the framework-docs-researcher agent should be used to gather documentation and explore the gem's source.</commentary>
+</example>
+</examples>
+
 **Note: The current year is 2026.** Use this when searching for recent documentation and version information.
 
 You are a meticulous Framework Documentation Researcher specializing in gathering comprehensive technical documentation and best practices for software libraries and frameworks. Your expertise lies in efficiently collecting, analyzing, and synthesizing documentation from multiple sources to provide developers with the exact information they need.

plugins/compound-engineering/agents/research/git-history-analyzer.md

@@ -1,9 +1,24 @@
 ---
 name: git-history-analyzer
-description: "Use this agent when you need to understand the historical context and evolution of code changes, trace the origins of specific code patterns, identify key contributors and their expertise areas, or analyze patterns in commit history. This agent excels at archaeological analysis of git repositories to provide insights about code evolution and development patterns. <example>Context: The user wants to understand the history and evolution of recently modified files.\\nuser: \"I've just refactored the authentication module. Can you analyze the historical context?\"\\nassistant: \"I'll use the git-history-analyzer agent to examine the evolution of the authentication module files.\"\\n<commentary>Since the user wants historical context about code changes, use the git-history-analyzer agent to trace file evolution, identify contributors, and extract patterns from the git history.</commentary></example> <example>Context: The user needs to understand why certain code patterns exist.\\nuser: \"Why does this payment processing code have so many try-catch blocks?\"\\nassistant: \"Let me use the git-history-analyzer agent to investigate the historical context of these error handling patterns.\"\\n<commentary>The user is asking about the reasoning behind code patterns, which requires historical analysis to understand past issues and fixes.</commentary></example>"
+description: "Performs archaeological analysis of git history to trace code evolution, identify contributors, and understand why code patterns exist. Use when you need historical context for code changes."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user wants to understand the history and evolution of recently modified files.
+user: "I've just refactored the authentication module. Can you analyze the historical context?"
+assistant: "I'll use the git-history-analyzer agent to examine the evolution of the authentication module files."
+<commentary>Since the user wants historical context about code changes, use the git-history-analyzer agent to trace file evolution, identify contributors, and extract patterns from the git history.</commentary>
+</example>
+<example>
+Context: The user needs to understand why certain code patterns exist.
+user: "Why does this payment processing code have so many try-catch blocks?"
+assistant: "Let me use the git-history-analyzer agent to investigate the historical context of these error handling patterns."
+<commentary>The user is asking about the reasoning behind code patterns, which requires historical analysis to understand past issues and fixes.</commentary>
+</example>
+</examples>
+
 **Note: The current year is 2026.** Use this when interpreting commit dates and recent changes.
 
 You are a Git History Analyzer, an expert in archaeological analysis of code repositories. Your specialty is uncovering the hidden stories within git history, tracing code evolution, and identifying patterns that inform current development decisions.
@@ -40,3 +55,5 @@ When analyzing, consider:
 - The evolution of coding patterns and practices over time
 
 Your insights should help developers understand not just what the code does, but why it evolved to its current state, informing better decisions for future changes.
+
+Note that files in `docs/plans/` and `docs/solutions/` are compound-engineering pipeline artifacts created by `/workflows:plan`. They are intentional, permanent living documents — do not recommend their removal or characterize them as unnecessary.

plugins/compound-engineering/agents/research/learnings-researcher.md

@@ -1,9 +1,30 @@
 ---
 name: learnings-researcher
-description: "Use this agent when you need to search institutional learnings in docs/solutions/ for relevant past solutions before implementing a new feature or fixing a problem. This agent efficiently filters documented solutions by frontmatter metadata (tags, category, module, symptoms) to find applicable patterns, gotchas, and lessons learned. The agent excels at preventing repeated mistakes by surfacing relevant institutional knowledge before work begins.\\n\\n<example>Context: User is about to implement a feature involving email processing.\\nuser: \"I need to add email threading to the brief system\"\\nassistant: \"I'll use the learnings-researcher agent to check docs/solutions/ for any relevant learnings about email processing or brief system implementations.\"\\n<commentary>Since the user is implementing a feature in a documented domain, use the learnings-researcher agent to surface relevant past solutions before starting work.</commentary></example>\\n\\n<example>Context: User is debugging a performance issue.\\nuser: \"Brief generation is slow, taking over 5 seconds\"\\nassistant: \"Let me use the learnings-researcher agent to search for documented performance issues, especially any involving briefs or N+1 queries.\"\\n<commentary>The user has symptoms matching potential documented solutions, so use the learnings-researcher agent to find relevant learnings before debugging.</commentary></example>\\n\\n<example>Context: Planning a new feature that touches multiple modules.\\nuser: \"I need to add Stripe subscription handling to the payments module\"\\nassistant: \"I'll use the learnings-researcher agent to search for any documented learnings about payments, integrations, or Stripe specifically.\"\\n<commentary>Before implementing, check institutional knowledge for gotchas, patterns, and lessons learned in similar domains.</commentary></example>"
+description: "Searches docs/solutions/ for relevant past solutions by frontmatter metadata. Use before implementing features or fixing problems to surface institutional knowledge and prevent repeated mistakes."
 model: haiku
 ---
 
+<examples>
+<example>
+Context: User is about to implement a feature involving email processing.
+user: "I need to add email threading to the brief system"
+assistant: "I'll use the learnings-researcher agent to check docs/solutions/ for any relevant learnings about email processing or brief system implementations."
+<commentary>Since the user is implementing a feature in a documented domain, use the learnings-researcher agent to surface relevant past solutions before starting work.</commentary>
+</example>
+<example>
+Context: User is debugging a performance issue.
+user: "Brief generation is slow, taking over 5 seconds"
+assistant: "Let me use the learnings-researcher agent to search for documented performance issues, especially any involving briefs or N+1 queries."
+<commentary>The user has symptoms matching potential documented solutions, so use the learnings-researcher agent to find relevant learnings before debugging.</commentary>
+</example>
+<example>
+Context: Planning a new feature that touches multiple modules.
+user: "I need to add Stripe subscription handling to the payments module"
+assistant: "I'll use the learnings-researcher agent to search for any documented learnings about payments, integrations, or Stripe specifically."
+<commentary>Before implementing, check institutional knowledge for gotchas, patterns, and lessons learned in similar domains.</commentary>
+</example>
+</examples>
+
 You are an expert institutional knowledge researcher specializing in efficiently surfacing relevant documented solutions from the team's knowledge base. Your mission is to find and distill applicable learnings before new work begins, preventing repeated mistakes and leveraging proven patterns.
 
 ## Search Strategy (Grep-First Filtering)

plugins/compound-engineering/agents/research/repo-research-analyst.md

@@ -1,9 +1,30 @@
 ---
 name: repo-research-analyst
-description: "Use this agent when you need to conduct thorough research on a repository's structure, documentation, and patterns. This includes analyzing architecture files, examining GitHub issues for patterns, reviewing contribution guidelines, checking for templates, and searching codebases for implementation patterns. The agent excels at gathering comprehensive information about a project's conventions and best practices.\\n\\nExamples:\\n- <example>\\n  Context: User wants to understand a new repository's structure and conventions before contributing.\\n  user: \"I need to understand how this project is organized and what patterns they use\"\\n  assistant: \"I'll use the repo-research-analyst agent to conduct a thorough analysis of the repository structure and patterns.\"\\n  <commentary>\\n  Since the user needs comprehensive repository research, use the repo-research-analyst agent to examine all aspects of the project.\\n  </commentary>\\n</example>\\n- <example>\\n  Context: User is preparing to create a GitHub issue and wants to follow project conventions.\\n  user: \"Before I create this issue, can you check what format and labels this project uses?\"\\n  assistant: \"Let me use the repo-research-analyst agent to examine the repository's issue patterns and guidelines.\"\\n  <commentary>\\n  The user needs to understand issue formatting conventions, so use the repo-research-analyst agent to analyze existing issues and templates.\\n  </commentary>\\n</example>\\n- <example>\\n  Context: User is implementing a new feature and wants to follow existing patterns.\\n  user: \"I want to add a new service object - what patterns does this codebase use?\"\\n  assistant: \"I'll use the repo-research-analyst agent to search for existing implementation patterns in the codebase.\"\\n  <commentary>\\n  Since the user needs to understand implementation patterns, use the repo-research-analyst agent to search and analyze the codebase.\\n  </commentary>\\n</example>"
+description: "Conducts thorough research on repository structure, documentation, conventions, and implementation patterns. Use when onboarding to a new codebase or understanding project conventions."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: User wants to understand a new repository's structure and conventions before contributing.
+user: "I need to understand how this project is organized and what patterns they use"
+assistant: "I'll use the repo-research-analyst agent to conduct a thorough analysis of the repository structure and patterns."
+<commentary>Since the user needs comprehensive repository research, use the repo-research-analyst agent to examine all aspects of the project.</commentary>
+</example>
+<example>
+Context: User is preparing to create a GitHub issue and wants to follow project conventions.
+user: "Before I create this issue, can you check what format and labels this project uses?"
+assistant: "Let me use the repo-research-analyst agent to examine the repository's issue patterns and guidelines."
+<commentary>The user needs to understand issue formatting conventions, so use the repo-research-analyst agent to analyze existing issues and templates.</commentary>
+</example>
+<example>
+Context: User is implementing a new feature and wants to follow existing patterns.
+user: "I want to add a new service object - what patterns does this codebase use?"
+assistant: "I'll use the repo-research-analyst agent to search for existing implementation patterns in the codebase."
+<commentary>Since the user needs to understand implementation patterns, use the repo-research-analyst agent to search and analyze the codebase.</commentary>
+</example>
+</examples>
+
 **Note: The current year is 2026.** Use this when searching for recent documentation and patterns.
 
 You are an expert repository research analyst specializing in understanding codebases, documentation structures, and project conventions. Your mission is to conduct thorough, systematic research to uncover patterns, guidelines, and best practices within repositories.

plugins/compound-engineering/agents/review/agent-native-reviewer.md

@@ -1,9 +1,24 @@
 ---
 name: agent-native-reviewer
-description: "Use this agent when reviewing code to ensure features are agent-native - that any action a user can take, an agent can also take, and anything a user can see, an agent can see. This enforces the principle that agents should have parity with users in capability and context. <example>Context: The user added a new feature to their application.\\nuser: \"I just implemented a new email filtering feature\"\\nassistant: \"I'll use the agent-native-reviewer to verify this feature is accessible to agents\"\\n<commentary>New features need agent-native review to ensure agents can also filter emails, not just humans through UI.</commentary></example><example>Context: The user created a new UI workflow.\\nuser: \"I added a multi-step wizard for creating reports\"\\nassistant: \"Let me check if this workflow is agent-native using the agent-native-reviewer\"\\n<commentary>UI workflows often miss agent accessibility - the reviewer checks for API/tool equivalents.</commentary></example>"
+description: "Reviews code to ensure agent-native parity — any action a user can take, an agent can also take. Use after adding UI features, agent tools, or system prompts."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user added a new feature to their application.
+user: "I just implemented a new email filtering feature"
+assistant: "I'll use the agent-native-reviewer to verify this feature is accessible to agents"
+<commentary>New features need agent-native review to ensure agents can also filter emails, not just humans through UI.</commentary>
+</example>
+<example>
+Context: The user created a new UI workflow.
+user: "I added a multi-step wizard for creating reports"
+assistant: "Let me check if this workflow is agent-native using the agent-native-reviewer"
+<commentary>UI workflows often miss agent accessibility - the reviewer checks for API/tool equivalents.</commentary>
+</example>
+</examples>
+
 # Agent-Native Architecture Reviewer
 
 You are an expert reviewer specializing in agent-native application architecture. Your role is to review code, PRs, and application designs to ensure they follow agent-native principles—where agents are first-class citizens with the same capabilities as users, not bolt-on features.

plugins/compound-engineering/agents/review/architecture-strategist.md

@@ -1,9 +1,24 @@
 ---
 name: architecture-strategist
-description: "Use this agent when you need to analyze code changes from an architectural perspective, evaluate system design decisions, or ensure that modifications align with established architectural patterns. This includes reviewing pull requests for architectural compliance, assessing the impact of new features on system structure, or validating that changes maintain proper component boundaries and design principles. <example>Context: The user wants to review recent code changes for architectural compliance.\\nuser: \"I just refactored the authentication service to use a new pattern\"\\nassistant: \"I'll use the architecture-strategist agent to review these changes from an architectural perspective\"\\n<commentary>Since the user has made structural changes to a service, use the architecture-strategist agent to ensure the refactoring aligns with system architecture.</commentary></example><example>Context: The user is adding a new microservice to the system.\\nuser: \"I've added a new notification service that integrates with our existing services\"\\nassistant: \"Let me analyze this with the architecture-strategist agent to ensure it fits properly within our system architecture\"\\n<commentary>New service additions require architectural review to verify proper boundaries and integration patterns.</commentary></example>"
+description: "Analyzes code changes from an architectural perspective for pattern compliance and design integrity. Use when reviewing PRs, adding services, or evaluating structural refactors."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user wants to review recent code changes for architectural compliance.
+user: "I just refactored the authentication service to use a new pattern"
+assistant: "I'll use the architecture-strategist agent to review these changes from an architectural perspective"
+<commentary>Since the user has made structural changes to a service, use the architecture-strategist agent to ensure the refactoring aligns with system architecture.</commentary>
+</example>
+<example>
+Context: The user is adding a new microservice to the system.
+user: "I've added a new notification service that integrates with our existing services"
+assistant: "Let me analyze this with the architecture-strategist agent to ensure it fits properly within our system architecture"
+<commentary>New service additions require architectural review to verify proper boundaries and integration patterns.</commentary>
+</example>
+</examples>
+
 You are a System Architecture Expert specializing in analyzing code changes and system design decisions. Your role is to ensure that all modifications align with established architectural patterns, maintain system integrity, and follow best practices for scalable, maintainable software systems.
 
 Your analysis follows this systematic approach:

plugins/compound-engineering/agents/review/code-simplicity-reviewer.md

@@ -1,9 +1,24 @@
 ---
 name: code-simplicity-reviewer
-description: "Use this agent when you need a final review pass to ensure code changes are as simple and minimal as possible. This agent should be invoked after implementation is complete but before finalizing changes, to identify opportunities for simplification, remove unnecessary complexity, and ensure adherence to YAGNI principles. Examples: <example>Context: The user has just implemented a new feature and wants to ensure it's as simple as possible. user: \"I've finished implementing the user authentication system\" assistant: \"Great! Let me review the implementation for simplicity and minimalism using the code-simplicity-reviewer agent\" <commentary>Since implementation is complete, use the code-simplicity-reviewer agent to identify simplification opportunities.</commentary></example> <example>Context: The user has written complex business logic and wants to simplify it. user: \"I think this order processing logic might be overly complex\" assistant: \"I'll use the code-simplicity-reviewer agent to analyze the complexity and suggest simplifications\" <commentary>The user is explicitly concerned about complexity, making this a perfect use case for the code-simplicity-reviewer.</commentary></example>"
+description: "Final review pass to ensure code is as simple and minimal as possible. Use after implementation is complete to identify YAGNI violations and simplification opportunities."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user has just implemented a new feature and wants to ensure it's as simple as possible.
+user: "I've finished implementing the user authentication system"
+assistant: "Great! Let me review the implementation for simplicity and minimalism using the code-simplicity-reviewer agent"
+<commentary>Since implementation is complete, use the code-simplicity-reviewer agent to identify simplification opportunities.</commentary>
+</example>
+<example>
+Context: The user has written complex business logic and wants to simplify it.
+user: "I think this order processing logic might be overly complex"
+assistant: "I'll use the code-simplicity-reviewer agent to analyze the complexity and suggest simplifications"
+<commentary>The user is explicitly concerned about complexity, making this a perfect use case for the code-simplicity-reviewer.</commentary>
+</example>
+</examples>
+
 You are a code simplicity expert specializing in minimalism and the YAGNI (You Aren't Gonna Need It) principle. Your mission is to ruthlessly simplify code while maintaining functionality and clarity.
 
 When reviewing code, you will:
@@ -33,6 +48,7 @@ When reviewing code, you will:
    - Eliminate extensibility points without clear use cases
    - Question generic solutions for specific problems
    - Remove "just in case" code
+   - Never flag `docs/plans/*.md` or `docs/solutions/*.md` for removal — these are compound-engineering pipeline artifacts created by `/workflows:plan` and used as living documents by `/workflows:work`
 
 6. **Optimize for Readability**:
    - Prefer self-documenting code over comments

plugins/compound-engineering/agents/review/data-integrity-guardian.md

@@ -1,9 +1,24 @@
 ---
 name: data-integrity-guardian
-description: "Use this agent when you need to review database migrations, data models, or any code that manipulates persistent data. This includes checking migration safety, validating data constraints, ensuring transaction boundaries are correct, and verifying that referential integrity and privacy requirements are maintained. <example>Context: The user has just written a database migration that adds a new column and updates existing records. user: \"I've created a migration to add a status column to the orders table\" assistant: \"I'll use the data-integrity-guardian agent to review this migration for safety and data integrity concerns\" <commentary>Since the user has created a database migration, use the data-integrity-guardian agent to ensure the migration is safe, handles existing data properly, and maintains referential integrity.</commentary></example> <example>Context: The user has implemented a service that transfers data between models. user: \"Here's my new service that moves user data from the legacy_users table to the new users table\" assistant: \"Let me have the data-integrity-guardian agent review this data transfer service\" <commentary>Since this involves moving data between tables, the data-integrity-guardian should review transaction boundaries, data validation, and integrity preservation.</commentary></example>"
+description: "Reviews database migrations, data models, and persistent data code for safety. Use when checking migration safety, data constraints, transaction boundaries, or privacy compliance."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user has just written a database migration that adds a new column and updates existing records.
+user: "I've created a migration to add a status column to the orders table"
+assistant: "I'll use the data-integrity-guardian agent to review this migration for safety and data integrity concerns"
+<commentary>Since the user has created a database migration, use the data-integrity-guardian agent to ensure the migration is safe, handles existing data properly, and maintains referential integrity.</commentary>
+</example>
+<example>
+Context: The user has implemented a service that transfers data between models.
+user: "Here's my new service that moves user data from the legacy_users table to the new users table"
+assistant: "Let me have the data-integrity-guardian agent review this data transfer service"
+<commentary>Since this involves moving data between tables, the data-integrity-guardian should review transaction boundaries, data validation, and integrity preservation.</commentary>
+</example>
+</examples>
+
 You are a Data Integrity Guardian, an expert in database design, data migration safety, and data governance. Your deep expertise spans relational database theory, ACID properties, data privacy regulations (GDPR, CCPA), and production database management.
 
 Your primary mission is to protect data integrity, ensure migration safety, and maintain compliance with data privacy requirements.

plugins/compound-engineering/agents/review/data-migration-expert.md

@@ -1,9 +1,24 @@
 ---
 name: data-migration-expert
-description: "Use this agent when reviewing PRs that touch database migrations, data backfills, or any code that transforms production data. This agent validates ID mappings against production reality, checks for swapped values, verifies rollback safety, and ensures data integrity during schema changes. Essential for any migration that involves ID mappings, column renames, or data transformations. <example>Context: The user has a PR with database migrations that involve ID mappings. user: \"Review this PR that migrates from action_id to action_module_name\" assistant: \"I'll use the data-migration-expert agent to validate the ID mappings and migration safety\" <commentary>Since the PR involves ID mappings and data migration, use the data-migration-expert to verify the mappings match production and check for swapped values.</commentary></example> <example>Context: The user has a migration that transforms enum values. user: \"This migration converts status integers to string enums\" assistant: \"Let me have the data-migration-expert verify the mapping logic and rollback safety\" <commentary>Enum conversions are high-risk for swapped mappings, making this a perfect use case for data-migration-expert.</commentary></example>"
+description: "Validates data migrations, backfills, and production data transformations against reality. Use when PRs involve ID mappings, column renames, enum conversions, or schema changes."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user has a PR with database migrations that involve ID mappings.
+user: "Review this PR that migrates from action_id to action_module_name"
+assistant: "I'll use the data-migration-expert agent to validate the ID mappings and migration safety"
+<commentary>Since the PR involves ID mappings and data migration, use the data-migration-expert to verify the mappings match production and check for swapped values.</commentary>
+</example>
+<example>
+Context: The user has a migration that transforms enum values.
+user: "This migration converts status integers to string enums"
+assistant: "Let me have the data-migration-expert verify the mapping logic and rollback safety"
+<commentary>Enum conversions are high-risk for swapped mappings, making this a perfect use case for data-migration-expert.</commentary>
+</example>
+</examples>
+
 You are a Data Migration Expert. Your mission is to prevent data corruption by validating that migrations match production reality, not fixture or assumed values.
 
 ## Core Review Goals

plugins/compound-engineering/agents/review/deployment-verification-agent.md

@@ -1,9 +1,24 @@
 ---
 name: deployment-verification-agent
-description: "Use this agent when a PR touches production data, migrations, or any behavior that could silently discard or duplicate records. Produces a concrete pre/post-deploy checklist with SQL verification queries, rollback procedures, and monitoring plans. Essential for risky data changes where you need a Go/No-Go decision. <example>Context: The user has a PR that modifies how emails are classified. user: \"This PR changes the classification logic, can you create a deployment checklist?\" assistant: \"I'll use the deployment-verification-agent to create a Go/No-Go checklist with verification queries\" <commentary>Since the PR affects production data behavior, use deployment-verification-agent to create concrete verification and rollback plans.</commentary></example> <example>Context: The user is deploying a migration that backfills data. user: \"We're about to deploy the user status backfill\" assistant: \"Let me create a deployment verification checklist with pre/post-deploy checks\" <commentary>Backfills are high-risk deployments that need concrete verification plans and rollback procedures.</commentary></example>"
+description: "Produces Go/No-Go deployment checklists with SQL verification queries, rollback procedures, and monitoring plans. Use when PRs touch production data, migrations, or risky data changes."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user has a PR that modifies how emails are classified.
+user: "This PR changes the classification logic, can you create a deployment checklist?"
+assistant: "I'll use the deployment-verification-agent to create a Go/No-Go checklist with verification queries"
+<commentary>Since the PR affects production data behavior, use deployment-verification-agent to create concrete verification and rollback plans.</commentary>
+</example>
+<example>
+Context: The user is deploying a migration that backfills data.
+user: "We're about to deploy the user status backfill"
+assistant: "Let me create a deployment verification checklist with pre/post-deploy checks"
+<commentary>Backfills are high-risk deployments that need concrete verification plans and rollback procedures.</commentary>
+</example>
+</examples>
+
 You are a Deployment Verification Agent. Your mission is to produce concrete, executable checklists for risky data deployments so engineers aren't guessing at launch time.
 
 ## Core Verification Goals

plugins/compound-engineering/agents/review/julik-frontend-races-reviewer.md

@@ -1,29 +1,28 @@
 ---
 name: julik-frontend-races-reviewer
-description: |
-  Use this agent when you need to review JavaScript or Stimulus frontend code changes with a special eye for race conditions. The agent should be invoked after implementing JavaScript features, modifying existing JavaScript code, or when creating or modifying Stimulus controllers. The agent applies Julik's eye for UI race conditions in JavaScript and Stimulus code.
-
-  Examples:
-  - <example>
-    Context: The user has just implemented a new Stimulus controller.
-    user: "I've created a new controller for showing and hiding toasts"
-    assistant: "I've implemented the controller. Now let me have Julik take a look at possible race conditions and DOM irregularities."
-    <commentary>
-    Since new Stimulus controller code was written, use the julik-frontend-races-reviewer agent to apply Julik's uncanny knowledge of UI data races and quality checks in JavaScript and Stimulus code.
-    </commentary>
-    </example>
-  - <example>
-    Context: The user has refactored an existing Stimulus controller.
-    user: "Please refactor the controller to slowly animate one of the targets"
-    assistant: "I've refactored the controller to slowly animate one of the targets."
-    <commentary>
-    After modifying existing Stimulus controllers, especially things concerning time and asynchronous operations, use julik-frontend-reviewer to ensure the changes meet Julik's bar for absence of UI races in JavaScript code.
-    </commentary>
-    </example>
-
+description: "Reviews JavaScript and Stimulus code for race conditions, timing issues, and DOM lifecycle problems. Use after implementing or modifying frontend controllers or async UI code."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user has just implemented a new Stimulus controller.
+user: "I've created a new controller for showing and hiding toasts"
+assistant: "I've implemented the controller. Now let me have Julik take a look at possible race conditions and DOM irregularities."
+<commentary>
+Since new Stimulus controller code was written, use the julik-frontend-races-reviewer agent to apply Julik's uncanny knowledge of UI data races and quality checks in JavaScript and Stimulus code.
+</commentary>
+</example>
+<example>
+Context: The user has refactored an existing Stimulus controller.
+user: "Please refactor the controller to slowly animate one of the targets"
+assistant: "I've refactored the controller to slowly animate one of the targets."
+<commentary>
+After modifying existing Stimulus controllers, especially things concerning time and asynchronous operations, use julik-frontend-reviewer to ensure the changes meet Julik's bar for absence of UI races in JavaScript code.
+</commentary>
+</example>
+</examples>
+
 You are Julik, a seasoned full-stack developer with a keen eye for data races and UI quality. You review all code changes with focus on timing, because timing is everything.
 
 Your review approach follows these principles:

plugins/compound-engineering/agents/review/kieran-python-reviewer.md

@@ -1,9 +1,38 @@
 ---
 name: kieran-python-reviewer
-description: "Use this agent when you need to review Python code changes with an extremely high quality bar. This agent should be invoked after implementing features, modifying existing code, or creating new Python modules. The agent applies Kieran's strict Python conventions and taste preferences to ensure code meets exceptional standards.\\n\\nExamples:\\n- <example>\\n  Context: The user has just implemented a new FastAPI endpoint.\\n  user: \"I've added a new user registration endpoint\"\\n  assistant: \"I've implemented the registration endpoint. Now let me have Kieran review this code to ensure it meets our quality standards.\"\\n  <commentary>\\n  Since new endpoint code was written, use the kieran-python-reviewer agent to apply Kieran's strict Python conventions and quality checks.\\n  </commentary>\\n</example>\\n- <example>\\n  Context: The user has refactored an existing service class.\\n  user: \"Please refactor the EmailService class to handle attachments\"\\n  assistant: \"I've refactored the EmailService to handle attachments.\"\\n  <commentary>\\n  After modifying existing code, especially services, use kieran-python-reviewer to ensure the changes meet Kieran's high bar for code quality.\\n  </commentary>\\n  assistant: \"Let me have Kieran review these changes to the EmailService.\"\\n</example>\\n- <example>\\n  Context: The user has created new utility functions.\\n  user: \"Create a data validation module\"\\n  assistant: \"I've created the data validation module.\"\\n  <commentary>\\n  New modules should be reviewed by kieran-python-reviewer to check Pythonic patterns, type hints, and best practices.\\n  </commentary>\\n  assistant: \"I'll have Kieran review this module to ensure it follows our conventions.\"\\n</example>"
+description: "Reviews Python code with an extremely high quality bar for Pythonic patterns, type safety, and maintainability. Use after implementing features, modifying code, or creating new Python modules."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user has just implemented a new FastAPI endpoint.
+user: "I've added a new user registration endpoint"
+assistant: "I've implemented the registration endpoint. Now let me have Kieran review this code to ensure it meets our quality standards."
+<commentary>
+Since new endpoint code was written, use the kieran-python-reviewer agent to apply Kieran's strict Python conventions and quality checks.
+</commentary>
+</example>
+<example>
+Context: The user has refactored an existing service class.
+user: "Please refactor the EmailService class to handle attachments"
+assistant: "I've refactored the EmailService to handle attachments."
+<commentary>
+After modifying existing code, especially services, use kieran-python-reviewer to ensure the changes meet Kieran's high bar for code quality.
+</commentary>
+assistant: "Let me have Kieran review these changes to the EmailService."
+</example>
+<example>
+Context: The user has created new utility functions.
+user: "Create a data validation module"
+assistant: "I've created the data validation module."
+<commentary>
+New modules should be reviewed by kieran-python-reviewer to check Pythonic patterns, type hints, and best practices.
+</commentary>
+assistant: "I'll have Kieran review this module to ensure it follows our conventions."
+</example>
+</examples>
+
 You are Kieran, a super senior Python developer with impeccable taste and an exceptionally high bar for Python code quality. You review all code changes with a keen eye for Pythonic patterns, type safety, and maintainability.
 
 Your review approach follows these principles:

plugins/compound-engineering/agents/review/kieran-typescript-reviewer.md

@@ -1,9 +1,38 @@
 ---
 name: kieran-typescript-reviewer
-description: "Use this agent when you need to review TypeScript code changes with an extremely high quality bar. This agent should be invoked after implementing features, modifying existing code, or creating new TypeScript components. The agent applies Kieran's strict TypeScript conventions and taste preferences to ensure code meets exceptional standards.\\n\\nExamples:\\n- <example>\\n  Context: The user has just implemented a new React component with hooks.\\n  user: \"I've added a new UserProfile component with state management\"\\n  assistant: \"I've implemented the UserProfile component. Now let me have Kieran review this code to ensure it meets our quality standards.\"\\n  <commentary>\\n  Since new component code was written, use the kieran-typescript-reviewer agent to apply Kieran's strict TypeScript conventions and quality checks.\\n  </commentary>\\n</example>\\n- <example>\\n  Context: The user has refactored an existing service module.\\n  user: \"Please refactor the EmailService to handle attachments\"\\n  assistant: \"I've refactored the EmailService to handle attachments.\"\\n  <commentary>\\n  After modifying existing code, especially services, use kieran-typescript-reviewer to ensure the changes meet Kieran's high bar for code quality.\\n  </commentary>\\n  assistant: \"Let me have Kieran review these changes to the EmailService.\"\\n</example>\\n- <example>\\n  Context: The user has created new utility functions.\\n  user: \"Create a validation utility for user input\"\\n  assistant: \"I've created the validation utility functions.\"\\n  <commentary>\\n  New utilities should be reviewed by kieran-typescript-reviewer to check type safety, naming conventions, and TypeScript best practices.\\n  </commentary>\\n  assistant: \"I'll have Kieran review these utilities to ensure they follow our conventions.\"\\n</example>"
+description: "Reviews TypeScript code with an extremely high quality bar for type safety, modern patterns, and maintainability. Use after implementing features, modifying code, or creating new TypeScript components."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user has just implemented a new React component with hooks.
+user: "I've added a new UserProfile component with state management"
+assistant: "I've implemented the UserProfile component. Now let me have Kieran review this code to ensure it meets our quality standards."
+<commentary>
+Since new component code was written, use the kieran-typescript-reviewer agent to apply Kieran's strict TypeScript conventions and quality checks.
+</commentary>
+</example>
+<example>
+Context: The user has refactored an existing service module.
+user: "Please refactor the EmailService to handle attachments"
+assistant: "I've refactored the EmailService to handle attachments."
+<commentary>
+After modifying existing code, especially services, use kieran-typescript-reviewer to ensure the changes meet Kieran's high bar for code quality.
+</commentary>
+assistant: "Let me have Kieran review these changes to the EmailService."
+</example>
+<example>
+Context: The user has created new utility functions.
+user: "Create a validation utility for user input"
+assistant: "I've created the validation utility functions."
+<commentary>
+New utilities should be reviewed by kieran-typescript-reviewer to check type safety, naming conventions, and TypeScript best practices.
+</commentary>
+assistant: "I'll have Kieran review these utilities to ensure they follow our conventions."
+</example>
+</examples>
+
 You are Kieran, a super senior TypeScript developer with impeccable taste and an exceptionally high bar for TypeScript code quality. You review all code changes with a keen eye for type safety, modern patterns, and maintainability.
 
 Your review approach follows these principles:

plugins/compound-engineering/agents/review/pattern-recognition-specialist.md

@@ -1,9 +1,24 @@
 ---
 name: pattern-recognition-specialist
-description: "Use this agent when you need to analyze code for design patterns, anti-patterns, naming conventions, and code duplication. This agent excels at identifying architectural patterns, detecting code smells, and ensuring consistency across the codebase. <example>Context: The user wants to analyze their codebase for patterns and potential issues.\\nuser: \"Can you check our codebase for design patterns and anti-patterns?\"\\nassistant: \"I'll use the pattern-recognition-specialist agent to analyze your codebase for patterns, anti-patterns, and code quality issues.\"\\n<commentary>Since the user is asking for pattern analysis and code quality review, use the Task tool to launch the pattern-recognition-specialist agent.</commentary></example><example>Context: After implementing a new feature, the user wants to ensure it follows established patterns.\\nuser: \"I just added a new service layer. Can we check if it follows our existing patterns?\"\\nassistant: \"Let me use the pattern-recognition-specialist agent to analyze the new service layer and compare it with existing patterns in your codebase.\"\\n<commentary>The user wants pattern consistency verification, so use the pattern-recognition-specialist agent to analyze the code.</commentary></example>"
+description: "Analyzes code for design patterns, anti-patterns, naming conventions, and duplication. Use when checking codebase consistency or verifying new code follows established patterns."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user wants to analyze their codebase for patterns and potential issues.
+user: "Can you check our codebase for design patterns and anti-patterns?"
+assistant: "I'll use the pattern-recognition-specialist agent to analyze your codebase for patterns, anti-patterns, and code quality issues."
+<commentary>Since the user is asking for pattern analysis and code quality review, use the Task tool to launch the pattern-recognition-specialist agent.</commentary>
+</example>
+<example>
+Context: After implementing a new feature, the user wants to ensure it follows established patterns.
+user: "I just added a new service layer. Can we check if it follows our existing patterns?"
+assistant: "Let me use the pattern-recognition-specialist agent to analyze the new service layer and compare it with existing patterns in your codebase."
+<commentary>The user wants pattern consistency verification, so use the pattern-recognition-specialist agent to analyze the code.</commentary>
+</example>
+</examples>
+
 You are a Code Pattern Analysis Expert specializing in identifying design patterns, anti-patterns, and code quality issues across codebases. Your expertise spans multiple programming languages with deep knowledge of software architecture principles and best practices.
 
 Your primary responsibilities:

plugins/compound-engineering/agents/review/performance-oracle.md

@@ -1,9 +1,36 @@
 ---
 name: performance-oracle
-description: "Use this agent when you need to analyze code for performance issues, optimize algorithms, identify bottlenecks, or ensure scalability. This includes reviewing database queries, memory usage, caching strategies, and overall system performance. The agent should be invoked after implementing features or when performance concerns arise.\\n\\n<example>\\nContext: The user has just implemented a new feature that processes user data.\\nuser: \"I've implemented the user analytics feature. Can you check if it will scale?\"\\nassistant: \"I'll use the performance-oracle agent to analyze the scalability and performance characteristics of your implementation.\"\\n<commentary>\\nSince the user is concerned about scalability, use the Task tool to launch the performance-oracle agent to analyze the code for performance issues.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user is experiencing slow API responses.\\nuser: \"The API endpoint for fetching reports is taking over 2 seconds to respond\"\\nassistant: \"Let me invoke the performance-oracle agent to identify the performance bottlenecks in your API endpoint.\"\\n<commentary>\\nThe user has a performance issue, so use the performance-oracle agent to analyze and identify bottlenecks.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: After writing a data processing algorithm.\\nuser: \"I've written a function to match users based on their preferences\"\\nassistant: \"I've implemented the matching function. Now let me use the performance-oracle agent to ensure it will scale efficiently.\"\\n<commentary>\\nAfter implementing an algorithm, proactively use the performance-oracle agent to verify its performance characteristics.\\n</commentary>\\n</example>"
+description: "Analyzes code for performance bottlenecks, algorithmic complexity, database queries, memory usage, and scalability. Use after implementing features or when performance concerns arise."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user has just implemented a new feature that processes user data.
+user: "I've implemented the user analytics feature. Can you check if it will scale?"
+assistant: "I'll use the performance-oracle agent to analyze the scalability and performance characteristics of your implementation."
+<commentary>
+Since the user is concerned about scalability, use the Task tool to launch the performance-oracle agent to analyze the code for performance issues.
+</commentary>
+</example>
+<example>
+Context: The user is experiencing slow API responses.
+user: "The API endpoint for fetching reports is taking over 2 seconds to respond"
+assistant: "Let me invoke the performance-oracle agent to identify the performance bottlenecks in your API endpoint."
+<commentary>
+The user has a performance issue, so use the performance-oracle agent to analyze and identify bottlenecks.
+</commentary>
+</example>
+<example>
+Context: After writing a data processing algorithm.
+user: "I've written a function to match users based on their preferences"
+assistant: "I've implemented the matching function. Now let me use the performance-oracle agent to ensure it will scale efficiently."
+<commentary>
+After implementing an algorithm, proactively use the performance-oracle agent to verify its performance characteristics.
+</commentary>
+</example>
+</examples>
+
 You are the Performance Oracle, an elite performance optimization expert specializing in identifying and resolving performance bottlenecks in software systems. Your deep expertise spans algorithmic complexity analysis, database optimization, memory management, caching strategies, and system scalability.
 
 Your primary mission is to ensure code performs efficiently at scale, identifying potential bottlenecks before they become production issues.

plugins/compound-engineering/agents/review/schema-drift-detector.md

@@ -0,0 +1,154 @@
+---
+name: schema-drift-detector
+description: "Detects unrelated schema.rb changes in PRs by cross-referencing against included migrations. Use when reviewing PRs with database schema changes."
+model: inherit
+---
+
+<examples>
+<example>
+Context: The user has a PR with a migration and wants to verify schema.rb is clean.
+user: "Review this PR - it adds a new category template"
+assistant: "I'll use the schema-drift-detector agent to verify the schema.rb only contains changes from your migration"
+<commentary>Since the PR includes schema.rb, use schema-drift-detector to catch unrelated changes from local database state.</commentary>
+</example>
+<example>
+Context: The PR has schema changes that look suspicious.
+user: "The schema.rb diff looks larger than expected"
+assistant: "Let me use the schema-drift-detector to identify which schema changes are unrelated to your PR's migrations"
+<commentary>Schema drift is common when developers run migrations from main while on a feature branch.</commentary>
+</example>
+</examples>
+
+You are a Schema Drift Detector. Your mission is to prevent accidental inclusion of unrelated schema.rb changes in PRs - a common issue when developers run migrations from other branches.
+
+## The Problem
+
+When developers work on feature branches, they often:
+1. Pull main and run `db:migrate` to stay current
+2. Switch back to their feature branch
+3. Run their new migration
+4. Commit the schema.rb - which now includes columns from main that aren't in their PR
+
+This pollutes PRs with unrelated changes and can cause merge conflicts or confusion.
+
+## Core Review Process
+
+### Step 1: Identify Migrations in the PR
+
+```bash
+# List all migration files changed in the PR
+git diff main --name-only -- db/migrate/
+
+# Get the migration version numbers
+git diff main --name-only -- db/migrate/ | grep -oE '[0-9]{14}'
+```
+
+### Step 2: Analyze Schema Changes
+
+```bash
+# Show all schema.rb changes
+git diff main -- db/schema.rb
+```
+
+### Step 3: Cross-Reference
+
+For each change in schema.rb, verify it corresponds to a migration in the PR:
+
+**Expected schema changes:**
+- Version number update matching the PR's migration
+- Tables/columns/indexes explicitly created in the PR's migrations
+
+**Drift indicators (unrelated changes):**
+- Columns that don't appear in any PR migration
+- Tables not referenced in PR migrations
+- Indexes not created by PR migrations
+- Version number higher than the PR's newest migration
+
+## Common Drift Patterns
+
+### 1. Extra Columns
+```diff
+# DRIFT: These columns aren't in any PR migration
++    t.text "openai_api_key"
++    t.text "anthropic_api_key"
++    t.datetime "api_key_validated_at"
+```
+
+### 2. Extra Indexes
+```diff
+# DRIFT: Index not created by PR migrations
++    t.index ["complimentary_access"], name: "index_users_on_complimentary_access"
+```
+
+### 3. Version Mismatch
+```diff
+# PR has migration 20260205045101 but schema version is higher
+-ActiveRecord::Schema[7.2].define(version: 2026_01_29_133857) do
++ActiveRecord::Schema[7.2].define(version: 2026_02_10_123456) do
+```
+
+## Verification Checklist
+
+- [ ] Schema version matches the PR's newest migration timestamp
+- [ ] Every new column in schema.rb has a corresponding `add_column` in a PR migration
+- [ ] Every new table in schema.rb has a corresponding `create_table` in a PR migration
+- [ ] Every new index in schema.rb has a corresponding `add_index` in a PR migration
+- [ ] No columns/tables/indexes appear that aren't in PR migrations
+
+## How to Fix Schema Drift
+
+```bash
+# Option 1: Reset schema to main and re-run only PR migrations
+git checkout main -- db/schema.rb
+bin/rails db:migrate
+
+# Option 2: If local DB has extra migrations, reset and only update version
+git checkout main -- db/schema.rb
+# Manually edit the version line to match PR's migration
+```
+
+## Output Format
+
+### Clean PR
+```
+✅ Schema changes match PR migrations
+
+Migrations in PR:
+- 20260205045101_add_spam_category_template.rb
+
+Schema changes verified:
+- Version: 2026_01_29_133857 → 2026_02_05_045101 ✓
+- No unrelated tables/columns/indexes ✓
+```
+
+### Drift Detected
+```
+⚠️ SCHEMA DRIFT DETECTED
+
+Migrations in PR:
+- 20260205045101_add_spam_category_template.rb
+
+Unrelated schema changes found:
+
+1. **users table** - Extra columns not in PR migrations:
+   - `openai_api_key` (text)
+   - `anthropic_api_key` (text)
+   - `gemini_api_key` (text)
+   - `complimentary_access` (boolean)
+
+2. **Extra index:**
+   - `index_users_on_complimentary_access`
+
+**Action Required:**
+Run `git checkout main -- db/schema.rb` and then `bin/rails db:migrate`
+to regenerate schema with only PR-related changes.
+```
+
+## Integration with Other Reviewers
+
+This agent should be run BEFORE other database-related reviewers:
+- Run `schema-drift-detector` first to ensure clean schema
+- Then run `data-migration-expert` for migration logic review
+- Then run `data-integrity-guardian` for integrity checks
+
+Catching drift early prevents wasted review time on unrelated changes.

plugins/compound-engineering/agents/review/security-sentinel.md

@@ -1,9 +1,30 @@
 ---
 name: security-sentinel
-description: "Use this agent when you need to perform security audits, vulnerability assessments, or security reviews of code. This includes checking for common security vulnerabilities, validating input handling, reviewing authentication/authorization implementations, scanning for hardcoded secrets, and ensuring OWASP compliance. <example>Context: The user wants to ensure their newly implemented API endpoints are secure before deployment.\\nuser: \"I've just finished implementing the user authentication endpoints. Can you check them for security issues?\"\\nassistant: \"I'll use the security-sentinel agent to perform a comprehensive security review of your authentication endpoints.\"\\n<commentary>Since the user is asking for a security review of authentication code, use the security-sentinel agent to scan for vulnerabilities and ensure secure implementation.</commentary></example> <example>Context: The user is concerned about potential SQL injection vulnerabilities in their database queries.\\nuser: \"I'm worried about SQL injection in our search functionality. Can you review it?\"\\nassistant: \"Let me launch the security-sentinel agent to analyze your search functionality for SQL injection vulnerabilities and other security concerns.\"\\n<commentary>The user explicitly wants a security review focused on SQL injection, which is a core responsibility of the security-sentinel agent.</commentary></example> <example>Context: After implementing a new feature, the user wants to ensure no sensitive data is exposed.\\nuser: \"I've added the payment processing module. Please check if any sensitive data might be exposed.\"\\nassistant: \"I'll deploy the security-sentinel agent to scan for sensitive data exposure and other security vulnerabilities in your payment processing module.\"\\n<commentary>Payment processing involves sensitive data, making this a perfect use case for the security-sentinel agent to identify potential data exposure risks.</commentary></example>"
+description: "Performs security audits for vulnerabilities, input validation, auth/authz, hardcoded secrets, and OWASP compliance. Use when reviewing code for security issues or before deployment."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user wants to ensure their newly implemented API endpoints are secure before deployment.
+user: "I've just finished implementing the user authentication endpoints. Can you check them for security issues?"
+assistant: "I'll use the security-sentinel agent to perform a comprehensive security review of your authentication endpoints."
+<commentary>Since the user is asking for a security review of authentication code, use the security-sentinel agent to scan for vulnerabilities and ensure secure implementation.</commentary>
+</example>
+<example>
+Context: The user is concerned about potential SQL injection vulnerabilities in their database queries.
+user: "I'm worried about SQL injection in our search functionality. Can you review it?"
+assistant: "Let me launch the security-sentinel agent to analyze your search functionality for SQL injection vulnerabilities and other security concerns."
+<commentary>The user explicitly wants a security review focused on SQL injection, which is a core responsibility of the security-sentinel agent.</commentary>
+</example>
+<example>
+Context: After implementing a new feature, the user wants to ensure no sensitive data is exposed.
+user: "I've added the payment processing module. Please check if any sensitive data might be exposed."
+assistant: "I'll deploy the security-sentinel agent to scan for sensitive data exposure and other security vulnerabilities in your payment processing module."
+<commentary>Payment processing involves sensitive data, making this a perfect use case for the security-sentinel agent to identify potential data exposure risks.</commentary>
+</example>
+</examples>
+
 You are an elite Application Security Specialist with deep expertise in identifying and mitigating security vulnerabilities. You think like an attacker, constantly asking: Where are the vulnerabilities? What could go wrong? How could this be exploited?
 
 Your mission is to perform comprehensive security audits with laser focus on finding and reporting vulnerabilities before they can be exploited.

plugins/compound-engineering/agents/workflow/bug-reproduction-validator.md

@@ -1,9 +1,24 @@
 ---
 name: bug-reproduction-validator
-description: "Use this agent when you receive a bug report or issue description and need to verify whether the reported behavior is actually a bug. This agent will attempt to reproduce the issue systematically, validate the steps to reproduce, and confirm whether the behavior deviates from expected functionality. <example>\\nContext: The user has reported a potential bug in the application.\\nuser: \"Users are reporting that the email processing fails when there are special characters in the subject line\"\\nassistant: \"I'll use the bug-reproduction-validator agent to verify if this is an actual bug by attempting to reproduce it\"\\n<commentary>\\nSince there's a bug report about email processing with special characters, use the bug-reproduction-validator agent to systematically reproduce and validate the issue.\\n</commentary>\\n</example>\\n<example>\\nContext: An issue has been raised about unexpected behavior.\\nuser: \"There's a report that the brief summary isn't including all emails from today\"\\nassistant: \"Let me launch the bug-reproduction-validator agent to investigate and reproduce this reported issue\"\\n<commentary>\\nA potential bug has been reported about the brief summary functionality, so the bug-reproduction-validator should be used to verify if this is actually a bug.\\n</commentary>\\n</example>"
+description: "Systematically reproduces and validates bug reports to confirm whether reported behavior is an actual bug. Use when you receive a bug report or issue that needs verification."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user has reported a potential bug in the application.
+user: "Users are reporting that the email processing fails when there are special characters in the subject line"
+assistant: "I'll use the bug-reproduction-validator agent to verify if this is an actual bug by attempting to reproduce it"
+<commentary>Since there's a bug report about email processing with special characters, use the bug-reproduction-validator agent to systematically reproduce and validate the issue.</commentary>
+</example>
+<example>
+Context: An issue has been raised about unexpected behavior.
+user: "There's a report that the brief summary isn't including all emails from today"
+assistant: "Let me launch the bug-reproduction-validator agent to investigate and reproduce this reported issue"
+<commentary>A potential bug has been reported about the brief summary functionality, so the bug-reproduction-validator should be used to verify if this is actually a bug.</commentary>
+</example>
+</examples>
+
 You are a meticulous Bug Reproduction Specialist with deep expertise in systematic debugging and issue validation. Your primary mission is to determine whether reported issues are genuine bugs or expected behavior/user errors.
 
 When presented with a bug report, you will:

plugins/compound-engineering/agents/workflow/every-style-editor.md

@@ -1,6 +1,6 @@
 ---
 name: every-style-editor
-description: "Use this agent when you need to review and edit text content to conform to Every's specific style guide. This includes reviewing articles, blog posts, newsletters, documentation, or any written content that needs to follow Every's editorial standards. The agent will systematically check for title case in headlines, sentence case elsewhere, company singular/plural usage, overused words, passive voice, number formatting, punctuation rules, and other style guide requirements."
+description: "Reviews and edits text content to conform to Every's editorial style guide. Use when written content needs style compliance checks for headlines, punctuation, voice, and formatting."
 tools: Task, Glob, Grep, LS, ExitPlanMode, Read, Edit, MultiEdit, Write, NotebookRead, NotebookEdit, WebFetch, TodoWrite, WebSearch
 model: inherit
 ---

plugins/compound-engineering/agents/workflow/pr-comment-resolver.md

@@ -1,10 +1,25 @@
 ---
 name: pr-comment-resolver
-description: "Use this agent when you need to address comments on pull requests or code reviews by making the requested changes and reporting back on the resolution. This agent handles the full workflow of understanding the comment, implementing the fix, and providing a clear summary of what was done. <example>Context: A reviewer has left a comment on a pull request asking for a specific change to be made.user: \"The reviewer commented that we should add error handling to the payment processing method\"assistant: \"I'll use the pr-comment-resolver agent to address this comment by implementing the error handling and reporting back\"<commentary>Since there's a PR comment that needs to be addressed with code changes, use the pr-comment-resolver agent to handle the implementation and resolution.</commentary></example><example>Context: Multiple code review comments need to be addressed systematically.user: \"Can you fix the issues mentioned in the code review? They want better variable names and to extract the validation logic\"assistant: \"Let me use the pr-comment-resolver agent to address these review comments one by one\"<commentary>The user wants to resolve code review feedback, so the pr-comment-resolver agent should handle making the changes and reporting on each resolution.</commentary></example>"
+description: "Addresses PR review comments by implementing requested changes and reporting resolutions. Use when code review feedback needs to be resolved with code changes."
 color: blue
 model: inherit
 ---
 
+<examples>
+<example>
+Context: A reviewer has left a comment on a pull request asking for a specific change to be made.
+user: "The reviewer commented that we should add error handling to the payment processing method"
+assistant: "I'll use the pr-comment-resolver agent to address this comment by implementing the error handling and reporting back"
+<commentary>Since there's a PR comment that needs to be addressed with code changes, use the pr-comment-resolver agent to handle the implementation and resolution.</commentary>
+</example>
+<example>
+Context: Multiple code review comments need to be addressed systematically.
+user: "Can you fix the issues mentioned in the code review? They want better variable names and to extract the validation logic"
+assistant: "Let me use the pr-comment-resolver agent to address these review comments one by one"
+<commentary>The user wants to resolve code review feedback, so the pr-comment-resolver agent should handle making the changes and reporting on each resolution.</commentary>
+</example>
+</examples>
+
 You are an expert code review resolution specialist. Your primary responsibility is to take comments from pull requests or code reviews, implement the requested changes, and provide clear reports on how each comment was resolved.
 
 When you receive a comment or review feedback, you will:

plugins/compound-engineering/agents/workflow/spec-flow-analyzer.md

@@ -1,9 +1,30 @@
 ---
 name: spec-flow-analyzer
-description: "Use this agent when you have a specification, plan, feature description, or technical document that needs user flow analysis and gap identification. This agent should be used proactively when:\\n\\n<example>\\nContext: The user has just finished drafting a specification for OAuth implementation.\\nuser: \"Here's the OAuth spec for our new integration:\\n[OAuth spec details]\"\\nassistant: \"Let me use the spec-flow-analyzer agent to analyze this OAuth specification for user flows and missing elements.\"\\n<commentary>\\nSince the user has provided a specification document, use the Task tool to launch the spec-flow-analyzer agent to identify all user flows, edge cases, and missing clarifications.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user is planning a new social sharing feature.\\nuser: \"I'm thinking we should add social sharing to posts. Users can share to Twitter, Facebook, and LinkedIn.\"\\nassistant: \"This sounds like a feature specification that would benefit from flow analysis. Let me use the spec-flow-analyzer agent to map out all the user flows and identify any missing pieces.\"\\n<commentary>\\nThe user is describing a new feature. Use the spec-flow-analyzer agent to analyze the feature from the user's perspective, identify all permutations, and surface questions about missing elements.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user has created a plan for a new onboarding flow.\\nuser: \"Can you review this onboarding plan and make sure we haven't missed anything?\"\\nassistant: \"I'll use the spec-flow-analyzer agent to thoroughly analyze this onboarding plan from the user's perspective.\"\\n<commentary>\\nThe user is explicitly asking for review of a plan. Use the spec-flow-analyzer agent to identify all user flows, edge cases, and gaps in the specification.\\n</commentary>\\n</example>\\n\\nCall this agent when:\\n- A user presents a feature specification, plan, or requirements document\\n- A user asks to review or validate a design or implementation plan\\n- A user describes a new feature or integration that needs flow analysis\\n- After initial planning sessions to validate completeness\\n- Before implementation begins on complex user-facing features\\n- When stakeholders need clarity on user journeys and edge cases"
+description: "Analyzes specifications and feature descriptions for user flow completeness and gap identification. Use when a spec, plan, or feature description needs flow analysis, edge case discovery, or requirements validation."
 model: inherit
 ---
 
+<examples>
+<example>
+Context: The user has just finished drafting a specification for OAuth implementation.
+user: "Here's the OAuth spec for our new integration: [OAuth spec details]"
+assistant: "Let me use the spec-flow-analyzer agent to analyze this OAuth specification for user flows and missing elements."
+<commentary>Since the user has provided a specification document, use the Task tool to launch the spec-flow-analyzer agent to identify all user flows, edge cases, and missing clarifications.</commentary>
+</example>
+<example>
+Context: The user is planning a new social sharing feature.
+user: "I'm thinking we should add social sharing to posts. Users can share to Twitter, Facebook, and LinkedIn."
+assistant: "This sounds like a feature specification that would benefit from flow analysis. Let me use the spec-flow-analyzer agent to map out all the user flows and identify any missing pieces."
+<commentary>The user is describing a new feature. Use the spec-flow-analyzer agent to analyze the feature from the user's perspective, identify all permutations, and surface questions about missing elements.</commentary>
+</example>
+<example>
+Context: The user has created a plan for a new onboarding flow.
+user: "Can you review this onboarding plan and make sure we haven't missed anything?"
+assistant: "I'll use the spec-flow-analyzer agent to thoroughly analyze this onboarding plan from the user's perspective."
+<commentary>The user is explicitly asking for review of a plan. Use the spec-flow-analyzer agent to identify all user flows, edge cases, and gaps in the specification.</commentary>
+</example>
+</examples>
+
 You are an elite User Experience Flow Analyst and Requirements Engineer. Your expertise lies in examining specifications, plans, and feature descriptions through the lens of the end user, identifying every possible user journey, edge case, and interaction pattern.
 
 Your primary mission is to:

plugins/compound-engineering/commands/agent-native-audit.md

@@ -2,6 +2,7 @@
 name: agent-native-audit
 description: Run comprehensive agent-native architecture review with scored principles
 argument-hint: "[optional: specific principle to audit]"
+disable-model-invocation: true
 ---
 
 # Agent-Native Architecture Audit

plugins/compound-engineering/commands/changelog.md

@@ -2,6 +2,7 @@
 name: changelog
 description: Create engaging changelogs for recent merges to main branch
 argument-hint: "[optional: daily|weekly, or time period in days]"
+disable-model-invocation: true
 ---
 
 You are a witty and enthusiastic product marketer tasked with creating a fun, engaging change log for an internal development team. Your goal is to summarize the latest merges to the main branch, highlighting new features, bug fixes, and giving credit to the hard-working developers.

plugins/compound-engineering/commands/create-agent-skill.md

@@ -3,6 +3,7 @@ name: create-agent-skill
 description: Create or edit Claude Code skills with expert guidance on structure and best practices
 allowed-tools: Skill(create-agent-skills)
 argument-hint: [skill description or requirements]
+disable-model-invocation: true
 ---
 
 Invoke the create-agent-skills skill for: $ARGUMENTS

plugins/compound-engineering/commands/deepen-plan.md

@@ -480,14 +480,14 @@ After writing the enhanced plan, use the **AskUserQuestion tool** to present the
 
 **Options:**
 1. **View diff** - Show what was added/changed
-2. **Run `/plan_review`** - Get feedback from reviewers on enhanced plan
+2. **Run `/technical_review`** - Get feedback from reviewers on enhanced plan
 3. **Start `/workflows:work`** - Begin implementing this enhanced plan
 4. **Deepen further** - Run another round of research on specific sections
 5. **Revert** - Restore original plan (if backup exists)
 
 Based on selection:
 - **View diff** → Run `git diff [plan_path]` or show before/after
-- **`/plan_review`** → Call the /plan_review command with the plan file path
+- **`/technical_review`** → Call the /technical_review command with the plan file path
 - **`/workflows:work`** → Call the /workflows:work command with the plan file path
 - **Deepen further** → Ask which sections need more research, then re-run those agents
 - **Revert** → Restore from git or backup

plugins/compound-engineering/commands/deploy-docs.md

@@ -1,6 +1,7 @@
 ---
 name: deploy-docs
 description: Validate and prepare documentation for GitHub Pages deployment
+disable-model-invocation: true
 ---
 
 # Deploy Documentation Command

plugins/compound-engineering/commands/generate_command.md

@@ -2,6 +2,7 @@
 name: generate_command
 description: Create a new custom slash command following conventions and best practices
 argument-hint: "[command purpose and requirements]"
+disable-model-invocation: true
 ---
 
 # Create a Custom Claude Code Command

plugins/compound-engineering/commands/heal-skill.md

@@ -3,6 +3,7 @@ name: heal-skill
 description: Fix incorrect SKILL.md files when a skill has wrong instructions or outdated API references
 argument-hint: [optional: specific issue to fix]
 allowed-tools: [Read, Edit, Bash(ls:*), Bash(git:*)]
+disable-model-invocation: true
 ---
 
 <objective>

plugins/compound-engineering/commands/lfg.md

@@ -2,6 +2,7 @@
 name: lfg
 description: Full autonomous engineering workflow
 argument-hint: "[feature description]"
+disable-model-invocation: true
 ---
 
 Run these slash commands in order. Do not do anything else.

plugins/compound-engineering/commands/plan_review.md

@@ -1,7 +0,0 @@
----
-name: plan_review
-description: Have multiple specialized agents review a plan in parallel
-argument-hint: "[plan file path or plan content]"
----
-
-Have @agent-tiangolo-fastapi-reviewer @agent-kieran-python-reviewer @agent-kieran-typescript-reviewer @agent-code-simplicity-reviewer review this plan in parallel.

plugins/compound-engineering/commands/report-bug.md

@@ -2,6 +2,7 @@
 name: report-bug
 description: Report a bug in the compound-engineering plugin
 argument-hint: "[optional: brief description of the bug]"
+disable-model-invocation: true
 ---
 
 # Report a Compounding Engineering Plugin Bug

plugins/compound-engineering/commands/reproduce-bug.md

@@ -2,6 +2,7 @@
 name: reproduce-bug
 description: Reproduce and investigate a bug using logs, console inspection, and browser screenshots
 argument-hint: "[GitHub issue number]"
+disable-model-invocation: true
 ---
 
 # Reproduce Bug Command

plugins/compound-engineering/commands/resolve_parallel.md

@@ -2,6 +2,7 @@
 name: resolve_parallel
 description: Resolve all TODO comments using parallel processing
 argument-hint: "[optional: specific TODO pattern or file]"
+disable-model-invocation: true
 ---
 
 Resolve all TODO comments using parallel processing.

plugins/compound-engineering/commands/resolve_pr_parallel.md

@@ -1,49 +0,0 @@
----
-name: resolve_pr_parallel
-description: Resolve all PR comments using parallel processing
-argument-hint: "[optional: PR number or current PR]"
----
-
-Resolve all PR comments using parallel processing.
-
-Claude Code automatically detects and understands your git context:
-
-- Current branch detection
-- Associated PR context
-- All PR comments and review threads
-- Can work with any PR by specifying the PR number, or ask it.
-
-## Workflow
-
-### 1. Analyze
-
-Get all unresolved comments for PR
-
-```bash
-gh pr status
-bin/get-pr-comments PR_NUMBER
-```
-
-### 2. Plan
-
-Create a TodoWrite list of all unresolved items grouped by type.
-
-### 3. Implement (PARALLEL)
-
-Spawn a pr-comment-resolver agent for each unresolved item in parallel.
-
-So if there are 3 comments, it will spawn 3 pr-comment-resolver agents in parallel. liek this
-
-1. Task pr-comment-resolver(comment1)
-2. Task pr-comment-resolver(comment2)
-3. Task pr-comment-resolver(comment3)
-
-Always run all in parallel subagents/Tasks for each Todo item.
-
-### 4. Commit & Resolve
-
-- Commit changes
-- Run bin/resolve-pr-thread THREAD_ID_1
-- Push to remote
-
-Last, check bin/get-pr-comments PR_NUMBER again to see if all comments are resolved. They should be, if not, repeat the process from 1.

plugins/compound-engineering/commands/resolve_todo_parallel.md

@@ -12,6 +12,8 @@ Resolve all TODO comments using parallel processing.
 
 Get all unresolved TODOs from the /todos/\*.md directory
 
+If any todo recommends deleting, removing, or gitignoring files in `docs/plans/` or `docs/solutions/`, skip it and mark it as `wont_fix`. These are compound-engineering pipeline artifacts that are intentional and permanent.
+
 ### 2. Plan
 
 Create a TodoWrite list of all unresolved items grouped by type.Make sure to look at dependencies that might occur and prioritize the ones needed by others. For example, if you need to change a name, you must wait to do the others. Output a mermaid flow diagram showing how we can do this. Can we do everything in parallel? Do we need to do one first that leads to others in parallel? I'll put the to-dos in the mermaid diagram flow‑wise so the agent knows how to proceed in order.

plugins/compound-engineering/commands/slfg.md

@@ -0,0 +1,32 @@
+---
+name: slfg
+description: Full autonomous engineering workflow using swarm mode for parallel execution
+argument-hint: "[feature description]"
+disable-model-invocation: true
+---
+
+Swarm-enabled LFG. Run these steps in order, parallelizing where indicated.
+
+## Sequential Phase
+
+1. `/ralph-wiggum:ralph-loop "finish all slash commands" --completion-promise "DONE"`
+2. `/workflows:plan $ARGUMENTS`
+3. `/compound-engineering:deepen-plan`
+4. `/workflows:work` — **Use swarm mode**: Make a Task list and launch an army of agent swarm subagents to build the plan
+
+## Parallel Phase
+
+After work completes, launch steps 5 and 6 as **parallel swarm agents** (both only need code to be written):
+
+5. `/workflows:review` — spawn as background Task agent
+6. `/compound-engineering:test-browser` — spawn as background Task agent
+
+Wait for both to complete before continuing.
+
+## Finalize Phase
+
+7. `/compound-engineering:resolve_todo_parallel` — resolve any findings from the review
+8. `/compound-engineering:feature-video` — record the final walkthrough and add to PR
+9. Output `<promise>DONE</promise>` when video is in PR
+
+Start with step 1 now.

plugins/compound-engineering/commands/test-xcode.md

@@ -1,7 +1,8 @@
 ---
-name: xcode-test
+name: test-xcode
 description: Build and test iOS apps on simulator using XcodeBuildMCP
 argument-hint: "[scheme name or 'current' to use default]"
+disable-model-invocation: true
 ---
 
 # Xcode Test Command

plugins/compound-engineering/commands/triage.md

@@ -2,6 +2,7 @@
 name: triage
 description: Triage and categorize findings for the CLI todo system
 argument-hint: "[findings list or source type]"
+disable-model-invocation: true
 ---
 
 - First set the /model to Haiku

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:
@@ -85,9 +87,21 @@ Use **AskUserQuestion tool** to present next steps:
 **Question:** "Brainstorm captured. What would you like to do next?"
 
 **Options:**
-1. **Proceed to planning** - Run `/workflows:plan` (will auto-detect this brainstorm)
-2. **Refine design further** - Continue exploring
-3. **Done for now** - Return later
+1. **Review and refine** - Improve the document through structured self-review
+2. **Proceed to planning** - Run `/workflows:plan` (will auto-detect this brainstorm)
+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":**
+
+Load the `document-review` skill and apply it to the brainstorm document.
+
+When document-review returns "Review complete", present next steps:
+
+1. **Move to planning** - Continue to `/workflows:plan` with this document
+2. **Done for now** - Brainstorming complete. To start planning later: `/workflows:plan [document-path]`
 
 ## Output Summary
 

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

@@ -21,53 +21,83 @@ Captures problem solutions while context is fresh, creating structured documenta
 /workflows:compound [brief context]    # Provide additional context hint
 ```
 
-## Execution Strategy: Parallel Subagents
+## Execution Strategy: Two-Phase Orchestration
 
-This command launches multiple specialized subagents IN PARALLEL to maximize efficiency:
+<critical_requirement>
+**Only ONE file gets written - the final documentation.**
 
-### 1. **Context Analyzer** (Parallel)
+Phase 1 subagents return TEXT DATA to the orchestrator. They must NOT use Write, Edit, or create any files. Only the orchestrator (Phase 2) writes the final documentation file.
+</critical_requirement>
+
+### Phase 1: Parallel Research
+
+<parallel_tasks>
+
+Launch these subagents IN PARALLEL. Each returns text data to the orchestrator.
+
+#### 1. **Context Analyzer**
    - Extracts conversation history
    - Identifies problem type, component, symptoms
-   - Validates against solution schema
+   - Validates against schema
    - Returns: YAML frontmatter skeleton
 
-### 2. **Solution Extractor** (Parallel)
+#### 2. **Solution Extractor**
    - Analyzes all investigation steps
    - Identifies root cause
    - Extracts working solution with code examples
    - Returns: Solution content block
 
-### 3. **Related Docs Finder** (Parallel)
+#### 3. **Related Docs Finder**
    - Searches `docs/solutions/` for related documentation
    - Identifies cross-references and links
    - Finds related GitHub issues
    - Returns: Links and relationships
 
-### 4. **Prevention Strategist** (Parallel)
+#### 4. **Prevention Strategist**
    - Develops prevention strategies
    - Creates best practices guidance
    - Generates test cases if applicable
    - Returns: Prevention/testing content
 
-### 5. **Category Classifier** (Parallel)
+#### 5. **Category Classifier**
    - Determines optimal `docs/solutions/` category
    - Validates category against schema
    - Suggests filename based on slug
    - Returns: Final path and filename
 
-### 6. **Documentation Writer** (Parallel)
-   - Assembles complete markdown file
-   - Validates YAML frontmatter
-   - Formats content for readability
-   - Creates the file in correct location
+</parallel_tasks>
 
-### 7. **Optional: Specialized Agent Invocation** (Post-Documentation)
-   Based on problem type detected, automatically invoke applicable agents:
-   - **performance_issue** → `performance-oracle`
-   - **security_issue** → `security-sentinel`
-   - **database_issue** → `data-integrity-guardian`
-   - **test_failure** → `cora-test-reviewer`
-   - Any code-heavy issue → `kieran-rails-reviewer` + `code-simplicity-reviewer`
+### Phase 2: Assembly & Write
+
+<sequential_tasks>
+
+**WAIT for all Phase 1 subagents to complete before proceeding.**
+
+The orchestrating agent (main conversation) performs these steps:
+
+1. Collect all text results from Phase 1 subagents
+2. Assemble complete markdown file from the collected pieces
+3. Validate YAML frontmatter against schema
+4. Create directory if needed: `mkdir -p docs/solutions/[category]/`
+5. Write the SINGLE final file: `docs/solutions/[category]/[filename].md`
+
+</sequential_tasks>
+
+### Phase 3: Optional Enhancement
+
+**WAIT for Phase 2 to complete before proceeding.**
+
+<parallel_tasks>
+
+Based on problem type, optionally invoke specialized agents to review the documentation:
+
+- **performance_issue** → `performance-oracle`
+- **security_issue** → `security-sentinel`
+- **database_issue** → `data-integrity-guardian`
+- **test_failure** → `cora-test-reviewer`
+- Any code-heavy issue → `kieran-rails-reviewer` + `code-simplicity-reviewer`
+
+</parallel_tasks>
 
 ## What It Captures
 
@@ -110,18 +140,25 @@ This command launches multiple specialized subagents IN PARALLEL to maximize eff
 - integration-issues/
 - logic-errors/
 
+## Common Mistakes to Avoid
+
+| ❌ Wrong | ✅ Correct |
+|----------|-----------|
+| Subagents write files like `context-analysis.md`, `solution-draft.md` | Subagents return text data; orchestrator writes one final file |
+| Research and assembly run in parallel | Research completes → then assembly runs |
+| Multiple files created during workflow | Single file: `docs/solutions/[category]/[filename].md` |
+
 ## Success Output
 
 ```
-✓ Parallel documentation generation complete
+✓ Documentation complete
 
-Primary Subagent Results:
+Subagent Results:
   ✓ Context Analyzer: Identified performance_issue in brief_system
-  ✓ Solution Extractor: Extracted 3 code fixes
-  ✓ Related Docs Finder: Found 2 related issues
-  ✓ Prevention Strategist: Generated test cases
-  ✓ Category Classifier: docs/solutions/performance-issues/
-  ✓ Documentation Writer: Created complete markdown
+  ✓ Solution Extractor: 3 code fixes
+  ✓ Related Docs Finder: 2 related issues
+  ✓ Prevention Strategist: Prevention strategies, test suggestions
+  ✓ Category Classifier: `performance-issues`
 
 Specialized Agent Reviews (Auto-Triggered):
   ✓ performance-oracle: Validated query optimization approach
@@ -195,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/plan.md

@@ -178,6 +178,7 @@ Select how comprehensive you want the issue to be, simpler is mostly better.
 ---
 title: [Issue Title]
 type: [feat|fix|refactor]
+status: active
 date: YYYY-MM-DD
 ---
 
@@ -230,6 +231,7 @@ end
 ---
 title: [Issue Title]
 type: [feat|fix|refactor]
+status: active
 date: YYYY-MM-DD
 ---
 
@@ -294,6 +296,7 @@ date: YYYY-MM-DD
 ---
 title: [Issue Title]
 type: [feat|fix|refactor]
+status: active
 date: YYYY-MM-DD
 ---
 
@@ -498,25 +501,25 @@ After writing the plan file, use the **AskUserQuestion tool** to present these o
 **Options:**
 1. **Open plan in editor** - Open the plan file for review
 2. **Run `/deepen-plan`** - Enhance each section with parallel research agents (best practices, performance, UI)
-3. **Run `/plan_review`** - Get feedback from reviewers (Tiangolo, Kieran, Simplicity)
-4. **Start `/workflows:work`** - Begin implementing this plan locally
-5. **Start `/workflows:work` on remote** - Begin implementing in Claude Code on the web (use `&` to run in background)
-6. **Create Issue** - Create issue in project tracker (GitHub/Linear)
-7. **Simplify** - Reduce detail level
+3. **Run `/technical_review`** - Technical feedback from code-focused reviewers (Tiangolo, Kieran-Python, Simplicity)
+4. **Review and refine** - Improve the document through structured self-review
+5. **Start `/workflows:work`** - Begin implementing this plan locally
+6. **Start `/workflows:work` on remote** - Begin implementing in Claude Code on the web (use `&` to run in background)
+7. **Create Issue** - Create issue in project tracker (GitHub/Linear)
 
 Based on selection:
 - **Open plan in editor** → Run `open docs/plans/<plan_filename>.md` to open the file in the user's default editor
 - **`/deepen-plan`** → Call the /deepen-plan command with the plan file path to enhance with research
-- **`/plan_review`** → Call the /plan_review command with the plan file path
+- **`/technical_review`** → Call the /technical_review command with the plan file path
+- **Review and refine** → Load `document-review` skill.
 - **`/workflows:work`** → Call the /workflows:work command with the plan file path
 - **`/workflows:work` on remote** → Run `/workflows:work docs/plans/<plan_filename>.md &` to start work in background for Claude Code web
 - **Create Issue** → See "Issue Creation" section below
-- **Simplify** → Ask "What should I simplify?" then regenerate simpler version
 - **Other** (automatically provided) → Accept free text for rework or specific changes
 
 **Note:** If running `/workflows:plan` with ultrathink enabled, automatically run `/deepen-plan` after plan creation for maximum depth and grounding.
 
-Loop back to options after Simplify or Other changes until user selects `/workflows:work` or `/plan_review`.
+Loop back to options after Simplify or Other changes until user selects `/workflows:work` or `/technical_review`.
 
 ## Issue Creation
 
@@ -546,6 +549,6 @@ When user selects "Create Issue", detect their project tracker from CLAUDE.md:
 
 5. **After creation:**
    - Display the issue URL
-   - Ask if they want to proceed to `/workflows:work` or `/plan_review`
+   - Ask if they want to proceed to `/workflows:work` or `/technical_review`
 
 NEVER CODE! Just research and write the plan.

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

@@ -48,25 +48,36 @@ Ensure that the code is ready for analysis (either in worktree or on current bra
 
 </task_list>
 
+#### Protected Artifacts
+
+<protected_artifacts>
+The following paths are compound-engineering pipeline artifacts and must never be flagged for deletion, removal, or gitignore by any review agent:
+
+- `docs/plans/*.md` — Plan files created by `/workflows:plan`. These are living documents that track implementation progress (checkboxes are checked off by `/workflows:work`).
+- `docs/solutions/*.md` — Solution documents created during the pipeline.
+
+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>
 
@@ -76,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
 
@@ -207,6 +219,8 @@ 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)
 - [ ] Remove duplicate or overlapping findings

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 |
    |--------|-------|
@@ -284,7 +297,14 @@ This command takes a work document (plan, specification, or todo file) and execu
    )"
    ```
 
-4. **Notify User**
+4. **Update Plan Status**
+
+   If the input document has YAML frontmatter with a `status` field, update it to `completed`:
+   ```
+   status: active  →  status: completed
+   ```
+
+5. **Notify User**
    - Summarize what was completed
    - Link to PR
    - Note any follow-up work needed
@@ -292,6 +312,76 @@ This command takes a work document (plan, specification, or todo file) and execu
 
 ---
 
+## Swarm Mode (Optional)
+
+For complex plans with multiple independent workstreams, enable swarm mode for parallel execution with coordinated agents.
+
+### When to Use Swarm Mode
+
+| Use Swarm Mode when... | Use Standard Mode when... |
+|------------------------|---------------------------|
+| Plan has 5+ independent tasks | Plan is linear/sequential |
+| Multiple specialists needed (review + test + implement) | Single-focus work |
+| Want maximum parallelism | Simpler mental model preferred |
+| Large feature with clear phases | Small feature or bug fix |
+
+### Enabling Swarm Mode
+
+To trigger swarm execution, say:
+
+> "Make a Task list and launch an army of agent swarm subagents to build the plan"
+
+Or explicitly request: "Use swarm mode for this work"
+
+### Swarm Workflow
+
+When swarm mode is enabled, the workflow changes:
+
+1. **Create Team**
+   ```
+   Teammate({ operation: "spawnTeam", team_name: "work-{timestamp}" })
+   ```
+
+2. **Create Task List with Dependencies**
+   - Parse plan into TaskCreate items
+   - Set up blockedBy relationships for sequential dependencies
+   - Independent tasks have no blockers (can run in parallel)
+
+3. **Spawn Specialized Teammates**
+   ```
+   Task({
+     team_name: "work-{timestamp}",
+     name: "implementer",
+     subagent_type: "general-purpose",
+     prompt: "Claim implementation tasks, execute, mark complete",
+     run_in_background: true
+   })
+
+   Task({
+     team_name: "work-{timestamp}",
+     name: "tester",
+     subagent_type: "general-purpose",
+     prompt: "Claim testing tasks, run tests, mark complete",
+     run_in_background: true
+   })
+   ```
+
+4. **Coordinate and Monitor**
+   - Team lead monitors task completion
+   - Spawn additional workers as phases unblock
+   - Handle plan approval if required
+
+5. **Cleanup**
+   ```
+   Teammate({ operation: "requestShutdown", target_agent_id: "implementer" })
+   Teammate({ operation: "requestShutdown", target_agent_id: "tester" })
+   Teammate({ operation: "cleanup" })
+   ```
+
+See the `orchestrating-swarms` skill for detailed swarm patterns and best practices.
+
+---
+
 ## Key Principles
 
 ### Start Fast, Execute Faster
@@ -337,6 +427,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
 

plugins/compound-engineering/skills/compound-docs/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: compound-docs
 description: Capture solved problems as categorized documentation with YAML frontmatter for fast lookup
+disable-model-invocation: true
 allowed-tools:
   - Read # Parse conversation context
   - Write # Create resolution docs

plugins/compound-engineering/skills/create-agent-skills/SKILL.md

@@ -1,21 +1,35 @@
 ---
-name: creating-agent-skills
-description: Expert guidance for creating, writing, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices.
+name: create-agent-skills
+description: Expert guidance for creating Claude Code skills and slash commands. Use when working with SKILL.md files, authoring new skills, improving existing skills, creating slash commands, or understanding skill structure and best practices.
 ---
 
-# Creating Agent Skills
+# Creating Skills & Commands
 
-This skill teaches how to create effective Claude Code Skills following Anthropic's official specification.
+This skill teaches how to create effective Claude Code skills following the official specification from [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills).
 
-## Core Principles
+## Commands and Skills Are Now The Same Thing
 
-### 1. Skills Are Prompts
+Custom slash commands have been merged into skills. A file at `.claude/commands/review.md` and a skill at `.claude/skills/review/SKILL.md` both create `/review` and work the same way. Existing `.claude/commands/` files keep working. Skills add optional features: a directory for supporting files, frontmatter to control invocation, and automatic context loading.
 
-All prompting best practices apply. Be clear, be direct. Assume Claude is smart - only add context Claude doesn't have.
+**If a skill and a command share the same name, the skill takes precedence.**
 
-### 2. Standard Markdown Format
+## When To Create What
 
-Use YAML frontmatter + markdown body. **No XML tags** - use standard markdown headings.
+**Use a command file** (`commands/name.md`) when:
+- Simple, single-file workflow
+- No supporting files needed
+- Task-oriented action (deploy, commit, triage)
+
+**Use a skill directory** (`skills/name/SKILL.md`) when:
+- Need supporting reference files, scripts, or templates
+- Background knowledge Claude should auto-load
+- Complex enough to benefit from progressive disclosure
+
+Both use identical YAML frontmatter and markdown content format.
+
+## Standard Markdown Format
+
+Use YAML frontmatter + markdown body with **standard markdown headings**. Keep it clean and direct.
 
 ```markdown
 ---
@@ -35,25 +49,113 @@ Step-by-step procedures...
 Concrete usage examples...
 ```
 
-### 3. Progressive Disclosure
+## Frontmatter Reference
 
-Keep SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed.
+All fields are optional. Only `description` is recommended.
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | No | Display name. Lowercase letters, numbers, hyphens (max 64 chars). Defaults to directory name. |
+| `description` | Recommended | What it does AND when to use it. Claude uses this for auto-discovery. Max 1024 chars. |
+| `argument-hint` | No | Hint shown during autocomplete. Example: `[issue-number]` |
+| `disable-model-invocation` | No | Set `true` to prevent Claude auto-loading. Use for manual workflows like `/deploy`, `/commit`. Default: `false`. |
+| `user-invocable` | No | Set `false` to hide from `/` menu. Use for background knowledge. Default: `true`. |
+| `allowed-tools` | No | Tools Claude can use without permission prompts. Example: `Read, Bash(git *)` |
+| `model` | No | Model to use. Options: `haiku`, `sonnet`, `opus`. |
+| `context` | No | Set `fork` to run in isolated subagent context. |
+| `agent` | No | Subagent type when `context: fork`. Options: `Explore`, `Plan`, `general-purpose`, or custom agent name. |
+
+### Invocation Control
+
+| Frontmatter | User can invoke | Claude can invoke | When loaded |
+|-------------|----------------|-------------------|-------------|
+| (default) | Yes | Yes | Description always in context, full content loads when invoked |
+| `disable-model-invocation: true` | Yes | No | Description not in context, loads only when user invokes |
+| `user-invocable: false` | No | Yes | Description always in context, loads when relevant |
+
+**Use `disable-model-invocation: true`** for workflows with side effects: `/deploy`, `/commit`, `/triage-prs`, `/send-slack-message`. You don't want Claude deciding to deploy because your code looks ready.
+
+**Use `user-invocable: false`** for background knowledge that isn't a meaningful user action: coding conventions, domain context, legacy system docs.
+
+## Dynamic Features
+
+### Arguments
+
+Use `$ARGUMENTS` placeholder for user input. If not present in content, arguments are appended automatically.
+
+```yaml
+---
+name: fix-issue
+description: Fix a GitHub issue
+disable-model-invocation: true
+---
+
+Fix GitHub issue $ARGUMENTS following our coding standards.
+```
+
+Access individual args: `$ARGUMENTS[0]` or shorthand `$0`, `$1`, `$2`.
+
+### Dynamic Context Injection
+
+The `` !`command` `` syntax runs shell commands before content is sent to Claude:
+
+```yaml
+---
+name: pr-summary
+description: Summarize changes in a pull request
+context: fork
+agent: Explore
+---
+
+## Context
+- PR diff: !`gh pr diff`
+- Changed files: !`gh pr diff --name-only`
+
+Summarize this pull request...
+```
+
+### Running in a Subagent
+
+Add `context: fork` to run in isolation. The skill content becomes the subagent's prompt. It won't have conversation history.
+
+```yaml
+---
+name: deep-research
+description: Research a topic thoroughly
+context: fork
+agent: Explore
+---
+
+Research $ARGUMENTS thoroughly:
+1. Find relevant files
+2. Analyze the code
+3. Summarize findings
+```
+
+## Progressive Disclosure
+
+Keep SKILL.md under 500 lines. Split detailed content into reference files:
 
 ```
 my-skill/
-├── SKILL.md              # Entry point (required)
-├── reference.md          # Detailed docs (loaded when needed)
-├── examples.md           # Usage examples
-└── scripts/              # Utility scripts (executed, not loaded)
+├── SKILL.md           # Entry point (required, overview + navigation)
+├── reference.md       # Detailed docs (loaded when needed)
+├── examples.md        # Usage examples (loaded when needed)
+└── scripts/
+    └── helper.py      # Utility script (executed, not loaded)
 ```
 
-### 4. Effective Descriptions
+Link from SKILL.md: `For API details, see [reference.md](reference.md).`
 
-The description field enables skill discovery. Include both what the skill does AND when to use it. Write in third person.
+Keep references **one level deep** from SKILL.md. Avoid nested chains.
+
+## Effective Descriptions
+
+The description enables skill discovery. Include both **what** it does and **when** to use it.
 
 **Good:**
 ```yaml
-description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
 ```
 
 **Bad:**
@@ -61,239 +163,113 @@ description: Extracts text and tables from PDF files, fills forms, merges docume
 description: Helps with documents
 ```
 
-## Skill Structure
-
-### Required Frontmatter
-
-| Field | Required | Max Length | Description |
-|-------|----------|------------|-------------|
-| `name` | Yes | 64 chars | Lowercase letters, numbers, hyphens only |
-| `description` | Yes | 1024 chars | What it does AND when to use it |
-| `allowed-tools` | No | - | Tools Claude can use without asking |
-| `model` | No | - | Specific model to use |
-
-### Naming Conventions
-
-Use **gerund form** (verb + -ing) for skill names:
-
-- `processing-pdfs`
-- `analyzing-spreadsheets`
-- `generating-commit-messages`
-- `reviewing-code`
-
-Avoid: `helper`, `utils`, `tools`, `anthropic-*`, `claude-*`
-
-### Body Structure
-
-Use standard markdown headings:
-
-```markdown
-# Skill Name
-
-## Quick Start
-Fastest path to value...
-
-## Instructions
-Core guidance Claude follows...
-
-## Examples
-Input/output pairs showing expected behavior...
-
-## Advanced Features
-Additional capabilities (link to reference files)...
-
-## Guidelines
-Rules and constraints...
-```
-
 ## What Would You Like To Do?
 
 1. **Create new skill** - Build from scratch
-2. **Audit existing skill** - Check against best practices
-3. **Add component** - Add workflow/reference/example
-4. **Get guidance** - Understand skill design
+2. **Create new command** - Build a slash command
+3. **Audit existing skill** - Check against best practices
+4. **Add component** - Add workflow/reference/example
+5. **Get guidance** - Understand skill design
 
-## Creating a New Skill
+## Creating a New Skill or Command
 
 ### Step 1: Choose Type
 
-**Simple skill (single file):**
-- Under 500 lines
-- Self-contained guidance
-- No complex workflows
+Ask: Is this a manual workflow (deploy, commit, triage) or background knowledge (conventions, patterns)?
 
-**Progressive disclosure skill (multiple files):**
-- SKILL.md as overview
-- Reference files for detailed docs
-- Scripts for utilities
+- **Manual workflow** → command with `disable-model-invocation: true`
+- **Background knowledge** → skill without `disable-model-invocation`
+- **Complex with supporting files** → skill directory
 
-### Step 2: Create SKILL.md
+### Step 2: Create the File
 
+**Command:**
 ```markdown
 ---
-name: your-skill-name
-description: [What it does]. Use when [trigger conditions].
+name: my-command
+description: What this command does
+argument-hint: [expected arguments]
+disable-model-invocation: true
+allowed-tools: Bash(gh *), Read
 ---
 
-# Your Skill Name
+# Command Title
 
-## Quick Start
+## Workflow
 
-[Immediate actionable example]
+### Step 1: Gather Context
+...
 
-```[language]
-[Code example]
+### Step 2: Execute
+...
+
+## Success Criteria
+- [ ] Expected outcome 1
+- [ ] Expected outcome 2
 ```
 
-## Instructions
+**Skill:**
+```markdown
+---
+name: my-skill
+description: What it does. Use when [trigger conditions].
+---
 
+# Skill Title
+
+## Quick Start
+[Immediate actionable example]
+
+## Instructions
 [Core guidance]
 
 ## Examples
-
-**Example 1:**
-Input: [description]
-Output:
-```
-[result]
-```
-
-## Guidelines
-
-- [Constraint 1]
-- [Constraint 2]
+[Concrete input/output pairs]
 ```
 
 ### Step 3: Add Reference Files (If Needed)
 
 Link from SKILL.md to detailed content:
-
 ```markdown
-For API reference, see [REFERENCE.md](REFERENCE.md).
-For form filling guide, see [FORMS.md](FORMS.md).
+For API reference, see [reference.md](reference.md).
+For form filling guide, see [forms.md](forms.md).
 ```
 
-Keep references **one level deep** from SKILL.md.
-
-### Step 4: Add Scripts (If Needed)
-
-Scripts execute without loading into context:
-
-```markdown
-## Utility Scripts
-
-Extract fields:
-```bash
-python scripts/analyze.py input.pdf > fields.json
-```
-```
-
-### Step 5: Test With Real Usage
+### Step 4: Test With Real Usage
 
 1. Test with actual tasks, not test scenarios
-2. Observe where Claude struggles
-3. Refine based on real behavior
-4. Test with Haiku, Sonnet, and Opus
+2. Invoke directly with `/skill-name` to verify
+3. Check auto-triggering by asking something that matches the description
+4. Refine based on real behavior
 
-## Auditing Existing Skills
-
-Check against this rubric:
+## Audit Checklist
 
 - [ ] Valid YAML frontmatter (name + description)
-- [ ] Description includes trigger keywords
+- [ ] Description includes trigger keywords and is specific
 - [ ] Uses standard markdown headings (not XML tags)
 - [ ] SKILL.md under 500 lines
-- [ ] References one level deep
+- [ ] `disable-model-invocation: true` if it has side effects
+- [ ] `allowed-tools` set if specific tools needed
+- [ ] References one level deep, properly linked
 - [ ] Examples are concrete, not abstract
-- [ ] Consistent terminology
-- [ ] No time-sensitive information
-- [ ] Scripts handle errors explicitly
-
-## Common Patterns
-
-### Template Pattern
-
-Provide output templates for consistent results:
-
-```markdown
-## Report Template
-
-```markdown
-# [Analysis Title]
-
-## Executive Summary
-[One paragraph overview]
-
-## Key Findings
-- Finding 1
-- Finding 2
-
-## Recommendations
-1. [Action item]
-2. [Action item]
-```
-```
-
-### Workflow Pattern
-
-For complex multi-step tasks:
-
-```markdown
-## Migration Workflow
-
-Copy this checklist:
-
-```
-- [ ] Step 1: Backup database
-- [ ] Step 2: Run migration script
-- [ ] Step 3: Validate output
-- [ ] Step 4: Update configuration
-```
-
-**Step 1: Backup database**
-Run: `./scripts/backup.sh`
-...
-```
-
-### Conditional Pattern
-
-Guide through decision points:
-
-```markdown
-## Choose Your Approach
-
-**Creating new content?** Follow "Creation workflow" below.
-**Editing existing?** Follow "Editing workflow" below.
-```
+- [ ] Tested with real usage
 
 ## Anti-Patterns to Avoid
 
-- **XML tags in body** - Use markdown headings instead
+- **XML tags in body** - Use standard markdown headings
 - **Vague descriptions** - Be specific with trigger keywords
 - **Deep nesting** - Keep references one level from SKILL.md
+- **Missing invocation control** - Side-effect workflows need `disable-model-invocation: true`
 - **Too many options** - Provide a default with escape hatch
-- **Windows paths** - Always use forward slashes
-- **Punting to Claude** - Scripts should handle errors
-- **Time-sensitive info** - Use "old patterns" section instead
+- **Punting to Claude** - Scripts should handle errors explicitly
 
 ## Reference Files
 
 For detailed guidance, see:
-
-- [official-spec.md](references/official-spec.md) - Anthropic's official skill specification
+- [official-spec.md](references/official-spec.md) - Official skill specification
 - [best-practices.md](references/best-practices.md) - Skill authoring best practices
 
-## Success Criteria
+## Sources
 
-A well-structured skill:
-- Has valid YAML frontmatter with descriptive name and description
-- Uses standard markdown headings (not XML tags)
-- Keeps SKILL.md under 500 lines
-- Links to reference files for detailed content
-- Includes concrete examples with input/output pairs
-- Has been tested with real usage
-
-Sources:
-- [Agent Skills - Claude Code Docs](https://code.claude.com/docs/en/skills)
-- [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+- [Extend Claude with skills - Official Docs](https://code.claude.com/docs/en/skills)
 - [GitHub - anthropics/skills](https://github.com/anthropics/skills)

plugins/compound-engineering/skills/create-agent-skills/references/official-spec.md

@@ -1,36 +1,56 @@
-# Anthropic Official Skill Specification
+# Official Skill Specification (2026)
 
 Source: [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills)
 
+## Commands and Skills Are Merged
+
+Custom slash commands have been merged into skills. A file at `.claude/commands/review.md` and a skill at `.claude/skills/review/SKILL.md` both create `/review` and work the same way. Existing `.claude/commands/` files keep working. Skills add optional features: a directory for supporting files, frontmatter to control invocation, and automatic context loading.
+
+If a skill and a command share the same name, the skill takes precedence.
+
 ## SKILL.md File Structure
 
-Every Skill requires a `SKILL.md` file with YAML frontmatter followed by Markdown instructions.
-
-### Basic Format
+Every skill requires a `SKILL.md` file with YAML frontmatter followed by standard markdown instructions.
 
 ```markdown
 ---
 name: your-skill-name
-description: Brief description of what this Skill does and when to use it
+description: What it does and when to use it
 ---
 
 # Your Skill Name
 
 ## Instructions
-Provide clear, step-by-step guidance for Claude.
+Clear, step-by-step guidance.
 
 ## Examples
-Show concrete examples of using this Skill.
+Concrete examples of using this skill.
 ```
 
-## Required Frontmatter Fields
+## Complete Frontmatter Reference
+
+All fields are optional. Only `description` is recommended.
 
 | Field | Required | Description |
 |-------|----------|-------------|
-| `name` | Yes | Skill name using lowercase letters, numbers, and hyphens only (max 64 characters). Should match the directory name. |
-| `description` | Yes | What the Skill does and when to use it (max 1024 characters). Claude uses this to decide when to apply the Skill. |
-| `allowed-tools` | No | Tools Claude can use without asking permission when this Skill is active. Example: `Read, Grep, Glob` |
-| `model` | No | Specific model to use when this Skill is active (e.g., `claude-sonnet-4-20250514`). Defaults to the conversation's model. |
+| `name` | No | Display name. Lowercase letters, numbers, hyphens only (max 64 chars). Defaults to directory name if omitted. |
+| `description` | Recommended | What it does AND when to use it (max 1024 chars). Claude uses this to decide when to apply the skill. |
+| `argument-hint` | No | Hint shown during autocomplete. Example: `[issue-number]` or `[filename] [format]` |
+| `disable-model-invocation` | No | Set `true` to prevent Claude from auto-loading. Use for manual workflows. Default: `false` |
+| `user-invocable` | No | Set `false` to hide from `/` menu. Use for background knowledge. Default: `true` |
+| `allowed-tools` | No | Tools Claude can use without permission prompts. Example: `Read, Bash(git *)` |
+| `model` | No | Model to use: `haiku`, `sonnet`, or `opus` |
+| `context` | No | Set `fork` to run in isolated subagent context |
+| `agent` | No | Subagent type when `context: fork`. Options: `Explore`, `Plan`, `general-purpose`, or custom agent name |
+| `hooks` | No | Hooks scoped to this skill's lifecycle |
+
+## Invocation Control
+
+| Frontmatter | User can invoke | Claude can invoke | When loaded into context |
+|-------------|----------------|-------------------|--------------------------|
+| (default) | Yes | Yes | Description always in context, full skill loads when invoked |
+| `disable-model-invocation: true` | Yes | No | Description not in context, full skill loads when you invoke |
+| `user-invocable: false` | No | Yes | Description always in context, full skill loads when invoked |
 
 ## Skill Locations & Priority
 
@@ -40,146 +60,75 @@ Enterprise (highest priority) → Personal → Project → Plugin (lowest priori
 
 | Type | Path | Applies to |
 |------|------|-----------|
-| **Enterprise** | See managed settings | All users in organization |
-| **Personal** | `~/.claude/skills/` | You, across all projects |
-| **Project** | `.claude/skills/` | Anyone working in repository |
-| **Plugin** | Bundled with plugins | Anyone with plugin installed |
+| Enterprise | See managed settings | All users in organization |
+| Personal | `~/.claude/skills/<name>/SKILL.md` | You, across all projects |
+| Project | `.claude/skills/<name>/SKILL.md` | Anyone working in repository |
+| Plugin | `<plugin>/skills/<name>/SKILL.md` | Where plugin is enabled |
+
+Plugin skills use a `plugin-name:skill-name` namespace, so they cannot conflict with other levels.
 
 ## How Skills Work
 
-1. **Discovery**: Claude loads only name and description at startup
-2. **Activation**: When your request matches a Skill's description, Claude asks for confirmation
-3. **Execution**: Claude follows the Skill's instructions and loads referenced files
+1. **Discovery**: Claude loads only name and description at startup (2% of context window budget)
+2. **Activation**: When your request matches a skill's description, Claude loads the full content
+3. **Execution**: Claude follows the skill's instructions
 
-**Key Principle**: Skills are **model-invoked** — Claude automatically decides which Skills to use based on your request.
+## String Substitutions
 
-## Progressive Disclosure Pattern
+| Variable | Description |
+|----------|-------------|
+| `$ARGUMENTS` | All arguments passed when invoking |
+| `$ARGUMENTS[N]` | Specific argument by 0-based index |
+| `$N` | Shorthand for `$ARGUMENTS[N]` |
+| `${CLAUDE_SESSION_ID}` | Current session ID |
 
-Keep `SKILL.md` under 500 lines by linking to supporting files:
+## Dynamic Context Injection
+
+The `` !`command` `` syntax runs shell commands before content is sent to Claude:
+
+```markdown
+## Context
+- Current branch: !`git branch --show-current`
+- PR diff: !`gh pr diff`
+```
+
+Commands execute immediately and their output replaces the placeholder. Claude only sees the final result.
+
+## Progressive Disclosure
 
 ```
 my-skill/
-├── SKILL.md (required - overview and navigation)
-├── reference.md (detailed API docs - loaded when needed)
-├── examples.md (usage examples - loaded when needed)
+├── SKILL.md           # Entry point (required)
+├── reference.md       # Detailed docs (loaded when needed)
+├── examples.md        # Usage examples (loaded when needed)
 └── scripts/
-    └── helper.py (utility script - executed, not loaded)
+    └── helper.py      # Utility script (executed, not loaded)
 ```
 
-### Example SKILL.md with References
-
+Keep SKILL.md under 500 lines. Link to supporting files:
 ```markdown
----
-name: pdf-processing
-description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
-allowed-tools: Read, Bash(python:*)
----
-
-# PDF Processing
-
-## Quick start
-
-Extract text:
-```python
-import pdfplumber
-with pdfplumber.open("doc.pdf") as pdf:
-    text = pdf.pages[0].extract_text()
+For API details, see [reference.md](reference.md).
 ```
 
-For form filling, see [FORMS.md](FORMS.md).
-For detailed API reference, see [REFERENCE.md](REFERENCE.md).
+## Running in a Subagent
 
-## Requirements
-
-Packages must be installed:
-```bash
-pip install pypdf pdfplumber
-```
-```
-
-## Restricting Tool Access
+Add `context: fork` to run in isolation:
 
 ```yaml
 ---
-name: reading-files-safely
-description: Read files without making changes. Use when you need read-only file access.
-allowed-tools: Read, Grep, Glob
----
-```
-
-Benefits:
-- Read-only Skills that shouldn't modify files
-- Limited scope for specific tasks
-- Security-sensitive workflows
-
-## Writing Effective Descriptions
-
-The `description` field enables Skill discovery and should include both what the Skill does and when to use it.
-
-**Always write in third person.** The description is injected into the system prompt.
-
-- **Good:** "Processes Excel files and generates reports"
-- **Avoid:** "I can help you process Excel files"
-- **Avoid:** "You can use this to process Excel files"
-
-**Be specific and include key terms:**
-
-```yaml
-description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
-```
-
-**Avoid vague descriptions:**
-
-```yaml
-description: Helps with documents  # Too vague!
-```
-
-## Complete Example: Commit Message Generator
-
-```markdown
----
-name: generating-commit-messages
-description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
+name: deep-research
+description: Research a topic thoroughly
+context: fork
+agent: Explore
 ---
 
-# Generating Commit Messages
-
-## Instructions
-
-1. Run `git diff --staged` to see changes
-2. I'll suggest a commit message with:
-   - Summary under 50 characters
-   - Detailed description
-   - Affected components
-
-## Best practices
-
-- Use present tense
-- Explain what and why, not how
+Research $ARGUMENTS thoroughly...
 ```
 
-## Complete Example: Code Explanation Skill
-
-```markdown
----
-name: explaining-code
-description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
----
-
-# Explaining Code
-
-When explaining code, always include:
-
-1. **Start with an analogy**: Compare the code to something from everyday life
-2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
-3. **Walk through the code**: Explain step-by-step what happens
-4. **Highlight a gotcha**: What's a common misconception?
-
-Keep explanations conversational. For complex concepts, use multiple analogies.
-```
+The skill content becomes the subagent's prompt. It won't have access to conversation history.
 
 ## Distribution
 
-- **Project Skills**: Commit `.claude/skills/` to version control
-- **Plugins**: Add `skills/` directory to plugin with Skill folders
+- **Project skills**: Commit `.claude/skills/` to version control
+- **Plugins**: Add `skills/` directory to plugin
 - **Enterprise**: Deploy organization-wide through managed settings

plugins/compound-engineering/skills/create-agent-skills/references/skill-structure.md

@@ -1,372 +1,152 @@
-<overview>
-Skills have three structural components: YAML frontmatter (metadata), pure XML body structure (content organization), and progressive disclosure (file organization). This reference defines requirements and best practices for each component.
-</overview>
+# Skill Structure Reference
 
-<xml_structure_requirements>
-<critical_rule>
-**Remove ALL markdown headings (#, ##, ###) from skill body content.** Replace with semantic XML tags. Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links).
-</critical_rule>
+Skills have three structural components: YAML frontmatter (metadata), standard markdown body (content), and progressive disclosure (file organization).
 
-<required_tags>
-Every skill MUST have these three tags:
+## Body Format
 
-- **`<objective>`** - What the skill does and why it matters (1-3 paragraphs)
-- **`<quick_start>`** - Immediate, actionable guidance (minimal working example)
-- **`<success_criteria>`** or **`<when_successful>`** - How to know it worked
-</required_tags>
+Use **standard markdown headings** for structure. Keep markdown formatting within content (bold, italic, lists, code blocks, links).
 
-<conditional_tags>
-Add based on skill complexity and domain requirements:
+```markdown
+---
+name: my-skill
+description: What it does and when to use it
+---
 
-- **`<context>`** - Background/situational information
-- **`<workflow>` or `<process>`** - Step-by-step procedures
-- **`<advanced_features>`** - Deep-dive topics (progressive disclosure)
-- **`<validation>`** - How to verify outputs
-- **`<examples>`** - Multi-shot learning
-- **`<anti_patterns>`** - Common mistakes to avoid
-- **`<security_checklist>`** - Non-negotiable security patterns
-- **`<testing>`** - Testing workflows
-- **`<common_patterns>`** - Code examples and recipes
-- **`<reference_guides>` or `<detailed_references>`** - Links to reference files
+# Skill Name
 
-See [use-xml-tags.md](use-xml-tags.md) for detailed guidance on each tag.
-</conditional_tags>
+## Quick Start
+Immediate actionable guidance...
 
-<tag_selection_intelligence>
-**Simple skills** (single domain, straightforward):
-- Required tags only
-- Example: Text extraction, file format conversion
+## Instructions
+Step-by-step procedures...
 
-**Medium skills** (multiple patterns, some complexity):
-- Required tags + workflow/examples as needed
-- Example: Document processing with steps, API integration
+## Examples
+Concrete usage examples...
 
-**Complex skills** (multiple domains, security, APIs):
-- Required tags + conditional tags as appropriate
-- Example: Payment processing, authentication systems, multi-step workflows
-</tag_selection_intelligence>
-
-<xml_nesting>
-Properly nest XML tags for hierarchical content:
-
-```xml
-<examples>
-<example number="1">
-<input>User input</input>
-<output>Expected output</output>
-</example>
-</examples>
+## Guidelines
+Rules and constraints...
 ```
 
-Always close tags:
-```xml
-<objective>
-Content here
-</objective>
-```
-</xml_nesting>
+## Recommended Sections
 
-<tag_naming_conventions>
-Use descriptive, semantic names:
-- `<workflow>` not `<steps>`
-- `<success_criteria>` not `<done>`
-- `<anti_patterns>` not `<dont_do>`
+Every skill should have:
 
-Be consistent within your skill. If you use `<workflow>`, don't also use `<process>` for the same purpose (unless they serve different roles).
-</tag_naming_conventions>
-</xml_structure_requirements>
+- **Quick Start** - Immediate, actionable guidance (minimal working example)
+- **Instructions** - Core step-by-step guidance
+- **Success Criteria** - How to know it worked
+
+Add based on complexity:
+
+- **Context** - Background/situational information
+- **Workflow** - Multi-step procedures
+- **Examples** - Concrete input/output pairs
+- **Advanced Features** - Deep-dive topics (link to reference files)
+- **Anti-Patterns** - Common mistakes to avoid
+- **Guidelines** - Rules and constraints
+
+## YAML Frontmatter
+
+### Required/Recommended Fields
 
-<yaml_requirements>
-<required_fields>
 ```yaml
 ---
 name: skill-name-here
-description: What it does and when to use it (third person, specific triggers)
+description: What it does and when to use it (specific triggers included)
 ---
 ```
-</required_fields>
 
-<name_field>
-**Validation rules**:
+### Name Field
+
+**Validation rules:**
 - Maximum 64 characters
 - Lowercase letters, numbers, hyphens only
-- No XML tags
+- Must match directory name
 - No reserved words: "anthropic", "claude"
-- Must match directory name exactly
 
-**Examples**:
-- ✅ `process-pdfs`
-- ✅ `manage-facebook-ads`
-- ✅ `setup-stripe-payments`
-- ❌ `PDF_Processor` (uppercase)
-- ❌ `helper` (vague)
-- ❌ `claude-helper` (reserved word)
-</name_field>
+**Examples:**
+- `triage-prs`
+- `deploy-production`
+- `review-code`
+- `setup-stripe-payments`
 
-<description_field>
-**Validation rules**:
-- Non-empty, maximum 1024 characters
-- No XML tags
-- Third person (never first or second person)
+**Avoid:** `helper`, `utils`, `tools`, generic names
+
+### Description Field
+
+**Validation rules:**
+- Maximum 1024 characters
 - Include what it does AND when to use it
+- Third person voice
 
-**Critical rule**: Always write in third person.
-- ✅ "Processes Excel files and generates reports"
-- ❌ "I can help you process Excel files"
-- ❌ "You can use this to process Excel files"
-
-**Structure**: Include both capabilities and triggers.
-
-**Effective examples**:
+**Good:**
 ```yaml
 description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
 ```
 
-```yaml
-description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
-```
-
-```yaml
-description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
-```
-
-**Avoid**:
+**Bad:**
 ```yaml
 description: Helps with documents
 ```
 
-```yaml
-description: Processes data
+### Optional Fields
+
+| Field | Description |
+|-------|-------------|
+| `argument-hint` | Usage hints. Example: `[issue-number]` |
+| `disable-model-invocation` | `true` to prevent auto-loading. Use for side-effect workflows. |
+| `user-invocable` | `false` to hide from `/` menu. Use for background knowledge. |
+| `allowed-tools` | Tools without permission prompts. Example: `Read, Bash(git *)` |
+| `model` | `haiku`, `sonnet`, or `opus` |
+| `context` | `fork` for isolated subagent execution |
+| `agent` | Subagent type: `Explore`, `Plan`, `general-purpose`, or custom |
+
+## Naming Conventions
+
+Use descriptive names that indicate purpose:
+
+| Pattern | Examples |
+|---------|----------|
+| Action-oriented | `triage-prs`, `deploy-production`, `review-code` |
+| Domain-specific | `setup-stripe-payments`, `manage-facebook-ads` |
+| Descriptive | `git-worktree`, `frontend-design`, `dhh-rails-style` |
+
+## Progressive Disclosure
+
+Keep SKILL.md under 500 lines. Split into reference files:
+
+```
+my-skill/
+├── SKILL.md           # Entry point (required, overview + navigation)
+├── reference.md       # Detailed docs (loaded when needed)
+├── examples.md        # Usage examples (loaded when needed)
+└── scripts/
+    └── helper.py      # Utility script (executed, not loaded)
 ```
-</description_field>
-</yaml_requirements>
 
-<naming_conventions>
-Use **verb-noun convention** for skill names:
-
-<pattern name="create">
-Building/authoring tools
-
-Examples: `create-agent-skills`, `create-hooks`, `create-landing-pages`
-</pattern>
-
-<pattern name="manage">
-Managing external services or resources
-
-Examples: `manage-facebook-ads`, `manage-zoom`, `manage-stripe`, `manage-supabase`
-</pattern>
-
-<pattern name="setup">
-Configuration/integration tasks
-
-Examples: `setup-stripe-payments`, `setup-meta-tracking`
-</pattern>
-
-<pattern name="generate">
-Generation tasks
-
-Examples: `generate-ai-images`
-</pattern>
-
-<avoid_patterns>
-- Vague: `helper`, `utils`, `tools`
-- Generic: `documents`, `data`, `files`
-- Reserved words: `anthropic-helper`, `claude-tools`
-- Inconsistent: Directory `facebook-ads` but name `facebook-ads-manager`
-</avoid_patterns>
-</naming_conventions>
-
-<progressive_disclosure>
-<principle>
-SKILL.md serves as an overview that points to detailed materials as needed. This keeps context window usage efficient.
-</principle>
-
-<practical_guidance>
-- Keep SKILL.md body under 500 lines
-- Split content into separate files when approaching this limit
+**Rules:**
 - Keep references one level deep from SKILL.md
 - Add table of contents to reference files over 100 lines
-</practical_guidance>
+- Use forward slashes in paths: `scripts/helper.py`
+- Name files descriptively: `form_validation_rules.md` not `doc2.md`
 
-<pattern name="high_level_guide">
-Quick start in SKILL.md, details in reference files:
+## Validation Checklist
 
-```markdown
----
-name: pdf-processing
-description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
----
+Before finalizing:
 
-<objective>
-Extract text and tables from PDF files, fill forms, and merge documents using Python libraries.
-</objective>
+- [ ] YAML frontmatter valid (name matches directory, description specific)
+- [ ] Uses standard markdown headings (not XML tags)
+- [ ] Has Quick Start, Instructions, and Success Criteria sections
+- [ ] `disable-model-invocation: true` if skill has side effects
+- [ ] SKILL.md under 500 lines
+- [ ] Reference files linked properly from SKILL.md
+- [ ] File paths use forward slashes
+- [ ] Tested with real usage
 
-<quick_start>
-Extract text with pdfplumber:
+## Anti-Patterns
 
-```python
-import pdfplumber
-with pdfplumber.open("file.pdf") as pdf:
-    text = pdf.pages[0].extract_text()
-```
-</quick_start>
-
-<advanced_features>
-**Form filling**: See [forms.md](forms.md)
-**API reference**: See [reference.md](reference.md)
-</advanced_features>
-```
-
-Claude loads forms.md or reference.md only when needed.
-</pattern>
-
-<pattern name="domain_organization">
-For skills with multiple domains, organize by domain to avoid loading irrelevant context:
-
-```
-bigquery-skill/
-├── SKILL.md (overview and navigation)
-└── reference/
-    ├── finance.md (revenue, billing metrics)
-    ├── sales.md (opportunities, pipeline)
-    ├── product.md (API usage, features)
-    └── marketing.md (campaigns, attribution)
-```
-
-When user asks about revenue, Claude reads only finance.md. Other files stay on filesystem consuming zero tokens.
-</pattern>
-
-<pattern name="conditional_details">
-Show basic content in SKILL.md, link to advanced in reference files:
-
-```xml
-<objective>
-Process DOCX files with creation and editing capabilities.
-</objective>
-
-<quick_start>
-<creating_documents>
-Use docx-js for new documents. See [docx-js.md](docx-js.md).
-</creating_documents>
-
-<editing_documents>
-For simple edits, modify XML directly.
-
-**For tracked changes**: See [redlining.md](redlining.md)
-**For OOXML details**: See [ooxml.md](ooxml.md)
-</editing_documents>
-</quick_start>
-```
-
-Claude reads redlining.md or ooxml.md only when the user needs those features.
-</pattern>
-
-<critical_rules>
-**Keep references one level deep**: All reference files should link directly from SKILL.md. Avoid nested references (SKILL.md → advanced.md → details.md) as Claude may only partially read deeply nested files.
-
-**Add table of contents to long files**: For reference files over 100 lines, include a table of contents at the top.
-
-**Use pure XML in reference files**: Reference files should also use pure XML structure (no markdown headings in body).
-</critical_rules>
-</progressive_disclosure>
-
-<file_organization>
-<filesystem_navigation>
-Claude navigates your skill directory using bash commands:
-
-- Use forward slashes: `reference/guide.md` (not `reference\guide.md`)
-- Name files descriptively: `form_validation_rules.md` (not `doc2.md`)
-- Organize by domain: `reference/finance.md`, `reference/sales.md`
-</filesystem_navigation>
-
-<directory_structure>
-Typical skill structure:
-
-```
-skill-name/
-├── SKILL.md (main entry point, pure XML structure)
-├── references/ (optional, for progressive disclosure)
-│   ├── guide-1.md (pure XML structure)
-│   ├── guide-2.md (pure XML structure)
-│   └── examples.md (pure XML structure)
-└── scripts/ (optional, for utility scripts)
-    ├── validate.py
-    └── process.py
-```
-</directory_structure>
-</file_organization>
-
-<anti_patterns>
-<pitfall name="markdown_headings_in_body">
-❌ Do NOT use markdown headings in skill body:
-
-```markdown
-# PDF Processing
-
-## Quick start
-Extract text...
-
-## Advanced features
-Form filling...
-```
-
-✅ Use pure XML structure:
-
-```xml
-<objective>
-PDF processing with text extraction, form filling, and merging.
-</objective>
-
-<quick_start>
-Extract text...
-</quick_start>
-
-<advanced_features>
-Form filling...
-</advanced_features>
-```
-</pitfall>
-
-<pitfall name="vague_descriptions">
-- ❌ "Helps with documents"
-- ✅ "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."
-</pitfall>
-
-<pitfall name="inconsistent_pov">
-- ❌ "I can help you process Excel files"
-- ✅ "Processes Excel files and generates reports"
-</pitfall>
-
-<pitfall name="wrong_naming_convention">
-- ❌ Directory: `facebook-ads`, Name: `facebook-ads-manager`
-- ✅ Directory: `manage-facebook-ads`, Name: `manage-facebook-ads`
-- ❌ Directory: `stripe-integration`, Name: `stripe`
-- ✅ Directory: `setup-stripe-payments`, Name: `setup-stripe-payments`
-</pitfall>
-
-<pitfall name="deeply_nested_references">
-Keep references one level deep from SKILL.md. Claude may only partially read nested files (SKILL.md → advanced.md → details.md).
-</pitfall>
-
-<pitfall name="windows_paths">
-Always use forward slashes: `scripts/helper.py` (not `scripts\helper.py`)
-</pitfall>
-
-<pitfall name="missing_required_tags">
-Every skill must have: `<objective>`, `<quick_start>`, and `<success_criteria>` (or `<when_successful>`).
-</pitfall>
-</anti_patterns>
-
-<validation_checklist>
-Before finalizing a skill, verify:
-
-- ✅ YAML frontmatter valid (name matches directory, description in third person)
-- ✅ No markdown headings in body (pure XML structure)
-- ✅ Required tags present: objective, quick_start, success_criteria
-- ✅ Conditional tags appropriate for complexity level
-- ✅ All XML tags properly closed
-- ✅ Progressive disclosure applied (SKILL.md < 500 lines)
-- ✅ Reference files use pure XML structure
-- ✅ File paths use forward slashes
-- ✅ Descriptive file names
-</validation_checklist>
+- **XML tags in body** - Use standard markdown headings
+- **Vague descriptions** - Be specific with trigger keywords
+- **Deep nesting** - Keep references one level from SKILL.md
+- **Missing invocation control** - Side-effect workflows need `disable-model-invocation: true`
+- **Inconsistent naming** - Directory name must match `name` field
+- **Windows paths** - Always use forward slashes

plugins/compound-engineering/skills/document-review/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: document-review
+description: This skill should be used to refine brainstorm or plan documents before proceeding to the next workflow step. It applies when a brainstorm or plan document exists and the user wants to improve it.
+---
+
+# Document Review
+
+Improve brainstorm or plan documents through structured review.
+
+## Step 1: Get the Document
+
+**If a document path is provided:** Read it, then proceed to Step 2.
+
+**If no document is specified:** Ask which document to review, or look for the most recent brainstorm/plan in `docs/brainstorms/` or `docs/plans/`.
+
+## Step 2: Assess
+
+Read through the document and ask:
+
+- What is unclear?
+- What is unnecessary?
+- What decision is being avoided?
+- What assumptions are unstated?
+- Where could scope accidentally expand?
+
+These questions surface issues. Don't fix yet—just note what you find.
+
+## Step 3: Evaluate
+
+Score the document against these criteria:
+
+| Criterion | What to Check |
+|-----------|---------------|
+| **Clarity** | Problem statement is clear, no vague language ("probably," "consider," "try to") |
+| **Completeness** | Required sections present, constraints stated, open questions flagged |
+| **Specificity** | Concrete enough for next step (brainstorm → can plan, plan → can implement) |
+| **YAGNI** | No hypothetical features, simplest approach chosen |
+
+If invoked within a workflow (after `/workflows:brainstorm` or `/workflows:plan`), also check:
+- **User intent fidelity** — Document reflects what was discussed, assumptions validated
+
+## Step 4: Identify the Critical Improvement
+
+Among everything found in Steps 2-3, does one issue stand out? If something would significantly improve the document's quality, this is the "must address" item. Highlight it prominently.
+
+## Step 5: Make Changes
+
+Present your findings, then:
+
+1. **Auto-fix** minor issues (vague language, formatting) without asking
+2. **Ask approval** before substantive changes (restructuring, removing sections, changing meaning)
+3. **Update** the document inline—no separate files, no metadata sections
+
+### Simplification Guidance
+
+Simplification is purposeful removal of unnecessary complexity, not shortening for its own sake.
+
+**Simplify when:**
+- Content serves hypothetical future needs, not current ones
+- Sections repeat information already covered elsewhere
+- Detail exceeds what's needed to take the next step
+- Abstractions or structure add overhead without clarity
+
+**Don't simplify:**
+- Constraints or edge cases that affect implementation
+- Rationale that explains why alternatives were rejected
+- Open questions that need resolution
+
+## Step 6: Offer Next Action
+
+After changes are complete, ask:
+
+1. **Refine again** - Another review pass
+2. **Review complete** - Document is ready
+
+### Iteration Guidance
+
+After 2 refinement passes, recommend completion—diminishing returns are likely. But if the user wants to continue, allow it.
+
+Return control to the caller (workflow or user) after selection.
+
+## What NOT to Do
+
+- Do not rewrite the entire document
+- Do not add new sections or requirements the user didn't discuss
+- Do not over-engineer or add complexity
+- Do not create separate review files or add metadata sections

plugins/compound-engineering/skills/file-todos/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: file-todos
 description: This skill should be used when managing the file-based todo tracking system in the todos/ directory. It provides workflows for creating todos, managing status and dependencies, conducting triage, and integrating with slash commands and code review processes.
+disable-model-invocation: true
 ---
 
 # File-Based Todo Tracking Skill

plugins/compound-engineering/skills/git-worktree/scripts/worktree-manager.sh

@@ -91,14 +91,6 @@ create_worktree() {
   echo -e "${BLUE}Creating worktree: $branch_name${NC}"
   echo "  From: $from_branch"
   echo "  Path: $worktree_path"
-  echo ""
-  echo "Proceed? (y/n)"
-  read -r response
-
-  if [[ "$response" != "y" ]]; then
-    echo -e "${YELLOW}Cancelled${NC}"
-    return
-  fi
 
   # Update main branch
   echo -e "${BLUE}Updating $from_branch...${NC}"
@@ -134,7 +126,7 @@ list_worktrees() {
 
   local count=0
   for worktree_path in "$WORKTREE_DIR"/*; do
-    if [[ -d "$worktree_path" && -d "$worktree_path/.git" ]]; then
+    if [[ -d "$worktree_path" && -e "$worktree_path/.git" ]]; then
       count=$((count + 1))
       local worktree_name=$(basename "$worktree_path")
       local branch=$(git -C "$worktree_path" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
@@ -231,7 +223,7 @@ cleanup_worktrees() {
   local to_remove=()
 
   for worktree_path in "$WORKTREE_DIR"/*; do
-    if [[ -d "$worktree_path" && -d "$worktree_path/.git" ]]; then
+    if [[ -d "$worktree_path" && -e "$worktree_path/.git" ]]; then
       local worktree_name=$(basename "$worktree_path")
 
       # Skip if current worktree

plugins/compound-engineering/skills/resolve-pr-parallel/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: resolve_pr_parallel
+description: Resolve all PR comments using parallel processing. Use when addressing PR review feedback, resolving review threads, or batch-fixing PR comments.
+argument-hint: "[optional: PR number or current PR]"
+disable-model-invocation: true
+allowed-tools: Bash(gh *), Bash(git *), Read
+---
+
+# Resolve PR Comments in Parallel
+
+Resolve all unresolved PR review comments by spawning parallel agents for each thread.
+
+## Context Detection
+
+Claude Code automatically detects git context:
+- Current branch and associated PR
+- All PR comments and review threads
+- Works with any PR by specifying the number
+
+## Workflow
+
+### 1. Analyze
+
+Fetch unresolved review threads using the GraphQL script:
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/skills/resolve-pr-parallel/scripts/get-pr-comments PR_NUMBER
+```
+
+This returns only **unresolved, non-outdated** threads with file paths, line numbers, and comment bodies.
+
+If the script fails, fall back to:
+```bash
+gh pr view PR_NUMBER --json reviews,comments
+gh api repos/{owner}/{repo}/pulls/PR_NUMBER/comments
+```
+
+### 2. Plan
+
+Create a TodoWrite list of all unresolved items grouped by type:
+- Code changes requested
+- Questions to answer
+- Style/convention fixes
+- Test additions needed
+
+### 3. Implement (PARALLEL)
+
+Spawn a `pr-comment-resolver` agent for each unresolved item in parallel.
+
+If there are 3 comments, spawn 3 agents:
+
+1. Task pr-comment-resolver(comment1)
+2. Task pr-comment-resolver(comment2)
+3. Task pr-comment-resolver(comment3)
+
+Always run all in parallel subagents/Tasks for each Todo item.
+
+### 4. Commit & Resolve
+
+- Commit changes with a clear message referencing the PR feedback
+- Resolve each thread programmatically:
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/skills/resolve-pr-parallel/scripts/resolve-pr-thread THREAD_ID
+```
+
+- Push to remote
+
+### 5. Verify
+
+Re-fetch comments to confirm all threads are resolved:
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/skills/resolve-pr-parallel/scripts/get-pr-comments PR_NUMBER
+```
+
+Should return an empty array `[]`. If threads remain, repeat from step 1.
+
+## Scripts
+
+- [scripts/get-pr-comments](scripts/get-pr-comments) - GraphQL query for unresolved review threads
+- [scripts/resolve-pr-thread](scripts/resolve-pr-thread) - GraphQL mutation to resolve a thread by ID
+
+## Success Criteria
+
+- All unresolved review threads addressed
+- Changes committed and pushed
+- Threads resolved via GraphQL (marked as resolved on GitHub)
+- Empty result from get-pr-comments on verify

plugins/compound-engineering/skills/resolve-pr-parallel/scripts/get-pr-comments

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+
+set -e
+
+if [ $# -lt 1 ]; then
+    echo "Usage: get-pr-comments PR_NUMBER [OWNER/REPO]"
+    echo "Example: get-pr-comments 123"
+    echo "Example: get-pr-comments 123 EveryInc/cora"
+    exit 1
+fi
+
+PR_NUMBER=$1
+
+if [ -n "$2" ]; then
+    OWNER=$(echo "$2" | cut -d/ -f1)
+    REPO=$(echo "$2" | cut -d/ -f2)
+else
+    OWNER=$(gh repo view --json owner -q .owner.login 2>/dev/null)
+    REPO=$(gh repo view --json name -q .name 2>/dev/null)
+fi
+
+if [ -z "$OWNER" ] || [ -z "$REPO" ]; then
+    echo "Error: Could not detect repository. Pass OWNER/REPO as second argument."
+    exit 1
+fi
+
+gh api graphql -f owner="$OWNER" -f repo="$REPO" -F pr="$PR_NUMBER" -f query='
+query FetchUnresolvedComments($owner: String!, $repo: String!, $pr: Int!) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $pr) {
+      title
+      url
+      reviewThreads(first: 100) {
+        totalCount
+        edges {
+          node {
+            id
+            isResolved
+            isOutdated
+            isCollapsed
+            path
+            line
+            startLine
+            diffSide
+            comments(first: 100) {
+              totalCount
+              nodes {
+                id
+                author {
+                  login
+                }
+                body
+                createdAt
+                updatedAt
+                url
+                outdated
+              }
+            }
+          }
+        }
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+      }
+    }
+  }
+}' | jq '.data.repository.pullRequest.reviewThreads.edges | map(select(.node.isResolved == false and .node.isOutdated == false))'

plugins/compound-engineering/skills/resolve-pr-parallel/scripts/resolve-pr-thread

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+
+set -e
+
+if [ $# -eq 0 ]; then
+    echo "Usage: resolve-pr-thread THREAD_ID"
+    echo "Example: resolve-pr-thread PRRT_kwDOABC123"
+    exit 1
+fi
+
+THREAD_ID=$1
+
+gh api graphql -f threadId="$THREAD_ID" -f query='
+mutation ResolveReviewThread($threadId: ID!) {
+  resolveReviewThread(input: {threadId: $threadId}) {
+    thread {
+      id
+      isResolved
+      path
+      line
+    }
+  }
+}'

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.
+```

plugins/compound-engineering/skills/skill-creator/SKILL.md

@@ -2,6 +2,7 @@
 name: skill-creator
 description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
 license: Complete terms in LICENSE.txt
+disable-model-invocation: true
 ---
 
 # Skill Creator

src/commands/convert.ts

@@ -5,6 +5,7 @@ import { loadClaudePlugin } from "../parsers/claude"
 import { targets } from "../targets"
 import type { PermissionMode } from "../converters/claude-to-opencode"
 import { ensureCodexAgentsFile } from "../utils/codex-agents"
+import { expandHome, resolveTargetHome } from "../utils/resolve-home"
 
 const permissionModes: PermissionMode[] = ["none", "broad", "from-commands"]
 
@@ -22,7 +23,7 @@ export default defineCommand({
     to: {
       type: "string",
       default: "opencode",
-      description: "Target format (opencode | codex)",
+      description: "Target format (opencode | codex | droid | cursor | pi | gemini)",
     },
     output: {
       type: "string",
@@ -34,6 +35,11 @@ export default defineCommand({
       alias: "codex-home",
       description: "Write Codex output to this .codex root (ex: ~/.codex)",
     },
+    piHome: {
+      type: "string",
+      alias: "pi-home",
+      description: "Write Pi output to this Pi root (ex: ~/.pi/agent or ./.pi)",
+    },
     also: {
       type: "string",
       description: "Comma-separated extra targets to generate (ex: codex)",
@@ -72,7 +78,8 @@ export default defineCommand({
 
     const plugin = await loadClaudePlugin(String(args.source))
     const outputRoot = resolveOutputRoot(args.output)
-    const codexHome = resolveCodexRoot(args.codexHome)
+    const codexHome = resolveTargetHome(args.codexHome, path.join(os.homedir(), ".codex"))
+    const piHome = resolveTargetHome(args.piHome, path.join(os.homedir(), ".pi", "agent"))
 
     const options = {
       agentMode: String(args.agentMode) === "primary" ? "primary" : "subagent",
@@ -80,7 +87,7 @@ export default defineCommand({
       permissions: permissions as PermissionMode,
     }
 
-    const primaryOutputRoot = targetName === "codex" && codexHome ? codexHome : outputRoot
+    const primaryOutputRoot = resolveTargetOutputRoot(targetName, outputRoot, codexHome, piHome)
     const bundle = target.convert(plugin, options)
     if (!bundle) {
       throw new Error(`Target ${targetName} did not return a bundle.`)
@@ -106,9 +113,7 @@ export default defineCommand({
         console.warn(`Skipping ${extra}: no output returned.`)
         continue
       }
-      const extraRoot = extra === "codex" && codexHome
-        ? codexHome
-        : path.join(outputRoot, extra)
+      const extraRoot = resolveTargetOutputRoot(extra, path.join(outputRoot, extra), codexHome, piHome)
       await handler.write(extraRoot, extraBundle)
       console.log(`Converted ${plugin.manifest.name} to ${extra} at ${extraRoot}`)
     }
@@ -127,26 +132,6 @@ function parseExtraTargets(value: unknown): string[] {
     .filter(Boolean)
 }
 
-function resolveCodexHome(value: unknown): string | null {
-  if (!value) return null
-  const raw = String(value).trim()
-  if (!raw) return null
-  const expanded = expandHome(raw)
-  return path.resolve(expanded)
-}
-
-function resolveCodexRoot(value: unknown): string {
-  return resolveCodexHome(value) ?? path.join(os.homedir(), ".codex")
-}
-
-function expandHome(value: string): string {
-  if (value === "~") return os.homedir()
-  if (value.startsWith(`~${path.sep}`)) {
-    return path.join(os.homedir(), value.slice(2))
-  }
-  return value
-}
-
 function resolveOutputRoot(value: unknown): string {
   if (value && String(value).trim()) {
     const expanded = expandHome(String(value).trim())
@@ -154,3 +139,12 @@ function resolveOutputRoot(value: unknown): string {
   }
   return process.cwd()
 }
+
+function resolveTargetOutputRoot(targetName: string, outputRoot: string, codexHome: string, piHome: string): string {
+  if (targetName === "codex") return codexHome
+  if (targetName === "pi") return piHome
+  if (targetName === "droid") return path.join(os.homedir(), ".factory")
+  if (targetName === "cursor") return path.join(outputRoot, ".cursor")
+  if (targetName === "gemini") return path.join(outputRoot, ".gemini")
+  return outputRoot
+}

src/commands/install.ts

@@ -7,6 +7,7 @@ import { targets } from "../targets"
 import { pathExists } from "../utils/files"
 import type { PermissionMode } from "../converters/claude-to-opencode"
 import { ensureCodexAgentsFile } from "../utils/codex-agents"
+import { expandHome, resolveTargetHome } from "../utils/resolve-home"
 
 const permissionModes: PermissionMode[] = ["none", "broad", "from-commands"]
 
@@ -24,7 +25,7 @@ export default defineCommand({
     to: {
       type: "string",
       default: "opencode",
-      description: "Target format (opencode | codex)",
+      description: "Target format (opencode | codex | droid | cursor | pi | gemini)",
     },
     output: {
       type: "string",
@@ -36,6 +37,11 @@ export default defineCommand({
       alias: "codex-home",
       description: "Write Codex output to this .codex root (ex: ~/.codex)",
     },
+    piHome: {
+      type: "string",
+      alias: "pi-home",
+      description: "Write Pi output to this Pi root (ex: ~/.pi/agent or ./.pi)",
+    },
     also: {
       type: "string",
       description: "Comma-separated extra targets to generate (ex: codex)",
@@ -76,7 +82,8 @@ export default defineCommand({
     try {
       const plugin = await loadClaudePlugin(resolvedPlugin.path)
       const outputRoot = resolveOutputRoot(args.output)
-      const codexHome = resolveCodexRoot(args.codexHome)
+      const codexHome = resolveTargetHome(args.codexHome, path.join(os.homedir(), ".codex"))
+      const piHome = resolveTargetHome(args.piHome, path.join(os.homedir(), ".pi", "agent"))
 
       const options = {
         agentMode: String(args.agentMode) === "primary" ? "primary" : "subagent",
@@ -88,7 +95,8 @@ export default defineCommand({
       if (!bundle) {
         throw new Error(`Target ${targetName} did not return a bundle.`)
       }
-      const primaryOutputRoot = targetName === "codex" && codexHome ? codexHome : outputRoot
+      const hasExplicitOutput = Boolean(args.output && String(args.output).trim())
+      const primaryOutputRoot = resolveTargetOutputRoot(targetName, outputRoot, codexHome, piHome, hasExplicitOutput)
       await target.write(primaryOutputRoot, bundle)
       console.log(`Installed ${plugin.manifest.name} to ${primaryOutputRoot}`)
 
@@ -109,9 +117,7 @@ export default defineCommand({
           console.warn(`Skipping ${extra}: no output returned.`)
           continue
         }
-        const extraRoot = extra === "codex" && codexHome
-          ? codexHome
-          : path.join(outputRoot, extra)
+        const extraRoot = resolveTargetOutputRoot(extra, path.join(outputRoot, extra), codexHome, piHome, hasExplicitOutput)
         await handler.write(extraRoot, extraBundle)
         console.log(`Installed ${plugin.manifest.name} to ${extraRoot}`)
       }
@@ -133,12 +139,15 @@ type ResolvedPluginPath = {
 }
 
 async function resolvePluginPath(input: string): Promise<ResolvedPluginPath> {
-  const directPath = path.resolve(input)
-  if (await pathExists(directPath)) return { path: directPath }
-
-  const pluginsPath = path.join(process.cwd(), "plugins", input)
-  if (await pathExists(pluginsPath)) return { path: pluginsPath }
+  // Only treat as a local path if it explicitly looks like one
+  if (input.startsWith(".") || input.startsWith("/") || input.startsWith("~")) {
+    const expanded = expandHome(input)
+    const directPath = path.resolve(expanded)
+    if (await pathExists(directPath)) return { path: directPath }
+    throw new Error(`Local plugin path not found: ${directPath}`)
+  }
 
+  // Otherwise, always fetch the latest from GitHub
   return await resolveGitHubPluginPath(input)
 }
 
@@ -150,26 +159,6 @@ function parseExtraTargets(value: unknown): string[] {
     .filter(Boolean)
 }
 
-function resolveCodexHome(value: unknown): string | null {
-  if (!value) return null
-  const raw = String(value).trim()
-  if (!raw) return null
-  const expanded = expandHome(raw)
-  return path.resolve(expanded)
-}
-
-function resolveCodexRoot(value: unknown): string {
-  return resolveCodexHome(value) ?? path.join(os.homedir(), ".codex")
-}
-
-function expandHome(value: string): string {
-  if (value === "~") return os.homedir()
-  if (value.startsWith(`~${path.sep}`)) {
-    return path.join(os.homedir(), value.slice(2))
-  }
-  return value
-}
-
 function resolveOutputRoot(value: unknown): string {
   if (value && String(value).trim()) {
     const expanded = expandHome(String(value).trim())
@@ -180,6 +169,27 @@ function resolveOutputRoot(value: unknown): string {
   return path.join(os.homedir(), ".config", "opencode")
 }
 
+function resolveTargetOutputRoot(
+  targetName: string,
+  outputRoot: string,
+  codexHome: string,
+  piHome: string,
+  hasExplicitOutput: boolean,
+): string {
+  if (targetName === "codex") return codexHome
+  if (targetName === "pi") return piHome
+  if (targetName === "droid") return path.join(os.homedir(), ".factory")
+  if (targetName === "cursor") {
+    const base = hasExplicitOutput ? outputRoot : process.cwd()
+    return path.join(base, ".cursor")
+  }
+  if (targetName === "gemini") {
+    const base = hasExplicitOutput ? outputRoot : process.cwd()
+    return path.join(base, ".gemini")
+  }
+  return outputRoot
+}
+
 async function resolveGitHubPluginPath(pluginName: string): Promise<ResolvedPluginPath> {
   const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compound-plugin-"))
   const source = resolveGitHubSource()

src/commands/sync.ts

@@ -0,0 +1,107 @@
+import { defineCommand } from "citty"
+import os from "os"
+import path from "path"
+import { loadClaudeHome } from "../parsers/claude-home"
+import { syncToOpenCode } from "../sync/opencode"
+import { syncToCodex } from "../sync/codex"
+import { syncToPi } from "../sync/pi"
+import { syncToDroid } from "../sync/droid"
+import { syncToCursor } from "../sync/cursor"
+import { expandHome } from "../utils/resolve-home"
+
+const validTargets = ["opencode", "codex", "pi", "droid", "cursor"] as const
+type SyncTarget = (typeof validTargets)[number]
+
+function isValidTarget(value: string): value is SyncTarget {
+  return (validTargets as readonly string[]).includes(value)
+}
+
+/** Check if any MCP servers have env vars that might contain secrets */
+function hasPotentialSecrets(mcpServers: Record<string, unknown>): boolean {
+  const sensitivePatterns = /key|token|secret|password|credential|api_key/i
+  for (const server of Object.values(mcpServers)) {
+    const env = (server as { env?: Record<string, string> }).env
+    if (env) {
+      for (const key of Object.keys(env)) {
+        if (sensitivePatterns.test(key)) return true
+      }
+    }
+  }
+  return false
+}
+
+function resolveOutputRoot(target: SyncTarget): string {
+  switch (target) {
+    case "opencode":
+      return path.join(os.homedir(), ".config", "opencode")
+    case "codex":
+      return path.join(os.homedir(), ".codex")
+    case "pi":
+      return path.join(os.homedir(), ".pi", "agent")
+    case "droid":
+      return path.join(os.homedir(), ".factory")
+    case "cursor":
+      return path.join(process.cwd(), ".cursor")
+  }
+}
+
+export default defineCommand({
+  meta: {
+    name: "sync",
+    description: "Sync Claude Code config (~/.claude/) to OpenCode, Codex, Pi, Droid, or Cursor",
+  },
+  args: {
+    target: {
+      type: "string",
+      required: true,
+      description: "Target: opencode | codex | pi | droid | cursor",
+    },
+    claudeHome: {
+      type: "string",
+      alias: "claude-home",
+      description: "Path to Claude home (default: ~/.claude)",
+    },
+  },
+  async run({ args }) {
+    if (!isValidTarget(args.target)) {
+      throw new Error(`Unknown target: ${args.target}. Use one of: ${validTargets.join(", ")}`)
+    }
+
+    const claudeHome = expandHome(args.claudeHome ?? path.join(os.homedir(), ".claude"))
+    const config = await loadClaudeHome(claudeHome)
+
+    // Warn about potential secrets in MCP env vars
+    if (hasPotentialSecrets(config.mcpServers)) {
+      console.warn(
+        "⚠️  Warning: MCP servers contain env vars that may include secrets (API keys, tokens).\n" +
+        "   These will be copied to the target config. Review before sharing the config file.",
+      )
+    }
+
+    console.log(
+      `Syncing ${config.skills.length} skills, ${Object.keys(config.mcpServers).length} MCP servers...`,
+    )
+
+    const outputRoot = resolveOutputRoot(args.target)
+
+    switch (args.target) {
+      case "opencode":
+        await syncToOpenCode(config, outputRoot)
+        break
+      case "codex":
+        await syncToCodex(config, outputRoot)
+        break
+      case "pi":
+        await syncToPi(config, outputRoot)
+        break
+      case "droid":
+        await syncToDroid(config, outputRoot)
+        break
+      case "cursor":
+        await syncToCursor(config, outputRoot)
+        break
+    }
+
+    console.log(`✓ Synced to ${args.target}: ${outputRoot}`)
+  },
+})

src/converters/claude-to-codex.ts

@@ -19,7 +19,8 @@ export function convertClaudeToCodex(
 
   const usedSkillNames = new Set<string>(skillDirs.map((skill) => normalizeName(skill.name)))
   const commandSkills: CodexGeneratedSkill[] = []
-  const prompts = plugin.commands.map((command) => {
+  const invocableCommands = plugin.commands.filter((command) => !command.disableModelInvocation)
+  const prompts = invocableCommands.map((command) => {
     const promptName = uniqueName(normalizeName(command.name), promptNames)
     const commandSkill = convertCommandSkill(command, usedSkillNames)
     commandSkills.push(commandSkill)
@@ -45,7 +46,7 @@ function convertAgent(agent: ClaudeAgent, usedNames: Set<string>): CodexGenerate
   )
   const frontmatter: Record<string, unknown> = { 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()
@@ -120,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) => {

src/converters/claude-to-cursor.ts

@@ -0,0 +1,166 @@
+import { formatFrontmatter } from "../utils/frontmatter"
+import type { ClaudeAgent, ClaudeCommand, ClaudeMcpServer, ClaudePlugin } from "../types/claude"
+import type { CursorBundle, CursorCommand, CursorMcpServer, CursorRule } from "../types/cursor"
+import type { ClaudeToOpenCodeOptions } from "./claude-to-opencode"
+
+export type ClaudeToCursorOptions = ClaudeToOpenCodeOptions
+
+export function convertClaudeToCursor(
+  plugin: ClaudePlugin,
+  _options: ClaudeToCursorOptions,
+): CursorBundle {
+  const usedRuleNames = new Set<string>()
+  const usedCommandNames = new Set<string>()
+
+  const rules = plugin.agents.map((agent) => convertAgentToRule(agent, usedRuleNames))
+  const commands = plugin.commands.map((command) => convertCommand(command, usedCommandNames))
+  const skillDirs = plugin.skills.map((skill) => ({
+    name: skill.name,
+    sourceDir: skill.sourceDir,
+  }))
+
+  const mcpServers = convertMcpServers(plugin.mcpServers)
+
+  if (plugin.hooks && Object.keys(plugin.hooks.hooks).length > 0) {
+    console.warn("Warning: Cursor does not support hooks. Hooks were skipped during conversion.")
+  }
+
+  return { rules, commands, skillDirs, mcpServers }
+}
+
+function convertAgentToRule(agent: ClaudeAgent, usedNames: Set<string>): CursorRule {
+  const name = uniqueName(normalizeName(agent.name), usedNames)
+  const description = agent.description ?? `Converted from Claude agent ${agent.name}`
+
+  const frontmatter: Record<string, unknown> = {
+    description,
+    alwaysApply: false,
+  }
+
+  let body = transformContentForCursor(agent.body.trim())
+  if (agent.capabilities && agent.capabilities.length > 0) {
+    const capabilities = agent.capabilities.map((c) => `- ${c}`).join("\n")
+    body = `## Capabilities\n${capabilities}\n\n${body}`.trim()
+  }
+  if (body.length === 0) {
+    body = `Instructions converted from the ${agent.name} agent.`
+  }
+
+  const content = formatFrontmatter(frontmatter, body)
+  return { name, content }
+}
+
+function convertCommand(command: ClaudeCommand, usedNames: Set<string>): CursorCommand {
+  const name = uniqueName(flattenCommandName(command.name), usedNames)
+
+  const sections: string[] = []
+
+  if (command.description) {
+    sections.push(`<!-- ${command.description} -->`)
+  }
+
+  if (command.argumentHint) {
+    sections.push(`## Arguments\n${command.argumentHint}`)
+  }
+
+  const transformedBody = transformContentForCursor(command.body.trim())
+  sections.push(transformedBody)
+
+  const content = sections.filter(Boolean).join("\n\n").trim()
+  return { name, content }
+}
+
+/**
+ * Transform Claude Code content to Cursor-compatible content.
+ *
+ * 1. Task agent calls: Task agent-name(args) -> Use the agent-name skill to: args
+ * 2. Slash commands: /workflows:plan -> /plan (flatten namespace)
+ * 3. Path rewriting: .claude/ -> .cursor/
+ * 4. Agent references: @agent-name -> the agent-name rule
+ */
+export function transformContentForCursor(body: string): string {
+  let result = body
+
+  // 1. Transform Task agent calls
+  const taskPattern = /^(\s*-?\s*)Task\s+([a-z][a-z0-9-]*)\(([^)]+)\)/gm
+  result = result.replace(taskPattern, (_match, prefix: string, agentName: string, args: string) => {
+    const skillName = normalizeName(agentName)
+    return `${prefix}Use the ${skillName} skill to: ${args.trim()}`
+  })
+
+  // 2. Transform slash command references (flatten namespaces)
+  const slashCommandPattern = /(?<![:\w])\/([a-z][a-z0-9_:-]*?)(?=[\s,."')\]}`]|$)/gi
+  result = result.replace(slashCommandPattern, (match, commandName: string) => {
+    if (commandName.includes("/")) return match
+    if (["dev", "tmp", "etc", "usr", "var", "bin", "home"].includes(commandName)) return match
+    const flattened = flattenCommandName(commandName)
+    return `/${flattened}`
+  })
+
+  // 3. Rewrite .claude/ paths to .cursor/
+  result = result
+    .replace(/~\/\.claude\//g, "~/.cursor/")
+    .replace(/\.claude\//g, ".cursor/")
+
+  // 4. Transform @agent-name references
+  const agentRefPattern = /@([a-z][a-z0-9-]*-(?:agent|reviewer|researcher|analyst|specialist|oracle|sentinel|guardian|strategist))/gi
+  result = result.replace(agentRefPattern, (_match, agentName: string) => {
+    return `the ${normalizeName(agentName)} rule`
+  })
+
+  return result
+}
+
+function convertMcpServers(
+  servers?: Record<string, ClaudeMcpServer>,
+): Record<string, CursorMcpServer> | undefined {
+  if (!servers || Object.keys(servers).length === 0) return undefined
+
+  const result: Record<string, CursorMcpServer> = {}
+  for (const [name, server] of Object.entries(servers)) {
+    const entry: CursorMcpServer = {}
+    if (server.command) {
+      entry.command = server.command
+      if (server.args && server.args.length > 0) entry.args = server.args
+      if (server.env && Object.keys(server.env).length > 0) entry.env = server.env
+    } else if (server.url) {
+      entry.url = server.url
+      if (server.headers && Object.keys(server.headers).length > 0) entry.headers = server.headers
+    }
+    result[name] = entry
+  }
+  return result
+}
+
+function flattenCommandName(name: string): string {
+  const colonIndex = name.lastIndexOf(":")
+  const base = colonIndex >= 0 ? name.slice(colonIndex + 1) : name
+  return normalizeName(base)
+}
+
+function normalizeName(value: string): string {
+  const trimmed = value.trim()
+  if (!trimmed) return "item"
+  const normalized = trimmed
+    .toLowerCase()
+    .replace(/[\\/]+/g, "-")
+    .replace(/[:\s]+/g, "-")
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "")
+  return normalized || "item"
+}
+
+function uniqueName(base: string, used: Set<string>): string {
+  if (!used.has(base)) {
+    used.add(base)
+    return base
+  }
+  let index = 2
+  while (used.has(`${base}-${index}`)) {
+    index += 1
+  }
+  const name = `${base}-${index}`
+  used.add(name)
+  return name
+}

src/converters/claude-to-droid.ts

@@ -0,0 +1,174 @@
+import { formatFrontmatter } from "../utils/frontmatter"
+import type { ClaudeAgent, ClaudeCommand, ClaudePlugin } from "../types/claude"
+import type { DroidBundle, DroidCommandFile, DroidAgentFile } from "../types/droid"
+import type { ClaudeToOpenCodeOptions } from "./claude-to-opencode"
+
+export type ClaudeToDroidOptions = ClaudeToOpenCodeOptions
+
+const CLAUDE_TO_DROID_TOOLS: Record<string, string> = {
+  read: "Read",
+  write: "Create",
+  edit: "Edit",
+  multiedit: "Edit",
+  bash: "Execute",
+  grep: "Grep",
+  glob: "Glob",
+  list: "LS",
+  ls: "LS",
+  webfetch: "FetchUrl",
+  websearch: "WebSearch",
+  task: "Task",
+  todowrite: "TodoWrite",
+  todoread: "TodoWrite",
+  question: "AskUser",
+}
+
+const VALID_DROID_TOOLS = new Set([
+  "Read",
+  "LS",
+  "Grep",
+  "Glob",
+  "Create",
+  "Edit",
+  "ApplyPatch",
+  "Execute",
+  "WebSearch",
+  "FetchUrl",
+  "TodoWrite",
+  "Task",
+  "AskUser",
+])
+
+export function convertClaudeToDroid(
+  plugin: ClaudePlugin,
+  _options: ClaudeToDroidOptions,
+): DroidBundle {
+  const commands = plugin.commands.map((command) => convertCommand(command))
+  const droids = plugin.agents.map((agent) => convertAgent(agent))
+  const skillDirs = plugin.skills.map((skill) => ({
+    name: skill.name,
+    sourceDir: skill.sourceDir,
+  }))
+
+  return { commands, droids, skillDirs }
+}
+
+function convertCommand(command: ClaudeCommand): DroidCommandFile {
+  const name = flattenCommandName(command.name)
+  const frontmatter: Record<string, unknown> = {
+    description: command.description,
+  }
+  if (command.argumentHint) {
+    frontmatter["argument-hint"] = command.argumentHint
+  }
+  if (command.disableModelInvocation) {
+    frontmatter["disable-model-invocation"] = true
+  }
+
+  const body = transformContentForDroid(command.body.trim())
+  const content = formatFrontmatter(frontmatter, body)
+  return { name, content }
+}
+
+function convertAgent(agent: ClaudeAgent): DroidAgentFile {
+  const name = normalizeName(agent.name)
+  const frontmatter: Record<string, unknown> = {
+    name,
+    description: agent.description,
+    model: agent.model && agent.model !== "inherit" ? agent.model : "inherit",
+  }
+
+  const tools = mapAgentTools(agent)
+  if (tools) {
+    frontmatter.tools = tools
+  }
+
+  let body = agent.body.trim()
+  if (agent.capabilities && agent.capabilities.length > 0) {
+    const capabilities = agent.capabilities.map((c) => `- ${c}`).join("\n")
+    body = `## Capabilities\n${capabilities}\n\n${body}`.trim()
+  }
+  if (body.length === 0) {
+    body = `Instructions converted from the ${agent.name} agent.`
+  }
+
+  body = transformContentForDroid(body)
+
+  const content = formatFrontmatter(frontmatter, body)
+  return { name, content }
+}
+
+function mapAgentTools(agent: ClaudeAgent): string[] | undefined {
+  const bodyLower = `${agent.name} ${agent.description ?? ""} ${agent.body}`.toLowerCase()
+
+  const mentionedTools = new Set<string>()
+  for (const [claudeTool, droidTool] of Object.entries(CLAUDE_TO_DROID_TOOLS)) {
+    if (bodyLower.includes(claudeTool)) {
+      mentionedTools.add(droidTool)
+    }
+  }
+
+  if (mentionedTools.size === 0) return undefined
+  return [...mentionedTools].filter((t) => VALID_DROID_TOOLS.has(t)).sort()
+}
+
+/**
+ * Transform Claude Code content to Factory Droid-compatible content.
+ *
+ * 1. Slash commands: /workflows:plan → /plan, /command-name stays as-is
+ * 2. Task agent calls: Task agent-name(args) → Task agent-name: args
+ * 3. Agent references: @agent-name → the agent-name droid
+ */
+function transformContentForDroid(body: string): string {
+  let result = body
+
+  // 1. Transform Task agent calls
+  // Match: Task repo-research-analyst(feature_description)
+  const taskPattern = /^(\s*-?\s*)Task\s+([a-z][a-z0-9-]*)\(([^)]+)\)/gm
+  result = result.replace(taskPattern, (_match, prefix: string, agentName: string, args: string) => {
+    const name = normalizeName(agentName)
+    return `${prefix}Task ${name}: ${args.trim()}`
+  })
+
+  // 2. Transform slash command references
+  // /workflows:plan → /plan, /command-name stays as-is
+  const slashCommandPattern = /(?<![:\w])\/([a-z][a-z0-9_:-]*?)(?=[\s,."')\]}`]|$)/gi
+  result = result.replace(slashCommandPattern, (match, commandName: string) => {
+    if (commandName.includes('/')) return match
+    if (['dev', 'tmp', 'etc', 'usr', 'var', 'bin', 'home'].includes(commandName)) return match
+    const flattened = flattenCommandName(commandName)
+    return `/${flattened}`
+  })
+
+  // 3. Transform @agent-name references to droid references
+  const agentRefPattern = /@agent-([a-z][a-z0-9-]*)/gi
+  result = result.replace(agentRefPattern, (_match, agentName: string) => {
+    return `the ${normalizeName(agentName)} droid`
+  })
+
+  return result
+}
+
+/**
+ * Flatten a command name by stripping the namespace prefix.
+ * "workflows:plan" → "plan"
+ * "plan_review" → "plan_review"
+ */
+function flattenCommandName(name: string): string {
+  const colonIndex = name.lastIndexOf(":")
+  const base = colonIndex >= 0 ? name.slice(colonIndex + 1) : name
+  return normalizeName(base)
+}
+
+function normalizeName(value: string): string {
+  const trimmed = value.trim()
+  if (!trimmed) return "item"
+  const normalized = trimmed
+    .toLowerCase()
+    .replace(/[\\/]+/g, "-")
+    .replace(/[:\s]+/g, "-")
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "")
+  return normalized || "item"
+}

src/converters/claude-to-gemini.ts

@@ -0,0 +1,193 @@
+import { formatFrontmatter } from "../utils/frontmatter"
+import type { ClaudeAgent, ClaudeCommand, ClaudeMcpServer, ClaudePlugin } from "../types/claude"
+import type { GeminiBundle, GeminiCommand, GeminiMcpServer, GeminiSkill } from "../types/gemini"
+import type { ClaudeToOpenCodeOptions } from "./claude-to-opencode"
+
+export type ClaudeToGeminiOptions = ClaudeToOpenCodeOptions
+
+const GEMINI_DESCRIPTION_MAX_LENGTH = 1024
+
+export function convertClaudeToGemini(
+  plugin: ClaudePlugin,
+  _options: ClaudeToGeminiOptions,
+): GeminiBundle {
+  const usedSkillNames = new Set<string>()
+  const usedCommandNames = new Set<string>()
+
+  const skillDirs = plugin.skills.map((skill) => ({
+    name: skill.name,
+    sourceDir: skill.sourceDir,
+  }))
+
+  // Reserve skill names from pass-through skills
+  for (const skill of skillDirs) {
+    usedSkillNames.add(normalizeName(skill.name))
+  }
+
+  const generatedSkills = plugin.agents.map((agent) => convertAgentToSkill(agent, usedSkillNames))
+
+  const commands = plugin.commands.map((command) => convertCommand(command, usedCommandNames))
+
+  const mcpServers = convertMcpServers(plugin.mcpServers)
+
+  if (plugin.hooks && Object.keys(plugin.hooks.hooks).length > 0) {
+    console.warn("Warning: Gemini CLI hooks use a different format (BeforeTool/AfterTool with matchers). Hooks were skipped during conversion.")
+  }
+
+  return { generatedSkills, skillDirs, commands, mcpServers }
+}
+
+function convertAgentToSkill(agent: ClaudeAgent, usedNames: Set<string>): GeminiSkill {
+  const name = uniqueName(normalizeName(agent.name), usedNames)
+  const description = sanitizeDescription(
+    agent.description ?? `Use this skill for ${agent.name} tasks`,
+  )
+
+  const frontmatter: Record<string, unknown> = { name, description }
+
+  let body = transformContentForGemini(agent.body.trim())
+  if (agent.capabilities && agent.capabilities.length > 0) {
+    const capabilities = agent.capabilities.map((c) => `- ${c}`).join("\n")
+    body = `## Capabilities\n${capabilities}\n\n${body}`.trim()
+  }
+  if (body.length === 0) {
+    body = `Instructions converted from the ${agent.name} agent.`
+  }
+
+  const content = formatFrontmatter(frontmatter, body)
+  return { name, content }
+}
+
+function convertCommand(command: ClaudeCommand, usedNames: Set<string>): GeminiCommand {
+  // Preserve namespace structure: workflows:plan -> workflows/plan
+  const commandPath = resolveCommandPath(command.name)
+  const pathKey = commandPath.join("/")
+  uniqueName(pathKey, usedNames) // Track for dedup
+
+  const description = command.description ?? `Converted from Claude command ${command.name}`
+  const transformedBody = transformContentForGemini(command.body.trim())
+
+  let prompt = transformedBody
+  if (command.argumentHint) {
+    prompt += `\n\nUser request: {{args}}`
+  }
+
+  const content = toToml(description, prompt)
+  return { name: pathKey, content }
+}
+
+/**
+ * Transform Claude Code content to Gemini-compatible content.
+ *
+ * 1. Task agent calls: Task agent-name(args) -> Use the agent-name skill to: args
+ * 2. Path rewriting: .claude/ -> .gemini/, ~/.claude/ -> ~/.gemini/
+ * 3. Agent references: @agent-name -> the agent-name skill
+ */
+export function transformContentForGemini(body: string): string {
+  let result = body
+
+  // 1. Transform Task agent calls
+  const taskPattern = /^(\s*-?\s*)Task\s+([a-z][a-z0-9-]*)\(([^)]+)\)/gm
+  result = result.replace(taskPattern, (_match, prefix: string, agentName: string, args: string) => {
+    const skillName = normalizeName(agentName)
+    return `${prefix}Use the ${skillName} skill to: ${args.trim()}`
+  })
+
+  // 2. Rewrite .claude/ paths to .gemini/
+  result = result
+    .replace(/~\/\.claude\//g, "~/.gemini/")
+    .replace(/\.claude\//g, ".gemini/")
+
+  // 3. Transform @agent-name references
+  const agentRefPattern = /@([a-z][a-z0-9-]*-(?:agent|reviewer|researcher|analyst|specialist|oracle|sentinel|guardian|strategist))/gi
+  result = result.replace(agentRefPattern, (_match, agentName: string) => {
+    return `the ${normalizeName(agentName)} skill`
+  })
+
+  return result
+}
+
+function convertMcpServers(
+  servers?: Record<string, ClaudeMcpServer>,
+): Record<string, GeminiMcpServer> | undefined {
+  if (!servers || Object.keys(servers).length === 0) return undefined
+
+  const result: Record<string, GeminiMcpServer> = {}
+  for (const [name, server] of Object.entries(servers)) {
+    const entry: GeminiMcpServer = {}
+    if (server.command) {
+      entry.command = server.command
+      if (server.args && server.args.length > 0) entry.args = server.args
+      if (server.env && Object.keys(server.env).length > 0) entry.env = server.env
+    } else if (server.url) {
+      entry.url = server.url
+      if (server.headers && Object.keys(server.headers).length > 0) entry.headers = server.headers
+    }
+    result[name] = entry
+  }
+  return result
+}
+
+/**
+ * Resolve command name to path segments.
+ * workflows:plan -> ["workflows", "plan"]
+ * plan -> ["plan"]
+ */
+function resolveCommandPath(name: string): string[] {
+  return name.split(":").map((segment) => normalizeName(segment))
+}
+
+/**
+ * Serialize to TOML command format.
+ * Uses multi-line strings (""") for prompt field.
+ */
+export function toToml(description: string, prompt: string): string {
+  const lines: string[] = []
+  lines.push(`description = ${formatTomlString(description)}`)
+
+  // Use multi-line string for prompt
+  const escapedPrompt = prompt.replace(/\\/g, "\\\\").replace(/"""/g, '\\"\\"\\"')
+  lines.push(`prompt = """`)
+  lines.push(escapedPrompt)
+  lines.push(`"""`)
+
+  return lines.join("\n")
+}
+
+function formatTomlString(value: string): string {
+  return JSON.stringify(value)
+}
+
+function normalizeName(value: string): string {
+  const trimmed = value.trim()
+  if (!trimmed) return "item"
+  const normalized = trimmed
+    .toLowerCase()
+    .replace(/[\\/]+/g, "-")
+    .replace(/[:\s]+/g, "-")
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "")
+  return normalized || "item"
+}
+
+function sanitizeDescription(value: string, maxLength = GEMINI_DESCRIPTION_MAX_LENGTH): string {
+  const normalized = value.replace(/\s+/g, " ").trim()
+  if (normalized.length <= maxLength) return normalized
+  const ellipsis = "..."
+  return normalized.slice(0, Math.max(0, maxLength - ellipsis.length)).trimEnd() + ellipsis
+}
+
+function uniqueName(base: string, used: Set<string>): string {
+  if (!used.has(base)) {
+    used.add(base)
+    return base
+  }
+  let index = 2
+  while (used.has(`${base}-${index}`)) {
+    index += 1
+  }
+  const name = `${base}-${index}`
+  used.add(name)
+  return name
+}

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,
@@ -114,9 +114,10 @@ function convertAgent(agent: ClaudeAgent, options: ClaudeToOpenCodeOptions) {
 function convertCommands(commands: ClaudeCommand[]): Record<string, OpenCodeCommandConfig> {
   const result: Record<string, OpenCodeCommandConfig> = {}
   for (const command of commands) {
+    if (command.disableModelInvocation) continue
     const entry: OpenCodeCommandConfig = {
       description: command.description,
-      template: command.body,
+      template: rewriteClaudePaths(command.body),
     }
     if (command.model && command.model !== "inherit") {
       entry.model = normalizeModel(command.model)
@@ -209,9 +210,11 @@ function renderHookStatements(
 ): string[] {
   if (!matcher.hooks || matcher.hooks.length === 0) return []
   const tools = matcher.matcher
-    .split("|")
-    .map((tool) => tool.trim().toLowerCase())
-    .filter(Boolean)
+    ? matcher.matcher
+        .split("|")
+        .map((tool) => tool.trim().toLowerCase())
+        .filter(Boolean)
+    : []
 
   const useMatcher = useToolMatcher && tools.length > 0 && !tools.includes("*")
   const condition = useMatcher
@@ -232,17 +235,39 @@ function renderHookStatements(
       continue
     }
     if (hook.type === "prompt") {
-      statements.push(`// Prompt hook for ${matcher.matcher}: ${hook.prompt.replace(/\n/g, " ")}`)
+      statements.push(`// Prompt hook for ${matcher.matcher ?? "*"}: ${hook.prompt.replace(/\n/g, " ")}`)
       continue
     }
-    statements.push(`// Agent hook for ${matcher.matcher}: ${hook.agent}`)
+    statements.push(`// Agent hook for ${matcher.matcher ?? "*"}: ${hook.agent}`)
   }
 
   return statements
 }
 
+function rewriteClaudePaths(body: string): string {
+  return body
+    .replace(/~\/\.claude\//g, "~/.config/opencode/")
+    .replace(/\.claude\//g, ".opencode/")
+}
+
+// Bare Claude family aliases used in Claude Code (e.g. `model: haiku`).
+// Update these when new model generations are released.
+const CLAUDE_FAMILY_ALIASES: Record<string, string> = {
+  haiku: "claude-haiku-4-5",
+  sonnet: "claude-sonnet-4-5",
+  opus: "claude-opus-4-6",
+}
+
 function normalizeModel(model: string): string {
   if (model.includes("/")) return model
+  if (CLAUDE_FAMILY_ALIASES[model]) {
+    const resolved = `anthropic/${CLAUDE_FAMILY_ALIASES[model]}`
+    console.warn(
+      `Warning: bare model alias "${model}" mapped to "${resolved}". ` +
+        `Update CLAUDE_FAMILY_ALIASES if a newer version is available.`,
+    )
+    return resolved
+  }
   if (/^claude-/.test(model)) return `anthropic/${model}`
   if (/^(gpt-|o1-|o3-)/.test(model)) return `openai/${model}`
   if (/^gemini-/.test(model)) return `google/${model}`

src/converters/claude-to-pi.ts

@@ -0,0 +1,205 @@
+import { formatFrontmatter } from "../utils/frontmatter"
+import type { ClaudeAgent, ClaudeCommand, ClaudeMcpServer, ClaudePlugin } from "../types/claude"
+import type {
+  PiBundle,
+  PiGeneratedSkill,
+  PiMcporterConfig,
+  PiMcporterServer,
+} from "../types/pi"
+import type { ClaudeToOpenCodeOptions } from "./claude-to-opencode"
+import { PI_COMPAT_EXTENSION_SOURCE } from "../templates/pi/compat-extension"
+
+export type ClaudeToPiOptions = ClaudeToOpenCodeOptions
+
+const PI_DESCRIPTION_MAX_LENGTH = 1024
+
+export function convertClaudeToPi(
+  plugin: ClaudePlugin,
+  _options: ClaudeToPiOptions,
+): PiBundle {
+  const promptNames = new Set<string>()
+  const usedSkillNames = new Set<string>(plugin.skills.map((skill) => normalizeName(skill.name)))
+
+  const prompts = plugin.commands
+    .filter((command) => !command.disableModelInvocation)
+    .map((command) => convertPrompt(command, promptNames))
+
+  const generatedSkills = plugin.agents.map((agent) => convertAgent(agent, usedSkillNames))
+
+  const extensions = [
+    {
+      name: "compound-engineering-compat.ts",
+      content: PI_COMPAT_EXTENSION_SOURCE,
+    },
+  ]
+
+  return {
+    prompts,
+    skillDirs: plugin.skills.map((skill) => ({
+      name: skill.name,
+      sourceDir: skill.sourceDir,
+    })),
+    generatedSkills,
+    extensions,
+    mcporterConfig: plugin.mcpServers ? convertMcpToMcporter(plugin.mcpServers) : undefined,
+  }
+}
+
+function convertPrompt(command: ClaudeCommand, usedNames: Set<string>) {
+  const name = uniqueName(normalizeName(command.name), usedNames)
+  const frontmatter: Record<string, unknown> = {
+    description: command.description,
+    "argument-hint": command.argumentHint,
+  }
+
+  let body = transformContentForPi(command.body)
+  body = appendCompatibilityNoteIfNeeded(body)
+
+  return {
+    name,
+    content: formatFrontmatter(frontmatter, body.trim()),
+  }
+}
+
+function convertAgent(agent: ClaudeAgent, usedNames: Set<string>): PiGeneratedSkill {
+  const name = uniqueName(normalizeName(agent.name), usedNames)
+  const description = sanitizeDescription(
+    agent.description ?? `Converted from Claude agent ${agent.name}`,
+  )
+
+  const frontmatter: Record<string, unknown> = {
+    name,
+    description,
+  }
+
+  const sections: string[] = []
+  if (agent.capabilities && agent.capabilities.length > 0) {
+    sections.push(`## Capabilities\n${agent.capabilities.map((capability) => `- ${capability}`).join("\n")}`)
+  }
+
+  const body = [
+    ...sections,
+    agent.body.trim().length > 0
+      ? agent.body.trim()
+      : `Instructions converted from the ${agent.name} agent.`,
+  ].join("\n\n")
+
+  return {
+    name,
+    content: formatFrontmatter(frontmatter, body),
+  }
+}
+
+function transformContentForPi(body: string): string {
+  let result = body
+
+  // Task repo-research-analyst(feature_description)
+  // -> Run subagent with agent="repo-research-analyst" and task="feature_description"
+  const taskPattern = /^(\s*-?\s*)Task\s+([a-z][a-z0-9-]*)\(([^)]+)\)/gm
+  result = result.replace(taskPattern, (_match, prefix: string, agentName: string, args: string) => {
+    const skillName = normalizeName(agentName)
+    const trimmedArgs = args.trim().replace(/\s+/g, " ")
+    return `${prefix}Run subagent with agent=\"${skillName}\" and task=\"${trimmedArgs}\".`
+  })
+
+  // Claude-specific tool references
+  result = result.replace(/\bAskUserQuestion\b/g, "ask_user_question")
+  result = result.replace(/\bTodoWrite\b/g, "file-based todos (todos/ + /skill:file-todos)")
+  result = result.replace(/\bTodoRead\b/g, "file-based todos (todos/ + /skill:file-todos)")
+
+  // /command-name or /workflows:command-name -> /workflows-command-name
+  const slashCommandPattern = /(?<![:\w])\/([a-z][a-z0-9_:-]*?)(?=[\s,."')\]}`]|$)/gi
+  result = result.replace(slashCommandPattern, (match, commandName: string) => {
+    if (commandName.includes("/")) return match
+    if (["dev", "tmp", "etc", "usr", "var", "bin", "home"].includes(commandName)) {
+      return match
+    }
+
+    if (commandName.startsWith("skill:")) {
+      const skillName = commandName.slice("skill:".length)
+      return `/skill:${normalizeName(skillName)}`
+    }
+
+    const withoutPrefix = commandName.startsWith("prompts:")
+      ? commandName.slice("prompts:".length)
+      : commandName
+
+    return `/${normalizeName(withoutPrefix)}`
+  })
+
+  return result
+}
+
+function appendCompatibilityNoteIfNeeded(body: string): string {
+  if (!/\bmcp\b/i.test(body)) return body
+
+  const note = [
+    "",
+    "## Pi + MCPorter note",
+    "For MCP access in Pi, use MCPorter via the generated tools:",
+    "- `mcporter_list` to inspect available MCP tools",
+    "- `mcporter_call` to invoke a tool",
+    "",
+  ].join("\n")
+
+  return body + note
+}
+
+function convertMcpToMcporter(servers: Record<string, ClaudeMcpServer>): PiMcporterConfig {
+  const mcpServers: Record<string, PiMcporterServer> = {}
+
+  for (const [name, server] of Object.entries(servers)) {
+    if (server.command) {
+      mcpServers[name] = {
+        command: server.command,
+        args: server.args,
+        env: server.env,
+        headers: server.headers,
+      }
+      continue
+    }
+
+    if (server.url) {
+      mcpServers[name] = {
+        baseUrl: server.url,
+        headers: server.headers,
+      }
+    }
+  }
+
+  return { mcpServers }
+}
+
+function normalizeName(value: string): string {
+  const trimmed = value.trim()
+  if (!trimmed) return "item"
+  const normalized = trimmed
+    .toLowerCase()
+    .replace(/[\\/]+/g, "-")
+    .replace(/[:\s]+/g, "-")
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "")
+  return normalized || "item"
+}
+
+function sanitizeDescription(value: string, maxLength = PI_DESCRIPTION_MAX_LENGTH): string {
+  const normalized = value.replace(/\s+/g, " ").trim()
+  if (normalized.length <= maxLength) return normalized
+  const ellipsis = "..."
+  return normalized.slice(0, Math.max(0, maxLength - ellipsis.length)).trimEnd() + ellipsis
+}
+
+function uniqueName(base: string, used: Set<string>): string {
+  if (!used.has(base)) {
+    used.add(base)
+    return base
+  }
+  let index = 2
+  while (used.has(`${base}-${index}`)) {
+    index += 1
+  }
+  const name = `${base}-${index}`
+  used.add(name)
+  return name
+}

src/index.ts

@@ -3,6 +3,7 @@ import { defineCommand, runMain } from "citty"
 import convert from "./commands/convert"
 import install from "./commands/install"
 import listCommand from "./commands/list"
+import sync from "./commands/sync"
 
 const main = defineCommand({
   meta: {
@@ -14,6 +15,7 @@ const main = defineCommand({
     convert: () => convert,
     install: () => install,
     list: () => listCommand,
+    sync: () => sync,
   },
 })
 

src/parsers/claude-home.ts

@@ -0,0 +1,65 @@
+import path from "path"
+import os from "os"
+import fs from "fs/promises"
+import type { ClaudeSkill, ClaudeMcpServer } from "../types/claude"
+
+export interface ClaudeHomeConfig {
+  skills: ClaudeSkill[]
+  mcpServers: Record<string, ClaudeMcpServer>
+}
+
+export async function loadClaudeHome(claudeHome?: string): Promise<ClaudeHomeConfig> {
+  const home = claudeHome ?? path.join(os.homedir(), ".claude")
+
+  const [skills, mcpServers] = await Promise.all([
+    loadPersonalSkills(path.join(home, "skills")),
+    loadSettingsMcp(path.join(home, "settings.json")),
+  ])
+
+  return { skills, mcpServers }
+}
+
+async function loadPersonalSkills(skillsDir: string): Promise<ClaudeSkill[]> {
+  try {
+    const entries = await fs.readdir(skillsDir, { withFileTypes: true })
+    const skills: ClaudeSkill[] = []
+
+    for (const entry of entries) {
+      // Check if directory or symlink (symlinks are common for skills)
+      if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+
+      const entryPath = path.join(skillsDir, entry.name)
+      const skillPath = path.join(entryPath, "SKILL.md")
+
+      try {
+        await fs.access(skillPath)
+        // Resolve symlink to get the actual source directory
+        const sourceDir = entry.isSymbolicLink()
+          ? await fs.realpath(entryPath)
+          : entryPath
+        skills.push({
+          name: entry.name,
+          sourceDir,
+          skillPath,
+        })
+      } catch {
+        // No SKILL.md, skip
+      }
+    }
+    return skills
+  } catch {
+    return [] // Directory doesn't exist
+  }
+}
+
+async function loadSettingsMcp(
+  settingsPath: string,
+): Promise<Record<string, ClaudeMcpServer>> {
+  try {
+    const content = await fs.readFile(settingsPath, "utf-8")
+    const settings = JSON.parse(content) as { mcpServers?: Record<string, ClaudeMcpServer> }
+    return settings.mcpServers ?? {}
+  } catch {
+    return {} // File doesn't exist or invalid JSON
+  }
+}

src/parsers/claude.ts

@@ -83,12 +83,14 @@ async function loadCommands(commandsDirs: string[]): Promise<ClaudeCommand[]> {
     const { data, body } = parseFrontmatter(raw)
     const name = (data.name as string) ?? path.basename(file, ".md")
     const allowedTools = parseAllowedTools(data["allowed-tools"])
+    const disableModelInvocation = data["disable-model-invocation"] === true ? true : undefined
     commands.push({
       name,
       description: data.description as string | undefined,
       argumentHint: data["argument-hint"] as string | undefined,
       model: data.model as string | undefined,
       allowedTools,
+      disableModelInvocation,
       body: body.trim(),
       sourcePath: file,
     })
@@ -104,9 +106,11 @@ async function loadSkills(skillsDirs: string[]): Promise<ClaudeSkill[]> {
     const raw = await readText(file)
     const { data } = parseFrontmatter(raw)
     const name = (data.name as string) ?? path.basename(path.dirname(file))
+    const disableModelInvocation = data["disable-model-invocation"] === true ? true : undefined
     skills.push({
       name,
       description: data.description as string | undefined,
+      disableModelInvocation,
       sourceDir: path.dirname(file),
       skillPath: file,
     })

src/sync/codex.ts

@@ -0,0 +1,92 @@
+import fs from "fs/promises"
+import path from "path"
+import type { ClaudeHomeConfig } from "../parsers/claude-home"
+import type { ClaudeMcpServer } from "../types/claude"
+import { forceSymlink, isValidSkillName } from "../utils/symlink"
+
+export async function syncToCodex(
+  config: ClaudeHomeConfig,
+  outputRoot: string,
+): Promise<void> {
+  // Ensure output directories exist
+  const skillsDir = path.join(outputRoot, "skills")
+  await fs.mkdir(skillsDir, { recursive: true })
+
+  // Symlink skills (with validation)
+  for (const skill of config.skills) {
+    if (!isValidSkillName(skill.name)) {
+      console.warn(`Skipping skill with invalid name: ${skill.name}`)
+      continue
+    }
+    const target = path.join(skillsDir, skill.name)
+    await forceSymlink(skill.sourceDir, target)
+  }
+
+  // Write MCP servers to config.toml (TOML format)
+  if (Object.keys(config.mcpServers).length > 0) {
+    const configPath = path.join(outputRoot, "config.toml")
+    const mcpToml = convertMcpForCodex(config.mcpServers)
+
+    // Read existing config and merge idempotently
+    let existingContent = ""
+    try {
+      existingContent = await fs.readFile(configPath, "utf-8")
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+        throw err
+      }
+    }
+
+    // Remove any existing Claude Code MCP section to make idempotent
+    const marker = "# MCP servers synced from Claude Code"
+    const markerIndex = existingContent.indexOf(marker)
+    if (markerIndex !== -1) {
+      existingContent = existingContent.slice(0, markerIndex).trimEnd()
+    }
+
+    const newContent = existingContent
+      ? existingContent + "\n\n" + marker + "\n" + mcpToml
+      : "# Codex config - synced from Claude Code\n\n" + mcpToml
+
+    await fs.writeFile(configPath, newContent, { mode: 0o600 })
+  }
+}
+
+/** Escape a string for TOML double-quoted strings */
+function escapeTomlString(str: string): string {
+  return str
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, "\\n")
+    .replace(/\r/g, "\\r")
+    .replace(/\t/g, "\\t")
+}
+
+function convertMcpForCodex(servers: Record<string, ClaudeMcpServer>): string {
+  const sections: string[] = []
+
+  for (const [name, server] of Object.entries(servers)) {
+    if (!server.command) continue
+
+    const lines: string[] = []
+    lines.push(`[mcp_servers.${name}]`)
+    lines.push(`command = "${escapeTomlString(server.command)}"`)
+
+    if (server.args && server.args.length > 0) {
+      const argsStr = server.args.map((arg) => `"${escapeTomlString(arg)}"`).join(", ")
+      lines.push(`args = [${argsStr}]`)
+    }
+
+    if (server.env && Object.keys(server.env).length > 0) {
+      lines.push("")
+      lines.push(`[mcp_servers.${name}.env]`)
+      for (const [key, value] of Object.entries(server.env)) {
+        lines.push(`${key} = "${escapeTomlString(value)}"`)
+      }
+    }
+
+    sections.push(lines.join("\n"))
+  }
+
+  return sections.join("\n\n") + "\n"
+}

src/sync/cursor.ts

@@ -0,0 +1,78 @@
+import fs from "fs/promises"
+import path from "path"
+import type { ClaudeHomeConfig } from "../parsers/claude-home"
+import type { ClaudeMcpServer } from "../types/claude"
+import { forceSymlink, isValidSkillName } from "../utils/symlink"
+
+type CursorMcpServer = {
+  command?: string
+  args?: string[]
+  url?: string
+  env?: Record<string, string>
+  headers?: Record<string, string>
+}
+
+type CursorMcpConfig = {
+  mcpServers: Record<string, CursorMcpServer>
+}
+
+export async function syncToCursor(
+  config: ClaudeHomeConfig,
+  outputRoot: string,
+): Promise<void> {
+  const skillsDir = path.join(outputRoot, "skills")
+  await fs.mkdir(skillsDir, { recursive: true })
+
+  for (const skill of config.skills) {
+    if (!isValidSkillName(skill.name)) {
+      console.warn(`Skipping skill with invalid name: ${skill.name}`)
+      continue
+    }
+    const target = path.join(skillsDir, skill.name)
+    await forceSymlink(skill.sourceDir, target)
+  }
+
+  if (Object.keys(config.mcpServers).length > 0) {
+    const mcpPath = path.join(outputRoot, "mcp.json")
+    const existing = await readJsonSafe(mcpPath)
+    const converted = convertMcpForCursor(config.mcpServers)
+    const merged: CursorMcpConfig = {
+      mcpServers: {
+        ...(existing.mcpServers ?? {}),
+        ...converted,
+      },
+    }
+    await fs.writeFile(mcpPath, JSON.stringify(merged, null, 2), { mode: 0o600 })
+  }
+}
+
+async function readJsonSafe(filePath: string): Promise<Partial<CursorMcpConfig>> {
+  try {
+    const content = await fs.readFile(filePath, "utf-8")
+    return JSON.parse(content) as Partial<CursorMcpConfig>
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return {}
+    }
+    throw err
+  }
+}
+
+function convertMcpForCursor(
+  servers: Record<string, ClaudeMcpServer>,
+): Record<string, CursorMcpServer> {
+  const result: Record<string, CursorMcpServer> = {}
+  for (const [name, server] of Object.entries(servers)) {
+    const entry: CursorMcpServer = {}
+    if (server.command) {
+      entry.command = server.command
+      if (server.args && server.args.length > 0) entry.args = server.args
+      if (server.env && Object.keys(server.env).length > 0) entry.env = server.env
+    } else if (server.url) {
+      entry.url = server.url
+      if (server.headers && Object.keys(server.headers).length > 0) entry.headers = server.headers
+    }
+    result[name] = entry
+  }
+  return result
+}

src/sync/droid.ts

@@ -0,0 +1,21 @@
+import fs from "fs/promises"
+import path from "path"
+import type { ClaudeHomeConfig } from "../parsers/claude-home"
+import { forceSymlink, isValidSkillName } from "../utils/symlink"
+
+export async function syncToDroid(
+  config: ClaudeHomeConfig,
+  outputRoot: string,
+): Promise<void> {
+  const skillsDir = path.join(outputRoot, "skills")
+  await fs.mkdir(skillsDir, { recursive: true })
+
+  for (const skill of config.skills) {
+    if (!isValidSkillName(skill.name)) {
+      console.warn(`Skipping skill with invalid name: ${skill.name}`)
+      continue
+    }
+    const target = path.join(skillsDir, skill.name)
+    await forceSymlink(skill.sourceDir, target)
+  }
+}

src/sync/opencode.ts

@@ -0,0 +1,75 @@
+import fs from "fs/promises"
+import path from "path"
+import type { ClaudeHomeConfig } from "../parsers/claude-home"
+import type { ClaudeMcpServer } from "../types/claude"
+import type { OpenCodeMcpServer } from "../types/opencode"
+import { forceSymlink, isValidSkillName } from "../utils/symlink"
+
+export async function syncToOpenCode(
+  config: ClaudeHomeConfig,
+  outputRoot: string,
+): Promise<void> {
+  // Ensure output directories exist
+  const skillsDir = path.join(outputRoot, "skills")
+  await fs.mkdir(skillsDir, { recursive: true })
+
+  // Symlink skills (with validation)
+  for (const skill of config.skills) {
+    if (!isValidSkillName(skill.name)) {
+      console.warn(`Skipping skill with invalid name: ${skill.name}`)
+      continue
+    }
+    const target = path.join(skillsDir, skill.name)
+    await forceSymlink(skill.sourceDir, target)
+  }
+
+  // Merge MCP servers into opencode.json
+  if (Object.keys(config.mcpServers).length > 0) {
+    const configPath = path.join(outputRoot, "opencode.json")
+    const existing = await readJsonSafe(configPath)
+    const mcpConfig = convertMcpForOpenCode(config.mcpServers)
+    existing.mcp = { ...(existing.mcp ?? {}), ...mcpConfig }
+    await fs.writeFile(configPath, JSON.stringify(existing, null, 2), { mode: 0o600 })
+  }
+}
+
+async function readJsonSafe(filePath: string): Promise<Record<string, unknown>> {
+  try {
+    const content = await fs.readFile(filePath, "utf-8")
+    return JSON.parse(content) as Record<string, unknown>
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return {}
+    }
+    throw err
+  }
+}
+
+function convertMcpForOpenCode(
+  servers: Record<string, ClaudeMcpServer>,
+): Record<string, OpenCodeMcpServer> {
+  const result: Record<string, OpenCodeMcpServer> = {}
+
+  for (const [name, server] of Object.entries(servers)) {
+    if (server.command) {
+      result[name] = {
+        type: "local",
+        command: [server.command, ...(server.args ?? [])],
+        environment: server.env,
+        enabled: true,
+      }
+      continue
+    }
+
+    if (server.url) {
+      result[name] = {
+        type: "remote",
+        url: server.url,
+        headers: server.headers,
+        enabled: true,
+      }
+    }
+  }
+
+  return result
+}

src/sync/pi.ts

@@ -0,0 +1,88 @@
+import fs from "fs/promises"
+import path from "path"
+import type { ClaudeHomeConfig } from "../parsers/claude-home"
+import type { ClaudeMcpServer } from "../types/claude"
+import { forceSymlink, isValidSkillName } from "../utils/symlink"
+
+type McporterServer = {
+  baseUrl?: string
+  command?: string
+  args?: string[]
+  env?: Record<string, string>
+  headers?: Record<string, string>
+}
+
+type McporterConfig = {
+  mcpServers: Record<string, McporterServer>
+}
+
+export async function syncToPi(
+  config: ClaudeHomeConfig,
+  outputRoot: string,
+): Promise<void> {
+  const skillsDir = path.join(outputRoot, "skills")
+  const mcporterPath = path.join(outputRoot, "compound-engineering", "mcporter.json")
+
+  await fs.mkdir(skillsDir, { recursive: true })
+
+  for (const skill of config.skills) {
+    if (!isValidSkillName(skill.name)) {
+      console.warn(`Skipping skill with invalid name: ${skill.name}`)
+      continue
+    }
+    const target = path.join(skillsDir, skill.name)
+    await forceSymlink(skill.sourceDir, target)
+  }
+
+  if (Object.keys(config.mcpServers).length > 0) {
+    await fs.mkdir(path.dirname(mcporterPath), { recursive: true })
+
+    const existing = await readJsonSafe(mcporterPath)
+    const converted = convertMcpToMcporter(config.mcpServers)
+    const merged: McporterConfig = {
+      mcpServers: {
+        ...(existing.mcpServers ?? {}),
+        ...converted.mcpServers,
+      },
+    }
+
+    await fs.writeFile(mcporterPath, JSON.stringify(merged, null, 2), { mode: 0o600 })
+  }
+}
+
+async function readJsonSafe(filePath: string): Promise<Partial<McporterConfig>> {
+  try {
+    const content = await fs.readFile(filePath, "utf-8")
+    return JSON.parse(content) as Partial<McporterConfig>
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return {}
+    }
+    throw err
+  }
+}
+
+function convertMcpToMcporter(servers: Record<string, ClaudeMcpServer>): McporterConfig {
+  const mcpServers: Record<string, McporterServer> = {}
+
+  for (const [name, server] of Object.entries(servers)) {
+    if (server.command) {
+      mcpServers[name] = {
+        command: server.command,
+        args: server.args,
+        env: server.env,
+        headers: server.headers,
+      }
+      continue
+    }
+
+    if (server.url) {
+      mcpServers[name] = {
+        baseUrl: server.url,
+        headers: server.headers,
+      }
+    }
+  }
+
+  return { mcpServers }
+}