chore: import upstream snapshot with attribution

.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "compound-engineering-plugin",
+  "interface": {
+    "displayName": "Compound Engineering"
+  },
+  "plugins": [
+    {
+      "name": "compound-engineering",
+      "source": {
+        "source": "url",
+        "url": "https://github.com/EveryInc/compound-engineering-plugin.git"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Coding"
+    }
+  ]
+}

.agy/INSTALL.md

@@ -0,0 +1,78 @@
+# Installing Compound Engineering for Antigravity CLI (`agy`)
+
+Antigravity installs CE as a native plugin bundle. The repository root is the plugin package: `plugin.json` plus the `skills/` directory. The committed `.agy/` subdirectory is a compatibility entry point for local checkouts that prefer an explicit bundle path.
+
+## One-command install (recommended)
+
+With [Antigravity CLI](https://antigravity.google) installed:
+
+```bash
+agy plugin install https://github.com/EveryInc/compound-engineering-plugin
+```
+
+Verify:
+
+```bash
+agy plugin list
+agy plugin validate https://github.com/EveryInc/compound-engineering-plugin
+```
+
+No clone step is required. `agy` stages the plugin under `~/.gemini/antigravity-cli/plugins/compound-engineering/`.
+
+## Local checkout install
+
+Clone first when you need a specific branch, tag, or unpublished changes:
+
+```bash
+git clone https://github.com/EveryInc/compound-engineering-plugin
+agy plugin install ./compound-engineering-plugin
+```
+
+Or install the bundled `.agy/` entry point (equivalent manifest via symlink):
+
+```bash
+agy plugin install ./compound-engineering-plugin/.agy
+```
+
+## Pin a release
+
+Install from a release tag:
+
+```bash
+git clone --branch compound-engineering-vX.Y.Z --depth 1 \
+  https://github.com/EveryInc/compound-engineering-plugin.git
+agy plugin install ./compound-engineering-plugin
+```
+
+Replace `X.Y.Z` with a tag from the [releases page](https://github.com/EveryInc/compound-engineering-plugin/releases).
+
+## Local development
+
+From your working copy:
+
+```bash
+agy plugin install "$PWD"
+agy plugin validate "$PWD"
+```
+
+Edit skills under `skills/` and restart `agy` or start a new session to pick up prose changes.
+
+## Context files
+
+`agy` reads `GEMINI.md` and `AGENTS.md` as workspace context. Run `agy` from a project that includes those files, or from this checkout when developing CE itself.
+
+## Uninstall
+
+```bash
+agy plugin uninstall compound-engineering
+```
+
+## Legacy Gemini CLI import
+
+If you previously installed CE under Gemini CLI:
+
+```bash
+agy plugin import gemini
+```
+
+Prefer the native install commands above for new setups.

.agy/plugin.json

@@ -0,0 +1 @@
+../plugin.json

.agy/skills

@@ -0,0 +1 @@
+../skills

.claude-plugin/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [1.0.3](https://github.com/EveryInc/compound-engineering-plugin/compare/marketplace-v1.0.2...marketplace-v1.0.3) (2026-06-24)
+
+
+### Bug Fixes
+
+* **metadata:** align plugin and marketplace metadata ([#987](https://github.com/EveryInc/compound-engineering-plugin/issues/987)) ([f57c682](https://github.com/EveryInc/compound-engineering-plugin/commit/f57c68257cbd792c25ef85047c426329c5c3f848))

.claude-plugin/marketplace.json

@@ -0,0 +1,29 @@
+{
+  "name": "compound-engineering-plugin",
+  "owner": {
+    "name": "Kieran Klaassen and Trevin Chow"
+  },
+  "metadata": {
+    "description": "Plugin marketplace for Claude Code and Codex extensions",
+    "version": "1.0.3"
+  },
+  "plugins": [
+    {
+      "name": "compound-engineering",
+      "description": "Brainstorm, plan, debug, review, and compound learnings with AI agents",
+      "author": {
+        "name": "Kieran Klaassen and Trevin Chow"
+      },
+      "homepage": "https://github.com/EveryInc/compound-engineering-plugin",
+      "tags": [
+        "ai-powered",
+        "compound-engineering",
+        "workflow-automation",
+        "code-review",
+        "quality",
+        "knowledge-management"
+      ],
+      "source": "./"
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "compound-engineering",
+  "version": "3.19.0",
+  "description": "Brainstorm, plan, debug, review, and compound learnings with AI agents",
+  "author": {
+    "name": "Kieran Klaassen and Trevin Chow"
+  },
+  "homepage": "https://every.to/source-code/my-ai-had-already-fixed-the-code-before-i-saw-it",
+  "repository": "https://github.com/EveryInc/compound-engineering-plugin",
+  "license": "MIT",
+  "keywords": [
+    "brainstorming",
+    "code-review",
+    "compound-engineering",
+    "debugging",
+    "ideation",
+    "workflows",
+    "workflow-automation"
+  ]
+}

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

.cline/INSTALL.md

@@ -0,0 +1,62 @@
+# Installing Compound Engineering for Cline
+
+Cline loads CE through native **skills** discovery — the same `SKILL.md` directories shipped in this repository's `skills/` folder. No Bun converter or generated copy step is required.
+
+## Extension (VS Code, Cursor, JetBrains)
+
+1. Install the [Cline extension](https://docs.cline.bot/getting-started/installing-cline) in your editor.
+2. Enable **Settings -> Features -> Enable Skills**.
+3. Link CE skills globally or into your project (see below).
+4. Start a new Cline task. Skills such as `ce-brainstorm` and `ce-plan` appear when their descriptions match your request.
+
+## Install skills
+
+From a clone of this repository:
+
+```bash
+# Global (~/.cline/skills/) — available in every project
+./compound-engineering-plugin/.cline/scripts/install-skills.sh --global
+
+# Project (.cline/skills/ in the current directory)
+./compound-engineering-plugin/.cline/scripts/install-skills.sh --project
+```
+
+The script creates symlinks so Cline reads the live skill directories from your checkout. Re-run it after `git pull` to refresh links when skill folder names change. It only ever creates or replaces CE-owned symlinks (links whose target resolves under this checkout's `skills/` tree); an existing `~/.cline/skills/<name>` pointing at your own skill, a fork, or another checkout is left untouched. Default installs also remove only manual-only symlinks that are CE-owned.
+
+Skills marked `disable-model-invocation: true` (for example `lfg`, `ce-dogfood`, `ce-polish`) are **not** linked by default — Cline auto-activates from description matching and has no manual-only gate, so linking them would let them fire unintentionally. Those slash commands are unavailable until you opt in:
+
+```bash
+./compound-engineering-plugin/.cline/scripts/install-skills.sh --global --include-manual
+```
+
+`--include-manual` links manual-only skills so `/lfg` and similar commands work, with a warning that Cline may still auto-activate them when descriptions match. Omit the flag if you do not need those workflows on Cline.
+
+## Pin a release
+
+Clone the tag you want, then run the install script against that checkout:
+
+```bash
+git clone --branch compound-engineering-vX.Y.Z --depth 1 \
+  https://github.com/EveryInc/compound-engineering-plugin.git
+./compound-engineering-plugin/.cline/scripts/install-skills.sh --global
+```
+
+Replace `X.Y.Z` with a tag from the [releases page](https://github.com/EveryInc/compound-engineering-plugin/releases).
+
+## Local development
+
+From your working copy:
+
+```bash
+/path/to/compound-engineering-plugin/.cline/scripts/install-skills.sh --global
+```
+
+Edit skills under `skills/` and start a new Cline task to pick up prose changes.
+
+## Uninstall
+
+Remove CE skill symlinks from `~/.cline/skills/` or `.cline/skills/`. Skill directory names match the folders under `skills/` (for example `ce-brainstorm`, `ce-plan`).
+
+## Cline CLI
+
+The Cline CLI supports separate `AgentPlugin` installs for custom tools and hooks. CE does not require a CLI plugin for its skills to work. Use the skills install script above when running Cline from the terminal.

.cline/scripts/install-skills.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# Link Compound Engineering skills/ into Cline's skills discovery directory.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+SKILLS_SRC="$REPO_ROOT/skills"
+
+usage() {
+  cat <<'EOF'
+Usage: install-skills.sh [--global | --project] [--include-manual]
+
+  --global          Link skills into ~/.cline/skills/ (default)
+  --project         Link skills into ./.cline/skills/ under the current directory
+  --include-manual  Also link manual-only skills (disable-model-invocation: true).
+                    Cline has no manual-only gate — linked manual skills may auto-activate.
+
+Set CLINE_SKILLS_DIR to override the global destination.
+EOF
+  exit 1
+}
+
+SCOPE="--global"
+INCLUDE_MANUAL=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --global | --project)
+      SCOPE="$1"
+      shift
+      ;;
+    --include-manual)
+      INCLUDE_MANUAL=true
+      shift
+      ;;
+    *)
+      usage
+      ;;
+  esac
+done
+
+if [[ "$SCOPE" == "--project" ]]; then
+  DEST="$(pwd)/.cline/skills"
+else
+  DEST="${CLINE_SKILLS_DIR:-$HOME/.cline/skills}"
+fi
+
+if [[ ! -d "$SKILLS_SRC" ]]; then
+  echo "error: skills directory not found at $SKILLS_SRC" >&2
+  exit 1
+fi
+
+canonical_path() {
+  python3 -c 'import os, sys; print(os.path.realpath(sys.argv[1]))' "$1"
+}
+
+SKILLS_ROOT_CANON="$(canonical_path "$SKILLS_SRC")"
+
+is_ce_owned_skill_link() {
+  local link_path="$1"
+  [[ -L "$link_path" ]] || return 1
+
+  local resolved
+  resolved="$(canonical_path "$link_path")"
+  [[ "$resolved" == "$SKILLS_ROOT_CANON/"* ]]
+}
+
+mkdir -p "$DEST"
+linked=0
+skipped=0
+manual_omitted=0
+manual_included=0
+manual_removed=0
+
+for skill_dir in "$SKILLS_SRC"/*/; do
+  [[ -f "${skill_dir}SKILL.md" ]] || continue
+  name="$(basename "$skill_dir")"
+  target="$DEST/$name"
+  is_manual=false
+
+  if grep -qE '^disable-model-invocation:[[:space:]]*true[[:space:]]*$' "${skill_dir}SKILL.md"; then
+    is_manual=true
+    if [[ "$INCLUDE_MANUAL" != "true" ]]; then
+      if is_ce_owned_skill_link "$target"; then
+        rm "$target"
+        echo "removed $name: stale CE manual-only symlink" >&2
+        manual_removed=$((manual_removed + 1))
+      fi
+      echo "skip $name: manual-only (disable-model-invocation)" >&2
+      manual_omitted=$((manual_omitted + 1))
+      continue
+    fi
+    echo "warn $name: manual-only skill linked — Cline may auto-activate when descriptions match" >&2
+    manual_included=$((manual_included + 1))
+  fi
+
+  if [[ -e "$target" && ! -L "$target" ]]; then
+    echo "skip $name: $target exists and is not a symlink" >&2
+    skipped=$((skipped + 1))
+    continue
+  fi
+
+  if [[ -L "$target" ]] && ! is_ce_owned_skill_link "$target"; then
+    echo "skip $name: $target is an existing user-managed symlink (not overwritten)" >&2
+    skipped=$((skipped + 1))
+    continue
+  fi
+
+  ln -sfn "$skill_dir" "$target"
+  if [[ "$is_manual" == "true" ]]; then
+    echo "linked $name (manual-only) -> $skill_dir"
+  else
+    echo "linked $name -> $skill_dir"
+  fi
+  linked=$((linked + 1))
+done
+
+if [[ "$INCLUDE_MANUAL" == "true" ]]; then
+  echo "done: $linked linked, $skipped skipped, $manual_included manual-only included (destination: $DEST)"
+else
+  echo "done: $linked linked, $skipped skipped, $manual_omitted manual-only omitted, $manual_removed stale manual-only removed (destination: $DEST)"
+fi

.codex-plugin/plugin.json

@@ -0,0 +1,45 @@
+{
+  "name": "compound-engineering",
+  "version": "3.19.0",
+  "description": "Brainstorm, plan, debug, review, and compound learnings with AI agents",
+  "author": {
+    "name": "Kieran Klaassen and Trevin Chow"
+  },
+  "homepage": "https://every.to/source-code/my-ai-had-already-fixed-the-code-before-i-saw-it",
+  "repository": "https://github.com/EveryInc/compound-engineering-plugin",
+  "license": "MIT",
+  "keywords": [
+    "brainstorming",
+    "code-review",
+    "compound-engineering",
+    "debugging",
+    "ideation",
+    "workflows",
+    "workflow-automation"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Compound Engineering",
+    "shortDescription": "Brainstorm, plan, debug, review, and compound learnings with AI agents",
+    "longDescription": "Compound Engineering guides AI agents through the full engineering loop: strategy, ideation, requirements, planning, execution, debugging, review, PR feedback, and captured learnings that make future work easier.",
+    "developerName": "Kieran Klaassen and Trevin Chow",
+    "category": "Coding",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/EveryInc/compound-engineering-plugin",
+    "privacyPolicyURL": "https://every.to/legal",
+    "termsOfServiceURL": "https://every.to/legal",
+    "defaultPrompt": [
+      "Brainstorm a new feature with me",
+      "Ideate and surprise me!",
+      "Simplify the code in my most-churned file"
+    ],
+    "brandColor": "#C9EFFA",
+    "composerIcon": "./assets/icon.svg",
+    "logo": "./assets/logo.png",
+    "screenshots": []
+  }
+}

.compound-engineering/config.local.example.yaml

@@ -0,0 +1,100 @@
+# Compound Engineering -- local config
+# Copy to .compound-engineering/config.local.yaml in your project root.
+# All settings are optional. Invalid values fall through to defaults.
+
+# --- Product pulse ---
+# Settings written by /ce-product-pulse first-run interview. Re-run the skill with
+# argument `setup` or `reconfigure` to edit interactively.
+
+# pulse_product_name: "Spiral"                          # used in report titles (no default)
+# pulse_lookback_default: 24h                           # 1h | 24h | 7d | 30d (default: 24h)
+# pulse_primary_event: "session_started"                # the event that means "user showed up"
+# pulse_value_event: "task_completed"                   # the event that means "user got value"
+# pulse_completion_events: "onboarded,first_purchase"   # comma-separated, 0-3 events
+# pulse_quality_scoring: false                          # true | false (default: false; AI products only)
+# pulse_quality_dimension: "answer accuracy"            # dimension scored 1-5 when pulse_quality_scoring is true
+# pulse_analytics_source: posthog                       # posthog | mixpanel | custom (no default)
+# pulse_tracing_source: sentry                          # sentry | datadog | custom (no default)
+# pulse_payments_source: stripe                         # stripe | custom (no default)
+# pulse_db_enabled: false                               # true | false (default: false; read-only DB if true)
+# pulse_metric_sources: "retention_d7=posthog,nps=delighted"  # strategy-metric -> source overrides; comma-separated 'metric=source' pairs; unlisted metrics fall back to pulse_analytics_source
+# pulse_pending_metrics: "retention_d7,nps"             # comma-separated strategy metrics awaiting instrumentation; render as 'no data'
+# pulse_excluded_metrics: "north_star"                  # comma-separated strategy metrics intentionally not in pulse
+
+# --- Output format ---
+# Per-skill output format default. Selects the exclusive format the artifact
+# is written in: `md` produces a markdown file, `html` produces a single
+# self-contained HTML file. The two are mutually exclusive -- there is no
+# sibling artifact. See DESIGN.md or your agent instructions to influence
+# HTML styling. Precedence: a format request in your prompt for that run wins
+# (e.g. "output:html" or "make it HTML"); a preference you established earlier
+# (in-session, saved to memory, or in your agent instructions) overrides these
+# keys (this config is the persisted fallback); pipeline contexts (e.g., LFG,
+# disable-model-invocation) always force `md`.
+
+# plan_output: html              # md | html (default: md)
+# brainstorm_output: html        # md | html (default: md)
+# ideate_output: md              # md | html (default: html -- ideation docs are human-facing, so HTML is the default; set md to opt out)
+
+# --- Fable elevation (Claude Code only) ---
+# Claude Code ONLY; silently ignored on every other harness (Codex, Cursor, ...).
+# When on, /ce-plan and /ce-brainstorm dispatch their reasoning-heavy step (plan
+# authoring; approach generation) to the Fable model via a subagent, so you get
+# higher-reasoning output even when your session model is cheaper -- no session
+# switch. Per-skill so you can enable one without the other. You can also just
+# say "use fable" in a prompt for a one-off. Invalid/commented/missing -> off.
+
+# plan_use_fable: true           # true | false (default: false)
+# brainstorm_use_fable: true     # true | false (default: false)
+# fable_nudge: false             # true | false (default: true -- one-time tip when elevation is available but off)
+
+# --- PR concept teaching (ce-commit-push-pr) ---
+# When a PR introduces a concept new to the codebase, the generated PR
+# description gains a "New concepts" section teaching it. The section toggle is
+# the single gate: off disables judgment, the section, the /ce-explain offer,
+# and archival. Archival additionally writes the explainer to docs/explainers/
+# and links it from the PR (full-workflow runs only; override per run with
+# archive:on|off). Note: this file is gitignored and per-checkout -- fresh
+# worktrees don't inherit it.
+
+# pr_teaching_section: false     # true | false (default: true)
+# pr_teaching_archive: true      # true | false (default: false; full-workflow runs only)
+
+# --- ce-commit-push-pr babysit handoff ---
+# After a full-workflow PR is opened, ce-commit-push-pr auto-invokes ce-babysit-pr
+# to watch CI + incoming review and drive the PR toward merge-ready. Set false to
+# opt out standing (per-run override: the babysit:off token).
+# auto_babysit: false            # true | false (default: true)
+
+# --- ce-plan scoping confirmation ---
+# By default /ce-plan pauses before research/plan-write to show a scoping
+# summary and wait for you to confirm scope. Set this to skip that wait: ce-plan
+# composes the summary for itself, records any inferred scope under an
+# Assumptions section, announces that it's proceeding, and keeps going. It skips
+# only that confirmation -- genuine blocking questions and the post-plan menu
+# still appear. Override per run with `confirm:auto` (skip) or `confirm:ask`
+# (force the gate on for one run).
+
+# plan_skip_scoping_confirm: true   # true | false (default: false)
+
+# --- ce-promote ---
+# Written automatically when you decline the Spiral setup offer in /ce-promote.
+# Suppresses that one-time setup nudge in this project. Remove the key to re-enable.
+
+# ce_promote_spiral_optout: true   # true | (absent) (default: absent -- offer once)
+
+# --- Sweep (ce-sweep) ---
+
+# Feedback sources swept by /ce-sweep. Generic key: other skills may read this list.
+# Each entry: type (slack | github-issues | email), id (short name), target (channel ID /
+# owner/repo / mailbox), ack_action, closeout_action, sensitive (true withholds content
+# from committed state/plan text), approved (standing approval for source-side writes).
+# feedback_sources:
+#   - { type: slack, id: slack-alpha, target: C0XXXXXXX, ack_action: eyes, closeout_action: white_check_mark, sensitive: false, approved: true }
+#   - { type: github-issues, id: gh-issues, target: owner/repo, ack_action: "feedback:ack", closeout_action: "feedback:resolved", sensitive: false, approved: true }
+
+# Sweep-owned settings.
+# sweep_state_path: docs/feedback-sweep/state.yml   # committed (multi-agent) or /tmp path (solo)
+# sweep_ack_cap: 25                                 # max acks per source per run before the circuit breaker
+# sweep_lease_ttl_minutes: 60                       # single-writer lease staleness threshold
+# sweep_shared_branch: false                        # true: push-gated lease for shared-docs-branch topology

.cursor-plugin/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## [1.0.2](https://github.com/EveryInc/compound-engineering-plugin/compare/cursor-marketplace-v1.0.1...cursor-marketplace-v1.0.2) (2026-06-24)
+
+
+### Bug Fixes
+
+* **metadata:** align plugin and marketplace metadata ([#987](https://github.com/EveryInc/compound-engineering-plugin/issues/987)) ([f57c682](https://github.com/EveryInc/compound-engineering-plugin/commit/f57c68257cbd792c25ef85047c426329c5c3f848))
+
+## [1.0.1](https://github.com/EveryInc/compound-engineering-plugin/compare/cursor-marketplace-v1.0.0...cursor-marketplace-v1.0.1) (2026-03-19)
+
+
+### Bug Fixes
+
+* add cursor-marketplace as release-please component ([#315](https://github.com/EveryInc/compound-engineering-plugin/issues/315)) ([838aeb7](https://github.com/EveryInc/compound-engineering-plugin/commit/838aeb79d069b57a80d15ff61d83913919b81aef))

.cursor-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "compound-engineering",
+  "owner": {
+    "name": "Kieran Klaassen",
+    "email": "kieran@every.to",
+    "url": "https://github.com/kieranklaassen"
+  },
+  "metadata": {
+    "description": "Cursor plugin marketplace for Every Inc plugins",
+    "version": "1.0.2"
+  },
+  "plugins": [
+    {
+      "name": "compound-engineering",
+      "source": ".",
+      "description": "Brainstorm, plan, debug, review, and compound learnings with AI agents"
+    }
+  ]
+}

.cursor-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "compound-engineering",
+  "displayName": "Compound Engineering",
+  "version": "3.19.0",
+  "description": "Brainstorm, plan, debug, review, and compound learnings with AI agents",
+  "author": {
+    "name": "Kieran Klaassen and Trevin Chow"
+  },
+  "homepage": "https://every.to/source-code/my-ai-had-already-fixed-the-code-before-i-saw-it",
+  "repository": "https://github.com/EveryInc/compound-engineering-plugin",
+  "license": "MIT",
+  "keywords": [
+    "cursor",
+    "plugin",
+    "ai-powered",
+    "compound-engineering",
+    "workflow-automation",
+    "code-review",
+    "rails",
+    "ruby",
+    "python",
+    "typescript",
+    "knowledge-management"
+  ]
+}

.devin-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "compound-engineering",
+  "version": "3.19.0",
+  "description": "Brainstorm, plan, debug, review, and compound learnings with AI agents",
+  "author": {
+    "name": "Kieran Klaassen and Trevin Chow"
+  },
+  "homepage": "https://every.to/source-code/my-ai-had-already-fixed-the-code-before-i-saw-it",
+  "repository": "https://github.com/EveryInc/compound-engineering-plugin",
+  "license": "MIT",
+  "keywords": [
+    "brainstorming",
+    "code-review",
+    "compound-engineering",
+    "debugging",
+    "ideation",
+    "workflows",
+    "workflow-automation"
+  ]
+}

.github/.release-please-manifest.json

@@ -0,0 +1,5 @@
+{
+  ".": "3.19.0",
+  ".claude-plugin": "1.0.3",
+  ".cursor-plugin": "1.0.2"
+}

.github/release-please-config.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "include-component-in-tag": true,
+  "release-search-depth": 20,
+  "commit-search-depth": 50,
+  "plugins": [],
+  "packages": {
+    ".": {
+      "release-type": "simple",
+      "package-name": "compound-engineering",
+      "changelog-sections": [
+        {
+          "type": "feat",
+          "section": "Features",
+          "hidden": false
+        },
+        {
+          "type": "fix",
+          "section": "Bug Fixes",
+          "hidden": false
+        },
+        {
+          "type": "deps",
+          "section": "Dependencies",
+          "hidden": false
+        },
+        {
+          "type": "refactor",
+          "section": "Refactoring",
+          "hidden": false
+        }
+      ],
+      "skip-changelog": true,
+      "exclude-paths": [
+        "SECURITY.md",
+        "PRIVACY.md",
+        "favicon.png",
+        "docs/",
+        "scripts/",
+        ".github/",
+        ".claude/",
+        ".codex/",
+        ".gemini/",
+        ".cursor/",
+        ".windsurf/",
+        ".agents/plugins/marketplace.json",
+        ".kimi-plugin/marketplace.json",
+        ".claude-plugin/marketplace.json",
+        ".cursor-plugin/marketplace.json",
+        ".grok-plugin/marketplace.json"
+      ],
+      "extra-files": [
+        {
+          "type": "json",
+          "path": "package.json",
+          "jsonpath": "$.version"
+        },
+        {
+          "type": "json",
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
+        },
+        {
+          "type": "json",
+          "path": ".cursor-plugin/plugin.json",
+          "jsonpath": "$.version"
+        },
+        {
+          "type": "json",
+          "path": ".codex-plugin/plugin.json",
+          "jsonpath": "$.version"
+        },
+        {
+          "type": "json",
+          "path": ".kimi-plugin/plugin.json",
+          "jsonpath": "$.version"
+        },
+        {
+          "type": "json",
+          "path": ".grok-plugin/plugin.json",
+          "jsonpath": "$.version"
+        },
+        {
+          "type": "json",
+          "path": ".devin-plugin/plugin.json",
+          "jsonpath": "$.version"
+        },
+        {
+          "type": "json",
+          "path": "plugin.json",
+          "jsonpath": "$.version"
+        }
+      ]
+    },
+    ".claude-plugin": {
+      "release-type": "simple",
+      "package-name": "marketplace",
+      "extra-files": [
+        {
+          "type": "json",
+          "path": "marketplace.json",
+          "jsonpath": "$.metadata.version"
+        }
+      ]
+    },
+    ".cursor-plugin": {
+      "release-type": "simple",
+      "package-name": "cursor-marketplace",
+      "extra-files": [
+        {
+          "type": "json",
+          "path": "marketplace.json",
+          "jsonpath": "$.metadata.version"
+        }
+      ]
+    }
+  }
+}

.github/workflows/ci.yml

@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  pr-title:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+
+    steps:
+      - name: Validate PR title
+        uses: amannn/action-semantic-pull-request@v6.1.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          requireScope: false
+          types: |
+            feat
+            fix
+            docs
+            refactor
+            chore
+            test
+            ci
+            build
+            perf
+            revert
+
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        # Full history so release:validate can read the base-branch (origin/main)
+        # release-please manifest when checking release-as pins for staleness.
+        with:
+          fetch-depth: 0
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Validate release metadata
+        run: bun run release:validate
+
+      # Canonical schema check: runs `claude plugin validate` against the
+      # marketplace catalog and each plugin directory (blocking, non-strict).
+      # The CLI must be installed via npm, not bun: `bun x` cannot run this
+      # package (bun blocks its required postinstall and cannot resolve its
+      # `claude` bin name), and `bun run` rewrites `npx` in package.json
+      # scripts to the broken `bun x`, so the script invokes a `claude`
+      # already on PATH instead.
+      #
+      # The validator version is pinned deliberately for reproducible CI: a
+      # floating @latest would track new upstream validation rules
+      # automatically but could break CI without any repo change. Bump the
+      # pin intentionally to adopt new `claude plugin validate` rules (and
+      # revisit --strict below when doing so).
+      #
+      # --strict (warnings-as-errors) should be enabled once this known
+      # warning is fixed:
+      #   . -- 1 warning:
+      #     "root: CLAUDE.md at the plugin root is not loaded as project context. To ship context with your plugin, use a skill (skills/<name>/SKILL.md) instead."
+      - name: Validate plugin schema (claude plugin validate)
+        run: |
+          npm install -g @anthropic-ai/claude-code@2.1.175
+          bun run plugin:validate
+
+      - name: Run tests
+        run: bun test

.github/workflows/release-pr.yml

@@ -0,0 +1,55 @@
+name: Release PR
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+concurrency:
+  group: release-pr-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  release-pr:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Detect release PR merge
+        id: detect
+        run: |
+          MSG=$(git log -1 --format=%s)
+          if [[ "$MSG" == chore:\ release* ]]; then
+            echo "is_release_merge=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "is_release_merge=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Validate release metadata scripts
+        if: steps.detect.outputs.is_release_merge == 'false'
+        run: bun run release:validate
+
+      - name: Maintain release PR
+        id: release
+        uses: googleapis/release-please-action@v4.4.0
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          config-file: .github/release-please-config.json
+          manifest-file: .github/.release-please-manifest.json
+          skip-labeling: false

.github/workflows/release-preview.yml

@@ -0,0 +1,87 @@
+name: Release Preview
+
+on:
+  workflow_dispatch:
+    inputs:
+      title:
+        description: "Conventional title to evaluate (defaults to the latest commit title on this ref)"
+        required: false
+        type: string
+      compound_engineering_bump:
+        description: "compound-engineering bump override"
+        required: false
+        type: choice
+        options: [auto, patch, minor, major]
+        default: auto
+      marketplace_bump:
+        description: "marketplace bump override"
+        required: false
+        type: choice
+        options: [auto, patch, minor, major]
+        default: auto
+      cursor_marketplace_bump:
+        description: "cursor-marketplace bump override"
+        required: false
+        type: choice
+        options: [auto, patch, minor, major]
+        default: auto
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Determine title and changed files
+        id: inputs
+        shell: bash
+        run: |
+          TITLE="${{ github.event.inputs.title }}"
+          if [ -z "$TITLE" ]; then
+            TITLE="$(git log -1 --pretty=%s)"
+          fi
+
+          FILES="$(git diff --name-only HEAD~1...HEAD | tr '\n' ' ')"
+
+          echo "title=$TITLE" >> "$GITHUB_OUTPUT"
+          echo "files=$FILES" >> "$GITHUB_OUTPUT"
+
+      - name: Add preview note
+        run: |
+          echo "This preview currently evaluates the selected ref from its latest commit title and changed files." >> "$GITHUB_STEP_SUMMARY"
+          echo "It is side-effect free, but it does not yet reconstruct the full accumulated open release PR state." >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Validate release metadata
+        run: bun run release:validate
+
+      - name: Preview release
+        shell: bash
+        run: |
+          TITLE='${{ steps.inputs.outputs.title }}'
+          FILES='${{ steps.inputs.outputs.files }}'
+
+          args=(--title "$TITLE" --json)
+          for file in $FILES; do
+            args+=(--file "$file")
+          done
+
+          args+=(--override "compound-engineering=${{ github.event.inputs.compound_engineering_bump || 'auto' }}")
+          args+=(--override "marketplace=${{ github.event.inputs.marketplace_bump || 'auto' }}")
+          args+=(--override "cursor-marketplace=${{ github.event.inputs.cursor_marketplace_bump || 'auto' }}")
+
+          bun run scripts/release/preview.ts "${args[@]}" | tee /tmp/release-preview.txt
+
+      - name: Publish preview summary
+        shell: bash
+        run: cat /tmp/release-preview.txt >> "$GITHUB_STEP_SUMMARY"

.gitignore

@@ -0,0 +1,12 @@
+.DS_Store
+*.log
+node_modules/
+.codex/
+todos/
+.worktrees
+.context/
+.claude/worktrees/
+__pycache__/
+*.pyc
+
+.compound-engineering/*.local.yaml

.grok-plugin/marketplace.json

@@ -0,0 +1,25 @@
+{
+  "name": "compound-engineering",
+  "description": "Compound Engineering plugin for Grok Build",
+  "owner": {
+    "name": "Kieran Klaassen and Trevin Chow"
+  },
+  "plugins": [
+    {
+      "name": "compound-engineering",
+      "description": "Brainstorm, plan, debug, review, and compound learnings with AI agents",
+      "category": "development",
+      "source": {
+        "source": "url",
+        "url": "https://github.com/EveryInc/compound-engineering-plugin.git"
+      },
+      "homepage": "https://github.com/EveryInc/compound-engineering-plugin",
+      "keywords": [
+        "compound-engineering",
+        "compound engineering",
+        "ce-plan",
+        "ce-work"
+      ]
+    }
+  ]
+}

.grok-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "compound-engineering",
+  "version": "3.19.0",
+  "description": "Brainstorm, plan, debug, review, and compound learnings with AI agents",
+  "author": {
+    "name": "Kieran Klaassen and Trevin Chow"
+  },
+  "homepage": "https://every.to/source-code/my-ai-had-already-fixed-the-code-before-i-saw-it",
+  "repository": "https://github.com/EveryInc/compound-engineering-plugin",
+  "license": "MIT",
+  "keywords": [
+    "brainstorming",
+    "code-review",
+    "compound-engineering",
+    "debugging",
+    "ideation",
+    "workflows",
+    "workflow-automation"
+  ],
+  "skills": "./skills/"
+}

.kimi-plugin/marketplace.json

@@ -0,0 +1,10 @@
+{
+  "version": "2",
+  "plugins": [
+    {
+      "id": "compound-engineering",
+      "displayName": "Compound Engineering",
+      "source": "https://github.com/EveryInc/compound-engineering-plugin"
+    }
+  ]
+}

.kimi-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "compound-engineering",
+  "version": "3.19.0",
+  "description": "Brainstorm, plan, debug, review, and compound learnings with AI agents",
+  "keywords": [
+    "brainstorming",
+    "code-review",
+    "compound-engineering",
+    "debugging",
+    "ideation",
+    "workflows",
+    "workflow-automation"
+  ],
+  "author": "Kieran Klaassen and Trevin Chow",
+  "homepage": "https://every.to/source-code/my-ai-had-already-fixed-the-code-before-i-saw-it",
+  "license": "MIT",
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Compound Engineering",
+    "shortDescription": "Brainstorm, plan, debug, review, and compound learnings with AI agents",
+    "longDescription": "Compound Engineering guides AI agents through the full engineering loop: strategy, ideation, requirements, planning, execution, debugging, review, PR feedback, and captured learnings that make future work easier.",
+    "developerName": "Kieran Klaassen and Trevin Chow",
+    "websiteURL": "https://github.com/EveryInc/compound-engineering-plugin"
+  }
+}

.opencode/INSTALL.md

@@ -0,0 +1,31 @@
+# Installing Compound Engineering for OpenCode
+
+Add Compound Engineering to the `plugin` array in your global or project `opencode.json`:
+
+```json
+{
+  "plugin": ["compound-engineering@git+https://github.com/EveryInc/compound-engineering-plugin.git"]
+}
+```
+
+Restart OpenCode after changing the config. The OpenCode plugin registers the Compound Engineering skills directory directly; no Bun installer or generated skill copy is required.
+
+To pin a release, add a tag. Replace `X.Y.Z` with the release you want — see the [releases page](https://github.com/EveryInc/compound-engineering-plugin/releases) for available tags:
+
+```json
+{
+  "plugin": ["compound-engineering@git+https://github.com/EveryInc/compound-engineering-plugin.git#compound-engineering-vX.Y.Z"]
+}
+```
+
+## Local Development
+
+From this checkout, point OpenCode at the package path:
+
+```json
+{
+  "plugin": ["/path/to/compound-engineering-plugin"]
+}
+```
+
+Restart OpenCode after changing the package source.

.opencode/plugins/compound-engineering.js

@@ -0,0 +1,17 @@
+import path from "path"
+import { fileURLToPath } from "url"
+
+const pluginDir = path.dirname(fileURLToPath(import.meta.url))
+const skillsDir = path.resolve(pluginDir, "../../skills")
+
+export const CompoundEngineeringPlugin = async () => ({
+  config: async (config) => {
+    config.skills = config.skills || {}
+    config.skills.paths = config.skills.paths || []
+    if (!config.skills.paths.includes(skillsDir)) {
+      config.skills.paths.push(skillsDir)
+    }
+  },
+})
+
+export default CompoundEngineeringPlugin

.pi/extensions/compound-engineering.ts

@@ -0,0 +1,12 @@
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const extensionDir = dirname(fileURLToPath(import.meta.url))
+const packageRoot = resolve(extensionDir, "../..")
+const skillsDir = resolve(packageRoot, "skills")
+
+export default function compoundEngineeringPiExtension(pi: any) {
+  pi.on("resources_discover", async () => ({
+    skillPaths: [skillsDir],
+  }))
+}

AGENTS.md

@@ -0,0 +1,284 @@
+# Agent Instructions
+
+This repository is the root of the `compound-engineering` coding-agent plugin and the marketplace/catalog metadata used to distribute it.
+
+It also contains:
+- the Bun/TypeScript CLI that converts Claude Code plugins into other agent platform formats
+- shared release and metadata infrastructure for the CLI, marketplace, and plugin
+
+`AGENTS.md` is the canonical repo instruction file. Root `CLAUDE.md` exists only as a compatibility shim for tools and conversions that still look for it.
+
+## Quick Start
+
+```bash
+bun install
+bun test                  # full test suite
+bun run release:validate  # check plugin/marketplace consistency
+```
+
+## Working Agreement
+
+- **Branching:** Create a feature branch for any non-trivial change. If already on the correct branch for the task, keep using it; do not create additional branches or worktrees unless explicitly requested.
+- **Merge policy:** All changes to `main` go through pull requests. Direct pushes and direct merges are not allowed; branch protection on `main` enforces this by requiring the `test` status check to pass. The direct path bypasses `release:validate`, the test suite, and PR title validation — past direct merges have caused version drift requiring multi-PR recovery (see `docs/solutions/workflow/release-please-version-drift-recovery.md`).
+- **Safety:** Do not delete or overwrite user data. Avoid destructive commands.
+- **Testing:** Run `bun test` after changes that affect parsing, conversion, or output.
+- **Release versioning:** Releases are prepared by release automation, not normal feature PRs. The repo has one root plugin/package release component (`compound-engineering`) plus marketplace components (`marketplace`, `cursor-marketplace`). GitHub release PRs and GitHub Releases are the canonical release-notes surface for new releases; root `CHANGELOG.md` is only a pointer to that history. Use conventional titles such as `feat:` and `fix:` so release automation can classify change intent, but do not hand-bump release-owned versions or hand-author release notes in routine PRs.
+- **Output Paths:** Keep OpenCode output at `opencode.json` and `.opencode/{agents,skills,plugins}`. For OpenCode, commands go to `~/.config/opencode/commands/<name>.md`; `opencode.json` is deep-merged (never overwritten wholesale).
+- **Scratch Space:** Default to OS temp. Use `.context/` only when explicitly justified by the rules below.
+  - **Default: OS temp** — covers most scratch, including per-run throwaway AND cross-invocation reusable, regardless of whether a repo is present or whether other skills may read the files. A stable OS-temp prefix handles cross-skill and cross-invocation coordination equally well as an in-repo path; repo-adjacency is rarely the relevant property.
+    - **Per-run throwaway**: `mktemp -d -t <prefix>-XXXXXX` (OS handles cleanup). Use for files consumed once and discarded — captured screenshots, stitched GIFs, intermediate build outputs, recordings, delegation prompts/results, single-run checkpoints. The resulting path is opaque (on macOS it resolves under `$TMPDIR`/`/var/folders/...`) — that is appropriate for throwaway files users are not meant to access.
+    - **Cross-invocation reusable**: stable path `/tmp/compound-engineering/<skill-name>/<run-id>/` — **not** `mktemp -d` — so later invocations of the same skill can discover sibling run-ids. Use `/tmp` directly rather than `$TMPDIR` so paths stay accessible: `$TMPDIR` on macOS resolves to `/var/folders/64/.../T/`, which is hostile for users who want to inspect checkpoints, grep them, or copy them out. The per-user isolation `$TMPDIR` provides is not valuable for cross-invocation reusable scratch where users are the intended audience. Use for caches keyed by session, checkpoints meant to survive context compaction within a loose session, or any state where later runs of the same skill need to locate prior outputs.
+  - **Exception: `.context/`** — use only when the artifact is genuinely bound to the CWD repo AND meets at least one of:
+    - (a) **User-curated**: the user is expected to inspect, manipulate, or manually curate the artifact outside the skill (e.g., a per-repo TODO database, a per-spec optimization log that survives across sessions on the same checkout).
+    - (b) **Repo+branch-inseparable**: the artifact's meaning is inseparable from this specific repo or branch (e.g., branch-specific resume state that a user expects to pick up again in the same checkout).
+    - (c) **Path is core UX**: surfacing the artifact path back to the user is a core part of the skill's output and that path is easier to communicate as a repo-relative location than an OS-temp one.
+    Namespace under `.context/compound-engineering/<workflow-or-skill-name>/`, add a per-run subdirectory when concurrent runs are plausible, and decide cleanup behavior per the artifact's lifecycle (per-run scratch clears on success; user-curated state persists). "Shared between skills" is not by itself sufficient — OS temp handles that equally well.
+  - **Durable outputs** (plans, specs, learnings, docs, final deliverables) belong in `docs/` or another repo-tracked location, not in either scratch tier.
+  - **Cross-platform note:** `/tmp` is writable on macOS (symlink to `/private/tmp`), Linux, and WSL. `mktemp -d -t <prefix>-XXXXXX` also works on all three. Skills authored here assume Unix-like shells; native Windows is not a current target.
+- **Character encoding:**
+  - **Identifiers** (file names, agent names, command names): ASCII only -- converters and regex patterns depend on it.
+  - **Markdown tables:** Use pipe-delimited (`| col | col |`), never box-drawing characters.
+  - **Prose and skill content:** Unicode is fine (emoji, punctuation, etc.). Prefer ASCII arrows (`->`, `<-`) over Unicode arrows in code blocks and terminal examples.
+
+## Directory Layout
+
+```
+src/              CLI entry point, parsers, converters, target writers
+skills/           Compound Engineering plugin skills
+.claude-plugin/   Claude plugin manifest and marketplace catalog metadata
+.codex-plugin/    Codex plugin manifest
+.cursor-plugin/   Cursor plugin manifest and marketplace catalog metadata
+.opencode/        OpenCode package entrypoint and install docs
+.pi/              Pi extension entrypoint
+tests/            Converter, writer, and CLI tests + fixtures
+docs/             Requirements, plans, solutions, and target specs
+CONCEPTS.md       Shared domain vocabulary (glossary of project-specific terms)
+```
+
+## Repo Surfaces
+
+Changes in this repo may affect one or more of these surfaces:
+
+- root plugin content under `skills/`, `AGENTS.md`, `README.md`, and platform manifests
+- marketplace catalogs under `.claude-plugin/`, `.cursor-plugin/`, and `.agents/plugins/`
+- the converter/install CLI in `src/` and `package.json`
+
+Do not assume a repo change is "just CLI" or "just plugin" without checking which surface owns the affected files.
+
+## Plugin Maintenance
+
+When changing plugin content:
+
+- Update substantive docs like `README.md` when the plugin behavior, inventory, or usage changes.
+- When adding a user-facing skill, document it: create a `docs/skills/<skill-name>.md` page (purpose, novel mechanics, when to use, chain position — follow the shape of the existing pages) and add a catalog row under the right category in `docs/skills/README.md`, alongside the root `README.md` inventory row and the skill-count bump in `tests/release-metadata.test.ts`. Keep these in sync when a skill's purpose or inventory changes. This is convention, not yet validated by a test, so it is easy to miss — most skills have a page; the few that don't (e.g. `lfg`, `ce-dogfood-beta`) are the exception, not the rule.
+- Do not hand-bump release-owned versions in plugin or marketplace manifests.
+- Do not hand-add release entries to `CHANGELOG.md` or treat it as the canonical source for new releases.
+- Run `bun run release:validate` if agents, commands, skills, MCP servers, or release-owned descriptions/counts may have changed.
+- When removing a skill, agent, or command, add its name to both cleanup registries so stale flat-install artifacts are swept on upgrade:
+  - `STALE_SKILL_DIRS` / `STALE_AGENT_NAMES` / `STALE_PROMPT_FILES` in `src/utils/legacy-cleanup.ts`
+  - `EXTRA_LEGACY_ARTIFACTS_BY_PLUGIN["compound-engineering"]` in `src/data/plugin-legacy-artifacts.ts`
+
+Useful validation commands:
+
+```bash
+bun run release:validate
+cat .claude-plugin/marketplace.json | jq .
+cat .claude-plugin/plugin.json | jq .
+```
+
+## Runtime vs Authoring Context
+
+`AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` are authoring context for this source repository. Skills are installed into end-user environments, where they run against the user's local instruction files, not this repo's. Behavioral rules that must affect a skill at runtime belong in that skill's `SKILL.md` or files under its own `references/` directory.
+
+## Cross-Model Skill Authoring
+
+This repository authors each skill once and distributes it across multiple agent models and harnesses. Before creating, materially revising, or reviewing a skill or skill-local persona, read `docs/solutions/skill-design/portable-agent-skill-authoring.md`.
+
+That field guide is the canonical reasoning layer for outcome-first authoring, model and harness portability, protocol versus judgment, proportional authority, tool adapters, evidence-backed review, and targeted behavioral evaluation. It is not a template: apply only the sections relevant to the skill. The repository-specific rules elsewhere in this file supplement the guide and take precedence where they are more specific.
+
+### Skill Prose Admission Rules
+
+- Keep a line only when it states a falsifiable constraint, counters a known default tendency or observed shortcut, or supplies domain knowledge that materially changes a decision.
+- Do not keep vague effort or quality language such as "be thorough" or "produce high-quality work" as a standalone instruction. Replace it with an observable rule, or retain a targeted effort cue only when it counters a documented runtime tendency and has been evaluated there.
+- Do not append motivational rationale to a directive that already stands on its own.
+- Repeat an instruction only at a demonstrated drift point where placement changes whether it fires. Protect genuinely required always-loaded duplicates with a parity test.
+
+### Skill Loading Supplements
+
+- Keep every load-bearing action, route, and reference-load instruction inline at the point where it must fire (`docs/solutions/skill-design/post-menu-routing-belongs-inline.md`).
+- Do not inline a summary complete enough to suppress loading the authoritative reference.
+- Extract a block to `references/` when it is conditional or late-sequence and a meaningful share of the skill (~20%+). Replace it with a 1-3 line condition and backtick path.
+- Never use `@` for an extracted block; it inlines at load time and defeats extraction.
+
+## Referencing Project Conventions in Skills
+
+When a skill needs to discover a project convention at runtime — the issue tracker, coding standards, commit format, lint command, scope constraints, etc. — describe **what to look for in the agent's existing context**, not **which file to open**.
+
+**On the read path, do not name instruction files (`AGENTS.md` / `CLAUDE.md` / `GEMINI.md` / `.cursor/rules`).** Phrase it as "the project's active instructions and conventions already in your context." Three reasons:
+
+- **Redundant.** Every major harness auto-injects the project's root instruction file into context at session start (Claude Code loads `CLAUDE.md`, Codex `AGENTS.md`, Gemini `GEMINI.md`). Telling the agent to "read `AGENTS.md`" asks it to re-open content it already has.
+- **Brittle / not portable.** The filename differs per harness, and this plugin is authored once and converted to all of them. A hardcoded "read `AGENTS.md` (or `CLAUDE.md`)" silently finds nothing on a harness that uses a different name.
+- **Security smell.** Instructing an agent to go *read named instruction dotfiles* is the exact shape that prompt-injection defenses in some agent frameworks (e.g., Hermes) flag. Referencing context rather than filenames avoids tripping those guards.
+
+**Name a concrete file only where the skill must do something a context reference can't express:**
+
+- **Writing a convention back** (e.g., persisting `project_tracker: linear`) needs a target — name it minimally and as an example ("the project's root agent-instructions file, e.g., `AGENTS.md`; if it `@`-includes another, write to the substantive one").
+- **Reading content that is genuinely not auto-loaded** — a subdirectory-scoped instruction file governing the area being changed, an optional project doc like `STRATEGY.md` / `CONCEPTS.md` / `README.md`, or any file a *fresh subagent* (which does not inherit the parent's loaded instructions) must open to do its job. Auditing tools that must enumerate every standards file (e.g., `ce-code-review`'s project-standards reviewer globbing all `CLAUDE.md`/`AGENTS.md`) are a legitimate exception — they review the files, they don't re-read them for context.
+
+**Describe the capability, not the tool.** Pair this with naming the *category* of thing rather than a closed set: "the project's issue tracker (e.g., GitHub Issues, Linear, Jira)" and "whatever interface that tracker exposes (connector/MCP, documented API, or a documented CLI)" — never assume a specific CLI exists, and never treat a missing binary / env var / MCP server as proof the capability is unavailable.
+
+## Validating Agent and Skill Changes
+
+Behavioral changes to a plugin skill or skill-local persona (anything under `skills/`) need a different validation path than mechanical code changes, because of how Claude Code loads plugins.
+
+- **Use the `skill-creator` skill to test changes.** Skill-creator is purpose-built for this: it spawns a generic subagent and injects the agent or skill content into the subagent's prompt at dispatch time, so each run reads the current source from disk. Invoke `/skill-creator` and use its eval workflow rather than reaching for ad-hoc workarounds.
+
+- **Plugin agent and skill definitions both cache at session start.** Once a Claude Code session is open, dispatching a typed plugin agent runs the in-memory copy that was loaded when the session began. The same applies to skills: invoking a skill goes through the cached skill loader, so edits to skill scripts are also not tested via that path. File edits to either layer after session start do not propagate within the same session. Any iteration loop built around typed-agent dispatch or Skill-tool invocation in the same session is testing pre-edit content, not your changes.
+
+- **Do NOT edit `~/.claude/plugins/cache/` or `~/.claude/plugins/marketplaces/` to try to force a reload.** Those paths are user machine state, not repo-managed. Modifying them does not reliably bypass the in-session cache (it didn't, in observed behavior), risks being silently overwritten by plugin updates, and is the wrong layer to test from. The skill-creator pattern is the proper approach; if you genuinely need fresh-loaded behavior of the typed-agent dispatch path, restart the Claude Code session — but skill-creator is preferred for fast iteration.
+
+- **A version-matched cache is not automatically stale — confirm by content, not by version.** When this working tree is the local marketplace source, a session (re)start re-copies it into `~/.claude/plugins/cache/.../compound-engineering/<version>/` (a plain copy, no `.git`; `<version>` is the working tree's `.claude-plugin/plugin.json` version), so the loaded plugin can be identical to — and as current as — your edits. Do not assume the running copy is stale just because it lives under the cache path; equally, do not assume a matching `<version>` means it includes your latest change. Version match is necessary but not sufficient: edits within a release do not bump the version, so a matching segment proves only that the cache was built from this release, not that it captured your most recent edit. To know which copy is actually loaded, diff the specific cache file against the working-tree file — identical means the running plugin is your current edit and you can trust it; differing means the session predates the edit, so restart (or use skill-creator). Never infer "stale" or "current" from the version segment alone.
+
+- **Mechanical changes do not have this restriction.** Skill scripts (e.g., `extract-metadata.py`), parser logic, conversion code, and anything `bun test` exercises always run the current source. The caching issue only affects LLM-driven skill prose behavior dispatched through the plugin loader.
+
+## Coding Conventions
+
+- Prefer explicit mappings over implicit magic when converting between platforms.
+- Keep target-specific behavior in dedicated converters/writers instead of scattering conditionals across unrelated files.
+- Preserve stable output paths and merge semantics for installed targets; do not casually change generated file locations.
+- When adding or changing a target, update fixtures/tests alongside implementation rather than treating docs or examples as sufficient proof.
+
+## Commit Conventions
+
+- **Prefix is based on intent, not file type.** Use conventional prefixes (`feat:`, `fix:`, `docs:`, `refactor:`, etc.) but classify by what the change does, not the file extension. Files under `skills/` and plugin manifests are product code even though they are Markdown or JSON. Reserve `docs:` for files whose sole purpose is documentation (`README.md`, `docs/`, `CHANGELOG.md`).
+- **Type selection — classify by intent, not diff shape.** Where `fix:` and `feat:` could both seem to fit, default to `fix:`: a change that remedies broken or missing behavior is `fix:` even when implemented by adding code, and net additions do not turn a fix into a `feat:`. Reserve `feat:` for capabilities the user could not previously accomplish where nothing was broken. Other conventional types (`chore:`, `refactor:`, `docs:`, `perf:`, `test:`, `ci:`, `build:`, `style:`) remain primary when they describe the change more precisely than either. Heuristic: if a regression test you could write today would have failed *before* the change, it's `fix:`. The user may override this default for a specific change.
+- **Include a component scope.** The scope appears verbatim in the changelog. Pick the narrowest useful label: skill/agent name (`document-review`, `learnings-researcher`), CLI or marketplace area (`cli`, `marketplace`), or shared area when cross-cutting (`review`, `research`, `converters`). Never use `compound-engineering` — it's the entire plugin and tells the reader nothing. Omit scope only when no single label adds clarity.
+- **Never use `!` or a `BREAKING CHANGE:` footer without explicit user confirmation.** These markers trigger release-please's automatic major version bump — a decision the user may not want even when a change is technically breaking. If a change appears breaking, surface that to the user and let them decide whether to apply the marker.
+
+## Adding a New Target Provider
+
+Only add a provider when the target format is stable, documented, and has a clear mapping for tools/permissions/hooks. Use this checklist:
+
+1. **Define the target entry**
+   - Add a new handler in `src/targets/index.ts` with `implemented: false` until complete.
+   - Use a dedicated writer module (e.g., `src/targets/codex.ts`).
+
+2. **Define types and mapping**
+   - Add provider-specific types under `src/types/`.
+   - Implement conversion logic in `src/converters/` (from Claude → provider).
+   - Keep mappings explicit: tools, permissions, hooks/events, model naming.
+
+3. **Wire the CLI**
+   - Ensure `convert` and `install` support `--to <provider>` and `--also`.
+   - Keep behavior consistent with OpenCode (write to a clean provider root).
+
+4. **Tests (required)**
+   - Extend fixtures in `tests/fixtures/sample-plugin`.
+   - Add spec coverage for mappings in `tests/converter.test.ts`.
+   - Add a writer test for the new provider output tree.
+   - Add a CLI test for the provider (similar to `tests/cli.test.ts`).
+
+5. **Docs**
+   - Update README with the new `--to` option and output locations.
+
+## Specialist Prompt Assets in Skills
+
+The compound-engineering plugin no longer ships standalone agent definitions under `agents/`. When a skill needs a specialist persona, store it inside that skill directory, usually under `references/agents/` or `references/personas/`, and have the calling skill dispatch a generic subagent with that file's contents in the prompt.
+
+Internal prompt asset file names should be descriptive and unprefixed because they are not externally exposed agent names.
+
+Example:
+- `references/agents/learnings-researcher.md` (correct)
+- `references/agents/ce-learnings-researcher.md` (wrong for an internal prompt asset)
+
+These prompt assets must not include YAML frontmatter. Model selection, tool constraints, and dispatch policy belong in the calling skill's `SKILL.md`, not in the prompt asset.
+
+## File References in Skills
+
+Each skill directory is a self-contained unit. A SKILL.md file must only reference files within its own directory tree (e.g., `references/`, `assets/`, `scripts/`) using relative paths from the skill root. Never reference files outside the skill directory — whether by relative traversal or absolute path.
+
+Broken patterns:
+
+- `../other-skill/references/schema.yaml` — relative traversal into a sibling skill
+- `/home/user/compound-engineering-plugin/skills/other-skill/file.md` — absolute path to another skill
+- `~/.claude/plugins/cache/marketplace/compound-engineering/1.0.0/skills/other-skill/file.md` — absolute path to an installed plugin location
+
+Why this matters:
+
+- **Runtime resolution:** Skills execute from the user's working directory, not the skill directory. Cross-directory paths and absolute paths will not resolve as expected.
+- **Unpredictable install paths:** Plugins installed from the marketplace are cached at versioned paths. Absolute paths that worked in the source repo will not match the installed layout, and the version segment changes on every release.
+- **Converter portability:** The CLI copies each skill directory as an isolated unit when converting to other agent platforms. Cross-directory references break because sibling directories are not included in the copy.
+
+If two skills need the same supporting file, duplicate it into each skill's directory. Prefer small, self-contained reference files over shared dependencies.
+
+> **Note (March 2026):** This constraint reflects current Claude Code skill resolution behavior and known path-resolution bugs ([#11011](https://github.com/anthropics/claude-code/issues/11011), [#17741](https://github.com/anthropics/claude-code/issues/17741), [#12541](https://github.com/anthropics/claude-code/issues/12541)). If Anthropic introduces a shared-files mechanism or cross-skill imports in the future, this guidance should be revisited with supporting documentation.
+
+## Shared Repo-Grounding Profile Cache
+
+Repo-grounding skills (`ce-pov`, `ce-plan`, `ce-optimize`, `ce-ideate`, `ce-brainstorm`, `ce-code-review`, plus lighter consumers `ce-compound` — which still derives **and persists** on a miss — and `ce-debug`, which only opportunistically reads `conventions.testing` and never derives/persists) reuse one cached **question-agnostic project profile** (stack, deps, conventions, structure) instead of each re-deriving it. The profile is git-keyed and stored at `/tmp/compound-engineering/repo-profile/<root-sha>/<head-sha>.json`.
+
+The mechanism is three **byte-duplicated** assets per consuming skill (the plugin has no cross-skill import — see "File References in Skills"):
+
+- `references/repo-profile-cache.md` — the schema + protocol (authoritative; read it before wiring a new consumer).
+- `scripts/repo-profile-cache.py` — deterministic `get`/`put`, invoked via the `SKILL_DIR` anchor (never the legacy `${CLAUDE_SKILL_DIR}` guard).
+- `references/agents/repo-profiler.md` — the persona that derives the profile on a miss.
+
+Rules:
+
+- A consumer resolves the agnostic profile through the cache (`get` → HIT load / MISS derive-and-`put` / NO-CACHE derive-fresh), then runs **only its question-specific grounding fresh**. The cache is an optimization, never a correctness dependency, and must never let a stale profile change an output.
+- **Always re-globbed fresh, never cached:** the `docs/solutions/` enumeration and subdirectory-scoped instruction files. Caching them would risk serving a stale match (e.g. a just-written learning), and re-globbing is ~free.
+- **Adding a consumer:** drop byte-identical copies of the three assets into the skill, add its name to `CONSUMER_SKILLS` in `tests/repo-profile-cache-parity.test.ts`, and wire its grounding phase. The parity test guards *file* drift; the per-consumer `skill-creator` eval (agnostic-from-cache, question-specific-fresh) guards *integration* drift.
+- Any change to the schema or protocol must be edited in **all** copies (the parity test fails otherwise) and bump `PROFILE_SCHEMA_VERSION` in the helper so older cache entries invalidate. Renaming or moving a profile **field** additionally requires updating every consumer `SKILL.md` that reads a named field path (grep the consumers for it, e.g. `conventions.testing`, `vocabulary`) — those per-skill field reads are not byte-duplicated, so the parity test does not guard them.
+
+## Platform-Specific Variables in Skills
+
+This plugin is authored once and converted for multiple agent platforms (Claude Code, Codex, Gemini CLI, etc.). Do not use platform-specific environment variables or string substitutions (e.g., `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_SKILL_DIR}`, `${CLAUDE_SESSION_ID}`, `CODEX_SANDBOX`, `CODEX_SESSION_ID`) in skill content without a graceful fallback that works when the variable is unavailable or unresolved.
+
+How a bundled-file reference resolves depends on *who* resolves it and whether a shell is involved, so references fall into three tiers. Do not assume a bare `scripts/…` path behaves the same in all three.
+
+**Tier 1 — Read-time file references (relative, no anchor):** When skill *content* points the agent at a co-located file to read (e.g., "read `references/schema.yaml`"), use a relative path from the skill root. The skill loader resolves these against the skill's own directory on all major platforms — no variable prefix needed. This is the rule in *File References in Skills* above.
+
+**Tier 2 — Prose pointers to a bundled file the agent acts on (relative + a "from this skill's directory" cue):** When skill prose names a bundled file the agent will use but does *not* put it in an executed shell command (e.g., "drive the loop with `scripts/hitl-loop.template.sh`" or "generate the package with `scripts/review-package BASE HEAD`"), use a relative path plus an explicit "from this skill's directory" phrase. The cue tells the agent what to resolve against without the verbosity of an anchor.
+
+**Tier 3 — Executed shell commands (the `SKILL_DIR` anchor):** When skill content puts a bundled script in a command the agent runs through the Bash tool — a fenced ` ```bash ` block **or** an inline `bash …` / `python …` — anchor it to the skill dir. The Bash tool's working directory is the user's **project**, not the skill directory, on Claude Code, Codex, and Cursor alike, so a bare `bash scripts/my-script.sh` resolves to `<project>/scripts/…`. Relative paths here *often still work* — a capable agent resolves them against the skill dir it loaded (which is how the agentskills.io spec and other ecosystems ship them) — but that relies on the agent translating the path, and the failure mode is a fenced block copied **verbatim** into a Bash call, which runs literally and misses (`exit 127`; recovery is a wasted round-trip that weaker models / mid-tier subagents botch). Anchoring bakes the resolution into the command, so it is **deterministic**. Use the anchor for executed shell as the house default — a conservative choice, not a claim that bare relative *cannot* work (recurring bug class: #764 `ce-worktree`, #811 `ce-code-review`, #898 `ce-compound`):
+
+```
+# set inline in the SAME command (shell state does not persist between Bash calls):
+SKILL_DIR="<absolute path of the directory containing the SKILL.md you just read>";
+bash "$SKILL_DIR/scripts/my-script.sh" ARG
+```
+
+**Keep the trailing `;` on the assignment line.** Some hosts (observed on Codex) flatten a fenced multi-line block into a single line by replacing the newline with a space before executing it. Without the `;`, `SKILL_DIR="…"` + newline + `bash "$SKILL_DIR/…"` collapses to the env-var-prefix form `SKILL_DIR="…" bash "$SKILL_DIR/…"`, where the shell expands `$SKILL_DIR` *before* the prefix assignment takes effect — so it expands to empty and the script path becomes `/scripts/my-script.sh` (`No such file or directory`). The trailing `;` makes the assignment a complete statement that survives flattening; it is load-bearing, not a style choice, so do not remove it.
+
+An existence guard (`if [ -f "$SKILL_DIR/scripts/my-script.sh" ]; then … else echo "not found — re-check the SKILL.md path"; fi`) is optional — useful when there's a real fallback, but see the permission caveat below before guarding a pinned call.
+
+`SKILL_DIR` is a **model-filled** value, not a harness variable: every harness loads SKILL.md from a real absolute path the agent knows, so the skill instructs the agent to set `SKILL_DIR` to that directory. This works identically on Claude Code, Codex, and Cursor precisely because it depends on no host-specific variable — `SKILL_DIR`, `CLAUDE_SKILL_DIR`, `CODEX_SKILL_DIR`, `AGENT_SKILL_DIR` are **not** env vars on any of them, yet the script runs because the agent supplies the path. This is the production pattern used by widely-installed cross-host skills (e.g. `last30days`). Two constraints: (1) shell state does **not** persist between separate Bash-tool calls, so `SKILL_DIR` cannot be set once and reused — each invocation must carry the absolute path (set it inline in the same command). (2) A script that needs its *own* directory (to read a sibling file) derives it from `BASH_SOURCE`, not `SKILL_DIR`, since `SKILL_DIR` is the orchestrator's shell var and is not exported to the child process — see `skills/ce-code-review/scripts/cross-model-adversarial-review.sh` for the reference implementation. `last30days` adopted this anchor for its critical multi-host engine after a path-resolution regression; it is the right tool when a script must run *reliably*, which is why it is the tier-3 default — but tiers 1 and 2 deliberately stay lighter.
+
+**Avoid `${CLAUDE_SKILL_DIR}` here — in this cross-agent plugin it is a footgun, not a neutral alternative.** Every skill in this repo is authored once and installed across Claude Code, Codex, Cursor, and Gemini, and `${CLAUDE_SKILL_DIR}` is a Claude-Code-only SKILL.md *content* substitution (not an env var) that is **empty on every other host**. So a `${CLAUDE_SKILL_DIR}`-guarded call's `then` branch quietly never fires off-Claude — the **genuine silent skip** — and a Claude-only mechanism breaks on Codex/Cursor because the converter doesn't rewrite these paths and the native Codex install loads raw `SKILL.md` (no `ce_platforms` filtering). The model-filled `SKILL_DIR` anchor works on every host, so it is the right replacement wherever a `${CLAUDE_SKILL_DIR}`-guarded executed-shell call exists today (tier 3). Do not reach for `${CLAUDE_SKILL_DIR}` as a "portable" option — it isn't. Reach for it only for behavior that is genuinely Claude-Code-only and will *never* run on another harness — which, given this plugin's cross-host install model, is essentially never; treat any new use as a smell to justify or remove. (Existing guarded uses such as `ce-compound`'s `validate-frontmatter.py` survive off-Claude only via an inline `else` fallback and should migrate to the anchor.)
+
+So: a skill's *core* behavior **can** live in a bundled script across hosts — invoke it via the `SKILL_DIR`-from-read-path anchor. You no longer need to avoid bundled scripts for portability; anchor them instead. Read-time references (`references/*.md`) still resolve against the skill dir on all targets and need no anchor.
+
+**Permission caveat (Claude Code).** Claude Code's permission checker evaluates every subcommand of a compound command, and a bare `[ -f … ]` test is not pre-approved — so wrapping a pinned `bash "…sh"` call in an `if … then … fi` guard defeats a narrow `Bash(bash *…sh)` allow-rule and prompts on every run. If a bundled-script call must stay auto-approved via such a pin, keep it a single pinned command rather than guarding it inline. Note the model-filled `SKILL_DIR` anchor produces a *dynamic* absolute path that won't match a static `Bash(bash /…/scripts/x.sh)` pin regardless of guarding — so for the anchor, expect a one-time approval prompt per distinct command (or use a broader allow-rule); the static-pin trick mainly applies to the fixed `${CLAUDE_SKILL_DIR}` form.
+
+**Do not use `!` load-time pre-resolution in skills.** The `!`cmd`` SKILL.md syntax runs `cmd` at skill load and inlines its stdout, but it is banned here (enforced by `tests/skill-shell-safety.test.ts`) for two unfixable reasons: it runs **only on Claude Code** — on Codex, Cursor, Gemini, and Grok the line is inert literal text — and on Claude Code a command that exits **non-zero aborts skill load** with a user-facing error. Every real use was git context (`git rev-parse …`, `gh pr view …`) whose non-zero exit is a *normal* state (no PR yet, no `origin/HEAD`, detached HEAD, not a repo), so the ordinary case broke the skill. The POSIX guards that force exit 0 (`2>/dev/null || echo SENTINEL`) then fail to parse under Windows PowerShell 5.1, which broke skill load there instead (issue #1066). No single command string both exits 0 on the expected-failure states and parses under both POSIX sh and PowerShell, so the construct cannot be made safe.
+
+**Gather context at runtime instead.** Have the agent run one argv-style command per shell tool call (`git …`, `gh …`) — no `;`, `&&`, `||`, pipes, `$(…)`, or redirects — and interpret each exit status as control flow. This parses identically under POSIX sh and PowerShell because it is a single external-program invocation, and a non-zero exit becomes data the agent reads rather than a load-time abort. See `ce-commit` / `ce-commit-push-pr` for the pattern.
+
+**When a platform variable is unavoidable:** resolve it at runtime with a single shell tool call and include explicit fallback instructions, so the agent knows what to do if the value is empty, a literal command string, or an error — e.g. run `jq -r .version "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json"`; if it resolved to a semantic version use it, otherwise fall back to the versionless behavior. This applies equally to any platform's variables — a skill converted from Codex, Gemini, or any other platform will have the same problem if it assumes platform-only variables exist without a fallback.
+
+## Repository Docs Convention
+
+- **Plans** live in `docs/plans/` — unified plan artifacts. New `ce-brainstorm` outputs are requirements-only unified plans (`artifact_readiness: requirements-only`); `ce-plan` enriches them to implementation-ready plans (`artifact_readiness: implementation-ready`). Historical `docs/brainstorms/*-requirements.*` files remain readable legacy inputs and should not be migrated just because a new plan is created.
+- **Brainstorm evidence / legacy requirements** may live in `docs/brainstorms/` — historical requirements docs and specialized analysis artifacts such as `docs/brainstorms/riffrec-feedback/`. Do not treat this as the canonical output path for new `ce-brainstorm` artifacts.
+- **Solutions** live in `docs/solutions/` — documented solutions to past problems (bugs, best practices, workflow patterns), organized by category with YAML frontmatter (`module`, `tags`, `problem_type`). Relevant when implementing or debugging in documented areas.
+- **Specs** live in `docs/specs/` — target platform format specifications.
+
+### Solution categories (`docs/solutions/`)
+
+This repo builds a plugin *for* developers. Categorize solutions from the perspective of the end user (a developer using the plugin), not a contributor to this repo.
+
+- **`developer-experience/`** — Issues with contributing to *this repo*: local dev setup, shell aliases, test ergonomics, CI friction. If the fix only matters to someone with a checkout of this repo, it belongs here.
+- **`integrations/`** — Issues where plugin output doesn't work correctly on a target platform or OS. Cross-platform bugs, target writer output problems, and converter compatibility issues go here.
+- **`workflow/`**, **`skill-design/`** — Plugin skill and agent design patterns, workflow improvements.
+
+When in doubt: if the bug affects someone running `bun install compound-engineering` or `bun convert`, it's an integration or product issue, not developer-experience.

CHANGELOG.md

@@ -0,0 +1,727 @@
+# Changelog
+
+## [3.13.1](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.13.0...cli-v3.13.1) (2026-06-17)
+
+
+### Bug Fixes
+
+* **proof:** replace HITL review loop with one-way publish ([#957](https://github.com/EveryInc/compound-engineering-plugin/issues/957)) ([68dd787](https://github.com/EveryInc/compound-engineering-plugin/commit/68dd787f98c734f57f6e40f1e8a6e29cb8584719))
+
+## [3.13.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.12.0...cli-v3.13.0) (2026-06-15)
+
+
+### Features
+
+* **ce-code-review:** add thematic triage grouping ([#845](https://github.com/EveryInc/compound-engineering-plugin/issues/845)) ([8092abe](https://github.com/EveryInc/compound-engineering-plugin/commit/8092abead5ab04355f55fb5ccddedfffd28c8901))
+* **ce-ideate:** improve for Fable model ([#924](https://github.com/EveryInc/compound-engineering-plugin/issues/924)) ([622fbfa](https://github.com/EveryInc/compound-engineering-plugin/commit/622fbfa60de346101e3177af243c79430b189a42))
+
+
+### Bug Fixes
+
+* **ce-compound:** guard validate-frontmatter.py on non-Claude platforms ([#947](https://github.com/EveryInc/compound-engineering-plugin/issues/947)) ([5e6ecca](https://github.com/EveryInc/compound-engineering-plugin/commit/5e6eccabb10e46fb2c149d06f82c4f46299e44b5))
+* **ce-worktree:** replace bundled-script creator with a portable isolation guardrail ([#948](https://github.com/EveryInc/compound-engineering-plugin/issues/948)) ([3437de3](https://github.com/EveryInc/compound-engineering-plugin/commit/3437de3049ea975bceec2688940d696e16cc5f87))
+* **config-read:** read config via native tool, not $() pre-resolution ([#942](https://github.com/EveryInc/compound-engineering-plugin/issues/942)) ([0757e85](https://github.com/EveryInc/compound-engineering-plugin/commit/0757e859d21e860a1fc0424bfcbbb35a1e597771))
+* **release:** bump marketplace catalogs for coding-tutor removal ([#951](https://github.com/EveryInc/compound-engineering-plugin/issues/951)) ([d4cb8ee](https://github.com/EveryInc/compound-engineering-plugin/commit/d4cb8eec0db5dc279f1671d3c362022c7617f615))
+* **skills:** enforce content conventions in CI and fix violations ([#930](https://github.com/EveryInc/compound-engineering-plugin/issues/930)) ([c8e7d90](https://github.com/EveryInc/compound-engineering-plugin/commit/c8e7d908fa7e230dc8723639ea48498e3e499f3c))
+
+## [3.12.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.11.2...cli-v3.12.0) (2026-06-09)
+
+
+### Features
+
+* HTML-first ideation docs and a status-free plan model ([#921](https://github.com/EveryInc/compound-engineering-plugin/issues/921)) ([e74e298](https://github.com/EveryInc/compound-engineering-plugin/commit/e74e29864fbfa2f800fc3e08509e2966e4947f1e))
+
+## [3.11.2](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.11.1...cli-v3.11.2) (2026-06-06)
+
+
+### Miscellaneous Chores
+
+* **cli:** Synchronize compound-engineering versions
+
+## [3.11.1](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.11.0...cli-v3.11.1) (2026-06-05)
+
+
+### Miscellaneous Chores
+
+* **cli:** Synchronize compound-engineering versions
+
+## [3.11.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.10.0...cli-v3.11.0) (2026-06-04)
+
+
+### Bug Fixes
+
+* **ce-polish:** promote from beta to stable ([#880](https://github.com/EveryInc/compound-engineering-plugin/issues/880)) ([63b6b26](https://github.com/EveryInc/compound-engineering-plugin/commit/63b6b260c345ba70ce9d9a393eeedefb64e4e0a0))
+
+## [3.10.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.9.4...cli-v3.10.0) (2026-06-03)
+
+
+### Features
+
+* **skill:** introduce CONCEPTS.md as shared vocabulary substrate ([#838](https://github.com/EveryInc/compound-engineering-plugin/issues/838)) ([7c4bb16](https://github.com/EveryInc/compound-engineering-plugin/commit/7c4bb16123412d97ded593fc785d206ecb9684bc))
+
+## [3.9.4](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.9.3...cli-v3.9.4) (2026-05-31)
+
+
+### Miscellaneous Chores
+
+* **cli:** Synchronize compound-engineering versions
+
+## [3.9.3](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.9.2...cli-v3.9.3) (2026-05-28)
+
+
+### Miscellaneous Chores
+
+* **cli:** Synchronize compound-engineering versions
+
+## [3.9.2](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.9.1...cli-v3.9.2) (2026-05-27)
+
+
+### Miscellaneous Chores
+
+* **cli:** Synchronize compound-engineering versions
+
+## [3.9.1](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.9.0...cli-v3.9.1) (2026-05-27)
+
+
+### Miscellaneous Chores
+
+* **cli:** Synchronize compound-engineering versions
+
+## [3.9.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.8.4...cli-v3.9.0) (2026-05-26)
+
+
+### Features
+
+* **ce-plan,ce-brainstorm:** contract-driven sections + optional HTML output ([#826](https://github.com/EveryInc/compound-engineering-plugin/issues/826)) ([11e12e5](https://github.com/EveryInc/compound-engineering-plugin/commit/11e12e5739c6691a2020eb8b70a944587e7f265f))
+
+## [3.8.4](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.8.3...cli-v3.8.4) (2026-05-21)
+
+
+### Bug Fixes
+
+* **agents:** rename .agent.md to .md for VS Code Copilot tool access ([#846](https://github.com/EveryInc/compound-engineering-plugin/issues/846)) ([796bea7](https://github.com/EveryInc/compound-engineering-plugin/commit/796bea75b74f3b101b53f7cc1c108aece0979e6b))
+
+## [3.8.3](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.8.2...cli-v3.8.3) (2026-05-17)
+
+
+### Bug Fixes
+
+* **ce-coherence-reviewer:** remove Bash from tool allowlist ([#837](https://github.com/EveryInc/compound-engineering-plugin/issues/837)) ([82b8af4](https://github.com/EveryInc/compound-engineering-plugin/commit/82b8af415d9ca5577577fa80da0a6119fc8b661e))
+
+## [3.8.2](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.8.1...cli-v3.8.2) (2026-05-14)
+
+
+### Bug Fixes
+
+* **codex:** respect CODEX_HOME for profile installs ([#830](https://github.com/EveryInc/compound-engineering-plugin/issues/830)) ([a0a08a1](https://github.com/EveryInc/compound-engineering-plugin/commit/a0a08a17cb178655baeabe4045b5164b3a5cef58))
+
+## [3.8.1](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.8.0...cli-v3.8.1) (2026-05-11)
+
+
+### Bug Fixes
+
+* **ce-code-review:** replace resolve-base.sh with prose-driven base detection ([#815](https://github.com/EveryInc/compound-engineering-plugin/issues/815)) ([d090bde](https://github.com/EveryInc/compound-engineering-plugin/commit/d090bde0ff1bbc33ec3c3b2049cb4687e9d76532))
+
+## [3.8.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.7.3...cli-v3.8.0) (2026-05-10)
+
+
+### Miscellaneous Chores
+
+* **cli:** Synchronize compound-engineering versions
+
+## [3.7.3](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.7.2...cli-v3.7.3) (2026-05-08)
+
+
+### Bug Fixes
+
+* **ce-resolve-pr-feedback:** paginate GraphQL connections ([#807](https://github.com/EveryInc/compound-engineering-plugin/issues/807)) ([07a6d52](https://github.com/EveryInc/compound-engineering-plugin/commit/07a6d52879ed715e179ff11daaee47e02bc6ecc9))
+
+## [3.7.2](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.7.1...cli-v3.7.2) (2026-05-08)
+
+
+### Bug Fixes
+
+* **ce-sessions:** unblock session-history on Claude Code ([#800](https://github.com/EveryInc/compound-engineering-plugin/issues/800)) ([81710ef](https://github.com/EveryInc/compound-engineering-plugin/commit/81710efad5666831715a630b04554a35946afb1d))
+
+## [3.7.1](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.7.0...cli-v3.7.1) (2026-05-08)
+
+
+### Miscellaneous Chores
+
+* **cli:** Synchronize compound-engineering versions
+
+## [3.7.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.6.1...cli-v3.7.0) (2026-05-07)
+
+
+### Miscellaneous Chores
+
+* **cli:** Synchronize compound-engineering versions
+
+## [3.6.1](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.6.0...cli-v3.6.1) (2026-05-06)
+
+
+### Bug Fixes
+
+* **doc-review:** cut review noise on plans, scope personas to doc shape ([#780](https://github.com/EveryInc/compound-engineering-plugin/issues/780)) ([8349e75](https://github.com/EveryInc/compound-engineering-plugin/commit/8349e750b856d267b74fbbeb2fb135e4ff73eb91))
+
+## [3.6.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.5.0...cli-v3.6.0) (2026-05-05)
+
+
+### Features
+
+* convert hooks to .codex/hooks.json for Codex target ([#742](https://github.com/EveryInc/compound-engineering-plugin/issues/742)) ([60b66dd](https://github.com/EveryInc/compound-engineering-plugin/commit/60b66dd904c3a81e0a25dd3bc61e2d94d8837f86))
+
+
+### Bug Fixes
+
+* **ce-plan:** render Implementation Units as headings, not bulleted list items ([#766](https://github.com/EveryInc/compound-engineering-plugin/issues/766)) ([be2efd7](https://github.com/EveryInc/compound-engineering-plugin/commit/be2efd7d7605c483ea9f068c6190b81a9d68e942))
+* **ce-worktree:** resolve script path against skill dir, not user CWD ([#772](https://github.com/EveryInc/compound-engineering-plugin/issues/772)) ([4cc1ee6](https://github.com/EveryInc/compound-engineering-plugin/commit/4cc1ee6fe2a353cd0b8e7466ec27e9556b042ee3))
+
+## [3.5.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.4.2...cli-v3.5.0) (2026-05-04)
+
+
+### Features
+
+* **riffrec-feedback-analysis:** add Riffrec feedback skill with three-path routing ([#747](https://github.com/EveryInc/compound-engineering-plugin/issues/747)) ([dde9256](https://github.com/EveryInc/compound-engineering-plugin/commit/dde9256362db90606d052c662dc8f2f0ae6b620b))
+
+## [3.4.2](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.4.1...cli-v3.4.2) (2026-05-04)
+
+
+### Bug Fixes
+
+* **ce-code-review:** keep finding numbers stable ([#754](https://github.com/EveryInc/compound-engineering-plugin/issues/754)) ([e856756](https://github.com/EveryInc/compound-engineering-plugin/commit/e8567566b7ed779ea1964d6ffe97e8cb4ca79d73))
+* **ce-compound, ce-sessions:** remove bash parameter expansion from ! backtick  ([#752](https://github.com/EveryInc/compound-engineering-plugin/issues/752)) ([9539bf0](https://github.com/EveryInc/compound-engineering-plugin/commit/9539bf045deba099a20d306b2b118e3b019c633c))
+
+## [3.4.1](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.4.0...cli-v3.4.1) (2026-05-01)
+
+
+### Bug Fixes
+
+* **ce-setup:** detect codex global skills ([#739](https://github.com/EveryInc/compound-engineering-plugin/issues/739)) ([887db6b](https://github.com/EveryInc/compound-engineering-plugin/commit/887db6b2ade997a2723debc15b5baf34fcf52fb4))
+* **code-review:** grant Write to JSON-pipeline reviewer agents ([#741](https://github.com/EveryInc/compound-engineering-plugin/issues/741)) ([520a9eb](https://github.com/EveryInc/compound-engineering-plugin/commit/520a9ebea039f4f5d984cd7f31d8b8e60a9e0bc6))
+
+## [3.4.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.3.2...cli-v3.4.0) (2026-05-01)
+
+
+### Features
+
+* **ce-strategy,ce-product-pulse:** add PM skills for upstream anchor and outcome pulse ([#614](https://github.com/EveryInc/compound-engineering-plugin/issues/614)) ([cb8f9b3](https://github.com/EveryInc/compound-engineering-plugin/commit/cb8f9b348391d28f31ce367b9ff308980939c96f))
+* **ce-strategy:** move strategy doc to root and add frontmatter ([#732](https://github.com/EveryInc/compound-engineering-plugin/issues/732)) ([265cb42](https://github.com/EveryInc/compound-engineering-plugin/commit/265cb4280f22bbd2fd5cc45e338371442b6c1692))
+
+
+### Bug Fixes
+
+* **ce-compound,ce-sessions:** handle non-git CWD in pre-resolved git branch ([#731](https://github.com/EveryInc/compound-engineering-plugin/issues/731)) ([5e04534](https://github.com/EveryInc/compound-engineering-plugin/commit/5e045341372fc95d284268d514a53da5722c81d2))
+* **ce-sessions:** 722 ce-compound and ce-sessions permission error ([#723](https://github.com/EveryInc/compound-engineering-plugin/issues/723)) ([8f80466](https://github.com/EveryInc/compound-engineering-plugin/commit/8f804669b184bc68ef6dbab4669fe0e431d8271a))
+* **review:** default to harness-native code review, escalate on risk ([#721](https://github.com/EveryInc/compound-engineering-plugin/issues/721)) ([d217660](https://github.com/EveryInc/compound-engineering-plugin/commit/d217660b3d37acf38227abf5c57ba6f390ccaa1e))
+
+## [3.3.2](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.3.1...cli-v3.3.2) (2026-04-29)
+
+
+### Miscellaneous Chores
+
+* **cli:** Synchronize compound-engineering versions
+
+## [3.3.1](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.3.0...cli-v3.3.1) (2026-04-28)
+
+
+### Bug Fixes
+
+* **review:** queue reviewers when subagent slots fill ([#716](https://github.com/EveryInc/compound-engineering-plugin/issues/716)) ([d69a772](https://github.com/EveryInc/compound-engineering-plugin/commit/d69a772bb8682da23fa0b6a293245768e573254b))
+
+## [3.3.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.2.0...cli-v3.3.0) (2026-04-28)
+
+
+### Bug Fixes
+
+* **ce-code-review:** restate model override at dispatch point ([#681](https://github.com/EveryInc/compound-engineering-plugin/issues/681)) ([9751d1a](https://github.com/EveryInc/compound-engineering-plugin/commit/9751d1a30a39fcfe17a9e052d32dbc9a5deafd02))
+* **ce-plan:** inline post-generation menu routing so option 1 actually starts /ce-work ([#715](https://github.com/EveryInc/compound-engineering-plugin/issues/715)) ([0c515c0](https://github.com/EveryInc/compound-engineering-plugin/commit/0c515c06fe7efc77baf29b5512a768c930d50ba0))
+* **ce-work-beta:** defer model and reasoning effort to Codex config ([#704](https://github.com/EveryInc/compound-engineering-plugin/issues/704)) ([4b5f28d](https://github.com/EveryInc/compound-engineering-plugin/commit/4b5f28da9746aae8f2c5dd715d7029d0ab2758a6))
+* **skills:** replace shell antipatterns blocked by permission check ([#711](https://github.com/EveryInc/compound-engineering-plugin/issues/711)) ([1f0a77b](https://github.com/EveryInc/compound-engineering-plugin/commit/1f0a77bcc1e4edbf1b7979ea5cd13d1e553d4662))
+
+## [3.2.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.1.0...cli-v3.2.0) (2026-04-26)
+
+
+### Features
+
+* **ce-compound:** add frontmatter parser-safety validator ([#697](https://github.com/EveryInc/compound-engineering-plugin/issues/697)) ([7eea2d1](https://github.com/EveryInc/compound-engineering-plugin/commit/7eea2d1cfe5c177e2d144b1e12f4957c75dac556))
+
+
+### Bug Fixes
+
+* **ce-code-review:** move run artifacts from .context/ to /tmp per AGENTS.md ([#690](https://github.com/EveryInc/compound-engineering-plugin/issues/690)) ([85e9a20](https://github.com/EveryInc/compound-engineering-plugin/commit/85e9a2073b09295b1a0771d4775d42b7142fd172))
+* **ce-code-review:** replace LFG with best-judgment auto-resolve ([#685](https://github.com/EveryInc/compound-engineering-plugin/issues/685)) ([9ba41a1](https://github.com/EveryInc/compound-engineering-plugin/commit/9ba41a14cadfe2eee75fe50485f72f38b09df00b))
+* **ce-code-review:** tighten autofix_class rubric for safe_auto/gated_auto boundary ([#695](https://github.com/EveryInc/compound-engineering-plugin/issues/695)) ([ad9577e](https://github.com/EveryInc/compound-engineering-plugin/commit/ad9577e7329cba31cffba71815cac6cef290ae1b))
+* **ce-debug:** delegate commit/PR and add branch check ([#683](https://github.com/EveryInc/compound-engineering-plugin/issues/683)) ([1284290](https://github.com/EveryInc/compound-engineering-plugin/commit/1284290af27139c2df192488099626688fd4898b))
+* **ce-demo-reel:** wait for network idle and reject blank frames ([#692](https://github.com/EveryInc/compound-engineering-plugin/issues/692)) ([f30404e](https://github.com/EveryInc/compound-engineering-plugin/commit/f30404e57bcbf7866c1a9524f4392f7dff8f3a0b))
+* **ce-doc-review:** rename LFG path to best-judgment to avoid /lfg collision ([#691](https://github.com/EveryInc/compound-engineering-plugin/issues/691)) ([50bf65e](https://github.com/EveryInc/compound-engineering-plugin/commit/50bf65e88c556eaa1ae10c7d88d8e646274d7ae0))
+* **session-historian:** cap deep-dives, add keyword filter primitive, tighten dispatch ([#699](https://github.com/EveryInc/compound-engineering-plugin/issues/699)) ([a91270c](https://github.com/EveryInc/compound-engineering-plugin/commit/a91270ccd2d5fba3e035275b7af2c4fec3f90b1c))
+* **skills:** replace case statements blocked by permission check ([#701](https://github.com/EveryInc/compound-engineering-plugin/issues/701)) ([5952b20](https://github.com/EveryInc/compound-engineering-plugin/commit/5952b20d7f2a056f8d7d8719a2d20b6615aca9e4))
+
+## [3.1.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.0.7...cli-v3.1.0) (2026-04-24)
+
+
+### Features
+
+* **ce-ideate:** subject gate, surprise-me, and warrant contract ([#671](https://github.com/EveryInc/compound-engineering-plugin/issues/671)) ([6514b1f](https://github.com/EveryInc/compound-engineering-plugin/commit/6514b1fce5df62582673fe7274c97a90e9aea45c))
+* **ce-setup:** check for ast-grep CLI and agent skill ([#653](https://github.com/EveryInc/compound-engineering-plugin/issues/653)) ([23dc11b](https://github.com/EveryInc/compound-engineering-plugin/commit/23dc11b95ae46dc6be0308306de5c8f16329fe49))
+* **codex:** native plugin install manifests + agents-only converter ([#616](https://github.com/EveryInc/compound-engineering-plugin/issues/616)) ([3ed4a4f](https://github.com/EveryInc/compound-engineering-plugin/commit/3ed4a4fa0f6f4d08144ae7598af391b4f070b649))
+* **pi:** first-class support via pi-subagents + pi-ask-user ([#651](https://github.com/EveryInc/compound-engineering-plugin/issues/651)) ([7ddfbed](https://github.com/EveryInc/compound-engineering-plugin/commit/7ddfbed33b08e5ad0dc56a3ecc19adb9a10ebb2c))
+
+
+### Bug Fixes
+
+* **ce-update:** compare against main plugin.json, not release tags ([#660](https://github.com/EveryInc/compound-engineering-plugin/issues/660)) ([351d12e](https://github.com/EveryInc/compound-engineering-plugin/commit/351d12ec5b795bff4c5e633e9a64644f045340c6))
+* **ce-update:** derive cache dir from CLAUDE_PLUGIN_ROOT parent ([#645](https://github.com/EveryInc/compound-engineering-plugin/issues/645)) ([6155b9d](https://github.com/EveryInc/compound-engineering-plugin/commit/6155b9de3c2d60ca424386f2dfcb0dfa7668f2c1))
+* **lfg:** use platform-neutral skill references ([#642](https://github.com/EveryInc/compound-engineering-plugin/issues/642)) ([b104ce4](https://github.com/EveryInc/compound-engineering-plugin/commit/b104ce46bea4b1b9b0e9cfbdd9203dbc5a0aa510))
+* **main:** recover version drift, fix stale test, document learnings ([#678](https://github.com/EveryInc/compound-engineering-plugin/issues/678)) ([bc8ae1a](https://github.com/EveryInc/compound-engineering-plugin/commit/bc8ae1a6b5375f7fbb8120104b3222391da470bb))
+* **release:** remove stale release-as pin ([#674](https://github.com/EveryInc/compound-engineering-plugin/issues/674)) ([ab44d89](https://github.com/EveryInc/compound-engineering-plugin/commit/ab44d89b0b2b1f7dd57d9ce1604d42b0c11f6415))
+* **skills:** cap skill descriptions at harness limit ([#643](https://github.com/EveryInc/compound-engineering-plugin/issues/643)) ([13f95ba](https://github.com/EveryInc/compound-engineering-plugin/commit/13f95ba6392f86aa8dd9b4430b84f0b7523c6c89))
+
+## [3.0.3](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.0.2...cli-v3.0.3) (2026-04-24)
+
+
+### Bug Fixes
+
+* **release:** remove stale release-as pin ([#674](https://github.com/EveryInc/compound-engineering-plugin/issues/674)) ([ab44d89](https://github.com/EveryInc/compound-engineering-plugin/commit/ab44d89b0b2b1f7dd57d9ce1604d42b0c11f6415))
+
+## [3.0.2](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.0.1...cli-v3.0.2) (2026-04-24)
+
+
+### Features
+
+* **ce-ideate:** subject gate, surprise-me, and warrant contract ([#671](https://github.com/EveryInc/compound-engineering-plugin/issues/671)) ([6514b1f](https://github.com/EveryInc/compound-engineering-plugin/commit/6514b1fce5df62582673fe7274c97a90e9aea45c))
+
+
+### Bug Fixes
+
+* **ce-update:** compare against main plugin.json, not release tags ([#660](https://github.com/EveryInc/compound-engineering-plugin/issues/660)) ([351d12e](https://github.com/EveryInc/compound-engineering-plugin/commit/351d12ec5b795bff4c5e633e9a64644f045340c6))
+
+## [3.0.1](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v3.0.0...cli-v3.0.1) (2026-04-23)
+
+
+### Miscellaneous Chores
+
+* **cli:** Synchronize compound-engineering versions
+
+## [3.0.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.68.1...cli-v3.0.0) (2026-04-22)
+
+
+### ⚠ BREAKING CHANGES
+
+* **cli:** rename all skills and agents to consistent ce- prefix ([#503](https://github.com/EveryInc/compound-engineering-plugin/issues/503))
+
+### Features
+
+* **ce-review:** add per-finding judgment loop to Interactive mode ([#590](https://github.com/EveryInc/compound-engineering-plugin/issues/590)) ([27cbaf8](https://github.com/EveryInc/compound-engineering-plugin/commit/27cbaf8161af8aad3260b58d0d9de03d6180a66c))
+* **ce-setup:** check for ast-grep CLI and agent skill ([#653](https://github.com/EveryInc/compound-engineering-plugin/issues/653)) ([23dc11b](https://github.com/EveryInc/compound-engineering-plugin/commit/23dc11b95ae46dc6be0308306de5c8f16329fe49))
+* **codex:** native plugin install manifests + agents-only converter ([#616](https://github.com/EveryInc/compound-engineering-plugin/issues/616)) ([3ed4a4f](https://github.com/EveryInc/compound-engineering-plugin/commit/3ed4a4fa0f6f4d08144ae7598af391b4f070b649))
+* **doc-review, learnings-researcher:** tiers, chain grouping, rewrite ([#601](https://github.com/EveryInc/compound-engineering-plugin/issues/601)) ([c1f68d4](https://github.com/EveryInc/compound-engineering-plugin/commit/c1f68d4d55ebf6085eaa7c177bf5c2e7a2cfb62c))
+* **pi:** first-class support via pi-subagents + pi-ask-user ([#651](https://github.com/EveryInc/compound-engineering-plugin/issues/651)) ([7ddfbed](https://github.com/EveryInc/compound-engineering-plugin/commit/7ddfbed33b08e5ad0dc56a3ecc19adb9a10ebb2c))
+
+
+### Bug Fixes
+
+* **ce-compound:** quote YAML array items starting with reserved indicators ([#613](https://github.com/EveryInc/compound-engineering-plugin/issues/613)) ([d8436b9](https://github.com/EveryInc/compound-engineering-plugin/commit/d8436b9a3c5b5370e51ec168a251ccb45f0d826e))
+* **ce-release-notes:** backtick-wrap `<skill-name>` token in description ([#603](https://github.com/EveryInc/compound-engineering-plugin/issues/603)) ([2aee4d4](https://github.com/EveryInc/compound-engineering-plugin/commit/2aee4d42031892e7937640a003d11fad82420944))
+* **ce-update:** derive cache dir from CLAUDE_PLUGIN_ROOT parent ([#645](https://github.com/EveryInc/compound-engineering-plugin/issues/645)) ([6155b9d](https://github.com/EveryInc/compound-engineering-plugin/commit/6155b9de3c2d60ca424386f2dfcb0dfa7668f2c1))
+* **lfg:** use platform-neutral skill references ([#642](https://github.com/EveryInc/compound-engineering-plugin/issues/642)) ([b104ce4](https://github.com/EveryInc/compound-engineering-plugin/commit/b104ce46bea4b1b9b0e9cfbdd9203dbc5a0aa510))
+* **skills:** cap skill descriptions at harness limit ([#643](https://github.com/EveryInc/compound-engineering-plugin/issues/643)) ([13f95ba](https://github.com/EveryInc/compound-engineering-plugin/commit/13f95ba6392f86aa8dd9b4430b84f0b7523c6c89))
+
+
+### Code Refactoring
+
+* **cli:** rename all skills and agents to consistent ce- prefix ([#503](https://github.com/EveryInc/compound-engineering-plugin/issues/503)) ([5c0ec91](https://github.com/EveryInc/compound-engineering-plugin/commit/5c0ec9137a7350534e32db91e8bad66f02693716))
+
+## [2.68.1](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.68.0...cli-v2.68.1) (2026-04-18)
+
+
+### Miscellaneous Chores
+
+* **cli:** Synchronize compound-engineering versions
+
+## [2.68.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.67.0...cli-v2.68.0) (2026-04-17)
+
+
+### Features
+
+* **ce-ideate:** mode-aware v2 ideation ([#588](https://github.com/EveryInc/compound-engineering-plugin/issues/588)) ([12aaad3](https://github.com/EveryInc/compound-engineering-plugin/commit/12aaad31ebd17686db1a75d1d3575da79d1dad2b))
+* **ce-release-notes:** add skill for browsing plugin release history ([#589](https://github.com/EveryInc/compound-engineering-plugin/issues/589)) ([59dbaef](https://github.com/EveryInc/compound-engineering-plugin/commit/59dbaef37607354d103113f05c13b731eecbb690))
+
+## [2.67.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.66.1...cli-v2.67.0) (2026-04-17)
+
+
+### Features
+
+* **ce-polish-beta:** human-in-the-loop polish phase between /ce:review and merge ([#568](https://github.com/EveryInc/compound-engineering-plugin/issues/568)) ([070092d](https://github.com/EveryInc/compound-engineering-plugin/commit/070092d997bcc3306016e9258150d3071f017ef8))
+
+
+### Bug Fixes
+
+* **ce-plan, ce-brainstorm:** reliable interactive handoff menus ([#575](https://github.com/EveryInc/compound-engineering-plugin/issues/575)) ([3d96c0f](https://github.com/EveryInc/compound-engineering-plugin/commit/3d96c0f074faf56fcdc835a0332e0f475dc8425f))
+
+
+### Miscellaneous Chores
+
+* **claude-permissions-optimizer:** drop skill in favor of /less-permission-prompts ([#583](https://github.com/EveryInc/compound-engineering-plugin/issues/583)) ([729fa19](https://github.com/EveryInc/compound-engineering-plugin/commit/729fa191b60305d8f3761f6441d1d3d15c5f48aa))
+
+## [2.66.1](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.66.0...cli-v2.66.1) (2026-04-16)
+
+
+### Miscellaneous Chores
+
+* **cli:** Synchronize compound-engineering versions
+
+## [2.66.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.65.0...cli-v2.66.0) (2026-04-15)
+
+
+### Bug Fixes
+
+* **converters:** preserve Codex agent sidecar scripts ([#563](https://github.com/EveryInc/compound-engineering-plugin/issues/563)) ([ee8e402](https://github.com/EveryInc/compound-engineering-plugin/commit/ee8e4028972252620f0dbfdbe1240204d22e6ea1))
+* **converters:** preserve Codex config on no-MCP install ([#564](https://github.com/EveryInc/compound-engineering-plugin/issues/564)) ([ed778e6](https://github.com/EveryInc/compound-engineering-plugin/commit/ed778e62f1e0e8621df94e5d461b20833cff33e2))
+
+## [2.65.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.64.0...cli-v2.65.0) (2026-04-11)
+
+
+### Features
+
+* **ce-setup:** unified setup skill with dependency management and config bootstrapping ([#345](https://github.com/EveryInc/compound-engineering-plugin/issues/345)) ([354dbb7](https://github.com/EveryInc/compound-engineering-plugin/commit/354dbb75828f0152f4cbbb3b50ce4511fa6710c7))
+
+## [2.64.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.63.1...cli-v2.64.0) (2026-04-10)
+
+
+### Features
+
+* **ce-demo-reel:** add demo reel skill with Python capture pipeline ([#541](https://github.com/EveryInc/compound-engineering-plugin/issues/541)) ([b979143](https://github.com/EveryInc/compound-engineering-plugin/commit/b979143ad0460a985dd224e7f1858416d79551fb))
+* **ce-update:** add plugin version check skill and ce_platforms filtering ([#532](https://github.com/EveryInc/compound-engineering-plugin/issues/532)) ([d37f0ed](https://github.com/EveryInc/compound-engineering-plugin/commit/d37f0ed16f94aaec2a7b435a0aaa018de5631ed3))
+* **ce-work-beta:** add beta Codex delegation mode ([#476](https://github.com/EveryInc/compound-engineering-plugin/issues/476)) ([31b0686](https://github.com/EveryInc/compound-engineering-plugin/commit/31b0686c2e88808381560314f10ce276c86e11e2))
+* **ce-work:** reduce token usage by extracting late-sequence references ([#540](https://github.com/EveryInc/compound-engineering-plugin/issues/540)) ([bb59547](https://github.com/EveryInc/compound-engineering-plugin/commit/bb59547a2efdd4e7213c149f51abd9c9a17016dd))
+* **session-historian:** cross-platform session history agent and /ce-sessions skill ([#534](https://github.com/EveryInc/compound-engineering-plugin/issues/534)) ([3208ec7](https://github.com/EveryInc/compound-engineering-plugin/commit/3208ec71f8f2209abc76baf97e3967406755317d))
+
+
+### Bug Fixes
+
+* **openclaw:** use sync plugin registration ([#498](https://github.com/EveryInc/compound-engineering-plugin/issues/498)) ([2c05c43](https://github.com/EveryInc/compound-engineering-plugin/commit/2c05c43dc8b66ae37501e42a9747c07d82002185))
+
+## [2.63.1](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.63.0...cli-v2.63.1) (2026-04-07)
+
+
+### Miscellaneous Chores
+
+* **cli:** Synchronize compound-engineering versions
+
+## [2.63.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.62.1...cli-v2.63.0) (2026-04-06)
+
+
+### Miscellaneous Chores
+
+* **cli:** Synchronize compound-engineering versions
+
+## [2.62.1](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.62.0...cli-v2.62.1) (2026-04-05)
+
+
+### Bug Fixes
+
+* **ce-brainstorm:** reduce token cost by extracting late-sequence content ([#511](https://github.com/EveryInc/compound-engineering-plugin/issues/511)) ([bdeb793](https://github.com/EveryInc/compound-engineering-plugin/commit/bdeb7935fcdb147b73107177769c2e968463d93f))
+* **cli:** resolve repo-wide tsc --noEmit type errors ([#512](https://github.com/EveryInc/compound-engineering-plugin/issues/512)) ([3fa0c81](https://github.com/EveryInc/compound-engineering-plugin/commit/3fa0c815b286c9e11b28dc04c803529e73b79c1b))
+
+## [2.62.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.61.0...cli-v2.62.0) (2026-04-03)
+
+
+### Features
+
+* **ce-plan:** reduce token usage by extracting conditional references ([#489](https://github.com/EveryInc/compound-engineering-plugin/issues/489)) ([fd562a0](https://github.com/EveryInc/compound-engineering-plugin/commit/fd562a0d0255d203d40fd53bb10d03a284a3c0e5))
+
+
+### Bug Fixes
+
+* **converters:** OpenCode subagent model and FQ agent name resolution ([#483](https://github.com/EveryInc/compound-engineering-plugin/issues/483)) ([577db53](https://github.com/EveryInc/compound-engineering-plugin/commit/577db53a2d2e237e900ef2079817cfe63df2d725))
+* **converters:** remove invalid tools/infer from Copilot agent frontmatter ([#493](https://github.com/EveryInc/compound-engineering-plugin/issues/493)) ([6dcb4a3](https://github.com/EveryInc/compound-engineering-plugin/commit/6dcb4a3c553c94e95cb15b5af59aeb6693e6fd61))
+* **mcp:** remove bundled context7 MCP server ([#486](https://github.com/EveryInc/compound-engineering-plugin/issues/486)) ([afdd9d4](https://github.com/EveryInc/compound-engineering-plugin/commit/afdd9d44651f834b1eed0b20e401ffbef5c8cd41))
+
+## [2.61.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.60.0...cli-v2.61.0) (2026-04-01)
+
+
+### Features
+
+* **release:** document linked-versions policy ([#482](https://github.com/EveryInc/compound-engineering-plugin/issues/482)) ([96345ac](https://github.com/EveryInc/compound-engineering-plugin/commit/96345acf217333726af0dcfdaa24058a149365bb))
+* **skill-design:** document skill file isolation and platform variable constraints ([#469](https://github.com/EveryInc/compound-engineering-plugin/issues/469)) ([0294652](https://github.com/EveryInc/compound-engineering-plugin/commit/0294652395cb62d5569f73ebfea543cfe8b514d6))
+
+
+### Bug Fixes
+
+* **converters:** preserve user config when writing MCP servers ([#479](https://github.com/EveryInc/compound-engineering-plugin/issues/479)) ([c65a698](https://github.com/EveryInc/compound-engineering-plugin/commit/c65a698d932d02e5fb4a948db4d000e21ed6ba4f))
+
+## [2.60.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.59.0...cli-v2.60.0) (2026-03-31)
+
+
+### Features
+
+* **ce-brainstorm:** add conditional visual aids to requirements documents ([#437](https://github.com/EveryInc/compound-engineering-plugin/issues/437)) ([bd02ca7](https://github.com/EveryInc/compound-engineering-plugin/commit/bd02ca7df04cf2c1c6301de3774e99d283d3d3ca))
+* **ce-compound:** add discoverability check for docs/solutions/ in instruction files ([#456](https://github.com/EveryInc/compound-engineering-plugin/issues/456)) ([5ac8a2c](https://github.com/EveryInc/compound-engineering-plugin/commit/5ac8a2c2c8c258458307e476d6693cc387deb27e))
+* **ce-compound:** add track-based schema for bug vs knowledge learnings ([#445](https://github.com/EveryInc/compound-engineering-plugin/issues/445)) ([739109c](https://github.com/EveryInc/compound-engineering-plugin/commit/739109c03ccd45474331625f35730924d17f63ef))
+* **ce-plan:** add conditional visual aids to plan documents ([#440](https://github.com/EveryInc/compound-engineering-plugin/issues/440)) ([4c7f51f](https://github.com/EveryInc/compound-engineering-plugin/commit/4c7f51f35bae56dd9c9dc2653372910c39b8b504))
+* **ce-plan:** add interactive deepening mode for on-demand plan strengthening ([#443](https://github.com/EveryInc/compound-engineering-plugin/issues/443)) ([ca78057](https://github.com/EveryInc/compound-engineering-plugin/commit/ca78057241ec64f36c562e3720a388420bdb347f))
+* **ce-review:** enforce table format, require question tool, fix autofix_class calibration ([#454](https://github.com/EveryInc/compound-engineering-plugin/issues/454)) ([847ce3f](https://github.com/EveryInc/compound-engineering-plugin/commit/847ce3f156a5cdf75667d9802e95d68e6b3c53a4))
+* **ce-review:** improve signal-to-noise with confidence rubric, FP suppression, and intent verification ([#434](https://github.com/EveryInc/compound-engineering-plugin/issues/434)) ([03f5aa6](https://github.com/EveryInc/compound-engineering-plugin/commit/03f5aa65b098e2ab8e25670594e0f554ea3cafbe))
+* **ce-work:** suggest branch rename when worktree name is meaningless ([#451](https://github.com/EveryInc/compound-engineering-plugin/issues/451)) ([e872e15](https://github.com/EveryInc/compound-engineering-plugin/commit/e872e15efa5514dcfea84a1a9e276bad3290cbc3))
+* **cli-agent-readiness-reviewer:** add smart output defaults criterion ([#448](https://github.com/EveryInc/compound-engineering-plugin/issues/448)) ([a01a8aa](https://github.com/EveryInc/compound-engineering-plugin/commit/a01a8aa0d29474c031a5b403f4f9bfc42a23ad78))
+* **converters:** centralize model field normalization across targets ([#442](https://github.com/EveryInc/compound-engineering-plugin/issues/442)) ([f93d10c](https://github.com/EveryInc/compound-engineering-plugin/commit/f93d10cf60a61b13c7765198d69f7c4cfa268ed6))
+* **git-commit-push-pr:** add conditional visual aids to PR descriptions ([#444](https://github.com/EveryInc/compound-engineering-plugin/issues/444)) ([44e3e77](https://github.com/EveryInc/compound-engineering-plugin/commit/44e3e77dc039d31a86194b0254e4e92839d9d5e9))
+* **git-commit-push-pr:** precompute shield badge version via skill preprocessing ([#464](https://github.com/EveryInc/compound-engineering-plugin/issues/464)) ([6ca7aef](https://github.com/EveryInc/compound-engineering-plugin/commit/6ca7aef7f33ebdf29f579cb4342c209d2bd40aad))
+* **model:** add MiniMax provider prefix for cross-platform model normalization ([#463](https://github.com/EveryInc/compound-engineering-plugin/issues/463)) ([e372b43](https://github.com/EveryInc/compound-engineering-plugin/commit/e372b43d30378321ac815fe1ae101c1d5634d321))
+* **resolve-pr-feedback:** add gated feedback clustering to detect systemic issues ([#441](https://github.com/EveryInc/compound-engineering-plugin/issues/441)) ([a301a08](https://github.com/EveryInc/compound-engineering-plugin/commit/a301a082057494e122294f4e7c1c3f5f87103f35))
+* **skills:** clean up argument-hint across ce:* skills ([#436](https://github.com/EveryInc/compound-engineering-plugin/issues/436)) ([d2b24e0](https://github.com/EveryInc/compound-engineering-plugin/commit/d2b24e07f6f2fde11cac65258cb1e76927238b5d))
+* **test-xcode:** add triggering context to skill description ([#466](https://github.com/EveryInc/compound-engineering-plugin/issues/466)) ([87facd0](https://github.com/EveryInc/compound-engineering-plugin/commit/87facd05dac94603780d75acb9da381dd7c61f1b))
+* **testing:** close the testing gap in ce:work, ce:plan, and testing-reviewer ([#438](https://github.com/EveryInc/compound-engineering-plugin/issues/438)) ([35678b8](https://github.com/EveryInc/compound-engineering-plugin/commit/35678b8add6a603cf9939564bcd2df6b83338c52))
+
+
+### Bug Fixes
+
+* **ce-brainstorm:** distinguish verification from technical design in Phase 1.1 ([#465](https://github.com/EveryInc/compound-engineering-plugin/issues/465)) ([8ec31d7](https://github.com/EveryInc/compound-engineering-plugin/commit/8ec31d703fc9ed19bf6377da0a9a29da935b719d))
+* **ce-compound:** require question tool for "What's next?" prompt ([#460](https://github.com/EveryInc/compound-engineering-plugin/issues/460)) ([9bf3b07](https://github.com/EveryInc/compound-engineering-plugin/commit/9bf3b07185a4aeb6490116edec48599b736dc86f))
+* **ce-plan:** reinforce mandatory document-review after auto deepening ([#450](https://github.com/EveryInc/compound-engineering-plugin/issues/450)) ([42fa8c3](https://github.com/EveryInc/compound-engineering-plugin/commit/42fa8c3e084db464ee0e04673f7c38cd422b32d6))
+* **ce-plan:** route confidence-gate pass to document-review ([#462](https://github.com/EveryInc/compound-engineering-plugin/issues/462)) ([1962f54](https://github.com/EveryInc/compound-engineering-plugin/commit/1962f546b5e5288c7ce5d8658f942faf71651c81))
+* **ce-work:** make code review invocation mandatory by default ([#453](https://github.com/EveryInc/compound-engineering-plugin/issues/453)) ([7f3aba2](https://github.com/EveryInc/compound-engineering-plugin/commit/7f3aba29e84c3166de75438d554455a71f4f3c22))
+* **document-review:** show contextual next-step in Phase 5 menu ([#459](https://github.com/EveryInc/compound-engineering-plugin/issues/459)) ([2b7283d](https://github.com/EveryInc/compound-engineering-plugin/commit/2b7283da7b48dc073670c5f4d116e58255f0ffcb))
+* **git-commit-push-pr:** quiet expected no-pr gh exit ([#439](https://github.com/EveryInc/compound-engineering-plugin/issues/439)) ([1f49948](https://github.com/EveryInc/compound-engineering-plugin/commit/1f499482bc65456fa7dd0f73fb7f2fa58a4c5910))
+* **resolve-pr-feedback:** add actionability filter and lower cluster gate to 3+ ([#461](https://github.com/EveryInc/compound-engineering-plugin/issues/461)) ([2619ad9](https://github.com/EveryInc/compound-engineering-plugin/commit/2619ad9f58e6c45968ec10d7f8aa7849fe43eb25))
+* **review:** harden ce-review base resolution ([#452](https://github.com/EveryInc/compound-engineering-plugin/issues/452)) ([638b38a](https://github.com/EveryInc/compound-engineering-plugin/commit/638b38abd267d415ad2d6b72eba3dfe12beefad9))
+
+## [2.59.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.58.1...cli-v2.59.0) (2026-03-29)
+
+
+### Features
+
+* **ce-review:** add headless mode for programmatic callers ([#430](https://github.com/EveryInc/compound-engineering-plugin/issues/430)) ([3706a97](https://github.com/EveryInc/compound-engineering-plugin/commit/3706a9764b6e73b7a155771956646ddef73f04a5))
+* **ce-work:** accept bare prompts and add test discovery ([#423](https://github.com/EveryInc/compound-engineering-plugin/issues/423)) ([6dabae6](https://github.com/EveryInc/compound-engineering-plugin/commit/6dabae6683fb2c37dc47616f172835eacc105d11))
+* **document-review:** collapse batch_confirm tier into auto ([#432](https://github.com/EveryInc/compound-engineering-plugin/issues/432)) ([0f5715d](https://github.com/EveryInc/compound-engineering-plugin/commit/0f5715d562fffc626ddfde7bd0e1652143710a44))
+* **review:** make review mandatory across pipeline skills ([#433](https://github.com/EveryInc/compound-engineering-plugin/issues/433)) ([9caaf07](https://github.com/EveryInc/compound-engineering-plugin/commit/9caaf071d9b74fd938567542167768f6cdb7a56f))
+
+## [2.58.1](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.58.0...cli-v2.58.1) (2026-03-28)
+
+
+### Bug Fixes
+
+* **release:** align cli and compound-engineering versions with linked-versions plugin ([0bd29c7](https://github.com/EveryInc/compound-engineering-plugin/commit/0bd29c7f2e930fc1198cc7ae833394bfabd47c40))
+
+## [2.58.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.57.1...cli-v2.58.0) (2026-03-28)
+
+
+### Features
+
+* **document-review:** add headless mode for programmatic callers ([#425](https://github.com/EveryInc/compound-engineering-plugin/issues/425)) ([4e4a656](https://github.com/EveryInc/compound-engineering-plugin/commit/4e4a6563b4aa7375e9d1c54bd73442f3b675f100))
+
+## [2.57.1](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.57.0...cli-v2.57.1) (2026-03-28)
+
+
+### Bug Fixes
+
+* **onboarding:** resolve section count contradiction with skip rule ([#421](https://github.com/EveryInc/compound-engineering-plugin/issues/421)) ([d2436e7](https://github.com/EveryInc/compound-engineering-plugin/commit/d2436e7c933129784c67799a5b9555bccce2e46d))
+
+## [2.57.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.56.0...cli-v2.57.0) (2026-03-28)
+
+
+### Features
+
+* **ce-plan:** add decision matrix form, unchanged invariants, and risk table format ([#417](https://github.com/EveryInc/compound-engineering-plugin/issues/417)) ([ccb371e](https://github.com/EveryInc/compound-engineering-plugin/commit/ccb371e0b7917420f5ca2c58433f5fc057211f04))
+
+
+### Bug Fixes
+
+* **cli-agent-readiness-reviewer:** remove top-5 cap on improvements ([#419](https://github.com/EveryInc/compound-engineering-plugin/issues/419)) ([16eb8b6](https://github.com/EveryInc/compound-engineering-plugin/commit/16eb8b660790f8de820d0fba709316c7270703c1))
+* **document-review:** enforce interactive questions and fix autofix classification ([#415](https://github.com/EveryInc/compound-engineering-plugin/issues/415)) ([d447296](https://github.com/EveryInc/compound-engineering-plugin/commit/d44729603da0c73d4959c372fac0198125a39c60))
+
+## [2.56.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.55.0...cli-v2.56.0) (2026-03-27)
+
+
+### Features
+
+* add adversarial review agents for code and documents ([#403](https://github.com/EveryInc/compound-engineering-plugin/issues/403)) ([5e6cd5c](https://github.com/EveryInc/compound-engineering-plugin/commit/5e6cd5c90950588fb9b0bc3a5cbecba2a1387080))
+* add CLI agent-readiness reviewer and principles guide ([#391](https://github.com/EveryInc/compound-engineering-plugin/issues/391)) ([13aa3fa](https://github.com/EveryInc/compound-engineering-plugin/commit/13aa3fa8465dce6c037e1bb8982a2edad13f199a))
+* add project-standards-reviewer as always-on ce:review persona ([#402](https://github.com/EveryInc/compound-engineering-plugin/issues/402)) ([b30288c](https://github.com/EveryInc/compound-engineering-plugin/commit/b30288c44e500013afe30b34f744af57cae117db))
+* **ce-brainstorm:** group requirements by logical concern, tighten autofix classification ([#412](https://github.com/EveryInc/compound-engineering-plugin/issues/412)) ([90684c4](https://github.com/EveryInc/compound-engineering-plugin/commit/90684c4e8272b41c098ef2452c40d86d460ea578))
+* **ce-plan:** strengthen test scenario guidance across plan and work skills ([#410](https://github.com/EveryInc/compound-engineering-plugin/issues/410)) ([615ec5d](https://github.com/EveryInc/compound-engineering-plugin/commit/615ec5d3feb14785530bbfe2b4a50afe29ccbc47))
+* **ce-review:** add base: and plan: arguments, extract scope detection ([#405](https://github.com/EveryInc/compound-engineering-plugin/issues/405)) ([914f9b0](https://github.com/EveryInc/compound-engineering-plugin/commit/914f9b0d9822786d9ba6dc2307a543ae5a25c6e9))
+* **document-review:** smarter autofix, batch-confirm, and error/omission classification ([#401](https://github.com/EveryInc/compound-engineering-plugin/issues/401)) ([0863cfa](https://github.com/EveryInc/compound-engineering-plugin/commit/0863cfa4cbebcd121b0757abf374e5095d42f989))
+* **onboarding:** add consumer perspective and split architecture diagrams ([#413](https://github.com/EveryInc/compound-engineering-plugin/issues/413)) ([31326a5](https://github.com/EveryInc/compound-engineering-plugin/commit/31326a54584a12c473944fa488bea26410fd6fce))
+
+
+### Bug Fixes
+
+* add strict YAML validation for plugin frontmatter ([#399](https://github.com/EveryInc/compound-engineering-plugin/issues/399)) ([0877b69](https://github.com/EveryInc/compound-engineering-plugin/commit/0877b693ced341cec699ea959dc39f8bd78f33ef))
+* clarify commit prefix selection for markdown product code ([#407](https://github.com/EveryInc/compound-engineering-plugin/issues/407)) ([4a60ee2](https://github.com/EveryInc/compound-engineering-plugin/commit/4a60ee23b77c942111f3935d325ca5c80424ceb2))
+* consolidate compound-docs into ce-compound skill ([#390](https://github.com/EveryInc/compound-engineering-plugin/issues/390)) ([daddb7d](https://github.com/EveryInc/compound-engineering-plugin/commit/daddb7d72f280a3bd9645c54d091844c198a324d))
+* consolidate local dev README and fix shell aliases ([#396](https://github.com/EveryInc/compound-engineering-plugin/issues/396)) ([1bd63c2](https://github.com/EveryInc/compound-engineering-plugin/commit/1bd63c2c8931b63bcafe960ea6353372ea85512a))
+* document SwiftUI Text link tap limitation in test-xcode skill ([#400](https://github.com/EveryInc/compound-engineering-plugin/issues/400)) ([6ddaec3](https://github.com/EveryInc/compound-engineering-plugin/commit/6ddaec3b6ed5b6a91aeaddadff3960714ef10dc1))
+* harden git workflow skills with better state handling ([#406](https://github.com/EveryInc/compound-engineering-plugin/issues/406)) ([f83305e](https://github.com/EveryInc/compound-engineering-plugin/commit/f83305e22af09c37f452cf723c1b08bb0e7c8bdf))
+* improve agent-native-reviewer with triage, prioritization, and stack-aware search ([#387](https://github.com/EveryInc/compound-engineering-plugin/issues/387)) ([e792166](https://github.com/EveryInc/compound-engineering-plugin/commit/e7921660ad42db8e9af56ec36f36ce8d1af13238))
+* replace broken markdown link refs in skills ([#392](https://github.com/EveryInc/compound-engineering-plugin/issues/392)) ([506ad01](https://github.com/EveryInc/compound-engineering-plugin/commit/506ad01b4f056b0d8d0d440bfb7821f050aba156))
+* sanitize colons in skill/agent names for Windows path compatibility ([#398](https://github.com/EveryInc/compound-engineering-plugin/issues/398)) ([b25480a](https://github.com/EveryInc/compound-engineering-plugin/commit/b25480af9eb1e69efa2fe30a8e7048f4c6aaa53c))
+
+## [2.55.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.54.0...cli-v2.55.0) (2026-03-26)
+
+
+### Features
+
+* add branch-based plugin install for worktree workflows ([#395](https://github.com/EveryInc/compound-engineering-plugin/issues/395)) ([e09a742](https://github.com/EveryInc/compound-engineering-plugin/commit/e09a7426be6ba1cd86122e7519abfe3376849ade))
+
+
+### Bug Fixes
+
+* prevent orphaned opening paragraphs in PR descriptions ([#393](https://github.com/EveryInc/compound-engineering-plugin/issues/393)) ([4b44a94](https://github.com/EveryInc/compound-engineering-plugin/commit/4b44a94e23c8621771b8813caebce78060a61611))
+
+## [2.54.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.53.0...cli-v2.54.0) (2026-03-26)
+
+
+### Features
+
+* add new `onboarding` skill to create onboarding guide for repo ([#384](https://github.com/EveryInc/compound-engineering-plugin/issues/384)) ([27b9831](https://github.com/EveryInc/compound-engineering-plugin/commit/27b9831084d69c4c8cf13d0a45c901268420de59))
+* replace manual review agent config with ce:review delegation ([#381](https://github.com/EveryInc/compound-engineering-plugin/issues/381)) ([fed9fd6](https://github.com/EveryInc/compound-engineering-plugin/commit/fed9fd68db283c64ec11293f88a8ad7a6373e2fe))
+
+
+### Bug Fixes
+
+* add default-branch guard to commit skills ([#386](https://github.com/EveryInc/compound-engineering-plugin/issues/386)) ([31f07c0](https://github.com/EveryInc/compound-engineering-plugin/commit/31f07c00473e9d8bd6d447cf04081c0a9631e34a))
+* one-step codex installs by preferring bundled plugins ([#383](https://github.com/EveryInc/compound-engineering-plugin/issues/383)) ([f819e43](https://github.com/EveryInc/compound-engineering-plugin/commit/f819e435a54f5d7df558df5a6bee1e616a5da837))
+* scope commit-push-pr descriptions to full branch diff ([#385](https://github.com/EveryInc/compound-engineering-plugin/issues/385)) ([355e739](https://github.com/EveryInc/compound-engineering-plugin/commit/355e7392b21a28c8725f87a8f9c473a86543ce4a))
+
+## [2.53.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.52.0...cli-v2.53.0) (2026-03-25)
+
+
+### Features
+
+* add git commit and branch helper skills ([#378](https://github.com/EveryInc/compound-engineering-plugin/issues/378)) ([fe08af2](https://github.com/EveryInc/compound-engineering-plugin/commit/fe08af2b417b707b6d3192a954af7ff2ab0fe667))
+* improve `resolve-pr-feedback` skill ([#379](https://github.com/EveryInc/compound-engineering-plugin/issues/379)) ([2ba4f3f](https://github.com/EveryInc/compound-engineering-plugin/commit/2ba4f3fd58d4e57dfc6c314c2992c18ba1fb164b))
+* improve commit-push-pr skill with net-result focus and badging ([#380](https://github.com/EveryInc/compound-engineering-plugin/issues/380)) ([efa798c](https://github.com/EveryInc/compound-engineering-plugin/commit/efa798c52cb9d62e9ef32283227a8df68278ff3a))
+* integrate orphaned stack-specific reviewers into ce:review ([#375](https://github.com/EveryInc/compound-engineering-plugin/issues/375)) ([ce9016f](https://github.com/EveryInc/compound-engineering-plugin/commit/ce9016fac5fde9a52753cf94a4903088f05aeece))
+
+
+### Bug Fixes
+
+* guard CONTEXTUAL_RISK_FLAGS lookup against prototype pollution ([#377](https://github.com/EveryInc/compound-engineering-plugin/issues/377)) ([8ebc77b](https://github.com/EveryInc/compound-engineering-plugin/commit/8ebc77b8e6c71e5bef40fcded9131c4457a387d7))
+
+## [2.52.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.51.0...cli-v2.52.0) (2026-03-25)
+
+
+### Features
+
+* add consolidation support and overlap detection to `ce:compound` and `ce:compound-refresh` skills ([#372](https://github.com/EveryInc/compound-engineering-plugin/issues/372)) ([fe27f85](https://github.com/EveryInc/compound-engineering-plugin/commit/fe27f85810268a8e713ef2c921f0aec1baf771d7))
+* minimal config for conductor support ([#373](https://github.com/EveryInc/compound-engineering-plugin/issues/373)) ([aad31ad](https://github.com/EveryInc/compound-engineering-plugin/commit/aad31adcd3d528581e8b00e78943b21fbe2c47e8))
+* optimize `ce:compound` speed and effectiveness ([#370](https://github.com/EveryInc/compound-engineering-plugin/issues/370)) ([4e3af07](https://github.com/EveryInc/compound-engineering-plugin/commit/4e3af079623ae678b9a79fab5d1726d78f242ec2))
+* promote `ce:review-beta` to stable `ce:review` ([#371](https://github.com/EveryInc/compound-engineering-plugin/issues/371)) ([7c5ff44](https://github.com/EveryInc/compound-engineering-plugin/commit/7c5ff445e3065fd13e00bcd57041f6c35b36f90b))
+* rationalize todo skill names and optimize skills ([#368](https://github.com/EveryInc/compound-engineering-plugin/issues/368)) ([2612ed6](https://github.com/EveryInc/compound-engineering-plugin/commit/2612ed6b3d86364c74dc024e4ce35dde63fefbf6))
+
+## [2.51.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.50.0...cli-v2.51.0) (2026-03-24)
+
+
+### Features
+
+* add `ce:review-beta` with structured persona pipeline ([#348](https://github.com/EveryInc/compound-engineering-plugin/issues/348)) ([e932276](https://github.com/EveryInc/compound-engineering-plugin/commit/e9322768664e194521894fe770b87c7dabbb8a22))
+* promote ce:plan-beta and deepen-plan-beta to stable ([#355](https://github.com/EveryInc/compound-engineering-plugin/issues/355)) ([169996a](https://github.com/EveryInc/compound-engineering-plugin/commit/169996a75e98a29db9e07b87b0911cc80270f732))
+* redesign `document-review` skill with persona-based review ([#359](https://github.com/EveryInc/compound-engineering-plugin/issues/359)) ([18d22af](https://github.com/EveryInc/compound-engineering-plugin/commit/18d22afde2ae08a50c94efe7493775bc97d9a45a))
+
+## [2.50.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.49.0...cli-v2.50.0) (2026-03-23)
+
+
+### Features
+
+* **ce-work:** add Codex delegation mode ([#328](https://github.com/EveryInc/compound-engineering-plugin/issues/328)) ([341c379](https://github.com/EveryInc/compound-engineering-plugin/commit/341c37916861c8bf413244de72f83b93b506575f))
+* improve `feature-video` skill with GitHub native video upload ([#344](https://github.com/EveryInc/compound-engineering-plugin/issues/344)) ([4aa50e1](https://github.com/EveryInc/compound-engineering-plugin/commit/4aa50e1bada07e90f36282accb3cd81134e706cd))
+* rewrite `frontend-design` skill with layered architecture and visual verification ([#343](https://github.com/EveryInc/compound-engineering-plugin/issues/343)) ([423e692](https://github.com/EveryInc/compound-engineering-plugin/commit/423e69272619e9e3c14750f5219cbf38684b6c96))
+
+
+### Bug Fixes
+
+* quote frontend-design skill description ([#353](https://github.com/EveryInc/compound-engineering-plugin/issues/353)) ([86342db](https://github.com/EveryInc/compound-engineering-plugin/commit/86342db36c0d09b65afe11241e095dda2ad2cdb0))
+
+## [2.49.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.48.0...cli-v2.49.0) (2026-03-22)
+
+
+### Features
+
+* add execution mode toggle and context pressure bounds to parallel skills ([#336](https://github.com/EveryInc/compound-engineering-plugin/issues/336)) ([216d6df](https://github.com/EveryInc/compound-engineering-plugin/commit/216d6dfb2c9320c3354f8c9f30e831fca74865cd))
+* fix skill transformation pipeline across all targets ([#334](https://github.com/EveryInc/compound-engineering-plugin/issues/334)) ([4087e1d](https://github.com/EveryInc/compound-engineering-plugin/commit/4087e1df82138f462a64542831224e2718afafa7))
+* improve reproduce-bug skill, sync agent-browser, clean up redundant skills ([#333](https://github.com/EveryInc/compound-engineering-plugin/issues/333)) ([affba1a](https://github.com/EveryInc/compound-engineering-plugin/commit/affba1a6a0d9320b529d429ad06fd5a3b5200bd8))
+
+
+### Bug Fixes
+
+* gitignore .context/ directory for Conductor ([#331](https://github.com/EveryInc/compound-engineering-plugin/issues/331)) ([0f6448d](https://github.com/EveryInc/compound-engineering-plugin/commit/0f6448d81cbc47e66004b4ecb8fb835f75aeffe2))
+
+## [2.48.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.47.0...cli-v2.48.0) (2026-03-22)
+
+
+### Features
+
+* **git-worktree:** auto-trust mise and direnv configs in new worktrees ([#312](https://github.com/EveryInc/compound-engineering-plugin/issues/312)) ([cfbfb67](https://github.com/EveryInc/compound-engineering-plugin/commit/cfbfb6710a846419cc07ad17d9dbb5b5a065801c))
+* make skills platform-agnostic across coding agents ([#330](https://github.com/EveryInc/compound-engineering-plugin/issues/330)) ([52df90a](https://github.com/EveryInc/compound-engineering-plugin/commit/52df90a16688ee023bbdb203969adcc45d7d2ba2))
+
+## [2.47.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.46.0...cli-v2.47.0) (2026-03-20)
+
+
+### Features
+
+* improve `repo-research-analyst` by adding a structured technology scan ([#327](https://github.com/EveryInc/compound-engineering-plugin/issues/327)) ([1c28d03](https://github.com/EveryInc/compound-engineering-plugin/commit/1c28d0321401ad50a51989f5e6293d773ac1a477))
+
+
+### Bug Fixes
+
+* **skills:** update ralph-wiggum references to ralph-loop in lfg/slfg ([#324](https://github.com/EveryInc/compound-engineering-plugin/issues/324)) ([ac756a2](https://github.com/EveryInc/compound-engineering-plugin/commit/ac756a267c5e3d5e4ceb2f99939dbb93491ac4d2))
+
+## [2.46.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.45.0...cli-v2.46.0) (2026-03-20)
+
+
+### Features
+
+* add optional high-level technical design to plan-beta skills ([#322](https://github.com/EveryInc/compound-engineering-plugin/issues/322)) ([3ba4935](https://github.com/EveryInc/compound-engineering-plugin/commit/3ba4935926b05586da488119f215057164d97489))
+
+
+### Bug Fixes
+
+* **ci:** add npm registry auth to release publish job ([#319](https://github.com/EveryInc/compound-engineering-plugin/issues/319)) ([3361a38](https://github.com/EveryInc/compound-engineering-plugin/commit/3361a38108991237de51050283e781be847c6bd3))
+
+## [2.45.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.44.0...cli-v2.45.0) (2026-03-19)
+
+
+### Features
+
+* edit resolve_todos_parallel skill for complete todo lifecycle ([#292](https://github.com/EveryInc/compound-engineering-plugin/issues/292)) ([88c89bc](https://github.com/EveryInc/compound-engineering-plugin/commit/88c89bc204c928d2f36e2d1f117d16c998ecd096))
+* integrate claude code auto memory as supplementary data source for ce:compound and ce:compound-refresh ([#311](https://github.com/EveryInc/compound-engineering-plugin/issues/311)) ([5c1452d](https://github.com/EveryInc/compound-engineering-plugin/commit/5c1452d4cc80b623754dd6fe09c2e5b6ae86e72e))
+
+
+### Bug Fixes
+
+* add cursor-marketplace as release-please component ([#315](https://github.com/EveryInc/compound-engineering-plugin/issues/315)) ([838aeb7](https://github.com/EveryInc/compound-engineering-plugin/commit/838aeb79d069b57a80d15ff61d83913919b81aef))
+
+## [2.44.0](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.43.2...cli-v2.44.0) (2026-03-18)
+
+
+### Features
+
+* **plugin:** add execution posture signaling to ce:plan-beta and ce:work ([#309](https://github.com/EveryInc/compound-engineering-plugin/issues/309)) ([748f72a](https://github.com/EveryInc/compound-engineering-plugin/commit/748f72a57f713893af03a4d8ed69c2311f492dbd))
+
+## [2.43.2](https://github.com/EveryInc/compound-engineering-plugin/compare/cli-v2.43.1...cli-v2.43.2) (2026-03-18)
+
+
+### Bug Fixes
+
+* enable release-please labeling so it can find its own PRs ([a7d6e3f](https://github.com/EveryInc/compound-engineering-plugin/commit/a7d6e3fbba862d4e8b4e1a0510f0776e9e274b89))
+* re-enable changelogs so release PRs accumulate correctly ([516bcc1](https://github.com/EveryInc/compound-engineering-plugin/commit/516bcc1dc4bf4e4756ae08775806494f5b43968a))
+* reduce release-please search depth from 500 to 50 ([f1713b9](https://github.com/EveryInc/compound-engineering-plugin/commit/f1713b9dcd0deddc2485e8cf0594266232bf0019))
+* remove close-stale-PR step that broke release creation ([178d6ec](https://github.com/EveryInc/compound-engineering-plugin/commit/178d6ec282512eaee71ab66d45832d22d75353ec))
+
+## Changelog
+
+Release notes now live in GitHub Releases for this repository:
+
+https://github.com/EveryInc/compound-engineering-plugin/releases
+
+Multi-component releases are published under component-specific tags such as:
+
+- `cli-vX.Y.Z`
+- `compound-engineering-vX.Y.Z`
+- `coding-tutor-vX.Y.Z`
+- `marketplace-vX.Y.Z`
+
+Do not add new release entries here. New release notes are managed by release automation in GitHub.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

CONCEPTS.md

@@ -0,0 +1,100 @@
+# Concepts
+
+Shared domain vocabulary for this project — entities, named processes, and status concepts with project-specific meaning. Seeded with core domain vocabulary, then accretes as ce-compound and ce-compound-refresh process learnings; direct edits are fine. Glossary only, not a spec or catch-all.
+
+## The plugin and its parts
+
+### Plugin
+A distributable bundle of Skills, Agents, Commands, and Hooks (optionally MCP servers) described by a single manifest and installed into a coding-agent platform as one unit — the artifact the Converter translates for non-Claude Targets and the Marketplace distributes.
+
+### Skill
+A user-invoked capability defined in its own directory, and the primary entry point a user reaches for. A Skill orchestrates: it can progressively pull in its own reference files as needed and dispatch generic subagents seeded with Specialist prompt assets. Distinct from an Agent in that a Skill is user-invoked and coordinates, whereas an Agent or subagent is dispatched to perform scoped work.
+
+### Agent
+A specialized, single-purpose worker running in its own isolated context and returning a result, rather than conversing with the user. Also called a subagent. In the current plugin design, most CE specialist behavior is not exposed as standalone Agent definitions; Skills seed generic subagents with Skill-local prompt material instead.
+
+### Specialist prompt asset
+An internal prompt file owned by one Skill that defines a specialist persona or research/review role for a generic subagent. It is not an externally exposed plugin component: the owning Skill controls when it is loaded, which model or tool policy applies, and how its output is merged.
+
+## Conversion
+
+### Target
+A destination coding-agent platform other than Claude Code (OpenCode, Codex, Pi, Antigravity, Kimi Code, and others) that the repo supports through native plugin metadata or a Converter/Writer pair. Also called a target provider when it uses the conversion path.
+
+A Plugin is installed to a Target at one of two scopes: global (user-wide) or per-workspace.
+
+### Native plugin surface
+A platform-provided install contract that can consume this repo's committed plugin manifest or marketplace metadata directly, without generating a converted Bundle. When a Target has a native plugin surface, user-facing support usually belongs in platform metadata, release validation, and docs instead of a new Converter and Writer.
+
+### Converter
+The step that transforms a parsed Plugin into one Target's in-memory form, mapping tools, permissions, hooks, and model names explicitly rather than by convention.
+
+### Writer
+The step that emits a Target's converted Bundle onto disk, in that Target's expected paths and merge semantics. Paired with a Converter, one per Target.
+
+### Bundle
+The in-memory converted form of a Plugin for a single Target — the handoff a Converter produces and a Writer consumes.
+
+### Install manifest
+A per-plugin ledger, written by a Writer at install time, of exactly which skill, agent, prompt, and extension paths that install created on a Target — the record later installs consult to tell tool-owned content apart from user-managed content.
+
+The load-bearing invariant is that a Writer never claims a path it did not write: a path the user has replaced (a symlink into a personal fork, a hand-authored directory) is excluded from the manifest and preserved on reinstall rather than overwritten, and the ledger is self-healing — removing the override lets the next install resume tracking that path. A path with no manifest entry — including one from an install predating the mechanism — reads as unowned and is therefore preserved.
+
+### Marketplace
+The catalog metadata listing installable plugins and their versions for distribution, kept consistent with each Plugin's manifest by release validation.
+
+## Compound engineering
+
+### Compound engineering
+The methodology this project embodies: structure engineering work so each unit makes the next one easier, capturing reusable knowledge as you go so the toolset gets smarter with every use.
+
+### Pipeline
+The chained progression of Skills that carries a piece of work from strategy and ideation through brainstorm, plan, execution, and review, and closes by capturing what was learned. Each stage hands a durable artifact to the next, and research is gathered at the stage that needs it rather than re-gathered downstream.
+
+### Learning
+A documented solution to a past problem — a bug fix, a convention, or a workflow pattern — stored as the unit of compounded knowledge so future work can find and reuse it. Also called a solution doc. Carries structured metadata (category, tags, problem type) for retrieval; its creation date lives in the entry, not the filename.
+
+### Pattern doc
+Guidance generalized from several Learnings into a broader rule. Higher-leverage than any single incident-level Learning, and higher-risk when stale, because future work treats it as broadly applicable.
+
+### Explainer
+A dense, visual teaching artifact written for the developer personally — explaining a concept, a change, an idea, or a window of their own recent work — so the human keeps learning when agents do the writing. The complement of a Learning: a Learning teaches the repo's future work; an explainer teaches the human.
+
+### Check-in
+The active-recall step that can follow an explainer in the same session: the developer predicts or answers first and the explanation confirms or corrects — predict-then-reveal for changes, checked exercises for concepts. Skippable when the material does not warrant retention work.
+
+### Concept-teaching section
+A conditional section of a generated PR description, added by agent judgment when the change introduces a concept new to the codebase, that teaches the concept — what it is, why it was chosen here, and an example from the PR — so a reader can understand and re-explain the change without reading the diff. The passive, in-description counterpart of an Explainer.
+
+## Skill orchestration
+
+### Model tier
+A semantic cost class for a dispatched sub-agent — extraction (cheapest capable, for retrieval and quoting), generation (mid-tier, for evidence-driven work and mechanical verification), or ceiling (the orchestrator's own model, inherited by omitting any model selection) — declared once per Skill and referenced by tier name so model names never hardcode into skill content.
+
+When a platform cannot select models per agent, every role runs on the inherited model and cost control falls back to structure: read budgets and output caps.
+
+### Evidence dossier
+A bulk evidence artifact — verbatim quotes with source pointers, gathered by a cheap scout agent — written to scratch storage instead of returned inline, so the orchestrator carries only a short gist and downstream agents read the full dossier themselves.
+
+### Load stub
+The inline remnant left in a Skill when load-bearing content moves to a reference file: a load instruction that names what the reference contains and the failure mode of skipping it, while keeping no detail an agent could improvise from — making the load structurally necessary rather than advisory.
+
+## Review and workflow vocabulary
+
+### Reviewer persona
+A single-lens reviewer role that evaluates work from one specific perspective — security, correctness, scope, design, and so on. Review Skills dispatch a panel of personas as subagents and merge their findings.
+
+### Confidence anchor
+A discrete, self-scored confidence value on a fixed small scale, each level tied to a behavioral criterion the model can honestly apply, used to gate and rank review findings instead of a continuous score that invites false precision. Each review Skill sets its own actionable threshold; corroboration across personas promotes a finding by one level.
+
+### Autofix class
+The classification of a review finding by how safely its proposed fix can be applied: applied silently, applied only after user confirmation, left for a human to resolve, or recorded as advisory with no action.
+
+### Headless mode
+An explicit opt-in mode that runs a Skill unattended, with no user prompts — it produces a written report as its deliverable and conservatively defers genuinely ambiguous decisions rather than guessing.
+
+### Feedback source
+A configured origin of customer or user feedback — a Slack channel, a GitHub Issues repo, an email inbox — declared once in the shared local config under a generic key so any Skill can read the list. Each source entry has its own identity and ingestion cursor; the Skill that ingests from it owns the per-item state, not the source declaration.
+
+### Beta skill
+A parallel copy of a stable Skill, suffixed `-beta`, used to trial a new version alongside the stable one without disrupting users. Invoked manually (model auto-invocation is disabled); promoting it to stable is more than a rename — every caller must move in the same change so none silently inherits stale defaults, and the retired beta name must be registered for stale-artifact cleanup so upgrading users don't keep a dead duplicate of the skill alongside the promoted one.

GEMINI.md

@@ -0,0 +1,9 @@
+# Compound Engineering
+
+This Gemini extension provides the Compound Engineering skill set for planning,
+review, implementation, debugging, and release workflows.
+
+Use the installed skills when they match the user's request. Treat this file as
+runtime context for extension users, not contributor guidance for this source
+repository. Do not apply this repository's `AGENTS.md` maintainer workflow to
+the user's project.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Every
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

PRIVACY.md

@@ -0,0 +1,38 @@
+# Privacy & Data Handling
+
+This repository contains:
+- a root plugin package made of markdown/config content
+- a CLI (`@every-env/compound-plugin`) that converts and installs plugin content for different AI coding tools
+
+## Summary
+
+- The plugin package does not include telemetry or analytics code.
+- The plugin package does not run a background service that uploads repository/workspace contents automatically.
+- Data leaves your machine only when your host/tooling or an explicitly invoked integration performs a network request.
+
+## What May Send Data
+
+1. AI host/model providers
+
+If you run the plugin in tools like Claude Code, Cursor, Codex, Gemini CLI, Copilot, Windsurf, etc., those tools may send prompts/context/code to their configured model providers. This behavior is controlled by those tools and providers, not by this plugin repository.
+
+2. Optional integrations and tools
+
+The plugin includes optional capabilities that can call external services when explicitly used, for example:
+- Context7 MCP (`https://mcp.context7.com/mcp`) for documentation lookup
+- Proof (`https://www.proofeditor.ai`) when using share/edit flows
+- Other opt-in skills (for example image generation or cloud upload workflows) that call their own external APIs/services
+
+If you do not invoke these integrations, they do not transmit your project data.
+
+3. Package/installer infrastructure
+
+Installing dependencies or packages (for example `npm`, `bunx`) communicates with package registries/CDNs according to your package manager configuration.
+
+## Data Ownership and Retention
+
+This repository does not operate a backend service for collecting or storing your project/workspace data. Data retention and processing for model prompts or optional integrations are governed by the external services you use.
+
+## Security Reporting
+
+If you identify a security issue in this repository, follow the disclosure process in [SECURITY.md](SECURITY.md).

README.md

@@ -0,0 +1,553 @@
+# Compound Engineering
+
+[![Build Status](https://github.com/EveryInc/compound-engineering-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/EveryInc/compound-engineering-plugin/actions/workflows/ci.yml)
+
+AI skills that make each unit of engineering work easier than the last.
+
+## Philosophy
+
+**Each unit of engineering work should make subsequent units easier -- not harder.**
+
+Traditional development accumulates technical debt. Every feature adds complexity. Every bug fix leaves behind a little more local knowledge that someone has to rediscover later. The codebase gets larger, the context gets harder to hold, and the next change becomes slower.
+
+Compound engineering inverts this. 80% is in planning and review, 20% is in execution:
+
+- Plan thoroughly before writing code with `/ce-brainstorm` and `/ce-plan` using one readiness-based plan artifact
+- Review to catch issues and calibrate judgment with `/ce-code-review` and `/ce-doc-review`
+- Codify knowledge so it is reusable with `/ce-compound`
+- Keep quality high so future changes are easy
+
+The point is not ceremony. The point is leverage. A good brainstorm makes the plan sharper. A good plan makes execution smaller. A good review catches the pattern, not just the bug. A good compound note means the next agent does not have to learn the same lesson from scratch.
+
+**Learn more**
+
+- [Skill documentation catalog](docs/skills/README.md)
+- [Compound engineering: how Every codes with agents](https://every.to/chain-of-thought/compound-engineering-how-every-codes-with-agents)
+- [The story behind compounding engineering](https://every.to/source-code/my-ai-had-already-fixed-the-code-before-i-saw-it)
+
+## Workflow
+
+The core loop is six steps: **brainstorm** the requirements, **plan** the implementation, **work** through the plan, **simplify** what you wrote, **review** the result, then **compound** the learning -- and repeat with better context.
+
+| Skill | Purpose |
+|-------|---------|
+| [`/ce-brainstorm`](docs/skills/ce-brainstorm.md) | Interactive Q&A to think through a feature or problem and write a requirements-only unified plan before planning |
+| [`/ce-plan`](docs/skills/ce-plan.md) | Enrich feature ideas or requirements-only plans into implementation-ready plans |
+| [`/ce-work`](docs/skills/ce-work.md) | Execute implementation-ready plans with worktrees and task tracking |
+| [`/ce-simplify-code`](docs/skills/ce-simplify-code.md) | Refine the freshly written code for clarity and reuse before review |
+| [`/ce-code-review`](docs/skills/ce-code-review.md) | Multi-agent review against the plan before merging |
+| [`/ce-compound`](docs/skills/ce-compound.md) | Capture the learning into `docs/solutions/` so the next loop starts smarter |
+
+Each cycle compounds: `/ce-compound` writes learnings that the next `/ce-brainstorm` and `/ce-plan` read as grounding -- brainstorms sharpen plans, plans inform future plans, reviews catch more issues, patterns get documented. That return arrow is the whole point.
+
+### Additional skills
+
+These sit around the loop or get reached for on demand -- not every cycle needs them.
+
+| Skill | When to reach for it |
+|-------|---------|
+| [`/ce-ideate`](docs/skills/ce-ideate.md) | *Before the loop*, when you don't yet know what to build -- generates and critically ranks grounded ideas, then routes the strongest one into `/ce-brainstorm` |
+| [`/ce-strategy`](docs/skills/ce-strategy.md) | *Upstream anchor* -- creates and maintains `STRATEGY.md`, read as grounding by ideate, brainstorm, and plan so strategy choices flow into every feature |
+| [`/ce-product-pulse`](docs/skills/ce-product-pulse.md) | *Outer loop* -- a time-windowed report on what users actually experienced (usage, performance, errors), saved to `docs/pulse-reports/`; its follow-ups feed back into ideation and brainstorming |
+| [`/ce-debug`](docs/skills/ce-debug.md) | *Instead of brainstorm -> plan -> work* when the input is a bug rather than a feature -- reproduce, trace root cause, fix, then polish/review before PR handoff when warranted |
+| [`/ce-pov`](docs/skills/ce-pov.md) | *On demand, before you commit* -- a decisive, project-grounded verdict on whether to adopt, switch to, or revisit an external technology, library, pattern, or platform; works cold or mid-session, and proposes the next step (`/ce-plan`, `/ce-brainstorm`, or a spike) from the verdict |
+| [`/ce-explain`](docs/skills/ce-explain.md) | *On demand, to keep learning* -- turns a concept, a diff, an idea, or "what did I do this week?" into a dense, visual explainer written for you personally, with an optional check-in (predict-then-reveal for diffs, corrected exercises) that makes it stick |
+
+For the full catalog and how each skill chains together, see [docs/skills](docs/skills/README.md). The complete inventory is [below](#full-skill-inventory).
+
+## Quick Example
+
+**Finding a direction** -- when you don't have a specific idea yet, ideate first, then carry the strongest survivor into the loop:
+
+```text
+/ce-ideate new drawing tools
+/ce-ideate surprise me
+/ce-ideate github issues   # ground ideas in your open issues instead of a prompt
+```
+
+`/ce-ideate` does the homework first (codebase, past learnings, prior art on the web, optionally your issue tracker), then hands you a ranked set of grounded candidates to take into `/ce-brainstorm`.
+
+**Standard feature loop** -- turn a rough idea into shipped, reviewed code:
+
+```text
+/ce-brainstorm make background job retries safer
+/ce-plan
+/ce-work
+/ce-simplify-code
+/ce-code-review
+/ce-compound
+```
+
+**Simplifying code** -- use it after fresh implementation work, or point it at code that keeps slowing changes down:
+
+```text
+/ce-simplify-code
+/ce-simplify-code simplify the code in my most-churned file
+```
+
+The first pass tightens recent branch changes before review. The targeted pass is useful when one file keeps absorbing unrelated fixes, follow-ups, or merge conflicts.
+
+**Debugging a bug** -- when you start from broken behavior instead of a feature:
+
+```text
+/ce-debug the checkout webhook sometimes creates duplicate invoices
+/ce-code-review
+/ce-compound
+```
+
+**Autonomous** -- hand off a feature and let the agent run the whole pipeline:
+
+```text
+/ce-brainstorm describe the feature
+/lfg
+```
+
+`/lfg` runs the loop hands-off: it plans, works through the plan, simplifies, runs code review and applies the fixes, runs browser tests, commits, pushes, opens a PR, then watches CI and repairs failures until it's green. Start it after `/ce-brainstorm` so it plans against real requirements rather than a one-line prompt. It's the autopilot version of the standard loop -- neat when you want to step away and come back to an open, green PR.
+
+## Getting Started
+
+After installing, run `/ce-setup` in any project. It checks repo-local config, reports optional tool capabilities, and helps keep machine-local CE settings safely gitignored.
+
+The `compound-engineering` plugin currently ships 30 skills and 0 standalone agents. Specialist review, research, and workflow behavior lives inside the owning skills as skill-local prompt assets.
+
+### Full Skill Inventory
+
+| Skill | Purpose |
+|-------|---------|
+| [`/ce-strategy`](docs/skills/ce-strategy.md) | Create or maintain `STRATEGY.md` |
+| [`/ce-ideate`](docs/skills/ce-ideate.md) | Generate and critically evaluate grounded ideas |
+| [`/ce-pov`](docs/skills/ce-pov.md) | Form a decisive, project-grounded verdict on an external input |
+| [`/ce-explain`](docs/skills/ce-explain.md) | Explain a concept, diff, idea, or window of your own work as a personal learning artifact |
+| [`/ce-brainstorm`](docs/skills/ce-brainstorm.md) | Explore requirements and write a right-sized requirements doc |
+| [`/ce-plan`](docs/skills/ce-plan.md) | Create structured implementation plans |
+| [`/ce-work`](docs/skills/ce-work.md) | Execute implementation plans systematically |
+| [`/ce-code-review`](docs/skills/ce-code-review.md) | Review code with skill-local reviewer personas |
+| [`/ce-doc-review`](docs/skills/ce-doc-review.md) | Review requirements and plan documents |
+| [`/ce-debug`](docs/skills/ce-debug.md) | Reproduce failures, trace root cause, fix bugs, and prepare non-trivial fixes for PR |
+| [`/ce-compound`](docs/skills/ce-compound.md) | Document solved problems to compound team knowledge |
+| [`/ce-compound-refresh`](docs/skills/ce-compound-refresh.md) | Refresh stale or drifting learnings |
+| [`/ce-optimize`](docs/skills/ce-optimize.md) | Run iterative optimization loops |
+| [`/ce-product-pulse`](docs/skills/ce-product-pulse.md) | Generate time-windowed product pulse reports |
+| [`/ce-riffrec-feedback-analysis`](docs/skills/ce-riffrec-feedback-analysis.md) | Convert Riffrec recordings or notes into structured feedback |
+| [`/ce-sweep`](docs/skills/ce-sweep.md) | Sweep feedback sources, track item lifecycles, and emit an `/lfg`-ready plan |
+| [`/ce-resolve-pr-feedback`](docs/skills/ce-resolve-pr-feedback.md) | Resolve PR review feedback |
+| [`/ce-commit`](docs/skills/ce-commit.md) | Create a git commit with a clear message |
+| [`/ce-commit-push-pr`](docs/skills/ce-commit-push-pr.md) | Commit, push, and open a PR that teaches any concept the change newly introduces |
+| [`/ce-babysit-pr`](docs/skills/ce-babysit-pr.md) | Watch an open PR and keep it moving toward merge, reacting to review comments and CI as they arrive |
+| [`/ce-worktree`](docs/skills/ce-worktree.md) | Ensure work happens in an isolated git worktree |
+| [`/ce-promote`](docs/skills/ce-promote.md) | Draft user-facing announcement copy |
+| [`/ce-test-browser`](docs/skills/ce-test-browser.md) | Run browser tests on PR-affected pages |
+| [`/ce-test-xcode`](docs/skills/ce-test-xcode.md) | Build and test iOS apps on simulator |
+| [`/ce-setup`](docs/skills/ce-setup.md) | Diagnose optional tool capabilities and project config |
+| [`/ce-simplify-code`](docs/skills/ce-simplify-code.md) | Simplify recent code changes |
+| [`/ce-polish`](docs/skills/ce-polish.md) | Start a dev server and iterate on UX polish |
+| [`/ce-proof`](docs/skills/ce-proof.md) | Create, edit, and share Proof documents |
+| [`/ce-dogfood`](docs/skills/ce-dogfood.md) | Hands-off diff-scoped browser QA of the active branch, with autonomous fixes |
+| [`/lfg`](docs/skills/lfg.md) | Full autonomous engineering workflow |
+
+---
+
+## Install
+
+### Claude Code
+
+```text
+/plugin marketplace add EveryInc/compound-engineering-plugin
+/plugin install compound-engineering
+```
+
+> **Already have Compound Engineering installed?** Compound Engineering moved to a root-native layout. You must refresh the marketplace *before* updating — see [Existing Installs](#existing-installs). Running `/plugin update` alone keeps you on the old version.
+
+### Cursor
+
+In Cursor Agent chat, install from the plugin marketplace:
+
+```text
+/add-plugin compound-engineering
+```
+
+Or search for "compound engineering" in the plugin marketplace.
+
+### Codex App
+
+Compound Engineering is not listed in Codex's built-in plugin marketplace yet. Add it as a custom marketplace:
+
+1. In the Codex app, open **Plugins** from the sidebar.
+2. Click **Add** / **Add plugin marketplace**.
+3. Enter:
+
+   | Field | Value |
+   | --- | --- |
+   | Source | `EveryInc/compound-engineering-plugin` |
+   | Git ref | `main` |
+   | Sparse paths | leave blank |
+
+4. Click **Add marketplace**.
+5. Select **Compound Engineering**, install **compound-engineering**, then restart Codex.
+
+The Codex app install is self-contained for Compound Engineering. Specialist reviewer and research behavior lives inside the skills as local prompt assets; no separate custom-agent install step is required.
+
+### Codex CLI
+
+Register the marketplace, then install the plugin.
+
+1. **Register the marketplace with Codex:**
+
+   ```bash
+   codex plugin marketplace add EveryInc/compound-engineering-plugin
+   ```
+
+2. **Install the plugin:**
+
+   ```bash
+   codex plugin add compound-engineering@compound-engineering-plugin
+   ```
+
+   You can also launch `codex`, run `/plugins`, find the **Compound Engineering** marketplace, select the **compound-engineering** plugin, and choose **Install**. Restart Codex after install completes.
+
+The native Codex plugin install is self-contained for Compound Engineering. Specialist reviewer and research behavior lives inside the skills as local prompt assets; no separate custom-agent install step is required.
+
+For a non-default Codex profile, run every Codex-related step against the same `CODEX_HOME`. This example installs CE into a `work` profile:
+
+```bash
+CODEX_HOME="$HOME/.codex/profiles/work" codex plugin marketplace add EveryInc/compound-engineering-plugin
+CODEX_HOME="$HOME/.codex/profiles/work" codex plugin add compound-engineering@compound-engineering-plugin
+```
+
+The marketplace step only makes the plugin available; the plugin install is what activates the native CE skills for that profile.
+
+### Kimi Code CLI
+
+Kimi Code CLI can install Compound Engineering directly from this repository because the repo ships a native `.kimi-plugin/plugin.json` manifest:
+
+```text
+/plugins install https://github.com/EveryInc/compound-engineering-plugin
+```
+
+You can also browse it through Kimi's custom marketplace flow:
+
+```text
+/plugins marketplace https://raw.githubusercontent.com/EveryInc/compound-engineering-plugin/main/.kimi-plugin/marketplace.json
+```
+
+After installing or updating, run `/reload` or start a new Kimi session so the plugin skills are loaded.
+
+### Cline
+
+Cline loads CE skills from on-demand `SKILL.md` directories. Enable **Settings -> Features -> Enable Skills** in the Cline extension, then link this repository's skills globally or per project:
+
+```bash
+git clone https://github.com/EveryInc/compound-engineering-plugin
+./compound-engineering-plugin/.cline/scripts/install-skills.sh --global
+```
+
+Per-project install from a checkout:
+
+```bash
+./compound-engineering-plugin/.cline/scripts/install-skills.sh --project
+```
+
+Start a new Cline task after installing or updating skills. See [`.cline/INSTALL.md`](.cline/INSTALL.md) for pinning, local development, and uninstall steps.
+
+### Grok Build CLI (`grok`)
+
+xAI's [Grok Build CLI](https://x.ai/cli) (`grok`) installs Compound Engineering directly from this repository — the repo root is a valid Grok plugin (`grok` reads the existing Claude-compatible manifests, and the repo also ships a native `.grok-plugin/plugin.json`):
+
+```bash
+grok plugin install EveryInc/compound-engineering-plugin
+```
+
+This tracks the repository; run `grok plugin update` to pull the latest. To browse it as a marketplace source instead, the repo ships a native `.grok-plugin/marketplace.json`:
+
+```bash
+grok plugin marketplace add EveryInc/compound-engineering-plugin
+grok plugin install compound-engineering
+```
+
+Both paths track the repository directly (no commit pin), so no Bun install step is needed. Add `--trust` to skip the install confirmation. `grok` stores config under `~/.grok`; start a new session after installing so the skills load.
+
+Compound Engineering is also being submitted to the official [xAI plugin marketplace](https://github.com/xai-org/plugin-marketplace); see [`docs/grok-marketplace-submission.md`](docs/grok-marketplace-submission.md) for the maintainer runbook.
+
+### Devin CLI
+
+Devin CLI can install Compound Engineering directly from GitHub because the repo ships a native `.devin-plugin/plugin.json` manifest:
+
+```bash
+devin plugins install EveryInc/compound-engineering-plugin
+```
+
+Verify the install and inspect the skills:
+
+```bash
+devin plugins list
+devin plugins info compound-engineering
+```
+
+Update to the latest version with `devin plugins update compound-engineering`. Plugins load at session start, so start a new Devin session after installing or updating for the skills to appear (as `/compound-engineering:<skill>` slash commands).
+
+A few skills declare Claude-style `allowed-tools` names that Devin does not map (for example `Bash`); those skills still work, but some of their actions ask for permission instead of running auto-approved. See [`docs/specs/devin.md`](docs/specs/devin.md) for details.
+
+### GitHub Copilot
+
+For **VS Code Copilot Agent Plugins**:
+
+1. Run `Chat: Install Plugin from Source` from the VS Code command palette
+2. Use `EveryInc/compound-engineering-plugin` for the repo
+3. Select `compound-engineering` when VS Code shows the plugins in this repository
+
+For **Copilot CLI**, use:
+
+Inside Copilot CLI:
+
+```text
+/plugin marketplace add EveryInc/compound-engineering-plugin
+/plugin install compound-engineering@compound-engineering-plugin
+```
+
+From a shell with the `copilot` binary:
+
+```bash
+copilot plugin marketplace add EveryInc/compound-engineering-plugin
+copilot plugin install compound-engineering@compound-engineering-plugin
+```
+
+Copilot CLI reads the existing Claude-compatible plugin manifests, so no separate Bun install step is needed.
+
+### Factory Droid
+
+From a shell with the `droid` binary:
+
+```bash
+droid plugin marketplace add https://github.com/EveryInc/compound-engineering-plugin
+droid plugin install compound-engineering@compound-engineering-plugin
+```
+
+Droid uses `plugin@marketplace` plugin IDs; here `compound-engineering` is the plugin and `compound-engineering-plugin` is the marketplace name. Droid installs the existing Claude Code-compatible plugin and translates the format automatically, so no Bun install step is needed.
+
+### Qwen Code
+
+```bash
+qwen extensions install EveryInc/compound-engineering-plugin:compound-engineering
+```
+
+Qwen Code installs Claude Code-compatible plugins directly from GitHub and converts the plugin format during install, so no Bun install step is needed.
+
+### OpenCode
+
+Add Compound Engineering to the `plugin` array in your global or project `opencode.json`:
+
+```json
+{
+  "plugin": ["compound-engineering@git+https://github.com/EveryInc/compound-engineering-plugin.git"]
+}
+```
+
+Restart OpenCode after changing the config. The OpenCode plugin registers the Compound Engineering skills directory directly; no Bun installer or generated skill copy is required. See [`.opencode/INSTALL.md`](.opencode/INSTALL.md) for pinning examples.
+
+### Pi
+
+Install Compound Engineering as a Pi package from this repository:
+
+```bash
+pi install git:github.com/EveryInc/compound-engineering-plugin
+```
+
+Required companion for CE workflows that dispatch reviewer, research, or implementation subagents:
+
+```bash
+pi install npm:pi-subagents
+```
+
+Recommended companion for richer blocking questions:
+
+```bash
+pi install npm:pi-ask-user
+```
+
+### Antigravity CLI (`agy`)
+
+Google has replaced the consumer Gemini CLI with [Antigravity CLI](https://antigravity.google) (`agy`), which still runs on Gemini models. Install Compound Engineering directly from GitHub — no clone step required:
+
+```bash
+agy plugin install https://github.com/EveryInc/compound-engineering-plugin
+```
+
+Verify with `agy plugin list`. The repository root is the plugin package (`plugin.json` plus `skills/`).
+
+For a local checkout or pinned release:
+
+```bash
+git clone https://github.com/EveryInc/compound-engineering-plugin
+agy plugin install ./compound-engineering-plugin
+```
+
+The bundled `.agy/` directory remains a compatibility entry point (`agy plugin install ./compound-engineering-plugin/.agy`). `agy` also loads `GEMINI.md` workspace context from the checkout.
+
+See [`.agy/INSTALL.md`](.agy/INSTALL.md) for pinning, local development, uninstall, and legacy Gemini import.
+
+### Existing Installs
+
+Compound Engineering moved to a root-native, skills-only layout. An existing marketplace install keeps a **cached** marketplace snapshot that still points at the old `plugins/compound-engineering` path, so updating the plugin on its own reads that stale snapshot and leaves you on the previous version. Refresh the cached marketplace **first**, then update the plugin — order matters.
+
+**Claude Code**
+
+```text
+/plugin marketplace update compound-engineering-plugin
+/plugin update compound-engineering
+```
+
+**Codex CLI**
+
+```bash
+codex plugin marketplace upgrade compound-engineering-plugin
+codex plugin add compound-engineering@compound-engineering-plugin
+```
+
+There is no `codex plugin update`; re-running `add` reinstalls from the refreshed snapshot. For a non-default profile, run both commands against the same `CODEX_HOME`.
+
+**Codex App**
+
+Refresh the marketplace from the **Plugins** panel (remove and re-add the `EveryInc/compound-engineering-plugin` marketplace if there is no refresh control), then reinstall **compound-engineering** and restart Codex.
+
+If you configured a host with a direct path or sparse path under `plugins/compound-engineering`, edit or reinstall that source so it points at the repository root with no sparse path.
+
+If a previous Bun-installed copy is still shadowing native plugin skills, run the current cleanup command from a checkout of this repository:
+
+```bash
+git clone https://github.com/EveryInc/compound-engineering-plugin.git /tmp/compound-engineering-plugin-cleanup
+cd /tmp/compound-engineering-plugin-cleanup
+bun install
+bun run cleanup --target all
+```
+
+---
+
+## Local Development
+
+```bash
+bun install
+bun test
+bun run release:validate
+```
+
+### From your local checkout
+
+For active development, load this checkout directly in the harness you want to test.
+
+**Claude Code**
+
+```bash
+claude --plugin-dir "$PWD"
+```
+
+**Codex App**
+
+In the app's **Add plugin marketplace** form, use this checkout as the source:
+
+| Field | Value |
+| --- | --- |
+| Source | `/path/to/compound-engineering-plugin` |
+| Git ref | current branch, or leave blank for a local folder |
+| Sparse paths | leave blank |
+
+**Codex CLI**
+
+```bash
+codex plugin marketplace add "$PWD"
+codex plugin add compound-engineering@compound-engineering-plugin
+```
+
+Use a separate `CODEX_HOME` when you want to keep local testing isolated from your normal Codex profile. The Codex marketplace entry points at the public Git plugin source so root-shaped plugin repos install correctly; use a temporary marketplace catalog with a `source.url` plus `ref` when testing unpublished plugin-content changes end to end.
+
+**Kimi Code CLI**
+
+Inside Kimi Code CLI:
+
+```text
+/plugins install /path/to/compound-engineering-plugin
+```
+
+To test the local marketplace catalog instead, pass the catalog path:
+
+```text
+/plugins marketplace /path/to/compound-engineering-plugin/.kimi-plugin/marketplace.json
+```
+
+**Cline**
+
+```bash
+/path/to/compound-engineering-plugin/.cline/scripts/install-skills.sh --global
+```
+
+Enable **Settings -> Features -> Enable Skills** in the Cline extension, then start a new task.
+
+**Devin CLI**
+
+```bash
+devin plugins install /path/to/compound-engineering-plugin
+```
+
+Local installs are linked to the checkout rather than copied, so skill edits apply on the next Devin session without reinstalling.
+
+**OpenCode**
+
+```json
+{
+  "plugin": ["/path/to/compound-engineering-plugin"]
+}
+```
+
+Restart OpenCode after changing `opencode.json`.
+
+**Pi**
+
+```bash
+pi -e "$PWD"
+```
+
+**Antigravity CLI (`agy`)**
+
+```bash
+agy plugin install "$PWD"
+agy plugin validate "$PWD"
+```
+
+Or install the bundled `.agy/` entry point:
+
+```bash
+agy plugin install "$PWD/.agy"
+```
+
+See [`.agy/INSTALL.md`](.agy/INSTALL.md) for remote install and pinning examples.
+
+## Limitations
+
+OpenCode and Pi use native package/plugin loading from this repository. The Bun CLI remains for repository development and converter maintenance, not normal installation.
+
+Release versions are owned by release automation. Routine feature PRs should not hand-bump plugin or marketplace manifest versions.
+
+## FAQ
+
+### Do I need Bun to install Compound Engineering?
+
+No. Bun is only needed for repo development tasks and converter maintenance.
+
+### Where do I see all available skills?
+
+The skill inventory is in this README, and the deeper skill catalog is in [`docs/skills/README.md`](docs/skills/README.md). Each skill's authoritative runtime spec lives in `skills/<skill>/SKILL.md`.
+
+### Where is release history?
+
+GitHub Releases are the canonical release-notes surface. The root [`CHANGELOG.md`](CHANGELOG.md) points to that history.
+
+## Contributing
+
+Contributions are welcome. Issues, bug reports, and pull requests all help make this better, and we genuinely appreciate them — bug reports especially.
+
+A note on what to expect: Compound Engineering is opinionated by design. It's maintained by [@kieranklaassen](https://github.com/kieranklaassen) and [@tmchow](https://github.com/tmchow), and its direction reflects a specific point of view about how AI-assisted engineering should work. So while we welcome help, we can't promise to accept every change — some proposals won't fit that vision even when they're good ideas on their own.
+
+Open an issue or send a PR, and we'll fold in what moves the plugin in the right direction. We just want to be upfront that not everything will land.
+
+## License
+
+[MIT](LICENSE)

README.wehub.md

@@ -0,0 +1,7 @@
+# WeHub 来源说明
+
+- 原始项目：`EveryInc/compound-engineering-plugin`
+- 原始仓库：https://github.com/EveryInc/compound-engineering-plugin
+- 导入方式：上游默认分支的最新快照
+- 原作者、版权和许可证信息以原始仓库及本仓库 LICENSE 为准
+- 本文件仅用于记录来源，不代表 WeHub 是原项目作者

SECURITY.md

@@ -0,0 +1,29 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are applied to the latest version on `main`.
+
+## Reporting a Vulnerability
+
+Please do not open a public issue for undisclosed vulnerabilities.
+
+Instead, report privately by emailing:
+- `kieran@every.to`
+
+Include:
+- A clear description of the issue
+- Reproduction steps or proof of concept
+- Impact assessment (what an attacker can do)
+- Any suggested mitigation
+
+We will acknowledge receipt as soon as possible and work with you on validation, remediation, and coordinated disclosure timing.
+
+## Scope Notes
+
+This repository primarily contains plugin instructions/configuration plus a conversion/install CLI.
+
+- Plugin instruction content itself does not run as a server process.
+- Security/privacy behavior also depends on the host AI tool and any external integrations you explicitly invoke.
+
+For data-handling details, see [PRIVACY.md](PRIVACY.md).

docs/brainstorms/2026-02-14-copilot-converter-target-brainstorm.md

@@ -0,0 +1,117 @@
+---
+date: 2026-02-14
+topic: copilot-converter-target
+---
+
+# Add GitHub Copilot Converter Target
+
+## What We're Building
+
+A new converter target that transforms the compound-engineering Claude Code plugin into GitHub Copilot's native format. This follows the same established pattern as the existing converters (Cursor, Codex, OpenCode, Droid, Pi) and outputs files that Copilot can consume directly from `.github/` (repo-level) or `~/.copilot/` (user-wide).
+
+Copilot's customization system (as of early 2026) supports: custom agents (`.agent.md`), agent skills (`SKILL.md`), prompt files (`.prompt.md`), custom instructions (`copilot-instructions.md`), and MCP servers (via repo settings).
+
+## Why This Approach
+
+The repository already has a robust multi-target converter infrastructure with a consistent `TargetHandler` pattern. Adding Copilot as a new target follows this proven pattern rather than inventing something new. Copilot's format is close enough to Claude Code's that the conversion is straightforward, and the SKILL.md format is already cross-compatible.
+
+### Approaches Considered
+
+1. **Full converter target (chosen)** — Follow the existing pattern with types, converter, writer, and target registration. Most consistent with codebase conventions.
+2. **Minimal agent-only converter** — Only convert agents, skip commands/skills. Too limited; users would lose most of the plugin's value.
+3. **Documentation-only approach** — Just document how to manually set up Copilot. Doesn't compound — every user would repeat the work.
+
+## Key Decisions
+
+### Component Mapping
+
+| Claude Code Component | Copilot Equivalent | Notes |
+|----------------------|-------------------|-------|
+| **Agents** (`.md`) | **Custom Agents** (`.agent.md`) | Full frontmatter mapping: description, tools, target, infer |
+| **Commands** (`.md`) | **Agent Skills** (`SKILL.md`) | Commands become skills since Copilot has no direct command equivalent. `allowed-tools` dropped silently. |
+| **Skills** (`SKILL.md`) | **Agent Skills** (`SKILL.md`) | Copy as-is — format is already cross-compatible |
+| **MCP Servers** | **Repo settings JSON** | Generate a `copilot-mcp-config.json` users paste into GitHub repo settings |
+| **Hooks** | **Skipped with warning** | Copilot doesn't have a hooks equivalent |
+
+### Agent Frontmatter Mapping
+
+| Claude Field | Copilot Field | Mapping |
+|-------------|--------------|---------|
+| `name` | `name` | Direct pass-through |
+| `description` | `description` (required) | Direct pass-through, generate fallback if missing |
+| `capabilities` | Body text | Fold into body as "## Capabilities" section (like Cursor) |
+| `model` | `model` | Pass through (works in IDE, may be ignored on github.com) |
+| — | `tools` | Default to `["*"]` (all tools). Claude agents have unrestricted tool access, so Copilot agents should too. |
+| — | `target` | Omit (defaults to `both` — IDE + github.com) |
+| — | `infer` | Set to `true` (auto-selection enabled) |
+
+### Output Directories
+
+- **Repository-level (default):** `.github/agents/`, `.github/skills/`
+- **User-wide (with --personal flag):** `~/.copilot/skills/` (only skills supported at this level)
+
+### Content Transformation
+
+Apply transformations similar to Cursor converter:
+
+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/` → `.github/` (Copilot's repo-level config path)
+4. **Agent references:** `@agent-name` → `the agent-name agent`
+
+### MCP Server Handling
+
+Generate a `copilot-mcp-config.json` file with the structure Copilot expects:
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "type": "local",
+      "command": "npx",
+      "args": ["package"],
+      "tools": ["*"],
+      "env": {
+        "KEY": "COPILOT_MCP_KEY"
+      }
+    }
+  }
+}
+```
+
+Note: Copilot requires env vars to use the `COPILOT_MCP_` prefix. The converter should transform env var names accordingly and include a comment/note about this.
+
+## Files to Create/Modify
+
+### New Files
+
+- `src/types/copilot.ts` — Type definitions (CopilotAgent, CopilotSkill, CopilotBundle, etc.)
+- `src/converters/claude-to-copilot.ts` — Converter with `transformContentForCopilot()`
+- `src/targets/copilot.ts` — Writer with `writeCopilotBundle()`
+- `docs/specs/copilot.md` — Format specification document
+
+### Modified Files
+
+- `src/targets/index.ts` — Register copilot target handler
+- `src/commands/sync.ts` — Add "copilot" to valid sync targets
+
+### Test Files
+
+- `tests/copilot-converter.test.ts` — Converter tests following existing patterns
+
+### Character Limit
+
+Copilot imposes a 30,000 character limit on agent body content. If an agent body exceeds this after folding in capabilities, the converter should truncate with a warning to stderr.
+
+### Agent File Extension
+
+Use `.agent.md` (not plain `.md`). This is the canonical Copilot convention and makes agent files immediately identifiable.
+
+## Open Questions
+
+- Should the converter generate a `copilot-setup-steps.yml` workflow file for MCP servers that need special dependencies (e.g., `uv`, `pipx`)?
+- Should `.github/copilot-instructions.md` be generated with any base instructions from the plugin?
+
+## Next Steps
+
+→ `/workflows:plan` for implementation details

docs/brainstorms/2026-02-17-copilot-skill-naming-brainstorm.md

@@ -0,0 +1,30 @@
+---
+date: 2026-02-17
+topic: copilot-skill-naming
+---
+
+# Copilot Skill Naming: Preserve Namespace
+
+## What We're Building
+
+Change the Copilot converter to preserve command namespaces when converting commands to skills. Currently `workflows:plan` flattens to `plan`, which is too generic and clashes with Copilot's own features in the chat suggestion UI.
+
+## Why This Approach
+
+The `flattenCommandName` function strips everything before the last colon, producing names like `plan`, `review`, `work` that are too generic for Copilot's skill discovery UI. Replacing colons with hyphens (`workflows:plan` -> `workflows-plan`) preserves context while staying within valid filename characters.
+
+## Key Decisions
+
+- **Replace colons with hyphens** instead of stripping the prefix: `workflows:plan` -> `workflows-plan`
+- **Copilot only** — other converters (Cursor, Droid, etc.) keep their current flattening behavior
+- **Content transformation too** — slash command references in body text also use hyphens: `/workflows:plan` -> `/workflows-plan`
+
+## Changes Required
+
+1. `src/converters/claude-to-copilot.ts` — change `flattenCommandName` to replace colons with hyphens
+2. `src/converters/claude-to-copilot.ts` — update `transformContentForCopilot` slash command rewriting
+3. `tests/copilot-converter.test.ts` — update affected tests
+
+## Next Steps
+
+-> Implement directly (small, well-scoped change)

docs/brainstorms/2026-03-14-ce-plan-rewrite-requirements.md

@@ -0,0 +1,85 @@
+---
+date: 2026-03-14
+topic: ce-plan-rewrite
+---
+
+# Rewrite `ce:plan` to Separate Planning from Implementation
+
+## Problem Frame
+
+`ce:plan` sits between `ce:brainstorm` and `ce:work`, but the current skill mixes issue authoring, technical planning, and pseudo-implementation. That makes plans brittle and pushes the planning phase to predict details that are often only discoverable during implementation. PR #246 intensifies this by asking plans to include complete code, exact commands, and micro-step TDD and commit choreography. The rewrite should keep planning strong enough for a capable agent or engineer to execute, while moving code-writing, test-running, and execution-time learning back into `ce:work`.
+
+## Requirements
+
+- R1. `ce:plan` must accept either a raw feature description or a requirements document produced by `ce:brainstorm` as primary input.
+- R2. `ce:plan` must preserve compound-engineering's planning strengths: repo pattern scan, institutional learnings, conditional external research, and requirements-gap checks when warranted.
+- R3. `ce:plan` must produce a durable implementation plan focused on decisions, sequencing, file paths, dependencies, risks, and test scenarios, not implementation code.
+- R4. `ce:plan` must not instruct the planner to run tests, generate exact implementation snippets, or learn from execution-time results. Those belong to `ce:work`.
+- R5. Plan tasks and subtasks must be right-sized for implementation handoff, but sized as logical units or atomic commits rather than 2-5 minute copy-paste steps.
+- R6. Plans must remain shareable and portable as documents or issues without tool-specific executor litter such as TodoWrite instructions, `/ce:work` choreography, or git command recipes in the artifact itself.
+- R7. `ce:plan` must carry forward product decisions, scope boundaries, success criteria, and deferred questions from `ce:brainstorm` without re-inventing them.
+- R8. `ce:plan` must explicitly distinguish what gets resolved during planning from what is intentionally deferred to implementation-time discovery.
+- R9. `ce:plan` must hand off cleanly to `ce:work`, giving enough information for task creation without pre-writing code.
+- R10. If detail levels remain, they must change depth of analysis and documentation, not the planning philosophy. A small plan can be terse while still staying decision-first.
+- R11. If an upstream requirements document contains unresolved `Resolve Before Planning` items, `ce:plan` must classify whether they are true product blockers or misfiled technical questions before proceeding.
+- R12. `ce:plan` must not plan past unresolved product decisions that would change behavior, scope, or success criteria, but it may absorb technical or research questions by reclassifying them into planning-owned investigation.
+- R13. When true blockers remain, `ce:plan` must pause helpfully: surface the blockers, allow the user to convert them into explicit assumptions or decisions, or route them back to `ce:brainstorm`.
+
+## Success Criteria
+
+- A fresh implementer can start work from the plan without needing clarifying questions, but the plan does not contain implementation code.
+- `ce:work` can derive actionable tasks from the plan without relying on micro-step commands or embedded git/test instructions.
+- Plans stay accurate longer as repo context changes because they capture decisions and boundaries rather than speculative code.
+- A requirements document from `ce:brainstorm` flows into planning without losing decisions, scope boundaries, or success criteria.
+- Plans do not proceed past unresolved product blockers unless the user explicitly converts them into assumptions or decisions.
+- For the same feature, the rewritten `ce:plan` produces output that is materially shorter and less brittle than the current skill or PR #246's proposed format while remaining execution-ready.
+
+## Scope Boundaries
+
+- Do not redesign `ce:brainstorm`'s product-definition role.
+- Do not remove decomposition, file paths, verification, or risk analysis from `ce:plan`.
+- Do not move planning into a vague, under-specified artifact that leaves execution to guess.
+- Do not change `ce:work` in this phase beyond possible follow-up clarification of what plan structure it should prefer.
+- Do not require heavyweight PRD ceremony for small or straightforward work.
+
+## Key Decisions
+
+- Use a hybrid model: keep compound-engineering's research and handoff strengths, but adopt iterative-engineering's "decisions, not code" boundary.
+- Planning stops before execution: no running tests, no fail/pass learning, no exact implementation snippets, and no commit shell commands in the plan.
+- Use logical tasks and subtasks sized around atomic changes or commit units rather than 2-5 minute micro-steps.
+- Keep explicit verification and test scenarios, but express them as expected coverage and validation outcomes rather than commands with predicted output.
+- Preserve `ce:brainstorm` as the preferred upstream input when available, with clear handling for deferred technical questions.
+- Treat `Resolve Before Planning` as a classification gate: planning first distinguishes true product blockers from technical questions, then investigates only the latter.
+
+## High-Level Direction
+
+- Phase 0: Resume existing plan work when relevant, detect brainstorm input, and assess scope.
+- Phase 1: Gather context through repo research, institutional learnings, and conditional external research.
+- Phase 2: Resolve planning-time technical questions and capture implementation-time unknowns separately.
+- Phase 3: Structure the plan around components, dependencies, files, test targets, risks, and verification.
+- Phase 4: Write a right-sized plan artifact whose depth varies by scope, but whose boundary stays planning-only.
+- Phase 5: Review and hand off to refinement, deeper research, issue sharing, or `ce:work`.
+
+## Alternatives Considered
+
+- Keep the current `ce:plan` and only reject PR #246.
+  Rejected because the underlying issue remains: the current skill already drifts toward issue-template output plus pseudo-implementation.
+- Adopt Superpowers `writing-plans` nearly wholesale.
+  Rejected because it is intentionally execution-script-oriented and collapses planning into detailed code-writing and command choreography.
+- Adopt iterative-engineering `tech-planning` wholesale.
+  Rejected because it would lose useful compound-engineering behaviors such as brainstorm-origin integration, institutional learnings, and richer post-plan handoff options.
+
+## Dependencies / Assumptions
+
+- `ce:work` can continue creating its own actionable task list from a decision-first plan.
+- If `ce:work` later benefits from an explicit section such as `## Implementation Units` or `## Work Breakdown`, that should be a separate follow-up designed around execution needs rather than micro-step code generation.
+
+## Resolved During Planning
+
+- [Affects R10][Technical] Replaced `MINIMAL` / `MORE` / `A LOT` with `Lightweight` / `Standard` / `Deep` to align `ce:plan` with `ce:brainstorm`'s scope model.
+- [Affects R9][Technical] Updated `ce:work` to explicitly consume decision-first plan sections such as `Implementation Units`, `Requirements Trace`, `Files`, `Test Scenarios`, and `Verification`.
+- [Affects R2][Needs research] Kept SpecFlow as a conditional planning aid: use it for `Standard` or `Deep` plans when flow completeness is unclear rather than making it mandatory for every plan.
+
+## Next Steps
+
+-> Review, refine, and commit the `ce:plan` and `ce:work` rewrite

docs/brainstorms/2026-03-15-ce-ideate-skill-requirements.md

@@ -0,0 +1,77 @@
+---
+date: 2026-03-15
+topic: ce-ideate-skill
+---
+
+# ce:ideate — Open-Ended Ideation Skill
+
+## Problem Frame
+
+The ce:brainstorm skill is reactive — the user brings an idea, and the skill helps refine it through collaborative dialogue. There is no workflow for the opposite direction: having the AI proactively generate ideas by deeply understanding the project and then filtering them through critical self-evaluation. Users currently achieve this through ad-hoc prompting (e.g., "come up with 100 ideas and give me your best 10"), but that approach has no codebase grounding, no structured output, no durable artifact, and no connection to the ce:* workflow pipeline.
+
+## Requirements
+
+- R1. ce:ideate is a standalone skill, separate from ce:brainstorm, with its own SKILL.md in `plugins/compound-engineering/skills/ce-ideate/`
+- R2. Accepts an optional freeform argument that serves as a focus hint — can be a concept ("DX improvements"), a path ("plugins/compound-engineering/skills/"), a constraint ("low-complexity quick wins"), or empty for fully open ideation
+- R3. Performs a deep codebase scan before generating ideas, grounding ideation in the actual project state rather than abstract speculation
+- R4. Preserves the user's proven prompt mechanism as the core workflow: generate many ideas first, then systematically and critically reject weak ones, then explain only the surviving ideas in detail
+- R5. Self-critiques the full list, rejecting weak ideas with explicit reasoning — the adversarial filtering step is the core quality mechanism
+- R6. Presents the top 5-7 surviving ideas with structured analysis: description, rationale, downsides, confidence score (0-100%), estimated complexity
+- R7. Includes a brief rejection summary — one-line per rejected idea with the reason — so the user can see what was considered and why it was cut
+- R8. Writes a durable ideation artifact to `docs/ideation/YYYY-MM-DD-<topic>-ideation.md` (or `YYYY-MM-DD-open-ideation.md` when no focus area). This compounds — rejected ideas prevent re-exploring dead ends, and un-acted-on ideas remain available for future sessions.
+- R9. The default volume (~30 ideas, top 5-7 presented) can be overridden by the user's argument (e.g., "give me your top 3" or "go deep, 100 ideas")
+- R10. Handoff options after presenting ideas: brainstorm a selected idea (feeds into ce:brainstorm), refine the ideation (dig deeper, re-evaluate, explore new angles), share to Proof, or end the session
+- R11. Always routes to ce:brainstorm when the user wants to act on an idea — ideation output is never detailed enough to skip requirements refinement
+- R12. Session completion: when ending, offer to commit the ideation doc to the current branch. If the user declines, leave the file uncommitted. Do not create branches or push — just the local commit.
+- R13. Resume behavior: when ce:ideate is invoked, check `docs/ideation/` for ideation docs created within the last 30 days. If a relevant one exists, offer to continue from it (add new ideas, revisit rejected ones, act on un-explored ideas) or start fresh.
+- R14. Present the surviving candidates to the user before writing the durable ideation artifact, so the user can ask questions or lightly reshape the candidate set before it is archived
+- R15. The ideation artifact must be written or updated before any downstream handoff, Proof sharing, or session end, even though the initial survivor presentation happens first
+- R16. Refine routes based on intent: "add more ideas" or "explore new angles" returns to generation (Phase 2), "re-evaluate" or "raise the bar" returns to critique (Phase 3), "dig deeper on idea #N" expands that idea's analysis in place. The ideation doc is updated after each refinement when the refined state is being preserved
+- R17. Uses agent intelligence to improve ideation quality, but only as support for the core prompt mechanism rather than as a replacement for it
+- R18. Uses existing research agents for codebase grounding, but ideation and critique sub-agents are prompt-defined roles with distinct perspectives rather than forced reuse of existing named review agents
+- R19. When sub-agents are used for ideation, each one receives the same grounding summary, the user focus hint, and the current volume target
+- R20. Focus hints influence both candidate generation and final filtering; they are not only an evaluation-time bias
+- R21. Ideation sub-agents return ideas in a standardized structured format so the orchestrator can merge, dedupe, and reason over them consistently
+- R22. The orchestrator owns final scoring, ranking, and survivor decisions across the merged idea set; sub-agents may emit lightweight local signals, but they do not authoritatively rank their own ideas
+- R23. Distinct ideation perspectives should be created through prompt framing methods that encourage creative spread without over-constraining the workflow; examples include friction, unmet need, inversion, assumption-breaking, leverage, and extreme-case prompts
+- R24. The skill does not hardcode a fixed number of sub-agents for all runs; it should use the smallest useful set that preserves diversity without overwhelming the orchestrator's context window
+- R25. When the user picks an idea to brainstorm, the ideation doc is updated to mark that idea as "explored" with a reference to the resulting brainstorm session date, so future revisits show which ideas have been acted on.
+
+## Success Criteria
+
+- A user can invoke `/ce:ideate` with no arguments on any project and receive genuinely surprising, high-quality improvement ideas grounded in the actual codebase
+- Ideas that survive the filter are meaningfully better than what the user would get from a naive "give me 10 ideas" prompt
+- The workflow uses agent intelligence to widen the candidate pool without obscuring the core generate -> reject -> survivors mechanism
+- The user sees and can question the surviving candidates before they are written into the durable artifact
+- The ideation artifact persists and provides value when revisited weeks later
+- The skill composes naturally with the existing pipeline: ideate → brainstorm → plan → work
+
+## Scope Boundaries
+
+- ce:ideate does NOT produce requirements, plans, or code — it produces ranked ideas
+- ce:ideate does NOT modify ce:brainstorm's behavior — discovery of ce:ideate is handled through the skill description and catalog, not by altering other skills
+- The skill does not do external research (competitive analysis, similar projects) in v1 — this could be a future enhancement but adds cost and latency without proven need
+- No configurable depth modes in v1 — fixed volume with argument-based override is sufficient
+
+## Key Decisions
+
+- **Standalone skill, not a mode within ce:brainstorm**: The workflows are fundamentally different cognitive modes (proactive/divergent vs. reactive/convergent) with different phases, outputs, and success criteria. Combining them would make ce:brainstorm harder to maintain and blur its identity.
+- **Durable artifact in docs/ideation/**: Discarding ideation results is anti-compounding. The file is cheap to write and provides value when revisiting un-acted-on ideas or avoiding re-exploration of rejected ones.
+- **Artifact written after candidate review, not before initial presentation**: The first survivor presentation is collaborative review, not archival finalization. The artifact should be written only after the candidate set is good enough to preserve, but always before handoff, sharing, or session end.
+- **Always route to ce:brainstorm for follow-up**: At ideation depth, ideas are one-paragraph concepts — never detailed enough to skip requirements refinement.
+- **Survivors + rejection summary output format**: Full transparency on what was considered without overwhelming with detailed analysis of rejected ideas.
+- **Freeform optional argument**: A concept, a path, or nothing at all — the skill interprets whatever it gets as context. No artificial distinction between "focus area" and "target path."
+- **Agent intelligence as support, not replacement**: The value comes from the proven ideation-and-rejection mechanism. Parallel sub-agents help produce a richer candidate pool and stronger critique, but the orchestrator remains responsible for synthesis, scoring, and final ranking.
+
+## Outstanding Questions
+
+### Deferred to Planning
+
+- [Affects R3][Technical] Which research agents should always run for codebase grounding in v1 beyond `repo-research-analyst` and `learnings-researcher`, if any?
+- [Affects R21][Technical] What exact structured output schema should ideation sub-agents return so the orchestrator can merge and score consistently without overfitting the format too early?
+- [Affects R6][Technical] Should the structured analysis per surviving idea include "suggested next steps" or "what this would unlock" beyond the current fields (description, rationale, downsides, confidence, complexity)?
+- [Affects R2][Technical] How should the skill detect volume overrides in the freeform argument vs. focus-area hints? Simple heuristic or explicit parsing?
+
+## Next Steps
+
+→ `/ce:plan` for structured implementation planning

docs/brainstorms/2026-03-16-issue-grounded-ideation-requirements.md

@@ -0,0 +1,65 @@
+---
+date: 2026-03-16
+topic: issue-grounded-ideation
+---
+
+# Issue-Grounded Ideation Mode for ce:ideate
+
+## Problem Frame
+
+When a team wants to ideate on improvements, their issue tracker holds rich signal about real user pain, recurring failures, and severity patterns — but ce:ideate currently only looks at the codebase and past learnings. Teams have to manually synthesize issue patterns before ideating, or they ideate without that context and miss what their users are actually hitting.
+
+The goal is not "fix individual bugs" but "generate strategic improvement ideas grounded in the patterns your issue tracker reveals." 25 duplicate bugs about the same failure mode is a signal about collaboration reliability, not 25 separate problems.
+
+## Requirements
+
+- R1. When the user's argument indicates they want issue-tracker data as input (e.g., "bugs", "github issues", "open issues", "what users are reporting", "issue patterns"), ce:ideate activates an issue intelligence step alongside the existing Phase 1 scans
+- R2. A new **issue intelligence agent** fetches, clusters, deduplicates, and analyzes issues, returning structured theme analysis — not a list of individual issues
+- R3. The agent fetches **open issues** plus **recently closed issues** (approximately 30 days), filtering out issues closed as duplicate, won't-fix, or not-planned. Recently fixed issues are included because they show which areas had enough pain to warrant action.
+- R4. Issue clusters drive the ideation frames in Phase 2 using a **hybrid strategy**: derive frames from clusters, pad with default frames (e.g., "assumption-breaking", "leverage/compounding") when fewer than 4 clusters exist. This ensures ideas are grounded in real pain patterns while maintaining ideation diversity.
+- R5. The existing Phase 1 scans (codebase context + learnings search) still run in parallel — issue analysis is additive context, not a replacement
+- R6. The issue intelligence agent detects the repository from the current directory's git remote
+- R7. Start with GitHub issues via `gh` CLI. Design the agent prompt and output structure so Linear or other trackers can be added later without restructuring the ideation flow.
+- R8. The issue intelligence agent is independently useful outside of ce:ideate — it can be dispatched directly by a user or other workflows to summarize issue themes, understand the current landscape, or reason over recent activity. Its output should be self-contained, not coupled to ideation-specific context.
+- R9. The agent's output must communicate at the **theme level**, not the individual-issue level. Each theme should convey: what the pattern is, why it matters (user impact, severity, frequency, trend direction), and what it signals about the system. The output should help a human or agent fully understand the importance and shape of each theme without needing to read individual issues.
+
+## Success Criteria
+
+- Running `/ce:ideate bugs` on a repo with noisy/duplicate issues (like proof's 25+ LIVE_DOC_UNAVAILABLE variants) produces clustered themes, not a rehash of individual issues
+- Surviving ideas are strategic improvements ("invest in collaboration reliability infrastructure") not bug fixes ("fix LIVE_DOC_UNAVAILABLE")
+- The issue intelligence agent's output is structured enough that ideation sub-agents can engage with themes meaningfully
+- Ideation quality is at least as good as the default mode, with the added benefit of issue grounding
+
+## Scope Boundaries
+
+- GitHub issues only in v1 (Linear is a future extension)
+- No issue triage or management — this is read-only analysis for ideation input
+- No changes to Phase 3 (adversarial filtering) or Phase 4 (presentation) — only Phase 1 and Phase 2 frame derivation are affected
+- The issue intelligence agent is a new agent file, not a modification to an existing research agent
+- The agent is designed as a standalone capability that ce:ideate composes, not an ideation-internal module
+- Assumes `gh` CLI is available and authenticated in the environment
+- When a repo has too few issues to cluster meaningfully (e.g., < 5 open+recent), the agent should report that and ce:ideate should fall back to default ideation with a note to the user
+
+## Key Decisions
+
+- **Pattern-first, not issue-first**: The output is improvement ideas grounded in bug patterns, not a prioritized bug list. The ideation instructions already prevent "just fix bug #534" thinking.
+- **Hybrid frame strategy**: Clusters derive ideation frames, padded with defaults when thin. Pure cluster-derived frames risk too few frames; pure default frames risk ignoring the issue signal.
+- **Flexible argument detection**: Use intent-based parsing ("reasonable interpretation rather than formal parsing") consistent with the existing volume hint system. No rigid keyword matching.
+- **Open + recently closed**: Including recently fixed issues provides richer pattern data — shows which areas warranted action, not just what's currently broken.
+- **Additive to Phase 1**: Issue analysis runs as a third parallel agent alongside codebase scan and learnings search. All three feed the grounding summary.
+- **Titles + labels + sample bodies**: Read titles and labels for all issues (cheap), then read full bodies for 2-3 representative issues per emerging cluster. This handles both well-labeled repos (labels drive clustering, bodies confirm) and poorly-labeled repos (bodies drive clustering). Avoids reading all bodies which is expensive at scale.
+
+## Outstanding Questions
+
+### Deferred to Planning
+
+- [Affects R2][Technical] What structured output format should the issue intelligence agent return? Likely theme clusters with: theme name, issue count, severity distribution, representative issue titles, and a one-line synthesis.
+- [Affects R3][Technical] How to detect GitHub close reasons (completed vs not-planned vs duplicate) via `gh` CLI? May need `gh issue list --state closed --json stateReason` or label-based filtering.
+- [Affects R4][Technical] What's the threshold for "too few clusters"? Current thinking: pad with default frames when fewer than 4 clusters, but this may need tuning.
+- [Affects R6][Technical] How to extract the GitHub repo from git remote? Standard `gh repo view --json nameWithOwner` or parse the remote URL.
+- [Affects R7][Needs research] What would a Linear integration look like? Just swapping the fetch mechanism, or does Linear's project/cycle structure change the clustering approach?
+- [Affects R2][Technical] Exact number of sample bodies per cluster to read (starting point: 2-3 per cluster).
+
+## Next Steps
+
+→ `/ce:plan` for structured implementation planning

docs/brainstorms/2026-03-17-release-automation-requirements.md

@@ -0,0 +1,89 @@
+---
+date: 2026-03-17
+topic: release-automation
+---
+
+# Release Automation and Changelog Ownership
+
+## Problem Frame
+
+The repository currently has one automated release flow for the npm CLI, but the broader release story is split across CI, manual maintainer workflows, stale docs, and multiple version surfaces. That makes it hard to batch releases intentionally, hard for multiple maintainers to share release responsibility, and easy for changelogs, plugin manifests, and derived metadata like component counts to drift out of sync. The goal is to move to a release model that supports intentional batching, independent component versioning, centralized history, and CI-owned release authority without forcing version bumps for untouched plugins.
+
+## Requirements
+
+- R1. The release process must be manually triggered; merging to `main` must not automatically publish a release.
+- R2. The release system must support batching: releasable merges may accumulate on `main` until maintainers decide to cut a release.
+- R3. The release system must maintain a single release PR for the whole repo that stays open until merged and automatically accumulates additional releasable changes merged to `main`.
+- R4. The release system must support independent version bumps for these components: `cli`, `compound-engineering`, `coding-tutor`, and `marketplace`.
+- R5. The release system must not bump untouched plugins or unrelated components.
+- R6. The release system must preserve one centralized root `CHANGELOG.md` as the canonical changelog for the repository.
+- R7. The root changelog must record releases as top-level entries per component version, rather than requiring separate changelog files per plugin.
+- R8. Existing root changelog history must be preserved during the migration; the new release model must not discard or rewrite historical entries in a way that loses continuity.
+- R9. `plugins/compound-engineering/CHANGELOG.md` must no longer be treated as the canonical changelog after the migration.
+- R10. The release process must replace the current `release-docs` workflow; `release-docs` must no longer act as a release authority or required release step.
+- R11. Narrow scripts must replace `release-docs` responsibilities, including metadata synchronization, count calculation, docs generation where still needed, and validation.
+- R12. Release automation must be the sole authority for version bumps, changelog writes, and computed metadata updates such as counts of agents, skills, commands, or similar release-owned descriptions.
+- R13. The release flow must support a dry-run mode that summarizes what would happen without publishing, tagging, or committing release changes.
+- R14. Dry run output must clearly summarize which components would release, the proposed version bumps, the changelog entries that would be added, and any blocking validation failures.
+- R15. Marketplace version bumps must happen only for marketplace-level changes, such as marketplace metadata changes or adding/removing plugins from the catalog.
+- R16. Updating a plugin version alone must not require a marketplace version bump.
+- R17. Plugin-only content changes must be releasable without requiring a CLI version bump when the CLI code itself has not changed.
+- R18. The release model must remain compatible with the current install behavior where `bunx @every-env/compound-plugin install ...` runs the npm CLI but fetches named plugin content from the GitHub repository at runtime.
+- R19. The release process must be triggerable by a maintainer or an AI agent through CI without requiring a local maintainer-only skill.
+- R20. The resulting model must scale to future plugins without requiring the repo to special-case `compound-engineering` forever.
+- R21. The release model must continue to rely on conventional release intent signals (`feat`, `fix`, breaking changes, etc.), but component scopes in commit or PR titles must remain optional rather than required.
+- R22. Release automation must infer component ownership primarily from changed files, not from commit or PR title scopes alone.
+- R23. The repo should enforce parseable conventional PR or merge titles strongly enough for release tooling to classify change type, while avoiding mandatory component scoping on every change.
+- R24. The manual CI-driven release workflow must support explicit bump overrides for exceptional cases, at least `patch`, `minor`, and `major`, without requiring maintainers to create fake or empty commits purely to coerce a release.
+- R25. Bump overrides must be expressible per component rather than only as a repo-wide override.
+- R26. Dry run output must clearly show both the inferred bump and any applied manual override for each affected component.
+
+## Success Criteria
+
+- Maintainers can let multiple PRs merge to `main` without immediately cutting a release.
+- At any point, maintainers can inspect a release PR or dry run and understand what would ship next.
+- A change to `coding-tutor` does not force a version bump to `compound-engineering`.
+- A plugin version bump does not force a marketplace version bump unless marketplace-level files changed.
+- Release-owned metadata and counts stay in sync without relying on a local slash command.
+- The root changelog remains readable and continuous before and after the migration.
+
+## Scope Boundaries
+
+- This work does not require changing how Claude Code itself consumes plugin and marketplace versions.
+- This work does not require solving end-user auto-update discovery for non-Claude harnesses in v1.
+- This work does not require adding dedicated per-plugin changelog files as the canonical history model.
+- This work does not require immediate future automation of release timing; manual release remains the default.
+
+## Key Decisions
+
+- **Use `release-please` rather than a single release-line flow**: The repo now has multiple independently versioned components, and the release PR model matches the need to batch merges on `main` until a release is intentionally cut.
+- **One release PR for the whole repo**: Centralized release visibility matters more than separate PRs per component, and a single release PR can still carry multiple component bumps.
+- **Manual release timing**: The release process should prepare and accumulate the next release automatically, but the decision to cut that release should remain explicit.
+- **Root changelog stays canonical**: Centralized history is more important than per-plugin changelog isolation for the current repo shape.
+- **Top-level changelog entries per component version**: This preserves one changelog file while keeping independent component version history readable.
+- **Retire `release-docs`**: Its responsibilities are too broad, stale, and conflated. Release logic, docs logic, and metadata synchronization should be separated.
+- **Scripts for narrow responsibilities**: Explicit scripts are easier to validate, automate, and reuse from CI than a local repo-maintenance skill.
+- **Marketplace version is catalog-scoped**: Plugin version bumps alone should not imply a marketplace release.
+- **Conventional type required, component scope optional**: Release intent should still come from conventional commit semantics, but requiring `(compound-engineering)` on most repo changes would add unnecessary wording overhead. Component detection should remain file-driven.
+- **Manual bump override is an explicit escape hatch**: Automatic bump inference remains the default, but maintainers should be able to override a component's release level in CI for exceptional cases without awkward synthetic commits.
+
+## Dependencies / Assumptions
+
+- The current install flow for named plugins continues to fetch plugin content from GitHub at runtime, so plugin content releases can remain independent from CLI releases unless CLI behavior also changes.
+- Claude Code already respects marketplace and plugin versions, so those version surfaces remain meaningful release signals.
+
+## Outstanding Questions
+
+### Deferred to Planning
+
+- [Affects R3][Technical] Should the release PR be updated automatically on every push to `main`, or via a manually triggered maintenance workflow that refreshes the release PR state on demand?
+- [Affects R7][Technical] What exact root changelog format best balances readability and automation for multiple component-version entries in one file?
+- [Affects R11][Technical] Which responsibilities should become distinct scripts versus steps embedded directly in the CI workflow?
+- [Affects R12][Technical] Which release-owned metadata fields should be computed automatically versus validated and left untouched when no count change is needed?
+- [Affects R9][Technical] Should `plugins/compound-engineering/CHANGELOG.md` be deleted, frozen, or replaced with a short pointer note after the migration?
+- [Affects R21][Technical] Should conventional-format enforcement happen on PR titles, squash-merge titles, commits, or some combination of them?
+- [Affects R24][Technical] Should manual bump overrides be implemented as workflow inputs that shape the generated release PR directly, or as an internal generated release-control commit on the release branch only?
+
+## Next Steps
+
+→ `/ce:plan` for structured implementation planning

docs/brainstorms/2026-03-18-auto-memory-integration-requirements.md

@@ -0,0 +1,50 @@
+---
+date: 2026-03-18
+topic: auto-memory-integration
+---
+
+# Auto Memory Integration for ce:compound and ce:compound-refresh
+
+## Problem Frame
+
+Claude Code's Auto Memory feature passively captures debugging insights, fix patterns, and preferences across sessions in `~/.claude/projects/<project>/memory/`. The ce:compound and ce:compound-refresh skills currently don't leverage this data source, even though it contains exactly the kind of raw material these workflows need: notes about problems solved, approaches tried, and patterns discovered.
+
+After long sessions or compaction, auto memory may preserve insights that conversation context has lost. For ce:compound-refresh, auto memory may contain newer observations that signal drift in existing docs/solutions/ learnings without anyone explicitly flagging it.
+
+## Requirements
+
+- R1. **ce:compound uses auto memory as supplementary evidence.** The orchestrator reads MEMORY.md before launching Phase 1 subagents, scans for entries related to the problem being documented, and passes relevant memory content as additional context to the Context Analyzer and Solution Extractor subagents. Those subagents treat memory notes as supplementary evidence alongside conversation history.
+- R2. **ce:compound-refresh investigation subagents check auto memory.** When investigating a candidate learning's staleness, investigation subagents also check auto memory for notes in the same problem domain. A memory note describing a different approach than what the learning recommends is treated as a drift signal.
+- R3. **Graceful absence handling.** If auto memory doesn't exist for the project (no memory directory or empty MEMORY.md), all skills proceed exactly as they do today with no errors or warnings.
+
+## Success Criteria
+
+- ce:compound produces richer documentation when auto memory contains relevant notes about the fix, especially after sessions involving compaction
+- ce:compound-refresh surfaces staleness signals that would otherwise require manual discovery
+- No regression when auto memory is absent or empty
+
+## Scope Boundaries
+
+- **Not changing auto memory's output location or format** -- these skills consume it as-is
+- **Read-only** -- neither skill writes to auto memory; ce:compound writes to docs/solutions/ (team-shared, structured), which serves a different purpose than machine-local auto memory
+- **Not adding a new subagent** -- existing subagents are augmented with memory-checking instructions
+- **Not changing the structure of docs/solutions/ output** -- the final artifacts are the same
+
+## Dependencies / Assumptions
+
+- Claude knows its auto memory directory path from the system prompt context in every session -- no path discovery logic needed in the skills
+
+## Key Decisions
+
+- **Augment existing subagents, not a new one**: ce:compound-refresh investigation subagents need memory context during their own investigation (not as a separate report), so a dedicated Memory Scanner subagent would be awkward. For ce:compound, the orchestrator pre-reads MEMORY.md once and passes relevant excerpts to subagents, avoiding redundant reads while keeping the same subagent count.
+
+## Outstanding Questions
+
+### Deferred to Planning
+
+- [Affects R1][Technical] How should the orchestrator determine which MEMORY.md entries are "related" to the current problem? Keyword matching against the problem description, or broader heuristic?
+- [Affects R2][Technical] Should ce:compound-refresh investigation subagents read the full MEMORY.md or only topic files matching the learning's domain? The 200-line MEMORY.md is small enough to read in full, but topic files may be more targeted.
+
+## Next Steps
+
+-> `/ce:plan` for structured implementation planning

docs/brainstorms/2026-03-22-frontend-design-skill-improvement.md

@@ -0,0 +1,187 @@
+# Frontend Design Skill Improvement
+
+**Date:** 2026-03-22
+**Status:** Design approved, pending implementation plan
+**Scope:** Rewrite `frontend-design` skill + surgical addition to `ce:work-beta`
+
+## Context
+
+The current `frontend-design` skill (43 lines) is a brief aesthetic manifesto forked from the Anthropic official skill. It emphasizes bold design and avoiding AI slop but lacks practical structure, concrete constraints, context-specific guidance, and any verification mechanism.
+
+Two external sources informed this redesign:
+- **Anthropic's official frontend-design skill** -- nearly identical to ours, same gaps
+- **OpenAI's frontend skill** (from their "Designing Delightful Frontends with GPT-5.4" article, March 2026) -- dramatically more comprehensive with composition rules, context modules, card philosophy, copy guidelines, motion specifics, and litmus checks
+
+Additionally, the beta workflow (`ce:plan-beta` -> `deepen-plan-beta` -> `ce:work-beta`) has no mechanism to invoke the frontend-design skill. The old `deepen-plan` discovered and applied it dynamically; `deepen-plan-beta` uses deterministic agent mapping and skips skill discovery entirely. The skill is effectively orphaned in the beta workflow.
+
+## Design Decisions
+
+### Authority Hierarchy
+
+Every rule in the skill is a default, not a mandate:
+1. **Existing design system / codebase patterns** -- highest priority, always respected
+2. **User's explicit instructions** -- override skill defaults
+3. **Skill defaults** -- only fully apply in greenfield or when user asks for design guidance
+
+This addresses a key weakness in OpenAI's approach: their rules read as absolutes ("No cards by default", "Full-bleed hero only") without escape hatches. Users who want cards in the hero shouldn't fight their own tooling.
+
+### Layered Architecture
+
+The skill is structured as layers:
+
+- **Layer 0: Context Detection** -- examine codebase for existing design signals before doing anything. Short-circuits opinionated guidance when established patterns exist.
+- **Layer 1: Pre-Build Planning** -- visual thesis + content plan + interaction plan (3 short statements). Adapts to greenfield vs existing codebase.
+- **Layer 2: Design Guidance Core** -- always-applicable principles (typography, color, composition, motion, accessibility, imagery). All yield to existing systems.
+- **Context Modules** -- agent selects one based on what's being built:
+  - Module A: Landing pages & marketing (greenfield)
+  - Module B: Apps & dashboards (greenfield)
+  - Module C: Components & features (default when working inside an existing app, regardless of what's being built)
+
+### Layer 0: Detection Signals (Concrete Checklist)
+
+The agent looks for these specific signals when classifying the codebase:
+
+- **Design tokens / CSS variables**: `--color-*`, `--spacing-*`, `--font-*` custom properties, theme files
+- **Component libraries**: shadcn/ui, Material UI, Chakra, Ant Design, Radix, or project-specific component directories
+- **CSS frameworks**: `tailwind.config.*`, `styled-components` theme, Bootstrap imports, CSS modules with consistent naming
+- **Typography**: Font imports in HTML/CSS, `@font-face` declarations, Google Fonts links
+- **Color palette**: Defined color scales, brand color files, design token exports
+- **Animation libraries**: Framer Motion, GSAP, anime.js, Motion One, Vue Transition imports
+- **Spacing / layout patterns**: Consistent spacing scale usage, grid systems, layout components
+
+**Mode classification:**
+- **Existing system**: 4+ signals detected across multiple categories. Defer to it.
+- **Partial system**: 1-3 signals detected. Apply skill defaults where no convention was detected; yield to detected conventions where they exist.
+- **Greenfield**: No signals detected. Full skill guidance applies.
+- **Ambiguous**: Signals are contradictory or unclear. Ask the user.
+
+### Interaction Method for User Questions
+
+When Layer 0 needs to ask the user (ambiguous detection), use the platform's blocking question tool:
+- Claude Code: `AskUserQuestion`
+- Codex: `request_user_input`
+- Gemini CLI: `ask_user`
+- Fallback: If no question tool is available, assume "partial" mode and proceed conservatively.
+
+### Where We Improve Beyond OpenAI
+
+1. **Accessibility as a first-class concern** -- OpenAI's skill is pure aesthetics. We include semantic HTML, contrast ratios, focus states as peers of typography and color.
+
+2. **Existing codebase integration** -- OpenAI has one exception line buried in the rules. We make context detection the first step and add Module C specifically for "adding a feature to an existing app" -- the most common real-world case that both OpenAI and Anthropic ignore entirely.
+
+3. **Defaults with escape hatches** -- Two-tier anti-pattern system: "default against" (overridable preferences) vs "always avoid" (genuine quality failures). OpenAI mixes these in a flat list.
+
+4. **Framework-aware animation defaults** -- OpenAI assumes Framer Motion. We detect existing animation libraries first. When no existing library is found, the default is framework-conditional: CSS animations as the universal baseline, Framer Motion for React, Vue Transition / Motion One for Vue, Svelte transitions for Svelte.
+
+5. **Visual self-verification** -- Neither OpenAI nor Anthropic have any verification. We add a browser-based screenshot + assessment step with a tool preference cascade:
+   1. Existing project browser tooling (Playwright, Puppeteer, etc.)
+   2. Browser MCP tools (claude-in-chrome, etc.)
+   3. agent-browser CLI (default when nothing else exists -- load the `agent-browser` skill for setup)
+   4. Mental review against litmus checks (last resort)
+
+6. **Responsive guidance** -- kept light (trust smart models) but present, unlike OpenAI's single mention.
+
+7. **Performance awareness** -- careful balance, noting that heavy animations and multiple font imports have costs, without being prescriptive about specific thresholds.
+
+8. **Copy guidance without arbitrary thresholds** -- OpenAI says "if deleting 30% of the copy improves the page, keep deleting." We use: "Every sentence should earn its place. Default to less copy, not more."
+
+### Scope Control on Verification
+
+Visual verification is a sanity check, not a pixel-perfect review. One pass. If there's a glaring issue, fix it. If it looks solid, move on. The goal is catching "this clearly doesn't work" before the user sees it.
+
+### ce:work-beta Integration
+
+A small addition to Phase 2 (Execute), after the existing Figma Design Sync section:
+
+**UI task detection heuristic:** A task is a "UI task" if any of these are true:
+- The task's implementation files include view, template, component, layout, or page files
+- The task creates new user-visible routes or pages
+- The plan text contains explicit "UI", "frontend", "design", "layout", or "styling" language
+- The task references building or modifying something the user will see in a browser
+
+The agent uses judgment -- these are heuristics, not a rigid classifier.
+
+**What ce:work-beta adds:**
+
+> For UI tasks without a Figma design, load the `frontend-design` skill before implementing. Follow its detection, guidance, and verification flow.
+
+This is intentionally minimal:
+- Doesn't duplicate skill content into ce:work-beta
+- Doesn't load the skill for non-UI tasks
+- Doesn't load the skill when Figma designs exist (Figma sync covers that)
+- Doesn't change any other phase
+
+**Verification screenshot reuse:** The frontend-design skill's visual verification screenshot satisfies ce:work-beta Phase 4's screenshot requirement. The agent does not need to screenshot twice -- the skill's verification output is reused for the PR.
+
+**Relationship to design-iterator agent:** The frontend-design skill's verification is a single sanity-check pass. For iterative refinement beyond that (multiple rounds of screenshot-assess-fix), see the `design-iterator` agent. The skill does not invoke design-iterator automatically.
+
+## Files Changed
+
+| File | Change |
+|------|--------|
+| `plugins/compound-engineering/skills/frontend-design/SKILL.md` | Full rewrite |
+| `plugins/compound-engineering/skills/ce-work-beta/SKILL.md` | Add ~5 lines to Phase 2 |
+
+## Skill Description (Optimized)
+
+```yaml
+name: frontend-design
+description: Build web interfaces with genuine design quality, not AI slop. Use for
+  any frontend work: landing pages, web apps, dashboards, admin panels, components,
+  interactive experiences. Activates for both greenfield builds and modifications to
+  existing applications. Detects existing design systems and respects them. Covers
+  composition, typography, color, motion, and copy. Verifies results via screenshots
+  before declaring done.
+```
+
+## Skill Structure (frontend-design/SKILL.md)
+
+```
+Frontmatter (name, description)
+Preamble (what, authority hierarchy, workflow preview)
+Layer 0: Context Detection
+  - Detect existing design signals
+  - Choose mode: existing / partial / greenfield
+  - Ask user if ambiguous
+Layer 1: Pre-Build Planning
+  - Visual thesis (one sentence)
+  - Content plan (what goes where)
+  - Interaction plan (2-3 motion ideas)
+Layer 2: Design Guidance Core
+  - Typography (2 typefaces max, distinctive choices, yields to existing)
+  - Color & Theme (CSS variables, one accent, no purple bias, yields to existing)
+  - Composition (poster mindset, cardless default, whitespace before chrome)
+  - Motion (2-3 intentional motions, use existing library, framework-conditional defaults)
+  - Accessibility (semantic HTML, WCAG AA contrast, focus states)
+  - Imagery (real photos, stable tonal areas, image generation when available)
+Context Modules (select one)
+  - A: Landing Pages & Marketing (greenfield -- hero rules, section sequence, copy as product language)
+  - B: Apps & Dashboards (greenfield -- calm surfaces, utility copy, minimal chrome)
+  - C: Components & Features (default in existing apps -- match existing, inherit tokens, focus on states)
+Hard Rules & Anti-Patterns
+  - Default against (overridable): generic card grids, purple bias, overused fonts, etc.
+  - Always avoid (quality floor): prompt language in UI, broken contrast, missing focus states
+Litmus Checks
+  - Context-sensitive self-review questions
+Visual Verification
+  - Tool cascade: existing > MCP > agent-browser > mental review
+  - One iteration, sanity check scope
+  - Include screenshot in deliverable
+```
+
+## What We Keep From Current Skill
+
+- Strong anti-AI-slop identity and messaging
+- Creative energy / encouragement to be bold in greenfield work
+- Tone-picking exercise (brutally minimal, maximalist chaos, retro-futuristic...)
+- "Differentiation" prompt: what makes this unforgettable?
+- Framework-agnostic approach (HTML/CSS/JS, React, Vue, etc.)
+
+## Cross-Agent Compatibility
+
+Per AGENTS.md rules:
+- Describe tools by capability class with platform hints, not Claude-specific names alone
+- Use platform-agnostic question patterns (name known equivalents + fallback)
+- No shell recipes for routine exploration
+- Reference co-located scripts with relative paths
+- Skill is written once, copied as-is to other platforms

docs/brainstorms/2026-03-23-plan-review-personas-requirements.md

@@ -0,0 +1,84 @@
+---
+date: 2026-03-23
+topic: plan-review-personas
+---
+
+# Persona-Based Plan Review for document-review
+
+## Problem Frame
+
+The `document-review` skill currently uses a single-voice evaluator with five generic criteria (Clarity, Completeness, Specificity, Appropriate Level, YAGNI). This catches surface-level issues but misses role-specific concerns: a security engineer, product leader, and design reviewer each see different problems in the same plan. The ce:review skill already demonstrates that multi-persona review produces richer, more actionable feedback for code. The same architecture should apply to plan review.
+
+## Requirements
+
+- R1. Replace the current single-voice `document-review` with a persona pipeline that dispatches specialized reviewer agents in parallel against the target document.
+
+- R2. Implement 2 always-on personas that run on every document review:
+  - **coherence**: Internal consistency, contradictions, terminology drift, structural issues, ambiguity. Checks whether readers would diverge on interpretation.
+  - **feasibility**: Can this actually be built? Architecture decisions, external dependencies, performance requirements, migration strategies. Absorbs the "tech-plan implementability" angle (can an implementer code from this?).
+
+- R3. Implement 4 conditional personas that activate based on document content analysis:
+  - **product-lens**: Activates when the document contains user-facing features, market claims, scope decisions, or prioritization. Opens with a "premise challenge" -- 3 diagnostic questions that challenge whether the plan solves the right problem. Asks: "What's the 10-star version? What's the narrowest wedge that proves demand?"
+  - **design-lens**: Activates when the document contains UI/UX work, frontend changes, or user flows. Uses a "rate 0-10 and describe what 10 looks like" dimensional rating method. Rates design dimensions concretely, identifies what "great" looks like for each.
+  - **security-lens**: Activates when the document contains auth, data handling, external APIs, or payments. Evaluates threat model at the plan level, not code level. Surfaces what the plan fails to account for.
+  - **scope-guardian**: Activates when the document contains multiple priority levels, unclear boundaries, or goals that don't align with requirements. Absorbs the "skeptic" angle -- challenges unnecessary complexity, premature abstractions, and frameworks ahead of need. Opens with a "what already exists?" check against the codebase.
+
+- R4. The skill auto-detects which conditional personas are relevant by analyzing the document content. No user configuration required for persona selection.
+
+- R5. Hybrid action model after persona findings are synthesized:
+  - **Auto-fix**: Document quality issues (contradictions, terminology drift, structural problems, missing details that can be inferred). These are unambiguously improvements.
+  - **Present for user decision**: Strategic/product questions (problem framing, scope challenges, priority conflicts, "is this the right thing to build?"). These require human judgment.
+
+- R6. Each persona returns structured findings with confidence scores. The orchestrator deduplicates overlapping findings across personas and synthesizes into a single prioritized report.
+
+- R7. Maintain backward compatibility with all existing callers:
+  - `ce-brainstorm` Phase 4 "Review and refine" option
+  - `ce-plan` / `ce-plan-beta` post-generation "Review and refine" option
+  - `deepen-plan-beta` post-deepening "Review and refine" option
+  - Standalone invocation
+  - Returns "Review complete" when done, as callers expect
+
+- R8. Pipeline-compatible: When called from automated pipelines (e.g., future lfg/slfg integration), auto-fixes run silently and only genuinely blocking strategic questions surface to the user.
+
+## Success Criteria
+
+- Running document-review on a plan surfaces role-specific issues that the current single-voice evaluator misses (e.g., security gaps, product framing problems, scope concerns).
+- Conditional personas activate only when relevant -- a backend refactor plan does not spawn design-lens.
+- Auto-fix changes improve the document without requiring user approval for every edit.
+- Strategic findings are presented as clear questions, not vague observations.
+- All existing callers (brainstorm, plan, plan-beta, deepen-plan-beta) work without modification.
+
+## Scope Boundaries
+
+- Not adding new callers or pipeline integrations beyond maintaining existing ones.
+- Not changing how deepen-plan-beta works (it strengthens with research; document-review reviews for issues).
+- Not adding user configuration for persona selection (auto-detection only for now).
+- Not inventing new review frameworks -- incorporating established review patterns (premise challenge, dimensional rating, existing-code check) into the respective personas.
+
+## Key Decisions
+
+- **Replace, don't layer**: document-review is fully replaced by the persona pipeline, not enhanced with an optional mode. Simpler mental model, one behavior.
+- **2 always-on + 4 conditional**: Coherence and feasibility run on every document. Product-lens, design-lens, security-lens, and scope-guardian activate based on content. Keeps cost proportional to document complexity.
+- **Hybrid action model**: Auto-fix document quality issues, present strategic questions. Matches the natural split between what personas surface.
+- **Absorb skeptic into scope-guardian**: Both challenge whether the plan is right-sized. One persona with both angles avoids redundancy.
+- **Absorb tech-plan implementability into feasibility**: Both ask "can this work?" One persona with both angles.
+- **Review patterns as persona behavior, not separate mechanisms**: Premise challenge goes into product-lens, dimensional rating goes into design-lens, existing-code check goes into scope-guardian.
+
+## Dependencies / Assumptions
+
+- Assumes the ce:review agent orchestration pattern (parallel dispatch, synthesis, dedup) can be adapted for plan review without fundamental changes.
+- Assumes plan/requirements documents are text-based and contain enough signal for content-based conditional persona selection.
+
+## Outstanding Questions
+
+### Deferred to Planning
+
+- [Affects R6][Technical] What is the exact structured output format for persona findings? Should it mirror ce:review's P1/P2/P3 severity model or use a different classification?
+- [Affects R4][Needs research] What content signals reliably detect each conditional persona's relevance? Need to define the heuristics (keyword-based, section-based, or semantic).
+- [Affects R1][Technical] Should personas be implemented as compound-engineering agents (like code review agents) or as inline prompt sections within the skill? Agents enable parallel dispatch; inline is simpler.
+- [Affects R5][Technical] How should the auto-fix mechanism work -- direct inline edits like current document-review, or a separate "apply fixes" pass after synthesis?
+- [Affects R7][Technical] Do any of the 4 existing callers need minor updates to handle the new output format, or is the "Review complete" contract sufficient?
+
+## Next Steps
+
+-> /ce:plan for structured implementation planning

docs/brainstorms/2026-03-25-config-storage-redesign-requirements.md

@@ -0,0 +1,172 @@
+---
+date: 2026-03-25
+topic: config-storage-redesign
+---
+
+# Config and Worktree-Safe Storage Redesign
+
+## Problem Frame
+
+The current branch improves `/ce-doctor` and `/ce-setup`, but it still assumes two foundations that do not hold up:
+
+1. Plugin state lives inside the repo under `.context/compound-engineering/` or `todos/`, which breaks across git worktrees and Conductor-managed parallel checkouts.
+2. Older plugin flows wrote `compound-engineering.local.md`, and parts of the repo still reference it, but main no longer treats review-agent selection as an active setup concern. Any new repo/user-level config system should not revive that removed model.
+
+This work is broader than dependency setup alone. It needs one coherent model for:
+
+- user-level defaults
+- repo-level overrides
+- machine-local overrides
+- worktree-safe durable storage
+- setup and doctor behavior
+- skill instructions, docs, and tests that currently hardcode `compound-engineering.local.md` or `.context/compound-engineering/...`
+
+Terminology for this document:
+
+- `user_state_dir` = the user-level Compound Engineering directory, defaulting to `~/.compound-engineering`
+- `repo_state_dir` = the repo-local Compound Engineering directory at `<repo>/.compound-engineering`
+- per-project storage path = `<user_state_dir>/projects/<project-slug>/`
+
+## Consolidation Notes
+
+This document is the active consolidated requirements doc for the setup, config, and worktree-safe storage work. It replaces the earlier setup-dependency-management and todo-path-consolidation brainstorm docs and incorporates the external worktree-safe storage draft from the parallel `gwangju` workspace.
+
+It changes the direction of two earlier efforts:
+
+- The dependency-management work remains in scope, but `/ce-setup` can no longer write `compound-engineering.local.md`; any surviving YAML config is optional and minimal.
+- The todo-path consolidation work is superseded by home-directory storage. The dual-read migration logic still matters for durable todo files, but `.context/compound-engineering/todos/` is no longer the end state.
+
+## Requirements
+
+- R1. Any new plugin config introduced by this work must use plain YAML files under `repo_state_dir`, specifically `config.yaml` and `config.local.yaml`. Config is data, not a markdown document.
+- R2. Config must support a three-layer cascade with `local > project > global` precedence and first-found wins per key:
+  - `<user_state_dir>/config.yaml`
+  - `<repo_state_dir>/config.yaml`
+  - `<repo_state_dir>/config.local.yaml`
+- R3. The config model must persist only active plugin-level behavior that truly needs durable storage, starting with minimal compatibility metadata if such metadata is still needed after planning. Deterministic path derivation under `user_state_dir` is runtime logic, not config data.
+- R4. The new config model must not reintroduce removed review-agent selection or review-context storage behavior. Reviewer selection is now automatic in `/ce:review`, and project-specific guidance belongs in `CLAUDE.md` or `AGENTS.md`, not plugin-managed config files.
+- R5. The YAML config shape may reorganize keys (for example, grouping review-related settings under a `review` object), but any such reshape must be applied consistently across all skills, docs, and tests that read or write config.
+- R6. The new config format must include only the minimum compatibility metadata needed for the plugin to decide whether `/ce-setup` must be run again.
+- R7. Compatibility checks must not rely only on plugin semver. If explicit versioning is needed, prefer a single setup or config contract revision that answers the practical question "is rerunning `/ce-setup` required?" Optional diagnostic metadata may be stored separately, but the requirements should not assume multiple independent version counters unless planning proves they are necessary.
+- R8. `/ce-setup` must treat legacy `compound-engineering.local.md` as obsolete. If the surviving CE contract still requires machine-local persisted state, `/ce-setup` may write `repo_state_dir/config.local.yaml`; otherwise it should not invent stored values just to mirror deterministic runtime path derivation. Because the legacy file no longer contains any valid first-class CE settings, `/ce-setup` should explain that it is obsolete and delete it as part of cleanup rather than attempting a semantic migration.
+- R9. `/ce-setup` must be the canonical place that executes config cleanup and any remaining compatibility migration. This flow should be safe to re-run, and it should handle at least these cases:
+  - legacy `compound-engineering.local.md` exists and no repo-local CE files exist yet
+  - legacy `compound-engineering.local.md` exists alongside `repo_state_dir/config.local.yaml`
+  - no repo-local CE files exist yet, but deterministic storage derivation still works
+- R10. When legacy `compound-engineering.local.md` and new repo-local CE files both exist, the new CE contract is authoritative. `/ce-setup` should explain that the legacy file is obsolete and delete it rather than attempting to merge removed settings back into the new model.
+
+- R11. `AGENTS.md` must define the config/storage contract section as a standard skill authoring criterion: every skill should include the approved compact header even if that specific skill does not currently consume config values, so the contract stays consistent across the plugin.
+- R12. The standard config section and its instructions must be coding-agent cross-compatible. They must not assume Claude Code-only or Codex-only tool names, interaction patterns, or permission models.
+- R13. The standard config section must be written to optimize for speed and execution reliability:
+  - prefer a minimal number of reads/tool calls
+  - avoid unnecessary shell fallbacks once config is established
+  - reduce permission prompts where the platform makes that possible
+  - keep wording concise so agents are more likely to execute it correctly
+- R14. Independently invocable skills that depend on config or storage must use one standard full preamble that:
+  - prefers caller-passed resolved values
+  - deterministically resolves `repo_state_dir`, `user_state_dir`, and the per-project storage path
+  - reads local, project, and global YAML layers with the same precedence rules when those layers exist
+  - warns and routes to `/ce-setup` when migration or rerun is needed
+  - continues with degraded behavior rather than writing to legacy or guessed fallback paths when canonical config or storage cannot be resolved safely
+  `AGENTS.md` must also define and enforce the delegation rule: when a parent skill spawns an agent that needs configuration or storage values, the parent skill must pass the resolved values into the agent prompt rather than making the spawned agent re-resolve them unless that agent is independently invocable.
+- R15. Migration warning behavior must be centralized rather than duplicated across the entire plugin. A small set of core entry skills, including `/ce-setup`, `/ce-doctor`, `/ce:brainstorm`, `/ce:plan`, `/ce:work`, and `/ce:review`, must detect legacy-only or conflicting config states and direct the user to run `/ce-setup` to migrate. Non-core skills should not each implement their own migration flow.
+- R16. Core entry skills and `/ce-doctor` must use the compatibility metadata to distinguish the actionable states that matter to the user:
+  - no new config exists yet
+  - legacy-only or conflicting config exists and `/ce-setup` must migrate it
+  - new config exists but is below the required contract and `/ce-setup` must be rerun
+  - config is current and no rerun is needed
+
+- R17. All durable plugin storage must resolve outside the repo tree under `user_state_dir`, with this fallback chain for determining `user_state_dir`:
+  - `$COMPOUND_ENGINEERING_HOME`
+  - `$XDG_DATA_HOME/compound-engineering` when `XDG_DATA_HOME` is set
+  - `~/.compound-engineering`
+- R18. Durable per-project storage must live under `<user_state_dir>/projects/<project-slug>/`, where the slug is deterministic and stable across worktrees of the same repo.
+- R19. Project identity must resolve from shared repo identity so all worktrees for the same repo share the same per-project storage path under `user_state_dir`. The primary identity source is `git rev-parse --path-format=absolute --git-common-dir`, and the directory-safe slug should be derived as `<sanitized-repo-name>-<short-hash>`. Non-git contexts must have a deterministic fallback.
+- R20. The standard full preamble must be sufficient for independently invocable skills to deterministically resolve the canonical per-project storage path without requiring `/ce-setup` to pre-write that path into config.
+- R21. Skills that read or write durable plugin state must use the per-project storage path under `user_state_dir` instead of repo-local `.context/compound-engineering/...` or `todos/` paths.
+- R22. Durable todo files must retain legacy read compatibility from repo-local `todos/` and `.context/compound-engineering/todos/` until they drain naturally. New todo writes must go only to `<user_state_dir>/projects/<project-slug>/todos/`.
+- R23. Per-run scratch and run-artifact directories do not need active migration from repo-local `.context/compound-engineering/...`; new writes move to `<user_state_dir>/projects/<project-slug>/<workflow>/...`.
+
+- R24. `/ce-doctor` must remain a standalone entry point and expand from dependency/env checks to also report config and storage health:
+  - resolved config layers
+  - resolved `user_state_dir`
+  - resolved `repo_state_dir`
+  - resolved per-project storage path
+  - presence of legacy `compound-engineering.local.md`
+  - whether no repo-local CE file exists yet
+  - whether setup attention is needed because a legacy file still exists or compatibility metadata is stale
+  - whether rerunning setup is required because the stored compatibility metadata is below the required contract
+  - whether `.compound-engineering/config.local.yaml` is safely gitignored
+- R25. `/ce-doctor` must continue to use a centralized dependency registry that lists known CLIs, MCP-backed capabilities, related environment variables, install guidance, tiering, and the skills/agents that depend on them.
+- R26. `/ce-doctor` remains informational only. It reports dependency, env, config, and storage status, but it does not install tools or mutate user config beyond diagnostics.
+- R27. `/ce-setup` must continue to include the dependency and environment flow already designed in this branch, but its output and guidance must target the new storage contract and any surviving YAML config state without inventing persisted path values that skills can derive deterministically.
+- R28. If `.compound-engineering/config.local.yaml` is part of the surviving CE contract and is not safely gitignored, `/ce-setup` must explain why that file is machine-local and offer to add an appropriate `.gitignore` entry for it.
+- R29. `/ce-setup` must present missing installable dependencies by tier, offer installation one item at a time with user approval, verify each install, and prompt for related environment variables at the appropriate point in the flow.
+- R30. For dependencies with both MCP and CLI paths, diagnostics and setup must detect MCP availability first, then CLI availability, and only offer CLI installation if neither satisfies the dependency.
+- R31. Dependency and env checks must always scan fresh on each run rather than relying on persisted installation state.
+
+- R32. Skill content, docs, and tests must stop treating `.context/compound-engineering/...` and `compound-engineering.local.md` as the stable contract.
+- R33. The config and storage contract must stay tool-agnostic across Claude Code, Codex, Gemini CLI, OpenCode, Copilot, and Conductor worktrees. This work should not introduce new provider-specific config paths.
+
+## Success Criteria
+
+- A user can run `/ce-setup` in the main checkout or any worktree and end up with the same resolved project storage location.
+- Independently invocable skills that need CE state can derive the same canonical per-project storage path without requiring `/ce-setup` to pre-write that path.
+- Users on the legacy config format get a clear migration path through `/ce-setup` without needing every individual skill to invent its own migration behavior.
+- Core skills and `/ce-doctor` can determine whether `/ce-setup` must run again without relying on raw plugin semver comparisons or multiple unnecessary version counters.
+- Todos and other durable workflow artifacts remain available across worktrees without symlinks, git hooks, or manual copying.
+- Existing users with repo-local todo files do not lose access to unresolved work.
+- Legacy `compound-engineering.local.md` files are cleaned up by `/ce-setup` after a brief explanation, without reviving removed review-agent selection behavior.
+- `/ce-doctor` can explain both dependency gaps and config/storage misconfiguration in one report.
+- `/ce-setup` can bring `.compound-engineering/config.local.yaml` under gitignore safely instead of only warning later.
+- The dependency registry remains the single source of truth for `/ce-doctor` and `/ce-setup` rather than splitting dependency metadata across multiple docs or skills.
+- Provider conversion tests and plugin docs reflect the new contract instead of the old file/path names.
+
+## Scope Boundaries
+
+- Do not add a full team-managed authoring workflow for tracked project config in `/ce-setup`; reading the project layer is in scope, authoring it is a separate effort.
+- Do not auto-migrate per-run scratch or historical run artifacts out of `.context/compound-engineering/...`.
+- Do not add storage garbage collection or project-directory pruning in this change.
+- Do not preserve markdown-frontmatter config as a long-term supported format after migration; legacy support is for import/migration, not dual-write.
+- Do not introduce provider-specific config directories for this feature.
+- Do not auto-install dependencies without explicit user approval.
+- Do not expand this work into project dependency management such as `bundle install`, `npm install`, or app-specific environment setup.
+
+## Key Decisions
+
+- **Home-directory storage is the durable answer:** repo-local `.context` is fine for scratch in a single checkout, but it is the wrong primitive for shared multi-worktree state.
+- **Plain YAML replaces the legacy markdown config format:** if this work introduces plugin-managed config, it should do so with files in `repo_state_dir`, not by extending `compound-engineering.local.md`.
+- **Legacy review config is not the target model:** main has already removed setup-managed reviewer selection. The new config system should focus on current setup-owned state such as storage and compatibility metadata, not on recreating reviewer preferences in a new file.
+- **Compatibility metadata should stay minimal:** plugin semver alone is too coarse, but the fix is not to add version fields everywhere. Keep only the metadata needed to answer whether `/ce-setup` must run again.
+- **Migration should have one owner:** `/ce-setup` should perform migration, `/ce-doctor` should report migration state, and a small set of entry skills should warn. Spreading migration logic across every skill creates drift and inconsistent user experience.
+- **Todo migration deserves special handling:** unlike per-run artifacts, todo files have a multi-session lifecycle. Read compatibility is worth keeping during the transition.
+- **Standard preamble, not universal prompt bloat:** use one shared config-loading pattern for independently invocable config/storage consumers and have parent skills pass resolved values to delegates. Requiring every skill to load config even when it does nothing with it adds carrying cost without enough value.
+- **Standard section belongs in AGENTS.md:** the skill-level config instructions should be codified as a repo authoring rule so future skills inherit the same structure instead of drifting.
+- **Cross-agent and low-friction wording matters:** the config section should be written against capability classes, minimal reads, and low-prompt execution patterns so it works well across Claude Code, Codex, Gemini, OpenCode, Copilot, and Conductor.
+- **`/ce-doctor` and `/ce-setup` stay coupled but distinct:** doctor diagnoses; setup installs/configures. The new architecture should deepen that relationship, not replace it.
+- **The dependency design from this branch carries forward:** registry-driven checks, tiered installs, env var prompting, and MCP-first detection still belong in scope. They just need to target the new config/storage contract.
+- **Gitignore safety is part of the feature, not a follow-up:** if `/ce-setup` writes `.compound-engineering/config.local.yaml` into repos, the plugin must also verify that users will not accidentally commit it. The gitignore rule should target that machine-local file, not the entire `.compound-engineering/` directory.
+
+## Dependencies / Assumptions
+
+- The current `/ce-doctor` dependency registry and install flow remain the starting point for the dependency portion of this work.
+- Skills and docs that currently reference `.context/compound-engineering/...` or `compound-engineering.local.md` will need an inventory-based update pass.
+- Converter and contract tests that assert old config names or old storage paths are part of the affected surface, not incidental cleanup.
+- `git worktree` metadata is available in normal git repos; planning still needs to define the exact fallback behavior for non-git contexts and edge cases.
+
+## Outstanding Questions
+
+### Deferred to Planning
+
+- [Affects R3][Technical] Choose the exact YAML shape for any surviving setup-owned config such as compatibility metadata and any future plugin-level keys that still belong in plugin-managed config.
+- [Affects R5][Technical] Define the smallest compatibility metadata shape that reliably tells the plugin whether `/ce-setup` must run again, and add extra diagnostic metadata only if it materially improves behavior.
+- [Affects R15][Technical] Decide when a plugin change should bump the setup or migration requirement versus when it should be treated as backward-compatible.
+- [Affects R17][Technical] Define the precise slugging and fallback algorithm for git repos, linked worktrees, and non-git directories.
+- [Affects R21][Technical] Decide how long legacy todo read compatibility remains and where to document eventual removal.
+- [Affects R13][Technical] Build the inventory of independently invocable skills that need direct config/storage loading versus parent-passed values.
+- [Affects R23][Technical] Define the doctor output format for config/storage warnings and migration guidance.
+- [Affects R30][Needs research] Inventory all docs, tests, and conversion fixtures that encode the old config/storage contract.
+
+## Next Steps
+
+-> `/ce:plan` for a phased implementation plan that starts by codifying the new config schema and migration strategy, then updates `/ce-setup` and `/ce-doctor`, then migrates storage consumers and tests.

docs/brainstorms/2026-03-25-vonboarding-skill-requirements.md

@@ -0,0 +1,62 @@
+---
+date: 2026-03-25
+topic: onboarding-skill
+---
+
+# Onboarding: Codebase Onboarding Document Generator
+
+## Problem Frame
+
+Onboarding is a general problem in software, but it is more acute in fast-moving codebases where code is written faster than documentation — whether through AI-assisted development, rapid prototyping, or simply a team that ships faster than it documents. The traditional assumption that the creator can explain the codebase breaks down when they didn't fully understand it to begin with, or when the codebase has evolved beyond any one person's mental model. New team members (and AI agents brought into the project) are left without the mental model they need to contribute effectively.
+
+The primary audience is human developers. A document that works for human comprehension is also effective as agent context, but the inverse is not true.
+
+## Requirements
+
+- R1. A skill named `onboarding` that crawls a repository and generates `ONBOARDING.md` at the repo root
+- R2. The skill always regenerates the full document from scratch — no surgical updates or diffing against a previous version
+- R3. The document has a fixed filename (`ONBOARDING.md`) so the skill can detect whether one already exists; existence is the only state — no separate mode flag
+- R4. The document contains exactly five sections, each earning its place by answering a question a new contributor will ask in their first hour:
+  - **What is this thing?** — Purpose, who it's for, what problem it solves
+  - **How is it organized?** — Architecture, key modules, how they connect, and what the system depends on externally (databases, APIs, services, env vars)
+  - **Key concepts and abstractions** — The vocabulary and architectural patterns needed to talk about and reason about this codebase
+  - **Primary flow** — One concrete path through the system showing how the pieces connect (the main thing the app does)
+  - **Where do I start?** — Dev setup, how to run it, where to make common types of changes
+- R5. During the crawl, if `docs/solutions/` or other existing documentation is discovered and is directly relevant to a section's content, link to it inline within that section. Do not create a separate references/further-reading section. If no relevant docs exist, the document stands on its own without mentioning their absence.
+- R6. The document is written for human comprehension first — clear prose, not agent-formatted structured data
+- R7. Use visual aids — ASCII diagrams, markdown tables — where they improve readability over prose. Architecture overviews and flow traces especially benefit from diagrams.
+- R8. Use proper markdown formatting throughout — backticks for file names, paths, commands, code references, and technical terms. Consistent styling maximizes legibility.
+
+## Success Criteria
+
+- A new contributor can read `ONBOARDING.md` and understand the codebase well enough to start making changes without needing the creator to explain it
+- The document is useful even when the creator themselves doesn't fully understand the architecture
+- Running the skill again on an evolved codebase produces an accurate, current document (no stale information carried over)
+
+## Scope Boundaries
+
+- Does not attempt to infer or fabricate design rationale ("why was X chosen over Y") — the creator may not know, and presenting guesses as fact is worse than saying nothing
+- Does not assess fragility or risk areas — that requires judgment about production behavior the agent doesn't have
+- Does not generate README.md, CLAUDE.md, AGENTS.md, or any other document — only `ONBOARDING.md`
+- Does not preserve hand-edits from a previous version on regeneration — if users want durable authored context, it belongs in other docs (which the skill may discover and link to)
+- No `ce:` prefix — this is a standalone utility skill, not part of the core workflow
+
+## Key Decisions
+
+- **Always regenerate, never update**: Reading the old document to update it means the agent does two jobs (understand the codebase + fact-check the old doc). That's slower and more error-prone than regenerating.
+- **Five sections, no more**: Every section must earn its place by answering a question a new person will actually ask. No speculative sections "just in case."
+- **Inline linking only**: Existing docs are surfaced within relevant sections, not collected in an appendix. This is opportunistic — works fine when nothing exists to link to.
+- **Human-first writing**: The document targets human readers. Agent utility is a natural side effect of clear prose, not a separate design goal.
+
+## Outstanding Questions
+
+### Deferred to Planning
+
+- [Affects R1][Technical] How should the skill orchestrate the crawl — single-pass or dispatch sub-agents for different sections?
+- [Affects R4][Technical] What crawl strategy produces the best "Primary flow" section — entry point tracing, route analysis, or something else?
+- [Affects R4][Needs research] What's the right depth/length target for each section to be useful without becoming a wall of text?
+- [Affects R5][Technical] What heuristic determines whether a discovered doc is "directly relevant" to a section versus noise?
+
+## Next Steps
+
+-> `/ce:plan` for structured implementation planning

docs/brainstorms/2026-03-26-merge-deepen-into-plan-requirements.md

@@ -0,0 +1,56 @@
+---
+date: 2026-03-26
+topic: merge-deepen-into-plan
+---
+
+# Merge Deepen-Plan Into ce:plan
+
+## Problem Frame
+
+The ce:plan and deepen-plan skills form a sequential workflow where the user is offered a choice ("want to deepen?") that they can't evaluate better than the agent can. When deepen-plan runs, it already evaluates whether deepening is warranted and gates itself accordingly. The user decision adds friction without adding value.
+
+With current model capabilities, the original concern about over-investing in planning is no longer a meaningful risk — the deepening skill already self-gates on scope and confidence scoring.
+
+## Requirements
+
+- R1. ce:plan automatically evaluates and deepens its own output after the initial plan is written, without asking the user for approval.
+- R2. When deepening runs, ce:plan reports what sections it's strengthening and why (transparency without requiring a decision).
+- R3. Deepening is skipped for Lightweight plans unless high-risk topics are detected (preserving the existing gate logic from deepen-plan).
+- R4. For Standard and Deep plans, ce:plan scores confidence gaps using deepen-plan's checklist-first, risk-weighted scoring. If no gaps exceed the threshold, it reports "confidence check passed" and moves on.
+- R5. When gaps are found, ce:plan dispatches targeted research agents (deepen-plan's deterministic agent mapping) to strengthen only the weak sections.
+- R6. The deepen-plan skill is removed as a standalone command. Re-deepening an existing plan is handled by re-running ce:plan in resume mode. In resume mode, ce:plan applies the same confidence-gap evaluation as on a fresh plan — it deepens only if gaps warrant it, unless the user explicitly requests deepening.
+- R7. The "Run deepen-plan" post-generation option in ce:plan is removed. Post-generation options become simpler.
+
+## Success Criteria
+
+- ce:plan produces plans at least as strong as the old ce:plan + manual deepen-plan flow
+- Users never need to decide whether to deepen — the agent handles it
+- Users see what's being strengthened (no black box)
+- One fewer skill to know about, simpler workflow
+- No regression in plan quality for any scope tier (Lightweight, Standard, Deep)
+
+## Scope Boundaries
+
+- This does not change what deepening does — only where it lives and who decides to run it
+- No changes to the deepening logic itself (confidence scoring, agent selection, section rewriting)
+- No changes to ce:brainstorm or ce:work
+- The planning boundary (no code, no commands) is preserved
+- deepen-plan scratch space (`.context/compound-engineering/deepen-plan/`) moves under ce:plan's namespace
+
+## Key Decisions
+
+- **Agent decides, user informed**: The agent evaluates whether deepening adds value and proceeds automatically. The user sees a brief status message about what's being strengthened but doesn't approve it. Why: the user can't evaluate this better than the agent, and the existing gate logic already prevents wasteful deepening.
+- **No standalone deepen command**: Re-deepening existing plans is handled through ce:plan's resume mode. Why: simpler mental model, one entry point for all planning work.
+- **Absorb, don't invoke**: The deepening logic is folded into ce:plan as a new phase rather than ce:plan invoking deepen-plan as a sub-skill. Why: eliminates a skill boundary and simplifies maintenance.
+
+## Outstanding Questions
+
+### Deferred to Planning
+
+- [Affects R1][Technical] Where exactly in ce:plan's phase structure should the confidence check and deepening phase land — as a new Phase 5 before the current post-generation options, or integrated into Phase 4 (plan writing)?
+- [Affects R6][Technical] How should ce:plan's resume mode distinguish "resume an incomplete plan" from "re-deepen a completed plan"? Likely frontmatter-based (`deepened: YYYY-MM-DD` presence).
+- [Affects R5][Technical] Should deepen-plan's artifact-backed research mode (for larger scope) use `.context/compound-engineering/ce-plan/deepen/` or a per-run subdirectory?
+
+## Next Steps
+
+-> /ce:plan for structured implementation planning

docs/brainstorms/2026-03-27-ce-skill-prefix-rename-requirements.md

@@ -0,0 +1,232 @@
+---
+date: 2026-03-27
+topic: ce-skill-prefix-rename
+---
+
+# Consistent `ce-` Prefix for All Skills and Agents
+
+## Problem Frame
+
+As the Claude Code plugin ecosystem grows, generic skill names like `setup`, `plan`, `review`, and `frontend-design` collide when users have multiple plugins installed. Typing `/plan` surfaces every plugin's plan skill, forcing users to scan descriptions. Agent names also collide across plugins — generic names like `adversarial-reviewer` or `security-reviewer` are common enough that multiple plugins could define them. The compound-engineering plugin currently uses an inconsistent mix: 8 core workflow skills have a `ce:` colon prefix, while 33 others have no prefix at all. Agents use verbose 3-segment references (`compound-engineering:<category>:<agent-name>`) that are cumbersome and can be simplified now that agents will have a unique `ce-` prefix. This creates collision risk, a confusing naming taxonomy, and unnecessarily verbose agent references.
+
+Standardizing on a `ce-` hyphen prefix for all owned skills and agents eliminates collisions, creates a consistent namespace, simplifies agent references, and removes the colon character that requires filesystem sanitization on Windows.
+
+Related: [GitHub Issue #337](https://github.com/EveryInc/compound-engineering-plugin/issues/337)
+
+## Requirements
+
+When doing renames of files and folders, you are required to use `git mv` whenever possible for simplicity and explicit intent and history preservation.  You can fallback provided you notify when it happens and why.
+
+### Naming Rules
+
+- R1. All compound-engineering-owned skills and agents adopt a `ce-` hyphen prefix
+- R2. Skills currently using `ce:` colon prefix change to `ce-` hyphen prefix (e.g., `ce:plan` -> `ce-plan`)
+- R3. Skills and Agents currently without a prefix get `ce-` prepended (e.g., `setup` -> `ce-setup`, `frontend-design` -> `ce-frontend-design`, `repo-research-analyst` -> `ce-repo-research-analyst`)
+- R4. `git-*` skills replace the `git-` prefix with `ce-` (e.g., `git-commit` -> `ce-commit`, `git-worktree` -> `ce-worktree`)
+- R5. `report-bug-ce` normalizes to `ce-report-bug` (drops redundant suffix)
+
+### Exclusions
+
+- R6. `agent-browser` and `rclone` are excluded (sourced from upstream, not our skills)
+- R7. `lfg` and `slfg` are excluded from renaming (short memorable workflow entry points), but their internal skill invocations must be updated per R12	
+
+### Propagation
+
+- R8. The skill and agent frontmatter `name:` field must match after rename (no more colon-vs-hyphen divergence). Directories need to reflect the new names as well when applicable.
+- R9. All cross-references updated: skill-to-skill invocations (`/ce:plan` -> `/ce-plan`), fully-qualified references (`/compound-engineering:todo-resolve` -> `/compound-engineering:ce-todo-resolve`), `Skill("compound-engineering:...")` programmatic invocations, prose mentions, skill `description:` frontmatter fields, and intra-skill path references (`${CLAUDE_PLUGIN_ROOT}/skills/<old-name>/...`)
+- R10. Active documentation updated: root README, plugin README, AGENTS.md. Note: the AGENTS.md "Why `ce:`?" rationale section (lines 53-60) needs a conceptual rewrite explaining the `ce-` convention, not just find-and-replace. Historical docs in `docs/` (past brainstorms, plans, solutions) are left as-is -- they are records of past decisions.
+- R11. Agent prompt files updated where they reference skill names.
+- R11b. Skill prompt files updated where they reference Agent names.
+- R11c. Agent references drop the `compound-engineering:` plugin prefix and keep the category. The agent name itself gets the `ce-` prefix. (e.g. `compound-engineering:review:adversarial-reviewer` -> `review:ce-adversarial-reviewer`)
+- R12. lfg and slfg orchestration chains updated to use new skill names (lfg/slfg themselves are not renamed per R7, but their internal skill and agent invocations must reflect new names)
+- R13. Converter infrastructure preserved: `sanitizePathName()` and colon-handling logic stays as future protection, not removed. Add a test assertion that no skill `name:` field contains a colon, so the sanitizer is defense-in-depth rather than a silent workaround.
+- R17. Codex converter's `isCanonicalCodexWorkflowSkill()` and `toCanonicalWorkflowSkillName()` in `src/converters/claude-to-codex.ts` updated to match `ce-` prefix pattern (currently hardcodes `ce:` prefix check). Related test fixtures in `tests/codex-converter.test.ts` and `tests/codex-writer.test.ts` updated accordingly.
+
+### Testing
+
+- R14. Path sanitization tests updated to reflect new naming (collision detection still works)
+- R15. `bun test` passes after all changes
+- R16. `bun run release:validate` passes after all changes
+- R18. Converter test fixtures that hardcode `ce:plan` etc. updated to `ce-plan` where they test compound-engineering plugin behavior. Fixtures testing abstract colon-handling for other plugins may remain.
+- R19. Sanity check and for every skill and agent name, grep to confirm new names are correct and old names do not persist except in historical planning, requirements, etc docs.
+
+---
+
+## Complete Rename Map
+
+### Excluded (no change) - 4 skills
+
+| Current Name | Reason |
+|---|---|
+| `agent-browser` | External/upstream |
+| `rclone` | External/upstream |
+| `lfg` | Exception (memorable name) |
+| `slfg` | Exception (memorable name) |
+
+### `ce:` -> `ce-` (frontmatter only, dirs already match) - 8 skills
+
+| Current Name | New Name | Dir Rename? |
+|---|---|---|
+| `ce:brainstorm` | `ce-brainstorm` | No |
+| `ce:compound` | `ce-compound` | No |
+| `ce:compound-refresh` | `ce-compound-refresh` | No |
+| `ce:ideate` | `ce-ideate` | No |
+| `ce:plan` | `ce-plan` | No |
+| `ce:review` | `ce-review` | No |
+| `ce:work` | `ce-work` | No |
+| `ce:work-beta` | `ce-work-beta` | No |
+
+### `git-*` -> `ce-*` (replace prefix) - 4 skills
+
+| Current Name | New Name | Dir Rename |
+|---|---|---|
+| `git-clean-gone-branches` | `ce-clean-gone-branches` | `git-clean-gone-branches/` -> `ce-clean-gone-branches/` |
+| `git-commit` | `ce-commit` | `git-commit/` -> `ce-commit/` |
+| `git-commit-push-pr` | `ce-commit-push-pr` | `git-commit-push-pr/` -> `ce-commit-push-pr/` |
+| `git-worktree` | `ce-worktree` | `git-worktree/` -> `ce-worktree/` |
+
+### Special normalization - 1 skill
+
+| Current Name | New Name | Dir Rename |
+|---|---|---|
+| `report-bug-ce` | `ce-report-bug` | `report-bug-ce/` -> `ce-report-bug/` |
+
+### Standard prefix addition - 24 skills
+
+| Current Name | New Name | Dir Rename |
+|---|---|---|
+| `agent-native-architecture` | `ce-agent-native-architecture` | `agent-native-architecture/` -> `ce-agent-native-architecture/` |
+| `agent-native-audit` | `ce-agent-native-audit` | `agent-native-audit/` -> `ce-agent-native-audit/` |
+| `andrew-kane-gem-writer` | `ce-andrew-kane-gem-writer` | `andrew-kane-gem-writer/` -> `ce-andrew-kane-gem-writer/` |
+| `changelog` | `ce-changelog` | `changelog/` -> `ce-changelog/` |
+| `claude-permissions-optimizer` | `ce-claude-permissions-optimizer` | `claude-permissions-optimizer/` -> `ce-claude-permissions-optimizer/` |
+| `deploy-docs` | `ce-deploy-docs` | `deploy-docs/` -> `ce-deploy-docs/` |
+| `dhh-rails-style` | `ce-dhh-rails-style` | `dhh-rails-style/` -> `ce-dhh-rails-style/` |
+| `document-review` | `ce-document-review` | `document-review/` -> `ce-document-review/` |
+| `dspy-ruby` | `ce-dspy-ruby` | `dspy-ruby/` -> `ce-dspy-ruby/` |
+| `every-style-editor` | `ce-every-style-editor` | `every-style-editor/` -> `ce-every-style-editor/` |
+| `feature-video` | `ce-feature-video` | `feature-video/` -> `ce-feature-video/` |
+| `frontend-design` | `ce-frontend-design` | `frontend-design/` -> `ce-frontend-design/` |
+| `gemini-imagegen` | `ce-gemini-imagegen` | `gemini-imagegen/` -> `ce-gemini-imagegen/` |
+| `onboarding` | `ce-onboarding` | `onboarding/` -> `ce-onboarding/` |
+| `orchestrating-swarms` | `ce-orchestrating-swarms` | `orchestrating-swarms/` -> `ce-orchestrating-swarms/` |
+| `proof` | `ce-proof` | `proof/` -> `ce-proof/` |
+| `reproduce-bug` | `ce-reproduce-bug` | `reproduce-bug/` -> `ce-reproduce-bug/` |
+| `resolve-pr-feedback` | `ce-resolve-pr-feedback` | `resolve-pr-feedback/` -> `ce-resolve-pr-feedback/` |
+| `setup` | `ce-setup` | `setup/` -> `ce-setup/` |
+| `test-browser` | `ce-test-browser` | `test-browser/` -> `ce-test-browser/` |
+| `test-xcode` | `ce-test-xcode` | `test-xcode/` -> `ce-test-xcode/` |
+| `todo-create` | `ce-todo-create` | `todo-create/` -> `ce-todo-create/` |
+| `todo-resolve` | `ce-todo-resolve` | `todo-resolve/` -> `ce-todo-resolve/` |
+| `todo-triage` | `ce-todo-triage` | `todo-triage/` -> `ce-todo-triage/` |
+
+**Total: 37 skills renamed, 4 excluded (41 skills total)**
+
+### Agent renames - 49 agents
+
+All agents are renamed with `ce-` prefix within their existing category subdirs. The `compound-engineering:` plugin prefix is dropped from references, keeping the `<category>:ce-<agent-name>` format. Category subdirs are preserved for organization.
+
+| Current File | New File | Old Reference | New Reference |
+|---|---|---|---|
+| `agents/design/design-implementation-reviewer.md` | `agents/design/ce-design-implementation-reviewer.md` | `compound-engineering:design:design-implementation-reviewer` | `design:ce-design-implementation-reviewer` |
+| `agents/design/design-iterator.md` | `agents/design/ce-design-iterator.md` | `compound-engineering:design:design-iterator` | `design:ce-design-iterator` |
+| `agents/design/figma-design-sync.md` | `agents/design/ce-figma-design-sync.md` | `compound-engineering:design:figma-design-sync` | `design:ce-figma-design-sync` |
+| `agents/docs/ankane-readme-writer.md` | `agents/docs/ce-ankane-readme-writer.md` | `compound-engineering:docs:ankane-readme-writer` | `docs:ce-ankane-readme-writer` |
+| `agents/document-review/adversarial-document-reviewer.md` | `agents/document-review/ce-adversarial-document-reviewer.md` | `compound-engineering:document-review:adversarial-document-reviewer` | `document-review:ce-adversarial-document-reviewer` |
+| `agents/document-review/coherence-reviewer.md` | `agents/document-review/ce-coherence-reviewer.md` | `compound-engineering:document-review:coherence-reviewer` | `document-review:ce-coherence-reviewer` |
+| `agents/document-review/design-lens-reviewer.md` | `agents/document-review/ce-design-lens-reviewer.md` | `compound-engineering:document-review:design-lens-reviewer` | `document-review:ce-design-lens-reviewer` |
+| `agents/document-review/feasibility-reviewer.md` | `agents/document-review/ce-feasibility-reviewer.md` | `compound-engineering:document-review:feasibility-reviewer` | `document-review:ce-feasibility-reviewer` |
+| `agents/document-review/product-lens-reviewer.md` | `agents/document-review/ce-product-lens-reviewer.md` | `compound-engineering:document-review:product-lens-reviewer` | `document-review:ce-product-lens-reviewer` |
+| `agents/document-review/scope-guardian-reviewer.md` | `agents/document-review/ce-scope-guardian-reviewer.md` | `compound-engineering:document-review:scope-guardian-reviewer` | `document-review:ce-scope-guardian-reviewer` |
+| `agents/document-review/security-lens-reviewer.md` | `agents/document-review/ce-security-lens-reviewer.md` | `compound-engineering:document-review:security-lens-reviewer` | `document-review:ce-security-lens-reviewer` |
+| `agents/research/best-practices-researcher.md` | `agents/research/ce-best-practices-researcher.md` | `compound-engineering:research:best-practices-researcher` | `research:ce-best-practices-researcher` |
+| `agents/research/framework-docs-researcher.md` | `agents/research/ce-framework-docs-researcher.md` | `compound-engineering:research:framework-docs-researcher` | `research:ce-framework-docs-researcher` |
+| `agents/research/git-history-analyzer.md` | `agents/research/ce-git-history-analyzer.md` | `compound-engineering:research:git-history-analyzer` | `research:ce-git-history-analyzer` |
+| `agents/research/issue-intelligence-analyst.md` | `agents/research/ce-issue-intelligence-analyst.md` | `compound-engineering:research:issue-intelligence-analyst` | `research:ce-issue-intelligence-analyst` |
+| `agents/research/learnings-researcher.md` | `agents/research/ce-learnings-researcher.md` | `compound-engineering:research:learnings-researcher` | `research:ce-learnings-researcher` |
+| `agents/research/repo-research-analyst.md` | `agents/research/ce-repo-research-analyst.md` | `compound-engineering:research:repo-research-analyst` | `research:ce-repo-research-analyst` |
+| `agents/review/adversarial-reviewer.md` | `agents/review/ce-adversarial-reviewer.md` | `compound-engineering:review:adversarial-reviewer` | `review:ce-adversarial-reviewer` |
+| `agents/review/agent-native-reviewer.md` | `agents/review/ce-agent-native-reviewer.md` | `compound-engineering:review:agent-native-reviewer` | `review:ce-agent-native-reviewer` |
+| `agents/review/api-contract-reviewer.md` | `agents/review/ce-api-contract-reviewer.md` | `compound-engineering:review:api-contract-reviewer` | `review:ce-api-contract-reviewer` |
+| `agents/review/architecture-strategist.md` | `agents/review/ce-architecture-strategist.md` | `compound-engineering:review:architecture-strategist` | `review:ce-architecture-strategist` |
+| `agents/review/cli-agent-readiness-reviewer.md` | `agents/review/ce-cli-agent-readiness-reviewer.md` | `compound-engineering:review:cli-agent-readiness-reviewer` | `review:ce-cli-agent-readiness-reviewer` |
+| `agents/review/cli-readiness-reviewer.md` | `agents/review/ce-cli-readiness-reviewer.md` | `compound-engineering:review:cli-readiness-reviewer` | `review:ce-cli-readiness-reviewer` |
+| `agents/review/code-simplicity-reviewer.md` | `agents/review/ce-code-simplicity-reviewer.md` | `compound-engineering:review:code-simplicity-reviewer` | `review:ce-code-simplicity-reviewer` |
+| `agents/review/correctness-reviewer.md` | `agents/review/ce-correctness-reviewer.md` | `compound-engineering:review:correctness-reviewer` | `review:ce-correctness-reviewer` |
+| `agents/review/data-integrity-guardian.md` | `agents/review/ce-data-integrity-guardian.md` | `compound-engineering:review:data-integrity-guardian` | `review:ce-data-integrity-guardian` |
+| `agents/review/data-migration-expert.md` | `agents/review/ce-data-migration-expert.md` | `compound-engineering:review:data-migration-expert` | `review:ce-data-migration-expert` |
+| `agents/review/data-migrations-reviewer.md` | `agents/review/ce-data-migrations-reviewer.md` | `compound-engineering:review:data-migrations-reviewer` | `review:ce-data-migrations-reviewer` |
+| `agents/review/deployment-verification-agent.md` | `agents/review/ce-deployment-verification-agent.md` | `compound-engineering:review:deployment-verification-agent` | `review:ce-deployment-verification-agent` |
+| `agents/review/dhh-rails-reviewer.md` | `agents/review/ce-dhh-rails-reviewer.md` | `compound-engineering:review:dhh-rails-reviewer` | `review:ce-dhh-rails-reviewer` |
+| `agents/review/julik-frontend-races-reviewer.md` | `agents/review/ce-julik-frontend-races-reviewer.md` | `compound-engineering:review:julik-frontend-races-reviewer` | `review:ce-julik-frontend-races-reviewer` |
+| `agents/review/kieran-python-reviewer.md` | `agents/review/ce-kieran-python-reviewer.md` | `compound-engineering:review:kieran-python-reviewer` | `review:ce-kieran-python-reviewer` |
+| `agents/review/kieran-rails-reviewer.md` | `agents/review/ce-kieran-rails-reviewer.md` | `compound-engineering:review:kieran-rails-reviewer` | `review:ce-kieran-rails-reviewer` |
+| `agents/review/kieran-typescript-reviewer.md` | `agents/review/ce-kieran-typescript-reviewer.md` | `compound-engineering:review:kieran-typescript-reviewer` | `review:ce-kieran-typescript-reviewer` |
+| `agents/review/maintainability-reviewer.md` | `agents/review/ce-maintainability-reviewer.md` | `compound-engineering:review:maintainability-reviewer` | `review:ce-maintainability-reviewer` |
+| `agents/review/pattern-recognition-specialist.md` | `agents/review/ce-pattern-recognition-specialist.md` | `compound-engineering:review:pattern-recognition-specialist` | `review:ce-pattern-recognition-specialist` |
+| `agents/review/performance-oracle.md` | `agents/review/ce-performance-oracle.md` | `compound-engineering:review:performance-oracle` | `review:ce-performance-oracle` |
+| `agents/review/performance-reviewer.md` | `agents/review/ce-performance-reviewer.md` | `compound-engineering:review:performance-reviewer` | `review:ce-performance-reviewer` |
+| `agents/review/previous-comments-reviewer.md` | `agents/review/ce-previous-comments-reviewer.md` | `compound-engineering:review:previous-comments-reviewer` | `review:ce-previous-comments-reviewer` |
+| `agents/review/project-standards-reviewer.md` | `agents/review/ce-project-standards-reviewer.md` | `compound-engineering:review:project-standards-reviewer` | `review:ce-project-standards-reviewer` |
+| `agents/review/reliability-reviewer.md` | `agents/review/ce-reliability-reviewer.md` | `compound-engineering:review:reliability-reviewer` | `review:ce-reliability-reviewer` |
+| `agents/review/schema-drift-detector.md` | `agents/review/ce-schema-drift-detector.md` | `compound-engineering:review:schema-drift-detector` | `review:ce-schema-drift-detector` |
+| `agents/review/security-reviewer.md` | `agents/review/ce-security-reviewer.md` | `compound-engineering:review:security-reviewer` | `review:ce-security-reviewer` |
+| `agents/review/security-sentinel.md` | `agents/review/ce-security-sentinel.md` | `compound-engineering:review:security-sentinel` | `review:ce-security-sentinel` |
+| `agents/review/testing-reviewer.md` | `agents/review/ce-testing-reviewer.md` | `compound-engineering:review:testing-reviewer` | `review:ce-testing-reviewer` |
+| `agents/workflow/bug-reproduction-validator.md` | `agents/workflow/ce-bug-reproduction-validator.md` | `compound-engineering:workflow:bug-reproduction-validator` | `workflow:ce-bug-reproduction-validator` |
+| `agents/workflow/lint.md` | `agents/workflow/ce-lint.md` | `compound-engineering:workflow:lint` | `workflow:ce-lint` |
+| `agents/workflow/pr-comment-resolver.md` | `agents/workflow/ce-pr-comment-resolver.md` | `compound-engineering:workflow:pr-comment-resolver` | `workflow:ce-pr-comment-resolver` |
+| `agents/workflow/spec-flow-analyzer.md` | `agents/workflow/ce-spec-flow-analyzer.md` | `compound-engineering:workflow:spec-flow-analyzer` | `workflow:ce-spec-flow-analyzer` |
+
+**Total: 49 agents renamed in place (category subdirs preserved)**
+
+---
+
+## Success Criteria
+
+- Every owned skill (except the 4 exclusions) has a `ce-` prefix in both directory name and frontmatter
+- Every agent has a `ce-` prefix in filename and frontmatter within its category subdir
+- All cross-references across skills, agents, docs, and orchestration chains use new names
+- All 3-segment agent references (`compound-engineering:<category>:<agent>`) simplified to `<category>:ce-<agent>`
+- `bun test` and `bun run release:validate` pass
+- No colon characters remain in any skill `name:` field (though sanitization infra is preserved)
+- Slash command invocations work with new names (e.g., `/ce-plan`)
+- lfg and slfg orchestration chains reference new skill and agent names (R12)
+- Grep sanity check confirms no old names persist in active code (R19)
+
+## Scope Boundaries
+
+- **Not removing sanitization infrastructure** — `sanitizePathName()` stays as future protection for any colons
+- **Not adding backward-compatibility aliases** — No alias mechanism exists; this is a clean break
+- **Not renaming external skills** — `agent-browser` and `rclone` are upstream
+- **Not renaming lfg/slfg** — Kept as memorable exceptions
+- **Historical docs are not updated** — Past brainstorms, plans, and solutions in `docs/` reference old names; this is expected and acceptable (they're historical records). R10 applies only to active docs (README, AGENTS.md), not historical docs.
+
+## Key Decisions
+
+- **Hyphen over colon**: `ce-` not `ce:` — eliminates filesystem sanitization divergence and is more portable
+- **git-* replaces prefix**: `git-commit` -> `ce-commit` rather than `ce-git-commit` — avoids verbose double-prefix
+- **report-bug-ce normalizes**: Drops redundant `-ce` suffix -> `ce-report-bug`
+- **Agents renamed in place**: Category subdirs preserved for organization. Agent files get `ce-` prefix within their category dir. 3-segment refs drop plugin prefix: `compound-engineering:review:adversarial-reviewer` -> `review:ce-adversarial-reviewer`.
+- **Major version bump**: This is a breaking change; plugin version will bump the major version to signal it.
+- **Clean break, no aliases**: Users learn new names immediately; the old names stop working
+- **Preserve sanitization**: Keep colon-handling code even though no skills currently use colons — future-proofing
+- **git mv required**: All renames use `git mv` for history preservation. Fallback only with notification.
+
+## Dependencies / Assumptions
+
+- Skill directory renames via `git mv` preserve git history. Commit strategy (single vs multiple commits) deferred to planning.
+- lfg/slfg reference other skills both by short name (`/ce:plan`) and fully-qualified (`/compound-engineering:todo-resolve`) — both patterns need updating
+- README may contain stale skill references (e.g., `/sync`) — clean up during R10 documentation pass
+
+## Outstanding Questions
+
+### Deferred to Planning
+
+- [Affects R9][Needs research] Exact inventory of every cross-reference in every SKILL.md, agent file, and doc that needs updating — planner should grep comprehensively
+- [Affects R8][Technical] Should directory renames be done via `git mv` in a single commit or spread across multiple commits for reviewability?
+- [Affects R14, R18][Technical] What specific test assertions reference skill names and need updating? Which test fixtures test compound-engineering behavior (should update) vs abstract colon-handling (may keep)?
+
+## Next Steps
+
+-> `/ce:plan` for structured implementation planning (will itself be renamed to `/ce-plan` as part of this work)

docs/brainstorms/2026-03-28-ce-review-headless-mode-requirements.md

@@ -0,0 +1,58 @@
+---
+date: 2026-03-28
+topic: ce-review-headless-mode
+---
+
+# ce:review Headless Mode
+
+## Problem Frame
+
+ce:review currently has three modes (interactive, autofix, report-only), but all assume some level of direct user interaction or have mode-specific behaviors that don't fit programmatic callers. When another skill needs code review results as structured input, there's no way to invoke ce:review without it trying to prompt a user or applying fixes with interactive-session assumptions.
+
+document-review solved this same problem in PR #425 with a `mode:headless` pattern. ce:review needs the same capability so it can be used as a utility skill by other workflows.
+
+## Requirements
+
+**Argument Parsing**
+- R1. Add `mode:headless` argument, parsed alongside existing mode flags
+
+**Runtime Behavior**
+- R2. In headless mode, apply `safe_auto` fixes silently (matching autofix behavior)
+- R4. No `AskUserQuestion` or other interactive prompts in headless mode
+- R5. End with a clear completion signal so callers can detect when the review is done
+
+**Output Format**
+- R3. Return all non-auto findings (`gated_auto`, `manual`, `advisory`) as structured text output, preserving their original classifications (severity, autofix_class, owner, confidence, evidence[], pre_existing)
+- R6. Follow document-review's structural output pattern (same envelope format, same section headings, similar parsing heuristics) while adapting per-finding fields to ce:review's own schema
+
+## Success Criteria
+
+- Another skill can invoke ce:review with `mode:headless`, receive structured findings, and act on them without any user interaction
+- Output envelope (section headings, severity grouping, completion signal) is structurally consistent with document-review's headless output so callers can use a similar consumption pattern for both, while per-finding fields reflect ce:review's own schema
+
+## Scope Boundaries
+
+- Not changing the existing three modes (interactive, autofix, report-only)
+- Not adding new reviewer personas or changing the review pipeline itself
+- Not building a specific caller workflow in this change — just enabling the capability
+
+## Key Decisions
+
+- **Apply safe_auto fixes in headless**: Matches document-review's pattern where auto-fixes are applied silently and everything else is returned for the caller to handle
+- **Structural consistency with document-review, not schema compatibility**: Same envelope and section headings, but per-finding fields use ce:review's own schema (which has different autofix_class values, owner, pre_existing, etc.). Callers will need skill-aware parsing for individual findings
+
+## Outstanding Questions
+
+### Deferred to Planning
+
+- [Affects R3][Technical] Exact structured output format — should it mirror document-review's text format verbatim, or adapt to ce:review's richer findings schema (which includes fields like `autofix_class`, `evidence[]`, `pre_existing` that document-review doesn't have)?
+- [Affects R1][Technical] How `mode:headless` interacts with the existing mode parsing — is it a fourth mode, or an overlay that modifies report-only/autofix behavior?
+- [Affects R5][Technical] What the completion signal looks like — "Review complete (headless mode)" text, or a more structured envelope?
+- [Affects R2][Technical] Should headless mode write run artifacts (`.context/compound-engineering/ce-review/<run-id>/`) and create durable todo files like autofix, or suppress them like report-only?
+- [Affects R1][Technical] How should headless mode handle checkout/branch switching in Stage 1? Programmatic callers may need the checkout to stay stable (like report-only) even though headless applies fixes (like autofix).
+- [Affects R1][Technical] Error behavior when headless receives conflicting mode flags (e.g., `mode:headless` + existing mode flags) or missing diff scope (no changes, no PR).
+- [Affects R2][Technical] Should headless mode support bounded re-review rounds (max_rounds: 2) like autofix, or be single-pass?
+
+## Next Steps
+
+-> `/ce:plan` for structured implementation planning

docs/brainstorms/2026-03-29-iterative-optimization-loop-requirements.md

@@ -0,0 +1,977 @@
+# Iterative Optimization Loop Skill — Requirements Brainstorm
+
+## Problem Statement
+
+CE has strong knowledge-compounding (learn from past work) and multi-agent review (quality gates), but no skill for **metric-driven iterative optimization** — the pattern where you define a measurable goal, build measurement scaffolding, then run an automated loop that tries many approaches, measures each, keeps improvements, and converges toward the best solution.
+
+### Motivating Example
+
+A project builds issue/PR clusters for a large open-source repo. Currently only ~20% of issues/PRs land in clusters with >1 item. The suspected achievable target is ~95%. Getting there requires testing many hypotheses:
+
+- Extracting signal (unique user-entered text) from noise (PR/issue template boilerplate that makes all vectors too similar)
+- Using issue-to-PR links as a new clustering signal
+- Adjusting similarity thresholds
+- Trying different embedding models or chunking strategies
+- Combining multiple signals (text similarity + link graph + label overlap + author patterns)
+- Pre-filtering or normalizing template sections before embedding
+
+No single hypothesis will get from 20% to 95%. It requires systematic experimentation — trying dozens or hundreds of variations, measuring each, and building on successes.
+
+## Landscape Analysis
+
+### Karpathy's AutoResearch (March 2026, 21k+ stars)
+
+The simplest and most influential model. Core design:
+
+- **One mutable file** (`train.py`) — the agent edits only this
+- **One immutable evaluator** (`prepare.py`) — the agent cannot touch measurement
+- **One instruction file** (`program.md`) — defines objectives, constraints, stopping criteria
+- **One metric** (`val_bpb`) — scalar, lower is better
+- **Linear keep/revert loop**: modify -> commit -> run -> measure -> if improved keep, else `git reset`
+- **History**: `results.tsv` accumulates all experiment results; git log preserves successful commits
+- **Result**: 700 experiments in 2 days, 20 discovered optimizations, ~12 experiments/hour
+
+**Strengths**: Dead simple. Git-native history. Easy to understand and debug.
+**Weaknesses**: Linear — can't explore multiple directions simultaneously. Single scalar metric. No backtracking to earlier promising states.
+
+### AIDE / WecoAI
+
+- **Tree search** in solution space — each script is a node, LLM patches spawn children
+- Can backtrack to any previous node and explore alternatives
+- 4x more Kaggle medals than linear agents on MLE-Bench
+- More complex but better at escaping local optima
+
+### Sakana AI Scientist v2
+
+- **Agentic tree search** with parallel experiment execution
+- VLM feedback for analyzing figures
+- Full paper generation with automated peer review
+- Overkill for code optimization but shows the value of tree-structured exploration
+
+### DSPy (Stanford)
+
+- Automated prompt/weight optimization for LLM programs
+- Bayesian optimization (MIPROv2), iterative feedback (GEPA), coordinate ascent (COPRO)
+- Shows that different optimization strategies suit different problem shapes
+
+### Existing Claude Code AutoResearch Forks
+
+- `uditgoenka/autoresearch` — packages the pattern as a Claude Code skill
+- `autoexp` — generalized for any project with a quantifiable metric
+- Multiple teams report 50-80% improvements over 30-70 iterations overnight
+
+## Key Design Decisions
+
+### 1. Linear vs. Tree Search
+
+| Approach | Pros | Cons |
+|---|---|---|
+| Linear (autoresearch) | Simple, easy to understand, git-native | Can't explore multiple directions, stuck in local optima |
+| Tree search (AIDE) | Can backtrack, explore alternatives | More complex state management, harder to review |
+| Hybrid: linear with manual branch points | Best of both — simple default, user chooses when to fork | Requires user interaction to fork |
+
+**Recommendation**: Start with linear keep/revert (Karpathy model) as the default. Add optional "branch point" support where the user can snapshot the current best and start a new exploration direction. Each direction is its own branch. This keeps the core loop simple while allowing multi-direction exploration when needed.
+
+### 2. What Gets Measured — The Three-Tier Metric Architecture
+
+AutoResearch uses a single scalar metric (val_bpb). That works when you have an objective function with clear ground truth. Most real-world optimization problems don't — especially when the quality of the output requires human judgment.
+
+**Key insight**: Hard scalar metrics are often the wrong optimization target. For clustering, "bigger clusters" isn't inherently better. "Fewer singletons" isn't inherently better. A solution with 35% singletons where every cluster is coherent beats a solution with 5% singletons where clusters are garbage. Hard metrics catch *degenerate* solutions; *quality* requires judgment.
+
+**Three tiers**:
+
+1. **Degenerate-case gates** (hard, cheap, fully automated):
+   - Catch obviously broken solutions before expensive evaluation
+   - Examples: "all items in 1 cluster" (degenerate merge), "all singletons" (degenerate split), "runtime > 10 minutes" (performance regression)
+   - These are fast boolean checks: pass/fail. If any gate fails, the experiment is immediately reverted without running the expensive judge
+   - Think of these as "sanity checks" not "optimization targets"
+
+2. **LLM-as-judge quality score** (the actual optimization target):
+   - For problems where quality requires judgment, this IS the primary metric
+   - Cost-controlled via stratified sampling (not exhaustive)
+   - Produces a scalar score the loop can optimize against
+   - Can include multiple dimensions (coherence, granularity, completeness)
+   - See detailed design below
+
+3. **Diagnostics** (logged for understanding, not gated on):
+   - Distribution stats, counts, histograms
+   - Useful for understanding WHY a judge score changed
+   - Examples: median cluster size, singleton %, largest cluster size, cluster count
+   - Logged in the experiment record but never used for keep/revert decisions
+
+**When to use which configuration**:
+
+| Problem Type | Degenerate Gates | Primary Metric | Example |
+|---|---|---|---|
+| Objective function exists | Yes | Hard metric (scalar) | Build time, test pass rate, API latency |
+| Quality requires judgment | Yes | LLM-as-judge score | Clustering quality, search relevance, content generation |
+| Hybrid | Yes | Hard metric + LLM-judge as guard rail | Latency (optimize) + response quality (must not drop) |
+
+**Recommendation**: Support all three tiers. The user declares whether the primary optimization target is a hard metric or an LLM-judge score. Degenerate gates always run first (cheap). Judge runs only on experiments that pass gates.
+
+### 3. What the Agent Can Edit
+
+AutoResearch constrains the agent to one file. This is elegant but too restrictive for most software projects.
+
+**Recommendation**: Define an explicit allowlist of mutable files/directories and an explicit denylist (measurement harness, test fixtures, evaluation data). The agent operates within the allowlist. The measurement harness is immutable — the agent cannot game the metric by changing how it's measured.
+
+### 4. Measurement Scaffolding First
+
+This is critical and distinguishes this from "just run the code in a loop":
+
+1. **Define the measurement spec** before any optimization begins
+2. **Build and validate the measurement harness** — ensure it produces reliable, reproducible results
+3. **Establish baseline** — run the harness on the current code to get starting metrics
+4. Only then begin the optimization loop
+
+**Recommendation**: Make this a hard phase gate. The skill refuses to enter the optimization loop until the measurement harness passes a validation check (runs successfully, produces expected metric types, baseline is recorded).
+
+### 5. History and Memory
+
+What gets remembered across iterations:
+
+- **Results log**: Every experiment's metrics, hypothesis, and outcome (kept/reverted)
+- **Git history**: Successful experiments are commits; branches are preserved
+- **Hypothesis log**: What was tried, why, what was learned — prevents re-trying failed approaches
+- **Strategy evolution**: As the agent learns what works, it should adapt its exploration strategy
+
+**Recommendation**: A structured experiment log (YAML or JSON) that captures: iteration number, hypothesis, changes made, metrics before/after, outcome (kept/reverted/error), and learnings. The agent reads this before proposing the next hypothesis. Git branches are preserved for all kept experiments.
+
+### 6. How Long It Runs
+
+- AutoResearch runs "indefinitely until manually stopped"
+- Real-world needs: time budgets, iteration budgets, metric targets, or "until no improvement for N iterations"
+
+**Recommendation**: Support multiple stopping criteria (any can trigger stop):
+- Target metric reached
+- Max iterations
+- Max wall-clock time
+- No improvement for N consecutive iterations
+- Manual stop (user interrupts)
+
+### 7. Parallelism
+
+AutoResearch is single-threaded. AIDE and AI Scientist run parallel experiments. For CE:
+
+- **Phase 1 (v1)**: Single-threaded linear loop. Simple, debuggable, works with git worktrees.
+- **Phase 2 (future)**: Parallel experiments using multiple worktrees or Codex sandboxes. Each experiment is independent.
+
+**Recommendation**: Start single-threaded. Design the experiment log and branching model to support parallelism later.
+
+### 8. Integration with Existing CE Skills
+
+The optimization loop should compose with existing CE capabilities:
+
+- **`/ce:ideate`** or **`/ce:brainstorm`** to generate initial hypothesis space
+- **Learnings researcher** to check if similar optimization was done before
+- **`/ce:compound`** to capture the winning strategy as institutional knowledge after the loop completes
+- **`/ce:review`** optionally on the final winning diff before it's merged
+
+## Proposed Skill: `/ce-optimize`
+
+### Workflow Phases
+
+```
+Phase 0: Setup
+  |-- Read/create optimization spec (target metric, guard rails, mutable files, constraints)
+  |-- Search learnings for prior related optimization attempts
+  '-- Validate spec completeness
+
+Phase 1: Measurement Scaffolding (HARD GATE - user must approve before Phase 2)
+  |-- If user provides harness:
+  |     |-- Review docs (or document usage if undocumented)
+  |     |-- Run harness once against current implementation
+  |     '-- Confirm baseline measurement is accurate with user
+  |-- If agent builds harness:
+  |     |-- Build measurement harness (immutable evaluator)
+  |     |-- Run validation: harness executes, produces expected metric types
+  |     '-- Establish baseline metrics
+  |-- Parallelism readiness probe:
+  |     |-- Check for hardcoded ports -> parameterize via env var
+  |     |-- Check for shared DB files (SQLite, etc.) -> plan copy strategy
+  |     |-- Check for shared external services -> warn user
+  |     |-- Check for exclusive resource needs (GPU, etc.)
+  |     '-- Produce parallel_readiness assessment
+  |-- Stability validation (if mode: repeat):
+  |     |-- Run harness repeat_count times
+  |     |-- Verify variance is within noise_threshold
+  |     '-- Confirm aggregation method produces stable baseline
+  '-- GATE: Present baseline + parallel readiness to user. Refuse to proceed until approved.
+
+Phase 2: Hypothesis Generation + Dependency Approval
+  |-- Analyze the problem space (read code, understand current approach)
+  |-- Generate initial hypothesis list (agent + optionally /ce:ideate)
+  |-- Prioritize by expected impact and feasibility
+  |-- Identify new dependencies across ALL planned hypotheses
+  |-- Present dependency list for bulk approval
+  '-- Record hypothesis backlog (with dep approval status per hypothesis)
+
+Phase 3: Optimization Loop (repeats in parallel batches)
+  |-- Select batch of hypotheses (batch_size = min(backlog, max_concurrent))
+  |     '-- Prefer diversity: mix different hypothesis categories per batch
+  |-- For each experiment in batch (PARALLEL by default):
+  |     |-- Create worktree or Codex sandbox
+  |     |-- Copy shared resources (DB files, data files)
+  |     |-- Apply parameterization (ports, env vars)
+  |     |-- Implement hypothesis (within mutable scope)
+  |     |-- Run measurement harness (respecting stability config)
+  |     '-- Collect metrics + diff
+  |-- Wait for batch completion
+  |-- Evaluate results:
+  |     |-- Rank by primary metric improvement
+  |     |-- Filter by guard rails (reject any that violate)
+  |     |-- If best > current: KEEP (merge to optimization branch)
+  |     |-- If best has unapproved dep: mark deferred_needs_approval
+  |     '-- All others: REVERT (log results, clean up worktrees)
+  |-- Handle unapproved deps:
+  |     '-- Set aside, don't block pipeline, batch-ask at end or check-in
+  |-- Update experiment log with ALL results (kept + reverted)
+  |-- Re-baseline: remaining hypotheses evaluated against new best
+  |-- Generate new hypotheses based on learnings from this batch
+  |-- Check stopping criteria
+  '-- Next batch
+
+Phase 4: Wrap-Up
+  |-- Present deferred hypotheses needing dep approval (if any)
+  |-- Summarize results: baseline -> final metrics, total iterations, kept improvements
+  |-- Preserve ALL experiment branches for reference
+  |-- Optionally run /ce:review on cumulative diff
+  |-- Optionally run /ce:compound to capture winning strategy as learning
+  '-- Report to user
+```
+
+### Optimization Spec File Format
+
+See "Updated Spec File Format" in the Resolved Design Decisions section below for the full spec with parallel execution and stability config.
+
+### Experiment Log Format
+
+```yaml
+# .context/compound-engineering/optimize/experiment-log.yaml
+spec: "improve-issue-clustering"
+
+baseline:
+  timestamp: "2026-03-29T10:00:00Z"
+  gates:
+    largest_cluster_pct: 0.02
+    singleton_pct: 0.79
+    cluster_count: 342
+    runtime_seconds: 45
+  diagnostics:
+    singleton_pct: 0.79
+    median_cluster_size: 2
+    cluster_count: 342
+    avg_cluster_size: 2.8
+    p95_cluster_size: 7
+  judge:
+    mean_score: 3.1
+    pct_scoring_4plus: 0.33
+    mean_distinct_topics: 1.8
+    singleton_false_negative_pct: 0.45   # 45% of sampled singletons should be clustered
+    sample_seed: 42
+    judge_cost_usd: 0.42
+
+experiments:
+  - iteration: 1
+    batch: 1
+    hypothesis: "Remove PR template boilerplate before embedding to reduce noise"
+    category: "signal-extraction"
+    changes:
+      - file: "src/preprocessing/text_cleaner.py"
+        summary: "Added template detection and removal using common PR template patterns"
+    gates:
+      largest_cluster_pct: 0.03
+      singleton_pct: 0.62
+      cluster_count: 489
+      runtime_seconds: 48
+    gates_passed: true
+    diagnostics:
+      singleton_pct: 0.62
+      median_cluster_size: 3
+      cluster_count: 489
+      avg_cluster_size: 3.4
+    judge:
+      mean_score: 3.8
+      pct_scoring_4plus: 0.57
+      mean_distinct_topics: 1.4
+      singleton_false_negative_pct: 0.31
+      judge_cost_usd: 0.38
+    outcome: "kept"
+    primary_delta: "+0.7"       # mean_score: 3.1 -> 3.8
+    learnings: "Template removal significantly improved coherence. Clusters now group by actual issue content rather than shared boilerplate. Singleton rate dropped 17pp."
+    commit: "abc123"
+
+  - iteration: 2
+    batch: 1                    # same batch as iteration 1 (ran in parallel)
+    hypothesis: "Lower similarity threshold from 0.85 to 0.75"
+    category: "clustering-algorithm"
+    changes:
+      - file: "config/clustering.yaml"
+        summary: "Changed similarity_threshold from 0.85 to 0.75"
+    gates:
+      largest_cluster_pct: 0.08
+      singleton_pct: 0.35
+      cluster_count: 210
+      runtime_seconds: 47
+    gates_passed: true
+    diagnostics:
+      singleton_pct: 0.35
+      median_cluster_size: 5
+      cluster_count: 210
+    judge:
+      mean_score: 2.4
+      pct_scoring_4plus: 0.13
+      mean_distinct_topics: 3.1   # clusters covering too many unrelated topics
+      singleton_false_negative_pct: 0.12
+      judge_cost_usd: 0.41
+    outcome: "reverted"
+    primary_delta: "-0.7"       # mean_score: 3.1 -> 2.4
+    learnings: "Lower threshold pulled in more items but destroyed coherence. Clusters became grab-bags. The hard metrics looked good (fewer singletons!) but judge correctly identified the quality drop. Validates that singleton_pct alone is a misleading optimization target."
+
+  - iteration: 3
+    batch: 2                    # new batch, runs on top of iteration 1's changes
+    hypothesis: "Use issue-to-PR link graph as additional clustering signal"
+    category: "graph-signals"
+    changes:
+      - file: "src/clustering/signals.py"
+        summary: "Added link-graph signal extraction from issue-PR references"
+      - file: "src/clustering/merger.py"
+        summary: "Combined text similarity with link-graph signal using weighted average"
+    gates:
+      largest_cluster_pct: 0.04
+      singleton_pct: 0.48
+      cluster_count: 520
+      runtime_seconds: 52
+    gates_passed: true
+    diagnostics:
+      singleton_pct: 0.48
+      median_cluster_size: 3
+      cluster_count: 520
+    judge:
+      mean_score: 4.1
+      pct_scoring_4plus: 0.70
+      mean_distinct_topics: 1.2
+      singleton_false_negative_pct: 0.22
+      judge_cost_usd: 0.39
+    outcome: "kept"
+    primary_delta: "+0.3"       # mean_score: 3.8 -> 4.1 (from iteration 1 baseline)
+    learnings: "Link graph is a strong complementary signal. Issues referencing the same PR are almost always related. Judge scores jumped — 70% of clusters now score 4+. Singleton false negatives dropped further."
+    commit: "def456"
+
+  - iteration: 4
+    batch: 2
+    hypothesis: "Add scikit-learn HDBSCAN for hierarchical density clustering"
+    category: "clustering-algorithm"
+    changes: []
+    gates_passed: false         # not evaluated — deferred
+    outcome: "deferred_needs_approval"
+    deferred_reason: "Requires unapproved dependency: scikit-learn"
+    learnings: "Set aside for batch approval at end of loop."
+
+best:
+  iteration: 3
+  judge:
+    mean_score: 4.1
+    pct_scoring_4plus: 0.70
+  total_judge_cost_usd: 1.60   # running total across all experiments
+```
+
+## Hypothesis Generation Strategies
+
+For the clustering example, here's the kind of hypothesis space the agent should explore:
+
+### Signal Extraction
+- Remove PR/issue template boilerplate before embedding
+- Extract only user-authored text (strip auto-generated sections)
+- Weight title more heavily than body
+- Use code snippets / file paths mentioned as signals
+- Extract error messages and stack traces as high-signal features
+
+### Graph-Based Signals
+- Issue-to-PR links (issues referencing same PR are related)
+- Cross-references between issues (`#123` mentions)
+- Author patterns (same author filing similar issues)
+- Label co-occurrence
+- Milestone/project board grouping
+
+### Embedding & Similarity
+- Try different embedding models (different size/quality tradeoffs)
+- Chunk long issues before embedding vs. truncate vs. summarize
+- Weighted combination of multiple similarity signals
+- Asymmetric similarity (issue-to-PR vs. issue-to-issue)
+
+### Clustering Algorithm
+- Adjust similarity thresholds (per-signal or combined)
+- Try hierarchical clustering vs. graph-based community detection
+- Two-pass: coarse clusters then split/merge refinement
+- Minimum cluster size constraints
+- Handle outlier issues that genuinely don't cluster
+
+### Pre-processing
+- Normalize markdown formatting
+- Deduplicate near-identical issues before clustering
+- Language detection and translation for multilingual repos
+- Time-decay weighting (recent issues weighted more)
+
+## Resolved Design Decisions
+
+### D1: Measurement Harness Ownership -> DECIDED: Agent builds, user validates
+
+The agent builds the measurement harness in Phase 1 and evaluates it against the current implementation. If the user provides an existing harness, the agent documents how to use it (or reviews existing docs), runs it once, and confirms the baseline measurement is accurate. Either way, the user reviews and approves before the loop starts. This is a hard gate.
+
+### D2: Flaky Metrics -> DECIDED: User-configurable, default stable
+
+The spec supports a `stability` block:
+
+```yaml
+measurement:
+  command: "python evaluate.py"
+  stability:
+    mode: "stable"          # default: run once, trust the result
+    # mode: "repeat"        # run N times, aggregate
+    # repeat_count: 5       # how many runs
+    # aggregation: "median" # median | mean | min | max | custom
+    # noise_threshold: 0.02 # improvement must exceed this to count
+```
+
+When `mode: repeat`, the harness runs `repeat_count` times. The `aggregation` function reduces results to a single value per metric. The `noise_threshold` prevents accepting improvements within the noise floor. Default is `stable` — run once, trust it.
+
+### D3: New Dependencies -> DECIDED: Pre-approve expected, defer surprises
+
+During Phase 2 (Hypothesis Generation), the agent outlines expected new dependencies across all planned variations and gets bulk approval up front. If an experiment during the loop discovers it needs an unapproved dependency, the agent:
+1. Sets that hypothesis aside (marks it `deferred_needs_approval` in the experiment log)
+2. Continues with other hypotheses that don't need new deps
+3. At the end of the loop (or at a user check-in), presents the deferred hypotheses and their dep requirements for batch approval
+4. If approved, those hypotheses enter the next iteration batch
+
+This prevents blocking the pipeline on interactive approval during long unattended runs.
+
+### D4: LLM-as-Judge -> DECIDED: Include in v1 (cost-controlled via sampling)
+
+LLM-as-judge is essential for problems where quality requires judgment — it's often the *actual* optimization target, not a nice-to-have. Hard metrics catch degenerate cases but can't tell you whether clusters are coherent or search results are relevant.
+
+**Cost control via stratified sampling**:
+- Don't judge every output item — sample a representative set
+- Stratified sampling ensures coverage of edge cases (small clusters, large clusters, singletons)
+- Default: ~30 samples per evaluation (configurable)
+- At ~$0.01-0.03 per judgment call, 30 samples = ~$0.30-0.90 per experiment
+- Over 100 experiments = $30-90 total — manageable
+
+**Sampling strategy**:
+```yaml
+judge:
+  sample_size: 30
+  stratification:
+    - bucket: "small"       # 2-3 items
+      count: 10
+    - bucket: "medium"      # 4-10 items
+      count: 10
+    - bucket: "large"       # 11+ items
+      count: 10
+  # For singletons: sample 10 and ask "should any of these be in a cluster?"
+  singleton_sample: 10
+```
+
+**Rubric-based scoring** (user-defined, per problem):
+```yaml
+judge:
+  rubric: |
+    Rate this cluster 1-5:
+    - 5: All items clearly about the same issue/feature
+    - 4: Strong theme, minor outliers
+    - 3: Related but covers 2-3 sub-topics
+    - 2: Weak connection
+    - 1: Unrelated items grouped together
+
+    Also answer:
+    - How many distinct sub-topics does this cluster represent?
+    - Should any items be removed from this cluster?
+
+  scoring:
+    primary: "mean_score"          # mean of 1-5 ratings
+    secondary: "pct_scoring_4plus" # % of samples scoring 4 or 5
+    output_format: "json"          # {"score": 4, "distinct_topics": 1, "remove_items": []}
+```
+
+**Judge execution order**:
+1. Run degenerate-case gates (fast, free) -- reject obviously broken solutions
+2. Run hard metrics (fast, free) -- collect diagnostics
+3. Only if gates pass: run LLM-as-judge on sampled outputs (slow, costs money)
+4. Keep/revert decision uses judge score as primary metric
+
+**Judge consistency**:
+- Use the same sample indices across experiments when possible (same random seed)
+- This reduces noise from sample variance — you're comparing the same clusters across runs
+- When the output structure changes (different number of clusters), re-sample but log the seed change
+
+**Judge model selection**:
+- Default: Haiku (fast, cheap, good enough for rubric-based scoring)
+- Option: Sonnet for nuanced judgment (2-3x cost)
+- The judge prompt is part of the immutable measurement harness — the agent cannot modify it
+
+**Singleton evaluation** (the non-obvious case):
+- Low singleton % isn't automatically good. High singleton % isn't automatically bad.
+- Sample singletons and ask the judge: "Given these other clusters, should this item be in one of them? Which one? Or is it genuinely unique?"
+- This catches false-negative clustering (items that should cluster but don't) AND validates true singletons
+
+### D5: Codex Support -> DECIDED: Include from v1
+
+Based on patterns from PRs #364/#365 in the compound-engineering plugin:
+
+**Dispatch pattern**: Write experiment prompt to a temp file, pipe to `codex exec` via stdin:
+```bash
+cat /tmp/optimize-exp-XXXXX.txt | codex exec --skip-git-repo-check - 2>&1
+```
+
+**Security posture**: User selects once per session (same as ce-work-beta):
+- Workspace write (`--full-auto`)
+- Full access (`--dangerously-bypass-approvals-and-sandbox`)
+
+**Result collection**: Inspect working directory diff after `codex exec` completes. No structured result format — Codex writes files, orchestrator reads the diff and runs the measurement harness.
+
+**Guard rails**:
+- Check for `CODEX_SANDBOX` / `CODEX_SESSION_ID` env vars to prevent recursive delegation
+- 3 consecutive delegate failures auto-disable Codex for remaining experiments
+- Orchestrator retains control of git operations, measurement, and keep/revert decisions
+
+### D6: Parallel Execution -> DECIDED: Parallel by default
+
+Experiments run in parallel by default. The user can specify serial execution if the system under test requires it. The skill actively probes for parallelism blockers.
+
+See full parallel execution design below.
+
+---
+
+## Parallel Execution Design
+
+### Default: Parallel Experiments
+
+The optimization loop dispatches multiple experiments simultaneously unless the user explicitly requests serial execution. This is the primary throughput lever — running 4-8 experiments in parallel vs. 1 at a time means 4-8x more iterations per hour.
+
+### Isolation Strategy
+
+Each parallel experiment needs full filesystem isolation. Two mechanisms, selectable per session:
+
+**Local worktrees** (default):
+```
+.claude/worktrees/optimize-exp-001/   # full repo copy
+.claude/worktrees/optimize-exp-002/
+.claude/worktrees/optimize-exp-003/
+```
+- Created via `git worktree add` with a unique branch per experiment
+- Each worktree gets its own copy of shared resources (see below)
+- Cleaned up after measurement: kept experiments merge to the optimization branch, reverted experiments have their worktree removed
+
+**Codex sandboxes** (opt-in):
+- Each experiment dispatched as an independent `codex exec` invocation
+- Codex provides built-in filesystem isolation
+- Orchestrator collects diffs after completion
+- Best for maximizing parallelism (no local resource limits)
+
+**Hybrid** (future):
+- Use Codex for implementation, local worktree for measurement
+- Useful when measurement requires local resources (GPU, specific hardware, large datasets)
+
+### Parallelism Blocker Detection (Phase 1)
+
+During Phase 1 (Measurement Scaffolding), the skill actively probes for common parallelism blockers:
+
+**Port conflicts**:
+- Run the measurement harness and check if it binds to fixed ports
+- Search config and code for hardcoded port numbers
+- If found: parameterize via environment variable (e.g., `PORT=0` for random, or `BASE_PORT + experiment_index`)
+- Add to spec: `parallel.port_strategy: "parameterized"` with the env var name
+
+**Shared database files**:
+- Check for SQLite databases, local file-based stores
+- If found: each experiment gets a copy of the database in its worktree
+- Cleanup: remove copies after measurement
+- Add to spec: `parallel.shared_files: ["data/clusters.db"]` with copy strategy
+
+**Shared external services**:
+- Check if the system writes to a shared external database, API, or queue
+- If found: warn user, suggest serial mode or test database isolation
+- This is a hard blocker for parallel unless the user confirms isolation
+
+**Resource contention**:
+- Check for GPU usage, large memory requirements
+- If the system needs exclusive access to a resource, serial mode is required
+- Add to spec: `parallel.exclusive_resources: ["gpu"]`
+
+**Detection output**: Phase 1 produces a `parallel_readiness` assessment:
+```yaml
+parallel:
+  mode: "parallel"            # parallel | serial | user-decision
+  max_concurrent: 4           # default, adjustable
+  blockers_found: []          # or list of issues
+  mitigations_applied:
+    - type: "port_parameterization"
+      env_var: "EVAL_PORT"
+      strategy: "base_port_plus_index"
+      base: 9000
+    - type: "database_copy"
+      source: "data/clusters.db"
+      strategy: "copy_per_worktree"
+  blockers_unresolved: []     # these force serial unless user resolves
+```
+
+### Parallel Loop Mechanics
+
+```
+Orchestrator (main branch)
+  |
+  |-- Batch N experiments from hypothesis backlog
+  |     (batch_size = min(backlog_size, max_concurrent))
+  |
+  |-- For each experiment in batch (parallel):
+  |     |-- Create worktree / Codex sandbox
+  |     |-- Copy shared resources (DB files, etc.)
+  |     |-- Apply parameterization (ports, env vars)
+  |     |-- Implement hypothesis (agent edits mutable files)
+  |     |-- Run measurement harness
+  |     |-- Collect metrics + diff
+  |     |-- Clean up shared resource copies
+  |
+  |-- Wait for all experiments in batch to complete
+  |
+  |-- Evaluate results:
+  |     |-- Rank by primary metric improvement
+  |     |-- Filter by guard rails
+  |     |-- Select best experiment that passes all guards
+  |     |-- If best > current best: KEEP (merge to optimization branch)
+  |     |-- All others: REVERT (remove worktrees, log results)
+  |     |-- If none improve: log all results, advance to next batch
+  |
+  |-- Update experiment log with all results (kept + reverted)
+  |-- Update hypothesis backlog based on learnings from ALL experiments
+  |-- Check stopping criteria
+  |-- Next batch
+```
+
+### Parallel-Aware Keep/Revert
+
+With parallel experiments, multiple experiments might improve the metric but conflict with each other (they modify the same files in incompatible ways). Resolution strategy:
+
+1. **Non-overlapping changes**: If the best experiment's changes don't overlap with the second-best, consider keeping both (merge sequentially, re-measure after merge to confirm)
+2. **Overlapping changes**: Keep only the best. Log the second-best as "promising but conflicts with experiment N" for potential future retry on top of the new baseline
+3. **Re-baseline**: After keeping any experiment, all remaining experiments in the batch that were reverted get re-measured mentally against the new baseline — their hypotheses go back into the backlog for potential retry
+
+### Experiment Prompt Template (for Codex dispatch)
+
+```markdown
+# Optimization Experiment #{iteration}
+
+## Context
+You are running experiment #{iteration} for optimization target: {spec.name}
+Current best metrics: {current_best_metrics}
+Baseline metrics: {baseline_metrics}
+
+## Your Hypothesis
+{hypothesis.description}
+
+## What To Change
+Modify ONLY files in the mutable scope:
+{spec.scope.mutable}
+
+DO NOT modify:
+{spec.scope.immutable}
+
+## Constraints
+{spec.constraints}
+{approved_dependencies}
+
+## Previous Experiments (for context)
+{recent_experiment_summaries}
+
+## Instructions
+1. Implement the hypothesis
+2. Do NOT run the measurement harness (orchestrator handles this)
+3. Do NOT commit (orchestrator handles this)
+4. Run `git diff --stat` when done so the orchestrator can see your changes
+```
+
+### Concurrency Limits
+
+```yaml
+parallel:
+  max_concurrent: 4           # default for local worktrees
+  # max_concurrent: 8         # default for Codex (no local resource limits)
+  codex_rate_limit: 10        # max Codex invocations per minute
+  worktree_cleanup: "immediate"  # or "batch" (clean up after full batch)
+```
+
+---
+
+## Updated Spec File Format
+
+### Example A: Hard-Metric Primary (build performance, test pass rate)
+
+```yaml
+# .context/compound-engineering/optimize/spec.yaml
+name: "reduce-build-time"
+description: "Reduce CI build time while maintaining test pass rate"
+
+metric:
+  primary:
+    type: "hard"               # hard | judge
+    name: "build_time_seconds"
+    direction: "minimize"
+    baseline: null             # filled by Phase 1
+    target: 60                 # optional target to stop at
+
+  degenerate_gates:            # fast boolean checks, run first
+    - name: "test_pass_rate"
+      check: ">= 1.0"         # all tests must pass
+    - name: "build_exits_zero"
+      check: "== true"
+
+  diagnostics:
+    - name: "cache_hit_rate"
+    - name: "slowest_step"
+    - name: "total_test_count"
+
+measurement:
+  command: "python evaluate.py"
+  timeout_seconds: 600
+  output_format: "json"
+  stability:
+    mode: "stable"
+```
+
+### Example B: LLM-Judge Primary (clustering quality, search relevance)
+
+```yaml
+# .context/compound-engineering/optimize/spec.yaml
+name: "improve-issue-clustering"
+description: "Improve coherence and coverage of issue/PR clusters"
+
+metric:
+  primary:
+    type: "judge"
+    name: "cluster_coherence"
+    direction: "maximize"
+    baseline: null
+    target: 4.2               # mean judge score (1-5 scale)
+
+  degenerate_gates:            # cheap checks that reject obviously broken solutions
+    - name: "largest_cluster_pct"
+      description: "% of all items in the single largest cluster"
+      check: "<= 0.10"        # if >10% of items are in one cluster, it's degenerate
+    - name: "singleton_pct"
+      description: "% of items that are singletons"
+      check: "<= 0.80"        # if >80% singletons, clustering isn't working at all
+    - name: "cluster_count"
+      check: ">= 10"          # fewer than 10 clusters for 18k items is degenerate
+    - name: "runtime_seconds"
+      check: "<= 600"
+
+  diagnostics:                 # logged for understanding, never gated on
+    - name: "singleton_pct"    # note: same metric can be diagnostic AND gate
+    - name: "median_cluster_size"
+    - name: "cluster_count"
+    - name: "avg_cluster_size"
+    - name: "p95_cluster_size"
+
+  judge:
+    model: "haiku"             # haiku (cheap) | sonnet (nuanced)
+    sample_size: 30
+    stratification:
+      - bucket: "small"       # 2-3 items per cluster
+        count: 10
+      - bucket: "medium"      # 4-10 items
+        count: 10
+      - bucket: "large"       # 11+ items
+        count: 10
+    singleton_sample: 10       # also sample singletons to check false negatives
+    sample_seed: 42            # fixed seed for cross-experiment consistency
+    rubric: |
+      Rate this cluster 1-5:
+      - 5: All items clearly about the same issue/feature
+      - 4: Strong theme, minor outliers
+      - 3: Related but covers 2-3 sub-topics
+      - 2: Weak connection
+      - 1: Unrelated items grouped together
+
+      Also answer in JSON:
+      - "score": your 1-5 rating
+      - "distinct_topics": how many distinct sub-topics this cluster represents
+      - "outlier_count": how many items don't belong
+    singleton_rubric: |
+      This item is currently a singleton (not in any cluster).
+      Given the cluster titles listed below, should this item be in one of them?
+
+      Answer in JSON:
+      - "should_cluster": true/false
+      - "best_cluster_id": cluster ID it belongs in (or null)
+      - "confidence": 1-5 how confident you are
+    scoring:
+      primary: "mean_score"              # what the loop optimizes
+      secondary:
+        - "pct_scoring_4plus"            # % of samples scoring 4+
+        - "mean_distinct_topics"         # lower is better (tighter clusters)
+        - "singleton_false_negative_pct" # % of sampled singletons that should be clustered
+
+measurement:
+  command: "python evaluate.py"          # outputs JSON with gate + diagnostic metrics
+  timeout_seconds: 600
+  output_format: "json"
+  stability:
+    mode: "stable"
+
+scope:
+  mutable:
+    - "src/clustering/"
+    - "src/preprocessing/"
+    - "config/clustering.yaml"
+  immutable:
+    - "evaluate.py"
+    - "tests/fixtures/"
+    - "data/"
+
+execution:
+  mode: "parallel"
+  backend: "worktree"
+  max_concurrent: 4
+  codex_security: null
+
+parallel:
+  port_strategy: null
+  shared_files: ["data/clusters.db"]
+  exclusive_resources: []
+
+dependencies:
+  approved: []
+
+constraints:
+  - "Do not change the output format of clusters"
+  - "Preserve backward compatibility with existing cluster consumers"
+
+stopping:
+  max_iterations: 100
+  max_hours: 8
+  plateau_iterations: 10
+  target_reached: true
+```
+
+### Evaluation Execution Order (per experiment)
+
+```
+1. Run measurement command (evaluate.py)
+   -> Produces JSON with gate metrics + diagnostics
+   -> Fast, free
+
+2. Check degenerate gates
+   -> If ANY gate fails: REVERT immediately, log as "degenerate"
+   -> Do NOT run the judge (saves money)
+
+3. If primary type is "judge": Run LLM-as-judge
+   -> Sample outputs according to stratification config
+   -> Send each sample to judge model with rubric
+   -> Aggregate scores per scoring config
+   -> This is the number the loop optimizes against
+
+4. Keep/revert decision
+   -> Based on primary metric (hard or judge score)
+   -> Must also pass all degenerate gates (already checked in step 2)
+```
+
+---
+
+## Open Questions (Remaining)
+
+1. **Should the agent propose hypotheses, or should the user provide them?**
+   - Both — agent generates from analysis, user can inject ideas, agent prioritizes
+
+2. **Judge calibration across experiments**
+   - LLM judges can drift or be inconsistent across calls
+   - Should we include "anchor samples" — a fixed set of clusters with known scores — in every judge batch to detect drift?
+   - If anchor scores shift >0.5 from baseline, re-calibrate or flag for user review
+
+3. **Judge rubric iteration**
+   - The rubric itself might need improvement after seeing early results
+   - But changing the rubric mid-loop invalidates comparisons to earlier experiments
+   - Solution: if rubric changes, re-judge the current best with the new rubric to re-baseline?
+
+4. **Relationship to `/lfg` and `/slfg`?**
+   - `/lfg` is autonomous execution of a single task
+   - `/ce-optimize` is autonomous execution of an iterative search
+   - `/ce-optimize` can delegate each experiment to Codex (decided D5)
+   - Local experiments use subagent dispatch similar to `/ce:review`
+
+5. **Branch strategy details?**
+   - Main optimization branch: `optimize/<spec-name>`
+   - Each kept experiment is a commit on that branch
+   - Branch points create `optimize/<spec-name>/direction-<N>`
+   - All branches preserved for later reference and comparison
+
+6. **Batch size adaptation?**
+   - Should the batch size grow/shrink based on success rate?
+   - High success rate -> larger batches (more exploration)
+   - Low success rate -> smaller batches (more focused)
+   - Or keep it simple and let the user tune `max_concurrent`
+
+7. **Hypothesis diversity within a batch?**
+   - Should parallel experiments in the same batch be intentionally diverse?
+   - E.g., one threshold tweak + one new signal + one preprocessing change
+   - Or let the prioritization algorithm decide naturally?
+
+8. **Judge cost budgets?**
+   - Should the spec include a `max_judge_cost_usd` budget?
+   - When budget is exhausted, switch to hard-metrics-only mode or stop?
+   - Or just track cost in the log and let the user decide?
+
+## What Makes This Different From "Just Using AutoResearch"
+
+AutoResearch is designed for ML training on a single GPU. CE's version needs to handle:
+
+1. **Multi-file changes** — real code changes span multiple files
+2. **Complex metrics** — not just one scalar, but primary + guard rails + diagnostics
+3. **Varied execution environments** — not just `python train.py` but arbitrary commands
+4. **Integration with existing workflows** — learnings, review, ideation
+5. **User-in-the-loop** — pause for approval on scope-expanding changes, inject new hypotheses
+6. **Knowledge capture** — document what worked and why for the team, not just for the agent's context
+7. **Non-ML domains** — clustering, search quality, API performance, test coverage, build times, etc.
+
+## Success Criteria for This Skill
+
+- User can define an optimization target in <15 minutes
+- Measurement scaffolding is validated before the loop starts
+- Loop runs unattended for hours, producing measurable improvement
+- All experiments are preserved in git for later reference
+- The winning strategy is documented as a learning
+- A human reviewing the experiment log can understand what was tried and why
+- The skill handles failures gracefully (bad experiments don't corrupt state)
+
+## Lessons from First Run (2026-03-30)
+
+The skill was tested on the clustering problem for ~90 minutes. Results:
+
+**What worked:**
+- Ran 16 experiments, improved multi_member_pct from 31.4% to 72.1%
+- Explored multiple algorithm modes (basic, refine, bounded union-find)
+- Correctly identified size-bounded union-find as the winning approach
+- Hypothesis diversity across parameter sweeps was reasonable
+
+**What failed:**
+
+1. **No LLM-as-judge evaluation** -- The skill defaulted to `type: hard` and optimized `multi_member_pct` as the primary metric. This is a proxy metric that can mislead. A solution that puts 72% of items in clusters is useless if the clusters are incoherent. The Phase 0.2 interactive spec creation did not actively probe whether the target was qualitative or guide toward judge mode.
+
+   **Fix applied**: Phase 0.2 now includes explicit qualitative vs quantitative detection, concrete examples of when to use each type, sampling strategy guidance with walkthrough questions, and rubric design guidance. The skill now strongly recommends `type: judge` for qualitative targets.
+
+2. **No disk persistence** -- Experiment results existed only in the conversation context (as a table dumped to chat). If the session had been compacted or crashed, all 90 minutes of results would have been lost. This directly contradicts the Karpathy model where `results.tsv` is written after every single experiment.
+
+   **Fix applied**: Added mandatory disk checkpoints (CP-0 through CP-5) at every phase boundary. Each checkpoint requires a write-then-verify cycle: write the file, read it back, confirm the content is present. The persistence discipline section now explicitly states "If you produce a results table in the conversation without writing those results to disk first, you have a bug."
+
+3. **Sampling strategy not prompted** -- Even if `type: judge` had been used, the skill didn't guide the user through designing a sampling strategy. For clustering, the user wants stratified sampling across: top clusters by size (check for mega-clusters), mid-range clusters (representative quality), small clusters (check if connections are real), and singletons (check for false negatives). This domain-specific guidance was missing.
+
+   **Fix applied**: Phase 0.2 now walks through sampling strategy design with concrete questions and domain-specific examples.
+
+**Key takeaway**: The skill had all the right machinery in the schema and templates but the SKILL.md instructions didn't forcefully enough guide the agent toward using that machinery. Instructions that say "if judge type, do X" are ignored when the skill silently defaults to hard type. Instructions need to actively detect the right path and guide toward it.
+
+## Next Steps
+
+1. Re-test with the clustering use case using `type: judge` to validate the judge loop works end-to-end
+2. Verify disk persistence works on a long run (2+ hours) with context compaction
+3. Test with a second use case (e.g., prompt optimization, build performance) to validate generality
+4. Consider adding anchor samples for judge calibration across experiments (Open Question #2)
+5. Consider judge cost budgets (Open Question #8)

docs/brainstorms/2026-03-29-testing-addressed-gate-requirements.md

@@ -0,0 +1,82 @@
+---
+date: 2026-03-29
+topic: testing-addressed-gate
+---
+
+# Close the Testing Gap in ce:work and ce:plan
+
+## Problem Frame
+
+ce:work has extensive testing instructions -- test discovery, test-first execution posture, system-wide test checks, and a test scenario completeness checklist. But two narrow gaps let untested behavioral changes slip through silently:
+
+1. **ce:work's quality gate says "All tests pass"** -- which is vacuously true when no tests exist. A passing empty test suite is indistinguishable from a passing comprehensive one. "No tests" can be a deliberate decision or an accidental omission, and the skill doesn't distinguish between the two.
+
+2. **ce:plan allows blank test scenarios without annotation** -- when a plan unit has no test scenarios, it's ambiguous whether the planner assessed testing and determined none were needed, or simply didn't think about it. ce:plan already requires test scenarios for feature-bearing units (Plan Quality Bar, Phase 5.1 review), but non-feature-bearing units legitimately omit them, and the template doesn't require saying so.
+
+The testing-reviewer in ce:review catches some of these after the fact by examining diffs for untested branches and missing edge case coverage. But it doesn't specifically flag the broader pattern: behavioral changes with no corresponding test additions at all.
+
+The existing testing instructions are thorough but generic. The gap isn't volume of instructions -- it's specificity at the right moments. This targets focused changes at three layers: planning (ce:plan annotation), execution (ce:work per-task deliberation), and review (testing-reviewer detection).
+
+## Requirements
+
+**ce:plan -- Handle the Blank Case**
+
+- R1. When a plan unit has no test scenarios, the planner should annotate why (e.g., "Test expectation: none -- config-only, no behavioral change") rather than leaving the field blank
+- R2. A blank or missing test scenarios field on a feature-bearing unit should be treated as incomplete during ce:plan's Phase 5.1 review, not silently accepted
+
+---
+
+**ce:work -- Per-Task Testing Deliberation**
+
+- R3. Before marking a task done, ce:work's execution loop should include an explicit testing deliberation: did this task change behavior? If yes, were tests written or updated? If no tests were added, why not? This is a prompt for deliberation at the point of action, not a formal artifact
+- R4. The Phase 3 quality checklist item "Tests pass (run project's test command)" and the Final Validation item "All tests pass" should both be updated to "Testing addressed -- tests pass AND new/changed behavior has corresponding test coverage (or an explicit justification for why tests are not needed)"
+- R5. Apply R3 and R4 to ce:work-beta (AGENTS.md requires explicit sync decisions for beta counterparts)
+
+---
+
+**testing-reviewer -- Flag the Missing-Test Pattern**
+
+- R6. The testing-reviewer agent should add a new check: when the diff contains behavioral code changes (new logic branches, state mutations, API changes) with zero corresponding test additions or modifications, flag it as a finding
+- R7. This check complements the existing checks (untested branches, weak assertions, brittle tests, missing edge cases) -- it catches the case those miss: no tests at all for new behavior
+
+**Contract Tests -- Practice What We Preach**
+
+- R8. Add contract tests verifying each behavioral change ships as intended. Following the existing pattern in `pipeline-review-contract.test.ts` and `review-skill-contract.test.ts` (string assertions against skill/agent file content):
+  - ce:work includes per-task testing deliberation in the execution loop (R3)
+  - ce:work checklist says "Testing addressed", not "Tests pass" or "All tests pass" (R4)
+  - ce:work-beta mirrors the testing deliberation and checklist changes (R5)
+  - ce:plan Phase 5.1 review treats blank test scenarios on feature-bearing units as incomplete (R2)
+  - testing-reviewer agent includes the behavioral-changes-with-no-test-additions check (R6)
+
+## Success Criteria
+
+- A diff with behavioral changes and no test changes gets flagged by the testing-reviewer (R6) -- the detective layer catches it on real artifacts
+- ce:plan units without test scenarios either have an explicit annotation or get flagged during plan review (R1-R2) -- the preventive layer operates at planning time
+- ce:work's execution loop prompts testing deliberation per task, and the checklist makes the agent explicitly consider whether testing was addressed, not just whether the suite is green (R3-R4)
+- "No tests needed" with justification remains a valid outcome -- the goal is deliberate decisions, not forced ceremony
+
+## Scope Boundaries
+
+- Not adding CI-level enforcement or programmatic gates -- these are prompt-level changes
+- Not adding new abstractions like "testing assessment artifacts" or structured output schemas
+- Not mandating coverage thresholds or specific testing frameworks
+- Not changing the testing-reviewer's output format -- adding one check within its existing review protocol
+
+## Key Decisions
+
+- **Layered approach -- deliberation + detection**: ce:work's per-task deliberation (R3) prompts the agent to think about testing at the point of action. The testing-reviewer (R6) operates on the actual diff as a backstop. Instruction specificity at the right moment matters -- "did you address testing for this task?" is a much more targeted prompt than "tests pass."
+- **Targeted edits over a new system**: Rather than introducing a "testing assessment gate" abstraction, make focused changes to ce:plan, ce:work, and testing-reviewer that close the identified gaps.
+- **Deliberate omission is a first-class outcome**: "No tests needed" with justification is valid. The goal is making "no tests" a deliberate decision, not an accidental one.
+
+## Outstanding Questions
+
+### Deferred to Planning
+
+- [Affects R1][Technical] What's the lightest-weight annotation for plan units that genuinely need no tests -- a field, a comment, or a convention?
+- [Affects R6][Needs research] Review the testing-reviewer's current check implementation to determine where the new "behavioral changes with no test changes" check fits in its analysis protocol
+- [Affects R3][Technical] Where in ce:work's execution loop (Phase 2 task loop) does the testing deliberation prompt fit -- after "Run tests after changes" or as part of "Mark task as completed"?
+- [Affects R4-R5][Resolved] ce:work's Phase 3 checklist is plaintext markdown in SKILL.md (line ~433 and ~289). ce:work-beta has the same pattern. The change is editing bullet points, no dynamic infrastructure.
+
+## Next Steps
+
+-> `/ce:plan` for structured implementation planning

docs/brainstorms/2026-03-30-cli-readiness-review-persona-requirements.md

@@ -0,0 +1,65 @@
+---
+date: 2026-03-30
+topic: cli-readiness-review-persona
+---
+
+# CLI Agent-Readiness Review Persona in ce:review
+
+## Problem Frame
+
+The `cli-agent-readiness-reviewer` agent exists as a standalone deep-audit tool, but developers only benefit from it if they know it exists and invoke it explicitly. Most CLI code gets reviewed through `ce:review`, which has no CLI-specific lens. Agent-readiness issues (prose-only output, missing `--json`, interactive prompts without bypass, unbounded list output) ship undetected because no review persona covers them.
+
+Adding CLI readiness as a conditional persona in ce:review makes this expertise automatic -- the developer runs their normal review and gets CLI agent-readiness findings alongside security, performance, and other concerns.
+
+## Requirements
+
+**Persona Selection**
+
+- R1. ce:review's orchestrator selects the CLI readiness persona based on diff analysis (same pattern as security-reviewer, performance-reviewer, etc.) -- not always-on
+- R2. Activation signals: diff touches CLI command definitions, argument parsing, CLI framework usage, or command handler implementations. The orchestrator uses judgment (not keyword matching), consistent with how all other conditional personas are activated
+- R3. Non-overlapping scope with agent-native-reviewer: CLI readiness evaluates CLI command structure and agent-friendliness; agent-native evaluates UI/agent tool parity. Both may activate on the same diff if it touches both CLI and UI code -- their findings address different concerns. Overlap is possible and handled during synthesis rather than prevented mechanically
+
+**Persona Behavior**
+
+- R4. Once dispatched, the persona self-scopes: identifies the framework, detects changed commands from the diff, and evaluates against the 7 principles from the standalone `cli-agent-readiness-reviewer` agent (used as reference material, not dispatched directly)
+- R5. The persona returns findings in ce:review's standard JSON findings schema (same as all other conditional personas). For design-level findings that span multiple files or concern missing capabilities, use the most relevant command handler file as the canonical location
+- R6. Severity mapping: Blocker -> P1, Friction -> P2, Optimization -> P3. The severity ceiling is P1 -- CLI readiness issues make the CLI harder for agents to use, they do not crash or corrupt
+- R7. Autofix class: all findings use autofix_class `manual` or `advisory` with owner `human`. CLI readiness findings are design decisions (JSON schema design, flag semantics, error message content) that should not be auto-applied
+- R8. Framework-idiomatic recommendations: findings reference the specific framework's patterns (e.g., "add `@click.option('--json', ...)` " for Click, not generic "add a --json flag")
+
+**Integration**
+
+- R9. Create a new lightweight persona agent file in `agents/review/` that distills the 7 principles into a code-review-oriented persona producing structured JSON findings. Add it to `ce-review/references/persona-catalog.md` in the cross-cutting conditional section with activation description and severity guidance
+- R10. The existing standalone `cli-agent-readiness-reviewer` agent stays unchanged -- it remains available for direct invocation and whole-CLI audits. The new persona references the same principles but is optimized for ce:review's dispatch pattern and output format
+
+## Success Criteria
+
+- A ce:review run on a PR that modifies CLI command handlers includes CLI readiness findings in the review report without the user asking
+- A ce:review run on a PR that only modifies React components or Rails views does not dispatch the CLI readiness persona
+- Findings use framework-specific language matching the CLI's detected framework
+- All findings have severity P1, P2, or P3 (never P0) and autofix_class `manual` or `advisory`
+
+## Scope Boundaries
+
+- This does not modify the standalone `cli-agent-readiness-reviewer` agent
+- This does not add CLI awareness to ce:brainstorm or ce:plan (deferred -- ce:review alone covers the highest-value case)
+- This does not introduce autofix for CLI readiness findings
+
+## Key Decisions
+
+- **New persona agent file**: A lightweight agent in `agents/review/` that distills the standalone agent's 7 principles into structured JSON findings. This matches how every other conditional persona works (security-reviewer, performance-reviewer, etc. are all separate agent files). The standalone agent's narrative report format doesn't match ce:review's JSON findings schema, and prompt surgery at dispatch time would be fragile.
+- **Conditional, not always-on**: Follows the existing pattern where the orchestrator selects personas based on diff content. The persona never runs on non-CLI diffs.
+- **Persona self-scopes**: The persona does its own framework detection and subcommand identification after dispatch. ce:review's orchestrator only decides whether to dispatch, not what framework is in use.
+- **No autofix**: All findings route to human review. CLI readiness issues require design judgment.
+- **Severity ceiling is P1**: CLI readiness issues don't crash the software -- they make it harder for agents to use. The highest reasonable severity is P1 (should fix), not P0 (must fix before merge).
+
+## Outstanding Questions
+
+### Deferred to Planning
+
+- [Affects R9][Needs research] How much of the standalone agent's content should the new persona include directly vs. reference? The standalone agent is 24K+ (the largest review agent) -- the persona should be much smaller, distilling the principles into code-review-oriented checks rather than reproducing the full Framework Idioms Reference.
+- [Affects R4][Needs research] Should the persona evaluate all 7 principles on every dispatch, or should it prioritize principles by command type (as the standalone agent does) and cap findings to avoid flooding the review with low-signal items?
+
+## Next Steps
+
+-> `/ce:plan` for structured implementation planning

docs/brainstorms/2026-03-31-codex-delegation-requirements.md

@@ -0,0 +1,236 @@
+---
+date: 2026-03-31
+topic: codex-delegation
+---
+
+# Codex Delegation Mode for ce:work
+
+## Problem Frame
+
+Users running ce:work from Claude Code (or other non-Codex agents) may want to delegate the actual code-writing to Codex. Two motivations: (1) Codex may produce better code for certain tasks, and (2) delegating token-heavy implementation work to Codex conserves tokens on the user's current model.
+
+PR #364 attempted this via a separate `ce-work-beta` skill with prose-based delegation instructions. The agent improvises CLI syntax each run, producing non-deterministic results confirmed as flaky in the PR author's own testing. The root cause: describing Codex CLI invocation in prose lets the agent guess differently every time.
+
+ce-work-beta does have a structured 7-step External Delegate Mode (environment guards, availability checks, prompt file writing, circuit breaker), but the CLI invocation step itself is prose-based, causing the non-determinism. This feature ports the useful structural elements (guards, circuit breaker pattern) while replacing prose invocations with concrete bash templates.
+
+> **Implementation note (2026-03-31):** The final rollout was redirected to `ce:work-beta` so stable `ce:work` remains unchanged during beta. `ce:work-beta` must be invoked manually; `ce:plan` and workflow handoffs stay on stable `ce:work` until promotion.
+
+## Delegation Flow
+
+```
+/ce:work delegate:codex ~/plan.md
+         │
+         ▼
+┌──────────────────────────┐
+│ Parse arguments           │
+│ - Extract delegate flag   │
+│ - Require plan file       │
+│ - Check local.md default  │
+│ - Resolution chain:       │
+│   flag > local.md > off   │
+└────────┬─────────────────┘
+         │
+         ▼
+┌──────────────────────────┐     ┌───────────────────────┐
+│ Environment guard         │────>│ Notify if explicit,   │
+│ $CODEX_SANDBOX set?       │ yes │ use standard mode     │
+│ $CODEX_SESSION_ID set?    │     └───────────────────────┘
+└────────┬─────────────────┘
+         │ no
+         ▼
+┌──────────────────────────┐     ┌───────────────────────┐
+│ Availability check        │────>│ Fall back to          │
+│ command -v codex          │ no  │ standard mode + notify│
+└────────┬─────────────────┘     └───────────────────────┘
+         │ yes
+         ▼
+┌──────────────────────────┐     ┌───────────────────────┐
+│ Consent + mode selection  │────>│ Ask: disable          │
+│ work_delegate_consent set?   │ no  │ delegation?           │
+│ Show warning + sandbox    │     │ Set local.md          │
+│ mode choice (yolo/full-   │     └───────────────────────┘
+│ auto). Recommend yolo.    │
+│ (headless: require prior) │
+└────────┬─────────────────┘
+         │ accepted
+         ▼
+┌──────────────────────────┐
+│ Per-unit execution loop   │
+│ (SERIAL, not parallel)    │
+│ For each implementation   │
+│ unit in the plan:         │
+│                           │
+│ 1. Check unit eligibility │
+│    (out-of-repo? trivial?)│
+│    -> local if ineligible │
+│ 2. Named stash snapshot   │
+│ 3. Write prompt + schema  │
+│    to .context/compound-  │
+│    engineering/codex-      │
+│    delegation/             │
+│ 4. codex exec w/ flags    │
+│ 5. Classify result:       │
+│    CLI fail | task fail | │
+│    verify fail | success  │
+│ 6. Pass: commit, drop     │
+│    stash, clean scratch   │
+│    Fail: rollback,        │
+│          increment ctr    │
+│ 7. If 3 consecutive       │
+│    failures: fall back    │
+│    to standard mode       │
+└──────────────────────────┘
+```
+
+## Requirements
+
+**Activation and Configuration**
+
+- R1. Codex delegation is an optional mode within ce:work, not a separate skill. ce-work-beta is superseded: its delegation logic is replaced by this feature; its non-delegation features (e.g., Frontend Design Guidance) should be ported to ce:work as a separate concern if valuable. Disposition of ce-work-beta (delete vs. retain without delegation) is a planning decision, not a product decision.
+- R2. Delegation is triggered via a resolution chain: (1) per-invocation argument wins, (2) `work_delegate` setting in `.claude/compound-engineering.local.md` is fallback, (3) hard default is `false` (off).
+- R3. Canonical activation argument is `delegate:codex`. The skill also recognizes fuzzy variants: `codex mode`, `codex`, `delegate codex`, and similar intent expressions. Agent intent recognition handles the fuzzy matching — the set does not need to be exhaustively enumerated.
+- R4. Canonical deactivation argument is `delegate:local`. Also recognizes fuzzy variants like `no codex`, `local mode`, `standard mode`.
+- R5. Delegation only applies to structured plan execution. Ad-hoc prompts without a plan file always use standard mode regardless of the delegation setting. When delegation mode is active for a plan, each implementation unit is delegated to Codex by default. The agent may execute a unit locally in standard mode when: (a) the unit explicitly requires modifications outside the repository root, or (b) the unit is trivially small (single-file config change, simple substitution) where delegation overhead exceeds the work. The agent states which mode it's using for each unit before execution.
+
+**Environment Safety**
+
+- R6. When running inside a Codex sandbox (detected by `$CODEX_SANDBOX` or `$CODEX_SESSION_ID` environment variables), delegation is disabled and ce:work proceeds in standard mode. If the user explicitly requested delegation (via argument), emit a brief notification: "Already inside Codex sandbox — using standard mode." If delegation was only enabled via local.md default, proceed silently.
+- R7. All delegation logic lives in the skill itself. Converters do not modify skill behavior for cross-platform compatibility — the environment guard handles platform detection at runtime.
+
+**Availability and Fallback**
+
+- R8. Before delegation, check `command -v codex`. If the Codex CLI is not on PATH, fall back to standard mode with a brief notification: "Codex CLI not found — using standard mode."
+- R9. No minimum version check for now. If a future CLI change breaks delegation, the invocation fails loudly and the fix is a single bash line update.
+
+**Consent and Mode Selection**
+
+- R10. First time delegation activates in a project, show a one-time consent flow that: (1) explains what delegation does and the security implications, (2) presents the sandbox mode choice with a recommendation, and (3) records the user's decisions. The sandbox modes are:
+  - **yolo** (recommended): Maps to `--yolo` (`--dangerously-bypass-approvals-and-sandbox`). Full system access including network. Required for verification steps that run tests or install dependencies. Explain why this is recommended.
+  - **full-auto**: Maps to `--full-auto`. Workspace-write sandbox, no network access. Tests/installs that need network will fail. Suitable for pure code-writing tasks without verification dependencies.
+- R11. On user acceptance, store `work_delegate_consent: true` and `work_delegate_sandbox: yolo` (or `full-auto`) in `.claude/compound-engineering.local.md`. Do not show the consent flow again for this project.
+- R12. On user decline, ask whether to disable codex delegation entirely. If yes, set `work_delegate: false` in local.md and proceed in standard mode.
+- R13. In headless mode, delegation proceeds only if `work_delegate_consent` is already `true` in local.md. If not set or `false`, fall back to standard mode silently. Headless runs never prompt for consent and never silently escalate to unsandboxed mode without prior interactive consent.
+
+**Execution Mechanism**
+
+- R14. Delegation uses concrete bash commands, not prose instructions. The exact invocation template:
+
+  ```bash
+  # Read sandbox mode from settings (default: yolo)
+  if [ "$CODEX_SANDBOX_MODE" = "full-auto" ]; then
+    SANDBOX_FLAG="--full-auto"
+  else
+    SANDBOX_FLAG="--yolo"
+  fi
+
+  codex exec \
+    $SANDBOX_FLAG \
+    --output-schema .context/compound-engineering/codex-delegation/result-schema.json \
+    -o .context/compound-engineering/codex-delegation/result-<unit-id>.json \
+    - < .context/compound-engineering/codex-delegation/prompt-<unit-id>.md
+  ```
+
+  The agent executes this verbatim — no improvisation of CLI syntax.
+
+- R15. Sandbox posture defaults to `yolo` (`--yolo`, shorthand for `--dangerously-bypass-approvals-and-sandbox`) but the user may choose `full-auto` during the consent flow (R10). The choice is stored in `work_delegate_sandbox` in local.md. `yolo` is recommended because `--full-auto` blocks network access, which is required for verification steps (running tests, installing dependencies). If `full-auto` is chosen and causes repeated verification failures, the circuit breaker (R18) handles fallback.
+
+- R16. When delegation mode is active, ALL units execute serially — both delegated and locally-executed units. Git stash is a global stack; mixing parallel and serial execution on the same working tree causes stash entanglement. This means delegation mode and swarm mode (Agent Teams) are mutually exclusive. Before each delegated unit, the loop assumes a clean working tree (enforced by ce:work's Phase 1 setup and by mandatory commits after each successful unit). Snapshot the working tree via named stash: `git stash push --include-untracked -m "ce-codex-<unit-id>"`. On failure, rollback via `git checkout -- . && git clean -fd && git stash drop "$(git stash list | grep 'ce-codex-<unit-id>' | head -1 | cut -d: -f1)"`. On success, commit the changes, then drop the named stash.
+
+- R17. The structured prompt template is written to a file at `.context/compound-engineering/codex-delegation/prompt-<unit-id>.md` rather than piped via stdin, to avoid ARG_MAX limits for large CURRENT PATTERNS sections. The template includes: TASK (goal from implementation unit), FILES TO MODIFY (file list), CURRENT PATTERNS (relevant code context), APPROACH (from implementation unit), CONSTRAINTS (no git commit, restrict modifications to files within the repository root, scoped changes, line limit, mandatory result reporting), and VERIFY (test/lint commands). Prompt files are cleaned up after each successful unit.
+
+- R18. A consecutive failure counter tracks delegation failures. After 3 consecutive failures, the skill falls back to standard mode for remaining units with a notification.
+
+- R19. Failure classification uses a multi-signal approach. `codex exec` returns exit code 0 even when the task fails — the exit code only reflects CLI infrastructure, not task success.
+
+  | Category | Signal | Action |
+  |---|---|---|
+  | **CLI failure** | Exit code != 0 | Hard failure — fall back to standard mode |
+  | **Result absent** | Exit code 0, result JSON missing or malformed | Count as task failure |
+  | **Task failure** | Exit code 0, result schema `status: "failed"` | Count toward circuit breaker, rollback |
+  | **Task partial** | Exit code 0, result schema `status: "partial"` | Keep changes, report gaps to main agent |
+  | **Verify failure** | Exit code 0, `status: "completed"`, VERIFY fails | Count toward circuit breaker, rollback |
+  | **Success** | Exit code 0, `status: "completed"`, VERIFY passes | Commit, drop stash, continue |
+
+- R20. A result schema file is written alongside the prompt file. Codex is instructed via `--output-schema` to produce structured JSON conforming to this schema. The `-o` flag writes the result to `result-<unit-id>.json`. The schema:
+
+  ```json
+  {
+    "type": "object",
+    "properties": {
+      "status": { "enum": ["completed", "partial", "failed"] },
+      "files_modified": { "type": "array", "items": { "type": "string" } },
+      "issues": { "type": "array", "items": { "type": "string" } },
+      "summary": { "type": "string" }
+    },
+    "required": ["status", "files_modified", "issues", "summary"],
+    "additionalProperties": false
+  }
+  ```
+
+  The prompt CONSTRAINTS section includes mandatory result reporting instructions telling Codex it MUST fill in the schema honestly: `status: "completed"` only if all changes were made, `"partial"` if incomplete, `"failed"` if no meaningful progress. Known limitation: `--output-schema` only works with `gpt-5` family models, not `gpt-5-codex` or `codex-` prefixed models (Codex CLI bug #4181). If the result JSON is absent or malformed, classify as task failure.
+
+- R21. The prompt constraint tells Codex to restrict all modifications to files within the repository root. If Codex discovers mid-execution that it needs to modify files outside the repo root, it should complete what it can within the repo and report what it couldn't do via the result schema `issues` field. The main agent then handles the out-of-repo work in standard mode. Out-of-repo changes cannot be detected or rolled back by git stash — this is an accepted risk mitigated by the prompt constraint and per-unit pre-screening (R5).
+
+**Settings in compound-engineering.local.md**
+
+- R22. New YAML frontmatter keys in `.claude/compound-engineering.local.md`:
+  - `work_delegate`: `codex`/`false` (default: `false`) — delegation target when enabled
+  - `work_delegate_consent`: `true`/`false` — whether the user has completed the one-time consent flow
+  - `work_delegate_sandbox`: `yolo`/`full-auto` (default: `yolo`) — sandbox posture for codex exec
+
+## Success Criteria
+
+- Codex successfully implements implementation units from ce:plan output across a variety of task types (new features, bug fixes, refactors)
+- CLI invocations are deterministic — no agent improvisation of shell syntax across runs
+- Delegation activates only when explicitly requested (argument or local.md), only with a plan file, and never when running inside Codex
+- Failed delegation rolls back cleanly via named git stash without corrupting tracked repository files
+- The result schema provides reliable signal for success/failure classification
+- Users who never enable delegation experience zero change in ce:work behavior
+
+## Scope Boundaries
+
+- **Not a separate skill.** ce-work-beta is superseded. This modifies ce:work directly.
+- **No app-server integration.** We use bare `codex exec`, not the codex-companion.mjs app server or the codex plugin's rescue skill. The delegation pattern is fire-prompt -> wait -> inspect-result, which is exactly what `codex exec` provides.
+- **No ad-hoc delegation.** Delegation only applies to structured plan execution with a plan file. Bare prompts without plans always use standard mode.
+- **No minimum version gating.** Added later if a breaking CLI change actually occurs.
+- **No periodic re-consent.** One acceptance per project. Version-gated or calendar-based re-consent can be added later if needed.
+- **No converter changes.** The skill handles platform detection internally via environment variable checks.
+- **No out-of-repo detection.** Git stash cannot protect files outside the repo. Defense is prompt constraint + per-unit pre-screening, not post-execution validation.
+- **No timeout for v1.** Neither `codex exec` nor the most mature codex integration (osc-work) implements timeouts. Added later if users report hung processes.
+
+## Key Decisions
+
+- **Modify ce:work, not a separate skill**: Avoids skill proliferation. Users stay in their existing workflow. ce-work-beta's delegation section is superseded; its structural patterns (guards, circuit breaker) are ported.
+- **`delegate:codex` namespace, not `mode:codex`**: Existing `mode:` tokens describe interaction style (headless, autofix). Delegation describes execution target. Separate namespace avoids semantic overloading.
+- **Bare `codex exec` over app-server**: App server offers structured output and thread management, but requires fragile path discovery into another plugin's versioned install directory. `codex exec` is one line of bash, works identically in subagents, and does exactly what fire-and-wait delegation needs.
+- **User-selected sandbox mode (yolo default, full-auto option)**: yolo is recommended because `--full-auto` blocks network access needed for test/lint commands. But users who prefer sandboxed execution can choose `full-auto`, accepting that verification may fail. The circuit breaker handles repeated failures.
+- **One-time consent with mode selection**: Consent is about informed awareness, not ongoing compliance. The sandbox mode choice is part of the consent flow and persisted in local.md.
+- **Per-unit delegation eligibility, not all-or-nothing**: Default is to delegate all units, but the agent pre-screens units that need out-of-repo access or are trivially small. This avoids delegating work that can't succeed in the unsandboxed environment and reduces overhead for trivial changes.
+- **Prompt file over stdin**: Writing prompts to `.context/compound-engineering/codex-delegation/` avoids ARG_MAX limits, provides debugging artifacts on failure, and follows the repo's scratch space convention.
+- **Complete-and-report over error-and-rollback**: When Codex discovers it needs out-of-repo access mid-execution, it completes in-repo changes and reports what it couldn't do. Preserves useful work rather than wasting it.
+- **Plan-only delegation**: Ad-hoc prompts use standard mode. Delegation requires the structured plan decomposition to build effective prompts and provide meaningful implementation units.
+- **Serial execution for all units when delegation is active**: Git stash is a global stack. Mixing parallel and serial execution causes stash entanglement. When delegation mode is on, all units (including locally-executed ones) run serially. This makes delegation mode and swarm mode (Agent Teams) mutually exclusive — a deliberate tradeoff of parallelism for the ability to use Codex.
+- **`--output-schema` for result classification**: `codex exec` returns exit code 0 even on task failure. The structured result schema combined with VERIFY commands provides reliable success/failure signal. Prompt-enforced honest reporting plus cross-validation with VERIFY catches model misreporting.
+- **No timeout for v1**: `codex exec` has no built-in timeout, and the most mature integration (osc-work) doesn't implement one either. Added if users report hung processes.
+
+## Dependencies / Assumptions
+
+- Codex CLI `exec` subcommand with `--yolo`, `--full-auto`, `--output-schema`, `-o`, and `-m` flags remains stable
+- `--output-schema` works with `gpt-5` family models. Known bug #4181 breaks it for `gpt-5-codex` / `codex-` prefixed models — delegation should use `gpt-5` family models (e.g., `o4-mini`, `gpt-5.4`)
+- `$CODEX_SANDBOX` and `$CODEX_SESSION_ID` environment variables continue to be set when running inside Codex
+- `.claude/compound-engineering.local.md` YAML frontmatter reading/writing infrastructure must be built as part of this work — no existing skill currently reads or writes these keys. This is a prerequisite, not an assumption.
+
+## Outstanding Questions
+
+### Deferred to Planning
+
+- [Affects R17][Needs research] What is the optimal prompt template structure for maximizing Codex code quality? The printing-press skill provides one template; the codex plugin's prompting skill (`gpt-5-4-prompting`) may offer insights on how to structure prompts for Codex/GPT models specifically.
+- [Affects R14][Technical] Where exactly in ce:work's Phase 2 task execution loop does the delegation branch? Need to read the current task-worker dispatch logic to identify the cleanest insertion point.
+- [Affects R18][Technical] Should the circuit breaker (3 consecutive failures) reset per-unit or persist across the entire plan execution? Per-unit is more forgiving; per-plan is more conservative.
+- [Affects R22][Technical] How does the agent parse `.claude/compound-engineering.local.md` YAML frontmatter at runtime? Is there an existing utility or must the skill instruct the agent to parse it directly via bash?
+- [Affects R20][Needs testing] How reliably does `--output-schema` constrain Codex's final response? Need to test with representative implementation prompts to validate the result classification approach. Use `--ephemeral` flag during testing to avoid session file clutter (production invocations do not use `--ephemeral` — session persistence is valuable for debugging).
+- [Affects R20][Technical] Fallback behavior when `--output-schema` fails (wrong model family, malformed output): define the exact classification logic when the result JSON is absent.
+
+## Next Steps
+
+-> `/ce:plan` for structured implementation planning

docs/brainstorms/2026-04-01-cross-invocation-cluster-analysis-requirements.md

@@ -0,0 +1,79 @@
+---
+date: 2026-04-01
+topic: cross-invocation-cluster-analysis
+---
+
+# Cross-Invocation Cluster Analysis for resolve-pr-feedback
+
+## Problem Frame
+
+The resolve-pr-feedback skill's cluster analysis is gated on two signals: volume (3+ items) and verify-loop re-entry (2nd+ pass within the same invocation). The verify-loop signal is effectively dead — it requires new review threads to appear between push and verify, but automated reviewers take minutes while verify runs seconds after push. The timing gap makes this gate unreliable at best, and in the common case of automated reviewers, impossible.
+
+This leaves volume as the only working gate. The skill misses the exact scenario clustering was designed for: a reviewer posts feedback about the same *class* of problem across multiple rounds, with each round containing only 1-2 threads. Individually, no round triggers the volume gate. But taken together, there's a clear recurring pattern — e.g., "three separate rounds of feedback all about missing convergence behavior in target writers." The skill should step back and investigate the problem class holistically rather than applying band-aids to each instance.
+
+## Requirements
+
+**Detection Signal**
+
+- R1. Replace the verify-loop re-entry gate signal with a cross-invocation awareness signal. Before triaging, the skill checks whether it has previously resolved threads on this same PR. Its own prior reply comments are the evidence.
+- R2. If prior resolutions exist and new unresolved feedback has arrived since the last resolution, that constitutes the re-entry signal — even with just 1 new item. If no prior resolutions are found (first invocation), the cross-invocation signal does not fire and processing continues with the volume gate as the only cluster trigger.
+- R3. The volume gate (3+ items) remains unchanged as a parallel trigger. The two gates are OR'd: either one fires cluster analysis.
+
+**Cost Control**
+
+- R9. Cross-invocation detection must not add GraphQL API calls. The existing `get-pr-comments` query should be broadened to return both unresolved and resolved threads (with skill replies) in a single call. All cross-invocation analysis — detection, overlap check, clustering — works on data already in memory from that one call.
+- R10. Cross-invocation clustering is scoped to the last N resolution rounds (not all history). A "round" is the set of threads resolved in a single skill invocation. This bounds the data the skill processes regardless of PR history length. Planning should determine the right value of N; 2-3 rounds is likely sufficient since recurring patterns surface in recent history.
+- R11. When the cross-invocation signal fires but the volume gate does not, the skill runs a lightweight overlap check first: compare concern categories and file paths between new and prior threads using data already fetched. Promote to full clustering only if category or spatial overlap exists. If no overlap, skip clustering and process the new thread(s) individually.
+
+**Clustering Input**
+
+- R4. When the cross-invocation signal fires and overlap is confirmed (R11), cluster analysis considers both the new thread(s) AND previously-resolved threads from the last N rounds as input. This enables detecting that the same concern category keeps recurring across rounds.
+- R5. Previously-resolved threads are included in category assignment and spatial grouping alongside new threads, so clusters can span rounds.
+
+**Resolver Behavior on Cross-Invocation Clusters**
+
+- R6. When a cross-invocation cluster forms, the resolver agent assesses the prior fixes and applies one of three modes:
+  - **Band-aid fixes** — prior fixes addressed symptoms, not root cause. Re-examine and potentially redo them as part of a holistic fix.
+  - **Correct but incomplete** — prior fixes were right for their scope, but the recurring pattern reveals the same problem likely exists in untouched sibling code. Keep prior fixes, fix the new thread, and proactively investigate whether the pattern extends to code no reviewer has flagged yet. This is the highest-value mode — it's what catches "three rounds of the same concern category in different files means there are probably more files with the same issue."
+  - **Sound and independent** — prior fixes were adequate and the new thread is genuinely unrelated despite clustering. Use prior context for awareness only.
+- R7. The cluster brief XML gains a `<prior-resolutions>` element listing previously-resolved thread IDs and their concern categories, with reply timestamps (createdAt) to establish ordering across rounds, so the resolver agent has the full cross-round picture.
+
+**Within-Session Verify Loop**
+
+- R8. The within-session verify loop (step 8: if new threads remain, repeat from step 2) continues to function as a workflow mechanism. Replies posted during earlier cycles within the same session count as prior resolutions for the cross-invocation signal, so the new gate naturally subsumes the old verify-loop re-entry gate.
+
+## Success Criteria
+
+- Recurring feedback about the same problem class across 2+ rounds triggers cluster analysis, even when each round has only 1-2 threads
+- A single new thread on a PR with prior resolutions in the same concern category produces a cluster brief that includes both the new and old threads
+- The resolver agent can distinguish three modes: "prior fixes were band-aids, redo holistically", "prior fixes were correct but incomplete, investigate sibling code", and "prior fixes were sound, this is independent"
+- Token cost is bounded: a PR with 15 prior resolution rounds costs no more for clustering than a PR with 3, and unrelated new feedback on a multi-round PR skips clustering entirely after the lightweight overlap check
+
+## Scope Boundaries
+
+- No persistent state files or `.context/` storage — detection relies entirely on GitHub PR comment history
+- No changes to the volume gate threshold or the cluster spatial grouping rules
+- No changes to how the resolver agent handles standard (non-cluster) threads
+- The `get-pr-comments` script currently filters to unresolved threads only (`isResolved == false`). Per R9, this query is broadened to also return resolved threads — no new script, just a wider filter in the existing one
+
+## Key Decisions
+
+- **Detection via own replies, not persistent state**: Prior resolutions are detected by checking for the skill's own reply comments on PR threads. This keeps the skill stateless and avoids `.context/` file management. The data is already authoritative (GitHub is the source of truth for what was resolved).
+- **Three-mode resolver assessment**: The agent distinguishes band-aid fixes (redo), correct-but-incomplete fixes (keep fixes, investigate sibling code), and sound-and-independent fixes (context only). The "correct but incomplete" mode is the highest-value case — it's what turns "three rounds of the same concern in different files" into proactive investigation of untouched code with the same pattern.
+- **Cross-invocation signal subsumes verify-loop signal**: Within-session cycles produce replies that count as prior resolutions, so the new gate handles both cross-session and within-session re-entry without needing a separate verify-loop signal.
+- **Bounded lookback, not full history**: Clustering only considers the last N resolution rounds. Recurring patterns surface in recent history — if the same concern category appeared in the last 2-3 rounds, that's the signal. Going back further adds cost without proportional value.
+- **Zero additional API calls**: Cross-invocation detection piggybacks on the existing `get-pr-comments` query by broadening the filter. All analysis — detection, overlap check, clustering — happens in-memory on data already fetched. No new GraphQL calls.
+- **Two-tier cost control**: The lightweight overlap check (R11) prevents unnecessary full clustering. Most multi-round PRs get unrelated feedback in later rounds; those skip clustering entirely after a cheap metadata comparison. Full clustering only runs when there's evidence it will find something.
+
+## Outstanding Questions
+
+### Deferred to Planning
+
+- [Affects R1][Technical] How should the skill identify its own prior replies? Options include checking the authenticated `gh` user, matching a reply-text pattern, or both. Planning should check what the existing `resolve-pr-thread` and `reply-to-pr-thread` scripts produce and what's easily queryable.
+- [Affects R4][Technical] How should previously-resolved threads be represented in the triage list alongside new threads? They need a status marker (e.g., `previously-resolved`) so clustering can include them while dispatch skips re-resolution of threads that don't cluster.
+- [Affects R9][Technical] What fields does the existing `get-pr-comments` GraphQL query return per thread? Planning should check whether the query already fetches enough data (file path, line range, comment body, author) to support both resolved and unresolved threads without changing the response shape, or whether fields need to be added.
+- [Affects R10][Technical] What is the right value of N for resolution round lookback? 2-3 is the starting hypothesis. Planning should consider typical PR review patterns and the marginal value of deeper lookback.
+
+## Next Steps
+
+-> `/ce:plan` for structured implementation planning

docs/brainstorms/2026-04-02-slack-analyst-agent-requirements.md

@@ -0,0 +1,101 @@
+---
+date: 2026-04-02
+topic: ce-slack-researcher-agent
+---
+
+# Slack Analyst Agent
+
+## Problem Frame
+
+Coding agents operating within compound-engineering workflows (ideate, plan, brainstorm) have no visibility into organizational knowledge that lives in Slack. Decisions, constraints, ongoing discussions, and context about projects are often undocumented anywhere except Slack conversations. When a developer is about to make a change, relevant Slack context -- a discussion about why something was designed a certain way, a decision to deprecate a feature, constraints mentioned by another team -- is invisible to the agent assisting them.
+
+The official Slack plugin provides user-facing commands (`/slack:find-discussions`, `/slack:summarize-channel`), but these are standalone and manual. There is no research agent that compound-engineering workflows can dispatch programmatically to surface Slack context as part of their normal research phase.
+
+## Requirements
+
+**Agent Identity and Placement**
+
+- R1. Create a research-category agent at `agents/research/ce-slack-researcher.md` following the established research agent pattern (frontmatter with name, description, model:inherit; examples block; phased execution).
+- R2. The agent's role is analytical: it searches Slack for context relevant to the task at hand and returns a concise, structured digest. It does not send messages, create canvases, or take any write actions in Slack.
+
+---
+
+**Precondition and Short-Circuit Design**
+
+- R3. Two-level short-circuit to minimize token waste:
+  - **Caller level:** Calling workflows check whether the Slack MCP server is connected before dispatching the agent. If unavailable, skip dispatch entirely. Detection should check for MCP availability (not specific tool names, which may change).
+  - **Agent level:** The agent performs its own precondition check on entry. If Slack MCP tools are not accessible, return a short message ("Slack MCP not connected -- skipping Slack analysis") and exit immediately.
+- R4. The agent should also short-circuit if the caller provides no meaningful search context (e.g., an empty or overly generic topic). Return a message indicating insufficient context rather than running broad, low-value searches.
+
+---
+
+**Search Strategy**
+
+- R5. Default behavior is search-first: run 2-3 targeted searches using `slack_search_public_and_private` based on keywords derived from the task topic. Search both public and private channels by default (user has already authed the Slack MCP).
+- R6. Read threads (`slack_read_thread`) only for high-relevance search hits -- not speculatively. Limit thread reads to avoid runaway token consumption (cap at ~3-5 thread reads per invocation).
+- R7. Accept an optional channel hint from the caller. When provided, also read recent history from the specified channel(s) using `slack_read_channel` with appropriate time bounds. Without a channel hint, do not read channel history -- search results are sufficient.
+- R8. Future consideration (not in scope): a user preference/setting for channels that should always be searched. Defer to a later iteration.
+
+---
+
+**Output Format**
+
+- R9. Return a concise summary digest organized by topic/theme. Each finding should include:
+  - The topic or theme
+  - A brief summary of what was discussed/decided
+  - Source attribution (channel name, approximate date, participants if notable)
+  - Relevance to the current task
+- R10. When no relevant Slack context is found, return a short explicit statement ("No relevant Slack discussions found for [topic]") rather than generating filler.
+- R11. Keep output compact enough to be useful context without dominating the calling workflow's token budget. Target roughly 200-500 tokens for typical results.
+
+---
+
+**Workflow Integration**
+
+- R12. Integrate into three calling workflows:
+  - **ce-ideate** -- dispatch during Phase 1 (Codebase Scan), alongside learnings-researcher. Slack context enriches ideation by surfacing org discussions about the focus area.
+  - **ce-plan** -- dispatch during the research/context-gathering phase. Slack context surfaces constraints, prior decisions, and ongoing discussions relevant to the implementation.
+  - **ce-brainstorm** -- dispatch during Phase 1.1 (Existing Context Scan). Brainstorming especially benefits from knowing what the org has already discussed about the topic.
+- R13. In all calling workflows, dispatch the Slack analyst agent in parallel with other research agents (learnings-researcher, etc.) to avoid adding latency. Callers wait for all parallel agents to return before consolidating results (this is the existing pattern for parallel research dispatch). The Slack analyst's dispatch condition is MCP availability (R3). The agent itself handles the meaningful-context check (R4) internally.
+- R14. Callers should incorporate the Slack analyst's output into their existing context summary alongside other research results, not as a separate section.
+
+---
+
+**Dependency on External Plugin**
+
+- R15. The Slack MCP server is owned by the official Slack plugin, not compound-engineering. The agent uses MCP tools that the Slack plugin configures. This creates a soft dependency: the agent is useful only when the Slack plugin is installed and authenticated, but compound-engineering must not require it.
+- R16. Do not bundle or reference the Slack plugin's `.mcp.json` or configuration from within compound-engineering. The agent relies solely on MCP tools being available at runtime.
+
+## Success Criteria
+
+- When Slack MCP is connected, the agent surfaces relevant org context that would not have been available from codebase analysis alone, enriching the output of ideate/plan/brainstorm workflows.
+- When Slack MCP is not connected, the agent adds zero token overhead (caller-level short-circuit prevents dispatch).
+- The agent completes within a reasonable time budget (~10-15 seconds) and returns compact output that doesn't bloat calling workflows.
+
+## Scope Boundaries
+
+- No write actions to Slack (no sending messages, no creating canvases).
+- No channel history reads unless the caller provides an explicit channel hint.
+- No user preference/settings system for default channels (deferred).
+- No replacement of existing Slack plugin commands -- this agent is complementary, not competitive.
+- No installation or configuration of the Slack MCP -- that remains the Slack plugin's responsibility.
+
+## Key Decisions
+
+- **Agent, not skill:** This is a sub-agent invoked programmatically by workflows, not a user-facing slash command. It lives in `agents/research/`.
+- **Public + private search by default:** The user already authed the Slack MCP, so searching private channels avoids missing the richest context.
+- **Search-first, reads on demand:** Avoids the token cost of speculatively reading channel history. Thread reads are limited to high-relevance hits.
+- **Concise digest output:** Callers are responsible for interpreting the output for their specific context. The agent returns useful summaries, not raw message dumps.
+- **MCP availability check, not tool-name check:** Callers check if the Slack MCP is connected, not for specific tool names (which may change in future Slack MCP versions).
+
+## Outstanding Questions
+
+### Deferred to Planning
+
+- [Affects R3][Technical] How exactly should callers detect Slack MCP availability? Claude Code's tool list inspection, checking for any `slack_*` tool prefix, or another mechanism?
+- [Affects R5][Needs research] What is the optimal number of search queries per invocation to balance coverage vs. token cost? Start with 2-3 and tune based on real usage.
+- [Affects R12][Technical] What modifications are needed in ce-ideate, ce-plan, and ce-brainstorm skill files to add the conditional dispatch? Review each skill's research phase to find the right insertion point.
+
+## Next Steps
+
+-> `/ce:plan` for structured implementation planning

docs/brainstorms/2026-04-05-universal-planning-requirements.md

@@ -0,0 +1,87 @@
+---
+date: 2026-04-05
+topic: universal-planning
+---
+
+# Universal Planning: Non-Software Task Support for ce:plan and ce:brainstorm
+
+## Problem Frame
+
+Users naturally reach for `/ce:plan` to plan any multi-step task — trip itineraries, study plans, content strategies, research workflows. Currently, the model self-gates and refuses non-software tasks because ce:plan's language is heavily software-centric ("implementation units", "test scenarios", "repo patterns"). This forces users back to unstructured prompting for non-software work, losing the structured thinking that makes ce:plan valuable.
+
+The structured thinking behind ce:plan — breaking down ambiguity, researching context, sequencing steps, identifying dependencies — is domain-agnostic. The skill's value proposition should not be limited to software.
+
+**Why a conditional path instead of just softening language:** Softening the self-gating language in SKILL.md would be cheaper and might stop the refusal. But the value of ce:plan for non-software tasks comes from the structured workflow — ambiguity assessment, research orchestration, quality-guided output, and a durable plan file. Without the non-software path, the model would attempt to follow software-specific phases (repo research, implementation units, test scenarios) on a non-software task, producing a worse result than a direct prompt. The conditional path lets non-software tasks benefit from structured thinking without fighting software-specific structure.
+
+See: [GitHub issue #517](https://github.com/EveryInc/compound-engineering-plugin/issues/517)
+
+## Requirements
+
+**Skill Description and Trigger Language**
+
+- R1. ce:plan's YAML `description` and trigger phrases are updated to include non-software planning. The model reads this description when deciding which skill to invoke — if triggers only mention software concepts, the internal detection logic never fires. Example: *"Create structured plans for any multi-step task — software features, research workflows, events, study plans, or any goal that benefits from structured breakdown."*
+
+**Detection and Routing**
+
+- R2. ce:plan detects whether a task is software-related or not early in Phase 0, before searching for requirements docs or launching software-specific research agents
+- R3. Detection error policy: false positives (software task routed to non-software path) are worse than false negatives (non-software task staying on software path), because a false positive skips repo research and produces a disconnected plan. When detection is ambiguous, ask the user rather than guessing. Default to software path when uncertain.
+- R4. ce:brainstorm: verify whether it actually self-gates on non-software tasks. If it doesn't (its description is already domain-agnostic), no changes needed — its existing Phase 4 handoff to ce:plan already works. If it does self-gate, soften the gating language so it stops refusing. ce:plan owns the non-software planning path; ce:brainstorm only needs to not block the flow.
+
+**Non-Software Planning Path in ce:plan (Core — Phase 1)**
+
+- R5. When a non-software task is detected, ce:plan skips Phases 0.2-0.5 and Phase 1 (all software-specific) and loads a reference file (`references/universal-planning.md`) containing the alternative workflow. Existing Phase 5.2 (Write Plan File) and Phase 5.4 (Handoff options) are reusable; Phase 5.3 (Confidence Check with software-specific agents) is not.
+- R6. The non-software path assesses ambiguity: is the request clear enough to plan directly, or does it need clarification first?
+- R7. When clarification is needed, the non-software path runs focused Q&A inline — up to 3 questions as a guideline, not a hard cap — targeting the most impactful clarifying questions. Stop when remaining ambiguity is acceptable to defer to plan execution.
+- R8. The plan output is guided by quality principles (what makes a great plan), not a prescribed template. The model decides the format based on the task domain
+
+**Non-Software Planning Path (Extensions — Phase 2, after core validation)**
+
+- R9. The non-software path can invoke web search directly (no new MCP integrations or research subsystems) when the task benefits from external context. The main skill collates findings inline.
+- R10. The non-software path can still interact with local files when the task involves them (e.g., "read these materials and create a study plan")
+
+**Token Cost Management**
+
+- R11. The non-software path lives entirely in reference files loaded conditionally via backtick paths. Main SKILL.md changes are minimal — detection stub only
+- R12. The software planning path remains completely unchanged — negligible token cost increase for software-only users (detection stub only)
+
+## Success Criteria
+
+- `/ce:plan a 3 day trip to Disney World with 2 kids ages 11 and 13` produces a thoughtful, structured plan instead of refusing
+- `/ce:plan look at the materials in this folder and create a study plan` reads local files and produces a study plan
+- `/ce:brainstorm plan my team offsite` produces a structured plan (verify — may already work without changes)
+- `/ce:plan plan the database migration to support multi-tenancy` routes to the software path (boundary case — software despite "plan" and "migration")
+- `/ce:plan plan our team's migration to the new office` routes to the non-software path (boundary case — non-software despite "migration")
+- Software tasks continue to work identically — no regression
+- Non-software detection adds negligible tokens to the software path
+
+## Scope Boundaries
+
+- Not building domain-specific planning templates (travel, education, etc.) — the model adapts format to domain
+- Not changing the software planning path in ce:plan at all
+- Not adding non-software support to ce:work or other downstream skills — those remain software-focused
+- Not adding MCP integrations or domain-specific research tools — use existing web research capabilities
+- Pipeline mode (LFG/SLFG): non-software tasks are not supported. Detection should short-circuit the pipeline gracefully rather than producing a plan that ce:work cannot execute. The short-circuit contract (what ce:plan returns, how LFG's retry gate handles it) is deferred to planning.
+
+## Key Decisions
+
+- **ce:plan owns universal planning, not ce:brainstorm**: The durable output is a plan file. Brainstorming Q&A is a means to an end, not a separate non-software workflow. ce:plan does its own focused Q&A when needed.
+- **No prescribed template for non-software outputs**: Impossible to anticipate all domains. Quality principles guide the model; format is emergent.
+- **Reference file extraction**: Non-software path in `references/universal-planning.md` keeps token costs down and avoids bloating the main skill for software users.
+- **Default to software when uncertain**: False positives (software → non-software) are costlier than false negatives (non-software → software). When ambiguous, ask the user.
+- **Non-software plan file location is user-chosen.** Before writing, prompt the user with options: (a) `docs/plans/` if it exists, (b) current working directory, (c) `/tmp`, or (d) a path they specify. Frontmatter omits software-specific fields (`type: feat|fix|refactor`). Filename convention (`YYYY-MM-DD-<descriptive-name>-plan.md`) applies regardless of location.
+- **Incremental delivery**: Core path (R5-R8) first — detection, ambiguity assessment, quality-guided output. Extensions (R9-R10) — research orchestration, local file interaction — added after core validation.
+
+## Outstanding Questions
+
+### Deferred to Planning
+
+- [Affects R2][Technical] What heuristics should the detection use? Likely a combination of: does the request reference code/repos/files in a software context, specific programming languages, software concepts? Needs to handle ambiguous cases like "plan a migration" (could be data migration or office migration). Error policy (R3) constrains the design: default to software, ask when uncertain.
+- [Affects R8][Technical] What output quality principles produce the best non-software plans? Define these directly during planning — principles like specificity, sequencing, resource identification, contingency planning — rather than running a separate research effort.
+- [Affects R9][Technical] Which research mechanisms work best for non-software tasks? WebSearch/WebFetch directly, or best-practices-researcher adapted for non-software topics? Defer until core path is validated.
+- [Affects R4][Technical] Does ce:brainstorm actually self-gate on non-software tasks? Verify before building detection there. Its description appears domain-agnostic — changes may be unnecessary. Note: even if it doesn't self-gate, its Phase 1.1 repo scan would waste tokens finding nothing on a non-software task. Decide whether that's acceptable or needs a skip.
+- [Affects R5][Technical] Non-software plan file location: prompt the user with options (docs/plans/ if it exists, CWD, /tmp, or custom path). Only show docs/plans/ option when the directory exists.
+- [Affects pipeline][Technical] LFG/SLFG short-circuit contract: does ce:plan write a stub file, return an error, or produce no file? LFG has a hard gate that retries if no plan file exists — the contract must satisfy or bypass that gate.
+
+## Next Steps
+
+-> `/ce:plan` for structured implementation planning

docs/brainstorms/2026-04-17-ce-release-notes-skill-requirements.md

@@ -0,0 +1,79 @@
+---
+date: 2026-04-17
+topic: ce-release-notes-skill
+---
+
+# `ce-release-notes` Skill
+
+## Problem Frame
+
+The `compound-engineering` plugin ships frequently — often multiple releases per week. Users who install the plugin via the marketplace can't easily keep up with what's changed: skill renames, new behaviors, retired commands, or relevant fixes. The release history exists publicly on GitHub (release-please-generated GitHub Releases at `EveryInc/compound-engineering-plugin`), but scrolling through release pages to answer "what happened to the deepen-plan skill?" is friction users won't bother with.
+
+This skill provides a conversational interface over the plugin's GitHub Releases so a user can ask either "what's new?" or a specific question and get a grounded, version-cited answer without leaving Claude Code.
+
+**Premise note:** The user-pain claim above is grounded in the rapid release cadence rather than in cited support asks or telemetry. We accept the residual risk that the skill may see low adoption if the conversational-lookup framing turns out to be a weaker need than discoverability or release-page bookmarking.
+
+## Requirements
+
+**Invocation and Modes**
+- R1. Skill is invoked via slash command `/ce:release-notes` (matching the `ce:` namespace convention used by sibling skills like `/ce:plan`, `/ce:brainstorm`). The skill directory is `plugins/compound-engineering/skills/ce-release-notes/`; the SKILL.md `name:` frontmatter field is `ce:release-notes` (colon form, not dash) — that is what produces the `/ce:release-notes` slash command. (Several existing `ce-` skills use `name: ce-x` and are not slash-invoked; this one needs the colon form to match R1.)
+- R2. Bare invocation (`/ce:release-notes`) returns a summary of recent releases.
+- R3. Argument invocation (`/ce:release-notes <question or topic>`) returns a direct answer to the user's question, grounded in the relevant release(s).
+- R4. **v1 is slash-only invocation.** The SKILL.md frontmatter sets `disable-model-invocation: true` so the skill only fires when the user explicitly types `/ce:release-notes`. Auto-invocation is deferred to a possible v2 once dogfooding shows users clearly want conversational triggering and a tested gating description has been validated against a prompt corpus.
+
+**Data Source**
+- R5. Source of truth is the GitHub Releases API for `EveryInc/compound-engineering-plugin`. **Layered access strategy:** prefer the `gh` CLI when available (authenticated, consistent JSON output, better error messages, higher rate limits). Fall back to anonymous HTTPS against `https://api.github.com/repos/EveryInc/compound-engineering-plugin/releases` (or the equivalent paginated endpoint) when `gh` is missing or unauthenticated. The repo is public, so anonymous reads work and the 60 req/hr-per-IP unauth'd limit is more than enough for this skill's invocation frequency.
+- R6. Only releases tagged with the `compound-engineering-v*` prefix are considered. Sibling tags (`cli-v*`, `coding-tutor-v*`, `marketplace-v*`, `cursor-marketplace-v*`) are filtered out, even though `cli` and `compound-engineering` share version numbers via release-please's `linked-versions` plugin.
+- R7. No local caching, no fallback to `CHANGELOG.md` files. Always fetch live.
+- R8. Skill must fail gracefully with an actionable message when **both** access paths fail (e.g., no network, GitHub API outage, rate-limit exhaustion on the anonymous fallback). Missing `gh` alone is not a failure — the skill silently uses the anonymous fallback.
+
+**Output — Summary Mode**
+- R9. Default window is the last 10 plugin releases.
+- R10. Per-release section format: version + publish date + the release-please-generated changelog body (already grouped by `Features`, `Bug Fixes`, etc.), trimmed minimally — release sizes vary, so do not impose a uniform highlight count.
+- R11. Each release section links to its GitHub release URL so users can read the full notes.
+
+**Output — Query Mode**
+- R12. Search window is the last 20 plugin releases — fixed cap, no expansion. 20 releases is already a substantial corpus (multiple weeks of cadence). If no matching content is found within that window, report "not found" and surface the GitHub releases page link (per R14) so the user can search further manually.
+- R13. **When a confident match is found**, the answer is a direct narrative response that cites the specific release version(s) the answer is drawn from (e.g., "The `deepen-plan` skill was renamed to `ce-debug` in `v2.45.0`"). Include a link to the cited release. The release body itself is a terse one-line conventional-commit bullet per change with a linked PR number; for query-mode synthesis the skill should follow the linked PR(s) (e.g., `gh pr view <N>`) to ground the narrative in the rich PR description rather than only the commit subject. (Verified against `v2.65.0`–`v2.67.0` release bodies and PR #568.)
+- R14. **When no confident match is found** (after expanding the search window per R12) **or the answer is uncertain**, say so plainly rather than guessing — and surface a link to the GitHub releases page so the user can investigate further.
+
+## Success Criteria
+- A user who installed the plugin via the marketplace can run `/ce:release-notes` and immediately see what's shipped recently in the compound-engineering plugin (not CLI noise, not other plugins).
+- A user can ask `/ce:release-notes what happened to deepen-plan?` and get a direct narrative answer with a version citation, without having to open any browser tab.
+- The skill works for users without `gh` installed (silent anonymous-API fallback) and produces a clear error only when both access paths fail.
+
+## Scope Boundaries
+- **Out of scope:** Coverage of `cli`, `coding-tutor`, `marketplace`, or `cursor-marketplace` releases. Only `compound-engineering` plugin releases are surfaced.
+- **Out of scope:** "What's coming next" / unreleased changes. The skill does not peek at the open release-please PR. Only shipped releases are summarized.
+- **Out of scope:** Local caching, CHANGELOG.md parsing, or any source other than the GitHub Releases API.
+- **Out of scope:** Per-PR or per-commit drill-down *as a primary user-facing surface*. Query mode may follow PR links for context (per R13), but the skill does not browse arbitrary commits or expose PR-level navigation as a separate mode.
+- **Out of scope:** Customization flags for window size or output format in v1. Defaults are fixed; users can ask follow-up questions in chat to drill deeper.
+
+## Key Decisions
+- **Plugin-only filter (excludes `cli-v*`):** Linked versions mean a `2.67.0` bump can contain CLI-only or plugin-only changes; surfacing both would dilute the user-facing signal. Users who care about plugin behavior should not have to mentally filter CLI noise.
+- **GitHub Releases over CHANGELOG.md:** GitHub Releases are authoritative for what shipped, are accessible without a repo checkout (most plugin users won't have one), and the release-please-generated body is already markdown-grouped and ready to display.
+- **Slash-only invocation in v1 (no auto-invoke):** No sibling `ce:*` skill currently auto-invokes. Making this the first one introduces a hard-to-validate gating problem (the skill description is the only lever, and the failure modes are silent — either firing on unrelated projects' "what's new?" prompts, or never firing for actual CE-shaped questions). Slash-only satisfies both stated user journeys (`/ce:release-notes` bare summary and `/ce:release-notes <question>`) without the gating risk. Auto-invoke is deferred to a possible v2 once dogfooding shows the conversational triggering is genuinely wanted and a tested gating description exists.
+- **Layered data access (`gh` preferred, anonymous public API fallback):** The repo is public, so anonymous reads work and the 60 req/hr unauth'd limit is far above this skill's invocation frequency. Layering means users without `gh` installed still get value rather than bouncing on an "install gh and retry" message. Prefer `gh` when present for cleaner error handling, consistent JSON output, and authenticated rate limits.
+- **No local caching:** `gh release list` is fast (~1s for metadata; bodies add some cost) and release queries are infrequent; caching adds carrying cost (invalidation, location in `.context/`) without meaningful payoff. Reversal cost is low — caching can be added later if real latency or frequency problems show up.
+- **Two-mode design instead of always-query:** A bare-invocation summary serves the casual "what have I missed?" use case, which is materially different from "what specifically happened to X?". One skill covers both with a clean argument convention.
+- **Distinct from the existing `changelog` skill:** The plugin already ships a `changelog` skill that produces witty daily/weekly changelog summaries of recent activity. That serves a different use case (narrative recap of work) than this skill's version-aware release-notes lookup against shipped GitHub Releases. The two are complementary, not redundant.
+
+## Dependencies / Assumptions
+- Users have **either** the `gh` CLI (preferred path) **or** outbound HTTPS access to `api.github.com` (anonymous fallback path). Per R5, missing `gh` alone is not a failure.
+- The 60 req/hr anonymous limit is per source IP, not per user. Users on shared NAT egress (corporate networks, VPN exit nodes) could in principle exhaust the budget collectively even at low individual usage. We accept this as low-likelihood given the skill's invocation pattern; if it surfaces in practice, encourage `gh auth login` rather than adding caching.
+- The repo `EveryInc/compound-engineering-plugin` remains the canonical source. (If the plugin moves repos, the hardcoded repo reference in the skill must be updated.)
+- Release-please continues to use the `compound-engineering-v*` tag prefix and the conventional-commit-grouped release body format. A change to release-please configuration could break R6 or R10.
+
+## Outstanding Questions
+
+### Deferred to Planning
+- [Affects R10][Technical] Should the summary impose a maximum-length cap on individual release bodies (separate from R10's no-uniform-highlight-count rule), to prevent a single 30-bullet release from dominating the summary view? Decide based on real release sizes during implementation.
+- [Affects R8][Technical] Exact failure messages when both access paths fail (network down, GitHub outage, anonymous rate-limit hit). Ensure they're actionable (point the user to the GitHub releases URL as a manual fallback).
+- [Affects R5][Technical] Implementation choice for the anonymous fallback: shell out to `curl` + `jq`, or use a different HTTP client. Decide based on cross-platform portability requirements (note: AGENTS.md "Platform-Specific Variables in Skills" rules apply since this skill will be converted for Codex/Gemini/OpenCode).
+- [Affects R13, R14][Technical] Define the "confident match" criterion that gates R13 (direct narrative answer) vs. R14 (say-so-plainly). Options include keyword/substring match against release bodies, semantic match via embedding, or LLM judgment with an explicit confidence prompt. Decide during planning based on cost and accuracy tradeoffs.
+- [Affects R4][Needs research] If/when v2 auto-invoke is reconsidered, define the actual gate. Since v1 has no auto-invoke surface to observe, "dogfooding shows users want it" is unfalsifiable as written — the v2 trigger needs a concrete source of evidence (explicit user requests, opt-in beta flag with telemetry, or a stated time-box for revisiting).
+- [Affects R5][Technical] Should the repo reference (`EveryInc/compound-engineering-plugin`) be hardcoded in the skill, or derived from `.claude-plugin/plugin.json` (`homepage`/`repository` field) for portability? Hardcoding is simpler; derivation survives a future repo move without skill edits. Decide based on portability vs. complexity tradeoff during planning.
+- [Affects R10][Technical] Release-please body format drift handling: R10 assumes the `Features`/`Bug Fixes` markdown grouping. Decide whether to (a) accept silent degradation if release-please config changes, (b) parse defensively and fall back to raw rendering, or (c) detect drift and surface a warning. Low priority — release-please config has been stable.
+
+## Next Steps
+- `/ce:plan docs/brainstorms/2026-04-17-ce-release-notes-skill-requirements.md` for structured implementation planning.

docs/brainstorms/2026-04-17-ce-review-interactive-judgment-requirements.md

@@ -0,0 +1,155 @@
+---
+date: 2026-04-17
+topic: ce-review-interactive-judgment
+---
+
+# ce:review Interactive Judgment Loop
+
+## Problem Frame
+
+`ce:review`'s Interactive mode produces a report, auto-applies `safe_auto` fixes, and then asks a single bucket-level policy question covering every remaining `gated_auto` and `manual` finding as a group. The findings themselves are presented as a pipe-delimited table grouped by severity.
+
+Two problems surface repeatedly:
+
+1. **Judgment calls are hard to make.** When a finding needs human judgment, the table row rarely gives enough context to decide confidently. The user is asked to approve or defer a bucket of findings they haven't individually understood.
+2. **High-volume feedback is unreason-able.** A review producing 8-12 findings turns into a scrolling table the user can't engage with. There's no way to respond to individual items meaningfully — the only choice is "approve the whole bucket" or "defer the whole bucket."
+
+The result is that Interactive mode mostly degrades into rubber-stamping or wholesale deferral. The "judgment" in `gated_auto` / `manual` routing is never actually exercised per-finding.
+
+## Requirements
+
+**Routing after `safe_auto` fixes**
+
+- R1. After `safe_auto` fixes are applied, if any `gated_auto` or `manual` findings remain, Interactive mode presents a four-option routing question that replaces today's bucket-level policy question.
+- R2. When zero `gated_auto` / `manual` findings remain after `safe_auto`, the routing question is skipped. Interactive mode shows a brief completion summary (e.g., "All findings resolved — N `safe_auto` fixes applied.") before handing off to the final-next-steps flow.
+- R3. The routing question names the detected tracker inline (e.g., "File a Linear ticket per finding") only when detection is high-confidence — the tracker is explicitly named in `CLAUDE.md` / `AGENTS.md` or equivalent project documentation. When detection is lower-confidence, the label uses a generic form (e.g., "File an issue per finding") and the agent confirms the tracker with the user before executing any ticket creation.
+- R4. The four routing options are:
+  - (A) `Review each finding one by one — accept the recommendation or choose another action`
+  - (B) `LFG. Apply the agent's best-judgment action per finding`
+  - (C) `File a [TRACKER] ticket per finding without applying fixes`
+  - (D) `Report only — take no further action`
+- R5. Routing option C is a batch-defer shortcut: it files tickets for every pending `gated_auto` / `manual` finding without per-finding confirmation. The walk-through's own Defer option is per-finding; C skips that interactivity.
+
+**Per-finding walk-through (routing option: Review)**
+
+- R6. When the user picks the walk-through, findings are presented one at a time in severity order (P0 first). Each per-finding question opens with a position indicator (e.g., "Finding 3 of 8 (P1):") so the user can judge how many decisions remain.
+- R7. Each per-finding question includes: plain-English statement of what the bug does, severity, confidence, the proposed fix (diff or concrete action), and a short reasoning for why the fix is right (grounded in codebase patterns when available).
+- R8. Per-finding options:
+  - `Apply the proposed fix`
+  - `Defer — file a [TRACKER] ticket`
+  - `Skip — don't apply, don't track`
+  - `LFG the rest — apply the agent's best judgment to this and remaining findings`
+- R9. For findings with no concrete fix to apply (advisory-only), option A becomes `Acknowledge — mark as reviewed`. Defer, Skip, and LFG the rest remain unchanged.
+- R10. "Override" on a per-finding question means picking a different preset action (Defer or Skip in place of Apply); no inline freeform custom fix authoring. A user who wants a custom fix picks Skip and hand-edits outside the flow.
+
+When exactly one `gated_auto` / `manual` finding remains, the walk-through's wording adapts for N=1 (e.g., "Review the finding" rather than "Review each finding one by one"), and `LFG the rest` is suppressed because no subsequent findings exist to bulk-handle.
+
+**LFG path (routing option: LFG)**
+
+- R11. LFG applies the per-finding action the agent would have recommended in the walk-through — Apply, Defer, or Skip. There is no separate confidence threshold; confidence already shapes what the agent recommends. The top-level LFG option scopes to every `gated_auto` / `manual` finding; the walk-through's `LFG the rest` (R8) scopes to the current finding and everything not yet decided. Both share the same per-finding mechanic and the same bulk preview (R13-R14).
+- R12. LFG (and `LFG the rest`) produces a single completion report after execution that must include, at minimum:
+  - per-finding entries with: title, severity, action taken (Applied / Deferred / Skipped / Acknowledged), the tracker URL or in-session task reference for Deferred entries, and a one-line reason for Skipped entries grounded in the finding's confidence or content
+  - summary counts by action
+  - any failures called out explicitly (fix application failed, ticket creation failed)
+  - the existing end-of-review verdict
+
+**Bulk action preview**
+
+- R13. Before executing any bulk action — top-level LFG (routing option B), top-level File tickets (routing option C), or walk-through `LFG the rest` (R8) — Interactive mode presents a compact plan preview and asks the user to confirm with `Proceed` or back out with `Cancel`. Two options. No per-item decisions in the preview; per-item decisioning is the walk-through's role.
+- R14. The preview content groups findings by the action the agent intends to take (e.g., `Applying (N):`, `Filing [TRACKER] tickets (N):`, `Skipping (N):`, `Acknowledging (N):`). Each finding gets one line under its bucket, written as a compressed form of the framing-quality bar (R22-R25) — observable behavior over code structure, no function or variable names unless needed to locate the issue. For walk-through `LFG the rest`, the preview scopes to remaining findings only and notes how many are already decided (e.g., "LFG plan — 5 remaining findings (3 already decided)").
+
+**Recommendation tie-breaking**
+
+- R15. When merged findings carry conflicting recommendations across contributing reviewers (e.g., one reviewer says Apply, another says Defer), synthesis picks the most conservative action using the order `Skip > Defer > Apply` so that LFG and walk-through behavior are deterministic and auditable post-hoc.
+
+**Defer behavior and tracker detection**
+
+- R16. Defer actions (from the walk-through, from the LFG path, or from routing option C) file a ticket in the project's tracker.
+- R17. The SKILL.md instruction for tracker detection is minimal: the agent determines the project's tracker from whatever documentation is obvious (primarily `CLAUDE.md` / `AGENTS.md`), without an enumerated checklist of files to read.
+- R18. When tracker detection is uncertain, the agent prefers durable external trackers over in-session-only primitives and communicates both the fallback behavior and the durability trade-off to the user before executing any Defer action.
+- R19. If a Defer action fails at ticket-creation time (API error, auth expiry, rate limit, malformed body), the agent surfaces the failure inline and offers: retry, fall back to the next available sink, or convert the finding to Skip with the error recorded in the completion report. Silent failure is not acceptable.
+- R20. When no external tracker is detectable and no harness task-tracking primitive is available on the current platform (e.g., CI contexts, converted targets without task binding), Defer is not offered as a menu option. The routing question and walk-through omit Defer paths and the agent tells the user why.
+- R21. The internal `.context/compound-engineering/todos/` system is **not** part of the fallback chain. It is on a deprecation path and must not be extended by this work.
+
+**Framing quality (cross-cutting)**
+
+- R22. Every user-facing surface that describes a finding — per-finding walk-through questions, LFG completion reports, and ticket bodies filed by Defer actions — explains the problem and fix in plain English that a reader can understand without opening the file.
+- R23. The framing leads with the *observable behavior* of the bug (what a user, attacker, or operator sees), not the code structure. Function and variable names appear only when the reader needs them to locate the issue.
+- R24. The framing explains *why the fix works*, not just what it changes. When a similar pattern exists elsewhere in the codebase, reference it so the recommendation is grounded.
+- R25. The framing is tight: approximately two to four sentences plus the minimum code needed to ground it. Longer framings are a regression.
+
+*Illustrative pair — weak vs. strong framing for the same finding:*
+
+> **Weak (code-citation style):**
+> *orders_controller.rb:42 — missing authorization check. Add `current_user.owns?(account)` guard before query.*
+>
+> **Strong (framed for a human):**
+> *Any signed-in user can read another user's orders by pasting the target account ID into the URL. The controller looks up the account and returns its orders without verifying the current user owns it. Adding a one-line ownership guard before the lookup matches the pattern already used in the shipments controller for the same attack.*
+
+- R26. R22-R25 depend on reviewer personas producing framing-suitable `why_it_matters` and `evidence` fields. If the planning-phase sample shows existing persona outputs do not meet this bar, persona prompt upgrades (or a synthesis-time rewrite pass) land with or before this work.
+
+**Mode boundaries**
+
+- R27. Only Interactive mode changes behavior. Autofix, Report-only, and Headless modes are unchanged.
+- R28. The existing post-review "final next steps" flow (push fixes / create PR / exit) runs only when one or more fixes were applied to the working tree. It is skipped after routing option C (File tickets per finding) and option D (Report only), and skipped when LFG or the walk-through completes without any Apply action.
+
+## Success Criteria
+
+- A user facing a review with one high-stakes finding can decide confidently about the fix without rereading the file.
+- A user facing a review with 8+ findings has a clear path to either engage per-item or trust the agent's judgment in one keystroke.
+- A user who starts the walk-through but runs out of attention can bail mid-flow into a bulk action without losing the findings still ahead of them.
+- Deferred findings land in the team's actual tracker (not a `.context/` file that gets forgotten).
+- LFG runs feel honest: the completion report makes clear what was applied and why, so a user can audit the agent's judgment post-hoc.
+- For reviews with three or more `gated_auto` / `manual` findings, Review is picked at a meaningful share of the time — LFG alone is not disproportionately the default, so the intervention actually shifts engagement upward rather than renaming the rubber-stamp.
+- A first-time user of Interactive mode understands which routing options cause external side effects (fixes applied to the working tree, tickets filed in an external tracker) before choosing, without needing external docs.
+
+## Scope Boundaries
+
+- No new `ce:fix` skill. All changes live inside `ce:review`.
+- No changes to the findings schema, persona agents, merge/dedup pipeline, or autofix-mode residual-todo creation in this work.
+- No inline freeform fix authoring in the walk-through. The walk-through is a decision loop, not a pair-programming surface.
+- The "approve the fix's intent but write a variant" case is explicitly unsupported in v1. Users in that situation pick Skip and hand-edit outside the flow; if they want the variant tracked, they file a ticket manually.
+- No changes to Autofix, Report-only, or Headless mode behavior.
+- The pre-menu findings table format (pipe-delimited, severity-grouped) is intentionally unchanged. The walk-through is the engagement surface for high-volume feedback; the table only needs to be scannable enough to reach the routing menu. Restructuring the table format is a separate follow-up if it proves necessary.
+- Phasing out the internal `.context/compound-engineering/todos/` system and the `/todo-create`, `/todo-triage`, `/todo-resolve` skills is acknowledged as the long-term direction but is not scoped into this redesign. A separate follow-up covers that cleanup.
+- The current bucket-level policy question wording (`Review and approve specific gated fixes` / `Leave as residual work` / `Report only`) is removed and replaced by the four-option routing question. No backward-compatibility shim.
+
+## Key Decisions
+
+- **Expand Interactive mode, no new skill.** Review and fix stay colocated; the review artifact, routing metadata, and fixer subagent are already wired up. A separate `ce:fix` skill would split state and add reintegration cost without clear benefit.
+- **Four-option routing upfront, not an escape hatch buried inside the walk-through.** LFG and tracker-deferral are legitimate primary intents for many reviews, not fallbacks. Offering them as peers to the walk-through is honest about how users actually want to engage.
+- **LFG = auto-accept recommendations, not a separate confidence policy.** Keeps the mental model simple. Confidence is already baked into whether the agent recommends Apply, Defer, or Skip for a given finding.
+- **Tracker detection is reasoning-based, not rote.** Agents are smart enough to read the obvious documentation. An enumerated checklist of files in SKILL.md is pure rationale-discipline tax and caps the agent at the sources we happened to list.
+- **Harness task tracking is the last-resort fallback, not internal todos.** Aligns with the deprecation direction for the internal todo system. Honest about the fact that in-session tasks don't survive past the session.
+- **Override in the walk-through = pick a different preset action.** No freeform custom fixes. Keeps the interaction a decision loop and avoids turning it into a pair-programming transcript. Users who want custom fixes Skip and hand-edit.
+- **Internal-todos deprecation ships a durability regression for some users.** A subset of users today treat `.context/compound-engineering/todos/` as persistent defer storage; removing it from the fallback chain means those users lose cross-session durability for Defer actions until they either document a tracker in `CLAUDE.md` / `AGENTS.md` or the broader phase-out lands. The trade is acknowledged and deliberate, not a silent regression; the mitigation is the separate phase-out cleanup referenced in Scope Boundaries.
+
+## Dependencies / Assumptions
+
+- The cross-platform blocking question tool (`AskUserQuestion` / `request_user_input` / `ask_user`) caps at 4 options. All menu designs respect this.
+- Option labels across every menu in the flow (routing question, per-finding question, Stop-asking follow-up) must be self-contained, use third-person voice for the agent, and front-load a distinguishing word so they survive truncation in harnesses that hide description text.
+- The walk-through writes per-finding decisions to the run artifact (e.g., `.context/compound-engineering/ce-review/<run-id>/walkthrough-state.json`) after each decision, so partial progress is inspectable post-hoc. Formal cross-session resumption is out of scope.
+- Findings already carry enough detail (title, severity, confidence, file, line, autofix_class, suggested_fix, why_it_matters, evidence) to support the framing requirements. If some reviewers don't reliably produce plain-English `why_it_matters`, the framing quality bar may require prompt upgrades to those personas — flagged below as a question for planning.
+- The existing per-run artifact directory (`.context/compound-engineering/ce-review/<run-id>/`) and the fixer subagent flow remain the underlying mechanics for applying fixes.
+- The merged finding set produced by the existing Stage 5 merge pipeline carries only merge-tier fields; detail-tier fields (`why_it_matters`, `evidence`) live in the per-agent artifact files on disk. The per-finding walk-through enriches each merged finding by reading the contributing reviewer's artifact file at `.context/compound-engineering/ce-review/<run-id>/{reviewer}.json`, using the same `file + line_bucket(line, +/-3) + normalize(title)` matching that headless mode already uses. When no artifact match exists (merge-synthesized finding, or failed artifact write), the walk-through degrades to title plus `suggested_fix` and notes the gap.
+- The four-option routing design is built to the cross-platform question tool's 4-option cap. A future fifth primary routing intent would require replacing an existing option, chaining a follow-up question, or pressuring the platform cap — the design does not provide pressure relief for this case.
+- Autofix mode continues to write residual actionable work to `.context/compound-engineering/todos/` in this redesign, while Interactive-LFG and Defer actions route to external trackers per R16-R21. This temporary divergence is acknowledged — aligning autofix mode's residual sink with the new tracker routing is separate cleanup work tracked in the follow-up referenced in Scope Boundaries.
+
+## Outstanding Questions
+
+### Resolve Before Planning
+
+None. All product decisions are made.
+
+### Deferred to Planning
+
+- [Affects Problem Frame][Needs research] Sample recent `.context/compound-engineering/ce-review/<run-id>/` run artifacts to confirm the rubber-stamping / wholesale-deferral failure mode the Problem Frame asserts. If the dominant failure is something else (users disengage before the bucket question, report itself is unreadable), the four-option routing may not be the right intervention.
+- [Affects R22-R26][Technical] Do reviewer personas reliably produce plain-English `why_it_matters` today, or does the framing bar require prompt upgrades and/or a synthesis-time rewrite pass? Planning should inspect a sample of recent review artifacts to decide before committing to R22-R25 as achievable without persona changes.
+- [Affects R18][Technical] The concrete sequencing of the fallback chain on each target platform (e.g., GitHub Issues via `gh` vs harness task tracking, how to detect `gh` availability cheaply) is intentionally left out of the requirements so detection stays principle-based. Planning resolves the specific sequencing and detection heuristics per target environment.
+- [Affects R18][Technical] If no documented tracker is found and `gh` is unavailable on the current platform, should the fallback to harness task tracking happen silently or should the agent confirm once per session? Default expectation: confirm once so users are not surprised by in-session-only behavior.
+- [Affects R6][Technical] Whether the walk-through presents findings strictly in severity order (current default) or groups them by file first and then severity within each file. File-grouping may feel more coherent when many findings touch the same file, but it interacts with `Stop asking` semantics (a file-grouped bulk-accept applies to different findings than a severity-first bulk-accept).
+- [Affects R7][Needs validation] Whether surfacing reviewer persona names in each per-finding question (e.g., `julik-frontend-races-reviewer`) helps user judgment or is noise. If validation shows noise, omit reviewer attribution from R7's required content or replace with a short category label.
+
+## Next Steps
+
+`-> /ce:plan` for structured implementation planning

docs/brainstorms/2026-04-18-ce-doc-review-autofix-and-interaction-requirements.md

@@ -0,0 +1,157 @@
+---
+date: 2026-04-18
+topic: ce-doc-review-autofix-and-interaction
+---
+
+# ce-doc-review Autofix and Interaction Overhaul
+
+## Problem Frame
+
+`ce-doc-review` consistently produces painful reviews. It surfaces too many findings as "requires judgment" when one reasonable fix exists, nitpicks on low-confidence items, and hands the user a wall of prose with only two terminal options — "refine and re-review" or "review complete." The interaction model lags behind what `ce-code-review` now offers (per PR #590): per-finding walk-through, LFG, bulk preview, tracker defer, and a recommendation-stable routing question.
+
+A real-world review of a plan document produced **14 findings all routed to "needs judgment"** — including five P3 findings at 0.55–0.68 confidence, three concrete mechanical fixes that a competent implementer would arrive at independently, and one subjective filename-symmetry observation that didn't need a decision at all. The user had to parse 14 prose blocks, pick answers, and then was forced into a re-review regardless of how little the edits actually changed.
+
+The gaps are structural and line up with four observable failure modes:
+
+1. **Classification is binary and coarse.** `autofix_class` is `auto` or `present`. There is no `gated_auto` tier (concrete fix, minor sign-off) and no `advisory` tier (report-only FYI). Everything that isn't "one clear correct fix with zero judgment" becomes `present`, which conflates high-stakes strategic decisions with small mechanical follow-ups.
+2. **Confidence gate is flat and too low.** A single 0.50 threshold across all severities lets borderline P3s through. `ce-code-review` moved to 0.60 with P0-only survival at 0.50+.
+3. **"Reasonable alternative" test is permissive.** Persona reviewers list `(a) / (b) / (c)` fix options where (b) and (c) are strawmen ("accept the regression," "document in release notes," "do nothing"). The classification rule reads those as multiple reasonable fixes and routes the finding to `present`, when in fact only (a) is a real option.
+4. **Subagent framing and interaction model are pre-PR-590.** No observable-behavior-first framing guidance, no walk-through, no bulk preview, no per-severity confidence calibration, no post-fix "apply and proceed" exit — every path that addresses findings forces a re-review, even when the user is done.
+
+## Requirements
+
+**Classification tiers**
+
+- R1. `autofix_class` expands from two values to four: `auto`, `gated_auto`, `advisory`, `present`. Values preserve the existing "is there one correct fix" axis but add (a) a tier for concrete fixes that touch document scope / meaning and should be user-confirmed (`gated_auto`), and (b) a tier for report-only observations with no decision to make (`advisory`).
+- R2. `auto` findings are applied silently, same as today. The promotion rules in the synthesis pipeline (current steps 3.6 and 3.7) are sharpened per R4 below and carry the new strictness forward.
+- R3. `gated_auto` findings carry a concrete `suggested_fix` and a user-confirmation requirement. They enter the per-finding walk-through (R13) with `Apply the proposed fix` marked `(recommended)`. They are the default tier for "concrete fix exists, but it changes what the document says in a way the author should sign off on" (e.g., adding a backward-compatibility read-fallback, requiring two units land in one commit, substituting a framework-native API for a hand-rolled one).
+- R4. `advisory` findings are report-only. They surface in a compact FYI block in the final output and do not enter the walk-through or any bulk action. Subjective observations ("filename asymmetry — could go either way"), drift notes without actionable fixes, and low-stakes calibration gaps live here.
+- R5. `present` findings remain for genuinely strategic / scope / prioritization decisions where multiple reasonable approaches exist and the right choice depends on context the reviewer doesn't have.
+
+**Classification rule sharpening**
+
+- R6. The subagent-template classification rule adds teeth: "a 'do nothing / accept the defect' option is not a real alternative — it's the failure state the finding describes." If the only listed alternatives to the primary fix are strawmen, the finding is `auto` (or `gated_auto` if confirmation is warranted), not `present`. This applies equally to "document in release notes," "accept drift," and other deferral framings that sidestep the actual problem.
+- R7. Auto-promotion patterns already scattered in prose (steps 3.6 and 3.7) are consolidated into an explicit promotion rule set, covering:
+  - Factually incorrect behavior where the correct behavior is derivable from context or the codebase
+  - Missing standard security / reliability controls with established implementations (HTTPS, fallback-with-deprecation-warning, input sanitization, checksum verification, private IP rejection, etc.)
+  - Codebase-pattern-resolved fixes that cite a concrete existing pattern
+  - Framework-native-API substitutions when a hand-rolled implementation duplicates first-class framework behavior (e.g., cobra's `Deprecated` field)
+  - Completeness additions mechanically implied by the document's own explicit decisions
+- R8. The subagent template includes a framing-guidance block (ported from the `ce-code-review` shared template): observable-behavior-first phrasing, why-the-fix-works grounding, 2-4 sentence budget, required-field reminder, positive/negative example pair. One file change, applied universally across all seven personas.
+
+**Per-severity confidence gates**
+
+- R9. The single 0.50 confidence gate is replaced with per-severity gates:
+  - P0: survive at 0.50+
+  - P1: survive at 0.60+
+  - P2: survive at 0.65+
+  - P3: survive at 0.75+
+- R10. The residual-concern promotion step (current step 3.4) is dropped. Cross-persona agreement instead boosts the confidence of findings that already survived the gate (by +0.10, capped at 1.0), mirroring `ce-code-review` stage 5 step 4. Residual concerns surface in Coverage only.
+- R11. `advisory` findings are exempt from the confidence gate — they are report-only and can't generate false-positive work even at lower confidence. This is the safety valve for observations the reviewer wants on record but doesn't want to escalate.
+
+**Interaction model (post-fix routing)**
+
+- R12. After `auto` fixes are applied and before any user interaction, Interactive mode presents a four-option routing question that mirrors `ce-code-review`'s post-PR-590 design:
+  - (A) `Review each finding one by one — accept the recommendation or choose another action`
+  - (B) `LFG. Apply the agent's best-judgment action per finding`
+  - (C) `Append findings to the doc's Open Questions section and proceed` (ce-doc-review analogue of ce-code-review's "file a tracker ticket" — for docs, "defer" means appending the findings to a `## Deferred / Open Questions` section within the document itself, not an external system)
+  - (D) `Report only — take no further action`
+  If zero `gated_auto` / `present` findings remain after the `auto` pass, the routing question is skipped and the flow falls directly into the terminal question (R19).
+- R13. Routing option A enters a per-finding walk-through, presented one finding at a time in severity order (P0 first). Each per-finding question carries: position indicator (`Finding N of M`), severity, confidence, a plain-English statement of the problem, the proposed edit, and a short reasoning grounded in the document's own content or the codebase. Options: `Apply the proposed fix` / `Defer — append to the doc's Open Questions section` / `Skip — don't apply, don't append` / `LFG the rest — apply the agent's best judgment to this and remaining findings`. Advisory-only findings substitute `Acknowledge — mark as reviewed` for Apply.
+- R14. Routing option B and walk-through `LFG the rest` execute the agent's per-finding recommended action across the selected scope (all pending findings for B, remaining-undecided for walk-through). The recommendation for each finding is determined deterministically by R16.
+- R15. Before any bulk action executes (routing B, routing C, walk-through `LFG the rest`), a compact plan preview renders findings grouped by intended action (`Applying (N):`, `Appending to Open Questions (N):`, `Skipping (N):`, `Acknowledging (N):`) with a one-line summary per finding. Exactly two responses: `Proceed` or `Cancel`. Cancel from walk-through `LFG the rest` returns the user to the current finding, not to the routing question.
+
+**Recommendation tie-breaking**
+
+- R16. When merged findings carry conflicting recommendations across contributing personas (one says Apply, another says Defer), synthesis picks the most conservative using `Skip > Defer > Apply > Acknowledge`, so walk-through recommendations and LFG behavior are deterministic across re-runs.
+
+**Terminal "next step" question (the re-review fix)**
+
+- R17. The current Phase 5 binary question (`Refine — re-review` / `Review complete`) conflates "apply fixes" with "re-review" into a single option. This is replaced by a three-option terminal question that separates the two axes:
+  - (A) `Apply decisions and proceed to <next stage>` — for requirements docs, hand off to `ce-plan`; for plan docs, hand off to `ce-work`. Default / recommended when fixes were applied or decisions were made.
+  - (B) `Apply decisions and re-review` — opt-in re-review when the user believes the edits warrant another pass.
+  - (C) `Exit without further action` — user wants to stop for now.
+  When zero actionable findings remain (everything was `auto` or `advisory`), option B is omitted — re-review is not useful when there's nothing to re-examine.
+- R18. The terminal question is distinct from the mid-flow routing question (R12). The routing question chooses *how* to engage with findings; the terminal question chooses *what to do next* once engagement is complete. The two are asked separately, not merged.
+- R19. The zero-findings degenerate case (no `gated_auto` / `present` findings after the `auto` pass) skips the routing question entirely and proceeds directly to the terminal question with option B suppressed.
+
+**In-doc deferral (Defer analogue)**
+
+- R20. Document-review's `Defer` action appends the deferred finding to a `## Deferred / Open Questions` section at the end of the document under review. If the heading does not exist, it is created on first defer within a review. Multiple deferred findings from a single review accumulate under a single timestamped subsection (e.g., `### From 2026-04-18 review`) to keep sequential reviews distinguishable. This replaces `ce-code-review`'s tracker-ticket mechanic with a document-native analogue: deferred findings stay attached to the document they came from.
+- R21. The appended entry for each deferred finding includes: title, severity, reviewer attribution, confidence, and the `why_it_matters` framing — enough context that a reader returning to the doc later can understand the concern without re-running the review. The entry does not include `suggested_fix` or `evidence` — those live in the review run artifact and can be looked up if needed.
+- R22. When the append fails (document is read-only, path issue, write failure), the agent surfaces the failure inline and offers: retry, fall back to recording the deferral in the completion report only, or convert the finding to Skip. Silent failure is not acceptable.
+
+**Framing quality in reviewer output**
+
+- R23. Every user-facing surface that describes a finding — walk-through questions, LFG completion reports, Open Questions entries — explains the problem and fix in plain English. The framing leads with the *observable consequence* of the issue (what an implementer, reader, or downstream caller sees), not the document's structural phrasing.
+- R24. The framing explains *why the fix works*, not just what it changes. When a pattern exists elsewhere in the document or codebase, reference it so the recommendation is grounded.
+- R25. The framing is tight — approximately two to four sentences. Longer framings are a regression.
+
+**Cross-cutting**
+
+- R26. Tool-loading pre-flight mirrors `ce-code-review`: on Claude Code, `AskUserQuestion` is pre-loaded once at the start of Interactive mode via `ToolSearch` (`select:AskUserQuestion`), not lazily per-question. The numbered-list text fallback applies only when `ToolSearch` explicitly returns no match or the tool call errors.
+- R27. Headless mode behavior is preserved. `mode:headless` continues to apply `auto` fixes silently and return all other findings as structured text to the caller. The caller owns routing. New tiers (`gated_auto`, `advisory`) must appear distinctly in headless output so callers can route them appropriately.
+
+**Multi-round decision memory**
+
+- R28. Every review round after the first passes a cumulative decision primer to every persona, carrying forward all prior rounds' decisions in the current interactive session: rejected findings (Skipped / Deferred from any prior round) with title, evidence quote, and rejection reason; plus Applied findings from any prior round with title and section reference. Personas still receive the full current document as their primary input. No diff is passed — fixed findings self-suppress because their evidence no longer exists, regressions surface as normal findings on the current doc, and rejected findings are handled by the suppression rule in R29.
+- R29. Personas must not re-raise a finding whose title and evidence pattern-match a finding rejected in any prior round, unless the current document state makes the concern materially different. The orchestrator drops any finding that would violate this rule and records the drop in Coverage.
+- R30. For each prior-round Applied finding, synthesis confirms the fix landed by checking that the specific issue the finding described no longer appears in the referenced section. If a persona re-surfaces the same finding at the same location, synthesis flags it as "fix did not land" in the final report rather than treating it as a new finding.
+
+**Institutional memory (learnings-researcher integration)**
+
+- R31. `ce-doc-review` dispatches `research:ce-learnings-researcher` as an always-on agent, in parallel with coherence-reviewer and feasibility-reviewer. The agent owns its own fast-exit behavior when `docs/solutions/` is empty or absent — no activation-gating in the orchestrator.
+- R32. The orchestrator produces a compressed search seed during Phase 1's classify-and-select step: document type, 3-5 topic keywords extracted from the doc, named entities (tools, frameworks, patterns explicitly named), and the doc's top-level decision points. Learnings-researcher receives the search seed plus the document path, not the full document content. It searches `docs/solutions/` by frontmatter metadata first, then selectively reads matching solution bodies.
+- R33. Learnings-researcher returns, per match: the solution doc's path, a one-line relevance reason, and the specific claim in the doc under review that the past solution relates to. Full solution content is loaded on demand by other personas or the orchestrator if the match is promoted into a finding. Results are capped at a small N (default 5) most relevant matches — past-solution volume is not the goal; directly applicable grounding is.
+- R34. Learnings-researcher output surfaces in a dedicated "Past Solutions" section of the review output. Entries default to `advisory` tier (report-only grounding) unless a past solution directly contradicts a specific claim in the document under review, in which case they promote to `gated_auto` or `present` with the past solution's path as evidence.
+- R35. Learnings-researcher content does not participate in confidence-gating (R9) or cross-persona dedup (existing step 3.3). Its role is to add institutional memory, not to compete with persona findings for user attention.
+
+**learnings-researcher agent rewrite (bundled)**
+
+- R36. Rewrite `research:ce-learnings-researcher` to treat the `docs/solutions/` corpus as domain-agnostic institutional knowledge. Code bugs are one genre among several, alongside skill-design patterns, workflow learnings, developer-experience discoveries, integration gotchas, and anything else captured by `ce-compound` and its refresh counterpart. The agent's primary function is "find applicable past learnings given a work context," not "find past bugs given a feature description."
+- R37. The agent accepts a structured `<work-context>` input from callers: a short description of what the caller is working on or considering, a list of key concepts / decisions / domains / components extracted from the caller's work, and an optional domain hint when one applies cleanly (e.g., `skill-design`, `workflow`, `code-implementation`). No mode flag is required — the context shape adapts to the calling skill without the agent branching on caller identity.
+- R38. The hardcoded category-to-directory table is replaced with a dynamic probe of `docs/solutions/` to discover available subdirectories at runtime. Category narrowing uses the discovered set. The agent no longer assumes which subdirectories exist in a given repo.
+- R39. Keyword extraction handles decision-and-approach-shape content alongside symptom-and-component-shape content. The extraction taxonomy expands from the current four dimensions (Module names, Technical terms, Problem indicators, Component types) to include Concepts, Decisions, Approaches, and Domains. No input shape is privileged over another; the caller's context determines which dimensions carry weight.
+- R40. Output framing drops code-bug-biased phrasing ("gotchas to avoid during implementation," "prevent repeated mistakes" framed narrowly around bugs) in favor of neutral institutional-memory framing ("applicable past learnings," "related decisions and their outcomes"). The pointer + one-line-relevance + key-insight summary format carries across all input genres.
+- R41. Read `docs/solutions/patterns/critical-patterns.md` only when it exists. When absent, the agent proceeds without it — this file is a per-repo convention, not a protocol requirement.
+- R42. The agent's Integration Points section documents invocation by `/ce-plan`, `/ce-code-review`, `ce-doc-review`, and any other skill benefiting from institutional memory. Remove the framing that implies planning-time is the agent's primary home.
+
+**Frontmatter enum expansion (bundled)**
+
+- R43. Expand the `ce-compound` frontmatter `problem_type` enum to add non-bug genre values: `architecture_pattern`, `design_pattern`, `tooling_decision`, `convention`. Document `best_practice` as the fallback for entries not covered by any narrower value, not the default. Migrate the 8 existing `best_practice` entries that fit a narrower value (3 architecture patterns, 3 design patterns, 1 tooling decision, 1 remaining as best_practice), and resolve the one `correctness-gap` schema violation (`workflow/todo-status-lifecycle.md`) into a valid enum value. Update `ce-compound` and `ce-compound-refresh` so they steer authors toward narrower values when the new categories apply.
+
+## Scope Boundaries
+
+- Not introducing a document-native tracker integration (e.g., Linear / Jira / GitHub Issues). Document-review's Defer analogue is an in-doc `## Deferred / Open Questions` section. If users later want tracker integration for doc findings, that's a follow-up proposal.
+- Not changing persona selection logic. The seven personas and the activation signals for conditional ones stay as-is. The persona markdown files themselves change only to absorb the subagent-template framing-guidance block.
+- Not changing headless mode's structural contract with callers (`ce-brainstorm`, `ce-plan`). Headless continues to apply `auto` fixes silently and return a structured text envelope. Callers must be updated to handle the new `gated_auto` and `advisory` tiers but the envelope shape stays.
+- Not adding a `requires_verification` field or an in-skill fixer subagent. Document edits happen inline during the walk-through; there is no batch-fixer analogue to `ce-code-review`'s Step 3 fixer because document fixes are trivially confined in scope (single-file markdown edits).
+- Not addressing iteration-limit guidance. The existing "after 2 refinement passes, recommend completion" heuristic stays.
+- Not persisting decision primers across interactive sessions. The cumulative decision list (R28) lives in-memory across rounds within a single invocation. A new invocation of `ce-doc-review` on the same doc starts fresh with no carried memory, even if prior-session decisions were Applied to the document. Mirrors `ce-code-review` walk-through state rules.
+- Not building a fully new frontmatter schema. R43 adds non-bug enum values but does not redesign the schema dimensions (no split into `learning_category` + `problem_type`, no new required fields). The existing authoring flow stays the same; only the set of valid `problem_type` values grows.
+
+## Design Decisions Worth Calling Out
+
+- **Three new tiers, not two.** A minimal refactor could add only `gated_auto` and keep `advisory` collapsed into `present`. But real-world evidence shows FYI-grade findings (subjective observations, low-stakes drift notes) drive significant noise, and folding them into `present` forces user decisions on things that don't warrant any decision. Adding `advisory` as a distinct tier is cheap (one enum value + one output block) and materially reduces decision fatigue.
+- **Strawman-aware classification rule in the subagent template, not in synthesis.** Moving the rule to synthesis means persona reviewers still emit inflated alternative lists and the orchestrator retroactively collapses them. Moving it to the subagent template changes what reviewers produce at the source, so the evidence and framing travel together correctly.
+- **Per-severity confidence gates, not a flat 0.60.** A flat 0.60 would still let 0.60–0.68 P3 nits through (three of them in the attached real-world example). Severity-aware gates recognize that a P3 finding at 0.65 is noise in a way a P1 at 0.65 is not, because P3 impact is low enough that the expected value of a borderline call doesn't justify the user's attention.
+- **Separate terminal question from routing question.** The current skill conflates "engage with findings" and "exit the review" into one question with two poorly-aligned options. Splitting them gives the user explicit control over whether re-review happens — the most common user frustration surfaced in the bug report that prompted this work.
+- **In-doc Open Questions section, not a sibling follow-up note or external tracker, as Defer analogue.** Documents don't have the same "handoff to a different system" shape that code findings do. A sibling markdown note would fragment context; an external tracker would add platform complexity with no upside for document review. Appending deferred findings to a `## Deferred / Open Questions` section inside the document itself keeps deferred concerns attached to the artifact they came from, is naturally discoverable by anyone reading the doc, and requires no new infrastructure. The trade-off is that deferred findings visibly mutate the doc — but that is the point: "I want to remember this but not act now" is exactly what an Open Questions section expresses in a planning doc.
+- **Port framing-guidance once via the shared subagent template.** Matches how `ce-code-review` shipped the same fix in PR #590. One file change, applied universally. Per-persona edits would inflate scope to seven files; a synthesis-time rewrite pass would add per-review model cost and paper over the root cause in the persona output itself.
+- **Classification-rule sharpening and promotion-pattern consolidation ship together with the tier expansion.** Shipping the tiers without the sharpened rule would leave the classifier behavior unchanged and just add new tier labels nothing routes to. Shipping the rule without the tiers has no tier to promote findings into.
+- **Keep the existing persona markdown files mostly unchanged.** The framing-guidance block lives in the shared subagent template that wraps every persona dispatch; the personas themselves retain their confidence calibration, suppress conditions, and domain focus. This keeps the persona-level failure-mode catalogs stable while upgrading the shared framing bar.
+- **No diff passed to the multi-round decision primer.** Fixed findings self-suppress because their evidence is gone from the current doc; regressions surface as normal findings; rejected findings are handled by the suppression rule (R29). A diff would be signal amplification, not a correctness requirement, and would add prompt weight without changing what the agent can do.
+- **learnings-researcher rewrite bundled, not split.** The review-time use case has no consumer without ce-doc-review, so splitting into a precursor PR would ship a dormant feature. Bundling keeps the change coherent and easier to review as one unit. The agent rewrite (R36–R42) and the frontmatter enum expansion (R43) also benefit `/ce-plan`'s existing usage, so the scope investment pays off beyond ce-doc-review.
+- **Generalize learnings-researcher rather than patch with a mode flag.** The original proposal was a minimal `review-time` mode flag grafted onto the agent. But the real issue is that the agent's taxonomy, categories, and output framing are code-bug-shaped even when invoked by non-review callers — the plugin already captures non-code learnings via `ce-compound` / `ce-compound-refresh`, and the agent should treat them as first-class. Rewriting for domain-agnostic institutional knowledge is a bigger change but removes the drift, rather than accumulating special cases.
+- **Expand `problem_type` rather than introduce a new orthogonal dimension.** A cleaner design might split current `problem_type` into separate `learning_category` (genre) and `problem_type` (bug-shape detail) fields. But that requires migrating every existing entry and teaching authors to pick both. Expanding the existing enum with non-bug values absorbs the `best_practice` overflow with minimal schema churn and keeps the authoring flow stable.
+
+## Calibration Against Real-World Example
+
+The attached review output (14 findings, all `present`) re-classifies under the proposed rules as:
+
+- **4 `auto`** (silently applied, no user interaction): missing fallback-with-deprecation-warning (industry-standard pattern), public-repo grep step (single action), deployment-coupling-commit guarantee (mechanical), cobra's native `Deprecated` field (framework-native substitution).
+- **1 `advisory`** (FYI line): filename asymmetry — genuinely ambiguous, no wrong answer.
+- **4 `present`** (walk-through): historical-docs rule, alias-compatibility breaking-change, escape-hatch scope decision, Unit merging decision.
+- **5 dropped** by per-severity gates: five P3-P2 findings at 0.55–0.68 confidence.
+
+Net: the user sees **4 decisions**, not 14. The walk-through's `LFG the rest` escape further bounds fatigue — after the user calibrates on the agent's recommendations, they can bail and accept the rest.

docs/brainstorms/2026-04-22-demo-reel-local-save-requirements.md

@@ -0,0 +1,53 @@
+---
+date: 2026-04-22
+topic: demo-reel-local-save
+---
+
+# Demo Reel: Local Evidence Save
+
+## Problem Frame
+
+When `ce-demo-reel` captures evidence (GIFs, screenshots, terminal recordings), the local artifacts are deleted after uploading to catbox.moe. Users who want to keep evidence locally — for offline access, committing to the repo, or archival — have no way to do so without manually copying files from the temp directory before cleanup runs.
+
+---
+
+## Requirements
+
+**Destination choice**
+- R1. After capture completes, ask the user whether to upload to catbox (existing behavior) or save locally.
+- R2. The question must present the captured artifact(s) and clearly describe both options.
+
+**Local save behavior**
+- R3. When the user chooses local save, copy the final artifact(s) (GIF, PNG, or recording) to a stable OS-temp path (`$TMPDIR/compound-engineering/ce-demo-reel/`). Do not upload to catbox.
+- R4. Create the destination directory if it does not exist.
+- R5. Use a descriptive filename that includes the branch name or PR identifier and a timestamp to avoid collisions across runs.
+- R6. After saving, display the local file path(s) to the user for easy reference.
+
+---
+
+## Success Criteria
+
+- A user running `ce-demo-reel` can keep captured evidence on disk without manual intervention.
+- The saved artifacts are discoverable in a predictable, stable OS-temp location.
+
+---
+
+## Scope Boundaries
+
+- Catbox upload logic itself is unchanged — only the routing (local vs. upload) is new.
+- No automatic git-add or commit of saved artifacts.
+- No configurable save path — `$TMPDIR/compound-engineering/ce-demo-reel/` is the fixed default for now.
+- No retroactive save of previously captured evidence.
+
+---
+
+## Key Decisions
+
+- **Local save as an alternative to upload, not an addition**: The user chooses one destination per capture — either catbox or local. This keeps the flow simple and avoids redundant artifacts.
+- **OS-temp as the local target**: Uses `$TMPDIR/compound-engineering/ce-demo-reel/` per the repo's cross-invocation scratch-space convention. Stable prefix makes files findable without polluting the repo tree.
+
+---
+
+## Next Steps
+
+-> `/ce-plan` for structured implementation planning, or proceed directly to implementation given the small scope.

docs/brainstorms/2026-04-24-surface-scope-earlier-requirements.md

@@ -0,0 +1,149 @@
+---
+date: 2026-04-24
+topic: surface-scope-earlier
+---
+
+# Surface Scope Earlier in ce-brainstorm and ce-plan
+
+## Problem Frame
+
+Issue #676 (jrdncstr) reports that CE works well for greenfield/low-stakes work but becomes a burden in brownfield codebases: brainstorms and plans reach 300+ lines, artifacts are excessively defensive, rewrites persist, and PRs stay at 1000+ lines regardless of steering. He suggested a `--pragmatic` flag.
+
+The surface suggestion (a mode or flag) is the wrong fix. **Scope under-visibility is the upstream cause; artifact density and PR diff size are downstream symptoms.** Both ce-brainstorm and ce-plan synthesize user input + agent inference into an interpretation, but the user doesn't see that synthesis until the doc lands. The user agrees to many individual things in dialogue but never sees the whole; the agent makes substantial inferences (especially in ce-plan solo invocation, where Phase 0.4 bootstrap is brief by design) and then writes against an unverified scope. Surprise at write-time means rework, and the rework looks like artifact bloat downstream.
+
+**Working hypothesis:** fix the cause — surface the synthesis to the user before doc-write — and the symptoms abate. If they don't, density-control tools (calibrated exemplars, brevity passes for defensive sections) become a follow-up. Shipping them now alongside the cause fix would entangle attribution (which mechanism worked?), add maintenance surface for value that may not be needed, and chase symptoms before testing whether the cause fix dissolves them.
+
+The fix lives in templates and phase additions — no new mode, no flag, no user-facing classification question. Scope tiers stay as-is.
+
+Related: [GitHub Issue #676](https://github.com/EveryInc/compound-engineering-plugin/issues/676)
+
+---
+
+## Actors
+
+- A1. **ce-brainstorm agent**: generates requirements documents. Currently runs extensive pre-write dialogue but never surfaces a whole-scope synthesis before doc-write.
+- A2. **ce-plan agent**: generates implementation plans. Currently runs minimal interview in solo invocation (Phase 0.4 "keep it brief") and never surfaces synthesized scope before research or plan-write.
+- A3. **End-user developer**: pays the cognitive-debt cost when artifacts over-invest, the rework cost when scope was misinterpreted, and the review cost when PRs over-reach.
+
+---
+
+## Requirements
+
+### R1. ce-brainstorm synthesis summary
+
+Before Phase 3 (write requirements doc), ce-brainstorm surfaces a synthesis summary to the user. Fires for **all tiers** including Lightweight — the value is partly synthesis confirmation and partly a transition checkpoint ("about to write a doc") that gives the user permission to proceed or redirect.
+
+Structure:
+- **Stated** — what the user said directly (in prompt, prior conversation, dialogue answers, approach selection)
+- **Inferred** — what the agent assumed to fill gaps (scope boundaries the user never explicitly named, success criteria extrapolated from intent)
+- **Out of scope** — deliberately excluded items (adjacent work, refactors, nice-to-haves)
+
+Length: Lightweight gets one paragraph plus brief lists; Standard/Deep get a few paragraphs with explicit lists. Open prose prompt invites feedback: *"Does this match your intent? Tell me what to add, remove, redirect, or that I got wrong — or just confirm to proceed."*
+
+User can rebut even when the synthesis accurately reflects their stated answers (they may change their mind, surface new context, correct unstated assumptions). Soft-cut fires on **circularity** (same item revised twice), not iteration count — new-item revisions across rounds proceed without limit.
+
+Always embedded as the first section of the requirements doc. **Headless mode** (pipeline / `disable-model-invocation` context): skip the prompt and embed the synthesis with the **Inferred list omitted** — pipelines consume without human review, so propagating un-validated agent inferences as authoritative content is unsafe.
+
+### R2. ce-plan synthesis summary, invocation-context-aware
+
+Same Stated/Inferred/Out structure, prose, soft-cut, always-embed, and headless behavior as R1. Two timing variants:
+
+- **Solo invocation** (no upstream brainstorm doc): fires **after Phase 0.4 bootstrap, before Phase 1 research begins**. Catches scope misinterpretation before sub-agent dispatch is spent. Synthesis covers full breadth: problem frame, intended behavior, success criteria, in/out scope. The "Inferred" list is especially load-bearing here — Phase 0.4 makes substantial inferences from a brief interview.
+- **Brainstorm-sourced invocation**: fires **after Phase 1 research, before Phase 5.2 plan-write**. Brainstorm doc + R1 already validated WHAT. Synthesis focuses on plan-time decisions the brainstorm didn't make: which files/modules to touch (and not), which patterns extended vs. introduced new, test scope (which existing-but-untested code is in/out), and tangential refactor scope.
+
+State-machine guards (explicit in SKILL.md, not implicit):
+- Skip on Phase 0.1 fast paths (resume existing plan, deepen-intent) — synthesis is pre-write, doesn't apply when doc exists
+- Skip when Phase 0.4 routes out (ce-debug, ce-work, universal-planning) — agent left planning workflow
+- Solo variant skips when Phase 0.2 found a brainstorm doc (defers to brainstorm-sourced variant)
+
+Self-redirect support: if user surfaces "this is bigger than I thought, let me brainstorm first" or similar, agent stops, suggests the alternative skill, offers to load it in-session. No "do you want to brainstorm first?" question fires upfront — that would add friction in the common case.
+
+Graceful fallback: if origin brainstorm doc lacks the R1 synthesis section (older brainstorms, hand-written ones), R2 brainstorm-sourced runs as normal — its content is independent of origin synthesis presence.
+
+### R3. Anti-expansion clause in ce-plan
+
+Both tangential refactors and scope expansions go to a deferred-items list, not the active diff. Cleanup spotted in touched files → deferred. "While we're here, we could also..." → deferred. Adjacent improvements → deferred. Reinforces R2 by setting the default the synthesis surfaces.
+
+---
+
+## Acceptance Examples
+
+- AE1. **Covers R1.** Given a brainstorm task, ce-brainstorm surfaces a synthesis (Stated / Inferred / Out) before doc-write. The user can confirm, add, remove, redirect, or change their mind — even when the synthesis accurately reflects what they said in dialogue. The confirmed synthesis is embedded as the first section of the requirements doc. In headless mode, the synthesis embeds without the Inferred list and without prompting.
+- AE2. **Covers R2 (solo).** Given a /ce-plan invocation with no upstream brainstorm doc, after Phase 0.4 bootstrap and before Phase 1 research begins, the agent surfaces a full-breadth synthesis with explicit "Inferred" list. The user can correct ("actually I want the whole password reset feature, not just the link"), and research runs against the corrected scope.
+- AE3. **Covers R2 (brainstorm-sourced).** Given a /ce-plan invocation with a matching brainstorm doc, after Phase 1 research and before plan-write, the agent surfaces a plan-time-focused synthesis (which files will/won't be touched, which patterns extended, test scope, refactor scope). Brainstorm-validated WHAT is assumed and not re-stated.
+
+---
+
+## Success Criteria
+
+**Directly validated outcomes** (this iteration tests these):
+- ce-brainstorm and ce-plan both surface scope synthesis before doc-write. Users have a clear opportunity to correct inferences, redirect, or confirm.
+- Solo ce-plan invocations specifically catch scope errors before research is spent.
+- Headless mode embeds synthesis (without Inferred) so a human PR reviewer can see what scope was auto-interpreted.
+- Greenfield protection: in-repo validation on this plugin's own current work shows no regression.
+
+**Expected downstream effects** (consequences of upstream cause-fix; not directly enforced or validated):
+- PR diff size resolves toward what the confirmed scope actually requires.
+- Rewrite frequency decreases because tangential refactors land in deferred items (R3) rather than the active diff.
+- Token spend on misdirected research decreases because solo ce-plan invocations catch scope errors before sub-agent dispatch.
+- Artifact density (defensive Outstanding Questions, placeholder template-tail sections) becomes proportional to confirmed-scope size — speculative, but a sufficient post-rollout signal to determine whether density-control tools (deferred — see Scope Boundaries) need to ship later.
+
+If these downstream effects do not materialize after Phase A ships, the diagnosis was wrong — that's a real signal, not a partial win. Treat post-rollout PR-size telemetry on jrdncstr's repo (or a comparable case) as the actual validation of the causal claim.
+
+---
+
+## Scope Boundaries
+
+- Not adding a new mode, flag, command, or user-facing classification question
+- Not changing existing Lightweight/Standard/Deep tier classification
+- Not adding diff-size budgets or PR-size gates (Goodhart concerns)
+- Not modifying ce-work or its handoff
+- Not duplicating ce-brainstorm dialogue inside ce-plan's solo synthesis (R2 solo is a synthesis checkpoint, not a brainstorm-style interview)
+- Not touching auto-deepening (Phase 5.3) — preserved as load-bearing depth
+- Not introducing automated validation for headless-mode embedded synthesis (human PR reviewer is the safety net; documented limitation)
+- Not extending ce-doc-review to validate synthesis sections
+
+**Depth-calibration mechanisms deferred to follow-up:** an earlier draft of this brainstorm proposed calibrated tier exemplars, targeted brevity passes for defensive sections in ce-brainstorm, and brevity passes for plan template-tail sections. These are density-control tools — they target *output density* directly. Under the working hypothesis that scope under-visibility is the upstream cause, density should follow naturally from disciplined scope; shipping density-control tools alongside the cause fix would entangle attribution, add maintenance surface, and chase symptoms before testing whether the cause fix dissolves them. **Revisit only if post-rollout signals show density problems persist after this iteration ships.**
+
+---
+
+## Key Decisions
+
+- **Working hypothesis: scope under-visibility is the upstream cause; density is downstream.** Post-rollout signals are the actual validation. If real-user feedback surfaces density problems persisting despite synthesis discipline, density-control tools become a follow-up.
+- **Two distinct synthesis-summary mechanisms (R1, R2), not one shared one.** ce-brainstorm has substantial pre-write dialogue; its summary is shorter and serves as synthesis confirmation + transition checkpoint. ce-plan has minimal pre-write interview in solo mode; its summary fires earlier (pre-research) and is more elaborate. Same Stated/Inferred/Out structure, different timing and shape per skill.
+- **No "do you want to brainstorm first?" fork in ce-plan.** Explicit forks add friction to the common case. The synthesis lets users self-redirect when they recognize they need brainstorming.
+- **Solo ce-plan synthesis fires pre-research, not pre-write.** Pre-research catches scope errors when correction is cheap (no sub-agent dispatch spent).
+- **Brainstorm-sourced ce-plan synthesis fires pre-write, not pre-research.** Brainstorm validates WHAT; plan-time decisions emerge during research, so pre-write catches them.
+- **Stated/Inferred/Out is the load-bearing structure.** Neutral about input richness (works for one-line prompts and rich prior conversation alike); forces honesty about how much was assumed vs. agreed.
+- **Open prose, not AskUserQuestion.** Cite Interaction Rule 5(a) inline in SKILL.md to prevent future "fix" back to a menu — option sets would leak the agent's framing of valid corrections.
+- **Headless mode omits the "Inferred" list.** Pipelines consume without human review; propagating un-validated inferences as authoritative is unsafe.
+- **Soft-cut fires on circularity, not iteration count.** Revising different aspects of a wrong synthesis is exactly what the mechanism should support.
+- **Always embed synthesis as first section of doc.** Self-describing artifact for human PR reviewers; no auto-validation in headless (accepted limitation).
+- **Phased delivery: Phase A (ce-brainstorm) before Phase B (ce-plan).** Validates the simpler synthesis mechanism in the smaller surface first.
+- **Rejected: diff budgets** (Goodhart failure mode).
+- **Deferred: depth-calibration mechanisms** (calibrated exemplars + brevity passes). Revisit only if post-rollout signals show density problems persist.
+
+---
+
+## Dependencies / Assumptions
+
+- Assumes ce-brainstorm Phase 2→3 boundary and ce-plan Phase 0.6→1.1 boundary and pre-Phase-5.2 boundary can accommodate new synthesis-summary phases without restructuring. Needs codebase verification during planning.
+- Assumes skill-isolation rules continue to forbid cross-skill references. Synthesis-summary template content will be duplicated between ce-brainstorm and ce-plan reference directories.
+- Assumes users will engage with the synthesis summary rather than skip past it. If users routinely confirm without reading, the mechanism degrades to invisible scope drift. Worth structuring the prompt to invite scanning ("look at the Inferred list — did I assume anything wrong?").
+- ce-plan Phase 0.3 (origin-doc carry-forward) must handle a brainstorm doc whose first section is the new synthesis. Verify pre-Phase-A; if incompatible, the relevant fix lands in Phase A alongside R1.
+
+---
+
+## Outstanding Questions
+
+### Deferred to Planning
+
+- [Affects R1, R2][Technical] Exact wording of the synthesis-summary prompt template. Per learning #9 (`pass-paths-not-content-to-subagents.md`), phrasing matters more than meta-rules. Author during implementation; iterate if early manual validation shows drift.
+- [Affects R1, R2][Technical] Whether `synthesis-summary.md` content lives as one file per skill (with both solo and brainstorm-sourced variants in the ce-plan version) or split. Default: one file per skill, two clearly-labeled sections in ce-plan's version.
+- [Affects R2][Technical] Whether the solo-mode prompt uses a blocking question tool or chat-output-with-natural-interrupt. Tradeoff: blocking is more reliable but adds friction; natural interrupt is lower friction but easier to skip past. Decide during planning.
+
+---
+
+## Next Steps
+
+-> `/ce-plan` for implementation planning.

docs/brainstorms/2026-05-19-vscode-copilot-agent-tool-access-requirements.md

@@ -0,0 +1,277 @@
+---
+date: 2026-05-19
+topic: vscode-copilot-agent-tool-access
+---
+
+# VS Code Copilot Agent Tool Access for CE Plugin
+
+## Problem Frame
+
+When the Compound Engineering plugin is installed in VS Code via "Chat: Install Plugin from Source", CE subagents (reviewers, researchers, etc.) cannot read workspace files. Invoking `ce-correctness-reviewer` produces:
+
+```
+ACCESS_FAILED No filesystem read tool is available in this session to read README.md
+```
+
+Meanwhile, built-in subagents like `Explore` succeed in the same session, proving the VS Code Copilot host does provide workspace access to subagents — but only when tools are properly declared in the agent's frontmatter.
+
+The root cause is a gap in the converter pipeline:
+
+1. Claude agent `.agent.md` files declare tools (`tools: Read, Grep, Glob, Bash`), but the parser never captures them.
+2. The Copilot converter intentionally drops tools, emitting agents without a `tools` field.
+3. VS Code Copilot interprets a missing `tools` field as "no tools granted" for custom plugin agents (contrary to the converter's original assumption that omitting means defaults).
+
+This renders all CE subagents inert under Copilot — they can reason but cannot inspect code.
+
+---
+
+## Actors
+
+- A1. **Developer using CE in VS Code Copilot**: Invokes CE skills and agents expecting them to read/search/execute against the workspace.
+- A2. **CE converter pipeline**: Parses Claude plugin source, converts agents/skills to Copilot-compatible format, and writes output files.
+- A3. **VS Code Copilot host**: Loads plugin agent definitions, grants tools based on frontmatter declarations, and dispatches subagents.
+
+---
+
+## Key Flows
+
+- F1. **Subagent tool access (broken path)**
+  - **Trigger:** User invokes a CE skill that dispatches a reviewer/researcher subagent.
+  - **Actors:** A1, A3
+  - **Steps:**
+    1. User invokes `/compound-engineering:ce-code-review`
+    2. Skill dispatches `ce-correctness-reviewer` as subagent
+    3. VS Code Copilot loads the agent definition, finds no `tools` field
+    4. Subagent receives no filesystem tools
+    5. Subagent fails to read any files
+  - **Outcome:** Review fails with tool-access error.
+  - **Covered by:** R1, R2, R3
+
+- F2. **Subagent tool access (fixed path)**
+  - **Trigger:** Same as F1, after fix is applied.
+  - **Actors:** A1, A2, A3
+  - **Steps:**
+    1. Parser captures `tools` from Claude agent frontmatter
+    2. Converter maps Claude tools to Copilot aliases (`read`, `search`, `execute`, etc.)
+    3. Emitted `.agent.md` includes `tools: [read, search, execute]`
+    4. VS Code Copilot grants declared tools to subagent
+    5. Subagent reads workspace files successfully
+  - **Outcome:** CE reviewers and researchers operate with full workspace access.
+  - **Covered by:** R1, R2, R3, R4
+
+---
+
+## Requirements
+
+**Parser: Capture agent tools**
+
+- R1. The Claude parser (`src/parsers/claude.ts` `loadAgents`) must parse the `tools` field from agent frontmatter and populate it on the `ClaudeAgent` type.
+- R2. The `ClaudeAgent` type (`src/types/claude.ts`) must include an optional `tools?: string[]` field.
+
+**Converter: Map tools to Copilot aliases**
+
+- R3. The Copilot converter (`src/converters/claude-to-copilot.ts`) must map Claude tool names to VS Code Copilot tool aliases and emit a `tools` array in agent frontmatter. Mapping:
+  - `Read` → `read`
+  - `Grep`, `Glob` → `search`
+  - `Glob` → `search` (deduplicated with Grep)
+  - `Bash` → `execute`
+  - `Write`, `Edit`, `Patch`, `MultiEdit` → `edit`
+  - `WebFetch`, `WebSearch` → `web`
+  - `TodoRead`, `TodoWrite` → `todo`
+  - `Task` → `agent`
+  - MCP tool references (e.g., `mcp__context7__*`) → omitted (not mappable to Copilot built-in aliases)
+- R4. Output deduplication: the emitted `tools` array must contain unique values only (e.g., `Grep` + `Glob` both map to `search`, emit `search` once).
+- R5. If no tools are declared on the source agent, the converter must omit the `tools` field (preserving current behavior for agents that genuinely have no tool declarations).
+
+**Copilot type: Support tools field**
+
+- R6. The `CopilotAgent` type should support tools metadata so the converter's output is type-safe. This may be achieved by adding a field to the type or by ensuring the frontmatter serialization path handles it.
+
+**Tests**
+
+- R7. Update `tests/copilot-converter.test.ts` to assert that agents with declared tools produce correct Copilot `tools` arrays.
+- R8. Add test cases for: deduplication, unknown/unmappable tools (omitted gracefully), agents with no tools (field omitted), agents with web/MCP tools.
+- R9. Add or update parser tests to verify `tools` is captured from agent frontmatter.
+
+**No install target required for plugin-from-source**
+
+- R10. The fix must work when VS Code loads the plugin directly from the repo via "Chat: Install Plugin from Source" — meaning the plugin-native `.agent.md` files must carry the correct Copilot `tools` frontmatter, OR the conversion happens at install time. Determine which path applies (see Outstanding Questions).
+
+---
+
+## Acceptance Examples
+
+- AE1. **Covers R1, R2, R3, R4.** Given a CE agent file with `tools: Read, Grep, Glob, Bash`, when the plugin is parsed and converted to Copilot format, the output `.agent.md` frontmatter includes `tools: [read, search, execute]` (search appears once despite two source entries).
+
+- AE2. **Covers R3, R5.** Given a CE agent file with no `tools` field, when converted to Copilot format, the output `.agent.md` frontmatter does NOT include a `tools` key.
+
+- AE3. **Covers R3.** Given a CE agent with `tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, mcp__context7__*`, when converted, the output is `tools: [read, search, execute, web]` (MCP reference omitted, web deduplicated).
+
+- AE4. **Covers R1, R3, R7.** Given the `ce-correctness-reviewer` agent is installed in VS Code Copilot, when it is dispatched as a subagent, it can successfully read `README.md` from the workspace.
+
+---
+
+## Success Criteria
+
+- CE reviewer and researcher subagents can read, search, and execute in the workspace when invoked through VS Code Copilot.
+- The smoke test (invoke `ce-correctness-reviewer`, ask it to read `README.md`) returns file content instead of `ACCESS_FAILED`.
+- No regression: agents without declared tools continue to work as before (tools field omitted).
+- Existing non-Copilot targets (OpenCode, Codex, Pi, Gemini, Kiro) are unaffected.
+
+---
+
+## Scope Boundaries
+
+- **Not in scope: Changing VS Code Copilot host behavior.** We work within the host's documented tool-declaration mechanism.
+- **Not in scope: Changing `/compound-engineering:ce-*` namespacing.** This is VS Code Copilot host behavior for installed plugins. Document it but do not attempt to override.
+- **Not in scope: `.compound-engineering/config.local.yaml` as a tool-access fix.** That config controls CE preferences (Codex delegation, etc.), not Copilot tool grants.
+- **Not in scope: Adding a full `copilot` install target to `src/targets/index.ts`.** The immediate fix is making the converter emit tools. A dedicated install target may be added later.
+- **Not in scope: Changing how the plugin is distributed/installed.** The fix must work with the existing "Install Plugin from Source" workflow.
+- **Deferred: Copilot skill `tools` field.** Skills (SKILL.md) may also benefit from tool declarations, but the immediate failure is in subagents. Skill tool access can be addressed separately if needed.
+- **Deferred: Registering a `copilot` target in `src/targets/index.ts`.** This would enable `bun convert --to copilot` as a first-class workflow but is not required for the plugin-from-source fix.
+
+---
+
+## Key Decisions
+
+- **Map tools explicitly rather than emitting all tools unconditionally.** An explicit mapping ensures CE agents get precisely the capabilities they declare, matching the principle of least privilege. Emitting `tools: [read, search, execute, edit, web, todo, agent]` on every agent would work but grants unnecessary capabilities.
+- **Omit unmappable tools (MCP references) rather than erroring.** MCP tools are platform-specific and have no Copilot built-in equivalent. Silently dropping them with a warning is the safe default.
+- **Parse tools as a flat string array.** Claude agent frontmatter declares tools as a comma-separated line (`tools: Read, Grep, Glob, Bash`). Parse by splitting on commas and trimming whitespace.
+
+---
+
+## Dependencies / Assumptions
+
+- **VS Code honors `tools` in plugin agent files.** Confirmed: the docs explicitly state custom agents use the `tools` frontmatter field to declare available tools.
+- **"Install Plugin from Source" reads raw agent files.** Confirmed: VS Code clones the repo and loads files directly. No conversion step occurs. The fix must modify source files or the plugin format.
+- **VS Code Claude format detection uses file extension.** The docs state Claude agents are "plain `.md` files" in `.claude/agents`. The CE plugin uses `.agent.md` — this likely causes format mis-detection. Needs empirical verification.
+- **Tool set names are stable.** The `read`, `search`, `execute`, `edit`, `web`, `agent`, `todos`, `vscode`, `browser` tool sets are documented as of May 2026.
+- **Claude Code may or may not accept Copilot-native tool format.** If we change tools to `tools: [read, search, execute]`, Claude Code behavior needs testing. This is the key cross-platform compatibility question.
+
+---
+
+## Research Findings (2026-05-20)
+
+### Q1: How does "Install Plugin from Source" load agents?
+
+**Answer: VS Code reads raw agent files directly from the cloned repo. There is no conversion step.**
+
+Evidence from [VS Code Agent Plugins docs](https://code.visualstudio.com/docs/copilot/customization/agent-plugins):
+- "Run Chat: Install Plugin From Source from the Command Palette. Enter a Git repository URL and VS Code clones and installs the plugin."
+- Cached at: `%APPDATA%\Code\agentPlugins\github.com\{org}\{repo}` (Windows)
+- VS Code auto-detects plugin format by checking: `.plugin/plugin.json` → `plugin.json` (root) → `.github/plugin/plugin.json` → `.claude-plugin/plugin.json`
+- The CE plugin has `.claude-plugin/plugin.json`, so VS Code identifies it as **Claude format**
+
+**Critical implication:** Fixing only the converter is INSUFFICIENT. The raw plugin files must carry tool declarations that VS Code can interpret correctly.
+
+### Q2: Does VS Code map Claude tool names automatically?
+
+**Answer: YES — documented, but likely broken for this specific case.**
+
+From the [Custom Agents docs](https://code.visualstudio.com/docs/copilot/customization/custom-agents), Claude agent format section:
+> "VS Code maps Claude-specific tool names to the corresponding VS Code tools. Both the VS Code `.agent.md` format (with YAML arrays for tools) and the Claude format (with comma-separated strings) are supported."
+
+However, the same docs state:
+> "Agent files in the `.claude/agents` folder use **plain `.md` files**"
+
+The CE plugin agents use `.agent.md` extension (`ce-correctness-reviewer.agent.md`), NOT plain `.md`. VS Code's Claude format detection for agent files appears to depend on the file extension:
+- `.md` in `.claude/agents/` → Claude format (comma-separated tools string, auto-mapped)
+- `.agent.md` → Copilot format (YAML array of VS Code tool names)
+
+**Likely root cause:** The CE agent files have Copilot file extension (`.agent.md`) but Claude-style frontmatter (`tools: Read, Grep, Glob, Bash`). VS Code parses them as Copilot-format agents and looks for VS Code tool names like `Read`, `Grep` — which don't exist. Unrecognized tools are silently ignored, leaving the agent with **zero tools**.
+
+### Q3: Canonical VS Code tool set names
+
+From the [VS Code cheat sheet](https://code.visualstudio.com/docs/copilot/reference/copilot-vscode-features), built-in tool sets:
+
+| Tool Set | Individual Tools |
+|----------|-----------------|
+| `agent` | `agent/runSubagent` |
+| `browser` | (experimental, multiple) |
+| `edit` | `edit/createDirectory`, `edit/createFile`, `edit/editFiles`, `edit/editNotebook` |
+| `execute` | `execute/runInTerminal`, `execute/getTerminalOutput`, `execute/createAndRunTask`, `execute/runNotebookCell`, `execute/testFailure` |
+| `read` | `read/readFile`, `read/problems`, `read/getNotebookSummary`, `read/readNotebookCellOutput`, `read/terminalLastCommand`, `read/terminalSelection` |
+| `search` | `search/changes`, `search/codebase`, `search/fileSearch`, `search/listDirectory`, `search/textSearch`, `search/usages` |
+| `todos` | (todo list tool) |
+| `vscode` | `vscode/askQuestions`, `vscode/extensions`, `vscode/runCommand`, `vscode/VSCodeAPI` |
+| `web` | `web/fetch` |
+
+Custom agent `tools` field accepts: tool set names (e.g. `read`), individual tool names (e.g. `read/readFile`), MCP tool names, or `*` for all.
+
+### Q4: Does `tools: []` differ from omitting `tools`?
+
+**Answer: Not explicitly documented.** Based on the error behavior ("No filesystem read tool is available"), an agent with unrecognized tools behaves the same as one with no tools — it gets nothing. The distinction between explicit empty array and omission is academic for this fix since the real issue is the format mismatch.
+
+### Q5: Subagent tool inheritance
+
+From the docs, subagents:
+- Run as isolated instances with their own agent definition
+- The **parent** agent needs `agent` in its tools list and the subagent in its `agents` field
+- The **subagent** uses its own `tools` declaration
+- Built-in `Explore` succeeds because it's a built-in agent with proper tool access
+
+This confirms the issue is in how the subagent's own tools are parsed, not in inheritance.
+
+---
+
+## Revised Problem Analysis
+
+The root cause is a **format mismatch**, not a missing converter feature:
+
+1. CE agent files use `.agent.md` extension (Copilot format indicator)
+2. CE agent files contain Claude-style frontmatter: `tools: Read, Grep, Glob, Bash` (comma-separated string)
+3. VS Code sees `.agent.md` → applies Copilot-format parsing → looks for VS Code tool names
+4. `Read`, `Grep`, `Glob`, `Bash` are not valid VS Code tool names → silently dropped
+5. Agent ends up with zero tools → "No filesystem read tool is available"
+
+**The built-in `Explore` agent works because it's VS Code's own agent with proper Copilot-native tool declarations.**
+
+---
+
+## Outstanding Questions
+
+### Resolve Before Planning
+
+- **[Affects fix strategy][Needs testing]** Does renaming CE agents to plain `.md` (and keeping `tools: Read, Grep, Glob, Bash`) trigger VS Code's Claude-to-Copilot tool mapping? If yes, the fix is just a file extension rename. If no, we must also change the tool declarations to Copilot-native format.
+- **[Affects fix strategy][Needs testing]** If we keep `.agent.md` extension but change `tools` to Copilot-native format (`tools: [read, search, execute]`), does Claude Code still function correctly? Claude's docs say `tools` is a comma-separated string — does Claude also accept YAML arrays?
+
+### Deferred to Planning
+
+- **[Affects R6][Technical]** Should `CopilotAgent` type carry a `tools?: string[]` field, or is it sufficient for the converter to inject tools into the frontmatter string without type-level modeling?
+- **[Affects scope][Technical]** Should the parser change also benefit other converter targets (Codex, Gemini, etc.), or is tool mapping currently handled differently for those targets?
+- **[Affects upstream][Decision]** Should this be reported as a VS Code bug (Claude format mapping not applied to `.agent.md` files in Claude-format plugins)?
+
+---
+
+## Validation Plan
+
+After implementation, verify the fix end-to-end:
+
+1. **Build/convert the plugin** (if a build step is required).
+2. **Install in VS Code** via "Chat: Install Plugin from Source" pointing at the fork repo.
+3. **Confirm plugin loaded:** Check VS Code's extension/plugin list shows compound-engineering from the fork.
+4. **Smoke test — subagent file read:**
+   - Invoke `/compound-engineering:ce-correctness-reviewer` (or dispatch it from a skill)
+   - Ask it to read `README.md` and report the first heading
+   - Expected: returns content (e.g., `# fantastic-chainsaw` or whatever the repo's H1 is)
+   - Failure: `ACCESS_FAILED No filesystem read tool`
+5. **Comparative test — built-in agent:**
+   - Invoke built-in `Explore` with the same request
+   - Expected: succeeds (baseline proof the host provides tools)
+6. **Full flow test — code review:**
+   - Invoke `/compound-engineering:ce-code-review` on a small diff
+   - Verify reviewer subagents produce findings referencing actual file content
+7. **Regression — no-tools agent:**
+   - If any CE agent legitimately has no `tools` field, verify it still loads without error
+
+---
+
+## Next Steps
+
+Two quick empirical tests will determine the fix strategy:
+
+1. **Test A (file extension):** Rename one CE agent to `.md` (e.g., `ce-correctness-reviewer.md`), keep Claude-style `tools: Read, Grep, Glob, Bash`. Install plugin, invoke as subagent. If it works → fix is renaming all agent files.
+
+2. **Test B (tool format):** Keep `.agent.md` extension, change `tools` to `tools: [read, search, execute, edit]` (Copilot-native YAML array). Install plugin, invoke as subagent. If it works → fix is converting tool declarations to Copilot format.
+
+After one test succeeds → `/ce-plan` for full implementation across all 49 agent files, converter updates, and test changes.

docs/brainstorms/2026-06-04-ce-plan-approach-altitude-requirements.md

@@ -0,0 +1,177 @@
+---
+title: "ce-plan approach altitude — plan-for-a-plan as a first-class shape"
+date: 2026-06-04
+topic: ce-plan-approach-altitude
+---
+
+# ce-plan approach altitude — plan-for-a-plan as a first-class shape
+
+## Summary
+
+Give `ce-plan` a deliberate "approach altitude": when a problem is hard, answer it one level up first — produce a grounded *plan for how the deliverable will be made* — before committing to the deliverable itself. Entered explicitly ("plan for a plan") or, rarely, offered proactively. The approach-plan lands in chat (file-optional, deepenable); at a checkpoint the user runs it now or later. Execution of a non-code deliverable routes to a lightweight `ce-work` carve-out (or any agent, since the plan stays portable); code execution stays `ce-work`'s normal path. `ce-plan` never executes — it stays a planning/knowledge-structuring skill.
+
+---
+
+## Problem Frame
+
+Users have started asking `ce-plan` for an *intermediate* plan — a plan for how the agent will approach a hard problem — and then trying to execute it. The canonical case (the "Margolis" request):
+
+> "Make a plan for the plan. I'm about to hand you two things: a book as a PDF, and the two-hour transcript of the meeting I just had with the author. I want a thoughtful plan for how my business problem, that conversation, and the lessons in the book come together into something I can actually use. Do not write that document now. Writing it is the work. Right now I only want the plan for how you'll read the book, mine the transcript, and produce a great document."
+
+This is a way to get **certainty and structure on something hard** rather than zero-shotting a fragile final deliverable. It fails today, and tracing the exact prompt shows why:
+
+- `ce-plan`'s non-software path forces a binary — **plan-seeking** (save a plan) or **answer-seeking** (deliver an answer, discard the scaffold). The request is neither: it wants an *approach plan now*, then the *real deliverable later*, as a deliberate two-step. The classifier is as likely to start synthesizing the document, or to answer-seek toward it, as to hold at the approach. The user had to spend three sentences forcing the hold ("Do not write that document now…") — that fight is the symptom of a missing shape.
+- **The second phase is homeless.** Even with a perfect approach-plan, "now go do it" has nowhere to land — `ce-work` is code-only, and the non-software handoff offers no execution. The `ce-plan → ce-work` chain users invented breaks because `ce-work` can't do the right thing with that kind of plan, not because two skills is wrong.
+- **The approach-plan wouldn't be grounded.** A good plan for mining a *specific* transcript against a *specific* book requires looking at them. Today's research is repo/web-flavored, with no "ingest the user's heavy inputs to shape the approach" step — so the output is generic methodology, not a plan worth approving.
+
+The same pattern generalizes beyond knowledge work: *"before you write the implementation plan, plan how you'll investigate the codebase."* The executor (human or agent) is irrelevant — a portable plan reads the same either way. What's missing is the altitude, the hold, and a home for execution.
+
+---
+
+## Key Decisions
+
+- **The real boundary is code vs. knowledge-work, not plan vs. execute.** `ce-plan` already executes knowledge work — the answer-seeking disposition reads sources, analyzes, and delivers a produced result. Producing a synthesis document is that same act with a bigger output. So planning, answering, and synthesizing a deliverable are all `ce-plan`'s knowledge-work remit; only **code** needs `ce-work`'s lifecycle. Drawing the line at code keeps the sacred boundary (no code, no execution-time discovery) fully intact while letting non-code deliverables flow.
+
+- **General capability, high-precision / low-recall trigger.** The capability is domain-general, but the *proactive* offer fires rarely. Because the explicit path is always available as a safety net, the errors are asymmetric: a missed offer is cheap (the user just asks), a wrong offer is a nag. The named enemy is the new-hammer failure mode — every `ce-plan` turn opening with "want me to plan the approach first?" When borderline, stay silent.
+
+- **Execution stays out of `ce-plan`; `ce-work` gains a non-code carve-out.** Rather than make the planning skill execute (which feels wrong) or force a document-production plan through `ce-work`'s code lifecycle (which would mangle it), `ce-work` gets a minimal non-code branch. `ce-work` stays "the execution skill" regardless of domain; `ce-plan` stays planning.
+
+- **Light recon, two-stage grounding.** A cheap heuristic (request shape + input metadata) decides whether to *offer*; light recon (skim/sample, not deep-read) happens only after the user accepts. This makes the approach-plan specific enough to judge without paying the deliverable's cost up front.
+
+- **Separate but coordinated, not a refactor of existing mechanics.** Three in-chat "approach" surfaces already exist — answer-seeking's plan-of-attack, the Phase 0.7 scoping synthesis, and the deepening pass. Approach-altitude is built as its own surface with firing rules drawn so it never overlaps them, rather than unifying them into one concept or destabilizing skills that already work. The cost moves to boundary-drawing: the rules for when approach-altitude fires vs. when an existing mechanic fires must be crisp enough that it never reads as a confusable fourth thing.
+
+---
+
+## Flow
+
+```mermaid
+flowchart TB
+  Req[Request to ce-plan] --> Explicit{Explicit<br/>'plan the approach'?}
+  Explicit -->|yes| Recon[Light recon of inputs]
+  Explicit -->|no| Gate{Method-uncertainty AND<br/>cost-of-getting-it-wrong<br/>both high?}
+  Gate -->|no| Normal[Plan / do normally]
+  Gate -->|yes| Offer[Offer approach-plan:<br/>one dismissible line,<br/>names the signal that fired]
+  Offer -->|declined| Normal
+  Offer -->|accepted| Recon
+  Recon --> Approach[Approach-plan in chat<br/>file-optional, deepenable]
+  Approach --> Checkpoint{Do it now / save for later}
+  Checkpoint -->|later| Save[Save portable plan]
+  Checkpoint -->|now, code| CW[ce-work normal path]
+  Checkpoint -->|now, non-code| Carve[ce-work non-code carve-out<br/>or any agent]
+```
+
+---
+
+## Actors
+
+- A1. **User** — issues the request, accepts/declines a proactive offer, decides at the checkpoint.
+- A2. **`ce-plan`** — recognizes or offers the approach altitude, does light recon, produces the approach-plan, routes execution. Never writes code or executes a non-code deliverable itself.
+- A3. **`ce-work` (and its non-code carve-out)** — executes the deliverable. Any agent can substitute, since the plan is portable.
+
+---
+
+## Key Flows
+
+- F1. **Explicit approach-plan**
+  - **Trigger:** User asks for the approach ("plan for a plan", "plan how you'll do it", "don't do it yet").
+  - **Steps:** `ce-plan` does light recon of provided inputs → produces a grounded approach-plan in chat → checkpoint → routes execution per choice.
+  - **Covered by:** R1, R5, R7, R8.
+
+- F2. **Proactive offer**
+  - **Trigger:** Plain request with no approach language, where method-uncertainty AND cost-of-getting-it-wrong are both high.
+  - **Steps:** Cheap heuristic fires → `ce-plan` offers once, dismissibly, naming the signal → if accepted, continue as F1 from recon onward; if declined, plan/do normally.
+  - **Covered by:** R2, R3, R6.
+
+- F3. **Execution routing**
+  - **Trigger:** User chooses "do it now" at the checkpoint.
+  - **Steps:** Code deliverable → `ce-plan` produces the implementation plan and hands code to `ce-work`'s normal path. Non-code deliverable → routes to `ce-work`'s non-code carve-out (skip the code lifecycle) or to any agent given the portable plan.
+  - **Covered by:** R9, R10, R11, R12.
+
+---
+
+## Requirements
+
+**Recognition and triggering**
+
+- R1. `ce-plan` recognizes an explicit request for an approach-plan and always honors it, ungated by the proactive heuristic — it holds at the approach and does not start the deliverable.
+- R2. `ce-plan` proactively offers an approach-plan only when method-uncertainty AND cost-of-getting-it-wrong are both high; when either is low, it stays silent and plans/does normally.
+- R3. A proactive offer is a single lightweight, dismissible line that names the specific signal that fired (the "why it helps"); it is never a blocking ceremony.
+- R4. The capability is domain-general — available for software and knowledge-work requests alike, and indifferent to whether a human or the agent will execute.
+- R16. Approach-altitude is a distinct surface from the existing in-chat approach mechanics (answer-seeking's plan-of-attack, the scoping synthesis, the deepening pass); its firing rules are drawn so it never overlaps or duplicates them.
+
+**Approach-plan production**
+
+- R5. Before producing the approach-plan, the agent does light recon of provided inputs (skim/sample), grounding the approach in specifics; full ingestion is deferred to execution.
+- R6. The offer/no-offer decision is a cheap heuristic over request shape and input metadata; recon cost is paid only after the user accepts.
+- R7. The approach-plan is delivered chat-first and is file-optional; the user can choose to persist it and deepen it.
+
+**Checkpoint and execution routing**
+
+- R8. After the approach-plan, the user decides at a checkpoint: execute now, or save for later.
+- R9. Code execution stays on `ce-work`'s normal path; `ce-plan` never writes code.
+- R10. Non-code deliverable execution routes to `ce-work`'s non-code carve-out, or to any agent given the portable plan.
+- R11. `ce-plan` itself does not execute the deliverable; it produces the approach-plan and hands off.
+
+**`ce-work` non-code carve-out**
+
+- R12. `ce-work`'s input triage recognizes a non-code plan (no implementation units / files / test scenarios, or an explicit signal) and routes to a branch that skips the code lifecycle (no branch/worktree, no Test Discovery, no commit/PR/CI).
+- R13. The carve-out executes the production plan — read sources, synthesize, produce and save the deliverable, and report where it landed.
+- R14. The carve-out is a minority-case branch alongside the code path, not a co-equal mode, and must not disturb the code path.
+
+**Portability**
+
+- R15. The approach-plan / production-plan stays agent-agnostic — no `ce-work`-specific choreography baked in — so handing it to any agent to execute works without `ce-work`.
+
+---
+
+## Acceptance Examples
+
+- AE1. **Covers R1.** Given "plan for a plan" or "don't write it yet — plan the approach", `ce-plan` produces an approach-plan and does not begin the deliverable, regardless of the proactive heuristic.
+- AE2. **Covers R2, R3.** Given a plain request whose method is clear — even a large one — `ce-plan` does not offer an approach-plan; it proceeds to plan/do normally.
+- AE3. **Covers R2, R3, R6.** Given a plain request with heavy disparate inputs and a vague outcome ("something I can actually use"), `ce-plan` offers once, dismissibly, naming the signal; if declined, it proceeds normally without re-asking.
+- AE4. **Covers R9, R10.** Given approval to execute a *software* approach-plan, `ce-plan` produces the implementation plan and hands code to `ce-work`. Given a *knowledge-work* approach-plan, execution routes to the `ce-work` carve-out (or any agent).
+- AE5. **Covers R12, R13.** Given the `ce-work` carve-out receives a non-code plan, it skips branch/test/commit/CI and instead reads the sources, synthesizes, and writes the deliverable.
+
+---
+
+## Scope Boundaries
+
+**Deferred for later**
+
+- A full non-software `ce-work` mode. The carve-out is intentionally minimal; building a co-equal knowledge-work execution engine is out of scope.
+- Git/save behavior of the produced deliverable (commit vs. plain write, save location) — settle during planning.
+- Renaming `ce-plan` to reflect that it can produce non-plan output. The naming oddness is accepted for now; the answer-seeking disposition already lives with it.
+
+**Outside this capability's identity**
+
+- `ce-plan` writing or running code. Code is always `ce-work`. The approach altitude never crosses into code execution.
+- Auto-executing the deliverable without the checkpoint. The hold is the point of the feature.
+
+---
+
+## Dependencies / Assumptions
+
+- Builds on the existing answer-seeking disposition in `plugins/compound-engineering/skills/ce-plan/references/universal-planning.md` — the precedent that `ce-plan` can execute knowledge work and produce a result, not just a plan.
+- Light recon assumes provided inputs are available at approach-plan time. If inputs arrive later, recon degrades gracefully to propose-from-request (less grounded, flagged as such).
+- The approach-altitude decision must sit above `ce-plan`'s software/non-software split so the capability is domain-general rather than trapped in the universal (non-software) path.
+
+---
+
+## Outstanding Questions
+
+**Deferred to planning**
+
+- The crisp firing boundaries that keep approach-altitude from overlapping the three existing in-chat approach mechanics — the rules for when it fires vs. when answer-seeking's plan-of-attack, the scoping synthesis, or the deepening pass fires. The reconciliation decision is made (separate but coordinated); the boundary-drawing is a planning-time design task that needs grounded reading of how each existing mechanic actually triggers.
+- How `ce-plan` signals "non-code plan" to the `ce-work` carve-out: plan metadata, absence of implementation units, or an explicit flag.
+- The explicit-trigger phrase set, and how recognition stays robust without inflating the proactive offer's firing rate.
+- Exactly how light "light recon" is per input type (PDF, transcript, codebase), and how it is bounded so the checkpoint stays cheap.
+
+---
+
+## Sources / Research
+
+- `plugins/compound-engineering/skills/ce-plan/SKILL.md` — the planning/execution boundary ("does not implement code… belongs in `ce-work`"), Core Principle 6 (keep the plan portable), and the Phase 0.7 solo-mode scoping synthesis (an existing approach-checkpoint in spirit).
+- `plugins/compound-engineering/skills/ce-plan/references/universal-planning.md` — the plan-seeking vs. answer-seeking dispositions; the answer-seeking flow that already executes knowledge work and delivers a produced result.
+- `plugins/compound-engineering/skills/ce-work/SKILL.md` — code-only Phase 0 triage (files to change, test files), Phase 1 branch/worktree setup, task lists built from implementation units; confirms `ce-work` would mishandle a non-code plan today.
+- `plugins/compound-engineering/skills/ce-work/references/shipping-workflow.md` — the commit → PR → CI lifecycle the carve-out must skip.
+- Motivating example: the "Margolis" request (book PDF + two-hour transcript → synthesis document), used as the canonical knowledge-work case throughout.

docs/brainstorms/2026-06-19-agentless-plugin-surface-reduction-requirements.md

@@ -0,0 +1,198 @@
+---
+title: "Agentless plugin surface reduction"
+date: 2026-06-19
+topic: agentless-plugin-surface-reduction
+---
+
+# Agentless Plugin Surface Reduction
+
+## Summary
+
+Move Compound Engineering away from standalone plugin agents and toward skill-local subagent prompt assets. Public skills should represent user-facing jobs, not convenience wrappers around specialist agents. Surviving skills that need subagents will dispatch generic subagents using prompt definitions stored inside that skill's own directory, such as `references/agents/*.md` or `references/personas/*.md`.
+
+The goal is maximum deletion: remove redundant public skills, delete `plugins/compound-engineering/agents/`, and make the Codex plugin fully self-contained through native skills rather than a hybrid native-skill plus Bun-installed custom-agent setup.
+
+## Problem Frame
+
+Compound Engineering currently defines specialist behavior in two forms:
+
+- standalone agent files under `plugins/compound-engineering/agents/`
+- skill-local prompt/persona files under skill `references/` directories
+
+The standalone-agent model creates portability and install friction. Codex native plugins load the CE skills, but standalone agent registration has required a second Bun install path that converts Claude Markdown agents to Codex TOML agents. That split is brittle, profile-sensitive, and prevents the Codex plugin from behaving as a normal self-contained plugin.
+
+Other plugin ecosystems, including Superpowers, use a cleaner pattern: the skill owns the workflow and carries prompt templates for subagents in its own directory. That gives the skill custom subagent behavior without requiring a platform-level custom-agent registry.
+
+## Decisions
+
+- **Delete standalone CE agents.** Remove `plugins/compound-engineering/agents/` after moving still-needed behavior into surviving skills as local prompt assets.
+- **Delete redundant public skills.** Public skills must map to real user jobs. Skills that only make an agent easy to call should be removed.
+- **Prefer skill-local duplication over shared agent infrastructure.** Duplicating prompt text across a few skills is acceptable when it removes cross-platform agent registration and makes each skill self-contained.
+- **Do not preserve compatibility wrappers.** This migration intentionally uses maximum deletion. Removed skills and agents go into legacy cleanup registries; no deprecated skill stubs or one-release grace wrappers.
+- **Keep generic converter support where it serves non-CE plugins.** The CLI may still convert agents for other plugin payloads, but CE-specific Codex installation should no longer require generated custom agents.
+
+## Skill Decisions
+
+### Delete
+
+| Skill | Disposition |
+| --- | --- |
+| `ce-agent-native-audit` | Delete; fold useful checklist material into `ce-agent-native-architecture` or `ce-code-review` only if needed. |
+| `ce-clean-gone-branches` | Delete. |
+| `ce-dhh-rails-style` | Delete. |
+| `ce-frontend-design` | Delete; salvage durable frontend rules into `ce-work`, `ce-work-beta`, and `ce-polish` where relevant. |
+| `ce-gemini-imagegen` | Delete. |
+| `ce-release-notes` | Delete. |
+| `ce-report-bug` | Delete. |
+| `ce-sessions` | Delete as a public product surface; fold discovery/extraction scripts and historian synthesis into `ce-compound` only for compounding/documentation workflows. |
+| `ce-slack-research` | Delete; fold Slack research prompts into `ce-brainstorm`, `ce-ideate`, and `ce-plan`. |
+| `ce-update` | Delete. |
+
+### Keep
+
+| Skill | Notes |
+| --- | --- |
+| `ce-agent-native-architecture` | Keep as a domain guide for agent-native systems. |
+| `ce-brainstorm` | Keep; localize Slack research prompt. |
+| `ce-code-review` | Keep; localize code-review personas. |
+| `ce-commit` | Keep. |
+| `ce-commit-push-pr` | Keep. |
+| `ce-compound` | Keep; absorb session-history workflow. |
+| `ce-compound-refresh` | Keep. |
+| `ce-debug` | Keep. |
+| `ce-demo-reel` | Keep. |
+| `ce-doc-review` | Keep; localize document-review personas. |
+| `ce-dogfood-beta` | Keep. |
+| `ce-ideate` | Keep; localize research prompts. |
+| `ce-optimize` | Keep; localize research prompts. |
+| `ce-plan` | Keep; localize research and deepening prompts. |
+| `ce-polish` | Keep; absorb frontend-design rules where useful. |
+| `ce-product-pulse` | Keep. |
+| `ce-promote` | Keep. |
+| `ce-proof` | Keep. |
+| `ce-resolve-pr-feedback` | Keep; localize PR comment resolver prompt. |
+| `ce-riffrec-feedback-analysis` | Keep. |
+| `ce-setup` | Keep. |
+| `ce-simplify-code` | Keep. |
+| `ce-strategy` | Keep. |
+| `ce-test-browser` | Keep. |
+| `ce-test-xcode` | Keep. |
+| `ce-work` | Keep; localize Figma/design-sync prompt if still needed. |
+| `ce-work-beta` | Keep. |
+| `ce-worktree` | Keep. |
+| `lfg` | Keep. |
+
+## Agent Decisions
+
+### Preserve as Skill-Local Prompt Assets
+
+| Agent | Destination |
+| --- | --- |
+| `ce-adversarial-document-reviewer` | `ce-doc-review/references/personas/` |
+| `ce-coherence-reviewer` | `ce-doc-review/references/personas/` |
+| `ce-design-lens-reviewer` | `ce-doc-review/references/personas/` |
+| `ce-feasibility-reviewer` | `ce-doc-review/references/personas/` |
+| `ce-product-lens-reviewer` | `ce-doc-review/references/personas/` |
+| `ce-scope-guardian-reviewer` | `ce-doc-review/references/personas/` |
+| `ce-security-lens-reviewer` | `ce-doc-review/references/personas/` |
+| `ce-adversarial-reviewer` | `ce-code-review/references/personas/` |
+| `ce-agent-native-reviewer` | `ce-code-review/references/personas/` |
+| `ce-api-contract-reviewer` | `ce-code-review/references/personas/` |
+| `ce-correctness-reviewer` | `ce-code-review/references/personas/` |
+| `ce-julik-frontend-races-reviewer` | `ce-code-review/references/personas/` |
+| `ce-maintainability-reviewer` | `ce-code-review/references/personas/` |
+| `ce-performance-reviewer` | `ce-code-review/references/personas/` |
+| `ce-previous-comments-reviewer` | `ce-code-review/references/personas/` |
+| `ce-project-standards-reviewer` | `ce-code-review/references/personas/` |
+| `ce-reliability-reviewer` | `ce-code-review/references/personas/` |
+| `ce-security-reviewer` | `ce-code-review/references/personas/` |
+| `ce-swift-ios-reviewer` | `ce-code-review/references/personas/` |
+| `ce-testing-reviewer` | `ce-code-review/references/personas/` |
+| `ce-pr-comment-resolver` | `ce-resolve-pr-feedback/references/agents/` |
+| `ce-figma-design-sync` | `ce-work/references/agents/` and `ce-work-beta/references/agents/` |
+| `ce-session-historian` | `ce-compound/references/agents/`; move supporting scripts from `ce-sessions`. |
+| `ce-slack-researcher` | Workflow-tuned local copies in `ce-brainstorm`, `ce-ideate`, and `ce-plan`. |
+| `ce-learnings-researcher` | Local copies in `ce-code-review`, `ce-ideate`, `ce-optimize`, and `ce-plan`; slim per workflow if practical. |
+| `ce-repo-research-analyst` | Local copies in `ce-plan` and `ce-optimize`. |
+| `ce-web-researcher` | Local copies in `ce-plan` and `ce-ideate`. |
+| `ce-best-practices-researcher` | Local copies in `ce-plan` and `ce-compound`, or merge with framework-docs prompt where it improves clarity. |
+| `ce-framework-docs-researcher` | Local copies in `ce-plan` and `ce-compound`, or merge with best-practices prompt where it improves clarity. |
+| `ce-data-migration-reviewer` | Local copies in `ce-code-review` and `ce-plan`. |
+| `ce-deployment-verification-agent` | Local copies in `ce-code-review` and `ce-plan`. |
+| `ce-data-integrity-guardian` | Local copies in `ce-plan` and `ce-compound`, or merge into nearby data prompts if redundant. |
+| `ce-security-sentinel` | Local copies in `ce-plan` and `ce-compound`, or merge into nearby security prompts if redundant. |
+| `ce-performance-oracle` | Local copies in `ce-plan` and `ce-compound`, or merge into nearby performance prompts if redundant. |
+| `ce-pattern-recognition-specialist` | Local copies in `ce-plan` and `ce-compound`, or fold into repo research/maintainability prompts if redundant. |
+| `ce-spec-flow-analyzer` | `ce-plan/references/agents/` |
+| `ce-architecture-strategist` | `ce-plan/references/agents/` |
+| `ce-git-history-analyzer` | `ce-plan/references/agents/` |
+| `ce-issue-intelligence-analyst` | `ce-ideate/references/agents/` |
+
+### Delete
+
+| Agent | Reason |
+| --- | --- |
+| `ce-ankane-readme-writer` | No runtime consumer. |
+| `ce-design-implementation-reviewer` | No runtime consumer. |
+| `ce-design-iterator` | Only consumed by deleted `ce-frontend-design`; salvage useful frontend rules elsewhere if needed. |
+| `ce-code-simplicity-reviewer` | Delete as a standalone agent; preserve code simplification as an important capability owned by `ce-simplify-code`. |
+
+## Requirements
+
+- R1. No surviving CE skill may dispatch a standalone `ce-*` agent by name.
+- R2. Every surviving subagent dispatch must identify a skill-local prompt asset or inline local prompt block as the source of specialist behavior.
+- R3. No `plugins/compound-engineering/agents/` directory remains after migration.
+- R4. Deleted skills and agents are added to both legacy cleanup registries:
+  - `src/utils/legacy-cleanup.ts`
+  - `src/data/plugin-legacy-artifacts.ts`
+- R5. Plugin README and docs catalogs no longer advertise standalone agents.
+- R6. Codex docs no longer require `bunx @every-env/compound-plugin install compound-engineering --to codex` for CE custom agents once CE no longer ships standalone agents.
+- R7. CE-specific converter tests are updated so current CE output is skills-only for Codex. Generic non-CE agent conversion coverage may remain.
+- R8. `bun run release:validate` passes after manifest, README, and marketplace metadata are updated.
+- R9. Behavioral validation for modified skills uses the repo's skill-validation path rather than stale in-session plugin agent dispatch.
+- R10. Install documentation is overhauled everywhere it appears, including plugin READMEs, marketplace/catalog README content, and tracked Markdown docs, so users no longer see obsolete custom-agent install guidance.
+- R11. `bun test` passes after converter, writer, cleanup, and plugin inventory changes.
+- R12. The implementation run is tracked under a single `/goal` objective tied to this requirements doc so long-running work can resume without losing the source of truth.
+- R13. High-risk surviving skills produce skill-eval receipts after migration, comparing revised behavior against a pre-migration snapshot where possible.
+- R14. Static validation proves there are no surviving CE standalone-agent dependencies: no `plugins/compound-engineering/agents/` directory, no surviving skill dispatches a standalone `ce-*` agent by name, and deleted artifacts are present in both cleanup registries.
+
+## Validation Strategy
+
+Use `/goal` for continuity, not as the proof mechanism. The goal should reference this requirements doc and remain active until implementation, docs, cleanup registries, automated tests, release validation, and eval receipts are complete.
+
+Skill-level evals should use `skill-eval` with `old_skill` baselines for revised skills. Snapshot each target skill before edits when possible, then run the same prompts against the migrated skill and the snapshot. Store artifacts under `/tmp/skill-eval/<skill-name>/<run-id>/` with prompts, transcripts, outputs, grading, benchmark summaries, and review notes.
+
+Minimum eval coverage:
+
+| Skill | Eval purpose |
+| --- | --- |
+| `ce-code-review` | Prove localized reviewer personas still produce schema-valid, confidence-gated findings on a small diff. |
+| `ce-doc-review` | Prove localized document-review personas still classify requirements/plan documents, synthesize findings, and apply safe-auto fixes correctly. |
+| `ce-plan` | Prove localized research/deepening prompts still produce a structured plan from a requirements doc without standalone agent dispatch. |
+| `ce-compound` | Prove folded session-history support works only inside the compounding workflow and no standalone `ce-sessions` path is required. |
+| `ce-brainstorm` | Prove localized Slack research prompt can be invoked as workflow context without the deleted `ce-slack-research` skill. |
+| `ce-ideate` | Prove localized research prompts still ground ideas and preserve the expected artifact shape. |
+| `ce-optimize` | Prove localized repo/learnings research prompts still support optimization setup without standalone agents. |
+| `ce-resolve-pr-feedback` | Prove the localized PR comment resolver prompt still evaluates review feedback and emits actionable resolution guidance. |
+| `ce-work` / `ce-work-beta` | Prove any localized Figma/design-sync prompt remains accessible where the work skills need it; explicitly state the stable/beta sync decision. |
+| `ce-simplify-code` | Prove code simplification remains available even though `ce-code-simplicity-reviewer` is deleted as a standalone agent. |
+
+Automated validation should include:
+
+- `bun test`
+- `bun run release:validate`
+- targeted static scans for removed skill names, removed agent names, stale install instructions, and forbidden standalone `ce-*` agent dispatches
+- native Codex plugin smoke validation when the local Codex plugin install path is available; otherwise record the unavailable command/tooling as a validation gap
+
+## Open Implementation Notes
+
+- Prefer moving agent bodies mechanically first, then slimming/merging prompts only where the consuming skill's context clearly warrants it.
+- For shared prompts, duplication must happen inside each consuming skill directory. Do not create cross-skill shared files.
+- The implementation plan should sequence this migration by workflow cluster to keep reviewable diffs:
+  1. Delete no-consumer agents and wrapper skills.
+  2. Localize `ce-code-review` and `ce-doc-review` personas.
+  3. Localize planning/research prompts.
+  4. Fold sessions into `ce-compound`.
+  5. Localize remaining one-off prompts.
+  6. Remove CE standalone agent install assumptions from Codex docs, READMEs, Markdown guides, and tests.
+  7. Run static checks, automated tests, release validation, and skill-eval receipts for the high-risk surviving skills.

docs/grok-marketplace-submission.md

@@ -0,0 +1,62 @@
+# Submitting Compound Engineering to the official xAI plugin marketplace
+
+Maintainer runbook for listing Compound Engineering in the official [xAI plugin
+marketplace](https://github.com/xai-org/plugin-marketplace). This is a **periodic
+"promote a stable version" action**, not a per-release step — the direct-install
+and self-hosted-catalog paths (below) already track the repository automatically.
+
+## How the three Grok distribution paths differ
+
+| Path | Command | Version tracking | Ongoing cost |
+|---|---|---|---|
+| Direct install | `grok plugin install EveryInc/compound-engineering-plugin` | tracks repo HEAD; `grok plugin update` pulls latest | none |
+| Self-hosted catalog | `grok plugin marketplace add EveryInc/compound-engineering-plugin` | our `.grok-plugin/marketplace.json` uses a bare Git URL source (no SHA) → tracks HEAD | none |
+| Official xAI catalog | browse/install from `xAI Official` marketplace | a **SHA-pinned** remote source entry in xAI's repo | one PR per promoted version |
+
+Only the official catalog carries per-version cost: xAI requires remote sources
+to pin a full 40-character commit SHA (a moving ref would let a force-push ship
+new code silently), so updating the official listing means opening a PR that
+bumps the SHA. Point contributors who want the latest at direct install instead.
+
+## Submission steps (remote source — recommended for third-party)
+
+1. Fork [`xai-org/plugin-marketplace`](https://github.com/xai-org/plugin-marketplace) and branch from `main`.
+2. Add one entry to their `.grok-plugin/marketplace.json` `plugins` array:
+
+   ```json
+   {
+     "name": "compound-engineering",
+     "description": "Brainstorm, plan, debug, review, and compound learnings with AI agents",
+     "category": "development",
+     "source": {
+       "source": "url",
+       "url": "https://github.com/EveryInc/compound-engineering-plugin.git",
+       "sha": "<full-40-char-commit-sha>"
+     },
+     "homepage": "https://github.com/EveryInc/compound-engineering-plugin",
+     "keywords": ["compound-engineering", "compound engineering", "ce-plan", "ce-work"]
+   }
+   ```
+
+3. Pin the SHA to the commit you want to ship (a real commit, not a branch or tag):
+
+   ```bash
+   git ls-remote https://github.com/EveryInc/compound-engineering-plugin.git HEAD
+   ```
+
+4. Regenerate their component index and validate locally (this is what their CI runs):
+
+   ```bash
+   python3 scripts/generate-plugin-index.py
+   python3 scripts/validate-catalog.py
+   python3 scripts/generate-plugin-index.py --check
+   ```
+
+5. Open the PR against `xai-org/plugin-marketplace` and fill in their template. Code-owner review is required.
+
+## Notes
+
+- **Source from the official org.** The `source.url` must be `EveryInc/compound-engineering-plugin` (our org), not a personal fork — xAI flags personal-account sources for branded plugins as possible impersonation.
+- **To roll out an update**, bump the pinned `sha` in the same entry and regenerate the index — do not open a parallel duplicate entry.
+- **Keep `keywords` brand-scoped.** They power Grok's plugin CTA; generic terms (`ai`, `cli`, `workflow`) get pushed back because they mis-fire on unrelated requests.
+- A local source (vendoring our files under xAI's `external_plugins/compound-engineering/`) is also accepted, but requires re-vendoring on every update — the remote source above is lighter to maintain.

docs/ideation/2026-06-28-ce-pov-skill-proposal.html

@@ -0,0 +1,297 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Proposal: the ce-pov skill</title>
+<link rel="preconnect" href="https://fonts.bunny.net">
+<link rel="stylesheet" href="https://fonts.bunny.net/css?family=fraunces:400,500,600|inter:400,500,600,700&display=swap">
+<style>
+  :root{
+    --bg:#faf8f4; --surface:#ffffff; --ink:#1d1b18; --muted:#6b655c;
+    --line:#e6e0d6; --accent:#9a3b1f; --accent-soft:#f6e9e2; --accent-text:#7a2d16;
+    --info-soft:#e8eef2; --info-text:#2c4a5a; --warn-soft:#f6efdc; --warn-text:#7a5a17;
+    --good-soft:#e5efe4; --good-text:#3a5a32;
+    --serif:"Fraunces",Georgia,serif;
+    --sans:"Inter",-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;
+  }
+  @media (prefers-color-scheme:dark){
+    :root{
+      --bg:#17150f; --surface:#201d16; --ink:#ece7dd; --muted:#a39c8e;
+      --line:#332f25; --accent:#e0865f; --accent-soft:#34241c; --accent-text:#f0a883;
+      --info-soft:#1c2a32; --info-text:#9fc4d6; --warn-soft:#2e2715; --warn-text:#d8b86a;
+      --good-soft:#1d2a1b; --good-text:#a7c89c;
+    }
+  }
+  *{box-sizing:border-box}
+  body{margin:0; background:var(--bg); color:var(--ink); font-family:var(--sans); font-size:16px; line-height:1.6; -webkit-font-smoothing:antialiased}
+  .page{max-width:900px; margin-inline:auto; padding:3.5rem 1.5rem 5rem}
+  .eyebrow{font-size:.72rem; letter-spacing:.14em; text-transform:uppercase; color:var(--accent); font-weight:600; margin:0 0 .5rem}
+  h1{font-family:var(--serif); font-weight:600; font-size:2.5rem; line-height:1.1; margin:0 0 .75rem; letter-spacing:-.01em}
+  h2{font-family:var(--serif); font-weight:600; font-size:1.55rem; margin:2.8rem 0 1rem; padding-bottom:.4rem; border-bottom:2px solid var(--line); scroll-margin-top:1rem}
+  h3{font-family:var(--sans); font-weight:600; font-size:1.12rem; margin:1.4rem 0 .35rem}
+  p{max-width:74ch}
+  a{color:var(--accent-text)}
+  .meta{display:flex; flex-wrap:wrap; gap:.5rem; margin:1.25rem 0 0}
+  .pill{display:inline-block; font-size:.74rem; font-weight:600; padding:.25rem .6rem; border-radius:999px; border:1px solid var(--line); background:var(--surface); color:var(--muted)}
+  .lede{font-size:1.12rem; max-width:74ch}
+  .callout{background:var(--accent-soft); border:1px solid var(--line); border-radius:12px; padding:1.1rem 1.25rem; margin:1.5rem 0}
+  .callout .eyebrow{color:var(--accent-text)}
+  .callout p{margin:.3rem 0 0}
+  .card{background:var(--surface); border:1px solid var(--line); border-radius:12px; padding:1.2rem 1.35rem; margin:1rem 0}
+  .nav{background:var(--surface); border:1px solid var(--line); border-radius:10px; padding:.9rem 1.1rem; margin:1.5rem 0 0}
+  .nav ol{margin:.3rem 0 0; padding-left:1.3rem; columns:2; column-gap:2rem}
+  .nav li{margin:.2rem 0; break-inside:avoid}
+  .nav a{text-decoration:none}
+  .nav a:hover{text-decoration:underline}
+  ul.tight li, ol.tight li{margin:.35rem 0; max-width:72ch}
+  table{border-collapse:collapse; width:100%; margin:1rem 0; font-size:.92rem}
+  th,td{text-align:left; padding:.55rem .7rem; border-bottom:1px solid var(--line); vertical-align:top}
+  th{font-size:.74rem; letter-spacing:.06em; text-transform:uppercase; color:var(--muted)}
+  code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:.86em; background:var(--accent-soft); padding:.08em .35em; border-radius:5px}
+  .step{display:grid; grid-template-columns:max-content 1fr; gap:0 1rem; margin:.6rem 0}
+  .step .n{font-family:var(--serif); font-weight:600; color:var(--accent); font-size:1.25rem; line-height:1.2}
+  .step .b{margin:0}
+  .step .b b{font-family:var(--sans)}
+  .guard{border-left:3px solid var(--accent); background:var(--surface); border-radius:0 8px 8px 0; padding:.9rem 1.1rem; margin:1rem 0}
+  .guard.theater{border-left-color:var(--info-text)}
+  .guard.ritual{border-left-color:var(--warn-text)}
+  figure{margin:1.4rem 0 .3rem; text-align:center}
+  figure svg{max-width:100%; height:auto}
+  figcaption{font-size:.82rem; color:var(--muted); margin-top:.5rem; font-style:italic}
+  .two{display:grid; grid-template-columns:1fr 1fr; gap:1rem}
+  .bucket{font-size:.92rem}
+  .bucket td:first-child{white-space:nowrap; font-weight:600}
+  @media (max-width:620px){ h1{font-size:2rem} .nav ol{columns:1} .two{grid-template-columns:1fr} }
+  footer.composition-signal{margin-top:4rem; padding-top:1.25rem; border-top:1px solid var(--line); font-size:.8rem; color:var(--muted)}
+</style>
+</head>
+<body>
+<main class="page">
+
+  <p class="eyebrow">Proposal &middot; Compound Engineering Plugin</p>
+  <h1>The <code>ce-pov</code> skill</h1>
+  <p class="lede">A skill that gives you a decisive, repo-grounded <strong>point of view</strong> on an external question &mdash; at the start of a session, or dropped into the middle of one. A bare agent gives you an opinion; <code>ce-pov</code> gives you a verdict it had to earn, and refuses to fake one.</p>
+  <div class="meta">
+    <span class="pill">2026-06-28</span>
+    <span class="pill">topic: ce-pov-skill</span>
+    <span class="pill">status: design proposal (rev 3 &mdash; converged)</span>
+    <span class="pill">reviewed: Claude + Codex + Cursor (4 rounds)</span>
+  </div>
+
+  <div class="callout">
+    <p class="eyebrow">The one rule that is the whole moat</p>
+    <p><strong>It will not hand you a verdict it didn't earn against your actual repo.</strong> A generic <code>deep-research</code> skill already exists; the differentiator is never "research the web." It is the refusal to answer in the abstract. Verified external evidence <em>and</em> concrete repo evidence, or no verdict. Nothing else &mdash; not the conversation, not the user's own assertions &mdash; substitutes for that.</p>
+  </div>
+
+  <nav class="nav" aria-label="Contents">
+    <p class="eyebrow" style="margin:0">Contents</p>
+    <ol>
+      <li><a href="#purpose">What it is</a></li>
+      <li><a href="#fight">What we bring to the fight</a></li>
+      <li><a href="#method">The method (4 steps)</a></li>
+      <li><a href="#verdict">The verdict contract</a></li>
+      <li><a href="#invocation">One method, two contexts</a></li>
+      <li><a href="#provenance">Grounding provenance</a></li>
+      <li><a href="#guardrails">Two guardrails</a></li>
+      <li><a href="#boundaries">Boundaries</a></li>
+      <li><a href="#scope">What we don't build</a></li>
+      <li><a href="#universal">Universal mode (deferred)</a></li>
+      <li><a href="#name">The name</a></li>
+      <li><a href="#review">External review</a></li>
+      <li><a href="#open">Open questions</a></li>
+    </ol>
+  </nav>
+
+  <h2 id="purpose">What it is</h2>
+  <p><strong>One-liner:</strong> <code>ce-pov</code> forms a project-grounded point of view on something from the outside world. You bring an external input; it does real research <em>and</em> reads your own codebase, then returns a decisive, graded verdict <em>for your project</em>.</p>
+  <p>It is one primitive &mdash; "form a grounded POV on an external input" &mdash; with many mouths. The original motivating case (should we adopt framework X?) is one instance:</p>
+  <ul class="tight">
+    <li>"Should we adopt framework X here?" (adoption / build-vs-buy / migrate-off)</li>
+    <li>"What should we use for auth?" (<strong>selection</strong> from a discoverable field &mdash; with a guard; see Boundaries)</li>
+    <li>"Does this CVE / deprecation / breaking change actually affect us?"</li>
+    <li>"Is this pattern from elsewhere right for us? Is our current approach dead?"</li>
+    <li>"We rejected X 18 months ago &mdash; still the right call?"</li>
+    <li>"Weigh in on the direction this brainstorm is heading." (mid-session second opinion)</li>
+  </ul>
+
+  <h2 id="fight">What we bring to the fight</h2>
+  <p>Anyone can prompt their agent "what's your POV on X?" So the value is not capability &mdash; the agent has that. The value is a <strong>sharp, opinionated method</strong>, the same reason <code>ce-work</code> and <code>ce-plan</code> exist when an agent can already code and plan. A bare agent asked "should we use X?" fails in predictable ways; <code>ce-pov</code> is the method that counteracts each:</p>
+  <table>
+    <thead><tr><th>A bare prompt tends to&hellip;</th><th><code>ce-pov</code> forces&hellip;</th></tr></thead>
+    <tbody>
+      <tr><td>Answer in the abstract ("X is great")</td><td>Dual-grounding: cite a real dep / call-site / prior decision, or no verdict</td></tr>
+      <tr><td>Agree with your framing (pushover)</td><td>A skeptic stance: seek disconfirming evidence, name the alternatives, allow "no"</td></tr>
+      <tr><td>Stop at the first source; hallucinate citations</td><td>Active, verified research &mdash; the claim must be supported by the source</td></tr>
+      <tr><td>Evaluate the named thing in isolation</td><td>Name the incumbent and "do nothing" as real options</td></tr>
+      <tr><td>Give a wishy-washy "it depends"</td><td>A graded verdict + "yes, if &lt;repo conditions&gt;" (+ a reversal trigger on weighty calls)</td></tr>
+      <tr><td>Let the answer evaporate in chat</td><td>An optional durable record, so re-runs are cheap</td></tr>
+      <tr><td>Re-litigate what the team already decided</td><td>A precedent check before researching</td></tr>
+      <tr><td>Apply uniform effort to trivial and weighty calls</td><td>Rigor sized to reversibility</td></tr>
+    </tbody>
+  </table>
+
+  <h2 id="method">The method (4 steps)</h2>
+  <p>Four steps, deliberately few so the agent runs a judgment loop rather than performing an 8-item checklist. Two things are <strong>cross-cutting properties of every step, not phases of their own</strong>: the <strong>skeptic stance</strong> (seek disconfirming evidence; "no" and "not our problem" are first-class) and <strong>reversibility-tiered effort</strong> (how deep each step goes scales with the door type).</p>
+  <div class="card">
+    <div class="step"><div class="n">1</div><p class="b"><b>Frame.</b> Pin the actual question, the incumbent, the time horizon, and what success looks like. Most "should we use X?" asks smuggle unstated assumptions ("replace auth" vs "greenfield sidecar"); without this the skill optimizes the wrong question elegantly. If the field of candidates can't be bounded or the decision criteria are unclear, stop and route out (see Boundaries) rather than turning into disguised requirements discovery.</p></div>
+    <div class="step"><div class="n">2</div><p class="b"><b>Precedent.</b> Check what we already decided &mdash; prior decision records, closed issues, past rejections. Update a known-good; don't re-litigate. (Precedent-aware, not rigidly first &mdash; a CVE's urgency can lead.)</p></div>
+    <div class="step"><div class="n">3</div><p class="b"><b>Verify (external + project).</b> The dual-grounded core. Active external research with the best tools available (built-in web search/fetch, or Exa / parallel-search / an MCP search server when present &mdash; never required), claims supported by their cited source; <em>and</em> concrete project grounding &mdash; deps, lockfile, license, call-site migration cost, conventions, git history, the named incumbent. Neither leg alone is enough.</p></div>
+    <div class="step"><div class="n">4</div><p class="b"><b>Verdict.</b> Emit the fixed verdict contract (next section): a grade from the defined vocabulary + "yes, if &lt;repo-specific conditions&gt;" + a next-step handoff. For Tier 2/3 (weighty/one-way) calls, add a <strong>reversal trigger</strong> ("adopt if volume &lt; N; re-evaluate if enterprise SSO appears"); skip it on Tier 1 / CVE triage where it is formulaic noise. Durable record optional, recommended only for Tier 2/3 or precedent-changing decisions.</p></div>
+  </div>
+
+  <h2 id="verdict">The verdict contract</h2>
+  <p>Two things make verdicts trustworthy <em>and</em> comparable: a fixed <strong>vocabulary</strong> and a fixed <strong>shape</strong>. Both are mandatory &mdash; the durable record and the Step-2 precedent search only work if past verdicts can be grepped and compared, which prose-only output defeats.</p>
+  <h3>Vocabulary &mdash; the grade is always one of:</h3>
+  <table>
+    <thead><tr><th>Grade</th><th>Meaning</th></tr></thead>
+    <tbody>
+      <tr><td><strong>Adopt</strong></td><td>Proven fit for us &mdash; use it.</td></tr>
+      <tr><td><strong>Trial</strong></td><td>Promising &mdash; use on a low-risk slice first; next step is a scoped spike.</td></tr>
+      <tr><td><strong>Hold</strong></td><td>A complete, valid decision to <em>wait</em> &mdash; promising but unstable, migration cost exceeds current pain, category moving too fast. <strong>Hold is a successful outcome, not a failure to finish.</strong> "Hold &mdash; insufficient grounding" is one subtype (the invalid-verdict escape when the project leg is too thin), not the only meaning of Hold.</td></tr>
+      <tr><td><strong>Reject</strong></td><td>Judged not worth it for us.</td></tr>
+      <tr><td><strong>Not our problem</strong></td><td>For exposure questions (CVE / deprecation) that don't reach us &mdash; avoids forced adopt/reject theater.</td></tr>
+    </tbody>
+  </table>
+  <h3>Schema &mdash; every verdict carries these fields:</h3>
+  <p><code>Grade</code> &middot; <code>Incumbent</code> &middot; <code>Verified facts (repo + external)</code> &middot; <code>Conversation hypotheses (unverified &mdash; warm only)</code> &middot; <code>Conditions ("yes, if &hellip;")</code> &middot; <code>Handoff (next skill)</code> &middot; <code>Reversal trigger (Tier 2/3 only)</code></p>
+  <p>The schema also enforces the provenance discipline structurally: "verified facts" and "conversation hypotheses" are separate fields, so an unverified chat claim can never quietly masquerade as grounding.</p>
+
+  <h2 id="invocation">One method, two contexts</h2>
+  <p><code>ce-pov</code> is one method with an <strong>invocation modifier</strong> &mdash; not two separate workflows. The same four steps run; what changes is where the <em>question</em> comes from and how much ceremony is warranted.</p>
+
+  <figure>
+    <svg viewBox="0 0 760 280" role="img" aria-labelledby="postt">
+      <title id="postt">Cold and warm invocation run the same dual-grounded verdict method; warm draws only the question and claims-to-verify from the conversation</title>
+      <defs><style>.h{font:600 13px Inter,sans-serif}.s{font:11.5px Inter,sans-serif}.t{font:600 12px Inter,sans-serif}</style>
+        <marker id="ap" markerWidth="8" markerHeight="8" refX="6" refY="3" orient="auto"><path d="M0,0 L6,3 L0,6 Z" fill="#9a3b1f"/></marker>
+      </defs>
+      <!-- COLD -->
+      <rect x="20" y="24" width="250" height="78" rx="11" fill="#e8eef2" stroke="#c4d2da"/>
+      <text x="36" y="48" class="h" fill="#2c4a5a">COLD (session start)</text>
+      <text x="36" y="70" class="s" fill="#2c4a5a">user states an explicit</text>
+      <text x="36" y="87" class="s" fill="#2c4a5a">external question</text>
+      <!-- WARM -->
+      <rect x="20" y="160" width="250" height="96" rx="11" fill="#f6e9e2" stroke="#d8b59f"/>
+      <text x="36" y="184" class="h" fill="#7a2d16">WARM (mid-session)</text>
+      <text x="36" y="205" class="s" fill="#7a2d16">conversation supplies the</text>
+      <text x="36" y="222" class="s" fill="#7a2d16">QUESTION + claims-to-verify</text>
+      <text x="36" y="239" class="s" fill="#7a2d16">(not grounding); stay short</text>
+      <!-- confirm gate -->
+      <rect x="300" y="172" width="150" height="72" rx="10" fill="#fff" stroke="#d8b59f"/>
+      <text x="375" y="196" class="t" fill="#7a2d16" text-anchor="middle">Question absent</text>
+      <text x="375" y="213" class="s" fill="#7a2d16" text-anchor="middle">or ambiguous?</text>
+      <text x="375" y="231" class="s" fill="#7a2d16" text-anchor="middle">infer &rarr; confirm</text>
+      <!-- engine -->
+      <rect x="480" y="92" width="160" height="96" rx="12" fill="#7a2d16"/>
+      <text x="560" y="124" class="h" fill="#fff" text-anchor="middle">4-step method</text>
+      <text x="560" y="146" class="s" fill="#fbe7dc" text-anchor="middle">dual-grounded,</text>
+      <text x="560" y="162" class="s" fill="#fbe7dc" text-anchor="middle">skeptic, tier-scaled</text>
+      <!-- output -->
+      <rect x="668" y="110" width="72" height="60" rx="10" fill="#e5efe4" stroke="#a9c79f"/>
+      <text x="704" y="136" class="t" fill="#3a5a32" text-anchor="middle">Verdict</text>
+      <text x="704" y="154" class="s" fill="#3a5a32" text-anchor="middle">+ handoff</text>
+      <!-- arrows -->
+      <line x1="270" y1="63" x2="478" y2="120" stroke="#9a3b1f" stroke-width="1.8" marker-end="url(#ap)"/>
+      <line x1="270" y1="208" x2="298" y2="208" stroke="#9a3b1f" stroke-width="1.8" marker-end="url(#ap)"/>
+      <line x1="450" y1="200" x2="500" y2="186" stroke="#9a3b1f" stroke-width="1.8" marker-end="url(#ap)"/>
+      <line x1="640" y1="140" x2="666" y2="140" stroke="#9a3b1f" stroke-width="1.8" marker-end="url(#ap)"/>
+    </svg>
+    <figcaption>Same method, two entry contexts. Crucially, warm invocation takes only the <em>question</em> and <em>claims to verify</em> from the conversation &mdash; the grounding still comes from repo + verified external sources.</figcaption>
+  </figure>
+
+  <div class="two">
+    <div class="card">
+      <h3>Cold &mdash; session start</h3>
+      <p>The user states an external question; the full method runs at the warranted tier. This is where the moat is thickest, because the repo grounding is automatable and hard to fake. Ship this rock-solid first.</p>
+    </div>
+    <div class="card">
+      <h3>Warm &mdash; mid-session interjection</h3>
+      <p>You want a second opinion mid-flow. The conversation supplies the <strong>question and the claims to verify</strong> &mdash; <em>not</em> grounding (see next section). Stay a <strong>guest</strong>: output a verdict block only, no reframing the session, hand control back. Be <strong>more</strong> adversarial than cold mode &mdash; the conversation's momentum pulls toward agreement, and a second opinion that rubber-stamps is worthless. When the question is absent or materially ambiguous, infer it and confirm before answering; when the user names it ("ce-pov: should we use X?"), skip the gate.</p>
+    </div>
+  </div>
+
+  <h2 id="provenance">Grounding provenance &mdash; the warm-mode safeguard</h2>
+  <p>The sharpest risk surfaced in review: <strong>consensus laundering</strong> &mdash; twenty turns of the user and the agent mutually assuming "we must migrate off Postgres" quietly become "grounding," and <code>ce-pov</code> returns a confident verdict that ratifies chat fiction. The fix is to label every input by where it came from, and to let only verified buckets satisfy the verdict rule:</p>
+  <table class="bucket">
+    <thead><tr><th>Bucket</th><th>Counts as grounding?</th></tr></thead>
+    <tbody>
+      <tr><td>Observed repo facts</td><td>Yes</td></tr>
+      <tr><td>Verified external facts</td><td>Yes</td></tr>
+      <tr><td>Conversation claims</td><td>No &mdash; frame &amp; hypotheses only, until corroborated</td></tr>
+      <tr><td>Assumptions needing confirmation</td><td>No &mdash; surfaced for the user to confirm/deny</td></tr>
+    </tbody>
+  </table>
+  <p>Warm invocation adds <strong>no evidentiary weight</strong>: it surfaces hypotheses and framing, nothing more. If the conversation says "we have 40 call-sites on library X," the skill must <code>grep</code> before that counts. <strong>Same invalidation rule, no warm exemption.</strong> A verdict may <em>use</em> conversation claims to frame the decision, but cannot lean on them to satisfy dual-grounding unless corroborated or explicitly marked conditional.</p>
+
+  <h2 id="guardrails">Two guardrails</h2>
+  <p>Both reviewers independently flagged the same self-failure &mdash; form over substance &mdash; from opposite ends. Two guardrails, one for each end:</p>
+  <div class="guard theater">
+    <h3 style="margin-top:0">Anti-theater &mdash; the Invalid-Verdict Rule</h3>
+    <p>If the project-grounding leg is thinner than the external leg &mdash; can't name the incumbent + at least one concrete touchpoint, or a prior decision &mdash; the skill is <strong>forbidden</strong> from saying Adopt/Reject. It must return <strong>"Hold &mdash; insufficient project grounding"</strong> with a numbered list of what to inspect next. No verdict on vibes; the skill earns authority by refusing to pretend. (The provenance rule above is what stops warm mode from quietly evading this.)</p>
+  </div>
+  <div class="guard ritual">
+    <h3 style="margin-top:0">Anti-ritual &mdash; Reversibility-Tiered Effort</h3>
+    <p>Bind effort and output length to the door type so it stays cheap enough to reach for casually. <strong>Tier 1 (reversible):</strong> one screen, 1&ndash;2 external + 1&ndash;2 repo facts, no reversal trigger. <strong>Tier 2 (moderate):</strong> fuller alternatives. <strong>Tier 3 (one-way / security / legal):</strong> deep research, precedent search, durable record. Otherwise it becomes a bureaucratic ritual and users go back to asking the model casually. The confirm-gate is held to the same standard &mdash; only when genuinely needed.</p>
+  </div>
+
+  <h2 id="boundaries">Boundaries</h2>
+  <p>The discriminator: <code>ce-pov</code> always takes an <strong>external input</strong> and judges it <strong>against your project</strong>, producing a <strong>decisive position</strong> &mdash; not options, not requirements, not implementation, not a diagnosis.</p>
+  <table>
+    <thead><tr><th>Neighbor</th><th>Theirs</th><th>The line</th></tr></thead>
+    <tbody>
+      <tr><td>generic <code>deep-research</code></td><td>"Tell me about X"</td><td><code>ce-pov</code> requires project grounding and ends in a graded verdict</td></tr>
+      <tr><td><code>ce-ideate</code></td><td>Invent options from an unbounded space</td><td><strong>Invented vs. discovered:</strong> ideate invents; <code>ce-pov</code> judges/selects from a discoverable field</td></tr>
+      <tr><td><code>ce-brainstorm</code></td><td>Scope a chosen idea into requirements</td><td><code>ce-pov</code> decides <em>whether</em>; brainstorm scopes <em>what</em> once it's a yes. No rollout sketching</td></tr>
+      <tr><td><code>ce-plan</code></td><td>How to build it</td><td>Verdict accepted &rarr; hand off. No task breakdown</td></tr>
+      <tr><td><code>ce-debug</code></td><td>Diagnose observed failing behavior</td><td><code>ce-pov</code> assesses <em>exposure and priority</em> (is this CVE ours, how urgent); debug investigates an actual failure</td></tr>
+      <tr><td><code>ce-strategy</code></td><td>Product thesis / metrics</td><td><code>ce-pov</code> is bounded to a specific external input, not company direction</td></tr>
+    </tbody>
+  </table>
+  <p><strong>The selection escape hatch (sharpened in review).</strong> "What should we use for auth?" is a <code>ce-pov</code> selection only when the candidate field is bounded (roughly &le;5 real options) and the decision criteria are knowable enough to judge. If the field can't be bounded without invention, or the criteria are unclear, <code>ce-pov</code> returns <strong>Hold &rarr; route to <code>ce-ideate</code> to enumerate (or <code>ce-brainstorm</code> to surface criteria), then re-run <code>ce-pov</code></strong>. Without this, large/ambiguous fields (auth, observability, CI) tempt a divergent fan-out and the skill becomes disguised requirements discovery.</p>
+
+  <h2 id="scope">What we don't build (v1)</h2>
+  <p>The risk is boiling the ocean. Cut anything that turns a judgment skill into an implementation or governance system. Unanimous across reviewers:</p>
+  <ul class="tight">
+    <li>No PoC scaffolding; no scheduled re-evaluation engine</li>
+    <li>No weighted-scoring spreadsheet (a one-line "considered: incumbent, X, Y; rejected Y because&hellip;" beats a matrix)</li>
+    <li>No <em>mandatory</em> decision-record commit &mdash; offer it, keep it lightweight; many runs (CVE triage) are fine as a chat verdict</li>
+    <li>No deep git archaeology (cap at ~15-min-equivalent effort); no exhaustive market map</li>
+    <li>No required multi-agent research fan-out</li>
+    <li>No three-mode taxonomy in the skill instructions &mdash; one method, one invocation modifier</li>
+  </ul>
+  <p>The standard is <strong>"enough verified evidence for the decision class,"</strong> not a research report.</p>
+
+  <h2 id="universal">Universal mode (designed-in, deferred to a later version)</h2>
+  <p>"Repo grounding" is a special case of <strong>grounding in the asker's real situation</strong>, so the method is portable beyond code (e.g. "should our company use vendor Y?", "should I adopt this productivity system?") with the grounding leg adaptive: repo when there is one, user-supplied context otherwise. That is real and consistent with how <code>ce-ideate</code> / <code>ce-brainstorm</code> / <code>ce-plan</code> generalize.</p>
+  <p><strong>Decision for v1: ship repo/project-first; treat universal as a caveat, not a headline.</strong> Reviewers were unanimous that universal mode broadens surface area, weakens the moat (the automatable grounding largely vanishes, drifting toward method-only deep-research), and invites fuzzy life/business advice under the same brand. The portable method stays in the design; v1 is explicitly optimized for code/project contexts, with "works outside a repo when enough concrete context exists" as a noted capability to prove out before promoting. <em>(This sequencing is the one item flagged for the owner's confirmation.)</em></p>
+
+  <h2 id="name">The name</h2>
+  <p><code>ce-pov</code> &mdash; it names the deliverable (a point of view) in the user's own words, signals a <em>position</em> (not a report), and carries the full breadth (a POV on any question). It earns its keep most in the warm "weigh in / second opinion" posture, which is unmistakably "give me your POV," never "check if it fits."</p>
+  <p>Rejected alternatives: <code>ce-research</code> (collides with the generic <code>deep-research</code> skill and signals open-ended exploration, the opposite of a verdict); <code>ce-fit</code> / <code>ce-fit-check</code> (too narrow &mdash; "fit" is one <em>criterion</em> the skill weighs, not the act; it shrinks a judgment skill into a compatibility check). If a sharper signal of "grounded judgment" is wanted later without narrowing, <code>ce-stance</code> and <code>ce-verdict</code> are the closest siblings.</p>
+
+  <h2 id="review">External review (Codex + Cursor, four rounds)</h2>
+  <p>Two independent models reviewed across four rounds and converged. At round 4 both returned <strong>"ship it &mdash; no blocker"</strong>; their two final additions (a defined Hold-inclusive verdict vocabulary, and a fixed verdict schema) are folded into <a href="#verdict">The verdict contract</a>. Round-3 changes:</p>
+  <ul class="tight">
+    <li><strong>Fixed the central contradiction:</strong> warm mode no longer treats the conversation as grounding &mdash; only as question + claims-to-verify &mdash; closing the "consensus laundering" hole both flagged. Added the grounding-provenance buckets.</li>
+    <li><strong>Collapsed 7 steps &rarr; 4</strong>; skeptic stance and reversibility tiering are now cross-cutting properties, and the two postures are one method + an invocation modifier (was a three-mode taxonomy reviewers warned agents would overfit).</li>
+    <li><strong>Tier-gated the reversal trigger</strong> (Tier 2/3 only) and the durable record.</li>
+    <li><strong>Narrowed the confirm-gate</strong> to absent/ambiguous questions.</li>
+    <li><strong>Added the selection escape hatch</strong> (unbounded field / unclear criteria &rarr; Hold &rarr; ideate/brainstorm &rarr; re-run).</li>
+    <li><strong>Deferred universal mode</strong> to repo-first per unanimous advice.</li>
+    <li>Earlier rounds established: dual-grounding as the #1 move, the two guardrails, "frame the decision first", incumbent inventory, and "not our problem" as a first-class verdict.</li>
+  </ul>
+
+  <h2 id="open">Open questions / next steps</h2>
+  <ul class="tight">
+    <li>Where does the optional durable record live &mdash; a new <code>docs/decisions/</code> (ADR-style) path, or fold into <code>docs/solutions/</code>? Needs a slug/index convention so the precedent check (Step 2) can find prior verdicts.</li>
+    <li>Should the precedent check and the verified-citation pass be shared persona assets, given the existing research-persona duplication across skills (the <code>web-researcher.md</code> copies have already drifted)? Likely a shared <em>evidence/verdict output contract</em> rather than a shared file, per the plugin's self-contained-skill constraint.</li>
+    <li>Confirm the v1 repo-first / universal-deferred scoping (owner decision).</li>
+    <li>Hand off to <code>ce-brainstorm</code> to turn this proposal into a requirements-only unified plan when ready to build.</li>
+  </ul>
+
+  <footer class="composition-signal">Composed 2026-06-28 by ce-ideate (design proposal, rev 3 &mdash; converged) &middot; ce-pov skill &middot; synthesized from repo grounding, a 5-frame ideation pass, and four rounds of cross-model review (Codex gpt-5.5, Cursor Composer 2.5; both returned "ship it" at round 4). Supersedes the 2026-06-27 ce-research ideation draft.</footer>
+
+</main>
+</body>
+</html>

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-copilot-converter-target-plan.md

@@ -0,0 +1,328 @@
+---
+title: "feat: Add GitHub Copilot converter target"
+type: feat
+date: 2026-02-14
+status: complete
+---
+
+# feat: Add GitHub Copilot Converter Target
+
+## Overview
+
+Add GitHub Copilot as a converter target following the established `TargetHandler` pattern. This converts the compound-engineering Claude Code plugin into Copilot's native format: custom agents (`.agent.md`), agent skills (`SKILL.md`), and MCP server configuration JSON.
+
+**Brainstorm:** `docs/brainstorms/2026-02-14-copilot-converter-target-brainstorm.md`
+
+## Problem Statement
+
+The CLI tool (`compound`) already supports converting Claude Code plugins to 5 target formats (OpenCode, Codex, Droid, Cursor, Pi). GitHub Copilot is a widely-used AI coding assistant that now supports custom agents, skills, and MCP servers — but there's no converter target for it.
+
+## Proposed Solution
+
+Follow the existing converter pattern exactly:
+
+1. Define types (`src/types/copilot.ts`)
+2. Implement converter (`src/converters/claude-to-copilot.ts`)
+3. Implement writer (`src/targets/copilot.ts`)
+4. Register target (`src/targets/index.ts`)
+5. Add sync support (`src/sync/copilot.ts`, `src/commands/sync.ts`)
+6. Write tests and documentation
+
+### Component Mapping
+
+| Claude Code | Copilot | Output Path |
+|-------------|---------|-------------|
+| Agents (`.md`) | Custom Agents (`.agent.md`) | `.github/agents/{name}.agent.md` |
+| Commands (`.md`) | Agent Skills (`SKILL.md`) | `.github/skills/{name}/SKILL.md` |
+| Skills (`SKILL.md`) | Agent Skills (`SKILL.md`) | `.github/skills/{name}/SKILL.md` |
+| MCP Servers | Config JSON | `.github/copilot-mcp-config.json` |
+| Hooks | Skipped | Warning to stderr |
+
+## Technical Approach
+
+### Phase 1: Types
+
+**File:** `src/types/copilot.ts`
+
+```typescript
+export type CopilotAgent = {
+  name: string
+  content: string // Full .agent.md content with frontmatter
+}
+
+export type CopilotGeneratedSkill = {
+  name: string
+  content: string // SKILL.md content with frontmatter
+}
+
+export type CopilotSkillDir = {
+  name: string
+  sourceDir: string
+}
+
+export type CopilotMcpServer = {
+  type: string
+  command?: string
+  args?: string[]
+  url?: string
+  tools: string[]
+  env?: Record<string, string>
+  headers?: Record<string, string>
+}
+
+export type CopilotBundle = {
+  agents: CopilotAgent[]
+  generatedSkills: CopilotGeneratedSkill[]
+  skillDirs: CopilotSkillDir[]
+  mcpConfig?: Record<string, CopilotMcpServer>
+}
+```
+
+### Phase 2: Converter
+
+**File:** `src/converters/claude-to-copilot.ts`
+
+**Agent conversion:**
+- Frontmatter: `description` (required, fallback to `"Converted from Claude agent {name}"`), `tools: ["*"]`, `infer: true`
+- Pass through `model` if present
+- Fold `capabilities` into body as `## Capabilities` section (same as Cursor)
+- Use `formatFrontmatter()` utility
+- Warn if body exceeds 30,000 characters (`.length`)
+
+**Command → Skill conversion:**
+- Convert to SKILL.md format with frontmatter: `name`, `description`
+- Flatten namespaced names: `workflows:plan` → `plan`
+- Drop `allowed-tools`, `model`, `disable-model-invocation` silently
+- Include `argument-hint` as `## Arguments` section in body
+
+**Skill pass-through:**
+- Map to `CopilotSkillDir` as-is (same as Cursor)
+
+**MCP server conversion:**
+- Transform env var names: `API_KEY` → `COPILOT_MCP_API_KEY`
+- Skip vars already prefixed with `COPILOT_MCP_`
+- Add `type: "local"` for command-based servers, `type: "sse"` for URL-based
+- Set `tools: ["*"]` for all servers
+
+**Content transformation (`transformContentForCopilot`):**
+
+| Pattern | Input | Output |
+|---------|-------|--------|
+| Task calls | `Task repo-research-analyst(desc)` | `Use the repo-research-analyst skill to: desc` |
+| Slash commands | `/workflows:plan` | `/plan` |
+| Path rewriting | `.claude/` | `.github/` |
+| Home path rewriting | `~/.claude/` | `~/.copilot/` |
+| Agent references | `@security-sentinel` | `the security-sentinel agent` |
+
+**Hooks:** Warn to stderr if present, skip.
+
+### Phase 3: Writer
+
+**File:** `src/targets/copilot.ts`
+
+**Path resolution:**
+- If `outputRoot` basename is `.github`, write directly into it (avoid `.github/.github/` double-nesting)
+- Otherwise, nest under `.github/`
+
+**Write operations:**
+- Agents → `.github/agents/{name}.agent.md` (note: `.agent.md` extension)
+- Generated skills (from commands) → `.github/skills/{name}/SKILL.md`
+- Skill dirs → `.github/skills/{name}/` (copy via `copyDir`)
+- MCP config → `.github/copilot-mcp-config.json` (backup existing with `backupFile`)
+
+### Phase 4: Target Registration
+
+**File:** `src/targets/index.ts`
+
+Add import and register:
+
+```typescript
+import { convertClaudeToCopilot } from "../converters/claude-to-copilot"
+import { writeCopilotBundle } from "./copilot"
+
+// In targets record:
+copilot: {
+  name: "copilot",
+  implemented: true,
+  convert: convertClaudeToCopilot as TargetHandler<CopilotBundle>["convert"],
+  write: writeCopilotBundle as TargetHandler<CopilotBundle>["write"],
+},
+```
+
+### Phase 5: Sync Support
+
+**File:** `src/sync/copilot.ts`
+
+Follow the Cursor sync pattern (`src/sync/cursor.ts`):
+- Symlink skills to `.github/skills/` using `forceSymlink`
+- Validate skill names with `isValidSkillName`
+- Convert MCP servers with `COPILOT_MCP_` prefix transformation
+- Merge MCP config into existing `.github/copilot-mcp-config.json`
+
+**File:** `src/commands/sync.ts`
+
+- Add `"copilot"` to `validTargets` array
+- Add case in `resolveOutputRoot()`: `case "copilot": return path.join(process.cwd(), ".github")`
+- Add import and switch case for `syncToCopilot`
+- Update meta description to include "Copilot"
+
+### Phase 6: Tests
+
+**File:** `tests/copilot-converter.test.ts`
+
+Test cases (following `tests/cursor-converter.test.ts` pattern):
+
+```
+describe("convertClaudeToCopilot")
+  ✓ converts agents to .agent.md with Copilot frontmatter
+  ✓ agent description is required, fallback generated if missing
+  ✓ agent with empty body gets default body
+  ✓ agent capabilities are prepended to body
+  ✓ agent model field is passed through
+  ✓ agent tools defaults to ["*"]
+  ✓ agent infer defaults to true
+  ✓ warns when agent body exceeds 30k characters
+  ✓ converts commands to skills with SKILL.md format
+  ✓ flattens namespaced command names
+  ✓ command name collision after flattening is deduplicated
+  ✓ command allowedTools is silently dropped
+  ✓ command with argument-hint gets Arguments section
+  ✓ passes through skill directories
+  ✓ skill and generated skill name collision is deduplicated
+  ✓ converts MCP servers with COPILOT_MCP_ prefix
+  ✓ MCP env vars already prefixed are not double-prefixed
+  ✓ MCP servers get type field (local vs sse)
+  ✓ warns when hooks are present
+  ✓ no warning when hooks are absent
+  ✓ plugin with zero agents produces empty agents array
+  ✓ plugin with only skills works
+
+describe("transformContentForCopilot")
+  ✓ rewrites .claude/ paths to .github/
+  ✓ rewrites ~/.claude/ paths to ~/.copilot/
+  ✓ transforms Task agent calls to skill references
+  ✓ flattens slash commands
+  ✓ transforms @agent references to agent references
+```
+
+**File:** `tests/copilot-writer.test.ts`
+
+Test cases (following `tests/cursor-writer.test.ts` pattern):
+
+```
+describe("writeCopilotBundle")
+  ✓ writes agents, generated skills, copied skills, and MCP config
+  ✓ agents use .agent.md file extension
+  ✓ writes directly into .github output root without double-nesting
+  ✓ handles empty bundles gracefully
+  ✓ writes multiple agents as separate .agent.md files
+  ✓ backs up existing copilot-mcp-config.json before overwriting
+  ✓ creates skill directories with SKILL.md
+```
+
+**File:** `tests/sync-copilot.test.ts`
+
+Test cases (following `tests/sync-cursor.test.ts` pattern):
+
+```
+describe("syncToCopilot")
+  ✓ symlinks skills to .github/skills/
+  ✓ skips skills with invalid names
+  ✓ merges MCP config with existing file
+  ✓ transforms MCP env var names to COPILOT_MCP_ prefix
+  ✓ writes MCP config with restricted permissions (0o600)
+```
+
+### Phase 7: Documentation
+
+**File:** `docs/specs/copilot.md`
+
+Follow `docs/specs/cursor.md` format:
+- Last verified date
+- Primary sources (GitHub Docs URLs)
+- Config locations table
+- Agents section (`.agent.md` format, frontmatter fields)
+- Skills section (`SKILL.md` format)
+- MCP section (config structure, env var prefix requirement)
+- Character limits (30k agent body)
+
+**File:** `README.md`
+
+- Add "copilot" to the list of supported targets
+- Add usage example: `compound convert --to copilot ./plugins/compound-engineering`
+- Add sync example: `compound sync copilot`
+
+## Acceptance Criteria
+
+### Converter
+- [x] Agents convert to `.agent.md` with `description`, `tools: ["*"]`, `infer: true`
+- [x] Agent `model` passes through when present
+- [x] Agent `capabilities` fold into body as `## Capabilities`
+- [x] Missing description generates fallback
+- [x] Empty body generates fallback
+- [x] Body exceeding 30k chars triggers stderr warning
+- [x] Commands convert to SKILL.md format
+- [x] Command names flatten (`workflows:plan` → `plan`)
+- [x] Name collisions deduplicated with `-2`, `-3` suffix
+- [x] Command `allowed-tools` dropped silently
+- [x] Skills pass through as `CopilotSkillDir`
+- [x] MCP env vars prefixed with `COPILOT_MCP_`
+- [x] Already-prefixed env vars not double-prefixed
+- [x] MCP servers get `type` field (`local` or `sse`)
+- [x] Hooks trigger warning, skip conversion
+- [x] Content transformation: Task calls, slash commands, paths, @agent refs
+
+### Writer
+- [x] Agents written to `.github/agents/{name}.agent.md`
+- [x] Generated skills written to `.github/skills/{name}/SKILL.md`
+- [x] Skill dirs copied to `.github/skills/{name}/`
+- [x] MCP config written to `.github/copilot-mcp-config.json`
+- [x] Existing MCP config backed up before overwrite
+- [x] No double-nesting when outputRoot is `.github`
+- [x] Empty bundles handled gracefully
+
+### CLI Integration
+- [x] `compound convert --to copilot` works
+- [x] `compound sync copilot` works
+- [x] Copilot registered in `src/targets/index.ts`
+- [x] Sync resolves output to `.github/` in current directory
+
+### Tests
+- [x] `tests/copilot-converter.test.ts` — all converter tests pass
+- [x] `tests/copilot-writer.test.ts` — all writer tests pass
+- [x] `tests/sync-copilot.test.ts` — all sync tests pass
+
+### Documentation
+- [x] `docs/specs/copilot.md` — format specification
+- [x] `README.md` — updated with copilot target
+
+## Files to Create
+
+| File | Purpose |
+|------|---------|
+| `src/types/copilot.ts` | Type definitions |
+| `src/converters/claude-to-copilot.ts` | Converter logic |
+| `src/targets/copilot.ts` | Writer logic |
+| `src/sync/copilot.ts` | Sync handler |
+| `tests/copilot-converter.test.ts` | Converter tests |
+| `tests/copilot-writer.test.ts` | Writer tests |
+| `tests/sync-copilot.test.ts` | Sync tests |
+| `docs/specs/copilot.md` | Format specification |
+
+## Files to Modify
+
+| File | Change |
+|------|--------|
+| `src/targets/index.ts` | Register copilot target |
+| `src/commands/sync.ts` | Add copilot to valid targets, output root, switch case |
+| `README.md` | Add copilot to supported targets |
+
+## References
+
+- [Custom agents configuration - GitHub Docs](https://docs.github.com/en/copilot/reference/custom-agents-configuration)
+- [About Agent Skills - GitHub Docs](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)
+- [MCP and coding agent - GitHub Docs](https://docs.github.com/en/copilot/concepts/agents/coding-agent/mcp-and-coding-agent)
+- Existing converter: `src/converters/claude-to-cursor.ts`
+- Existing writer: `src/targets/cursor.ts`
+- Existing sync: `src/sync/cursor.ts`
+- Existing tests: `tests/cursor-converter.test.ts`, `tests/cursor-writer.test.ts`

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/plans/2026-02-14-feat-auto-detect-install-and-gemini-sync-plan.md

@@ -0,0 +1,361 @@
+---
+title: Auto-detect install targets and add Gemini sync
+type: feat
+status: completed
+date: 2026-02-14
+completed_date: 2026-02-14
+completed_by: "Claude Opus 4.6"
+actual_effort: "Completed in one session"
+---
+
+# Auto-detect Install Targets and Add Gemini Sync
+
+## Overview
+
+Two related improvements to the converter CLI:
+
+1. **`install --to all`** — Auto-detect which AI coding tools are installed and convert to all of them in one command
+2. **`sync --target gemini`** — Add Gemini CLI as a sync target (currently missing), then add `sync --target all` to sync personal config to every detected tool
+
+## Problem Statement
+
+Users currently must run 6 separate commands to install to all targets:
+
+```bash
+bunx @every-env/compound-plugin install compound-engineering --to opencode
+bunx @every-env/compound-plugin install compound-engineering --to droid
+bunx @every-env/compound-plugin install compound-engineering --to cursor
+bunx @every-env/compound-plugin install compound-engineering --to pi
+bunx @every-env/compound-plugin install compound-engineering --to gemini
+```
+
+Superseded note (2026-06-19): Compound Engineering's Codex path is now native plugin install through `codex plugin marketplace add` plus the `/plugins` TUI. The old converted Codex companion install is no longer part of the CE install flow.
+
+Similarly, sync requires separate commands per target. And Gemini sync doesn't exist yet.
+
+## Acceptance Criteria
+
+### Auto-detect install
+
+- [x]`install --to all` detects installed tools and installs to each
+- [x]Detection checks config directories and/or binaries for each tool
+- [x]Prints which tools were detected and which were skipped
+- [x]Tools with no detection signal are skipped (not errored)
+- [x]`convert --to all` also works (same detection logic)
+- [x]Existing `--to <target>` behavior unchanged
+- [x]Tests for detection logic and `all` target handling
+
+### Gemini sync
+
+- [x]`sync --target gemini` symlinks skills and writes MCP servers to `.gemini/settings.json`
+- [x]MCP servers merged into existing `settings.json` (same pattern as writer)
+- [x]`gemini` added to `validTargets` in `sync.ts`
+- [x]Tests for Gemini sync
+
+### Sync all
+
+- [x]`sync --target all` syncs to all detected tools
+- [x]Reuses same detection logic as install
+- [x]Prints summary of what was synced where
+
+## Implementation
+
+### Phase 1: Tool Detection Utility
+
+**Create `src/utils/detect-tools.ts`**
+
+```typescript
+import os from "os"
+import path from "path"
+import { pathExists } from "./files"
+
+export type DetectedTool = {
+  name: string
+  detected: boolean
+  reason: string // e.g. "found ~/.codex/" or "not found"
+}
+
+export async function detectInstalledTools(): Promise<DetectedTool[]> {
+  const home = os.homedir()
+  const cwd = process.cwd()
+
+  const checks: Array<{ name: string; paths: string[] }> = [
+    { name: "opencode", paths: [path.join(home, ".config", "opencode"), path.join(cwd, ".opencode")] },
+    { name: "codex", paths: [path.join(home, ".codex")] },
+    { name: "droid", paths: [path.join(home, ".factory")] },
+    { name: "cursor", paths: [path.join(cwd, ".cursor"), path.join(home, ".cursor")] },
+    { name: "pi", paths: [path.join(home, ".pi")] },
+    { name: "gemini", paths: [path.join(cwd, ".gemini"), path.join(home, ".gemini")] },
+  ]
+
+  const results: DetectedTool[] = []
+  for (const check of checks) {
+    let detected = false
+    let reason = "not found"
+    for (const p of check.paths) {
+      if (await pathExists(p)) {
+        detected = true
+        reason = `found ${p}`
+        break
+      }
+    }
+    results.push({ name: check.name, detected, reason })
+  }
+  return results
+}
+
+export async function getDetectedTargetNames(): Promise<string[]> {
+  const tools = await detectInstalledTools()
+  return tools.filter((t) => t.detected).map((t) => t.name)
+}
+```
+
+**Detection heuristics:**
+
+| Tool | Check paths | Notes |
+|------|------------|-------|
+| OpenCode | `~/.config/opencode/`, `.opencode/` | XDG config or project-local |
+| Codex | `~/.codex/` | Global only |
+| Droid | `~/.factory/` | Global only |
+| Cursor | `.cursor/`, `~/.cursor/` | Project-local or global |
+| Pi | `~/.pi/` | Global only |
+| Gemini | `.gemini/`, `~/.gemini/` | Project-local or global |
+
+### Phase 2: Gemini Sync
+
+**Create `src/sync/gemini.ts`**
+
+Follow the Cursor sync pattern (`src/sync/cursor.ts`) since both use JSON config with `mcpServers` key:
+
+```typescript
+import path from "path"
+import { symlinkSkills } from "../utils/symlink"
+import { backupFile, pathExists, readJson, writeJson } from "../utils/files"
+import type { ClaudeMcpServer } from "../types/claude"
+
+export async function syncToGemini(
+  skills: { name: string; sourceDir: string }[],
+  mcpServers: Record<string, ClaudeMcpServer>,
+  outputRoot: string,
+): Promise<void> {
+  const geminiDir = path.join(outputRoot, ".gemini")
+
+  // Symlink skills
+  if (skills.length > 0) {
+    const skillsDir = path.join(geminiDir, "skills")
+    await symlinkSkills(skills, skillsDir)
+  }
+
+  // Merge MCP servers into settings.json
+  if (Object.keys(mcpServers).length > 0) {
+    const settingsPath = path.join(geminiDir, "settings.json")
+    let existing: Record<string, unknown> = {}
+    if (await pathExists(settingsPath)) {
+      await backupFile(settingsPath)
+      try {
+        existing = await readJson<Record<string, unknown>>(settingsPath)
+      } catch {
+        console.warn("Warning: existing settings.json could not be parsed and will be replaced.")
+      }
+    }
+
+    const existingMcp = (existing.mcpServers && typeof existing.mcpServers === "object")
+      ? existing.mcpServers as Record<string, unknown>
+      : {}
+
+    const merged = { ...existing, mcpServers: { ...existingMcp, ...convertMcpServers(mcpServers) } }
+    await writeJson(settingsPath, merged)
+  }
+}
+
+function convertMcpServers(servers: Record<string, ClaudeMcpServer>) {
+  const result: Record<string, Record<string, unknown>> = {}
+  for (const [name, server] of Object.entries(servers)) {
+    const entry: Record<string, unknown> = {}
+    if (server.command) {
+      entry.command = server.command
+      if (server.args?.length) 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
+}
+```
+
+**Update `src/commands/sync.ts`:**
+
+- Add `"gemini"` to `validTargets` array
+- Import `syncToGemini` from `../sync/gemini`
+- Add case in switch for `"gemini"` calling `syncToGemini(skills, mcpServers, outputRoot)`
+
+### Phase 3: Wire `--to all` into Install and Convert
+
+**Modify `src/commands/install.ts`:**
+
+```typescript
+import { detectInstalledTools } from "../utils/detect-tools"
+
+// In args definition, update --to description:
+to: {
+  type: "string",
+  default: "opencode",
+  description: "Target format (opencode | codex | droid | cursor | pi | gemini | all)",
+},
+
+// In run(), before the existing target lookup:
+if (targetName === "all") {
+  const detected = await detectInstalledTools()
+  const activeTargets = detected.filter((t) => t.detected)
+
+  if (activeTargets.length === 0) {
+    console.log("No AI coding tools detected. Install at least one tool first.")
+    return
+  }
+
+  console.log(`Detected ${activeTargets.length} tools:`)
+  for (const tool of detected) {
+    console.log(`  ${tool.detected ? "✓" : "✗"} ${tool.name} — ${tool.reason}`)
+  }
+
+  // Install to each detected target
+  for (const tool of activeTargets) {
+    const handler = targets[tool.name]
+    const bundle = handler.convert(plugin, options)
+    if (!bundle) continue
+    const root = resolveTargetOutputRoot(tool.name, outputRoot, codexHome, piHome, hasExplicitOutput)
+    await handler.write(root, bundle)
+    console.log(`Installed ${plugin.manifest.name} to ${tool.name} at ${root}`)
+  }
+
+  // Codex post-processing
+  if (activeTargets.some((t) => t.name === "codex")) {
+    await ensureCodexAgentsFile(codexHome)
+  }
+  return
+}
+```
+
+**Same change in `src/commands/convert.ts`** with its version of `resolveTargetOutputRoot`.
+
+### Phase 4: Wire `--target all` into Sync
+
+**Modify `src/commands/sync.ts`:**
+
+```typescript
+import { detectInstalledTools } from "../utils/detect-tools"
+
+// Update validTargets:
+const validTargets = ["opencode", "codex", "pi", "droid", "cursor", "gemini", "all"] as const
+
+// In run(), handle "all":
+if (targetName === "all") {
+  const detected = await detectInstalledTools()
+  const activeTargets = detected.filter((t) => t.detected).map((t) => t.name)
+
+  if (activeTargets.length === 0) {
+    console.log("No AI coding tools detected.")
+    return
+  }
+
+  console.log(`Syncing to ${activeTargets.length} detected tools...`)
+  for (const name of activeTargets) {
+    // call existing sync logic for each target
+  }
+  return
+}
+```
+
+### Phase 5: Tests
+
+**Create `tests/detect-tools.test.ts`**
+
+- Test detection with mocked directories (create temp dirs, check detection)
+- Test `getDetectedTargetNames` returns only detected tools
+- Test empty detection returns empty array
+
+**Create `tests/gemini-sync.test.ts`**
+
+Follow `tests/sync-cursor.test.ts` pattern:
+
+- Test skills are symlinked to `.gemini/skills/`
+- Test MCP servers merged into `settings.json`
+- Test existing `settings.json` is backed up
+- Test empty skills/servers produce no output
+
+**Update `tests/cli.test.ts`**
+
+- Test `--to all` flag is accepted
+- Test `sync --target all` is accepted
+- Test `sync --target gemini` is accepted
+
+### Phase 6: Documentation
+
+**Update `README.md`:**
+
+Add to install section:
+```bash
+# auto-detect installed tools and install to all
+bunx @every-env/compound-plugin install compound-engineering --to all
+```
+
+Add to sync section:
+```bash
+# Sync to Gemini
+bunx @every-env/compound-plugin sync --target gemini
+
+# Sync to all detected tools
+bunx @every-env/compound-plugin sync --target all
+```
+
+## What We're NOT Doing
+
+- Not adding binary detection (`which cursor`, `which gemini`) — directory checks are sufficient and don't require shell execution
+- Not adding interactive prompts ("Install to Cursor? y/n") — auto-detect is fire-and-forget
+- Not adding `--exclude` flag for skipping specific targets — can use `--to X --also Y` for manual selection
+- Not adding Gemini to the `sync` symlink watcher (no watcher exists for any target)
+
+## Complexity Assessment
+
+**Low-medium change.** All patterns are established:
+- Detection utility is new but simple (pathExists checks)
+- Gemini sync follows cursor sync pattern exactly
+- `--to all` is plumbing — iterate detected tools through existing handlers
+- No new dependencies needed
+
+## References
+
+- Cursor sync (reference pattern): `src/sync/cursor.ts`
+- Gemini writer (merge pattern): `src/targets/gemini.ts`
+- Install command: `src/commands/install.ts`
+- Sync command: `src/commands/sync.ts`
+- File utilities: `src/utils/files.ts`
+- Symlink utilities: `src/utils/symlink.ts`
+
+## Completion Summary
+
+### What Was Delivered
+- Tool detection utility (`src/utils/detect-tools.ts`) with `detectInstalledTools()` and `getDetectedTargetNames()`
+- Gemini sync (`src/sync/gemini.ts`) following cursor sync pattern — symlinks skills, merges MCP servers into `settings.json`
+- `install --to all` and `convert --to all` auto-detect and install to all detected tools
+- `sync --target gemini` added to sync command
+- `sync --target all` syncs to all detected tools with summary output
+- 8 new tests across 2 test files (detect-tools + sync-gemini)
+
+### Implementation Statistics
+- 4 new files, 3 modified files
+- 139 tests passing (8 new + 131 existing)
+- No new dependencies
+
+### Git Commits
+- `e4d730d` feat: add detect-tools utility and Gemini sync with tests
+- `bc655f7` feat: wire --to all into install/convert and --target all/gemini into sync
+- `877e265` docs: add auto-detect and Gemini sync to README, bump to 0.8.0
+
+### Completion Details
+- **Completed By:** Claude Opus 4.6
+- **Date:** 2026-02-14
+- **Session:** Single session, TDD approach

docs/plans/2026-02-25-feat-windsurf-global-scope-support-plan.md

@@ -0,0 +1,627 @@
+---
+title: Windsurf Global Scope Support
+type: feat
+status: completed
+date: 2026-02-25
+deepened: 2026-02-25
+prior: docs/plans/2026-02-23-feat-add-windsurf-target-provider-plan.md (removed — superseded)
+---
+
+# Windsurf Global Scope Support
+
+## Post-Implementation Revisions (2026-02-26)
+
+After auditing the implementation against `docs/specs/windsurf.md`, two significant changes were made:
+
+1. **Agents → Skills (not Workflows)**: Claude agents map to Windsurf Skills (`skills/{name}/SKILL.md`), not Workflows. Skills are "complex multi-step tasks with supporting resources" — a better conceptual match for specialized expertise/personas. Workflows are "reusable step-by-step procedures" — a better match for Claude Commands (slash commands).
+
+2. **Workflows are flat files**: Command workflows are written to `global_workflows/{name}.md` (global scope) or `workflows/{name}.md` (workspace scope). No subdirectories — the spec requires flat files.
+
+3. **Content transforms updated**: `@agent-name` references are kept as-is (Windsurf skill invocation syntax). `/command` references produce `/{name}` (not `/commands/{name}`). `Task agent(args)` produces `Use the @agent-name skill: args`.
+
+### Final Component Mapping (per spec)
+
+| Claude Code | Windsurf | Output Path | Invocation |
+|---|---|---|---|
+| Agents (`.md`) | Skills | `skills/{name}/SKILL.md` | `@skill-name` or automatic |
+| Commands (`.md`) | Workflows (flat) | `global_workflows/{name}.md` (global) / `workflows/{name}.md` (workspace) | `/{workflow-name}` |
+| Skills (`SKILL.md`) | Skills (pass-through) | `skills/{name}/SKILL.md` | `@skill-name` |
+| MCP servers | `mcp_config.json` | `mcp_config.json` | N/A |
+| Hooks | Skipped with warning | N/A | N/A |
+| CLAUDE.md | Skipped | N/A | N/A |
+
+### Files Changed in Revision
+
+- `src/types/windsurf.ts` — `agentWorkflows` → `agentSkills: WindsurfGeneratedSkill[]`
+- `src/converters/claude-to-windsurf.ts` — `convertAgentToSkill()`, updated content transforms
+- `src/targets/windsurf.ts` — Skills written as `skills/{name}/SKILL.md`, flat workflows
+- Tests updated to match
+
+---
+
+## Enhancement Summary
+
+**Deepened on:** 2026-02-25
+**Research agents used:** architecture-strategist, kieran-typescript-reviewer, security-sentinel, code-simplicity-reviewer, pattern-recognition-specialist
+**External research:** Windsurf MCP docs, Windsurf tutorial docs
+
+### Key Improvements from Deepening
+1. **HTTP/SSE servers should be INCLUDED** — Windsurf supports all 3 transport types (stdio, Streamable HTTP, SSE). Original plan incorrectly skipped them.
+2. **File permissions: use `0o600`** — `mcp_config.json` contains secrets and must not be world-readable. Add secure write support.
+3. **Extract `resolveTargetOutputRoot` to shared utility** — both commands duplicate this; adding scope makes it worse. Extract first.
+4. **Bug fix: missing `result[name] = entry`** — all 5 review agents caught a copy-paste bug in the `buildMcpConfig` sample code.
+5. **`hasPotentialSecrets` to shared utility** — currently in sync.ts, would be duplicated. Extract to `src/utils/secrets.ts`.
+6. **Windsurf `mcp_config.json` is global-only** — per Windsurf docs, no per-project MCP config support. Workspace scope writes it for forward-compatibility but emit a warning.
+7. **Windsurf supports `${env:VAR}` interpolation** — consider writing env var references instead of literal values for secrets.
+
+### New Considerations Discovered
+- Backup files accumulate with secrets and are never cleaned up — cap at 3 backups
+- Workspace `mcp_config.json` could be committed to git — warn about `.gitignore`
+- `WindsurfMcpServerEntry` type needs `serverUrl` field for HTTP/SSE servers
+- Simplicity reviewer recommends handling scope as windsurf-specific in CLI rather than generic `TargetHandler` fields — but brainstorm explicitly chose "generic with windsurf as first adopter". **Decision: keep generic approach** per user's brainstorm decision, with JSDoc documenting the relationship between `defaultScope` and `supportedScopes`.
+
+---
+
+## Overview
+
+Add a generic `--scope global|workspace` flag to the converter CLI with Windsurf as the first adopter. Global scope writes to `~/.codeium/windsurf/`, making workflows, skills, and MCP servers available across all projects. This also upgrades MCP handling from a human-readable setup doc (`mcp-setup.md`) to a proper machine-readable config (`mcp_config.json`), and removes AGENTS.md generation (the plugin's CLAUDE.md contains development-internal instructions, not user-facing content).
+
+## Problem Statement / Motivation
+
+The current Windsurf converter (v0.10.0) writes everything to project-level `.windsurf/`, requiring re-installation per project. Windsurf supports global paths for skills (`~/.codeium/windsurf/skills/`) and MCP config (`~/.codeium/windsurf/mcp_config.json`). Users should install once and get capabilities everywhere.
+
+Additionally, the v0.10.0 MCP output was a markdown setup guide — not an actual integration. Windsurf reads `mcp_config.json` directly, so we should write to that file.
+
+## Breaking Changes from v0.10.0
+
+This is a **minor version bump** (v0.11.0) with intentional breaking changes to the experimental Windsurf target:
+
+1. **Default output location changed** — `--to windsurf` now defaults to global scope (`~/.codeium/windsurf/`). Use `--scope workspace` for the old behavior.
+2. **AGENTS.md no longer generated** — old files are left in place (not deleted).
+3. **`mcp-setup.md` replaced by `mcp_config.json`** — proper machine-readable integration. Old files left in place.
+4. **Env var secrets included with warning** — previously redacted, now included (required for the config file to work).
+5. **`--output` semantics changed** — `--output` now specifies the direct target directory (not a parent where `.windsurf/` is created).
+
+## Proposed Solution
+
+### Phase 0: Extract Shared Utilities (prerequisite)
+
+**Files:** `src/utils/resolve-output.ts` (new), `src/utils/secrets.ts` (new)
+
+#### 0a. Extract `resolveTargetOutputRoot` to shared utility
+
+Both `install.ts` and `convert.ts` have near-identical `resolveTargetOutputRoot` functions that are already diverging (`hasExplicitOutput` exists in install.ts but not convert.ts). Adding scope would make the duplication worse.
+
+- [x] Create `src/utils/resolve-output.ts` with a unified function:
+
+```typescript
+import os from "os"
+import path from "path"
+import type { TargetScope } from "../targets"
+
+export function resolveTargetOutputRoot(options: {
+  targetName: string
+  outputRoot: string
+  codexHome: string
+  piHome: string
+  hasExplicitOutput: boolean
+  scope?: TargetScope
+}): string {
+  const { targetName, outputRoot, codexHome, piHome, hasExplicitOutput, scope } = options
+  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")
+  }
+  if (targetName === "copilot") {
+    const base = hasExplicitOutput ? outputRoot : process.cwd()
+    return path.join(base, ".github")
+  }
+  if (targetName === "kiro") {
+    const base = hasExplicitOutput ? outputRoot : process.cwd()
+    return path.join(base, ".kiro")
+  }
+  if (targetName === "windsurf") {
+    if (hasExplicitOutput) return outputRoot
+    if (scope === "global") return path.join(os.homedir(), ".codeium", "windsurf")
+    return path.join(process.cwd(), ".windsurf")
+  }
+  return outputRoot
+}
+```
+
+- [x] Update `install.ts` to import and call `resolveTargetOutputRoot` from shared utility
+- [x] Update `convert.ts` to import and call `resolveTargetOutputRoot` from shared utility
+- [x] Add `hasExplicitOutput` tracking to `convert.ts` (currently missing)
+
+### Research Insights (Phase 0)
+
+**Architecture review:** Both commands will call the same function with the same signature. This eliminates the divergence and ensures scope resolution has a single source of truth. The `--also` loop in both commands also uses this function with `handler.defaultScope`.
+
+**Pattern review:** This follows the same extraction pattern as `resolveTargetHome` in `src/utils/resolve-home.ts`.
+
+#### 0b. Extract `hasPotentialSecrets` to shared utility
+
+Currently in `sync.ts:20-31`. The same regex pattern also appears in `claude-to-windsurf.ts:223` as `redactEnvValue`. Extract to avoid a third copy.
+
+- [x] Create `src/utils/secrets.ts`:
+
+```typescript
+const SENSITIVE_PATTERN = /key|token|secret|password|credential|api_key/i
+
+export function hasPotentialSecrets(
+  servers: Record<string, { env?: Record<string, string> }>,
+): boolean {
+  for (const server of Object.values(servers)) {
+    if (server.env) {
+      for (const key of Object.keys(server.env)) {
+        if (SENSITIVE_PATTERN.test(key)) return true
+      }
+    }
+  }
+  return false
+}
+```
+
+- [x] Update `sync.ts` to import from shared utility
+- [x] Use in new windsurf converter
+
+### Phase 1: Types and TargetHandler
+
+**Files:** `src/types/windsurf.ts`, `src/targets/index.ts`
+
+#### 1a. Update WindsurfBundle type
+
+```typescript
+// src/types/windsurf.ts
+export type WindsurfMcpServerEntry = {
+  command?: string
+  args?: string[]
+  env?: Record<string, string>
+  serverUrl?: string
+  headers?: Record<string, string>
+}
+
+export type WindsurfMcpConfig = {
+  mcpServers: Record<string, WindsurfMcpServerEntry>
+}
+
+export type WindsurfBundle = {
+  agentWorkflows: WindsurfWorkflow[]
+  commandWorkflows: WindsurfWorkflow[]
+  skillDirs: WindsurfSkillDir[]
+  mcpConfig: WindsurfMcpConfig | null
+}
+```
+
+- [x] Remove `agentsMd: string | null`
+- [x] Replace `mcpSetupDoc: string | null` with `mcpConfig: WindsurfMcpConfig | null`
+- [x] Add `WindsurfMcpServerEntry` (supports both stdio and HTTP/SSE) and `WindsurfMcpConfig` types
+
+### Research Insights (Phase 1a)
+
+**Windsurf docs confirm** three transport types: stdio (`command` + `args`), Streamable HTTP (`serverUrl`), and SSE (`serverUrl` or `url`). The `WindsurfMcpServerEntry` type must support all three — making `command` optional and adding `serverUrl` and `headers` fields.
+
+**TypeScript reviewer:** Consider making `WindsurfMcpServerEntry` a discriminated union if strict typing is desired. However, since this mirrors JSON config structure, a flat type with optional fields is pragmatically simpler.
+
+#### 1b. Add TargetScope to TargetHandler
+
+```typescript
+// src/targets/index.ts
+export type TargetScope = "global" | "workspace"
+
+export type TargetHandler<TBundle = unknown> = {
+  name: string
+  implemented: boolean
+  /**
+   * Default scope when --scope is not provided.
+   * Only meaningful when supportedScopes is defined.
+   * Falls back to "workspace" if absent.
+   */
+  defaultScope?: TargetScope
+  /** Valid scope values. If absent, the --scope flag is rejected for this target. */
+  supportedScopes?: TargetScope[]
+  convert: (plugin: ClaudePlugin, options: ClaudeToOpenCodeOptions) => TBundle | null
+  write: (outputRoot: string, bundle: TBundle) => Promise<void>
+}
+```
+
+- [x] Add `TargetScope` type export
+- [x] Add `defaultScope?` and `supportedScopes?` to `TargetHandler` with JSDoc
+- [x] Set windsurf target: `defaultScope: "global"`, `supportedScopes: ["global", "workspace"]`
+- [x] No changes to other targets (they have no scope fields, flag is ignored)
+
+### Research Insights (Phase 1b)
+
+**Simplicity review:** Argued this is premature generalization (only 1 of 8 targets uses scopes). Recommended handling scope as windsurf-specific with `if (targetName !== "windsurf")` guard instead. **Decision: keep generic approach** per brainstorm decision "Generic with windsurf as first adopter", but add JSDoc documenting the invariant.
+
+**TypeScript review:** Suggested a `ScopeConfig` grouped object to prevent `defaultScope` without `supportedScopes`. The JSDoc approach is simpler and sufficient for now.
+
+**Architecture review:** Adding optional fields to `TargetHandler` follows Open/Closed Principle — existing targets are unaffected. Clean extension.
+
+### Phase 2: Converter Changes
+
+**Files:** `src/converters/claude-to-windsurf.ts`
+
+#### 2a. Remove AGENTS.md generation
+
+- [x] Remove `buildAgentsMd()` function
+- [x] Remove `agentsMd` from return value
+
+#### 2b. Replace MCP setup doc with MCP config
+
+- [x] Remove `buildMcpSetupDoc()` function
+- [x] Remove `redactEnvValue()` helper
+- [x] Add `buildMcpConfig()` that returns `WindsurfMcpConfig | null`
+- [x] Include **all** env vars (including secrets) — no redaction
+- [x] Use shared `hasPotentialSecrets()` from `src/utils/secrets.ts`
+- [x] Include **both** stdio and HTTP/SSE servers (Windsurf supports all transport types)
+
+```typescript
+function buildMcpConfig(
+  servers?: Record<string, ClaudeMcpServer>,
+): WindsurfMcpConfig | null {
+  if (!servers || Object.keys(servers).length === 0) return null
+
+  const result: Record<string, WindsurfMcpServerEntry> = {}
+  for (const [name, server] of Object.entries(servers)) {
+    if (server.command) {
+      // stdio transport
+      const entry: WindsurfMcpServerEntry = { command: server.command }
+      if (server.args?.length) entry.args = server.args
+      if (server.env && Object.keys(server.env).length > 0) entry.env = server.env
+      result[name] = entry
+    } else if (server.url) {
+      // HTTP/SSE transport
+      const entry: WindsurfMcpServerEntry = { serverUrl: server.url }
+      if (server.headers && Object.keys(server.headers).length > 0) entry.headers = server.headers
+      if (server.env && Object.keys(server.env).length > 0) entry.env = server.env
+      result[name] = entry
+    } else {
+      console.warn(`Warning: MCP server "${name}" has no command or URL. Skipping.`)
+      continue
+    }
+  }
+
+  if (Object.keys(result).length === 0) return null
+
+  // Warn about secrets (don't redact — they're needed for the config to work)
+  if (hasPotentialSecrets(result)) {
+    console.warn(
+      "Warning: MCP servers contain env vars that may include secrets (API keys, tokens).\n" +
+      "   These will be written to mcp_config.json. Review before sharing the config file.",
+    )
+  }
+
+  return { mcpServers: result }
+}
+```
+
+### Research Insights (Phase 2)
+
+**Windsurf docs (critical correction):** Windsurf supports **stdio, Streamable HTTP, and SSE** transports in `mcp_config.json`. HTTP/SSE servers use `serverUrl` (not `url`). The original plan incorrectly planned to skip HTTP/SSE servers. This is now corrected — all transport types are included.
+
+**All 5 review agents flagged:** The original code sample was missing `result[name] = entry` — the entry was built but never stored. Fixed above.
+
+**Security review:** The warning message should enumerate which specific env var names triggered detection. Enhanced version:
+
+```typescript
+if (hasPotentialSecrets(result)) {
+  const flagged = Object.entries(result)
+    .filter(([, s]) => s.env && Object.keys(s.env).some(k => SENSITIVE_PATTERN.test(k)))
+    .map(([name]) => name)
+  console.warn(
+    `Warning: MCP servers contain env vars that may include secrets: ${flagged.join(", ")}.\n` +
+    "   These will be written to mcp_config.json. Review before sharing the config file.",
+  )
+}
+```
+
+**Windsurf env var interpolation:** Windsurf supports `${env:VARIABLE_NAME}` syntax in `mcp_config.json`. Future enhancement: write env var references instead of literal values for secrets. Out of scope for v0.11.0 (requires more research on which fields support interpolation).
+
+### Phase 3: Writer Changes
+
+**Files:** `src/targets/windsurf.ts`, `src/utils/files.ts`
+
+#### 3a. Simplify writer — remove AGENTS.md and double-nesting guard
+
+The writer always writes directly into `outputRoot`. The CLI resolves the correct output root based on scope.
+
+- [x] Remove AGENTS.md writing block (lines 10-17)
+- [x] Remove `resolveWindsurfPaths()` — no longer needed
+- [x] Write workflows, skills, and MCP config directly into `outputRoot`
+
+### Research Insights (Phase 3a)
+
+**Pattern review (dissent):** Every other writer (kiro, copilot, gemini, droid) has a `resolve*Paths()` function with a double-nesting guard. Removing it makes Windsurf the only target where the CLI fully owns nesting. This creates an inconsistency in the `write()` contract.
+
+**Resolution:** Accept the divergence — Windsurf has genuinely different semantics (global vs workspace). Add a JSDoc comment on `TargetHandler.write()` documenting that some writers may apply additional nesting while the Windsurf writer expects the final resolved path. Long-term, other targets could migrate to this pattern in a separate refactor.
+
+#### 3b. Replace MCP setup doc with JSON config merge
+
+Follow Kiro pattern (`src/targets/kiro.ts:68-92`) with security hardening:
+
+- [x] Read existing `mcp_config.json` if present
+- [x] Backup before overwrite (`backupFile()`)
+- [x] Parse existing JSON (warn and replace if corrupted; add `!Array.isArray()` guard)
+- [x] Merge at `mcpServers` key: plugin entries overwrite same-name entries, user entries preserved
+- [x] Preserve all other top-level keys in existing file
+- [x] Write merged result with **restrictive permissions** (`0o600`)
+- [x] Emit warning when writing to workspace scope (Windsurf `mcp_config.json` is global-only per docs)
+
+```typescript
+// MCP config merge with security hardening
+if (bundle.mcpConfig) {
+  const mcpPath = path.join(outputRoot, "mcp_config.json")
+  const backupPath = await backupFile(mcpPath)
+  if (backupPath) {
+    console.log(`Backed up existing mcp_config.json to ${backupPath}`)
+  }
+
+  let existingConfig: Record<string, unknown> = {}
+  if (await pathExists(mcpPath)) {
+    try {
+      const parsed = await readJson<unknown>(mcpPath)
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        existingConfig = parsed as Record<string, unknown>
+      }
+    } catch {
+      console.warn("Warning: existing mcp_config.json could not be parsed and will be replaced.")
+    }
+  }
+
+  const existingServers =
+    existingConfig.mcpServers &&
+    typeof existingConfig.mcpServers === "object" &&
+    !Array.isArray(existingConfig.mcpServers)
+      ? (existingConfig.mcpServers as Record<string, unknown>)
+      : {}
+  const merged = { ...existingConfig, mcpServers: { ...existingServers, ...bundle.mcpConfig.mcpServers } }
+  await writeJsonSecure(mcpPath, merged)  // 0o600 permissions
+}
+```
+
+### Research Insights (Phase 3b)
+
+**Security review (HIGH):** The current `writeJson()` in `src/utils/files.ts` uses default umask (`0o644`) — world-readable. The sync targets all use `{ mode: 0o600 }` for secret-containing files. The Windsurf writer (and Kiro writer) must do the same.
+
+**Implementation:** Add a `writeJsonSecure()` helper or add a `mode` parameter to `writeJson()`:
+
+```typescript
+// src/utils/files.ts
+export async function writeJsonSecure(filePath: string, data: unknown): Promise<void> {
+  const content = JSON.stringify(data, null, 2)
+  await ensureDir(path.dirname(filePath))
+  await fs.writeFile(filePath, content + "\n", { encoding: "utf8", mode: 0o600 })
+}
+```
+
+**Security review (MEDIUM):** Backup files inherit default permissions. Ensure `backupFile()` also sets `0o600` on the backup copy when the source may contain secrets.
+
+**Security review (MEDIUM):** Workspace `mcp_config.json` could be committed to git. After writing to workspace scope, emit a warning:
+
+```
+Warning: .windsurf/mcp_config.json may contain secrets. Ensure it is in .gitignore.
+```
+
+**TypeScript review:** The `readJson<Record<string, unknown>>` assertion is unsafe — a valid JSON array or string passes parsing but fails the type. Added `!Array.isArray()` guard.
+
+**TypeScript review:** The `bundle.mcpConfig` null check is sufficient — when non-null, `mcpServers` is guaranteed to have entries (the converter returns null for empty servers). Simplified from `bundle.mcpConfig && Object.keys(...)`.
+
+**Windsurf docs (important):** `mcp_config.json` is a **global configuration only** — Windsurf has no per-project MCP config support. Writing it to `.windsurf/` in workspace scope may not be discovered by Windsurf. Emit a warning for workspace scope but still write the file for forward-compatibility.
+
+#### 3c. Updated writer structure
+
+```typescript
+export async function writeWindsurfBundle(outputRoot: string, bundle: WindsurfBundle): Promise<void> {
+  await ensureDir(outputRoot)
+
+  // Write agent workflows
+  if (bundle.agentWorkflows.length > 0) {
+    const agentDir = path.join(outputRoot, "workflows", "agents")
+    await ensureDir(agentDir)
+    for (const workflow of bundle.agentWorkflows) {
+      validatePathSafe(workflow.name, "agent workflow")
+      const content = formatFrontmatter({ description: workflow.description }, `# ${workflow.name}\n\n${workflow.body}`)
+      await writeText(path.join(agentDir, `${workflow.name}.md`), content + "\n")
+    }
+  }
+
+  // Write command workflows
+  if (bundle.commandWorkflows.length > 0) {
+    const cmdDir = path.join(outputRoot, "workflows", "commands")
+    await ensureDir(cmdDir)
+    for (const workflow of bundle.commandWorkflows) {
+      validatePathSafe(workflow.name, "command workflow")
+      const content = formatFrontmatter({ description: workflow.description }, `# ${workflow.name}\n\n${workflow.body}`)
+      await writeText(path.join(cmdDir, `${workflow.name}.md`), content + "\n")
+    }
+  }
+
+  // Copy skill directories
+  if (bundle.skillDirs.length > 0) {
+    const skillsDir = path.join(outputRoot, "skills")
+    await ensureDir(skillsDir)
+    for (const skill of bundle.skillDirs) {
+      validatePathSafe(skill.name, "skill directory")
+      const destDir = path.join(skillsDir, skill.name)
+      const resolvedDest = path.resolve(destDir)
+      if (!resolvedDest.startsWith(path.resolve(skillsDir))) {
+        console.warn(`Warning: Skill name "${skill.name}" escapes skills/. Skipping.`)
+        continue
+      }
+      await copyDir(skill.sourceDir, destDir)
+    }
+  }
+
+  // Merge MCP config (see 3b above)
+  if (bundle.mcpConfig) {
+    // ... merge logic from 3b
+  }
+}
+```
+
+### Phase 4: CLI Wiring
+
+**Files:** `src/commands/install.ts`, `src/commands/convert.ts`
+
+#### 4a. Add `--scope` flag to both commands
+
+```typescript
+scope: {
+  type: "string",
+  description: "Scope level: global | workspace (default varies by target)",
+},
+```
+
+- [x] Add `scope` arg to `install.ts`
+- [x] Add `scope` arg to `convert.ts`
+
+#### 4b. Validate scope with type guard
+
+Use a proper type guard instead of unsafe `as TargetScope` cast:
+
+```typescript
+function isTargetScope(value: string): value is TargetScope {
+  return value === "global" || value === "workspace"
+}
+
+const scopeValue = args.scope ? String(args.scope) : undefined
+if (scopeValue !== undefined) {
+  if (!target.supportedScopes) {
+    throw new Error(`Target "${targetName}" does not support the --scope flag.`)
+  }
+  if (!isTargetScope(scopeValue) || !target.supportedScopes.includes(scopeValue)) {
+    throw new Error(`Target "${targetName}" does not support --scope ${scopeValue}. Supported: ${target.supportedScopes.join(", ")}`)
+  }
+}
+const resolvedScope = scopeValue ?? target.defaultScope ?? "workspace"
+```
+
+- [x] Add `isTargetScope` type guard
+- [x] Add scope validation in both commands (single block, not two separate checks)
+
+### Research Insights (Phase 4b)
+
+**TypeScript review:** The original plan cast `scopeValue as TargetScope` before validation — a type lie. Use a proper type guard function to keep the type system honest.
+
+**Simplicity review:** The two-step validation (check supported, then check exists) can be a single block with the type guard approach above.
+
+#### 4c. Update output root resolution
+
+Both commands now use the shared `resolveTargetOutputRoot` from Phase 0a.
+
+- [x] Call shared function with `scope: resolvedScope` for primary target
+- [x] Default scope: `target.defaultScope ?? "workspace"` (only used when target supports scopes)
+
+#### 4d. Handle `--also` targets
+
+`--scope` applies only to the primary `--to` target. Extra `--also` targets use their own `defaultScope`.
+
+- [x] Pass `handler.defaultScope` for `--also` targets (each uses its own default)
+- [x] Update the `--also` loop in both commands to use target-specific scope resolution
+
+### Research Insights (Phase 4d)
+
+**Architecture review:** There is no way for users to specify scope for an `--also` target (e.g., `--also windsurf:workspace`). Accept as a known v0.11.0 limitation. If users need workspace scope for windsurf, they can run two separate commands. Add a code comment indicating where per-target scope overrides would be added in the future.
+
+### Phase 5: Tests
+
+**Files:** `tests/windsurf-converter.test.ts`, `tests/windsurf-writer.test.ts`
+
+#### 5a. Update converter tests
+
+- [x] Remove all AGENTS.md tests (lines 275-303: empty plugin, CLAUDE.md missing)
+- [x] Remove all `mcpSetupDoc` tests (lines 305-366: stdio, HTTP/SSE, redaction, null)
+- [x] Update `fixturePlugin` default — remove `agentsMd` and `mcpSetupDoc` references
+- [x] Add `mcpConfig` tests:
+  - stdio server produces correct JSON structure with `command`, `args`, `env`
+  - HTTP/SSE server produces correct JSON structure with `serverUrl`, `headers`
+  - mixed servers (stdio + HTTP) both included
+  - env vars included (not redacted) — verify actual values present
+  - `hasPotentialSecrets()` emits console.warn for sensitive keys
+  - `hasPotentialSecrets()` does NOT warn when no sensitive keys
+  - no servers produces null mcpConfig
+  - empty bundle has null mcpConfig
+  - server with no command and no URL is skipped with warning
+
+#### 5b. Update writer tests
+
+- [x] Remove AGENTS.md tests (backup test, creation test, double-nesting AGENTS.md parent test)
+- [x] Remove double-nesting guard test (guard removed)
+- [x] Remove `mcp-setup.md` write test
+- [x] Update `emptyBundle` fixture — remove `agentsMd`, `mcpSetupDoc`, add `mcpConfig: null`
+- [x] Add `mcp_config.json` tests:
+  - writes mcp_config.json to outputRoot
+  - merges with existing mcp_config.json (preserves user servers)
+  - backs up existing mcp_config.json before overwrite
+  - handles corrupted existing mcp_config.json (warn and replace)
+  - handles existing mcp_config.json with array (not object) at root
+  - handles existing mcp_config.json with `mcpServers: null`
+  - preserves non-mcpServers keys in existing file
+  - server name collision: plugin entry wins
+  - file permissions are 0o600 (not world-readable)
+- [x] Update full bundle test — writer writes directly into outputRoot (no `.windsurf/` nesting)
+
+#### 5c. Add scope resolution tests
+
+Test the shared `resolveTargetOutputRoot` function:
+
+- [x] Default scope for windsurf is "global" → resolves to `~/.codeium/windsurf/`
+- [x] Explicit `--scope workspace` → resolves to `cwd/.windsurf/`
+- [x] `--output` overrides scope resolution (both global and workspace)
+- [x] Invalid scope value for windsurf → error
+- [x] `--scope` on non-scope target (e.g., opencode) → error
+- [x] `--also windsurf` uses windsurf's default scope ("global")
+- [x] `isTargetScope` type guard correctly identifies valid/invalid values
+
+### Phase 6: Documentation
+
+**Files:** `README.md`, `CHANGELOG.md`
+
+- [x] Update README.md Windsurf section to mention `--scope` flag and global default
+- [x] Add CHANGELOG entry for v0.11.0 with breaking changes documented
+- [x] Document migration path: `--scope workspace` for old behavior
+- [x] Note that Windsurf `mcp_config.json` is global-only (workspace MCP config may not be discovered)
+
+## Acceptance Criteria
+
+- [x] `install compound-engineering --to windsurf` writes to `~/.codeium/windsurf/` by default
+- [x] `install compound-engineering --to windsurf --scope workspace` writes to `cwd/.windsurf/`
+- [x] `--output /custom/path` overrides scope for both commands
+- [x] `--scope` on non-supporting target produces clear error
+- [x] `mcp_config.json` merges with existing file (backup created, user entries preserved)
+- [x] `mcp_config.json` written with `0o600` permissions (not world-readable)
+- [x] No AGENTS.md generated for either scope
+- [x] Env var secrets included in `mcp_config.json` with `console.warn` listing affected servers
+- [x] Both stdio and HTTP/SSE MCP servers included in `mcp_config.json`
+- [x] All existing tests updated, all new tests pass
+- [x] No regressions in other targets
+- [x] `resolveTargetOutputRoot` extracted to shared utility (no duplication)
+
+## Dependencies & Risks
+
+**Risk: Global workflow path is undocumented.** Windsurf may not discover workflows from `~/.codeium/windsurf/workflows/`. Mitigation: documented as a known assumption in the brainstorm. Users can `--scope workspace` if global workflows aren't discovered.
+
+**Risk: Breaking changes for existing v0.10.0 users.** Mitigation: document migration path clearly. `--scope workspace` restores previous behavior. Target is experimental with a small user base.
+
+**Risk: Workspace `mcp_config.json` not read by Windsurf.** Per Windsurf docs, `mcp_config.json` is global-only configuration. Workspace scope writes the file for forward-compatibility but emits a warning. The primary use case is global scope anyway.
+
+**Risk: Secrets in `mcp_config.json` committed to git.** Mitigation: `0o600` file permissions, console.warn about sensitive env vars, warning about `.gitignore` for workspace scope.
+
+## References & Research
+
+- Spec: `docs/specs/windsurf.md` (authoritative reference for component mapping)
+- Kiro MCP merge pattern: [src/targets/kiro.ts:68-92](../../src/targets/kiro.ts)
+- Sync secrets warning: [src/commands/sync.ts:20-28](../../src/commands/sync.ts)
+- Windsurf MCP docs: https://docs.windsurf.com/windsurf/cascade/mcp
+- Windsurf Skills global path: https://docs.windsurf.com/windsurf/cascade/skills
+- Windsurf MCP tutorial: https://windsurf.com/university/tutorials/configuring-first-mcp-server
+- Adding converter targets (learning): [docs/solutions/adding-converter-target-providers.md](../solutions/adding-converter-target-providers.md)
+- Plugin versioning (learning): [docs/solutions/plugin-versioning-requirements.md](../solutions/plugin-versioning-requirements.md)

docs/plans/2026-03-01-feat-ce-command-aliases-backwards-compatible-deprecation-plan.md

@@ -0,0 +1,261 @@
+---
+title: "feat: Add ce:* command aliases with backwards-compatible deprecation of workflows:*"
+type: feat
+status: complete
+date: 2026-03-01
+---
+
+# feat: Add `ce:*` Command Aliases with Backwards-Compatible Deprecation of `workflows:*`
+
+## Overview
+
+Rename the five `workflows:*` commands to `ce:*` to make it clearer they belong to compound-engineering. Keep `workflows:*` working as thin deprecation wrappers that warn users and forward to the new commands.
+
+## Problem Statement / Motivation
+
+The current `workflows:plan`, `workflows:work`, `workflows:review`, `workflows:brainstorm`, and `workflows:compound` commands are prefixed with `workflows:` — a generic namespace that doesn't signal their origin. Users don't immediately associate them with the compound-engineering plugin.
+
+The `ce:` prefix is shorter, more memorable, and unambiguously identifies these as compound-engineering commands — consistent with how other plugin commands already use `compound-engineering:` as a namespace.
+
+## Proposed Solution
+
+### 1. Create New `ce:*` Commands (Primary)
+
+Create a `commands/ce/` directory with five new command files. Each file gets the full implementation content from the current `workflows:*` counterpart, with the `name:` frontmatter updated to the new name.
+
+| New Command | Source Content |
+|-------------|---------------|
+| `ce:plan` | `commands/workflows/plan.md` |
+| `ce:work` | `commands/workflows/work.md` |
+| `ce:review` | `commands/workflows/review.md` |
+| `ce:brainstorm` | `commands/workflows/brainstorm.md` |
+| `ce:compound` | `commands/workflows/compound.md` |
+
+### 2. Convert `workflows:*` to Deprecation Wrappers (Backwards Compatibility)
+
+Replace the full content of each `workflows:*` command with a thin wrapper that:
+1. Displays a visible deprecation warning to the user
+2. Invokes the new `ce:*` command with the same `$ARGUMENTS`
+
+Example wrapper body:
+
+```markdown
+---
+name: workflows:plan
+description: "[DEPRECATED] Use /ce:plan instead. Renamed for clarity."
+argument-hint: "[feature description]"
+---
+
+> ⚠️ **Deprecated:** `/workflows:plan` has been renamed to `/ce:plan`.
+> Please update your workflow to use `/ce:plan` instead.
+> This alias will be removed in a future version.
+
+/ce:plan $ARGUMENTS
+```
+
+### 3. Update All Internal References
+
+The grep reveals `workflows:*` is referenced in **many more places** than just `lfg`/`slfg`. All of these must be updated to point to the new `ce:*` names:
+
+**Orchestration commands (update to new names):**
+- `commands/lfg.md` — `/workflows:plan`, `/workflows:work`, `/workflows:review`
+- `commands/slfg.md` — `/workflows:plan`, `/workflows:work`, `/workflows:review`
+
+**Command bodies that cross-reference (update to new names):**
+- `commands/workflows/brainstorm.md` — references `/workflows:plan` multiple times (will be in the deprecated wrapper, so should forward to `/ce:plan`)
+- `commands/workflows/compound.md` — self-references and references `/workflows:plan`
+- `commands/workflows/plan.md` — references `/workflows:work` multiple times
+- `commands/deepen-plan.md` — references `/workflows:work`, `/workflows:compound`
+
+**Agents (update to new names):**
+- `agents/review/code-simplicity-reviewer.md` — references `/workflows:plan` and `/workflows:work`
+- `agents/research/git-history-analyzer.md` — references `/workflows:plan`
+- `agents/research/learnings-researcher.md` — references `/workflows:plan`
+
+**Skills (update to new names):**
+- `skills/document-review/SKILL.md` — references `/workflows:brainstorm`, `/workflows:plan`
+- `skills/git-worktree/SKILL.md` — references `/workflows:review`, `/workflows:work` extensively
+- `skills/ce-setup/SKILL.md` — references `/workflows:review`, `/workflows:work`
+- `skills/brainstorming/SKILL.md` — references `/workflows:plan` multiple times
+- `skills/file-todos/SKILL.md` — references `/workflows:review`
+
+**Other commands (update to new names):**
+- `commands/test-xcode.md` — references `/workflows:review`
+
+**Historical docs (leave as-is — they document the old names intentionally):**
+- `docs/plans/*.md` — old plan files, historical record
+- `docs/brainstorms/*.md` — historical
+- `docs/solutions/*.md` — historical
+- `tests/fixtures/` — test fixtures for the converter (intentionally use `workflows:*` to test namespace handling)
+- `CHANGELOG.md` historical entries — don't rewrite history
+
+### 4. Update Documentation
+
+- `CHANGELOG.md` — add new entry documenting the rename and deprecation
+- `plugins/compound-engineering/README.md` — update command table to list `ce:*` as primary, note `workflows:*` as deprecated aliases
+- `plugins/compound-engineering/CLAUDE.md` — update command listing and the "Why `workflows:`?" section
+- Root `README.md` — update the command table (lines 133–136)
+
+### 5. Converter / bunx Install Script Considerations
+
+The `bunx` install script (`src/commands/install.ts`) **only writes files, never deletes them**. This has two implications:
+
+**Now (while deprecated wrappers exist):** No stale file problem. Running `bunx install compound-engineering --to gemini` after this change will:
+- Write `commands/ce/plan.toml` (new primary)
+- Write `commands/workflows/plan.toml` (deprecated wrapper, with deprecation content)
+
+Both coexist correctly. Users who re-run install get both.
+
+**Future (when deprecated wrappers are eventually removed):** The old `commands/workflows/` files will remain stale in users' converted targets. At that point, a cleanup step will be needed — either:
+- Manual instructions: "Delete `.gemini/commands/workflows/` after upgrading"
+- OR add a cleanup pass to the install script that removes known-renamed command directories
+
+For now, document in the plan that stale cleanup is a known future concern when `workflows:*` wrappers are eventually dropped.
+
+## Technical Considerations
+
+### Command Naming
+
+The `ce:` prefix maps to a `commands/ce/` directory. This follows the existing convention where `workflows:plan` maps to `commands/workflows/plan.md`.
+
+### Deprecation Warning Display
+
+Since commands are executed by Claude, the deprecation message in the wrapper body will be displayed to the user as Claude's response before the new command runs. The `>` blockquote markdown renders as a styled callout.
+
+The deprecated wrappers should **not** use `disable-model-invocation: true` — Claude needs to process the body to display the warning and invoke the new command.
+
+### Deprecation Wrapper Mechanism
+
+The deprecated wrappers **must** use `disable-model-invocation: true`. This is the same mechanism `lfg.md` uses — the CLI runtime parses the body and executes slash command invocations directly. Without it, Claude reads the body as text and cannot actually invoke `/ce:plan`.
+
+The deprecation notice in the wrapper body becomes a printed note (same as `lfg` step descriptions), not a styled Claude response. That's acceptable — it still communicates the message.
+
+### Context Token Budget
+
+The 5 new `ce:*` commands add descriptions to the context budget. Keep descriptions short (under 120 chars). The 5 deprecated `workflows:*` wrappers have minimal descriptions (tagged as deprecated) to minimize budget impact.
+
+### Count Impact
+
+Command count remains 22 (5 new `ce:*` + 5 updated `workflows:*` wrappers = net zero change). No version bump required for counts.
+
+## Acceptance Criteria
+
+- [ ] `commands/ce/` directory created with 5 new command files
+- [ ] Each `ce:*` command has the full implementation from its `workflows:*` counterpart
+- [ ] Each `ce:*` command frontmatter `name:` field set to `ce:plan`, `ce:work`, etc.
+- [ ] Each `workflows:*` command replaced with a thin deprecation wrapper
+- [ ] Deprecation wrapper shows a clear ⚠️ warning with the new command name
+- [ ] Deprecation wrapper invokes the new `ce:*` command with `$ARGUMENTS`
+- [ ] `lfg.md` updated to use `ce:plan`, `ce:work`, `ce:review`
+- [ ] `slfg.md` updated to use `ce:plan`, `ce:work`, `ce:review`
+- [ ] All agent `.md` files updated (code-simplicity-reviewer, git-history-analyzer, learnings-researcher)
+- [ ] All skill `SKILL.md` files updated (document-review, git-worktree, setup, brainstorming, file-todos)
+- [ ] `commands/deepen-plan.md` and `commands/test-xcode.md` updated
+- [ ] `CHANGELOG.md` updated with deprecation notice
+- [ ] `plugins/compound-engineering/README.md` command table updated
+- [ ] `plugins/compound-engineering/CLAUDE.md` command listing updated
+- [ ] Root `README.md` command table updated
+- [ ] Validate: `/ce:plan "test feature"` works end-to-end
+- [ ] Validate: `/workflows:plan "test feature"` shows deprecation warning and continues
+- [ ] Re-run `bunx install compound-engineering --to [target]` and confirm both `ce/` and `workflows/` output dirs are written correctly
+
+## Implementation Steps
+
+### Step 1: Create `commands/ce/` directory with 5 new files
+
+For each command, copy the source file and update only the `name:` frontmatter field:
+
+- `commands/ce/plan.md` — copy `commands/workflows/plan.md`, set `name: ce:plan`
+- `commands/ce/work.md` — copy `commands/workflows/work.md`, set `name: ce:work`
+- `commands/ce/review.md` — copy `commands/workflows/review.md`, set `name: ce:review`
+- `commands/ce/brainstorm.md` — copy `commands/workflows/brainstorm.md`, set `name: ce:brainstorm`
+- `commands/ce/compound.md` — copy `commands/workflows/compound.md`, set `name: ce:compound`
+
+### Step 2: Replace `commands/workflows/*.md` with deprecation wrappers
+
+Use `disable-model-invocation: true` so the CLI runtime directly invokes `/ce:<command>`. The deprecation note is printed as a step description.
+
+Template for each wrapper:
+
+```markdown
+---
+name: workflows:<command>
+description: "[DEPRECATED] Use /ce:<command> instead — renamed for clarity."
+argument-hint: "[...]"
+disable-model-invocation: true
+---
+
+NOTE: /workflows:<command> is deprecated. Please use /ce:<command> instead. This alias will be removed in a future version.
+
+/ce:<command> $ARGUMENTS
+```
+
+### Step 3: Update all internal references
+
+**Orchestration commands:**
+- `commands/lfg.md` — replace `/workflows:plan`, `/workflows:work`, `/workflows:review`
+- `commands/slfg.md` — same
+
+**Command bodies:**
+- `commands/deepen-plan.md` — replace `/workflows:work`, `/workflows:compound`
+- `commands/test-xcode.md` — replace `/workflows:review`
+- The deprecated `workflows/brainstorm.md`, `workflows/compound.md`, `workflows/plan.md` wrappers — references in their body text pointing to other `workflows:*` commands should also be updated to `ce:*` (since users reading them should see the new names)
+
+**Agents:**
+- `agents/review/code-simplicity-reviewer.md`
+- `agents/research/git-history-analyzer.md`
+- `agents/research/learnings-researcher.md`
+
+**Skills:**
+- `skills/document-review/SKILL.md`
+- `skills/git-worktree/SKILL.md`
+- `skills/ce-setup/SKILL.md`
+- `skills/brainstorming/SKILL.md`
+- `skills/file-todos/SKILL.md`
+
+### Step 4: Update documentation
+
+**`plugins/compound-engineering/CHANGELOG.md`** — Add under new version section:
+```
+### Changed
+- `workflows:plan`, `workflows:work`, `workflows:review`, `workflows:brainstorm`, `workflows:compound` renamed to `ce:plan`, `ce:work`, `ce:review`, `ce:brainstorm`, `ce:compound` for clarity
+
+### Deprecated
+- `workflows:*` commands — use `ce:*` equivalents instead. Aliases remain functional and will be removed in a future version.
+```
+
+**`plugins/compound-engineering/README.md`** — Update the commands table to list `ce:*` as primary, show `workflows:*` as deprecated aliases.
+
+**`plugins/compound-engineering/CLAUDE.md`** — Update command listing and the "Why `workflows:`?" section to reflect new `ce:` namespace.
+
+**Root `README.md`** — Update the commands table (lines 133–136).
+
+### Step 5: Verify converter output
+
+After updating, re-run the bunx install script to confirm both targets are written:
+
+```bash
+bunx @every-env/compound-plugin install compound-engineering --to gemini --output /tmp/test-output
+ls /tmp/test-output/.gemini/commands/
+# Should show both: ce/ and workflows/
+```
+
+The `workflows/` output will contain the deprecation wrapper content. The `ce/` output will have the full implementation.
+
+**Future cleanup note:** When `workflows:*` wrappers are eventually removed, users must manually delete the stale `workflows/` directories from their converted targets (`.gemini/commands/workflows/`, `.codex/commands/workflows/`, etc.). Consider adding a migration note to the CHANGELOG at that time.
+
+### Step 6: Run `/release-docs` to update the docs site
+
+## Dependencies & Risks
+
+- **Risk:** Users with saved references to `workflows:*` commands in their CLAUDE.md files or scripts. **Mitigation:** The deprecation wrappers remain functional indefinitely.
+- **Risk:** Context token budget slightly increases (5 new command descriptions). **Mitigation:** Keep all descriptions short. Deprecated wrappers get minimal descriptions.
+- **Risk:** `lfg`/`slfg` orchestration breaks if update is partial. **Mitigation:** Update both in the same commit.
+
+## Sources & References
+
+- Existing commands: `plugins/compound-engineering/commands/workflows/*.md`
+- Orchestration commands: `plugins/compound-engineering/commands/lfg.md`, `plugins/compound-engineering/commands/slfg.md`
+- Plugin metadata: `plugins/compound-engineering/.claude-plugin/plugin.json`
+- Changelog: `plugins/compound-engineering/CHANGELOG.md`
+- README: `plugins/compound-engineering/README.md`

docs/plans/2026-03-01-fix-setup-skill-non-claude-llm-fallback-plan.md

@@ -0,0 +1,140 @@
+---
+title: "fix: Setup skill fails silently on non-Claude LLMs due to AskUserQuestion dependency"
+type: fix
+status: active
+date: 2026-03-01
+---
+
+## Enhancement Summary
+
+**Deepened on:** 2026-03-01
+**Research agents used:** best-practices-researcher, architecture-strategist, code-simplicity-reviewer, scope-explorer
+
+### Key Improvements
+1. Simplified preamble from 16 lines to 4 lines — drop platform name list and example blockquote (YAGNI)
+2. Expanded scope: `create-new-skill.md` also has `AskUserQuestion` and needs the same fix
+3. Clarified that `codex-agents.ts` change helps command/agent contexts only — does NOT reach skill execution (skills aren't converter-transformed)
+4. Added CLAUDE.md skill compliance policy as a third deliverable to prevent recurrence
+5. Separated two distinct failure modes: tool-not-found error vs silent auto-configuration
+
+### New Considerations Discovered
+- Only Pi converter transforms `AskUserQuestion` (incompletely); all others pass skill content through verbatim — the codex-agents.ts fix is independent of skill execution
+- `add-workflow.md` and `audit-skill.md` already explicitly prohibit `AskUserQuestion` — this undocumented policy should be formalized
+- Prose fallback is probabilistic (LLM compliance); converter-level transformation is the correct long-term architectural fix
+- The brainstorming skill avoids `AskUserQuestion` entirely and works cross-platform — that's the gold standard pattern
+
+---
+
+# fix: Setup Skill Cross-Platform Fallback for AskUserQuestion
+
+## Overview
+
+The `setup` skill uses `AskUserQuestion` at 5 decision points. On non-Claude platforms (Codex, Gemini, OpenCode, Copilot, Kiro, etc.), this tool doesn't exist — the LLM reads the skill body but cannot call the tool, causing silent failure or unconsented auto-configuration. Fix by adding a minimal fallback instruction to the skill body, applying the same to `create-new-skill.md`, and adding a policy to the CLAUDE.md skill checklist to prevent recurrence.
+
+## Problem Statement
+
+**Two distinct failure modes:**
+
+1. **Tool-not-found error** — LLM tries to call `AskUserQuestion` as a function; platform returns an error. Setup halts.
+2. **Silent skip** — LLM reads `AskUserQuestion` as prose, ignores the decision gate, auto-configures. User never consulted. This is worse — produces a `compound-engineering.local.md` the user never approved.
+
+`plugins/compound-engineering/skills/ce-setup/SKILL.md` has 5 `AskUserQuestion` blocks:
+
+| Line | Decision Point |
+|------|----------------|
+| 13 | Check existing config: Reconfigure / View / Cancel |
+| 44 | Stack detection: Auto-configure / Customize |
+| 67 | Stack override (multi-option) |
+| 85 | Focus areas (multiSelect) |
+| 104 | Review depth: Thorough / Fast / Comprehensive |
+
+`plugins/compound-engineering/skills/create-agent-skills/workflows/create-new-skill.md` lines 22 and 45 also use `AskUserQuestion`.
+
+Only the Pi converter transforms the reference (incompletely). All other converters (Codex, Gemini, Copilot, Kiro, Droid, Windsurf) pass skill content through verbatim — **skills are not converter-transformed**.
+
+## Proposed Solution
+
+Three deliverables, each addressing a different layer:
+
+### 1. Add 4-line "Interaction Method" preamble to `setup/SKILL.md`
+
+Immediately after the `# Compound Engineering Setup` heading, insert:
+
+```markdown
+## Interaction Method
+
+If `AskUserQuestion` is available, use it for all prompts below.
+
+If not, present each question as a numbered list and wait for a reply before proceeding to the next step. For multiSelect questions, accept comma-separated numbers (e.g. `1, 3`). Never skip or auto-configure.
+```
+
+**Why 4 lines, not 16:** LLMs know what a numbered list is — no example blockquote needed. The branching condition is tool availability, not platform identity — no platform name list needed (YAGNI: new platforms will be added and lists go stale). State the "never skip" rule once here; don't repeat it in `codex-agents.ts`.
+
+**Why this works:** The skill body IS read by the LLM on all platforms when `/ce-setup` is invoked. The agent follows prose instructions regardless of tool availability. This is the same pattern `brainstorming/SKILL.md` uses — it avoids `AskUserQuestion` entirely and uses inline numbered lists — the gold standard cross-platform approach.
+
+### 2. Apply the same preamble to `create-new-skill.md`
+
+`plugins/compound-engineering/skills/create-agent-skills/workflows/create-new-skill.md` uses `AskUserQuestion` at lines 22 and 45. Apply an identical preamble at the top of that file.
+
+### 3. Strengthen `codex-agents.ts` AskUserQuestion mapping
+
+This change does NOT fix skill execution (skills bypass the converter pipeline). It improves the AGENTS.md guidance for Codex command/agent contexts.
+
+Replace (`src/utils/codex-agents.ts` line 21):
+```
+- AskUserQuestion/Question: ask the user in chat
+```
+
+With:
+```
+- AskUserQuestion/Question: present choices as a numbered list in chat and wait for a reply number. For multi-select (multiSelect: true), accept comma-separated numbers. Never skip or auto-configure — always wait for the user's response before proceeding.
+```
+
+### 4. Add lint rule to CLAUDE.md skill compliance checklist
+
+Add to the "Skill Compliance Checklist" in `plugins/compound-engineering/CLAUDE.md`:
+
+```
+### AskUserQuestion Usage
+
+- [ ] If the skill uses `AskUserQuestion`, it must include an "Interaction Method" preamble explaining the numbered-list fallback for non-Claude environments
+- [ ] Prefer avoiding `AskUserQuestion` entirely (see brainstorming/SKILL.md pattern) for skills intended to run cross-platform
+```
+
+## Technical Considerations
+
+- `setup/SKILL.md` has `disable-model-invocation: true` — this controls session-startup context loading only, not skill-body execution at invocation time
+- The prose fallback is probabilistic (LLM compliance), not a build-time guarantee. The correct long-term architectural fix is converter-level transformation of skill content (a `transformSkillContent()` pass in each converter), but that is out of scope here
+- Commands with `AskUserQuestion` (`ce/brainstorm.md`, `ce/plan.md`, `test-browser.md`, etc.) have the same gap but are out of scope — explicitly noted as a future task
+
+## Acceptance Criteria
+
+- [ ] `setup/SKILL.md` has a 4-line "Interaction Method" preamble after the opening heading
+- [ ] `create-new-skill.md` has the same preamble
+- [ ] The skills still use `AskUserQuestion` as primary — no change to Claude Code behavior
+- [ ] `codex-agents.ts` AskUserQuestion line updated with structured guidance
+- [ ] `plugins/compound-engineering/CLAUDE.md` skill checklist includes AskUserQuestion policy
+- [ ] No regression: on Claude Code, setup works exactly as before
+
+## Files
+
+- `plugins/compound-engineering/skills/ce-setup/SKILL.md` — Add 4-line preamble after line 8
+- `plugins/compound-engineering/skills/create-agent-skills/workflows/create-new-skill.md` — Add same preamble at top
+- `src/utils/codex-agents.ts` — Strengthen AskUserQuestion mapping (line 21)
+- `plugins/compound-engineering/CLAUDE.md` — Add AskUserQuestion policy to skill compliance checklist
+
+## Future Work (Out of Scope)
+
+- Converter-level `transformSkillContent()` for all targets — build-time guarantee instead of prose fallback
+- Commands with `AskUserQuestion` (`ce/brainstorm.md`, `ce/plan.md`, `test-browser.md`) — same failure mode, separate fix
+
+## Sources & References
+
+- Issue: [#204](https://github.com/EveryInc/compound-engineering-plugin/issues/204)
+- `plugins/compound-engineering/skills/ce-setup/SKILL.md`
+- `plugins/compound-engineering/skills/create-agent-skills/workflows/create-new-skill.md:22,45`
+- `src/utils/codex-agents.ts:21`
+- `src/converters/claude-to-pi.ts:106` — Pi converter (reference pattern)
+- `plugins/compound-engineering/skills/brainstorming/SKILL.md` — gold standard cross-platform skill (no AskUserQuestion)
+- `plugins/compound-engineering/skills/create-agent-skills/workflows/add-workflow.md:12,37` — existing "DO NOT use AskUserQuestion" policy
+- `docs/solutions/adding-converter-target-providers.md`

docs/plans/2026-03-03-feat-sync-claude-mcp-all-supported-providers-plan.md

@@ -0,0 +1,639 @@
+---
+title: "feat: Sync Claude MCP servers to all supported providers"
+type: feat
+date: 2026-03-03
+status: completed
+deepened: 2026-03-03
+---
+
+# feat: Sync Claude MCP servers to all supported providers
+
+## Overview
+
+Expand the `sync` command so a user's local Claude Code MCP configuration can be propagated to every provider this CLI can reasonably support, instead of only the current partial set.
+
+Today, `sync` already symlinks Claude skills and syncs MCP servers for a subset of targets. The gap is that install/convert support has grown much faster than sync support, so the product promise in `README.md` has drifted away from what `src/commands/sync.ts` can actually do.
+
+This feature should close that parity gap without changing the core sync contract:
+
+- Claude remains the source of truth for personal skills and MCP servers.
+- Skills stay symlinked, not copied.
+- Existing user config in the destination tool is preserved where possible.
+- Target-specific MCP formats stay target-specific.
+
+## Problem Statement
+
+The current implementation has three concrete problems:
+
+1. `sync` only knows about `opencode`, `codex`, `pi`, `droid`, `copilot`, and `gemini`, while install/convert now supports `kiro`, `windsurf`, `openclaw`, and `qwen` too.
+2. `sync --target all` relies on stale detection metadata that still includes `cursor`, but misses newer supported tools.
+3. Existing MCP sync support is incomplete even for some already-supported targets:
+   - `codex` only emits stdio servers and silently drops remote MCP servers.
+   - `droid` is still skills-only even though Factory now documents `mcp.json`.
+
+User impact:
+
+- A user can install the plugin to more providers than they can sync their personal Claude setup to.
+- `sync --target all` does not mean "all supported tools" anymore.
+- Users with remote MCP servers in Claude get partial results depending on target.
+
+## Research Summary
+
+### No Relevant Brainstorm
+
+I checked recent brainstorms in `docs/brainstorms/` and found no relevant document for this feature within the last 14 days.
+
+### Internal Findings
+
+- `src/commands/sync.ts:15-125` hardcodes the sync target list, output roots, and per-target dispatch. It omits `windsurf`, `kiro`, `openclaw`, and `qwen`.
+- `src/utils/detect-tools.ts:15-22` still detects `cursor`, but not `windsurf`, `kiro`, `openclaw`, or `qwen`.
+- `src/parsers/claude-home.ts:11-19` already gives sync exactly the right inputs: personal skills plus `settings.json` `mcpServers`.
+- `src/sync/codex.ts:25-91` only serializes stdio MCP servers, even though Codex supports remote MCP config.
+- `src/sync/droid.ts:6-21` symlinks skills but ignores MCP entirely.
+- Target writers already encode several missing MCP formats and merge behaviors:
+  - `src/targets/windsurf.ts:65-92`
+  - `src/targets/kiro.ts:68-91`
+  - `src/targets/openclaw.ts:34-42`
+  - `src/targets/qwen.ts:9-15`
+- `README.md:89-123` promises "Sync Personal Config" but only documents the old subset of targets.
+
+### Institutional Learnings
+
+`docs/solutions/adding-converter-target-providers.md:20-32` and `docs/solutions/adding-converter-target-providers.md:208-214` reinforce the right pattern for this feature:
+
+- keep target mappings explicit,
+- treat MCP conversion as target-specific,
+- warn on unsupported features instead of forcing fake parity,
+- and add tests for each mapping.
+
+Note: `docs/solutions/patterns/critical-patterns.md` does not exist in this repository, so there was no critical-patterns file to apply.
+
+### External Findings
+
+Official docs confirm that the missing targets are not all equivalent, so this cannot be solved with a generic JSON pass-through.
+
+| Target | Official MCP / skills location | Key notes |
+| --- | --- | --- |
+| Factory Droid | `~/.factory/mcp.json`, `.factory/mcp.json`, `~/.factory/skills/` | Supports `stdio` and `http`; user config overrides project config. |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json`, `~/.codeium/windsurf/skills/` | Supports `stdio`, Streamable HTTP, and SSE; remote config uses `serverUrl` or `url`. |
+| Kiro | `~/.kiro/settings/mcp.json`, `.kiro/settings/mcp.json`, `~/.kiro/skills/` | Supports user and workspace config; remote MCP support was added after this repo's local Kiro spec was written. |
+| Qwen Code | `~/.qwen/settings.json`, `.qwen/settings.json`, `~/.qwen/skills/`, `.qwen/skills/` | Supports `stdio`, `http`, and `sse`; official docs say prefer `http`, with `sse` treated as legacy/deprecated. |
+| OpenClaw | `~/.openclaw/skills`, `<workspace>/skills`, `~/.openclaw/openclaw.json` | Skills are well-documented; a generic MCP server config surface is not clearly documented in official docs, so MCP sync needs validation before implementation is promised. |
+
+Additional important findings:
+
+- Kiro's current official behavior supersedes the local repo spec that says "workspace only" and "stdio only".
+- Qwen's current docs explicitly distinguish `httpUrl` from legacy SSE `url`; blindly copying Claude's `url` is too lossy.
+- Factory and Windsurf both support remote MCP, so `droid` should no longer be treated as skills-only.
+
+## Proposed Solution
+
+### Product Decision
+
+Treat this as **sync parity for MCP-capable providers**, not as a one-off patch.
+
+That means this feature should:
+
+- add missing sync targets where the provider has a documented skills/MCP surface,
+- upgrade partial implementations where existing sync support drops valid Claude MCP data,
+- and replace stale detection metadata so `sync --target all` is truthful again.
+
+### Scope
+
+#### In Scope
+
+- Add MCP sync coverage for:
+  - `droid`
+  - `windsurf`
+  - `kiro`
+  - `qwen`
+- Expand `codex` sync to support remote MCP servers.
+- Add provider detection for newly supported sync targets.
+- Keep skills syncing for all synced targets.
+- Update CLI help text, README sync docs, and tests.
+
+#### Conditional / Validation Gate
+
+- `openclaw` skills sync is straightforward and should be included if the target is added to `sync`.
+- `openclaw` MCP sync should only be implemented if its config surface is validated against current upstream docs or current upstream source. If that validation fails, the feature should explicitly skip OpenClaw MCP sync with a warning rather than inventing a format.
+
+#### Out of Scope
+
+- Standardizing all existing sync targets onto user-level paths only.
+- Reworking install/convert output roots.
+- Hook sync.
+- A full rewrite of target writers.
+
+### Design Decisions
+
+#### 0. Keep existing sync roots stable unless this feature is explicitly adding a new target
+
+Do not use this feature to migrate existing `copilot` and `gemini` sync behavior.
+
+Backward-compatibility rule:
+
+- existing targets keep their current sync roots unless a correctness bug forces a change,
+- newly added sync targets use the provider's documented personal/global config surface,
+- and any future root migration belongs in a separate plan.
+
+Planned sync roots after this feature:
+
+| Target | Sync root | Notes |
+| --- | --- | --- |
+| `opencode` | `~/.config/opencode` | unchanged |
+| `codex` | `~/.codex` | unchanged |
+| `pi` | `~/.pi/agent` | unchanged |
+| `droid` | `~/.factory` | unchanged root, new MCP file |
+| `copilot` | `.github` | unchanged for backwards compatibility |
+| `gemini` | `.gemini` | unchanged for backwards compatibility |
+| `windsurf` | `~/.codeium/windsurf` | new |
+| `kiro` | `~/.kiro` | new |
+| `qwen` | `~/.qwen` | new |
+| `openclaw` | `~/.openclaw` | new, MCP still validation-gated |
+
+#### 1. Add a dedicated sync target registry
+
+Do not keep growing `sync.ts` as a hand-maintained switch statement.
+
+Create a dedicated sync registry, for example:
+
+### `src/sync/registry.ts`
+
+```ts
+import os from "os"
+import path from "path"
+import type { ClaudeHomeConfig } from "../parsers/claude-home"
+
+export type SyncTargetDefinition = {
+  name: string
+  detectPaths: (home: string, cwd: string) => string[]
+  resolveOutputRoot: (home: string, cwd: string) => string
+  sync: (config: ClaudeHomeConfig, outputRoot: string) => Promise<void>
+}
+```
+
+This registry becomes the single source of truth for:
+
+- valid `sync` targets,
+- `sync --target all` detection,
+- output root resolution,
+- and dispatch.
+
+This avoids the current drift between:
+
+- `src/commands/sync.ts`
+- `src/utils/detect-tools.ts`
+- `README.md`
+
+#### 2. Preserve sync semantics, not writer semantics
+
+Do not directly reuse install target writers for sync.
+
+Reason:
+
+- writers mostly copy skill directories,
+- sync intentionally symlinks skills,
+- writers often emit full plugin/install bundles,
+- sync only needs personal skills plus MCP config.
+
+However, provider-specific MCP conversion helpers should be extracted or reused where practical so sync and writer logic do not diverge again.
+
+#### 3. Keep merge behavior additive, with Claude winning on same-name collisions
+
+For JSON-based targets:
+
+- preserve unrelated user keys,
+- preserve unrelated user MCP servers,
+- but if the same server name exists in Claude and the target config, Claude's value should overwrite that server entry during sync.
+
+Codex remains the special case:
+
+- continue using the managed marker block,
+- remove the previous managed block,
+- rewrite the managed block from Claude,
+- leave the rest of `config.toml` untouched.
+
+#### 4. Secure config writes where secrets may exist
+
+Any config file that may contain MCP headers or env vars should be written with restrictive permissions where the platform already supports that pattern.
+
+At minimum:
+
+- `config.toml`
+- `mcp.json`
+- `mcp_config.json`
+- `settings.json`
+
+should follow the repo's existing "secure write" conventions where possible.
+
+#### 5. Do not silently coerce ambiguous remote transports
+
+Qwen and possibly future targets distinguish Streamable HTTP from legacy SSE.
+
+Use this mapping rule:
+
+- if Claude explicitly provides `type: "sse"` or an equivalent known signal, map to the target's SSE field,
+- otherwise prefer the target's HTTP form for remote URLs,
+- and log a warning when a target requires more specificity than Claude provides.
+
+## Provider Mapping Plan
+
+### Existing Targets to Upgrade
+
+#### Codex
+
+Current issue:
+
+- only stdio servers are synced.
+
+Implementation:
+
+- extend `syncToCodex()` so remote MCP servers are serialized into the Codex TOML format, not dropped.
+- keep the existing marker-based idempotent section handling.
+
+Notes:
+
+- This is a correctness fix, not a new target.
+
+#### Droid / Factory
+
+Current issue:
+
+- skills-only sync despite current official MCP support.
+
+Implementation:
+
+- add `src/sync/droid.ts` MCP config writing to `~/.factory/mcp.json`.
+- merge with existing `mcpServers`.
+- support both `stdio` and `http`.
+
+### New Sync Targets
+
+#### Windsurf
+
+Add `src/sync/windsurf.ts`:
+
+- symlink Claude skills into `~/.codeium/windsurf/skills/`
+- merge MCP servers into `~/.codeium/windsurf/mcp_config.json`
+- support `stdio`, Streamable HTTP, and SSE
+- prefer `serverUrl` for remote HTTP config
+- preserve unrelated existing servers
+- write with secure permissions
+
+Reference implementation:
+
+- `src/targets/windsurf.ts:65-92`
+
+#### Kiro
+
+Add `src/sync/kiro.ts`:
+
+- symlink Claude skills into `~/.kiro/skills/`
+- merge MCP servers into `~/.kiro/settings/mcp.json`
+- support both local and remote MCP servers
+- preserve user config already present in `mcp.json`
+
+Important:
+
+- This feature must treat the repository's local Kiro spec as stale where it conflicts with official 2025-2026 Kiro docs/blog posts.
+
+Reference implementation:
+
+- `src/targets/kiro.ts:68-91`
+
+#### Qwen
+
+Add `src/sync/qwen.ts`:
+
+- symlink Claude skills into `~/.qwen/skills/`
+- merge MCP servers into `~/.qwen/settings.json`
+- map stdio directly
+- map remote URLs to `httpUrl` by default
+- only emit legacy SSE `url` when Claude transport clearly indicates SSE
+
+Important:
+
+- capture the deprecation note in docs/comments: SSE is legacy, so HTTP is the default remote mapping.
+
+#### OpenClaw
+
+Add `src/sync/openclaw.ts` only if validated during implementation:
+
+- symlink skills into `~/.openclaw/skills`
+- optionally merge MCP config into `~/.openclaw/openclaw.json` if the official/current upstream contract is confirmed
+
+Fallback behavior if MCP config cannot be validated:
+
+- sync skills only,
+- emit a warning that OpenClaw MCP sync is skipped because the official config surface is not documented clearly enough.
+
+## Implementation Phases
+
+### Phase 1: Registry and shared helpers
+
+Files:
+
+- `src/commands/sync.ts`
+- `src/utils/detect-tools.ts`
+- `src/sync/registry.ts` (new)
+- `src/sync/skills.ts` or `src/utils/symlink.ts` extension
+- optional `src/sync/mcp-merge.ts`
+
+Tasks:
+
+- move sync target metadata into a single registry
+- make `validTargets` derive from the registry
+- make `sync --target all` use the registry
+- update detection to include supported sync targets instead of stale `cursor`
+- extract a shared helper for validated skill symlinking
+
+### Phase 2: Upgrade existing partial targets
+
+Files:
+
+- `src/sync/codex.ts`
+- `src/sync/droid.ts`
+- `tests/sync-droid.test.ts`
+- new or expanded `tests/sync-codex.test.ts`
+
+Tasks:
+
+- add remote MCP support to Codex sync
+- add MCP config writing to Droid sync
+- preserve current skill symlink behavior
+
+### Phase 3: Add missing sync targets
+
+Files:
+
+- `src/sync/windsurf.ts`
+- `src/sync/kiro.ts`
+- `src/sync/qwen.ts`
+- optionally `src/sync/openclaw.ts`
+- `tests/sync-windsurf.test.ts`
+- `tests/sync-kiro.test.ts`
+- `tests/sync-qwen.test.ts`
+- optionally `tests/sync-openclaw.test.ts`
+
+Tasks:
+
+- implement skill symlink + MCP merge for each target
+- align output paths with the target's documented personal config surface
+- secure writes and corrupted-config fallbacks
+
+### Phase 4: CLI, docs, and detection parity
+
+Files:
+
+- `src/commands/sync.ts`
+- `src/utils/detect-tools.ts`
+- `tests/detect-tools.test.ts`
+- `tests/cli.test.ts`
+- `README.md`
+- optionally `docs/specs/kiro.md`
+
+Tasks:
+
+- update `sync` help text and summary output
+- ensure `sync --target all` only reports real sync-capable tools
+- document newly supported sync targets
+- fix stale Kiro assumptions if repository docs are updated in the same change
+
+## SpecFlow Analysis
+
+### Primary user flows
+
+#### Flow 1: Explicit sync to one target
+
+1. User runs `bunx @every-env/compound-plugin sync --target <provider>`
+2. CLI loads `~/.claude/skills` and `~/.claude/settings.json`
+3. CLI resolves that provider's sync root
+4. Skills are symlinked
+5. MCP config is merged
+6. CLI prints the destination path and completion summary
+
+#### Flow 2: Sync to all detected tools
+
+1. User runs `bunx @every-env/compound-plugin sync`
+2. CLI detects installed/supported tools
+3. CLI prints which tools were found and which were skipped
+4. CLI syncs each detected target in sequence
+5. CLI prints per-target success lines
+
+#### Flow 3: Existing config already present
+
+1. User already has destination config file(s)
+2. Sync reads and parses the existing file
+3. Existing unrelated keys are preserved
+4. Claude MCP entries are merged in
+5. Corrupt config produces a warning and replacement behavior
+
+### Edge cases to account for
+
+- Claude has zero MCP servers: skills still sync, no config file is written.
+- Claude has remote MCP servers: targets that support remote config receive them; unsupported transports warn, not crash.
+- Existing target config is invalid JSON/TOML: warn and replace the managed portion.
+- Skill name contains path traversal characters: skip with warning, same as current behavior.
+- Real directory already exists where a symlink would go: skip safely, do not delete user data.
+- `sync --target all` detects a tool with skills support but unclear MCP support: sync only the documented subset and warn explicitly.
+
+### Critical product decisions already assumed
+
+- `sync` remains additive and non-destructive.
+- Sync roots may differ from install roots when the provider has a documented personal config location.
+- OpenClaw MCP support is validation-gated rather than assumed.
+
+## Acceptance Criteria
+
+### Functional Requirements
+
+- [x] `sync --target` accepts `windsurf`, `kiro`, and `qwen`, in addition to the existing targets.
+- [x] `sync --target droid` writes MCP servers to Factory's documented `mcp.json` format instead of remaining skills-only.
+- [x] `sync --target codex` syncs both stdio and remote MCP servers.
+- [x] `sync --target all` detects only sync-capable supported tools and includes the new targets.
+- [x] Claude personal skills continue to be symlinked, not copied.
+- [x] Existing destination config keys unrelated to MCP are preserved during merge.
+- [x] Existing same-named MCP entries are refreshed from Claude for sync-managed targets.
+- [x] Unsafe skill names are skipped without deleting user content.
+- [x] If OpenClaw MCP sync is not validated, the CLI warns and skips MCP sync for OpenClaw instead of writing an invented format.
+
+### Non-Functional Requirements
+
+- [x] MCP config files that may contain secrets are written with restrictive permissions where supported.
+- [x] Corrupt destination config files warn and recover cleanly.
+- [x] New sync code does not duplicate target detection metadata in multiple places.
+- [x] Remote transport mapping is explicit and tested, especially for Qwen and Codex.
+
+### Quality Gates
+
+- [x] Add target-level sync tests for every new or upgraded provider.
+- [x] Update `tests/detect-tools.test.ts` for new detection rules and remove stale cursor expectations.
+- [x] Add or expand CLI coverage for `sync --target all`.
+- [x] `bun test` passes.
+
+## Testing Plan
+
+### Unit / integration tests
+
+Add or expand:
+
+- `tests/sync-codex.test.ts`
+  - remote URL server is emitted
+  - existing non-managed TOML content is preserved
+- `tests/sync-droid.test.ts`
+  - writes `mcp.json`
+  - merges with existing file
+- `tests/sync-windsurf.test.ts`
+  - writes `mcp_config.json`
+  - merges existing servers
+  - preserves HTTP/SSE fields
+- `tests/sync-kiro.test.ts`
+  - writes `settings/mcp.json`
+  - supports user-scope root
+  - preserves remote servers
+- `tests/sync-qwen.test.ts`
+  - writes `settings.json`
+  - maps remote servers to `httpUrl`
+  - emits legacy SSE only when explicitly indicated
+- `tests/sync-openclaw.test.ts` if implemented
+  - skills path
+  - MCP behavior or explicit skip warning
+
+### CLI tests
+
+Expand `tests/cli.test.ts` or add focused sync CLI coverage for:
+
+- `sync --target windsurf`
+- `sync --target kiro`
+- `sync --target qwen`
+- `sync --target all` with detected new tool homes
+- `sync --target all` no longer surfacing unsupported `cursor`
+
+## Risks and Mitigations
+
+### Risk: local specs are stale relative to current provider docs
+
+Impact:
+
+- implementing from local docs alone would produce incorrect paths and transport support.
+
+Mitigation:
+
+- treat official 2025-2026 docs/blog posts as source of truth where they supersede local specs
+- update any obviously stale repo docs touched by this feature
+
+### Risk: transport ambiguity for remote MCP servers
+
+Impact:
+
+- a Claude `url` may map incorrectly for targets that distinguish HTTP vs SSE.
+
+Mitigation:
+
+- prefer HTTP where the target recommends it
+- only emit legacy SSE when Claude transport is explicit
+- warn when mapping is lossy
+
+### Risk: OpenClaw MCP surface is not sufficiently documented
+
+Impact:
+
+- writing a guessed MCP config could create a broken or misleading feature.
+
+Mitigation:
+
+- validation gate during implementation
+- if validation fails, ship OpenClaw skills sync only and document MCP as a follow-up
+
+### Risk: `sync --target all` remains easy to drift out of sync again
+
+Impact:
+
+- future providers get added to install/convert but missed by sync.
+
+Mitigation:
+
+- derive sync valid targets and detection from a shared registry
+- add tests that assert detection and sync target lists match expected supported names
+
+## Alternative Approaches Considered
+
+### 1. Just add more cases to `sync.ts`
+
+Rejected:
+
+- this is exactly how the current drift happened.
+
+### 2. Reuse target writers directly
+
+Rejected:
+
+- writers copy directories and emit install bundles;
+- sync must symlink skills and only manage personal config subsets.
+
+### 3. Standardize every sync target on user-level output now
+
+Rejected for this feature:
+
+- it would change existing `gemini` and `copilot` behavior and broaden scope into a migration project.
+
+## Documentation Plan
+
+- Update `README.md` sync section to list all supported sync targets and call out any exceptions.
+- Update sync examples for `windsurf`, `kiro`, and `qwen`.
+- If OpenClaw MCP is skipped, document that explicitly.
+- If repository specs are corrected during implementation, update `docs/specs/kiro.md` to match official current behavior.
+
+## Success Metrics
+
+- `sync --target all` covers the same provider surface users reasonably expect from the current CLI, excluding only targets that lack a validated MCP config contract.
+- A Claude config with one stdio server and one remote server syncs correctly to every documented MCP-capable provider.
+- No user data is deleted during sync.
+- Documentation and CLI help no longer over-promise relative to actual behavior.
+
+## AI Pairing Notes
+
+- Treat official provider docs as authoritative over older local notes, especially for Kiro and Qwen transport handling.
+- Have a human review any AI-generated MCP mapping code before merge because these config files may contain secrets and lossy transport assumptions are easy to miss.
+- When using an implementation agent, keep the work split by target so each provider's config contract can be tested independently.
+
+## References & Research
+
+### Internal References
+
+- `src/commands/sync.ts:15-125`
+- `src/utils/detect-tools.ts:11-46`
+- `src/parsers/claude-home.ts:11-64`
+- `src/sync/codex.ts:7-92`
+- `src/sync/droid.ts:6-21`
+- `src/targets/windsurf.ts:13-93`
+- `src/targets/kiro.ts:5-93`
+- `src/targets/openclaw.ts:6-95`
+- `src/targets/qwen.ts:5-64`
+- `docs/solutions/adding-converter-target-providers.md:20-32`
+- `docs/solutions/adding-converter-target-providers.md:208-214`
+- `README.md:89-123`
+
+### External References
+
+- Factory MCP docs: https://docs.factory.ai/factory-cli/configuration/mcp
+- Factory skills docs: https://docs.factory.ai/cli/configuration/skills
+- Windsurf MCP docs: https://docs.windsurf.com/windsurf/cascade/mcp
+- Kiro MCP overview: https://kiro.dev/blog/unlock-your-development-productivity-with-kiro-and-mcp/
+- Kiro remote MCP support: https://kiro.dev/blog/introducing-remote-mcp/
+- Kiro skills announcement: https://kiro.dev/blog/custom-subagents-skills-and-enterprise-controls/
+- Qwen settings docs: https://qwenlm.github.io/qwen-code-docs/en/users/configuration/settings/
+- Qwen MCP docs: https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/
+- Qwen skills docs: https://qwenlm.github.io/qwen-code-docs/zh/users/features/skills/
+- OpenClaw setup/config docs: https://docs.openclaw.ai/start/setup
+- OpenClaw skills docs: https://docs.openclaw.ai/skills
+
+## Implementation Notes for the Follow-Up `/workflows-work` Step
+
+Suggested implementation order:
+
+1. registry + detection cleanup
+2. codex remote MCP + droid MCP
+3. windsurf + kiro + qwen sync modules
+4. openclaw validation and implementation or explicit warning path
+5. docs + tests

docs/plans/2026-03-15-001-feat-ce-ideate-skill-plan.md

@@ -0,0 +1,387 @@
+---
+title: "feat: Add ce:ideate open-ended ideation skill"
+type: feat
+status: completed
+date: 2026-03-15
+origin: docs/brainstorms/2026-03-15-ce-ideate-skill-requirements.md
+deepened: 2026-03-16
+---
+
+# feat: Add ce:ideate open-ended ideation skill
+
+## Overview
+
+Add a new `ce:ideate` skill to the compound-engineering plugin that performs open-ended, divergent-then-convergent idea generation for any project. The skill deeply scans the codebase, generates ~30 ideas, self-critiques and filters them, and presents the top 5-7 as a ranked list with structured analysis. It uses agent intelligence to improve the candidate pool without replacing the core prompt mechanism, writes a durable artifact to `docs/ideation/` after the survivors have been reviewed, and hands off selected ideas to `ce:brainstorm`.
+
+## Problem Frame
+
+The ce:* workflow pipeline has a gap at the very beginning. `ce:brainstorm` requires the user to bring an idea — it refines but doesn't generate. Users who want the AI to proactively suggest improvements must resort to ad-hoc prompting, which lacks codebase grounding, structured output, durable artifacts, and pipeline integration. (see origin: docs/brainstorms/2026-03-15-ce-ideate-skill-requirements.md)
+
+## Requirements Trace
+
+- R1. Standalone skill in `plugins/compound-engineering/skills/ce-ideate/`
+- R2. Optional freeform argument as focus hint (concept, path, constraint, or empty)
+- R3. Deep codebase scan via research agents before generating ideas
+- R4. Preserve the proven prompt mechanism: many ideas first, then brutal filtering, then detailed survivors
+- R5. Self-critique with explicit rejection reasoning
+- R6. Present top 5-7 with structured analysis (description, rationale, downsides, confidence 0-100%, complexity)
+- R7. Rejection summary (one-line per rejected idea)
+- R8. Durable artifact in `docs/ideation/YYYY-MM-DD-<topic>-ideation.md`
+- R9. Volume overridable via argument
+- R10. Handoff: brainstorm an idea, refine, share to Proof, or end session
+- R11. Always route to ce:brainstorm for follow-up on selected ideas
+- R12. Offer commit on session end
+- R13. Resume from existing ideation docs (30-day recency window)
+- R14. Present survivors before writing the durable artifact
+- R15. Write artifact before handoff/share/end
+- R16. Update doc in place on refine when preserving refined state
+- R17. Use agent intelligence as support for the core mechanism, not a replacement
+- R18. Use research agents for grounding; ideation/critique sub-agents are prompt-defined roles
+- R19. Pass grounding summary, focus hint, and volume target to ideation sub-agents
+- R20. Focus hints influence both generation and filtering
+- R21. Use standardized structured outputs from ideation sub-agents
+- R22. Orchestrator owns final scoring, ranking, and survivor decisions
+- R23. Use broad prompt-framing methods to encourage creative spread without over-constraining ideation
+- R24. Use the smallest useful set of sub-agents rather than a hardcoded fixed count
+- R25. Mark ideas as "explored" when brainstormed
+
+## Scope Boundaries
+
+- No external research (competitive analysis, similar projects) in v1 (see origin)
+- No configurable depth modes — fixed volume with argument-based override (see origin)
+- No modifications to ce:brainstorm — discovery via skill description only (see origin)
+- No deprecated `workflows:ideate` alias — the `workflows:*` prefix is deprecated
+- No `references/` split — estimated skill length ~300 lines, well under the 500-line threshold
+
+## Context & Research
+
+### Relevant Code and Patterns
+
+- `plugins/compound-engineering/skills/ce-brainstorm/SKILL.md` — Closest sibling. Mirror: resume behavior (Phase 0.1), artifact frontmatter (date + topic), handoff options via platform question tool, document-review integration, Proof sharing
+- `plugins/compound-engineering/skills/ce-plan/SKILL.md` — Agent dispatch pattern: `Task compound-engineering:research:repo-research-analyst(context)` running in parallel. Phase 0.2 upstream document detection
+- `plugins/compound-engineering/skills/ce-work/SKILL.md` — Session completion: incremental commit pattern, staging specific files, conventional commit format
+- `plugins/compound-engineering/skills/ce-compound/SKILL.md` — Parallel research assembly: subagents return text only, orchestrator writes the single file
+- `plugins/compound-engineering/skills/document-review/SKILL.md` — Utility invocation: "Load the `document-review` skill and apply it to..." Returns "Review complete" signal
+- `plugins/compound-engineering/skills/deepen-plan/SKILL.md` — Broad parallel agent dispatch pattern
+- PR #277 (`fix: codex workflow conversion for compound-engineering`) — establishes the Codex model for canonical `ce:*` workflows: prompt wrappers for canonical entrypoints, transformed intra-workflow handoffs, and omission of deprecated `workflows:*` aliases
+
+### Institutional Learnings
+
+- `docs/solutions/plugin-versioning-requirements.md` — Do not bump versions or cut changelog entries in feature PRs. Do update README counts and plugin.json descriptions.
+- `docs/solutions/codex-skill-prompt-entrypoints.md` (from PR #277) — for compound-engineering workflows in Codex, prompts are the canonical user-facing entrypoints and copied skills are the reusable implementation units underneath them
+
+## Key Technical Decisions
+
+- **Agent dispatch for codebase scan**: Use `repo-research-analyst` + `learnings-researcher` in parallel (matches ce:plan Phase 1.1). Skip `git-history-analyzer` by default — marginal ideation value for the cost. The focus hint (R2) is passed as context to both agents.
+- **Core mechanism first, agents second**: The core design is still the user's proven prompt pattern: generate many ideas, reject aggressively, then explain only the survivors. Agent intelligence improves the candidate pool and critique quality, but does not replace this mechanism.
+- **Prompt-defined ideation and critique sub-agents**: Use prompt-shaped sub-agents with distinct framing methods for ideation and optional skeptical critique, rather than forcing reuse of existing named review agents whose purpose is different.
+- **Orchestrator-owned synthesis and scoring**: The orchestrator merges and dedupes sub-agent outputs, applies one consistent rubric, and decides final scoring/ranking. Sub-agents may emit lightweight local signals, but not authoritative final rankings.
+- **Artifact frontmatter**: `date`, `topic`, `focus` (optional). Minimal, paralleling the brainstorm `date` + `topic` pattern.
+- **Volume override via natural language**: The skill instructions tell Claude to interpret number patterns in the argument ("top 3", "100 ideas") as volume overrides. No formal parsing.
+- **Artifact timing**: Present survivors first, allow brief questions or lightweight clarification, then write/update the durable artifact before any handoff, Proof share, or session end.
+- **No `disable-model-invocation`**: The skill should be auto-loadable when users say things like "what should I improve?", "give me ideas for this project", "ideate on improvements". Following the same pattern as ce:brainstorm.
+- **Commit pattern**: Stage only `docs/ideation/<filename>`, use conventional format `docs: add ideation for <topic>`, offer but don't force.
+- **Relationship to PR #277**: `ce:ideate` must follow the same Codex workflow model as the other canonical `ce:*` workflows. Why: without #277's prompt-wrapper and handoff-rewrite model, a copied workflow skill can still point at Claude-style slash handoffs that do not exist coherently in Codex. `ce:ideate` should be introduced as another canonical `ce:*` workflow on that same surface, not as a one-off pass-through skill.
+
+## Open Questions
+
+### Resolved During Planning
+
+- **Which agents for codebase scan?** → `repo-research-analyst` + `learnings-researcher`. Rationale: same proven pattern as ce:plan, covers both current code and institutional knowledge.
+- **Additional analysis fields per idea?** → Keep as specified in R6. "What this unlocks" bleeds into brainstorm scope. YAGNI.
+- **Volume override detection?** → Natural language interpretation. The skill instructions describe how to detect overrides. No formal parsing needed.
+- **Artifact frontmatter fields?** → `date`, `topic`, `focus` (optional). Follows brainstorm pattern.
+- **Need references/ split?** → No. Estimated ~300 lines, under the 500-line threshold.
+- **Need deprecated alias?** → No. `workflows:*` is deprecated; new skills go straight to `ce:*`.
+- **How should docs regeneration be represented in the plan?** → The checked-in tree does not currently contain the previously assumed generated files (`docs/index.html`, `docs/pages/skills.html`). Treat `/release-docs` as a repo-maintenance validation step that may update tracked generated artifacts, not as a guaranteed edit to predetermined file paths.
+- **How should skill counts be validated across artifacts?** → Do not force one unified count across every surface. The plugin manifests should reflect parser-discovered skill directories, while `plugins/compound-engineering/README.md` should preserve its human-facing taxonomy of workflow commands vs. standalone skills.
+- **What is the dependency on PR #277?** → Treat #277 as an upstream prerequisite for Codex correctness. If it merges first, `ce:ideate` should slot into its canonical `ce:*` workflow model. If it does not merge first, equivalent Codex workflow behavior must be included before `ce:ideate` is considered complete.
+- **How should agent intelligence be applied?** → Research agents are used for grounding, prompt-defined sub-agents are used to widen the candidate pool and critique it, and the orchestrator remains the final judge.
+- **Who should score the ideas?** → The orchestrator, not the ideation sub-agents and not a separate scoring sub-agent by default.
+- **When should the artifact be written?** → After the survivors are presented and reviewed enough to preserve, but always before handoff, sharing, or session end.
+
+### Deferred to Implementation
+
+- **Exact wording of the divergent ideation prompt section**: The plan specifies the structure and mechanisms, but the precise phrasing will be refined during implementation. This is an inherently iterative design element.
+- **Exact wording of the self-critique instructions**: Same — structure is defined, exact prose is implementation-time.
+
+## Implementation Units
+
+- [x] **Unit 1: Create the ce:ideate SKILL.md**
+
+**Goal:** Write the complete skill definition with all phases, the ideation prompt structure, optional sub-agent support, artifact template, and handoff options.
+
+**Requirements:** R1-R25 (all requirements — this is the core deliverable)
+
+**Dependencies:** None
+
+**Files:**
+- Create: `plugins/compound-engineering/skills/ce-ideate/SKILL.md`
+- Test (conditional): `tests/claude-parser.test.ts`, `tests/cli.test.ts`
+
+**Approach:**
+
+- Keep this unit primarily content-only unless implementation discovers a real parser or packaging gap. `loadClaudePlugin()` already discovers any `skills/*/SKILL.md`, and most target converters/writers already pass `plugin.skills` through as `skillDirs`.
+- Do not rely on pure pass-through for Codex. Because PR #277 gives compound-engineering `ce:*` workflows a canonical prompt-wrapper model in Codex, `ce:ideate` must be validated against that model and may require Codex-target updates if #277 is not already present.
+- Treat artifact lifecycle rules as part of the skill contract, not polish: resume detection, present-before-write, refine-in-place, and brainstorm handoff state all live inside this SKILL.md and must be internally consistent.
+- Keep the prompt sections grounded in Phase 1 findings so ideation quality does not collapse into generic product advice.
+- Keep the user's original prompt mechanism as the backbone of the workflow. Extra agent structure should strengthen that mechanism rather than replacing it.
+- When sub-agents are used, keep them prompt-defined and lightweight: shared grounding/focus/volume input, structured output, orchestrator-owned merge/dedupe/scoring.
+
+The skill follows the ce:brainstorm phase structure but with fundamentally different phases:
+
+```
+Phase 0: Resume and Route
+  0.1 Check docs/ideation/ for recent ideation docs (R13)
+  0.2 Parse argument — extract focus hint and any volume override (R2, R9)
+  0.3 If no argument, proceed with fully open ideation (no blocking ask)
+
+Phase 1: Codebase Scan
+  1.1 Dispatch research agents in parallel (R3):
+      - Task compound-engineering:research:repo-research-analyst(focus context)
+      - Task compound-engineering:research:learnings-researcher(focus context)
+  1.2 Consolidate scan results into a codebase understanding summary
+
+Phase 2: Divergent Generation (R4, R17-R21, R23-R24)
+  Core ideation instructions tell Claude to:
+  - Generate ~30 ideas (or override amount) as a numbered list
+  - Each idea is a one-liner at this stage
+  - Push past obvious suggestions — the first 10-15 will be safe/obvious,
+    the interesting ones come after
+  - Ground every idea in specific codebase findings from Phase 1
+  - Ideas should span multiple dimensions where justified
+  - If a focus area was provided, weight toward it but don't exclude
+    other strong ideas
+  - Preserve the user's original many-ideas-first mechanism
+  Optional sub-agent support:
+  - If the platform supports it, dispatch a small useful set of ideation
+    sub-agents with the same grounding summary, focus hint, and volume target
+  - Give each one a distinct prompt framing method (e.g. friction, unmet
+    need, inversion, assumption-breaking, leverage, extreme case)
+  - Require structured idea output so the orchestrator can merge and dedupe
+  - Do not use sub-agents to replace the core ideation mechanism
+
+Phase 3: Self-Critique and Filter (R5, R7, R20-R22)
+  Critique instructions tell Claude to:
+  - Go through each idea and evaluate it critically
+  - For each rejection, write a one-line reason
+  - Rejection criteria: not actionable, too vague, too expensive relative
+    to value, already exists, duplicates another idea, not grounded in
+    actual codebase state
+  - Target: keep 5-7 survivors (or override amount)
+  - If more than 7 pass scrutiny, do a second pass with higher bar
+  - If fewer than 5 pass, note this honestly rather than lowering the bar
+  Optional critique sub-agent support:
+  - Skeptical sub-agents may attack the merged list from distinct angles
+  - The orchestrator synthesizes critiques and owns final scoring/ranking
+
+Phase 4: Present Results (R6, R7, R14)
+  - Display ranked survivors with structured analysis per idea:
+    title, description (2-3 sentences), rationale, downsides,
+    confidence (0-100%), estimated complexity (low/medium/high)
+  - Display rejection summary: collapsed section, one-line per rejected idea
+  - Allow brief questions or lightweight clarification before archival write
+
+Phase 5: Write Artifact (R8, R15, R16)
+  - mkdir -p docs/ideation/
+  - Write the ideation doc after survivors are reviewed enough to preserve
+  - Artifact includes: metadata, codebase context summary, ranked
+    survivors with full analysis, rejection summary
+  - Always write/update before brainstorm handoff, Proof share, or session end
+
+Phase 6: Handoff (R10, R11, R12, R15-R16, R25)
+  6.1 Present options via platform question tool:
+      - Brainstorm an idea (pick by number → feeds to ce:brainstorm) (R11)
+      - Refine (R15)
+      - Share to Proof
+      - End session (R12)
+  6.2 Handle selection:
+      - Brainstorm: update doc to mark idea as "explored" (R16),
+        then invoke ce:brainstorm with the idea description
+      - Refine: ask what kind of refinement, then route:
+        "add more ideas" / "explore new angles" → return to Phase 2
+        "re-evaluate" / "raise the bar" → return to Phase 3
+        "dig deeper on idea #N" → expand that idea's analysis in place
+        Update doc after each refinement when preserving the refined state (R16)
+      - Share to Proof: upload ideation doc using the standard
+        curl POST pattern (same as ce:brainstorm), return to options
+      - End: offer to commit the ideation doc (R12), display closing summary
+```
+
+Frontmatter:
+```yaml
+---
+name: ce:ideate
+description: 'Generate and critically evaluate improvement ideas for any project through deep codebase analysis and divergent-then-convergent thinking. Use when the user says "what should I improve", "give me ideas", "ideate", "surprise me with improvements", "what would you change about this project", or when they want AI-generated project improvement suggestions rather than refining their own idea.'
+argument-hint: "[optional: focus area, path, or constraint]"
+---
+```
+
+Artifact template:
+```markdown
+---
+date: YYYY-MM-DD
+topic: <kebab-case-topic>
+focus: <focus area if provided, omit if open>
+---
+
+# Ideation: <Topic or "Open Exploration">
+
+## Codebase Context
+[Brief summary of what the scan revealed — project structure, patterns, pain points, opportunities]
+
+## Ranked Ideas
+
+### 1. <Idea Title>
+**Description:** [2-3 sentences]
+**Rationale:** [Why this would be a good improvement]
+**Downsides:** [Risks or costs]
+**Confidence:** [0-100%]
+**Complexity:** [Low / Medium / High]
+
+### 2. <Idea Title>
+...
+
+## Rejection Summary
+| # | Idea | Reason for Rejection |
+|---|------|---------------------|
+| 1 | ... | ... |
+
+## Session Log
+- [Date]: Initial ideation — [N] generated, [M] survived
+```
+
+**Patterns to follow:**
+- ce:brainstorm SKILL.md — phase structure, frontmatter style, argument handling, resume pattern, handoff options, Proof sharing, interaction rules
+- ce:plan SKILL.md — agent dispatch syntax (`Task compound-engineering:research:*`)
+- ce:work SKILL.md — session completion commit pattern
+- Plugin CLAUDE.md — skill compliance checklist (imperative voice, cross-platform question tool, no second person)
+
+**Test scenarios:**
+- Invoke with no arguments → fully open ideation, generates ideas, presents survivors, then writes artifact when preserving results
+- Invoke with focus area (`/ce:ideate DX improvements`) → weighted ideation toward focus
+- Invoke with path (`/ce:ideate plugins/compound-engineering/skills/`) → scoped scan
+- Invoke with volume override (`/ce:ideate give me your top 3`) → adjusted volume
+- Resume: invoke when recent ideation doc exists → offers to continue or start fresh
+- Resume + refine loop: revisit an existing ideation doc, add more ideas, then re-run critique without creating a duplicate artifact
+- If sub-agents are used: each receives grounding + focus + volume context and returns structured outputs for orchestrator merge
+- If critique sub-agents are used: orchestrator remains final scorer and ranker
+- Brainstorm handoff: pick an idea → doc updated with "explored" marker, ce:brainstorm invoked
+- Refine: ask to dig deeper → doc updated in place with refined analysis
+- End session: offer commit → stages only the ideation doc, conventional message
+- Initial review checkpoint: survivors can be questioned before archival write
+- Codex install path after PR #277: `ce:ideate` is exposed as the canonical `ce:ideate` workflow entrypoint, not only as a copied raw skill
+- Codex intra-workflow handoffs: any copied `SKILL.md` references to `/ce:*` routes resolve to the canonical Codex prompt surface, and no deprecated `workflows:ideate` alias is emitted
+
+**Verification:**
+- SKILL.md is under 500 lines
+- Frontmatter has `name`, `description`, `argument-hint`
+- Description includes trigger phrases for auto-discovery
+- All 25 requirements are addressed in the phase structure
+- Writing style is imperative/infinitive, no second person
+- Cross-platform question tool pattern with fallback
+- No `disable-model-invocation` (auto-loadable)
+- The repository still loads plugin skills normally because `ce:ideate` is discovered as a `skillDirs` entry
+- Codex output follows the compound-engineering workflow model from PR #277 for this new canonical `ce:*` workflow
+
+---
+
+- [x] **Unit 2: Update plugin metadata and documentation**
+
+**Goal:** Update all locations where component counts and skill listings appear.
+
+**Requirements:** R1 (skill exists in the plugin)
+
+**Dependencies:** Unit 1
+
+**Files:**
+- Modify: `plugins/compound-engineering/.claude-plugin/plugin.json` — update description with new skill count
+- Modify: `.claude-plugin/marketplace.json` — update plugin description with new skill count
+- Modify: `plugins/compound-engineering/README.md` — add ce:ideate to skills table/list, update count
+
+**Approach:**
+- Count actual skill directories after adding ce:ideate for manifest-facing descriptions (`plugin.json`, `.claude-plugin/marketplace.json`)
+- Preserve the README's separate human-facing breakdown of `Commands` vs `Skills` instead of forcing it to equal the manifest-level skill-directory count
+- Add ce:ideate to the README skills section with a brief description in the existing table format
+- Do NOT bump version numbers (per plugin versioning requirements)
+- Do NOT add a CHANGELOG.md release entry
+
+**Patterns to follow:**
+- CLAUDE.md checklist: "Updating the Compounding Engineering Plugin"
+- Existing skill entries in README.md for description format
+- `src/parsers/claude.ts` loading model: manifests and targets derive skill inventory from discovered `skills/*/SKILL.md` directories
+
+**Test scenarios:**
+- Manifest descriptions reflect the post-change skill-directory count
+- README component table and skill listing stay internally consistent with the README's own taxonomy
+- JSON files remain valid
+- README skill listing includes ce:ideate
+
+**Verification:**
+- `grep -o "Includes [0-9]* specialized agents" plugins/compound-engineering/.claude-plugin/plugin.json` matches actual agent count
+- Manifest-facing skill count matches the number of skill directories under `plugins/compound-engineering/skills/`
+- README counts and tables are internally consistent, even if they intentionally differ from manifest-facing skill-directory totals
+- `jq . < .claude-plugin/marketplace.json` succeeds
+- `jq . < plugins/compound-engineering/.claude-plugin/plugin.json` succeeds
+
+---
+
+- [x] **Unit 3: Refresh generated docs artifacts if the local docs workflow produces tracked changes**
+
+**Goal:** Keep generated documentation outputs in sync without inventing source-of-truth files that are not present in the current tree.
+
+**Requirements:** R1 (skill visible in docs)
+
+**Dependencies:** Unit 2
+
+**Files:**
+- Modify (conditional): tracked files under `docs/` updated by the local docs release workflow, if any are produced in this checkout
+
+**Approach:**
+- Run the repo-maintenance docs regeneration workflow after the durable source files are updated
+- Review only the tracked artifacts it actually changes instead of assuming specific generated paths
+- If the local docs workflow produces no tracked changes in this checkout, stop without hand-editing guessed HTML files
+
+**Patterns to follow:**
+- CLAUDE.md: "After ANY change to agents, commands, skills, or MCP servers, run `/release-docs`"
+
+**Test scenarios:**
+- Generated docs, if present, pick up ce:ideate and updated counts from the durable sources
+- Docs regeneration does not introduce unrelated count drift across generated artifacts
+
+**Verification:**
+- Any tracked generated docs diffs are mechanically consistent with the updated plugin metadata and README
+- No manual HTML edits are invented for files absent from the working tree
+
+## System-Wide Impact
+
+- **Interaction graph:** `ce:ideate` sits before `ce:brainstorm` and calls into `repo-research-analyst`, `learnings-researcher`, the platform question tool, optional Proof sharing, and optional local commit flow. The plan has to preserve that this is an orchestration skill spanning multiple existing workflow seams rather than a standalone document generator.
+- **Error propagation:** Resume mismatches, write-before-present failures, or refine-in-place write failures can leave the ideation artifact out of sync with what the user saw. The skill should prefer conservative routing and explicit state updates over optimistic wording.
+- **State lifecycle risks:** `docs/ideation/` becomes a new durable state surface. Topic slugging, 30-day resume matching, refinement updates, and the "explored" marker for brainstorm handoff need stable rules so repeated runs do not create duplicate or contradictory ideation records.
+- **API surface parity:** Most targets can continue to rely on copied `skillDirs`, but Codex is now a special-case workflow surface for compound-engineering because of PR #277. `ce:ideate` needs parity with the canonical `ce:*` workflow model there: explicit prompt entrypoint, rewritten intra-workflow handoffs, and no deprecated alias duplication.
+- **Integration coverage:** Unit-level reading of the SKILL.md is not enough. Verification has to cover end-to-end workflow behavior: initial ideation, artifact persistence, resume/refine loops, and handoff to `ce:brainstorm` without dropping ideation state.
+
+## Risks & Dependencies
+
+- **Divergent ideation quality is hard to verify at planning time**: The self-prompting instructions for Phase 2 and Phase 3 are the novel design element. Their effectiveness depends on exact wording and how well Phase 1 findings are fed back into ideation. Mitigation: verify on the real repo with open and focused prompts, then tighten the prompt structure only where groundedness or rejection quality is weak.
+- **Artifact state drift across resume/refine/handoff**: The feature depends on updating the same ideation doc repeatedly. A weak state model could duplicate docs, lose "explored" markers, or present stale survivors after refinement. Mitigation: keep one canonical ideation file per session/topic and make every refine/handoff path explicitly update that file before returning control.
+- **Count taxonomy drift across docs and manifests**: This repo already uses different count semantics across surfaces. A naive "make every number match" implementation could either break manifest descriptions or distort the README taxonomy. Mitigation: validate each artifact against its own intended counting model and document that distinction in the plan.
+- **Dependency on PR #277 for Codex workflow correctness**: `ce:ideate` is another canonical `ce:*` workflow, so its Codex install surface should not regress to the old copied-skill-only behavior. Mitigation: land #277 first or explicitly include the same Codex workflow behavior before considering this feature complete.
+- **Local docs workflow dependency**: `/release-docs` is a repo-maintenance workflow, not part of the distributed plugin. Its generated outputs may differ by environment or may not produce tracked files in the current checkout. Mitigation: treat docs regeneration as conditional maintenance verification after durable source edits, not as the primary source of truth.
+- **Skill length**: Estimated ~300 lines. If the ideation and self-critique instructions need more detail, the skill could approach the 500-line limit. Mitigation: monitor during implementation and split to `references/` only if the final content genuinely needs it.
+
+## Documentation / Operational Notes
+
+- README.md gets updated in Unit 2
+- Generated docs artifacts are refreshed only if the local docs workflow produces tracked changes in this checkout
+- The local `release-docs` workflow exists as a Claude slash command in this repo, but it was not directly runnable from the shell environment used for this implementation pass
+- No CHANGELOG entry for this PR (per versioning requirements)
+- No version bumps (automated release process handles this)
+
+## Sources & References
+
+- **Origin document:** [docs/brainstorms/2026-03-15-ce-ideate-skill-requirements.md](docs/brainstorms/2026-03-15-ce-ideate-skill-requirements.md)
+- Related code: `plugins/compound-engineering/skills/ce-brainstorm/SKILL.md`, `plugins/compound-engineering/skills/ce-plan/SKILL.md`, `plugins/compound-engineering/skills/ce-work/SKILL.md`
+- Related institutional learning: `docs/solutions/plugin-versioning-requirements.md`
+- Related PR: #277 (`fix: codex workflow conversion for compound-engineering`) — upstream Codex workflow model this plan now depends on
+- Related institutional learning: `docs/solutions/codex-skill-prompt-entrypoints.md`

docs/plans/2026-03-16-001-feat-issue-grounded-ideation-plan.md

@@ -0,0 +1,246 @@
+---
+title: "feat: Add issue-grounded ideation mode to ce:ideate"
+type: feat
+status: complete
+date: 2026-03-16
+origin: docs/brainstorms/2026-03-16-issue-grounded-ideation-requirements.md
+---
+
+# feat: Add issue-grounded ideation mode to ce:ideate
+
+## Overview
+
+Add an issue intelligence agent and integrate it into ce:ideate so that when a user's argument indicates they want issue-tracker data as input, the skill fetches, clusters, and analyzes GitHub issues — then uses the resulting themes to drive ideation frames. The agent is also independently useful outside ce:ideate for understanding a project's issue landscape.
+
+## Problem Statement / Motivation
+
+ce:ideate currently grounds ideation in codebase context and past learnings only. Teams' issue trackers hold rich signal about real user pain, recurring failures, and severity patterns that ideation misses. The goal is strategic improvement ideas grounded in bug patterns ("invest in collaboration reliability") not individual bug fixes ("fix LIVE_DOC_UNAVAILABLE").
+
+(See brainstorm: docs/brainstorms/2026-03-16-issue-grounded-ideation-requirements.md — R1-R9)
+
+## Proposed Solution
+
+Two deliverables:
+
+1. **New agent**: `issue-intelligence-analyst` in `agents/research/` — fetches GitHub issues via `gh` CLI, clusters by theme, returns structured analysis. Standalone-capable.
+2. **ce:ideate modifications**: detect issue-tracker intent in arguments, dispatch the agent as a third Phase 1 scan, derive Phase 2 ideation frames from issue clusters using a hybrid strategy.
+
+## Technical Approach
+
+### Deliverable 1: Issue Intelligence Analyst Agent
+
+**File**: `plugins/compound-engineering/agents/research/ce-issue-intelligence-analyst.agent.md`
+
+**Frontmatter:**
+```yaml
+---
+name: issue-intelligence-analyst
+description: "Fetches and analyzes GitHub issues to surface recurring themes, pain patterns, and severity trends. Use when understanding a project's issue landscape, analyzing bug patterns for ideation, or summarizing what users are reporting."
+model: inherit
+---
+```
+
+**Agent methodology (in execution order):**
+
+1. **Precondition checks** — verify in order, fail fast with clear message on any failure:
+   - Current directory is a git repo
+   - A GitHub remote exists (prefer `upstream` over `origin` to handle fork workflows)
+   - `gh` CLI is installed
+   - `gh auth status` succeeds
+
+2. **Fetch issues** — priority-aware, minimal fields (no bodies, no comments):
+
+   **Priority-aware open issue fetching:**
+   - First, scan available labels to detect priority signals: `gh label list --json name --limit 100`
+   - If priority/severity labels exist (e.g., `P0`, `P1`, `priority:critical`, `severity:high`, `urgent`):
+     - Fetch high-priority issues first: `gh issue list --state open --label "{high-priority-labels}" --limit 50 --json number,title,labels,createdAt`
+     - Backfill with remaining issues up to 100 total: `gh issue list --state open --limit 100 --json number,title,labels,createdAt` (deduplicate against already-fetched)
+     - This ensures the 50 P0s in a 500-issue repo are always analyzed, not buried under 100 recent P3s
+   - If no priority labels detected, fetch by recency (default `gh` sort) up to 100: `gh issue list --state open --limit 100 --json number,title,labels,createdAt`
+
+   **Recently closed issues:**
+   - `gh issue list --state closed --limit 50 --json number,title,labels,createdAt,stateReason,closedAt` — filter client-side to last 30 days, exclude `stateReason: "not_planned"` and issues with labels matching common won't-fix patterns (`wontfix`, `won't fix`, `duplicate`, `invalid`, `by design`)
+
+3. **First-pass clustering** — the core analytical step. Group issues into themes that represent **areas of systemic weakness or user pain**, not individual bugs. This is what makes the agent's output valuable.
+
+   **Clustering approach:**
+   - Start with labels as strong clustering hints when present (e.g., `subsystem:collab` groups collaboration issues). When labels are absent or inconsistent, cluster by title similarity and inferred problem domain.
+   - Cluster by **root cause or system area**, not by symptom. Example from proof repo: 25 issues mentioning `LIVE_DOC_UNAVAILABLE` and 5 mentioning `PROJECTION_STALE` are symptoms — the theme is "collaboration write path reliability." Cluster at the system level, not the error-message level.
+   - Issues that span multiple themes should be noted in the primary cluster with a cross-reference, not duplicated across clusters.
+   - Distinguish issue sources when relevant: bot/agent-generated issues (e.g., `agent-report` label) often have different signal quality than human-reported issues. Note the source mix per cluster — a theme with 25 agent reports and 0 human reports is different from one with 5 human reports and 2 agent reports.
+   - Separate bugs from enhancement requests. Both are valid input but represent different kinds of signal (current pain vs. desired capability).
+   - Aim for 3-8 themes. Fewer than 3 suggests the issues are too homogeneous or the repo has few issues. More than 8 suggests the clustering is too granular — merge related themes.
+
+   **What makes a good cluster:**
+   - It names a systemic concern, not a specific error or ticket
+   - A product or engineering leader would recognize it as "an area we need to invest in"
+   - It's actionable at a strategic level (could drive an initiative, not just a patch)
+
+4. **Sample body reads** — for each emerging cluster, read the full body of 2-3 representative issues (most recent or most reacted) using individual `gh issue view {number} --json body` calls. Use these to:
+   - Confirm the cluster grouping is correct (titles can be misleading)
+   - Understand the actual user/operator experience behind the symptoms
+   - Identify severity and impact signals not captured in metadata
+   - Surface any proposed solutions or workarounds already discussed
+
+5. **Theme synthesis** — for each cluster, produce:
+   - `theme_title`: short descriptive name
+   - `description`: what the pattern is and what it signals about the system
+   - `why_it_matters`: user impact, severity distribution, frequency
+   - `issue_count`: number of issues in this cluster
+   - `trend_direction`: increasing/stable/decreasing (compare issues opened vs closed in last 30 days within the cluster)
+   - `representative_issues`: top 3 issue numbers with titles
+   - `confidence`: high/medium/low based on label consistency and cluster coherence
+
+6. **Return structured output** — themes ordered by issue count (descending), plus a summary line with total issues analyzed, cluster count, and date range covered.
+
+**Output format (returned to caller):**
+
+```markdown
+## Issue Intelligence Report
+
+**Repo:** {owner/repo}
+**Analyzed:** {N} open + {M} recently closed issues ({date_range})
+**Themes identified:** {K}
+
+### Theme 1: {theme_title}
+**Issues:** {count} | **Trend:** {increasing/stable/decreasing} | **Confidence:** {high/medium/low}
+
+{description — what the pattern is and what it signals}
+
+**Why it matters:** {user impact, severity, frequency}
+
+**Representative issues:** #{num} {title}, #{num} {title}, #{num} {title}
+
+### Theme 2: ...
+
+### Minor / Unclustered
+{Issues that didn't fit any theme, with a brief note}
+```
+
+This format is human-readable (standalone use) and structured enough for orchestrator consumption (ce:ideate use).
+
+**Data source priority:**
+1. **`gh` CLI (preferred)** — most reliable, works in all terminal environments, no MCP dependency
+2. **GitHub MCP server** (fallback) — if `gh` is unavailable but a GitHub MCP server is connected, use its issue listing/reading tools instead. The clustering logic is identical; only the fetch mechanism changes.
+
+If neither is available, fail gracefully per precondition checks.
+
+**Token-efficient fetching:**
+
+The agent runs as a sub-agent with its own context window. Every token of fetched issue data competes with the space needed for clustering reasoning. Minimize input, maximize analysis.
+
+- **Metadata pass (all issues):** Fetch only the fields needed for clustering: `--json number,title,labels,createdAt,stateReason,closedAt`. Omit `body`, `comments`, `assignees`, `milestone` — these are expensive and not needed for initial grouping.
+- **Body reads (samples only):** After clusters emerge, fetch full bodies for 2-3 representative issues per cluster using individual `gh issue view {number} --json body` calls. Pick the most reacted or most recent issue in each cluster.
+- **Never fetch all bodies in bulk.** 100 issue bodies could easily consume 50k+ tokens before any analysis begins.
+
+**Tool guidance** (per AGENTS.md conventions):
+- Use `gh` CLI for issue fetching (one simple command at a time, no chaining)
+- Use native file-search/glob for any repo exploration
+- Use native content-search/grep for label or pattern searches
+- Do not chain shell commands with `&&`, `||`, `;`, or pipes
+
+### Deliverable 2: ce:ideate Skill Modifications
+
+**File**: `plugins/compound-engineering/skills/ce-ideate/SKILL.md`
+
+Four targeted modifications:
+
+#### Mod 1: Phase 0.2 — Add issue-tracker intent detection
+
+After the existing focus context and volume override interpretation, add a third inference:
+
+- **Issue-tracker intent** — detect when the user wants issue data as input
+
+The detection uses the same "reasonable interpretation rather than formal parsing" approach as the existing volume hints. Trigger on arguments whose intent is clearly about issue/bug analysis: `bugs`, `github issues`, `open issues`, `issue patterns`, `what users are reporting`, `bug reports`.
+
+Do NOT trigger on arguments that merely mention bugs as a focus: `bug in auth`, `fix the login issue` — these are focus hints.
+
+When combined with other dimensions (e.g., `top 3 bugs in authentication`): parse issue trigger first, volume override second, remainder is focus hint. The focus hint narrows which issues matter; the volume override controls survivor count.
+
+#### Mod 2: Phase 1 — Add third parallel agent
+
+Add a third numbered item to the Phase 1 parallel dispatch:
+
+```
+3. **Issue intelligence** (conditional) — if issue-tracker intent was detected in Phase 0.2,
+   dispatch `compound-engineering:research:issue-intelligence-analyst` with the focus hint.
+   If a focus hint is present, pass it so the agent can weight its clustering.
+```
+
+Update the grounding summary consolidation to include a separate **Issue Intelligence** section (distinct from codebase context) so that ideation sub-agents can distinguish between code-observed and user-reported pain points.
+
+If the agent returns an error (gh not installed, no remote, auth failure), log a warning to the user ("Issue analysis unavailable: {reason}. Proceeding with standard ideation.") and continue with the existing two-agent grounding.
+
+If the agent returns fewer than 5 issues total, note "Insufficient issue signal for theme analysis" and proceed with default ideation.
+
+#### Mod 3: Phase 2 — Dynamic frame derivation
+
+Add conditional logic before the existing frame assignment (step 8):
+
+When issue-tracker intent is active and the issue intelligence agent returned themes:
+- Each theme with `confidence: high` or `confidence: medium` becomes an ideation frame. The frame prompt uses the theme title and description as the starting bias.
+- If fewer than 4 cluster-derived frames, pad with default frames selected in order: "leverage and compounding effects", "assumption-breaking or reframing", "inversion, removal, or automation of a painful step" (these complement issue-grounded themes best by pushing beyond the reported problems).
+- Cap at 6 total frames (if more than 6 themes, use the top 6 by issue count; remaining themes go into the grounding summary as "minor themes").
+
+When issue-tracker intent is NOT active: existing behavior unchanged.
+
+#### Mod 4: Phase 0.1 — Resume awareness
+
+When checking for recent ideation documents, treat issue-grounded and non-issue ideation as distinct topics. An existing `docs/ideation/YYYY-MM-DD-open-ideation.md` should not be offered as a resume candidate when the current argument indicates issue-tracker intent, and vice versa.
+
+### Files Changed
+
+| File | Change |
+|------|--------|
+| `agents/research/issue-intelligence-analyst.md` | **New file** — the agent |
+| `skills/ce-ideate/SKILL.md` | **Modified** — 4 targeted modifications (Phase 0.1, 0.2, 1, 2) |
+| `.claude-plugin/plugin.json` | **Modified** — increment agent count, add agent to list, update description |
+| `../../.claude-plugin/marketplace.json` | **Modified** — update description with new agent count |
+| `README.md` | **Modified** — add agent to research agents table |
+
+### Not Changed
+
+- Phase 3 (adversarial filtering) — unchanged
+- Phase 4 (presentation) — unchanged, survivors already include a one-line overview
+- Phase 5 (artifact) — unchanged, the grounding summary naturally includes issue context
+- Phase 6 (refine/handoff) — unchanged
+- No other agents modified
+- No new skills
+
+## Acceptance Criteria
+
+- [ ] New agent file exists at `agents/research/issue-intelligence-analyst.md` with correct frontmatter
+- [ ] Agent handles precondition failures gracefully (no gh, no remote, no auth) with clear messages
+- [ ] Agent handles fork workflows (prefers upstream remote over origin)
+- [ ] Agent uses priority-aware fetching (scans for priority/severity labels, fetches high-priority first)
+- [ ] Agent caps fetching at 100 open + 50 recently closed issues
+- [ ] Agent falls back to GitHub MCP when `gh` CLI is unavailable but MCP is connected
+- [ ] Agent clusters issues into themes, not individual bug reports
+- [ ] Agent reads 2-3 sample bodies per cluster for enrichment
+- [ ] Agent output includes theme title, description, why_it_matters, issue_count, trend, representative issues, confidence
+- [ ] Agent is independently useful when dispatched directly (not just as ce:ideate sub-agent)
+- [ ] ce:ideate detects issue-tracker intent from arguments like `bugs`, `github issues`
+- [ ] ce:ideate does NOT trigger issue mode on focus hints like `bug in auth`
+- [ ] ce:ideate dispatches issue intelligence agent as third parallel Phase 1 scan when triggered
+- [ ] ce:ideate falls back to default ideation with warning when agent fails
+- [ ] ce:ideate derives ideation frames from issue clusters (hybrid: clusters + default padding)
+- [ ] ce:ideate caps at 6 frames, padding with defaults when < 4 clusters
+- [ ] Running `/ce:ideate bugs` on proof repo produces clustered themes from 25+ LIVE_DOC_UNAVAILABLE variants, not 25 separate ideas
+- [ ] Surviving ideas are strategic improvements, not individual bug fixes
+- [ ] plugin.json, marketplace.json, README.md updated with correct counts
+
+## Dependencies & Risks
+
+- **`gh` CLI dependency**: The agent requires `gh` installed and authenticated. Mitigated by graceful fallback to standard ideation.
+- **Issue volume**: Repos with thousands of issues could produce noisy clusters. Mitigated by fetch cap (100 open + 50 closed) and frame cap (6 max).
+- **Label quality variance**: Repos without structured labels rely on title/body clustering, which may produce lower-confidence themes. Mitigated by the confidence field and sample body reads.
+- **Context window**: Fetching 150 issues + reading 15-20 bodies could consume significant tokens in the agent's context. Mitigated by metadata-only initial fetch and sample-only body reads.
+- **Priority label detection**: No standard naming convention. Mitigated by scanning available labels and matching common patterns (P0/P1, priority:*, severity:*, urgent, critical). When no priority labels exist, falls back to recency-based fetching.
+
+## Sources & References
+
+- **Origin brainstorm:** [docs/brainstorms/2026-03-16-issue-grounded-ideation-requirements.md](docs/brainstorms/2026-03-16-issue-grounded-ideation-requirements.md) — Key decisions: pattern-first ideation, hybrid frame strategy, flexible argument detection, additive to Phase 1, standalone agent
+- **Exemplar agent:** `plugins/compound-engineering/agents/research/ce-repo-research-analyst.agent.md` — agent structure pattern
+- **ce:ideate skill:** `plugins/compound-engineering/skills/ce-ideate/SKILL.md` — integration target
+- **Institutional learning:** `docs/solutions/skill-design/compound-refresh-skill-improvements.md` — impact clustering pattern, platform-agnostic tool references, evidence-first interaction
+- **Real-world test repo:** `EveryInc/proof` (555 issues, 25+ LIVE_DOC_UNAVAILABLE duplicates, structured labels)

docs/plans/2026-03-17-001-feat-release-automation-migration-beta-plan.md

@@ -0,0 +1,605 @@
+---
+title: "feat: Migrate repo releases to manual release-please with centralized changelog"
+type: feat
+status: active
+date: 2026-03-17
+origin: docs/brainstorms/2026-03-17-release-automation-requirements.md
+---
+
+# feat: Migrate repo releases to manual release-please with centralized changelog
+
+## Overview
+
+Replace the current single-line `semantic-release` flow and maintainer-local `release-docs` workflow with a repo-owned release system built around `release-please`, a single accumulating release PR, explicit component version ownership, release automation-owned metadata/count updates, and a centralized root `CHANGELOG.md`. The new model keeps release timing manual by making merge of the generated release PR the release action while allowing dry-run previews and automatic release PR maintenance as new merges land on `main`.
+
+## Problem Frame
+
+The current repo mixes one automated root CLI release line with manual plugin release conventions and stale docs/tooling. `publish.yml` publishes on every push to `main`, `.releaserc.json` only understands the root package, `release-docs` still encodes outdated repo structure, and plugin-level version/changelog ownership is inconsistent. The result is drift across root changelog history, plugin manifests, computed counts, and contributor guidance. The origin requirements define a different target: manual release timing, one release PR for the whole repo, independent component versions, no bumps for untouched plugins, centralized changelog ownership, and CI-owned release authority. (see origin: docs/brainstorms/2026-03-17-release-automation-requirements.md)
+
+## Requirements Trace
+
+- R1. Manual release; no publish on every merge to `main`
+- R2. Batched releasable changes may accumulate on `main`
+- R3. One release PR for the whole repo that auto-accumulates releasable merges
+- R4. Independent version bumps for `cli`, `compound-engineering`, `coding-tutor`, and `marketplace`
+- R5. Untouched components do not bump
+- R6. Root `CHANGELOG.md` remains canonical
+- R7. Root changelog uses top-level component-version entries
+- R8. Existing changelog history is preserved
+- R9. `plugins/compound-engineering/CHANGELOG.md` is no longer canonical
+- R10. Retire `release-docs` as release authority
+- R11. Replace `release-docs` with narrow scripts
+- R12. Release automation owns versions, counts, and release metadata
+- R13. Support dry run with no side effects
+- R14. Dry run summarizes proposed component bumps, changelog entries, and blockers
+- R15. Marketplace version bumps only for marketplace-level changes
+- R16. Plugin version changes do not imply marketplace version bumps
+- R17. Plugin-only content changes do not force CLI version bumps
+- R18. Preserve compatibility with current install behavior where the npm CLI fetches plugin content from GitHub at runtime
+- R19. Release flow is triggerable through CI by maintainers or AI agents
+- R20. The model must scale to additional plugins
+- R21. Conventional release intent signals remain required, but component scopes in titles remain optional
+- R22. Component ownership is inferred primarily from changed files, not title scopes alone
+- R23. The repo enforces parseable conventional PR or merge titles without requiring component scope on every change
+- R24. Manual CI release supports explicit bump overrides for exceptional cases without fake commits
+- R25. Bump overrides are per-component rather than repo-wide only
+- R26. Dry run shows inferred bump and applied override clearly
+
+## Scope Boundaries
+
+- No change to how Claude Code consumes marketplace/plugin version fields
+- No end-user auto-update discovery flow for non-Claude harnesses in v1
+- No per-plugin canonical changelog model
+- No fully automatic timed release cadence in v1
+
+## Context & Research
+
+### Relevant Code and Patterns
+
+- `.github/workflows/publish.yml` currently runs `npx semantic-release` on every push to `main`; this is the behavior being retired.
+- `.releaserc.json` is the current single-line release configuration and only writes `CHANGELOG.md` and `package.json`.
+- `package.json` already exposes repo-maintenance scripts and is the natural place to add release preview/validation script entrypoints.
+- `src/commands/install.ts` resolves named plugin installs by cloning the GitHub repo and reading `plugins/<name>` at runtime; this means plugin content releases can remain independent from npm CLI releases when CLI code is unchanged.
+- `.claude-plugin/marketplace.json`, `plugins/compound-engineering/.claude-plugin/plugin.json`, and `plugins/coding-tutor/.claude-plugin/plugin.json` are the current version-bearing metadata surfaces that need explicit ownership.
+- `.claude/commands/release-docs.md` is stale and mixes docs generation, metadata synchronization, validation, and release guidance; it should be replaced rather than modernized in place.
+- Existing planning docs in `docs/plans/` use one file per plan, frontmatter with `origin`, and dependency-ordered implementation units with explicit file paths; this plan follows that pattern.
+
+### Institutional Learnings
+
+- `docs/solutions/plugin-versioning-requirements.md` already encodes an important constraint: version bumps and changelog entries should be release-owned, not added in routine feature PRs. The migration should preserve that principle while moving the authority into CI.
+
+### External References
+
+- `release-please` release PR model supports maintaining a standing release PR that updates as more work lands on the default branch.
+- `release-please` manifest mode supports multi-component repos and per-component extra file updates, which is a strong fit for plugin manifests and marketplace metadata.
+- GitHub Actions `workflow_dispatch` provides a stable manual trigger surface for dry-run preview workflows.
+
+## Key Technical Decisions
+
+- **Use `release-please` for version planning and release PR lifecycle**: The repo needs one accumulating release PR with multiple independently versioned components; that is closer to `release-please`'s native model than to `semantic-release`.
+- **Keep one centralized root changelog**: The root `CHANGELOG.md` remains the canonical changelog. Release automation must render component-labeled entries into that one file rather than splitting canonical history across plugin-local changelog files.
+- **Use top-level component-version entries in the root changelog**: Each released component version gets its own top-level entry in `CHANGELOG.md`, including the component name, version, and release date in the heading. This keeps one centralized file while preserving readable independent version history.
+- **Treat component versioning and changelog rendering as related but separate concerns**: `release-please` can own component version bumps and release PR state, but root changelog formatting may require repo-specific rendering logic to preserve a single readable canonical file.
+- **Use explicit release scripts for repo-specific logic**: Count computation, metadata sync, dry-run summaries, and root changelog shaping should live in versioned scripts rather than hidden maintainer-local command prompts.
+- **Preserve current plugin delivery assumptions**: Plugin content updates do not force CLI version bumps unless the converter/installer behavior in `src/` changes.
+- **Marketplace is catalog-scoped**: Marketplace version bumps depend on marketplace file changes such as plugin additions/removals or marketplace metadata edits, not routine plugin release version updates.
+- **Use conventional type as release intent, not mandatory component scope**: `feat`, `fix`, and explicit breaking-change markers remain important release signals, but component scope in PR or merge titles is optional and should not be required for common compound-engineering work.
+- **File ownership is authoritative for component selection**: Optional title scope can help notes and validation, but changed-file ownership rules should decide which components bump.
+- **Support manual bump overrides as an explicit escape hatch**: Inferred bumping remains the default, but the CI-driven release flow should allow per-component `patch` / `minor` / `major` overrides for exceptional cases without requiring synthetic commits on `main`.
+- **Deprecate, do not rely on, legacy changelog/docs surfaces**: `plugins/compound-engineering/CHANGELOG.md` and `release-docs` should stop being live authorities; they should be removed, frozen, or reduced to pointer guidance only after the new flow is in place.
+
+## Root Changelog Format
+
+The root `CHANGELOG.md` should remain the only canonical changelog and should use component-version entries rather than repo-wide release-event entries.
+
+### Format Rules
+
+- Each released component gets its own top-level entry.
+- Entry headings include the component name, version, and release date.
+- Entries are ordered newest-first in the single root file.
+- When multiple components release from the same merged release PR, they appear as adjacent entries with the same date.
+- Each entry contains only changes relevant to that component.
+- The file keeps a short header note explaining that it is the canonical changelog for the repo and that versions are component-scoped.
+- Historical root changelog entries remain in place; the migration adds a note and changes formatting only for new entries after cutover.
+
+### Recommended Heading Shape
+
+```md
+## compound-engineering v2.43.0 - 2026-04-10
+
+### Features
+- ...
+
+### Fixes
+- ...
+```
+
+Additional examples:
+
+```md
+## coding-tutor v1.2.2 - 2026-04-18
+
+### Fixes
+- ...
+
+## marketplace v1.3.0 - 2026-04-18
+
+### Changed
+- Added `new-plugin` to the marketplace catalog.
+
+## cli v2.43.1 - 2026-04-21
+
+### Fixes
+- Correct OpenClaw install path handling.
+```
+
+### Migration Rules
+
+- Preserve all existing root changelog history as published.
+- Add a short migration note near the top stating that, starting with the cutover release, entries are recorded per component version in the root file.
+- Do not attempt to rewrite or normalize all older entries into the new structure.
+- `plugins/compound-engineering/CHANGELOG.md` should no longer receive new canonical entries after cutover.
+
+## Component Release Rules
+
+The release system should use explicit file-to-component ownership rules so unchanged components do not bump accidentally.
+
+### Component Definitions
+
+- **`cli`**: The npm-distributed `@every-env/compound-plugin` package and its release-owned root metadata.
+- **`compound-engineering`**: The plugin rooted at `plugins/compound-engineering/`.
+- **`coding-tutor`**: The plugin rooted at `plugins/coding-tutor/`.
+- **`marketplace`**: Marketplace-level metadata rooted at `.claude-plugin/` and any future repo-owned marketplace-only surfaces.
+
+### File-to-Component Mapping
+
+#### `cli`
+
+Changes that should trigger a `cli` release:
+
+- `src/**`
+- `package.json`
+- `bun.lock`
+- CLI-only tests or fixtures that validate root CLI behavior:
+  - `tests/cli.test.ts`
+  - other top-level tests whose subject is the CLI itself
+- Release-owned root files only when they reflect a CLI release rather than another component:
+  - root `CHANGELOG.md` entry generation for the `cli` component
+
+Changes that should **not** trigger `cli` by themselves:
+
+- Plugin content changes under `plugins/**`
+- Marketplace metadata changes under `.claude-plugin/**`
+- Docs or brainstorm/plan documents unless the repo explicitly decides docs-only changes are releasable for the CLI
+
+#### `compound-engineering`
+
+Changes that should trigger a `compound-engineering` release:
+
+- `plugins/compound-engineering/**`
+- Tests or fixtures whose primary purpose is validating compound-engineering content or conversion results derived from that plugin
+- Release-owned metadata updates for the compound-engineering plugin:
+  - `plugins/compound-engineering/.claude-plugin/plugin.json`
+- Root `CHANGELOG.md` entry generation for the `compound-engineering` component
+
+Changes that should **not** trigger `compound-engineering` by themselves:
+
+- `plugins/coding-tutor/**`
+- Root CLI implementation changes in `src/**`
+- Marketplace-only metadata changes
+
+#### `coding-tutor`
+
+Changes that should trigger a `coding-tutor` release:
+
+- `plugins/coding-tutor/**`
+- Tests or fixtures whose primary purpose is validating coding-tutor content or conversion results derived from that plugin
+- Release-owned metadata updates for the coding-tutor plugin:
+  - `plugins/coding-tutor/.claude-plugin/plugin.json`
+- Root `CHANGELOG.md` entry generation for the `coding-tutor` component
+
+Changes that should **not** trigger `coding-tutor` by themselves:
+
+- `plugins/compound-engineering/**`
+- Root CLI implementation changes in `src/**`
+- Marketplace-only metadata changes
+
+#### `marketplace`
+
+Changes that should trigger a `marketplace` release:
+
+- `.claude-plugin/marketplace.json`
+- Future marketplace-only docs or config files if the repo later introduces them
+- Adding a new plugin directory under `plugins/` when that addition is accompanied by marketplace catalog changes
+- Removing a plugin from the marketplace catalog
+- Marketplace metadata changes such as owner info, catalog description, or catalog-level structure changes
+
+Changes that should **not** trigger `marketplace` by themselves:
+
+- Routine version bumps to existing plugin manifests
+- Plugin-only content changes under `plugins/compound-engineering/**` or `plugins/coding-tutor/**`
+- Root CLI implementation changes in `src/**`
+
+### Multi-Component Rules
+
+- A single merged PR may trigger multiple components when it changes files owned by each of those components.
+- A plugin content change plus a CLI behavior change should release both the plugin and `cli`.
+- Adding a new plugin should release at least the new plugin and `marketplace`; it should release `cli` only if the CLI behavior, plugin discovery logic, or install UX also changed.
+- Root `CHANGELOG.md` should not itself be used as the primary signal for component detection; it is a release output, not an input.
+- Release-owned metadata writes generated by the release flow should not recursively cause unrelated component bumps on subsequent runs.
+
+### Release Intent Rules
+
+- The repo should continue to require conventional release intent markers such as `feat:`, `fix:`, and explicit breaking change notation.
+- Component scopes such as `feat(coding-tutor): ...` are optional and should remain optional.
+- When a scope is present, it should be treated as advisory metadata that can improve release note grouping or mismatch detection.
+- When no scope is present, release automation should still work correctly by using changed-file ownership to determine affected components.
+- Docs-only, planning-only, or maintenance-only titles such as `docs:` or `chore:` should remain parseable even when they do not imply a releasable component bump.
+
+### Manual Override Rules
+
+- Automatic bump inference remains the default for all components.
+- The manual CI workflow should support override values of at least `patch`, `minor`, and `major`.
+- Overrides should be selectable per component rather than only as one repo-wide override.
+- Overrides should be treated as exceptional operational controls, not the normal release path.
+- When an override is present, release output should show both:
+  - inferred bump
+  - override-applied bump
+- Overrides should affect the prepared release state without requiring maintainers to add fake commits to `main`.
+
+### Ambiguity Resolution Rules
+
+- If a file exists primarily to support one plugin's content or fixtures, map it to that plugin rather than to `cli`.
+- If a shared utility in `src/` changes behavior for all installs/conversions, treat it as a `cli` change even if the immediate motivation came from one plugin.
+- If a change only updates docs, brainstorms, plans, or repo instructions, default to no release unless the repo intentionally adds docs-only release semantics later.
+- When a new plugin is introduced in the future, add it as its own explicit component rather than folding it into `marketplace` or `cli`.
+
+## Release Workflow Behavior
+
+The release flow should have three distinct modes that share the same component-detection and metadata-rendering logic.
+
+### Release PR Maintenance
+
+- Runs automatically on pushes to `main`.
+- Creates one release PR for the repo if none exists.
+- Updates the existing open release PR when additional releasable changes land on `main`.
+- Includes only components selected by release-intent parsing plus file ownership rules.
+- Updates release-owned files only on the release PR branch, not directly on `main`.
+- Never publishes npm, creates final GitHub releases, or tags versions as part of this maintenance step.
+
+The maintained release PR should make these outputs visible:
+- component version bumps
+- draft root changelog entries
+- release-owned metadata changes such as plugin version fields and computed counts
+
+### Manual Dry Run
+
+- Runs only through `workflow_dispatch`.
+- Computes the same release result the current open release PR would contain, or would create if none exists.
+- Produces a human-readable summary in workflow output and optionally an artifact.
+- Validates component ownership, conventional release intent, metadata sync, count updates, and root changelog rendering.
+- Does not push commits, create or update branches, merge PRs, publish packages, create tags, or create GitHub releases.
+
+The dry-run summary should include:
+- detected releasable components
+- current version -> proposed version for each component
+- draft root changelog entries
+- metadata files that would change
+- blocking validation failures and non-blocking warnings
+
+### Actual Release Execution
+
+- Happens only when the generated release PR is intentionally merged.
+- The merge writes the release-owned version and changelog changes into `main`.
+- Post-merge release automation then performs publish steps only for components included in that merged release.
+- npm publish runs only when the `cli` component is part of the merged release.
+- Non-CLI component releases still update canonical version surfaces and release notes even when no npm publish occurs.
+
+### Safety Rules
+
+- Ordinary feature merges to `main` must never publish by themselves.
+- Dry run must remain side-effect free.
+- Release PR maintenance, dry run, and post-merge release must use the same underlying release-state computation.
+- Release-generated version and metadata writes must not recursively trigger a follow-up release that contains only its own generated churn.
+- The release PR merge remains the auditable manual boundary; do not replace it with direct-to-main release commits from a manual workflow.
+
+## Open Questions
+
+### Resolved During Planning
+
+- **Should release timing remain manual?** Yes. The release PR may be maintained automatically, but release happens only when the generated release PR is intentionally merged.
+- **Should the release PR update automatically as more merges land on `main`?** Yes. This is a core batching behavior and should remain automatic.
+- **Should release preview be distinct from release execution?** Yes. Dry run should be a side-effect-free manual workflow that previews the same release state without mutating branches or publishing anything.
+- **Should root changelog history stay centralized?** Yes. The root `CHANGELOG.md` remains canonical to avoid fragmented history.
+- **What changelog structure best fits the centralized model?** Top-level component-version entries in the root changelog are the preferred format. This keeps the file centralized while making independent version history readable.
+- **What should drive component bumps?** Explicit file-to-component ownership rules. `src/**` drives `cli`, each `plugins/<name>/**` tree drives its own plugin, and `.claude-plugin/marketplace.json` drives `marketplace`.
+- **How strict should conventional formatting be?** Conventional type should be required strongly enough for release tooling and release-note generation, but component scope should remain optional to match the repo's work style.
+- **Should exceptional manual bumping be supported?** Yes. The release workflow should expose per-component patch/minor/major override controls rather than forcing synthetic commits to manipulate inferred versions.
+- **Should marketplace version bump when only a listed plugin version changes?** No. Marketplace bumps are reserved for marketplace-level changes.
+- **Should `release-docs` remain part of release authority?** No. It should be retired and replaced with narrow scripts.
+
+### Deferred to Implementation
+
+- What exact combination of `release-please` config and custom post-processing yields the chosen root changelog output without fighting the tool too hard?
+- Should conventional-format enforcement happen on PR titles, squash-merge titles, commit messages, or a combination of them?
+- Should `plugins/compound-engineering/CHANGELOG.md` be deleted outright or replaced with a short pointer note after the migration is stable?
+- Should release preview be implemented by invoking `release-please` in dry-run mode directly, or by a repo-owned script that computes the same summary from component rules and current git state?
+- Should final post-merge release execution live in a dedicated publish workflow keyed off merged release PR state, or remain in a renamed/adapted version of the current `publish.yml`?
+- Should override inputs be encoded directly into release workflow inputs only, or also persisted into the generated release PR body for auditability?
+
+## Implementation Units
+
+- [x] **Unit 1: Define the new release component model and config scaffolding**
+
+**Goal:** Replace the single-line semantic-release configuration with release-please-oriented repo configuration that expresses the four release components and their version surfaces.
+
+**Requirements:** R1, R3, R4, R5, R15, R16, R17, R20
+
+**Dependencies:** None
+
+**Files:**
+- Create: `.release-please-config.json`
+- Create: `.release-please-manifest.json`
+- Modify: `package.json`
+- Modify: `.github/workflows/publish.yml`
+- Delete or freeze: `.releaserc.json`
+
+**Approach:**
+- Define components for `cli`, `compound-engineering`, `coding-tutor`, and `marketplace`.
+- Use manifest configuration so version lines are independent and untouched components do not bump.
+- Rework the existing publish workflow so it no longer releases on every push to `main` and instead supports the release-please-driven model.
+- Add package scripts for release preview, metadata sync, and validation so CI can call stable entrypoints instead of embedding release logic inline.
+- Define the repo's release-intent contract: conventional type required, breaking changes explicit, component scope optional, file ownership authoritative.
+- Define the override contract: per-component `auto | patch | minor | major`, with `auto` as the default.
+
+**Patterns to follow:**
+- Existing repo-level config files at the root (`package.json`, `.releaserc.json`, `.github/workflows/*.yml`)
+- Current release ownership documented in `docs/solutions/plugin-versioning-requirements.md`
+
+**Test scenarios:**
+- A plugin-only change maps to that plugin component without implying CLI or marketplace bump.
+- A marketplace metadata/catalog change maps to marketplace only.
+- A `src/` CLI behavior change maps to the CLI component.
+- A combined change yields multiple component updates inside one release PR.
+- A title like `fix: adjust ce:plan-beta wording` remains valid without component scope and still produces the right component mapping from files.
+- A manual override can promote an inferred patch bump for one component to minor without affecting unrelated components.
+
+**Verification:**
+- The repo contains a single authoritative release configuration model for all versioned components.
+- The old automatic-on-push semantic-release path is removed or inert.
+- Package scripts exist for preview/sync/validate entrypoints.
+- Release intent rules are documented without forcing repetitive component scoping on routine CE work.
+
+- [x] **Unit 2: Build repo-owned release scripts for metadata sync, counts, and preview**
+
+**Goal:** Replace `release-docs` and ad-hoc release bookkeeping with explicit scripts that compute release-owned metadata updates and produce dry-run summaries.
+
+**Requirements:** R10, R11, R12, R13, R14, R18, R19
+
+**Dependencies:** Unit 1
+
+**Files:**
+- Create: `scripts/release/sync-metadata.ts`
+- Create: `scripts/release/render-root-changelog.ts`
+- Create: `scripts/release/preview.ts`
+- Create: `scripts/release/validate.ts`
+- Modify: `package.json`
+
+**Approach:**
+- `sync-metadata.ts` should own count calculation and synchronized writes to release-owned metadata fields such as manifest descriptions and version mirrors.
+- `render-root-changelog.ts` should generate the centralized root changelog entries in the agreed component-version format.
+- `preview.ts` should summarize proposed component bumps, generated changelog entries, affected files, and validation blockers without mutating the repo or publishing anything.
+- `validate.ts` should provide a stable CI check for component counts, manifest consistency, and changelog formatting expectations.
+- `preview.ts` should accept optional per-component overrides and display both inferred and effective bump levels in its summary output.
+
+**Patterns to follow:**
+- TypeScript/Bun scripting already used elsewhere in the repo
+- Root package scripts as stable repo entrypoints
+
+**Test scenarios:**
+- Count calculation updates plugin descriptions correctly when agents/skills change.
+- Preview output includes only changed components.
+- Preview mode performs no file writes.
+- Validation fails when manifest counts or version ownership rules drift.
+- Root changelog renderer produces component-version entries with stable ordering and headings.
+- Preview output clearly distinguishes inferred bump from override-applied bump when an override is used.
+
+**Verification:**
+- `release-docs` responsibilities are covered by explicit scripts.
+- Dry run can run in CI without side effects.
+- Metadata/count drift can be detected deterministically before release.
+
+- [x] **Unit 3: Wire release PR maintenance and manual release execution in CI**
+
+**Goal:** Establish one standing release PR for the repo that updates automatically as new releasable work lands, while keeping the actual release action manual.
+
+**Requirements:** R1, R2, R3, R13, R14, R19
+
+**Dependencies:** Units 1-2
+
+**Files:**
+- Create: `.github/workflows/release-pr.yml`
+- Create: `.github/workflows/release-preview.yml`
+- Modify: `.github/workflows/ci.yml`
+- Modify: `.github/workflows/publish.yml`
+
+**Approach:**
+- `release-pr.yml` should run on push to `main` and maintain the standing release PR for the whole repo.
+- The actual release event should remain merge of that generated release PR; no automatic publish should happen on ordinary merges to `main`.
+- `release-preview.yml` should use `workflow_dispatch` with explicit dry-run inputs and publish a human-readable summary to workflow logs and/or artifacts.
+- Decide whether npm publish remains in `publish.yml` or moves into the release-please-driven workflow, but ensure it runs only when the CLI component is actually releasing.
+- Keep normal `ci.yml` focused on verification, not publishing.
+- Add lightweight validation for release-intent formatting on PR or merge titles, without requiring component scopes.
+- Ensure release PR maintenance, dry run, and post-merge publish all call the same underlying release-state computation so they cannot drift.
+- Add workflow inputs for per-component bump overrides and ensure they can shape the prepared release state when explicitly invoked by a maintainer or AI agent.
+
+**Patterns to follow:**
+- Existing GitHub workflow layout in `.github/workflows/`
+- Current manual `workflow_dispatch` presence in `publish.yml`
+
+**Test scenarios:**
+- A normal merge to `main` updates or creates the release PR but does not publish.
+- A manual dry-run workflow produces a summary with no tags, commits, or publishes.
+- Merging the release PR results in release creation for changed components only.
+- A release that excludes CLI does not attempt npm publish.
+- A PR titled `feat: add new plan-beta handoff guidance` passes validation without a component scope.
+- A PR titled with an explicit contradictory scope can be surfaced as a warning or failure if file ownership clearly disagrees.
+- A second releasable merge to `main` updates the existing open release PR instead of creating a competing release PR.
+- A dry run executed while a release PR is open reports the same proposed component set and versions as the PR contents.
+- Merging a release PR does not immediately create a follow-up release PR containing only release-generated metadata churn.
+- A manual workflow can override one component to `major` while leaving other components on inferred `auto`.
+
+**Verification:**
+- Maintainers can inspect the current release PR to see the pending release batch.
+- Dry-run and actual-release paths are distinct and safe.
+- The release system is triggerable through CI without local maintainer-only tooling.
+- The same proposed release state is visible consistently across release PR maintenance, dry run, and post-merge release execution.
+- Exceptional release overrides are possible without synthetic commits on `main`.
+
+- [x] **Unit 4: Centralize changelog ownership and retire plugin-local canonical release history**
+
+**Goal:** Make the root changelog the only canonical changelog while preserving history and preventing future fragmentation.
+
+**Requirements:** R6, R7, R8, R9
+
+**Dependencies:** Units 1-3
+
+**Files:**
+- Modify: `CHANGELOG.md`
+- Modify or replace: `plugins/compound-engineering/CHANGELOG.md`
+- Optionally create: `plugins/coding-tutor/CHANGELOG.md` only if needed as a non-canonical pointer or future placeholder
+
+**Approach:**
+- Add a migration note near the top of the root changelog clarifying that it is the canonical changelog for the repo and future releases.
+- Render future canonical entries into the root file as top-level component-version entries using the agreed heading shape.
+- Stop writing future canonical entries into `plugins/compound-engineering/CHANGELOG.md`.
+- Replace the plugin-local changelog with either a short pointer note or a frozen historical file, depending on the least confusing path discovered during implementation.
+- Keep existing root changelog entries intact; do not attempt to rewrite historical releases into a new structure retroactively.
+
+**Patterns to follow:**
+- Existing Keep a Changelog-style root file
+- Brainstorm decision favoring centralized history over fragmented per-plugin changelogs
+
+**Test scenarios:**
+- Historical root changelog entries remain intact after migration.
+- New generated entries appear in the root changelog in the intended component-version format.
+- Multiple components released on the same day appear as separate adjacent entries rather than being merged into one release-event block.
+- Component-specific notes do not leak unrelated changes into the wrong entry.
+- Plugin-local CE changelog no longer acts as a live release target.
+
+**Verification:**
+- A maintainer reading the repo can identify one canonical changelog without ambiguity.
+- No history is lost or silently rewritten.
+
+- [x] **Unit 5: Remove legacy release guidance and replace it with the new authority model**
+
+**Goal:** Update repo instructions and docs so contributors follow the new release system rather than obsolete semantic-release or `release-docs` guidance.
+
+**Requirements:** R10, R11, R12, R19, R20
+
+**Dependencies:** Units 1-4
+
+**Files:**
+- Modify: `AGENTS.md`
+- Modify: `CLAUDE.md`
+- Modify: `plugins/compound-engineering/AGENTS.md`
+- Modify: `docs/solutions/plugin-versioning-requirements.md`
+- Delete: `.claude/commands/release-docs.md` or replace with a deprecation stub
+
+**Approach:**
+- Update all contributor-facing docs so they describe release PR maintenance, manual release merge, centralized root changelog ownership, and the new scripts for sync/preview/validate.
+- Remove references that tell contributors to run `release-docs` or to rely on stale docs-generation assumptions.
+- Keep the contributor rule that release-owned metadata should not be hand-bumped in ordinary PRs, but point that rule at release automation rather than a local maintainer slash command.
+- Document the release-intent policy explicitly: conventional type required, component scope optional, breaking changes explicit.
+
+**Patterns to follow:**
+- Existing contributor guidance files already used as authoritative workflow docs
+
+**Test scenarios:**
+- No user-facing doc still points to `release-docs` as a required release workflow.
+- No contributor guidance still claims plugin-local changelog authority for CE.
+- Release ownership guidance is consistent across root and plugin-level instruction files.
+
+**Verification:**
+- A new maintainer can understand the release process from docs alone without hidden local workflows.
+- Docs no longer encode obsolete repo structure or stale release surfaces.
+
+- [x] **Unit 6: Add automated coverage for component detection, metadata sync, and release preview**
+
+**Goal:** Protect the new release model against regression by testing the component rules, metadata updates, and preview behavior.
+
+**Requirements:** R4, R5, R12, R13, R14, R15, R16, R17
+
+**Dependencies:** Units 1-5
+
+**Files:**
+- Create: `tests/release-metadata.test.ts`
+- Create: `tests/release-preview.test.ts`
+- Create: `tests/release-components.test.ts`
+- Modify: `package.json`
+
+**Approach:**
+- Add fixture-driven tests for file-change-to-component mapping.
+- Snapshot or assert dry-run summaries for representative release cases.
+- Verify metadata sync updates only expected files and counts.
+- Cover the marketplace-specific rule so plugin-only version changes do not trigger marketplace bumps.
+- Encode ambiguity-resolution cases explicitly so future contributors can add new plugins without guessing which component should bump.
+- Add validation coverage for release-intent parsing so conventional titles remain required but optional scopes remain non-blocking when omitted.
+- Add override-path coverage so manual bump overrides remain scoped, visible, and side-effect free in preview mode.
+
+**Patterns to follow:**
+- Existing top-level Bun test files under `tests/`
+- Current fixture-driven testing style used by converters and writers
+
+**Test scenarios:**
+- Change only `plugins/coding-tutor/**` and confirm only `coding-tutor` bumps.
+- Change only `plugins/compound-engineering/**` and confirm only CE bumps.
+- Change only marketplace catalog metadata and confirm only marketplace bumps.
+- Change only `src/**` and confirm only CLI bumps.
+- Combined `src/**` + plugin change yields both component bumps.
+- Change docs only and confirm no component bumps by default.
+- Add a new plugin directory plus marketplace catalog entry and confirm new-plugin + marketplace bump without forcing unrelated existing plugin bumps.
+- Dry-run preview lists the same components that the component detector identifies.
+- Conventional `fix:` / `feat:` titles without scope pass validation.
+- Explicit breaking-change markers are recognized.
+- Optional scopes, when present, can be compared against file ownership without becoming mandatory.
+- Override one component in preview and confirm only that component's effective bump changes.
+- Override does not create phantom bumps for untouched components.
+
+**Verification:**
+- The release model is covered by automated tests rather than only CI trial runs.
+- Future plugin additions can follow the same component-detection pattern with low risk.
+
+## System-Wide Impact
+
+- **Interaction graph:** Release config, CI workflows, metadata-bearing JSON files, contributor docs, and changelog generation are all coupled. The plan deliberately separates configuration, scripting, release PR maintenance, and documentation cleanup so one layer can change without obscuring another.
+- **Error propagation:** Release metadata drift should fail in preview/validation before a release PR or publish path proceeds. CI needs clear failure reporting because release mistakes affect user-facing version surfaces.
+- **State lifecycle risks:** Partial migration is risky. Running old and new release authorities simultaneously could double-write changelog entries, version fields, or publish flows. The migration should explicitly disable the old path before trusting the new one.
+- **API surface parity:** Contributor-facing workflows in `AGENTS.md`, `CLAUDE.md`, and plugin-level instructions must all describe the same release authority model or maintainers will continue using legacy local commands.
+- **Integration coverage:** Unit tests for scripts are not enough. The workflow interaction between release PR maintenance, dry-run preview, and conditional CLI publish needs at least one integration-level verification path in CI.
+
+## Risks & Dependencies
+
+- `release-please` may not natively express the exact root changelog shape you want; custom rendering may be required.
+- If old semantic-release and new release-please flows overlap during migration, duplicate or conflicting release writes are likely.
+- The distinction between version-bearing metadata and descriptive/count-bearing metadata must stay explicit; otherwise scripts may overwrite user-edited documentation that should remain manual.
+- Release preview quality matters. If dry run is vague or noisy, maintainers will bypass it and the manual batching goal will weaken.
+- Removing `release-docs` may expose other hidden docs/deploy assumptions, especially if GitHub Pages or docs generation still depend on stale paths.
+
+## Documentation / Operational Notes
+
+- Document one canonical release path: release PR maintenance on push to `main`, dry-run preview on manual dispatch, actual release on merge of the generated release PR.
+- Document one canonical changelog: root `CHANGELOG.md`.
+- Document one rule for contributors: ordinary feature PRs do not hand-bump release-owned versions or changelog entries.
+- Add a short migration note anywhere old release instructions are likely to be rediscovered, especially around `plugins/compound-engineering/CHANGELOG.md` and the removed `release-docs` command.
+- After merge, run one live GitHub Actions validation pass to confirm `release-please` tag/output wiring and conditional CLI publish behavior end to end.
+
+## Sources & References
+
+- **Origin document:** [docs/brainstorms/2026-03-17-release-automation-requirements.md](docs/brainstorms/2026-03-17-release-automation-requirements.md)
+- Existing release workflow: `.github/workflows/publish.yml`
+- Existing semantic-release config: `.releaserc.json`
+- Existing release-owned guidance: `docs/solutions/plugin-versioning-requirements.md`
+- Legacy repo-maintenance command to retire: `.claude/commands/release-docs.md`
+- Install behavior reference: `src/commands/install.ts`
+- External docs: `release-please` manifest and release PR documentation, GitHub Actions `workflow_dispatch`

docs/plans/2026-03-18-001-feat-auto-memory-integration-beta-plan.md

@@ -0,0 +1,163 @@
+---
+title: "feat: Integrate auto memory as data source for ce:compound and ce:compound-refresh"
+type: feat
+status: completed
+date: 2026-03-18
+origin: docs/brainstorms/2026-03-18-auto-memory-integration-requirements.md
+---
+
+# Integrate Auto Memory as Data Source for ce:compound and ce:compound-refresh
+
+## Overview
+
+Add Claude Code's Auto Memory as a supplementary read-only data source for ce:compound and ce:compound-refresh. The orchestrator and investigation subagents check the auto memory directory for relevant notes that enrich documentation or signal drift in existing learnings.
+
+## Problem Frame
+
+Auto memory passively captures debugging insights, fix patterns, and preferences across sessions. After long sessions or compaction, it preserves insights that conversation context lost. For ce:compound-refresh, it may contain newer observations that signal drift without anyone flagging it. Neither skill currently leverages this free data source. (see origin: `docs/brainstorms/2026-03-18-auto-memory-integration-requirements.md`)
+
+## Requirements Trace
+
+- R1. ce:compound uses auto memory as supplementary evidence -- orchestrator pre-reads MEMORY.md, passes relevant content to Context Analyzer and Solution Extractor subagents (see origin: R1)
+- R2. ce:compound-refresh investigation subagents check auto memory for drift signals in the learning's problem domain (see origin: R2)
+- R3. Graceful absence -- if auto memory doesn't exist or is empty, skills proceed unchanged with no errors (see origin: R3)
+
+## Scope Boundaries
+
+- Read-only -- neither skill writes to auto memory (see origin: Scope Boundaries)
+- No new subagents -- existing subagents are augmented (see origin: Key Decisions)
+- No changes to docs/solutions/ output structure (see origin: Scope Boundaries)
+- MEMORY.md only -- topic files deferred to future iteration
+- No changes to auto memory format or location (see origin: Scope Boundaries)
+
+## Context & Research
+
+### Relevant Code and Patterns
+
+- `plugins/compound-engineering/skills/ce-compound/SKILL.md` -- Phase 1 subagents receive implicit context (conversation history); orchestrator coordinates launch and assembly
+- `plugins/compound-engineering/skills/ce-compound-refresh/SKILL.md` -- investigation subagents receive explicit task prompts with tool guidance; each returns evidence + recommended action
+- ce:compound-refresh already has an explicit "When spawning any subagent, include this instruction" block that can be extended naturally
+- ce:plan has a precedent pattern: orchestrator pre-reads source documents before launching agents (Phase 0 requirements doc scan)
+
+### Institutional Learnings
+
+- `docs/solutions/skill-design/compound-refresh-skill-improvements.md` -- replacement subagents pattern, tool guidance convention, context isolation principle
+- Plugin AGENTS.md tool selection rules: describe tools by capability class with platform hints, not by Claude Code-specific tool names alone
+
+## Key Technical Decisions
+
+- **Relevance matching via semantic judgment, not keyword algorithm**: MEMORY.md is max 200 lines. The orchestrator reads it in full and uses Claude's semantic understanding to identify entries related to the problem. No keyword matching logic needed. (Resolves origin: Deferred Q1)
+- **MEMORY.md only for this iteration**: Topic files are deferred. MEMORY.md as an index is sufficient for a first pass. Expanding to topic files adds complexity with uncertain value until the core integration is validated. (Resolves origin: Deferred Q2)
+- **Augment existing subagents, not a new one**: ce:compound-refresh investigation subagents need memory context during their investigation. A separate Memory Scanner subagent would deliver results too late. For ce:compound, the orchestrator pre-reads once and passes excerpts. (see origin: Key Decisions)
+- **Memory drift signals are supplementary, not primary**: A memory note alone cannot trigger Replace or Archive in ce:compound-refresh. Memory signals corroborate codebase evidence or prompt deeper investigation. In autonomous mode, memory-only drift results in stale-marking, not action.
+- **Provenance labeling required**: Memory excerpts passed to subagents must be wrapped in a clearly labeled section so subagents don't conflate them with verified conversation history.
+- **Conversation history is authoritative**: When memory contradicts the current session's verified fix, the fix takes priority. Memory contradictions can be noted as cautionary context.
+- **All partial memory states treated as absent**: No directory, no MEMORY.md, empty MEMORY.md, malformed MEMORY.md -- all result in graceful skip with no error or warning.
+
+## Open Questions
+
+### Resolved During Planning
+
+- **Which subagents receive memory in ce:compound?** Only Context Analyzer and Solution Extractor. The Related Docs Finder could benefit but starting narrow is safer. Can expand later.
+- **Compact-safe mode?** Still reads MEMORY.md. 200 lines is negligible context cost even in compact-safe mode. The orchestrator uses memory inline during its single pass.
+- **ce:compound-refresh: who reads MEMORY.md?** Each investigation subagent reads it via its task prompt instructions. The orchestrator does not pre-filter because each subagent knows its own investigation domain and 200 lines per read is cheap.
+- **Observability?** Add a line to ce:compound success output when memory contributed. Tag memory-sourced evidence in ce:compound-refresh reports. No changes to YAML frontmatter schema.
+
+### Deferred to Implementation
+
+- **Exact phrasing of subagent instruction additions**: The precise markdown wording will be refined during implementation to fit naturally with existing SKILL.md prose style.
+- **Whether to also augment the Related Docs Finder**: Deferred until after the initial integration shows whether the current scope is sufficient.
+
+## Implementation Units
+
+- [ ] **Unit 1: Add auto memory integration to ce:compound SKILL.md**
+
+**Goal:** Enable ce:compound to read auto memory and pass relevant notes to subagents as supplementary evidence.
+
+**Requirements:** R1, R3
+
+**Dependencies:** None
+
+**Files:**
+- Modify: `plugins/compound-engineering/skills/ce-compound/SKILL.md`
+
+**Approach:**
+- Insert a new "Phase 0.5: Auto Memory Scan" section between the Full Mode critical requirement block and Phase 1. This section instructs the orchestrator to:
+  1. Read MEMORY.md from the auto memory directory (path known from system prompt context)
+  2. If absent or empty, skip and proceed to Phase 1 unchanged
+  3. Scan for entries related to the problem being documented
+  4. Prepare a labeled excerpt block with provenance marking ("Supplementary notes from auto memory -- treat as additional context, not primary evidence")
+  5. Pass the block as additional context to Context Analyzer and Solution Extractor task prompts
+- Augment the Context Analyzer description (under Phase 1) to note: incorporate auto memory excerpts as supplementary evidence when identifying problem type, component, and symptoms
+- Augment the Solution Extractor description (under Phase 1) to note: use auto memory excerpts as supplementary evidence; conversation history and the verified fix take priority; note contradictions as cautionary context
+- Add to Compact-Safe Mode step 1: also read MEMORY.md if it exists, use relevant notes as supplementary context inline
+- Add an optional line to the Success Output template: `Auto memory: N relevant entries used as supplementary evidence` (only when N > 0)
+
+**Patterns to follow:**
+- ce:plan's Phase 0 pattern of pre-reading source documents before launching agents
+- ce:compound-refresh's existing "When spawning any subagent" instruction block pattern
+- Plugin AGENTS.md convention: describe tools by capability class with platform hints
+
+**Test scenarios:**
+- Memory present with relevant entries: orchestrator identifies related notes and passes them to 2 subagents; final documentation is enriched
+- Memory present but no relevant entries: orchestrator reads MEMORY.md, finds nothing related, proceeds without passing memory context
+- Memory absent (no directory): skill proceeds exactly as before with no error
+- Memory empty (directory exists, MEMORY.md is empty or boilerplate): skill proceeds exactly as before
+- Compact-safe mode with memory: single-pass flow uses memory inline alongside conversation history
+- Post-compaction session: memory notes about the fix compensate for lost conversation context
+
+**Verification:**
+- The modified SKILL.md reads naturally with the new sections integrated into the existing flow
+- The Phase 0.5 section clearly describes the graceful absence behavior
+- The subagent augmentations specify provenance labeling
+- The success output template shows the optional memory line
+- `bun run release:validate` passes
+
+- [ ] **Unit 2: Add auto memory checking to ce:compound-refresh SKILL.md**
+
+**Goal:** Enable ce:compound-refresh investigation subagents to use auto memory as a supplementary drift signal source.
+
+**Requirements:** R2, R3
+
+**Dependencies:** None (can be done in parallel with Unit 1)
+
+**Files:**
+- Modify: `plugins/compound-engineering/skills/ce-compound-refresh/SKILL.md`
+
+**Approach:**
+- Add "Auto memory" as a fifth investigation dimension in Phase 1 (after References, Recommended solution, Code examples, Related docs). Instruct: check MEMORY.md from the auto memory directory for notes in the same problem domain. A memory note describing a different approach is a supplementary drift signal. If MEMORY.md doesn't exist or is empty, skip this dimension.
+- Add a paragraph to the Drift Classification section (after Update/Replace territory) explaining memory signal weight: memory drift signals are supplementary; they corroborate codebase-sourced drift or prompt deeper investigation but cannot alone justify Replace or Archive; in autonomous mode, memory-only drift results in stale-marking not action
+- Extend the existing "When spawning any subagent" instruction block to include: read MEMORY.md from auto memory directory if it exists; check for notes related to the learning's problem domain; report memory-sourced drift signals separately, tagged with "(auto memory)" in the evidence section
+- Update the output format guidance to note that memory-sourced findings should be tagged `(auto memory)` to distinguish from codebase-sourced evidence
+
+**Patterns to follow:**
+- The existing investigation dimensions structure in Phase 1 (References, Recommended solution, Code examples, Related docs)
+- The existing "When spawning any subagent" instruction block
+- The existing drift classification guidance style (Update territory vs Replace territory)
+- Plugin AGENTS.md convention: describe tools by capability class with platform hints
+
+**Test scenarios:**
+- Memory contains note contradicting a learning's recommended approach: investigation subagent reports it as "(auto memory)" drift signal alongside codebase evidence
+- Memory contains note confirming the learning's approach: no drift signal, learning stays as Keep
+- Memory-only drift (codebase still matches the learning): in interactive mode, drift is noted but does not alone change classification; in autonomous mode, results in stale-marking
+- Memory absent: investigation proceeds exactly as before, fifth dimension is skipped
+- Broad scope refresh with memory: each parallel investigation subagent independently reads MEMORY.md
+- Report output: memory-sourced evidence is visually distinguishable from codebase evidence
+
+**Verification:**
+- The modified SKILL.md reads naturally with the new dimension and drift guidance integrated
+- The "When spawning any subagent" block cleanly includes memory instructions alongside existing tool guidance
+- The drift classification section clearly states that memory signals are supplementary
+- `bun run release:validate` passes
+
+## Risks & Dependencies
+
+- **Auto memory format changes**: If Claude Code changes the MEMORY.md format in a future release, these skills may need updating. Mitigated by the fact that the skills only instruct Claude to "read MEMORY.md" -- Claude's own semantic understanding handles format interpretation.
+- **Assumption: system prompt contains memory path**: If this assumption breaks, skills would skip memory (graceful absence). The assumption is currently stable across Claude Code versions.
+
+## Sources & References
+
+- **Origin document:** [docs/brainstorms/2026-03-18-auto-memory-integration-requirements.md](docs/brainstorms/2026-03-18-auto-memory-integration-requirements.md) -- Key decisions: augment existing subagents, read-only, graceful absence, orchestrator pre-read for ce:compound
+- Related code: `plugins/compound-engineering/skills/ce-compound/SKILL.md`, `plugins/compound-engineering/skills/ce-compound-refresh/SKILL.md`
+- Institutional learning: `docs/solutions/skill-design/compound-refresh-skill-improvements.md`
+- External docs: https://code.claude.com/docs/en/memory#auto-memory

docs/plans/2026-03-22-001-feat-frontend-design-skill-rewrite-beta-plan.md

@@ -0,0 +1,190 @@
+---
+title: "feat: Rewrite frontend-design skill with layered architecture and visual verification"
+type: feat
+status: completed
+date: 2026-03-22
+origin: docs/brainstorms/2026-03-22-frontend-design-skill-improvement.md
+---
+
+# feat: Rewrite frontend-design skill with layered architecture and visual verification
+
+## Overview
+
+Rewrite the `frontend-design` skill from a 43-line aesthetic manifesto into a structured, layered skill that detects existing design systems, provides context-specific guidance, and verifies its own output via browser screenshots. Add a surgical trigger in `ce-work-beta` to load the skill for UI tasks without Figma designs.
+
+## Problem Frame
+
+The current skill provides vague creative encouragement ("be bold", "choose a BOLD aesthetic direction") but lacks practical structure. It has no mechanism to detect existing design systems, no context-specific guidance (landing pages vs dashboards vs components in existing apps), no concrete constraints, no accessibility guidance, and no verification step. The beta workflow (`ce:plan-beta` -> `deepen-plan-beta` -> `ce:work-beta`) has no way to invoke it -- the skill is effectively orphaned.
+
+Two external sources informed the redesign: Anthropic's official frontend-design skill (nearly identical to ours, same gaps) and OpenAI's comprehensive frontend skill from March 2026 (see origin: `docs/brainstorms/2026-03-22-frontend-design-skill-improvement.md`).
+
+## Requirements Trace
+
+- R1. Detect existing design systems before applying opinionated guidance (Layer 0)
+- R2. Enforce authority hierarchy: existing design system > user instructions > skill defaults
+- R3. Provide pre-build planning step (visual thesis, content plan, interaction plan)
+- R4. Cover typography, color, composition, motion, accessibility, and imagery with concrete constraints
+- R5. Provide context-specific modules: landing pages, apps/dashboards, components/features
+- R6. Module C (components/features) is the default when working in an existing app
+- R7. Two-tier anti-pattern system: overridable defaults vs quality floor
+- R8. Visual self-verification via browser screenshot with tool cascade
+- R9. Cross-agent compatibility (Claude Code, Codex, Gemini CLI)
+- R10. ce-work-beta loads the skill for UI tasks without Figma designs
+- R11. Verification screenshot reuse -- skill's screenshot satisfies ce-work-beta Phase 4's requirement
+
+## Scope Boundaries
+
+- The `frontend-design` skill itself handles all design guidance and verification. ce-work-beta gets only a trigger.
+- ce-work (non-beta) is not modified.
+- The design-iterator agent is not modified. The skill does not invoke it.
+- The agent-browser skill is upstream-vendored and not modified.
+- The design-iterator's `<frontend_aesthetics>` block (which duplicates current skill content) is not cleaned up in this plan -- that is a separate follow-up.
+
+## Context & Research
+
+### Relevant Code and Patterns
+
+- `plugins/compound-engineering/skills/frontend-design/SKILL.md` -- target for full rewrite (43 lines currently)
+- `plugins/compound-engineering/skills/ce-work-beta/SKILL.md` -- target for surgical Phase 2 addition (lines 210-219, between Figma Design Sync and Track Progress)
+- `plugins/compound-engineering/skills/ce-plan-beta/SKILL.md` -- reference for cross-agent interaction patterns (Pattern A: platform's blocking question tool with named equivalents)
+- `plugins/compound-engineering/skills/reproduce-bug/SKILL.md` -- reference for cross-agent patterns
+- `plugins/compound-engineering/skills/agent-browser/SKILL.md` -- upstream-vendored, reference for browser automation CLI
+- `plugins/compound-engineering/agents/design/ce-design-iterator.agent.md` -- contains `<frontend_aesthetics>` block that overlaps with current skill; new skill will supersede this when both are loaded
+- `plugins/compound-engineering/AGENTS.md` -- skill compliance checklist (cross-platform interaction, tool selection, reference rules)
+
+### Institutional Learnings
+
+- **Cross-platform tool references** (`docs/solutions/skill-design/compound-refresh-skill-improvements.md`): Never hardcode a single tool name with an escape hatch. Use capability-first language with platform examples and plain-text fallback. Anti-pattern table directly applicable.
+- **Beta skills framework** (`docs/solutions/skill-design/beta-skills-framework.md`): frontend-design is NOT a beta skill -- it is a stable skill being improved. ce-work-beta should reference it by its stable name.
+- **Codex skill conversion** (`docs/solutions/codex-skill-prompt-entrypoints.md`): Skills are copied as-is to Codex. Slash references inside SKILL.md are NOT rewritten. Use semantic wording ("load the `agent-browser` skill") rather than slash syntax.
+- **Context token budget** (`docs/plans/2026-02-08-refactor-reduce-plugin-context-token-usage-plan.md`): Description field's only job is discovery. The proposed 6-line description is well-sized for the budget.
+- **Script-first architecture** (`docs/solutions/skill-design/script-first-skill-architecture.md`): When a skill's core value IS the model's judgment, script-first does not apply. Frontend-design is judgment-based. Detection checklist should be inline, not in reference files.
+
+## Key Technical Decisions
+
+- **No `disable-model-invocation`**: The skill should auto-invoke when the model detects frontend work. Current skill does not have it; the rewrite preserves this.
+- **Drop `license` frontmatter field**: Only the current frontend-design skill has this field. No other skill uses it. Drop it for consistency.
+- **Inline everything in SKILL.md**: No reference files or scripts directory. The skill is pure guidance (~300-400 lines of markdown). The detection checklist, context modules, anti-patterns, litmus checks, and verification cascade all live in one file.
+- **Fix ce-work-beta duplicate numbering**: The current Phase 2 has two items numbered "6." (Figma Design Sync and Track Progress). Fix this while inserting the new section.
+- **Framework-conditional animation defaults**: CSS animations as universal baseline. Framer Motion for React, Vue Transition / Motion One for Vue, Svelte transitions for Svelte. Only when no existing animation library is detected.
+- **Semantic skill references only**: Reference agent-browser as "load the `agent-browser` skill" not `/agent-browser`. Per AGENTS.md and Codex conversion learnings.
+
+## Open Questions
+
+### Resolved During Planning
+
+- **Should the skill have `disable-model-invocation: true`?** No. It should auto-invoke for frontend work. The current skill does not have it.
+- **Should Module A/B ever apply in an existing app?** No. When working inside an existing app, always default to Module C regardless of what's being built. Modules A and B are for greenfield work.
+- **Should the `license` field be kept?** No. It is unique to this skill and inconsistent with all other skills.
+
+### Deferred to Implementation
+
+- **Exact line count of the rewritten skill**: Estimated 300-400 lines. The implementer should prioritize clarity over brevity but avoid bloat.
+- **Whether the design-iterator's `<frontend_aesthetics>` block needs updating**: Out of scope. The new skill supersedes it when loaded. Cleanup is a separate follow-up.
+
+## Implementation Units
+
+- [x] **Unit 1: Rewrite frontend-design SKILL.md**
+
+  **Goal:** Replace the 43-line aesthetic manifesto with the full layered skill covering detection, planning, guidance, context modules, anti-patterns, litmus checks, and visual verification.
+
+  **Requirements:** R1, R2, R3, R4, R5, R6, R7, R8, R9
+
+  **Dependencies:** None
+
+  **Files:**
+  - Modify: `plugins/compound-engineering/skills/frontend-design/SKILL.md`
+
+  **Approach:**
+  - Full rewrite preserving only the `name` field from current frontmatter
+  - Use the optimized description from the brainstorm doc (see origin: Section "Skill Description (Optimized)")
+  - Structure as: Frontmatter -> Preamble (authority hierarchy, workflow preview) -> Layer 0 (context detection with concrete checklist, mode classification, cross-platform question pattern) -> Layer 1 (pre-build planning) -> Layer 2 (design guidance core with subsections for typography, color, composition, motion, accessibility, imagery) -> Context Modules (A/B/C) -> Hard Rules & Anti-Patterns (two tiers) -> Litmus Checks -> Visual Verification (tool cascade with scope control)
+  - Carry forward from current skill: anti-AI-slop identity, creative energy for greenfield, tone-picking exercise, differentiation prompt
+  - Apply AGENTS.md skill compliance checklist: imperative voice, capability-first tool references with platform examples, semantic skill references, no shell recipes for exploration, cross-platform question patterns with fallback
+  - All rules framed as defaults that yield to existing design systems and user instructions
+  - Copy guidance uses "Every sentence should earn its place. Default to less copy, not more." (not arbitrary percentage thresholds)
+  - Animation defaults are framework-conditional: CSS baseline, then Framer Motion (React), Vue Transition/Motion One (Vue), Svelte transitions (Svelte)
+  - Visual verification cascade: existing project tooling -> browser MCP tools -> agent-browser CLI (load the `agent-browser` skill for setup) -> mental review as last resort
+  - One verification pass with scope control ("sanity check, not pixel-perfect review")
+  - Note relationship to design-iterator: "For iterative refinement beyond a single pass, see the `design-iterator` agent"
+
+  **Patterns to follow:**
+  - `plugins/compound-engineering/skills/ce-plan-beta/SKILL.md` -- cross-agent interaction pattern (Pattern A)
+  - `plugins/compound-engineering/skills/reproduce-bug/SKILL.md` -- cross-agent tool reference pattern
+  - `plugins/compound-engineering/AGENTS.md` -- skill compliance checklist
+  - `docs/solutions/skill-design/compound-refresh-skill-improvements.md` -- anti-pattern table for tool references
+
+  **Test scenarios:**
+  - Skill passes all items in the AGENTS.md skill compliance checklist
+  - Description field is present and follows "what + when" format
+  - No hardcoded Claude-specific tool names without platform equivalents
+  - No slash references to other skills (uses semantic wording)
+  - No `TodoWrite`/`TodoRead` references
+  - No shell commands for routine file exploration
+  - Cross-platform question pattern includes AskUserQuestion, request_user_input, ask_user, and a fallback
+  - All design rules explicitly framed as defaults (not absolutes)
+  - Layer 0 detection checklist is concrete (specific file patterns and config names)
+  - Mode classification has clear thresholds (4+ signals = existing, 1-3 = partial, 0 = greenfield)
+  - Visual verification section references agent-browser semantically ("load the `agent-browser` skill")
+
+  **Verification:**
+  - `grep -E 'description:' plugins/compound-engineering/skills/frontend-design/SKILL.md` returns the optimized description
+  - `grep -E '^\`(references|assets|scripts)/[^\`]+\`' plugins/compound-engineering/skills/frontend-design/SKILL.md` returns nothing (no unlinked references)
+  - Manual review confirms the layered structure matches the brainstorm doc's "Skill Structure" outline
+  - `bun run release:validate` passes
+
+- [x] **Unit 2: Add frontend-design trigger to ce-work-beta Phase 2**
+
+  **Goal:** Insert a conditional section in ce-work-beta Phase 2 that loads the `frontend-design` skill for UI tasks without Figma designs, and fix the duplicate item numbering.
+
+  **Requirements:** R10, R11
+
+  **Dependencies:** Unit 1 (the skill must exist in its new form for the reference to be meaningful)
+
+  **Files:**
+  - Modify: `plugins/compound-engineering/skills/ce-work-beta/SKILL.md`
+
+  **Approach:**
+  - Insert new section after Figma Design Sync (line 217) and before Track Progress (line 219)
+  - New section titled "Frontend Design Guidance" (if applicable), following the same conditional pattern as Figma Design Sync
+  - Content: UI task detection heuristic (implementation files include views/templates/components/layouts/pages, creates user-visible routes, plan text contains UI/frontend/design language, or task builds something user-visible in browser) + instruction to load the `frontend-design` skill + note that the skill's verification screenshot satisfies Phase 4's screenshot requirement
+  - Fix duplicate "6." numbering: Figma Design Sync = 6, Frontend Design Guidance = 7, Track Progress = 8
+  - Keep the addition to ~10 lines including the heuristic and the verification-reuse note
+  - Use semantic skill reference: "load the `frontend-design` skill" (not slash syntax)
+
+  **Patterns to follow:**
+  - The existing Figma Design Sync section (lines 210-217) -- same conditional "(if applicable)" pattern, same level of brevity
+
+  **Test scenarios:**
+  - New section follows same formatting as Figma Design Sync section
+  - No duplicate item numbers in Phase 2
+  - Semantic skill reference used (no slash syntax for frontend-design)
+  - Verification screenshot reuse is explicit
+  - `bun run release:validate` passes
+
+  **Verification:**
+  - Phase 2 items are numbered sequentially without duplicates
+  - The new section references `frontend-design` skill semantically
+  - The verification-reuse note is present
+  - `bun run release:validate` passes
+
+## System-Wide Impact
+
+- **Interaction graph:** The frontend-design skill is auto-invocable (no `disable-model-invocation`). When loaded, it may interact with: agent-browser CLI (for verification screenshots), browser MCP tools, or existing project browser tooling. ce-work-beta Phase 2 will conditionally trigger the skill load. The design-iterator agent's `<frontend_aesthetics>` block will be superseded when both the skill and agent are active in the same context.
+- **Error propagation:** If browser tooling is unavailable for verification, the skill falls back to mental review. No hard failure path.
+- **State lifecycle risks:** None. This is markdown document work -- no runtime state, no data, no migrations.
+- **API surface parity:** The skill description change affects how Claude discovers and triggers the skill. The new description is broader (covers existing app modifications) which may increase trigger rate.
+- **Integration coverage:** The primary integration is ce-work-beta -> frontend-design skill -> agent-browser. This flow should be manually tested end-to-end with a UI task in the beta workflow.
+
+## Risks & Dependencies
+
+- **Trigger rate change:** The broader description may cause the skill to trigger for borderline cases (e.g., a task that touches one CSS class). Mitigated by the Layer 0 detection step which will quickly identify "existing system" mode and short-circuit most opinionated guidance.
+- **Skill length:** Estimated 300-400 lines is substantial for a skill body. Mitigated by the layered architecture -- an agent in "existing system" mode can skip Layer 2's opinionated sections entirely.
+- **design-iterator overlap:** The design-iterator's `<frontend_aesthetics>` block now partially duplicates the skill's Layer 2 content. Not a functional problem (the skill supersedes when loaded) but creates maintenance overhead. Flagged for follow-up cleanup.
+
+## Sources & References
+
+- **Origin document:** [docs/brainstorms/2026-03-22-frontend-design-skill-improvement.md](docs/brainstorms/2026-03-22-frontend-design-skill-improvement.md)
+- Related code: `plugins/compound-engineering/skills/frontend-design/SKILL.md`, `plugins/compound-engineering/skills/ce-work-beta/SKILL.md`
+- External inspiration: Anthropic official frontend-design skill, OpenAI "Designing Delightful Frontends with GPT-5.4" skill (March 2026)
+- Institutional learnings: `docs/solutions/skill-design/compound-refresh-skill-improvements.md`, `docs/solutions/skill-design/beta-skills-framework.md`, `docs/solutions/codex-skill-prompt-entrypoints.md`

docs/plans/2026-03-23-001-feat-ce-review-beta-pipeline-mode-beta-plan.md

@@ -0,0 +1,316 @@
+---
+title: "feat: Make ce:review-beta autonomous and pipeline-safe"
+type: feat
+status: active
+date: 2026-03-23
+origin: direct user request and planning discussion on ce:review-beta standalone vs. autonomous pipeline behavior
+---
+
+# Make ce:review-beta Autonomous and Pipeline-Safe
+
+## Overview
+
+Redesign `ce:review-beta` from a purely interactive standalone review workflow into a policy-driven review engine that supports three explicit modes: `interactive`, `autonomous`, and `report-only`. The redesign should preserve the current standalone UX for manual review, enable hands-off review and safe autofix in automated workflows, and define a clean residual-work handoff for anything that should not be auto-fixed. This plan remains beta-only; promotion to stable `ce:review` and any `lfg` / `slfg` cutover should happen only in a follow-up plan after the beta behavior is validated.
+
+## Problem Frame
+
+`ce:review-beta` currently mixes three responsibilities in one loop:
+
+1. Review and synthesis
+2. Human approval on what to fix
+3. Local fixing, re-review, and push/PR next steps
+
+That is acceptable for standalone use, but it is the wrong shape for autonomous orchestration:
+
+- `lfg` currently treats review as an upstream producer before downstream resolution and browser testing
+- `slfg` currently runs review and browser testing in parallel, which is only safe if review is non-mutating
+- `resolve-todo-parallel` expects a durable residual-work contract (`todos/`), while `ce:review-beta` currently tries to resolve accepted findings inline
+- The findings schema lacks routing metadata, so severity is doing too much work; urgency and autofix eligibility are distinct concerns
+
+The result is a workflow that is hard to promote safely: it can be interactive, or autonomous, or mutation-owning, but not all three at once without an explicit mode model and clearer ownership boundaries.
+
+## Requirements Trace
+
+- R1. `ce:review-beta` supports explicit execution modes: `interactive` (default), `autonomous`, and `report-only`
+- R2. `autonomous` mode never asks the user questions, never waits for approval, and applies only policy-allowed safe fixes
+- R3. `report-only` mode is strictly read-only and safe to run in parallel with other read-only verification steps
+- R4. Findings are routed by explicit fixability metadata, not by severity alone
+- R5. `ce:review-beta` can run one bounded in-skill autofix pass for `safe_auto` findings and then re-review the changed scope
+- R6. Residual actionable findings are emitted as durable downstream work artifacts; advisory outputs remain report-only
+- R7. CE helper outputs (`learnings`, `agent-native`, `schema-drift`, `deployment-verification`) are preserved but only some become actionable work items
+- R8. The beta contract makes future orchestration constraints explicit so a later `lfg` / `slfg` cutover does not run a mutating review concurrently with browser testing on the same checkout
+- R9. Repeated regression classes around interaction mode, routing, and orchestration boundaries gain lightweight contract coverage
+
+## Scope Boundaries
+
+- Keep the existing persona ensemble, confidence gate, and synthesis model as the base architecture
+- Do not redesign every reviewer persona's prompt beyond the metadata they need to emit
+- Do not introduce a new general-purpose orchestration framework; reuse existing skill patterns where possible
+- Do not auto-fix deployment checklists, residual risks, or other advisory-only outputs
+- Do not attempt broad converter/platform work in this change unless the review skill's frontmatter or references require it
+- Beta remains the only implementation target in this plan; stable promotion is intentionally deferred to a follow-up plan after validation
+
+## Context & Research
+
+### Relevant Code and Patterns
+
+- `plugins/compound-engineering/skills/ce-review-beta/SKILL.md`
+  - Current staged review pipeline with interactive severity acceptance, inline fixer, re-review offer, and post-fix push/PR actions
+- `plugins/compound-engineering/skills/ce-review-beta/references/findings-schema.json`
+  - Structured persona finding contract today; currently missing routing metadata for autonomous handling
+- `plugins/compound-engineering/skills/ce-review/SKILL.md`
+  - Current stable review workflow; creates durable `todos/` artifacts rather than fixing findings inline
+- `plugins/compound-engineering/skills/resolve-todo-parallel/SKILL.md`
+  - Existing residual-work resolver; parallelizes item handling once work has already been externalized
+- `plugins/compound-engineering/skills/file-todos/SKILL.md`
+  - Existing review -> triage -> todo -> resolve integration contract
+- `plugins/compound-engineering/skills/lfg/SKILL.md`
+  - Sequential orchestrator whose future cutover constraints should inform the beta contract, even though this plan does not modify it
+- `plugins/compound-engineering/skills/slfg/SKILL.md`
+  - Swarm orchestrator whose current review/browser parallelism defines an important future integration constraint, even though this plan does not modify it
+- `plugins/compound-engineering/skills/ce-compound-refresh/SKILL.md`
+  - Strong repo precedent for explicit `mode:autonomous` argument handling and conservative non-interactive behavior
+- `plugins/compound-engineering/skills/ce-plan/SKILL.md`
+  - Strong repo precedent for pipeline mode skipping interactive questions
+
+### Institutional Learnings
+
+- `docs/solutions/skill-design/compound-refresh-skill-improvements.md`
+  - Explicit autonomous mode beats tool-based auto-detection
+  - Ambiguous cases in autonomous mode should be recorded conservatively, not guessed
+  - Report structure should distinguish applied actions from recommended follow-up
+- `docs/solutions/skill-design/beta-skills-framework.md`
+  - Beta skills should remain isolated until validated
+  - Promotion is the right time to rewire `lfg` / `slfg`, which is out of scope for this plan
+
+### External Research Decision
+
+Skipped. This is a repo-internal orchestration and skill-design change with strong existing local patterns for autonomous mode, beta promotion, and residual-work handling.
+
+## Key Technical Decisions
+
+- **Use explicit mode arguments instead of auto-detection.** Follow `ce:compound-refresh` and require `mode:autonomous` / `mode:report-only` arguments. Interactive remains the default. This avoids conflating "no question tool" with "headless workflow."
+- **Split review from mutation semantically, not by creating two separate skills.** `ce:review-beta` should always perform the same review and synthesis stages. Mutation behavior becomes a mode-controlled phase layered on top.
+- **Route by fixability, not severity.** Add explicit per-finding routing fields such as `autofix_class`, `owner`, and `requires_verification`. Severity remains urgency; it no longer implies who acts.
+- **Keep one in-skill fixer, but only for `safe_auto` findings.** The current "one fixer subagent" rule is still right for consistent-tree edits. The change is that the fixer is selected by policy and routing metadata, not by an interactive severity prompt.
+- **Emit both ephemeral and durable outputs.** Use `.context/compound-engineering/ce-review-beta/<run-id>/` for the per-run machine-readable report and create durable `todos/` items only for unresolved actionable findings that belong downstream.
+- **Treat CE helper outputs by artifact class.**
+  - `learnings-researcher`: contextual/advisory unless a concrete finding corroborates it
+  - `agent-native-reviewer`: often `gated_auto` or `manual`, occasionally `safe_auto` when the fix is purely local and mechanical
+  - `schema-drift-detector`: default `manual` or `gated_auto`; never auto-fix blindly by default
+  - `deployment-verification-agent`: always advisory / operational, never autofix
+- **Design the beta contract so future orchestration cutover is safe.** The beta must make it explicit that mutating review cannot run concurrently with browser testing on the same checkout. That requirement is part of validation and future cutover criteria, not a same-plan rewrite of `slfg`.
+- **Move push / PR creation decisions out of autonomous review.** Interactive standalone mode may still offer next-step prompts. Autonomous and report-only modes should stop after producing fixes and/or residual artifacts; any future parent workflow decides commit, push, and PR timing.
+- **Add lightweight contract tests.** Repeated regressions have come from instruction-boundary drift. String- and structure-level contract tests are justified here even though the behavior is prompt-driven.
+
+## Open Questions
+
+### Resolved During Planning
+
+- **Should `ce:review-beta` keep any embedded fix loop?** Yes, but only for `safe_auto` findings under an explicit mode/policy. Residual work is handed off.
+- **Should autonomous mode be inferred from lack of interactivity?** No. Use explicit `mode:autonomous`.
+- **Should `slfg` keep review and browser testing in parallel?** No, not once review can mutate the checkout. Run browser testing after the mutating review phase on the stabilized tree.
+- **Should residual work be `todos/`, `.context/`, or both?** Both. `.context` holds the run artifact; `todos/` is only for durable unresolved actionable work.
+
+### Deferred to Implementation
+
+- Exact metadata field names in `findings-schema.json`
+- Whether `report-only` should imply a different default output template section ordering than `interactive` / `autonomous`
+- Whether residual `todos/` should be created directly by `ce:review-beta` or via a small shared helper/reference template used by both review and resolver flows
+
+## High-Level Technical Design
+
+This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.
+
+```text
+review stages -> synthesize -> classify outputs by autofix_class/owner
+               -> if mode=report-only: emit report + stop
+               -> if mode=interactive: acquire policy from user
+               -> if mode=autonomous: use policy from arguments/defaults
+               -> run single fixer on safe_auto set
+               -> verify tests + focused re-review
+               -> emit residual todos for unresolved actionable items
+               -> emit advisory/report sections for non-actionable outputs
+```
+
+## Implementation Units
+
+- [x] **Unit 1: Add explicit mode handling and routing metadata to ce:review-beta**
+
+**Goal:** Give `ce:review-beta` a clear execution contract for standalone, autonomous, and read-only pipeline use.
+
+**Requirements:** R1, R2, R3, R4, R7
+
+**Dependencies:** None
+
+**Files:**
+- Modify: `plugins/compound-engineering/skills/ce-review-beta/SKILL.md`
+- Modify: `plugins/compound-engineering/skills/ce-review-beta/references/findings-schema.json`
+- Modify: `plugins/compound-engineering/skills/ce-review-beta/references/review-output-template.md`
+- Modify: `plugins/compound-engineering/skills/ce-review-beta/references/subagent-template.md` (if routing metadata needs to be spelled out in spawn prompts)
+
+**Approach:**
+- Add a Mode Detection section near the top of `SKILL.md` using the established `mode:autonomous` argument pattern from `ce:compound-refresh`
+- Introduce `mode:report-only` alongside `mode:autonomous`
+- Scope all interactive question instructions so they apply only to interactive mode
+- Extend `findings-schema.json` with routing-oriented fields such as:
+  - `autofix_class`: `safe_auto | gated_auto | manual | advisory`
+  - `owner`: `review-fixer | downstream-resolver | human | release`
+  - `requires_verification`: boolean
+- Update the review output template so the final report can distinguish:
+  - applied fixes
+  - residual actionable work
+  - advisory / operational notes
+
+**Patterns to follow:**
+- `plugins/compound-engineering/skills/ce-compound-refresh/SKILL.md` explicit autonomous mode structure
+- `plugins/compound-engineering/skills/ce-plan/SKILL.md` pipeline-mode question skipping
+
+**Test scenarios:**
+- Interactive mode still presents questions and next-step prompts
+- `mode:autonomous` never asks a question and never waits for user input
+- `mode:report-only` performs no edits and no commit/push/PR actions
+- A helper-agent output can be preserved in the final report without being treated as auto-fixable work
+
+**Verification:**
+- `tests/review-skill-contract.test.ts` asserts the three mode markers and interactive scoping rules
+- `bun run release:validate` passes
+
+- [x] **Unit 2: Redesign the fix loop around policy-driven safe autofix and bounded re-review**
+
+**Goal:** Replace the current severity-prompt-centric fix loop with one that works in both interactive and autonomous contexts.
+
+**Requirements:** R2, R4, R5, R7
+
+**Dependencies:** Unit 1
+
+**Files:**
+- Modify: `plugins/compound-engineering/skills/ce-review-beta/SKILL.md`
+- Add: `plugins/compound-engineering/skills/ce-review-beta/references/fix-policy.md` (if the classification and policy table becomes too large for `SKILL.md`)
+- Modify: `plugins/compound-engineering/skills/ce-review-beta/references/review-output-template.md`
+
+**Approach:**
+- Replace "Severity Acceptance" as the primary decision point with a classification stage that groups synthesized findings by `autofix_class`
+- In interactive mode, ask the user only for policy decisions that remain ambiguous after classification
+- In autonomous mode, use conservative defaults:
+  - apply `safe_auto`
+  - leave `gated_auto`, `manual`, and `advisory` unresolved
+- Keep the "exactly one fixer subagent" rule for consistency
+- Bound the loop with `max_rounds` (for example 2) and require targeted verification plus focused re-review after any applied fix set
+- Restrict commit / push / PR creation steps to interactive mode only; autonomous and report-only modes stop after emitting outputs
+
+**Patterns to follow:**
+- `docs/solutions/skill-design/compound-refresh-skill-improvements.md` applied-vs-recommended distinction
+- Existing `ce-review-beta` single-fixer rule
+
+**Test scenarios:**
+- A `safe_auto` testing finding gets fixed and re-reviewed without user input in autonomous mode
+- A `gated_auto` API contract or authz finding is preserved as residual actionable work, not auto-fixed
+- A deployment checklist remains advisory and never enters the fixer queue
+- Zero findings skip the fix phase entirely
+- Re-review is bounded and does not recurse indefinitely
+
+**Verification:**
+- `tests/review-skill-contract.test.ts` asserts that autonomous mode has no mandatory user-question step in the fix path
+- Manual dry run: read the fix-loop prose end-to-end and verify there is no mutation-owning step outside the policy gate
+
+- [x] **Unit 3: Define residual artifact and downstream handoff behavior**
+
+**Goal:** Make autonomous review compatible with downstream workflows instead of competing with them.
+
+**Requirements:** R5, R6, R7
+
+**Dependencies:** Unit 2
+
+**Files:**
+- Modify: `plugins/compound-engineering/skills/ce-review-beta/SKILL.md`
+- Modify: `plugins/compound-engineering/skills/resolve-todo-parallel/SKILL.md`
+- Modify: `plugins/compound-engineering/skills/file-todos/SKILL.md`
+- Add: `plugins/compound-engineering/skills/ce-review-beta/references/residual-work-template.md` (if a dedicated durable-work shape helps keep review prose smaller)
+
+**Approach:**
+- Write a per-run review artifact under `.context/compound-engineering/ce-review-beta/<run-id>/` containing:
+  - synthesized findings
+  - what was auto-fixed
+  - what remains unresolved
+  - advisory-only outputs
+- Create durable `todos/` items only for unresolved actionable findings whose `owner` is downstream resolution
+- Update `resolve-todo-parallel` to acknowledge this source explicitly so residual review work can be picked up without pretending everything came from stable `ce:review`
+- Update `file-todos` integration guidance to reflect the new flow:
+  - review-beta autonomous -> residual todos -> resolve-todo-parallel
+  - advisory-only outputs do not become todos
+
+**Patterns to follow:**
+- `.context/compound-engineering/<workflow>/<run-id>/` scratch-space convention from `AGENTS.md`
+- Existing `file-todos` review/resolution lifecycle
+
+**Test scenarios:**
+- Autonomous review with only advisory outputs creates no todos
+- Autonomous review with 2 unresolved actionable findings creates exactly 2 residual todos
+- Residual work items exclude protected-artifact cleanup suggestions
+- The run artifact is sufficient to explain what the in-skill fixer changed vs. what remains
+
+**Verification:**
+- `tests/review-skill-contract.test.ts` asserts the documented `.context` and `todos/` handoff rules
+- `bun run release:validate` passes after any skill inventory/reference changes
+
+- [x] **Unit 4: Add contract-focused regression coverage for mode, handoff, and future-integration boundaries**
+
+**Goal:** Catch the specific instruction-boundary regressions that have repeatedly escaped manual review.
+
+**Requirements:** R8, R9
+
+**Dependencies:** Units 1-3
+
+**Files:**
+- Add: `tests/review-skill-contract.test.ts`
+- Optionally modify: `package.json` only if a new test entry point is required (prefer using the existing Bun test setup without package changes)
+
+**Approach:**
+- Add a focused test that reads the relevant skill files and asserts contract-level invariants instead of brittle full-file snapshots
+- Cover:
+  - `ce-review-beta` mode markers and mode-specific behavior phrases
+  - absence of unconditional interactive prompts in autonomous/report-only paths
+  - explicit residual-work handoff language
+  - explicit documentation that mutating review must not run concurrently with browser testing on the same checkout
+- Keep assertions semantic and localized; avoid snapshotting large markdown files
+
+**Patterns to follow:**
+- Existing Bun tests that read repository files directly for release/config validation
+
+**Test scenarios:**
+- Missing `mode:autonomous` block fails
+- Reintroduced unconditional "Ask the user" text in the autonomous path fails
+- Missing residual todo handoff text fails
+- Missing future integration constraint around mutating review vs. browser testing fails
+
+**Verification:**
+- `bun test tests/review-skill-contract.test.ts`
+- full `bun test`
+
+## Risks & Dependencies
+
+- **Over-aggressive autofix classification.**
+  - Mitigation: conservative defaults, `gated_auto` bucket, bounded rounds, focused re-review
+- **Dual ownership confusion between `ce:review-beta` and `resolve-todo-parallel`.**
+  - Mitigation: explicit owner/routing metadata and durable residual-work contract
+- **Brittle contract tests.**
+  - Mitigation: assert only boundary invariants, not full markdown snapshots
+- **Promotion churn.**
+  - Mitigation: keep beta isolated until Unit 4 contract coverage and manual verification pass
+
+## Sources & References
+
+- Related skills:
+  - `plugins/compound-engineering/skills/ce-review-beta/SKILL.md`
+  - `plugins/compound-engineering/skills/ce-review/SKILL.md`
+  - `plugins/compound-engineering/skills/resolve-todo-parallel/SKILL.md`
+  - `plugins/compound-engineering/skills/file-todos/SKILL.md`
+  - `plugins/compound-engineering/skills/lfg/SKILL.md`
+  - `plugins/compound-engineering/skills/slfg/SKILL.md`
+- Institutional learnings:
+  - `docs/solutions/skill-design/compound-refresh-skill-improvements.md`
+  - `docs/solutions/skill-design/beta-skills-framework.md`
+- Supporting pattern reference:
+  - `plugins/compound-engineering/skills/ce-compound-refresh/SKILL.md`
+  - `plugins/compound-engineering/skills/ce-plan/SKILL.md`

docs/plans/2026-03-23-001-feat-plan-review-personas-beta-plan.md

@@ -0,0 +1,504 @@
+---
+title: "feat: Replace document-review with persona-based review pipeline"
+type: feat
+status: completed
+date: 2026-03-23
+deepened: 2026-03-23
+origin: docs/brainstorms/2026-03-23-plan-review-personas-requirements.md
+---
+
+# Replace document-review with Persona-Based Review Pipeline
+
+## Overview
+
+Replace the single-voice `document-review` skill with a multi-persona review pipeline that dispatches specialized reviewer agents in parallel. Two always-on personas (coherence, feasibility) run on every review. Four conditional personas (product-lens, design-lens, security-lens, scope-guardian) activate based on document content analysis. Quality issues are auto-fixed; strategic questions are presented to the user.
+
+## Problem Frame
+
+The current `document-review` applies five generic criteria (Clarity, Completeness, Specificity, Appropriate Level, YAGNI) through a single evaluator voice. This misses role-specific concerns: a security engineer, product leader, and design reviewer each see different problems in the same plan. The `ce:review` skill already demonstrates that multi-persona review produces richer, more actionable feedback for code. The same architecture applies to plan/requirements review. (see origin: docs/brainstorms/2026-03-23-plan-review-personas-requirements.md)
+
+## Requirements Trace
+
+- R1. Replace document-review with persona pipeline dispatching specialized agents in parallel
+- R2. 2 always-on personas: coherence, feasibility
+- R3. 4 conditional personas: product-lens, design-lens, security-lens, scope-guardian
+- R4. Auto-detect conditional persona relevance from document content
+- R5. Hybrid action model: auto-fix quality issues, present strategic questions
+- R6. Structured findings with confidence, dedup, synthesized report
+- R7. Backward compatibility with all 4 callers (brainstorm, plan, plan-beta, deepen-plan-beta)
+- R8. Pipeline-compatible for future automated workflows
+
+## Scope Boundaries
+
+- Not adding new callers or pipeline integrations
+- Not changing deepen-plan-beta behavior
+- Not adding user configuration for persona selection
+- Not inventing new review frameworks -- incorporating established review patterns into respective personas
+- Not modifying any of the 4 existing caller skills
+
+## Context & Research
+
+### Relevant Code and Patterns
+
+- `plugins/compound-engineering/skills/ce-review/SKILL.md` -- Multi-agent orchestration reference: parallel dispatch via Task tool, always-on + conditional agents, P1/P2/P3 severity, finding synthesis with dedup
+- `plugins/compound-engineering/skills/document-review/SKILL.md` -- Current single-voice skill to replace. Key contract: "Review complete" terminal signal
+- `plugins/compound-engineering/agents/review/ce-*.agent.md` -- 15 existing review agents. Frontmatter schema: `name`, `description`, `model: inherit`. Body: examples block, role definition, analysis protocol, output format
+- `plugins/compound-engineering/AGENTS.md` -- Agent naming: fully-qualified `compound-engineering:<category>:<agent-name>`. Agent placement: `agents/<category>/<name>.md`
+
+### Caller Integration Points
+
+All 4 callers use the same contract:
+- `ce-brainstorm/SKILL.md` line 301: "Load the `document-review` skill and apply it to the requirements document"
+- `ce-plan/SKILL.md` line 592: "Load `document-review` skill"
+- `ce-plan-beta/SKILL.md` line 611: "Load the `document-review` skill with the plan path"
+- `deepen-plan-beta/SKILL.md` line 402: "Load the `document-review` skill with the plan path"
+
+All expect "Review complete" as the terminal signal. No callers check for specific output format. No caller changes needed.
+
+### Institutional Learnings
+
+- **Subagent design** (docs/solutions/skill-design/compound-refresh-skill-improvements.md): Each persona agent needs explicit context (file path, scope, output format) -- don't rely on inherited context. Use native file tools, not shell commands. Avoid hardcoded tool names; use capability-first language with platform examples.
+- **Parallel dispatch safety**: Persona reviewers are read-only (analyze the document, don't modify it). Parallel dispatch is safe. This differs from compound-refresh which used sequential subagents because they modified files.
+- **Contradictory findings**: With 6 independent reviewers, findings will conflict (scope-guardian wants to cut; coherence wants to keep for narrative flow). Synthesis needs conflict-resolution rules, not just dedup.
+- **Classification pipeline ordering**: Pipeline ordering matters: filter -> normalize -> group -> threshold -> re-classify -> output. Post-grouping safety checks catch misclassified findings. Single source of truth for classification logic.
+- **Beta skills framework** (docs/solutions/skill-design/beta-skills-framework.md): Since we're replacing document-review entirely (not running side-by-side), the beta framework doesn't apply here.
+
+### Research Insights: iterative-engineering plan-review
+
+The iterative-engineering plugin (v1.16.1) implements a mature plan-review skill with persona agents. Key architectural patterns to adopt:
+
+**Structured output contract**: All personas return findings in a consistent JSON-like structure with: title (<=10 words), priority (HIGH/MEDIUM/LOW), section, line, why_it_matters (impact not symptom), confidence (0.0-1.0), evidence (quoted text, minimum 1), and optional suggestion. This consistency enables reliable synthesis.
+
+**Fingerprint-based dedup**: `normalize(section) + line_bucket(line, +/-5) + normalize(title)`. When fingerprints match: keep highest priority, highest confidence, union evidence, note all reviewers. This is more precise than judgment-based dedup.
+
+**Residual concerns**: Findings below the confidence threshold (0.50) are stored separately as residual concerns. During synthesis, residual concerns are promoted to findings if they overlap with findings from other reviewers or describe concrete blocking risks. This catches issues that one persona sees dimly but another confirms.
+
+**Per-persona confidence calibration**: Each persona defines its own confidence bands -- what HIGH (0.80+), MODERATE (0.60-0.79), and LOW mean for that persona's domain. This prevents apples-to-oranges confidence comparisons.
+
+**Explicit suppress conditions**: Each persona lists what it should NOT flag (e.g., coherence suppresses style preferences and missing content; feasibility suppresses implementation style choices). This prevents noise and keeps personas focused.
+
+**Subagent prompt template**: A shared template wraps each persona's identity + output schema + review context. This ensures consistent behavior across all personas without repeating boilerplate in each agent file.
+
+### Established Review Patterns
+
+Three proven review approaches provide the behavioral foundation for specific personas:
+
+**Premise challenge pattern (-> product-lens persona):**
+- Nuclear scope challenge with 3 questions: (1) Is this the right problem? Could a different framing yield a simpler/more impactful solution? (2) What is the actual user/business outcome? Is the plan the most direct path? (3) What happens if we do nothing? Real pain or hypothetical?
+- Implementation alternatives: Produce 2-3 approaches with effort (S/M/L/XL), risk (Low/Med/High), pros/cons
+- Search-before-building: Layer 1 (conventional), Layer 2 (search results), Layer 3 (first principles)
+
+**Dimensional rating pattern (-> design-lens persona):**
+- 0-10 rating loop: Rate dimension -> explain gap ("4 because X; 10 would have Y") -> suggest fix -> re-rate -> repeat
+- 7 evaluation passes: Information architecture, interaction state coverage, user journey/emotional arc, AI slop risk, design system alignment, responsive/a11y, unresolved design decisions
+- AI slop blacklist: 10 recognizable AI-generated patterns to avoid (3-column feature grids, purple gradients, icons in colored circles, uniform border-radius, etc.)
+
+**Existing-code audit pattern (-> scope-guardian + feasibility personas):**
+- "What already exists?" check: (1) What existing code partially/fully solves each sub-problem? (2) What is minimum set of changes for stated goal? (3) Complexity check (>8 files or >2 new classes = smell). (4) Search check per architectural pattern. (5) TODOS cross-reference
+- Completeness principle: With AI, completeness cost is 10-100x cheaper. If shortcut saves human hours but only minutes with AI, recommend complete version
+- Error & rescue map: For every method/codepath that can fail, name the exception class, trigger, handler, and user-visible outcome
+
+## Key Technical Decisions
+
+- **Agents, not inline prompts**: Persona reviewers are implemented as agent files under `agents/review/`. This enables parallel dispatch via Task tool, follows established patterns, and keeps the SKILL.md focused on orchestration. (Resolves deferred question from origin)
+
+- **Structured output contract aligned with ce:review-beta (PR #348)**: Same normalization mechanism -- findings-schema.json, subagent-template.md, review-output-template.md as reference files. Same field names and enums where applicable (severity P0-P3, autofix_class, owner, confidence, evidence). Document-specific adaptations: `section` replaces `file`+`line`, `deferred_questions` replaces `testing_gaps`, drop `pre_existing`. Each persona defines its own confidence calibration and suppress conditions. (Resolves deferred question from origin -- output format)
+
+- **Content-based activation heuristics**: The orchestrator skill checks the document for keyword and structural patterns to select conditional personas. Heuristics are defined in the skill, not in the agents -- this keeps selection logic centralized and agents focused on review. (Resolves deferred question from origin)
+
+- **Separate auto-fix pass after synthesis**: Personas are read-only (produce findings only). After dedup and synthesis, the orchestrator applies auto-fixes for quality issues in a single pass, then presents strategic questions. This prevents conflicting edits from multiple agents. (Resolves deferred question from origin)
+
+- **No caller modifications needed**: The "Review complete" contract is sufficient. All 4 callers reference document-review by skill name and check for the terminal signal. (Resolves deferred question from origin)
+
+- **Fingerprint-based dedup over judgment-based**: Use `normalize(section) + normalize(title)` fingerprinting for deterministic dedup. More reliable than asking the model to "remove duplicates" at synthesis time. When fingerprints match: keep highest priority, highest confidence, union evidence, note all agreeing reviewers.
+
+- **Residual concerns with cross-persona promotion**: Findings below 0.50 confidence are stored as residual concerns. During synthesis, promote to findings if corroborated by another persona or if they describe concrete blocking risks. This catches issues one persona sees dimly but another confirms.
+
+## Open Questions
+
+### Resolved During Planning
+
+- **Agent category**: Place under `agents/review/` alongside existing code review agents. Names are distinct (coherence-reviewer, feasibility-reviewer, etc.) and don't conflict with existing agents. Fully-qualified: `compound-engineering:review:<name>`.
+- **Parallel vs serial dispatch**: Always parallel. We have 2-6 agents per run (under the auto-serial threshold of 5 from ce:review's pattern). Even at max (6), these are document reviewers with bounded scope.
+- **Review pattern integration**: Premise challenge -> product-lens opener. Dimensional rating -> design-lens evaluation method. Existing-code audit -> scope-guardian opener. These are incorporated as agent behavior, not separate orchestration mechanisms.
+- **Output format**: Align with ce:review-beta (PR #348) normalization pattern. Same mechanism: JSON schema reference file, shared subagent template, output template. Same enums (P0-P3 severity, autofix_class, owner). Document-specific field swaps: `section` replaces `file`+`line`, `deferred_questions` replaces `testing_gaps`, drop `pre_existing`.
+
+### Deferred to Implementation
+
+- Exact keyword lists for conditional persona activation -- start with the obvious signals, refine based on real usage
+- Whether the auto-fix pass should re-read the document after applying changes to verify consistency, or trust a single pass
+
+## High-Level Technical Design
+
+> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
+
+```
+Document Review Pipeline Flow:
+
+1. READ document
+2. CLASSIFY document type (requirements doc vs plan)
+3. ANALYZE content for conditional persona signals
+   - product signals? -> activate product-lens
+   - design/UI signals? -> activate design-lens
+   - security/auth signals? -> activate security-lens
+   - scope/priority signals? -> activate scope-guardian
+4. ANNOUNCE review team with per-conditional justifications
+5. DISPATCH agents in parallel via Task tool
+   - Always: coherence-reviewer, feasibility-reviewer
+   - Conditional: activated personas from step 3
+   - Each receives: subagent-template.md populated with persona + schema + doc content
+6. COLLECT findings from all agents (validate against findings-schema.json)
+7. SYNTHESIZE
+   a. Validate: check structure compliance against schema, drop malformed
+   b. Confidence gate: suppress findings below 0.50
+   c. Deduplicate: fingerprint matching, keep highest severity/confidence
+   d. Promote residual concerns: corroborated or blocking -> promote to finding
+   e. Resolve contradictions: conflicting personas -> combined finding, manual + human
+   f. Route: safe_auto -> apply, everything else -> present
+8. APPLY safe_auto fixes (edit document inline, single pass)
+9. PRESENT remaining findings to user, grouped by severity
+10. FORMAT output using review-output-template.md
+11. OFFER next action: "Refine again" or "Review complete"
+```
+
+**Finding structure (aligned with ce:review-beta PR #348):**
+
+```
+Envelope (per persona):
+  reviewer:            Persona name (e.g., "coherence", "product-lens")
+  findings:            Array of finding objects
+  residual_risks:      Risks noticed but not confirmed as findings
+  deferred_questions:  Questions that should be resolved in a later workflow stage
+
+Finding object:
+  title:               Short issue title (<=10 words)
+  severity:            P0 / P1 / P2 / P3  (same scale as ce:review-beta)
+  section:             Document section where issue appears (replaces file+line)
+  why_it_matters:      Impact statement (what goes wrong if not addressed)
+  autofix_class:       safe_auto / gated_auto / manual / advisory
+  owner:               review-fixer / downstream-resolver / human / release
+  requires_verification: Whether fix needs re-review
+  suggested_fix:       Optional concrete fix (null if not obvious)
+  confidence:          0.0-1.0 (calibrated per persona)
+  evidence:            Quoted text from document (minimum 1)
+
+Severity definitions (same as ce:review-beta):
+  P0: Contradictions or gaps that would cause building the wrong thing. Must fix.
+  P1: Significant gap likely hit during planning/implementation. Should fix.
+  P2: Moderate issue with meaningful downside. Fix if straightforward.
+  P3: Minor improvement. User's discretion.
+
+Autofix classes (same enum as ce:review-beta for schema compatibility):
+  safe_auto:  Terminology fix, formatting, cross-reference -- local and deterministic
+  gated_auto: Restructure or edit that changes document meaning -- needs approval
+  manual:     Strategic question requiring user judgment -- becomes residual work
+  advisory:   Informational finding -- surface in report only
+
+Orchestrator routing (document review simplification):
+  The 4-class enum is preserved for schema compatibility with ce:review-beta,
+  but the orchestrator routes as 2 buckets:
+    safe_auto           -> apply automatically
+    gated_auto + manual + advisory -> present to user
+  The gated/manual/advisory distinction is blurry for documents (all need user
+  judgment). Personas still classify precisely; the orchestrator collapses.
+```
+
+## Implementation Units
+
+- [x] **Unit 1: Create always-on persona agents**
+
+**Goal:** Create the coherence and feasibility reviewer agents that run on every document review.
+
+**Requirements:** R2
+
+**Dependencies:** None
+
+**Files:**
+- Create: `plugins/compound-engineering/agents/document-review/ce-coherence-reviewer.agent.md`
+- Create: `plugins/compound-engineering/agents/document-review/ce-feasibility-reviewer.agent.md`
+
+**Approach:**
+- Follow existing agent structure: frontmatter (name, description, model: inherit), examples block, role definition, analysis protocol
+- Each agent defines: role identity, analysis protocol, confidence calibration, and suppress conditions
+- Agents do NOT define their own output format -- the shared `references/findings-schema.json` and `references/subagent-template.md` handle output normalization (same pattern as ce:review-beta PR #348)
+
+**coherence-reviewer:**
+- Role: Technical editor who reads for internal consistency
+- Hunts: contradictions between sections, terminology drift (same concept called different names), structural issues (sections that don't flow logically), ambiguity where readers would diverge on interpretation
+- Confidence calibration: HIGH (0.80+) = provable contradictions from text. MODERATE (0.60-0.79) = likely but could be reconciled charitably. Suppress below 0.50.
+- Suppress: style preferences, missing content (other personas handle that), imprecision that isn't actually ambiguity, formatting opinions
+
+**feasibility-reviewer:**
+- Role: Systems architect evaluating whether proposed approaches survive contact with reality
+- Hunts: architecture decisions that conflict with existing patterns, external dependencies without fallback plans, performance requirements without measurement plans, migration strategies with gaps, approaches that won't work with known constraints
+- Absorbs tech-plan implementability: can an implementer read this and start coding? Are file paths, interfaces, and dependencies specific enough?
+- Opens with "what already exists?" check: does the plan acknowledge existing code before proposing new abstractions?
+- Confidence calibration: HIGH (0.80+) = specific technical constraint that blocks approach. MODERATE (0.60-0.79) = constraint likely but depends on specifics not in document.
+- Suppress: implementation style choices, testing strategy details, code organization preferences, theoretical scalability concerns
+
+**Patterns to follow:**
+- `plugins/compound-engineering/agents/review/ce-code-simplicity-reviewer.agent.md` for agent structure and output format conventions
+- `plugins/compound-engineering/agents/review/ce-architecture-strategist.agent.md` for systematic analysis protocol style
+- iterative-engineering agents for confidence calibration and suppress conditions pattern
+
+**Test scenarios:**
+- coherence-reviewer identifies a plan where Section 3 claims "no external dependencies" but Section 5 proposes calling an external API
+- coherence-reviewer flags a document using "pipeline" and "workflow" interchangeably for the same concept
+- coherence-reviewer does NOT flag a minor formatting inconsistency (suppress condition working)
+- feasibility-reviewer identifies a requirement for "sub-millisecond response time" without a measurement or caching strategy
+- feasibility-reviewer identifies that a plan proposes building a custom auth system when the codebase already has one
+- feasibility-reviewer surfaces "what already exists?" when plan doesn't acknowledge existing patterns
+- Both agents produce findings with all required fields (title, priority, section, confidence, evidence, action)
+
+**Verification:**
+- Both agents have valid frontmatter (name, description, model: inherit)
+- Both agents include examples, role definition, analysis protocol, confidence calibration, and suppress conditions
+- Agents rely on shared findings-schema.json for output normalization (no per-agent output format)
+- Suppress conditions are explicit and sensible for each persona's domain
+
+---
+
+- [x] **Unit 2: Create conditional persona agents**
+
+**Goal:** Create the four conditional persona agents that activate based on document content.
+
+**Requirements:** R3
+
+**Dependencies:** Unit 1 (for consistent agent structure)
+
+**Files:**
+- Create: `plugins/compound-engineering/agents/document-review/ce-product-lens-reviewer.agent.md`
+- Create: `plugins/compound-engineering/agents/document-review/ce-design-lens-reviewer.agent.md`
+- Create: `plugins/compound-engineering/agents/document-review/ce-security-lens-reviewer.agent.md`
+- Create: `plugins/compound-engineering/agents/document-review/ce-scope-guardian-reviewer.agent.md`
+
+**Approach:**
+All four use the same structure established in Unit 1 (frontmatter, examples, role, protocol, confidence calibration, suppress conditions). Output normalization handled by shared reference files.
+
+**product-lens-reviewer:**
+- Role: Senior product leader evaluating whether the plan solves the right problem
+- Opens with premise challenge: 3 diagnostic questions:
+  1. Is this the right problem to solve? Could a different framing yield a simpler or more impactful solution?
+  2. What is the actual user/business outcome? Is the plan the most direct path, or is it solving a proxy problem?
+  3. What would happen if we did nothing? Real pain point or hypothetical?
+- Evaluates: scope decisions and prioritization rationale, implementation alternatives (are there simpler paths?), whether goals connect to requirements
+- Confidence calibration: HIGH (0.80+) = specific text demonstrating misalignment between stated goal and proposed work. MODERATE (0.60-0.79) = likely but depends on business context.
+- Suppress: implementation details, technical specifics, measurement methodology, style
+
+**design-lens-reviewer:**
+- Role: Senior product designer reviewing plans for missing design decisions
+- Uses "rate 0-10 and describe what 10 looks like" dimensional rating method
+- Evaluates design dimensions: information architecture (what does user see first/second/third?), interaction state coverage (loading, empty, error, success, partial), user flow completeness, responsive/accessibility considerations
+- Produces rated findings: "Information architecture: 4/10 -- it's a 4 because [gap]. A 10 would have [what's needed]."
+- AI slop check: flags plans that would produce generic AI-looking interfaces (3-column feature grids, purple gradients, icons in colored circles, uniform border-radius)
+- Confidence calibration: HIGH (0.80+) = missing states or flows that will clearly cause UX problems. MODERATE (0.60-0.79) = design gap exists but skilled designer could resolve from context.
+- Suppress: backend implementation details, performance concerns, security (other persona handles), business strategy
+
+**security-lens-reviewer:**
+- Role: Security architect evaluating threat model at the plan level
+- Evaluates: auth/authz gaps, data exposure risks, API surface vulnerabilities, input validation assumptions, secrets management, third-party trust boundaries, plan-level threat model completeness
+- Distinct from the code-level `security-sentinel` agent -- this reviews whether the PLAN accounts for security, not whether the CODE is secure
+- Confidence calibration: HIGH (0.80+) = plan explicitly introduces attack surface without mentioning mitigation. MODERATE (0.60-0.79) = security concern likely but plan may address it implicitly.
+- Suppress: code quality issues, performance, non-security architecture, business logic
+
+**scope-guardian-reviewer:**
+- Role: Product manager reviewing scope decisions for alignment, plus skeptic evaluating whether complexity earns its keep
+- Opens with "what already exists?" check: (1) What existing code/patterns already solve sub-problems? (2) What is the minimum set of changes for stated goal? (3) Complexity check -- if plan touches many files or introduces many new abstractions, is that justified?
+- Challenges: scope size relative to stated goals, unnecessary complexity, premature abstractions, framework-ahead-of-need, priority dependency conflicts (e.g., core feature depending on nice-to-have), scope boundaries violated by requirements, goals disconnected from requirements
+- Completeness principle check: is the plan taking shortcuts where the complete version would cost little more?
+- Confidence calibration: HIGH (0.80+) = can point to specific text showing scope conflict or unjustified complexity. MODERATE (0.60-0.79) = misalignment likely but depends on interpretation.
+- Suppress: implementation style choices, priority preferences (other persona handles), missing requirements (coherence handles), business strategy
+
+**Patterns to follow:**
+- Unit 1 agents for consistent structure
+- `plugins/compound-engineering/agents/review/ce-security-sentinel.agent.md` for security analysis style (plan-level adaptation)
+
+**Test scenarios:**
+- product-lens-reviewer challenges a plan that builds a complex admin dashboard when the stated goal is "improve user onboarding"
+- product-lens-reviewer produces premise challenge as its opening findings
+- design-lens-reviewer rates a user flow at 6/10 and describes what 10 looks like with specific missing states
+- design-lens-reviewer flags a plan describing "a modern card-based dashboard layout" as AI slop risk
+- security-lens-reviewer flags a plan that adds a public API endpoint without mentioning auth or rate limiting
+- security-lens-reviewer does NOT flag code quality issues (suppress condition working)
+- scope-guardian-reviewer identifies a plan with 12 implementation units when 4 would deliver the core value
+- scope-guardian-reviewer identifies that the plan proposes a custom solution when an existing framework would work
+- All four agents produce findings with all required fields
+
+**Verification:**
+- All four agents have valid frontmatter and follow the same structure as Unit 1
+- product-lens-reviewer includes the 3-question premise challenge
+- design-lens-reviewer includes the "rate 0-10, describe what 10 looks like" evaluation pattern
+- scope-guardian-reviewer includes the "what already exists?" opening check
+- All agents define confidence calibration and suppress conditions
+- All agents rely on shared findings-schema.json for output normalization
+
+---
+
+- [x] **Unit 3: Rewrite document-review skill with persona pipeline**
+
+**Goal:** Replace the current single-voice document-review SKILL.md with the persona pipeline orchestrator.
+
+**Requirements:** R1, R4, R5, R6, R7, R8
+
+**Dependencies:** Unit 1, Unit 2
+
+**Files:**
+- Modify: `plugins/compound-engineering/skills/document-review/SKILL.md`
+- Create: `plugins/compound-engineering/skills/document-review/references/findings-schema.json`
+- Create: `plugins/compound-engineering/skills/document-review/references/subagent-template.md`
+- Create: `plugins/compound-engineering/skills/document-review/references/review-output-template.md`
+
+**Approach:**
+
+**Reference files (aligned with ce:review-beta PR #348 mechanism):**
+- `findings-schema.json`: JSON schema that all persona agents must conform to. Same structure as ce:review-beta with document-specific swaps: `section` replaces `file`+`line`, `deferred_questions` replaces `testing_gaps`, drop `pre_existing`. Same enums for severity, autofix_class, owner.
+- `subagent-template.md`: Shared prompt template with variable slots ({persona_file}, {schema}, {document_content}, {document_path}, {document_type}). Rules: "Return ONLY valid JSON matching the schema", suppress below confidence floor, every finding needs evidence. Adapted from ce:review-beta's template for document context instead of diff context.
+- `review-output-template.md`: Markdown template for synthesized output. Findings grouped by severity (P0-P3), pipe-delimited tables with section, issue, reviewer, confidence, and route (autofix_class -> owner). Adapted from ce:review-beta's template for sections instead of file:line.
+
+The rewritten skill has these phases:
+
+**Phase 1 -- Get and Analyze Document:**
+- Same entry point as current: accept a path or find the most recent doc in `docs/brainstorms/` or `docs/plans/`
+- Read the document
+- Classify document type: requirements doc (from brainstorms/) or plan (from plans/)
+- Analyze content for conditional persona activation signals:
+  - product-lens: user-facing features, market claims, scope decisions, prioritization language, requirements with user/customer focus
+  - design-lens: UI/UX references, frontend components, user flows, wireframes, screen/page/view mentions
+  - security-lens: auth/authorization mentions, API endpoints, data handling, payments, tokens, credentials, encryption
+  - scope-guardian: multiple priority tiers (P0/P1/P2), large requirement count (>8), stretch goals, nice-to-haves, scope boundary language that seems misaligned
+
+**Phase 2 -- Announce and Dispatch Personas:**
+- Announce the review team with per-conditional justifications (e.g., "scope-guardian-reviewer -- plan has 12 requirements across 3 priority levels")
+- Build the agent list: always coherence-reviewer + feasibility-reviewer, plus activated conditional agents
+- Dispatch all agents in parallel via Task tool using fully-qualified names (`compound-engineering:review:<name>`)
+- Pass each agent: document content, document path, document type (requirements vs plan), and the structured output schema
+- Each agent receives the full document -- do not split into sections
+
+**Phase 3 -- Synthesize Findings:**
+Synthesis pipeline (order matters):
+1. **Validate**: Check each agent's output for structural compliance against findings-schema.json. Drop malformed findings but note the agent's name for the coverage section.
+2. **Confidence gate**: Suppress findings below 0.50 confidence. Store them as residual concerns.
+3. **Deduplicate**: Fingerprint each finding using `normalize(section) + normalize(title)`. When fingerprints match: keep highest severity, highest confidence, union evidence, note all agreeing reviewers.
+4. **Promote residual concerns**: Scan residual concerns for overlap with existing findings from other reviewers or concrete blocking risks. Promote to findings at P2 with confidence 0.55-0.65.
+5. **Resolve contradictions**: When personas disagree on the same section (e.g., scope-guardian says cut, coherence says keep for narrative flow), create a combined finding presenting both perspectives with autofix_class `manual` and owner `human` -- let the user decide.
+6. **Route by autofix_class**: `safe_auto` -> apply immediately. Everything else (`gated_auto`, `manual`, `advisory`) -> present to user. Personas classify precisely; the orchestrator collapses to 2 buckets.
+7. **Sort**: P0 -> P1 -> P2 -> P3, then by confidence (descending), then document order.
+
+**Phase 4 -- Apply and Present:**
+- Apply `safe_auto` fixes to the document inline (single pass)
+- Present all other findings (`gated_auto`, `manual`, `advisory`) to the user, grouped by severity
+- Show a brief summary: N auto-fixes applied, M findings to consider
+- Show coverage: which personas ran, any suppressed/residual counts
+- Use the review-output-template.md format for consistent presentation
+
+**Phase 5 -- Next Action:**
+- Use the platform's blocking question tool when available (AskUserQuestion in Claude Code, request_user_input in Codex, ask_user in Gemini). Otherwise present numbered options and wait.
+- Offer: "Refine again" or "Review complete"
+- After 2 refinement passes, recommend completion (carry over from current behavior)
+- "Review complete" as terminal signal for callers
+
+**Pipeline mode:** When called from automated workflows, auto-fixes run silently. Strategic questions are still surfaced (the calling skill decides whether to present them or convert to assumptions).
+
+**Protected artifacts:** Carry over from ce:review -- never flag `docs/brainstorms/`, `docs/plans/`, or `docs/solutions/` files for deletion. Discard any such findings during synthesis.
+
+**What NOT to do section:** Carry over current guardrails:
+- Don't rewrite the entire document
+- Don't add new requirements the user didn't discuss
+- Don't create separate review files or metadata sections
+- Don't over-engineer or add complexity
+- Don't add new sections not discussed in the brainstorm/plan
+
+**Conflict resolution rules for synthesis:**
+- When coherence says "keep for consistency" and scope-guardian says "cut for simplicity" -> combined finding, autofix_class: manual, owner: human
+- When feasibility says "this is impossible" and product-lens says "this is essential" -> P1 finding, autofix_class: manual, owner: human, frame as a tradeoff
+- When multiple personas flag the same issue -> merge into single finding, note consensus, increase confidence
+- When a residual concern from one persona matches a finding from another -> promote the concern, note corroboration
+
+**Patterns to follow:**
+- `plugins/compound-engineering/skills/ce-review/SKILL.md` for agent dispatch and synthesis patterns
+- Current `document-review/SKILL.md` for the entry point, iteration guidance, and "What NOT to Do" guardrails
+- iterative-engineering `plan-review/SKILL.md` for synthesis pipeline ordering and fingerprint dedup
+
+**Test scenarios:**
+- A backend refactor plan triggers only coherence + feasibility (no conditional personas)
+- A plan mentioning "user authentication flow" triggers coherence + feasibility + security-lens
+- A plan with UI mockups and 15 requirements triggers all 6 personas
+- A safe_auto finding correctly updates a terminology inconsistency without user approval
+- A gated_auto finding is presented to the user (not auto-applied) despite having a suggested_fix
+- A contradictory finding (scope-guardian vs coherence) is presented as a combined manual finding, not as two separate findings
+- A residual concern from one persona is promoted when corroborated by another persona's finding
+- Findings below 0.50 confidence are suppressed (not shown to user)
+- Duplicate findings from two personas are merged into one with both reviewer names
+- "Review complete" signal works correctly with a caller context
+- Second refinement pass recommends completion
+- Protected artifacts are not flagged for deletion
+
+**Verification:**
+- Skill has valid frontmatter (name: document-review, description updated to reflect persona pipeline)
+- All agent references use fully-qualified namespace (`compound-engineering:review:<name>`)
+- Entry point matches current skill (path or auto-find)
+- Terminal signal "Review complete" preserved
+- Conditional persona selection logic is centralized in the skill
+- Synthesis pipeline follows the correct ordering (validate -> gate -> dedup -> promote -> resolve -> route -> sort)
+- Reference files exist: findings-schema.json, subagent-template.md, review-output-template.md
+- Cross-platform guidance included (platform question tool with fallback)
+- Protected artifacts section present
+
+---
+
+- [x] **Unit 4: Update README and validate**
+
+**Goal:** Update plugin documentation to reflect the new agents and revised skill.
+
+**Requirements:** R1, R7
+
+**Dependencies:** Unit 1, Unit 2, Unit 3
+
+**Files:**
+- Modify: `plugins/compound-engineering/README.md`
+
+**Approach:**
+- Add 6 new agents to the Review table in README.md (coherence-reviewer, design-lens-reviewer, feasibility-reviewer, product-lens-reviewer, scope-guardian-reviewer, security-lens-reviewer)
+- Update agent count from "25+" to "31+" (or appropriate count after adding 6)
+- Update the document-review description in the skills table if it exists
+- Run `bun run release:validate` to verify consistency
+
+**Patterns to follow:**
+- Existing README.md table formatting
+- Alphabetical ordering within the Review agent table
+
+**Test scenarios:**
+- All 6 new agents appear in README Review table
+- Agent count is accurate
+- `bun run release:validate` passes
+
+**Verification:**
+- README agent count matches actual agent file count
+- All new agents listed with accurate descriptions
+- release:validate passes without errors
+
+## System-Wide Impact
+
+- **Interaction graph:** document-review is called from 4 skills (ce-brainstorm, ce-plan, ce-plan-beta, deepen-plan-beta). The "Review complete" contract is preserved, so no caller changes needed.
+- **Error propagation:** If a persona agent fails or times out during parallel dispatch, the orchestrator should proceed with findings from the agents that completed. Do not block the entire review on a single agent failure. Note the failed agent in the coverage section.
+- **State lifecycle risks:** None -- personas are read-only. Only the orchestrator modifies the document, in a single auto-fix pass.
+- **API surface parity:** The skill name (`document-review`) and terminal signal ("Review complete") remain unchanged. No breaking changes to callers.
+- **Integration coverage:** Verify the skill works when invoked standalone and from each of the 4 caller contexts.
+- **Finding noise risk:** With up to 6 personas, the total finding count could be high. The confidence gate (suppress below 0.50), dedup (fingerprint matching), and suppress conditions (per-persona) are the three mechanisms that control noise. If findings are still too noisy in practice, tighten the confidence gate or add suppress conditions.
+
+## Risks & Dependencies
+
+- **Agent dispatch limit:** ce:review auto-switches to serial mode at >5 agents. Maximum dispatch here is 6 (2 always-on + 4 conditional). If all 6 activate, the orchestrator should still use parallel dispatch since these are lightweight document reviewers reading a single document, not code analyzers scanning a codebase. Document this decision in the skill.
+- **Contradictory findings:** The synthesis phase must handle conflicting persona findings explicitly. The initial implementation should lean toward presenting contradictions (both perspectives as a combined finding) rather than auto-resolving them. This preserves value even if it's slightly noisier.
+- **Finding volume at full activation:** When all 6 personas activate on a large document, the total pre-dedup finding count could exceed 20-30. The synthesis pipeline (confidence gate + dedup + suppress conditions) should reduce this to a manageable set. If it doesn't, the first lever to pull is tightening per-persona suppress conditions.
+- **Persona prompt quality:** The agents are only as good as their prompts. The established review patterns and iterative-engineering references provide battle-tested material, but the compound-engineering versions will be new and may need iteration. Plan for 1-2 rounds of prompt refinement after initial implementation.
+
+## Sources & References
+
+- **Origin document:** [docs/brainstorms/2026-03-23-plan-review-personas-requirements.md](docs/brainstorms/2026-03-23-plan-review-personas-requirements.md)
+- Related code: `plugins/compound-engineering/skills/ce-review/SKILL.md` (multi-agent orchestration pattern)
+- Related code: `plugins/compound-engineering/skills/document-review/SKILL.md` (current implementation to replace)
+- Related code: `plugins/compound-engineering/agents/review/` (agent structure reference)
+- Related pattern: iterative-engineering `skills/plan-review/SKILL.md` (synthesis pipeline, findings schema, subagent template)
+- Related pattern: iterative-engineering `agents/coherence-reviewer.md`, `feasibility-reviewer.md`, `scope-guardian-reviewer.md`, `prd-reviewer.md`, `tech-plan-reviewer.md`, `skeptic-reviewer.md` (persona prompt design, confidence calibration, suppress conditions)
+- Related learning: `docs/solutions/skill-design/compound-refresh-skill-improvements.md` (subagent design patterns)

docs/plans/2026-03-23-001-feat-promote-plan-beta-skills-to-stable-plan.md

@@ -0,0 +1,132 @@
+---
+title: "feat: promote ce:plan-beta and deepen-plan-beta to stable"
+type: feat
+status: completed
+date: 2026-03-23
+---
+
+# Promote ce:plan-beta and deepen-plan-beta to stable
+
+## Overview
+
+Replace the stable `ce:plan` and `deepen-plan` skills with their validated beta counterparts, following the documented 9-step promotion path from `docs/solutions/skill-design/beta-skills-framework.md`.
+
+## Problem Statement
+
+The beta versions of `ce:plan` and `deepen-plan` have been tested and are ready for promotion. They currently sit alongside the stable versions as separate skill directories with `disable-model-invocation: true`, meaning users must invoke them manually. Promotion makes them the default for all workflows including `lfg`/`slfg` orchestration.
+
+## Proposed Solution
+
+Follow the beta-skills-framework promotion checklist exactly, applied to both skill pairs simultaneously.
+
+## Implementation Plan
+
+### Phase 1: Replace stable SKILL.md content with beta content
+
+**Files to modify:**
+
+1. **`skills/ce-plan/SKILL.md`** -- Replace entire content with `skills/ce-plan-beta/SKILL.md`
+2. **`skills/deepen-plan/SKILL.md`** -- Replace entire content with `skills/deepen-plan-beta/SKILL.md`
+
+### Phase 2: Restore stable frontmatter and remove beta markers
+
+**In promoted `skills/ce-plan/SKILL.md`:**
+
+- Change `name: ce:plan-beta` to `name: ce:plan`
+- Remove `[BETA] ` prefix from description
+- Remove `disable-model-invocation: true` line
+
+**In promoted `skills/deepen-plan/SKILL.md`:**
+
+- Change `name: deepen-plan-beta` to `name: deepen-plan`
+- Remove `[BETA] ` prefix from description
+- Remove `disable-model-invocation: true` line
+
+### Phase 3: Update all internal references from beta to stable names
+
+**In promoted `skills/ce-plan/SKILL.md`:**
+
+- All references to `/deepen-plan-beta` become `/deepen-plan`
+- All references to `ce:plan-beta` become `ce:plan` (in headings, prose, etc.)
+- All references to `-beta-plan.md` file suffix become `-plan.md`
+- Example filenames using `-beta-plan.md` become `-plan.md`
+
+**In promoted `skills/deepen-plan/SKILL.md`:**
+
+- All references to `ce:plan-beta` become `ce:plan`
+- All references to `deepen-plan-beta` become `deepen-plan`
+- Scratch directory paths: `deepen-plan-beta` becomes `deepen-plan`
+
+### Phase 4: Clean up ce-work-beta cross-reference
+
+**In `skills/ce-work-beta/SKILL.md` (line 450):**
+
+- Remove `ce:plan-beta or ` from the text so it reads just `ce:plan`
+
+### Phase 5: Delete beta skill directories
+
+- Delete `skills/ce-plan-beta/` directory entirely
+- Delete `skills/deepen-plan-beta/` directory entirely
+
+### Phase 6: Update README.md
+
+**In `plugins/compound-engineering/README.md`:**
+
+1. **Update `ce:plan` description** in the Workflow Commands table (line 81): Change from `Create implementation plans` to `Transform features into structured implementation plans grounded in repo patterns`
+2. **Update `deepen-plan` description** in the Utility Commands table (line 93): Description already says `Stress-test plans and deepen weak sections with targeted research` which matches the beta -- verify and keep
+3. **Remove the entire Beta Skills section** (lines 156-165): The `### Beta Skills` heading, explanatory paragraph, table with `ce:plan-beta` and `deepen-plan-beta` rows, and the "To test" line
+4. **Update skill count**: Currently `40+` in the Components table. Removing 2 beta directories decreases the count. Verify with `bun run release:validate` and update if needed
+
+### Phase 7: Validation
+
+1. **Search for remaining `-beta` references**: Grep all files under `plugins/compound-engineering/` for leftover `plan-beta` strings -- every hit is a bug, except historical entries in `CHANGELOG.md` which are expected and must not be modified
+2. **Run `bun run release:validate`**: Check plugin/marketplace consistency, skill counts
+3. **Run `bun test`**: Ensure converter tests still pass (they use skill names as fixtures)
+4. **Verify `lfg`/`slfg` references**: Confirm they reference stable `/ce:plan` and `/deepen-plan` (they already do -- no change needed)
+5. **Verify `ce:brainstorm` handoff**: Confirms it hands off to stable `/ce:plan` (already does -- no change needed)
+6. **Verify `ce:work` compatibility**: Plans from promoted skills use `-plan.md` suffix, same as before
+
+## Files Changed
+
+| File | Action | Notes |
+|------|--------|-------|
+| `skills/ce-plan/SKILL.md` | Replace | Beta content with stable frontmatter |
+| `skills/deepen-plan/SKILL.md` | Replace | Beta content with stable frontmatter |
+| `skills/ce-plan-beta/` | Delete | Entire directory |
+| `skills/deepen-plan-beta/` | Delete | Entire directory |
+| `skills/ce-work-beta/SKILL.md` | Edit | Remove `ce:plan-beta or` reference at line 450 |
+| `README.md` | Edit | Remove Beta Skills section, verify counts and descriptions |
+
+## Files NOT Changed (verified safe)
+
+These files reference stable `ce:plan` or `deepen-plan` and require **no changes** because stable names are preserved:
+
+- `skills/lfg/SKILL.md` -- calls `/ce:plan` and `/deepen-plan`
+- `skills/slfg/SKILL.md` -- calls `/ce:plan` and `/deepen-plan`
+- `skills/ce-brainstorm/SKILL.md` -- hands off to `/ce:plan`
+- `skills/ce-ideate/SKILL.md` -- explains pipeline
+- `skills/document-review/SKILL.md` -- references `/ce:plan`
+- `skills/ce-compound/SKILL.md` -- references `/ce:plan`
+- `skills/ce-review/SKILL.md` -- references `/ce:plan`
+- `AGENTS.md` -- lists `ce:plan`
+- `agents/research/learnings-researcher.md` -- references both
+- `agents/research/git-history-analyzer.md` -- references `/ce:plan`
+- `agents/review/code-simplicity-reviewer.md` -- references `/ce:plan`
+- `plugin.json` / `marketplace.json` -- no individual skill listings
+
+## Acceptance Criteria
+
+- [ ] `skills/ce-plan/SKILL.md` contains the beta planning approach (decision-first, phase-structured)
+- [ ] `skills/deepen-plan/SKILL.md` contains the beta deepening approach (selective stress-test, risk-weighted)
+- [ ] No `disable-model-invocation` in either promoted skill
+- [ ] No `[BETA]` prefix in either description
+- [ ] No remaining `-beta` references in any file under `plugins/compound-engineering/`
+- [ ] `skills/ce-plan-beta/` and `skills/deepen-plan-beta/` directories deleted
+- [ ] README Beta Skills section removed
+- [ ] `bun run release:validate` passes
+- [ ] `bun test` passes
+
+## Sources
+
+- **Promotion checklist:** `docs/solutions/skill-design/beta-skills-framework.md` (steps 1-9)
+- **Versioning rules:** `docs/solutions/plugin-versioning-requirements.md` (no manual version bumps)

docs/plans/2026-03-25-001-feat-onboarding-skill-plan.md

@@ -0,0 +1,281 @@
+---
+title: "feat: Add onboarding skill to generate ONBOARDING.md from repo crawl"
+type: feat
+status: complete
+date: 2026-03-25
+origin: docs/brainstorms/2026-03-25-vonboarding-skill-requirements.md
+---
+
+# feat: Add onboarding skill to generate ONBOARDING.md from repo crawl
+
+## Overview
+
+Add an `/onboarding` skill to the compound-engineering plugin that crawls a repository and generates `ONBOARDING.md` at the repo root. The skill uses a bundled inventory script for deterministic data gathering and model judgment for narrative synthesis, producing a document that helps new contributors understand the codebase without requiring the creator to explain it.
+
+## Problem Frame
+
+When a codebase is built through AI-assisted "vibe coding," the creator may not fully understand their own architecture. New team members are left without the mental model they need to contribute. The onboarding document reconstructs this mental model from the code itself.
+
+The primary audience is human developers. A document that works for human comprehension is also effective as agent context, but the inverse is not true. (see origin: `docs/brainstorms/2026-03-25-vonboarding-skill-requirements.md`)
+
+## Requirements Trace
+
+- R1. A skill named `onboarding` that crawls a repository and generates `ONBOARDING.md` at the repo root
+- R2. The skill always regenerates the full document from scratch -- no surgical updates or diffing
+- R3. Fixed filename (`ONBOARDING.md`) is the only state -- exists means refresh, doesn't exist means create
+- R4. Exactly five sections: What is this thing? / How is it organized? / Key concepts / Primary flow / Where do I start?
+- R5. Inline-link existing docs when directly relevant to a section; no separate references section
+- R6. Written for human comprehension first -- clear prose, not structured data
+- R7. Use visual aids -- ASCII diagrams, markdown tables -- where they improve readability over prose
+- R8. Proper markdown formatting throughout -- backticks for file names, paths, commands, code references, and technical terms
+
+## Scope Boundaries
+
+- Does not infer or fabricate design rationale
+- Does not assess fragility or risk areas
+- Does not generate README.md, CLAUDE.md, AGENTS.md, or any other document
+- Does not preserve hand-edits from a previous version
+- No `ce:` prefix -- standalone utility skill
+- No new agents -- the skill uses a bundled script plus the model's own file-reading and writing capabilities
+
+## Context & Research
+
+### Relevant Code and Patterns
+
+- Skills live in `plugins/compound-engineering/skills/<name>/SKILL.md` with optional `scripts/`, `references/`, `assets/` directories
+- Skills are auto-discovered from directory structure -- no registration in `plugin.json`
+- SKILL.md requires YAML frontmatter with `name` and `description` fields
+- Arguments received via `#$ARGUMENTS` interpolation in an XML tag
+- Platform-agnostic interaction: use capability-class tool descriptions with platform hints
+- Reference files must be proper markdown links, not bare backtick paths
+
+### Institutional Learnings
+
+- **Script-first skill architecture** (`docs/solutions/skill-design/script-first-skill-architecture.md`): Move deterministic processing into bundled scripts; model does judgment work only. 60-75% token reduction. Applies here as a hybrid -- script gathers structural inventory, model reads key files and writes prose.
+- **Compound-refresh skill improvements** (`docs/solutions/skill-design/compound-refresh-skill-improvements.md`): Triage before asking (don't ask users what to document); platform-agnostic tool references; subagents should use file tools not shell; no contradictory rules across phases.
+- Skill compliance checklist in `plugins/compound-engineering/AGENTS.md`: imperative voice, no second person, cross-platform question tool patterns, markdown-linked references.
+
+## Key Technical Decisions
+
+- **Hybrid script-first architecture**: The inventory script handles deterministic work (file tree, manifest parsing, framework detection, entry point identification, doc discovery). The model handles judgment work (reading key files, understanding architecture, tracing flows, writing prose). This follows the institutional pattern and avoids burning tokens on mechanical directory traversal.
+
+- **No sub-agent dispatch**: The five sections are interdependent -- understanding architecture informs the primary flow, domain terms appear across sections. A single model pass produces a more coherent document than independent sub-agents writing sections in isolation. The inventory script provides the structural grounding the model needs.
+
+- **No `repo-research-analyst` dependency**: That agent produces research-formatted output for planning skills. Using it would add a layer of indirection (research output -> re-synthesis into human prose). A simpler inventory script gives the model raw facts and lets it write directly for the human audience.
+
+- **Universal inventory script**: The script must work across any language/framework by detecting from manifests and conventional directory locations. It does not parse code ASTs or read file contents -- those are model tasks.
+
+- **No explicit create/refresh mode**: The skill always regenerates. The SKILL.md need not branch on whether `ONBOARDING.md` exists -- the behavior is identical either way.
+
+## Open Questions
+
+### Resolved During Planning
+
+- **Orchestration strategy**: Single-pass with bundled inventory script. Sub-agents per section would create overlapping crawls and lose cross-section coherence. The document is short enough for one model pass.
+- **Primary flow strategy**: Entry point tracing guided by inventory. The script identifies entry points; the model reads the primary one and follows the main user-facing path through imports and calls.
+- **Section depth/length**: No prescriptive line counts. Guiding principle: each section answers its question concisely enough that a new person reads the entire document. Total should be readable in under 10 minutes.
+- **Doc relevance heuristic**: Model judgment during writing. The inventory lists existing docs; when the model writes about a topic and a discovered doc is relevant, it links inline. No programmatic relevance scoring.
+
+### Deferred to Implementation
+
+- Exact JSON schema for inventory script output -- the shape will be refined when writing the script against real repos
+- Which conventional entry point locations to check per ecosystem -- will be enumerated during script implementation
+- Precise wording of the section writing guidance in SKILL.md -- will iterate during implementation
+
+## Implementation Units
+
+- [ ] **Unit 1: Create the inventory script**
+
+  **Goal:** Build a Node.js script that produces a structured JSON inventory of any repository, giving the model a map to work from without burning tokens on directory traversal.
+
+  **Requirements:** R1 (crawl mechanism), R5 (doc discovery)
+
+  **Dependencies:** None
+
+  **Files:**
+  - Create: `plugins/compound-engineering/skills/onboarding/scripts/inventory.mjs`
+  - Test: `tests/onboarding-inventory.test.ts`
+
+  **Approach:**
+
+  The script accepts an optional `--root <path>` argument (defaults to cwd) and writes JSON to stdout. It gathers:
+
+  - **Project identity**: Name from the nearest manifest (package.json `name`, Cargo.toml `[package].name`, go.mod module path, etc.), falling back to directory name
+  - **Languages and frameworks**: Detected from manifest files using the same ecosystem mapping table as `repo-research-analyst` Phase 0.1. Extract language, major framework dependencies, and versions from each manifest found. Include package manager and test framework when detectable.
+  - **Directory structure**: Top-level directories plus one level into `src/`, `lib/`, `app/`, `pkg/`, `internal/` (or equivalent). Cap at 2 levels deep. Exclude `node_modules/`, `.git/`, `vendor/`, `target/`, `dist/`, `build/`, `__pycache__/`, `.next/`, `.cache/`, and other common build/dependency directories.
+  - **Entry points**: Check conventional locations per detected ecosystem:
+    - Node/TS: `src/index.*`, `src/main.*`, `src/app.*`, `index.*`, `server.*`, `app.*`, `pages/`, `app/` (Next.js)
+    - Python: `main.py`, `app.py`, `manage.py`, `src/<project>/`, `__main__.py`
+    - Ruby: `config/routes.rb`, `app/controllers/`, `bin/rails`, `config.ru`
+    - Go: `main.go`, `cmd/*/main.go`
+    - Rust: `src/main.rs`, `src/lib.rs`
+    - General: `Makefile`, `Procfile` targets
+  - **Scripts/commands**: Extract from `package.json` scripts, Makefile targets, or equivalent. Focus on dev, build, test, start, and lint commands.
+  - **Existing documentation**: Find markdown files in repo root and common doc directories (`docs/`, `doc/`, `documentation/`, `docs/solutions/`, `wiki/`). List paths only, don't read contents.
+  - **Test infrastructure**: Detect test directories and config files (`tests/`, `test/`, `spec/`, `__tests__/`, `jest.config.*`, `vitest.config.*`, `.rspec`, `pytest.ini`, `conftest.py`)
+
+  Output shape (directional -- exact fields will be refined during implementation):
+  ```
+  {
+    "name": "...",
+    "languages": [...],
+    "frameworks": [...],
+    "packageManager": "...",
+    "testFramework": "...",
+    "structure": { "topLevel": [...], "srcLayout": [...] },
+    "entryPoints": [...],
+    "scripts": { ... },
+    "docs": [...],
+    "testInfra": { "dirs": [...], "config": [...] }
+  }
+  ```
+
+  The script must:
+  - Use only Node.js built-in modules (`fs`, `path`, `child_process` for git-tracked file list if useful)
+  - Exit 0 and output valid JSON even when manifests are missing or unparseable
+  - Be fast -- no network calls, no AST parsing, bounded directory traversal
+  - Handle monorepos gracefully (list workspace structure without recursing into every package)
+
+  **Patterns to follow:**
+  - `skills/claude-permissions-optimizer/scripts/extract-commands.mjs` -- script-first pattern, JSON output, CLI flags, Node.js built-ins only
+
+  **Test scenarios:**
+  - Script produces valid JSON for a minimal repo (just a README)
+  - Script detects Node.js ecosystem from `package.json`
+  - Script detects multiple languages in a polyglot repo
+  - Script respects directory depth limits
+  - Script excludes common build/dependency directories
+  - Script exits 0 with empty/partial JSON when manifests are malformed
+  - Script finds entry points for at least Node, Python, and Ruby ecosystems
+  - Script discovers docs in standard locations
+
+  **Verification:**
+  - Running the script against the compound-engineering repo produces sensible output
+  - JSON output parses without error
+  - Script completes in under 5 seconds on a typical repo
+
+- [ ] **Unit 2: Create the SKILL.md**
+
+  **Goal:** Write the skill definition that orchestrates the inventory script, guided file reading, and narrative synthesis into `ONBOARDING.md`.
+
+  **Requirements:** R1, R2, R3, R4, R5, R6, R7, R8
+
+  **Dependencies:** Unit 1
+
+  **Files:**
+  - Create: `plugins/compound-engineering/skills/onboarding/SKILL.md`
+
+  **Approach:**
+
+  The SKILL.md contains:
+
+  1. **Frontmatter**: `name: onboarding`, description that covers what it does and when to use it, `argument-hint` for optional scope/focus hints.
+
+  2. **Execution flow** with three phases:
+
+     **Phase 1: Gather inventory.** Run the bundled script. Parse the JSON output. This gives the model a structural map of the repo without reading every file.
+
+     **Phase 2: Read key files.** Guided by the inventory, read files that are essential for understanding the codebase:
+     - README.md (if exists) -- for project purpose and setup
+     - Primary entry points identified by the script
+     - Route/controller files (for understanding the primary flow)
+     - Configuration files that reveal architecture (e.g., docker-compose, database config)
+     - A sample of the discovered documentation files (for inline linking in Phase 3)
+
+     Cap the reading at a reasonable number of files (~10-15 key files) to avoid context bloat. Prioritize entry points and routes over config files. Use the native file-read tool, not shell commands.
+
+     **Phase 3: Write ONBOARDING.md.** Synthesize everything into the five sections. Guidance for each section:
+
+     - **What is this thing?** -- Draw from README, manifest descriptions, and entry point examination. State the purpose, who it's for, and what problem it solves. If this can't be determined, say so plainly rather than fabricating.
+     - **How is it organized?** -- Use the inventory structure plus what was learned from reading key files. Describe the architecture, key modules, and how they connect. Use an ASCII directory tree to show the high-level structure. Use a markdown table when listing modules with their responsibilities.
+     - **Key concepts / domain terms** -- Extract domain vocabulary from code (class names, module names, database tables, API endpoints) and explain each in one sentence. Present as a markdown table (`| Term | Definition |`) for scanability. These are the words someone needs to talk about this codebase.
+     - **Primary flow** -- Trace one concrete path from the user's perspective. Start with the main thing the app does (e.g., "when a user submits an order..."), then walk through the code path: which file handles the request, what services it calls, where data is stored. Use an ASCII flow diagram to visualize the path (e.g., `Request -> Router -> Controller -> Service -> DB`). Reference specific file paths at each step.
+     - **Where do I start?** -- Dev setup from README or scripts. How to run the app, how to run tests. Where to make common types of changes (e.g., "to add a new API endpoint, look at `src/routes/`"). List the 2-3 most common change patterns.
+
+     For each section: if a discovered documentation file is directly relevant to what the section is explaining, link to it inline (e.g., "authentication uses token-based middleware -- see `docs/solutions/auth-pattern.md` for details"). Do not create a separate references section. If no relevant docs exist, the section stands alone.
+
+  3. **Quality bar**: Before writing the file, verify:
+     - Every section answers its question without padding
+     - No fabricated design rationale or fragility assessments
+     - File paths referenced in the document actually exist in the inventory
+     - Prose is written for a human developer, not formatted as agent-consumable structured data
+     - Existing docs are linked inline only where directly relevant, not collected in an appendix
+     - All file names, paths, commands, code references, and technical terms use backtick formatting
+     - Markdown styling is consistent throughout (headers, bold, code blocks, tables)
+
+  4. **Post-generation options**: After writing, present options using the platform's blocking question tool:
+     - Open the file for review
+     - Commit the file
+     - Done
+
+  **Patterns to follow:**
+  - `skills/ce-plan/SKILL.md` -- research-then-write orchestration, platform-agnostic tool references
+  - `skills/claude-permissions-optimizer/SKILL.md` -- script-first execution pattern
+  - Skill compliance checklist in `plugins/compound-engineering/AGENTS.md`
+
+  **Test scenarios:**
+  - The skill description triggers on "generate onboarding", "onboard new contributor", "create ONBOARDING.md", "document this codebase for new developers"
+  - The skill runs the inventory script as its first action
+  - The skill reads key files identified by inventory, not arbitrary files
+  - The generated ONBOARDING.md contains exactly five sections
+  - The skill does not ask the user what to document -- it triages autonomously
+  - File paths referenced in ONBOARDING.md correspond to real files in the repo
+
+  **Verification:**
+  - SKILL.md passes the compliance checklist (no hardcoded tool names, imperative voice, markdown-linked scripts, platform-agnostic question patterns)
+  - Running the skill against a real repo produces a readable ONBOARDING.md with all five sections
+  - Re-running the skill regenerates the file from scratch (no diffing or updating behavior)
+
+- [ ] **Unit 3: Update README and validate plugin**
+
+  **Goal:** Register the new skill in the plugin README and verify plugin consistency.
+
+  **Requirements:** R1
+
+  **Dependencies:** Unit 2
+
+  **Files:**
+  - Modify: `plugins/compound-engineering/README.md`
+
+  **Approach:**
+
+  Add `onboarding` to the **Workflow Utilities** table in README.md:
+
+  ```
+  | `/onboarding` | Generate ONBOARDING.md to help new contributors understand the codebase |
+  ```
+
+  Update the skill count in the Components table if it's now inaccurate (currently "40+").
+
+  **Patterns to follow:**
+  - Existing README skill table format and descriptions
+
+  **Test scenarios:**
+  - Skill appears in the correct category table
+  - Description is concise and matches SKILL.md description intent
+  - Component count is accurate
+
+  **Verification:**
+  - `bun run release:validate` passes
+  - README skill count matches actual skill count
+
+## System-Wide Impact
+
+- **Interaction graph:** The skill is standalone -- no callbacks, middleware, or cross-skill dependencies. Other skills do not invoke it.
+- **Error propagation:** If the inventory script fails (malformed JSON, permission error), the skill should report the error and stop rather than attempting to write ONBOARDING.md from incomplete data.
+- **API surface parity:** The skill outputs a file, not an API. No parity concerns.
+- **Integration coverage:** Manual testing against a real repo is the primary integration check. The inventory script gets unit tests.
+
+## Risks & Dependencies
+
+- **Inventory script universality**: The script needs to handle repos in any language/framework. Risk: edge cases in ecosystem detection for less common stacks. Mitigation: start with the most common ecosystems (Node, Python, Ruby, Go, Rust) and degrade gracefully for others (still produce structure and docs, just skip framework-specific entry point detection).
+- **Output quality variance**: The quality of ONBOARDING.md depends heavily on the model's synthesis ability, which varies by codebase complexity. Mitigation: the quality bar in SKILL.md sets clear expectations, and the five-section structure constrains scope.
+- **Token budget**: Large codebases could produce large inventories or require reading many files. Mitigation: the inventory script caps directory depth, and the SKILL.md caps file reading at ~10-15 key files.
+
+## Sources & References
+
+- **Origin document:** [docs/brainstorms/2026-03-25-vonboarding-skill-requirements.md](../brainstorms/2026-03-25-vonboarding-skill-requirements.md)
+- Script-first architecture: [docs/solutions/skill-design/script-first-skill-architecture.md](../solutions/skill-design/script-first-skill-architecture.md)
+- Compound-refresh learnings: [docs/solutions/skill-design/compound-refresh-skill-improvements.md](../solutions/skill-design/compound-refresh-skill-improvements.md)
+- Repo-research-analyst agent: `plugins/compound-engineering/agents/research/ce-repo-research-analyst.agent.md`
+- Skill compliance checklist: `plugins/compound-engineering/AGENTS.md`

docs/plans/2026-03-25-002-refactor-config-storage-redesign-plan.md

@@ -0,0 +1,367 @@
+---
+title: "refactor: Redesign config and worktree-safe storage for compound-engineering"
+type: refactor
+status: active
+date: 2026-03-25
+deepened: 2026-03-25
+origin: docs/brainstorms/2026-03-25-config-storage-redesign-requirements.md
+---
+
+# Redesign Config and Worktree-Safe Storage for Compound Engineering
+
+## Overview
+
+Replace the legacy repo-local config and storage assumptions with a two-scope state model:
+
+- `user_state_dir` for user-level CE state and per-project durable storage
+- `repo_state_dir` for repo-local CE config
+
+The work preserves the new `/ce-doctor` + `/ce-setup` dependency flow already added on this branch, but repoints it at the new state contract and migrates durable plugin state out of `.context/compound-engineering/...` and `todos/`.
+
+## Problem Frame
+
+The current plugin still treats repo-local `.context/compound-engineering/...` and legacy `compound-engineering.local.md` as stable runtime contracts. That breaks across git worktrees, leaves setup migration undefined, and leaks old assumptions into docs, tests, and converter fixtures. Main has also removed setup-managed reviewer selection, so this refactor must not recreate that model in a new config file. (see origin: `docs/brainstorms/2026-03-25-config-storage-redesign-requirements.md`)
+
+## Requirements Trace
+
+- R1-R10. Introduce YAML config under `repo_state_dir`, keep compatibility metadata minimal, and make `/ce-setup` the sole migration owner for legacy config.
+- R11-R16. Codify the standard config/storage contract section in `AGENTS.md`, keep it cross-agent and low-friction, and centralize migration warnings in core entry skills plus `/ce-doctor`.
+- R17-R23. Resolve durable CE state under `user_state_dir/projects/<project-slug>/`, preserve legacy todo reads, and move future durable writes there.
+- R24-R31. Expand `/ce-doctor` and `/ce-setup` around the new config/storage contract while preserving the registry-driven dependency flow and fresh scans.
+- R32-R33. Remove the old config/storage contract from skills, tests, and converter surfaces without introducing provider-specific paths.
+
+## Scope Boundaries
+
+- Do not reintroduce review-agent selection or review-context storage into plugin-managed config.
+- Do not actively migrate historical per-run scratch directories out of repo-local `.context/compound-engineering/...`.
+- Do not add garbage collection or pruning for orphaned per-project directories.
+- Do not keep `compound-engineering.local.md` as a long-term dual-write format; treat it as legacy migration input only.
+- Do not expand this work into project dependency management such as `bundle install`, app setup, or team-authored config workflows beyond laying the repo-local config structure.
+
+## Context & Research
+
+### Relevant Code and Patterns
+
+- [plugins/compound-engineering/skills/ce-setup/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-setup/SKILL.md) now focuses on dependency setup only; review-agent configuration is already gone on main.
+- [plugins/compound-engineering/skills/ce-doctor/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-doctor/SKILL.md) and [plugins/compound-engineering/skills/ce-doctor/scripts/check-health](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-doctor/scripts/check-health) already provide the shared diagnostic surface and script-first dependency checks.
+- [plugins/compound-engineering/skills/ce-brainstorm/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md), [plugins/compound-engineering/skills/ce-plan/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-plan/SKILL.md), and [plugins/compound-engineering/skills/ce-work/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-work/SKILL.md) are the concrete core entry skills that currently lack any shared migration-warning contract.
+- [plugins/compound-engineering/skills/todo-create/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/todo-create/SKILL.md), [plugins/compound-engineering/skills/todo-triage/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/todo-triage/SKILL.md), and [plugins/compound-engineering/skills/todo-resolve/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/todo-resolve/SKILL.md) encode the current todo path contract and legacy-drain semantics.
+- [plugins/compound-engineering/skills/ce-review/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-review/SKILL.md), [plugins/compound-engineering/skills/feature-video/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/feature-video/SKILL.md), and [plugins/compound-engineering/skills/deepen-plan/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/deepen-plan/SKILL.md) are the highest-signal per-run artifact consumers still hardcoding `.context/compound-engineering/...`.
+- Converter/test surfaces still encode the old contract in [tests/converter.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/converter.test.ts), [tests/codex-converter.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/codex-converter.test.ts), [tests/copilot-converter.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/copilot-converter.test.ts), [tests/pi-converter.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/pi-converter.test.ts), [tests/review-skill-contract.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/review-skill-contract.test.ts), [src/utils/codex-agents.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/src/utils/codex-agents.ts), and [src/converters/claude-to-pi.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/src/converters/claude-to-pi.ts).
+- [docs/solutions/skill-design/beta-skills-framework.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/docs/solutions/skill-design/beta-skills-framework.md) is an active solution doc that still references the old config contract, so the doc sweep cannot be limited to tests and plugin README alone.
+- Repo-level instruction surfaces live in [AGENTS.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/AGENTS.md) and [plugins/compound-engineering/AGENTS.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/AGENTS.md).
+
+### Institutional Learnings
+
+- [docs/solutions/skill-design/compound-refresh-skill-improvements.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/docs/solutions/skill-design/compound-refresh-skill-improvements.md): keep skill instructions platform-agnostic, avoid hardcoded tool names, and prefer dedicated file tools over shell exploration to reduce prompts.
+- [docs/solutions/workflow/todo-status-lifecycle.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/docs/solutions/workflow/todo-status-lifecycle.md): todo status is load-bearing; any path migration must preserve the pending/ready/complete pipeline rather than flattening it.
+- [docs/solutions/codex-skill-prompt-entrypoints.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/docs/solutions/codex-skill-prompt-entrypoints.md): copied `SKILL.md` content is often passed through mostly as-is, so skill wording must remain meaningful without target-specific rewriting assumptions.
+
+### External References
+
+- None. The repo already contains sufficient current patterns for this planning pass.
+
+## Key Technical Decisions
+
+- **Keep the state vocabulary to two named directories.** Use `user_state_dir` and `repo_state_dir`, and treat the per-project storage path as the derived subpath `<user_state_dir>/projects/<project-slug>/` rather than naming a third root.
+- **Standardize on header plus selective preamble.** Every skill carries one compact config/storage header so the vocabulary and fallback behavior stay consistent. Only independently invocable skills that diagnose config state or read/write durable CE state carry the full config-resolution preamble. Parent skills pass resolved values to spawned agents unless the child is itself independently invocable.
+- **Do not revive legacy review config.** `compound-engineering.local.md` is obsolete cleanup input only. Any surviving YAML config should store only real persisted CE state such as minimal compatibility metadata, not values that the runtime can derive deterministically.
+- **Keep migration state user-action oriented.** The runtime only needs to distinguish four practical states: no new config yet, legacy/conflicting config that needs migration, stale compatibility contract that requires rerunning `/ce-setup`, and current config. Do not split “migration version” and “setup version” unless execution discovers a real user-visible difference in remediation.
+- **Make `/ce-setup` the only writer of migration state.** `/ce-doctor` diagnoses and entry skills warn, but only `/ce-setup` reconciles legacy and new config.
+- **Treat path derivation as runtime contract, not persisted config.** Independently invocable config/storage consumers should derive `user_state_dir`, `repo_state_dir`, and the per-project path directly from the standard preamble. `/ce-setup` should not pre-write the derived per-project path just to make later skills work.
+- **Treat project identity as a shared-storage guarantee.** The per-project path must resolve from shared repo identity, not current checkout identity. Use `git rev-parse --path-format=absolute --git-common-dir` as the primary identity source so linked worktrees map to the same CE project. Derive the directory slug as `<sanitized-repo-name>-<short-hash>`, where the repo name comes from the basename of `${git_common_dir%/.git}` and the hash comes from the full absolute `git_common_dir`. If git identity cannot be resolved, execution may use a deterministic absolute-path fallback, but the worktree-safe path must be the default contract.
+- **Degrade instead of blocking on missing CE state.** Core entry skills should emit a short migration warning and point to `/ce-setup`, but missing CE config or storage should not block the main workflow by default. Full-preamble skills should derive canonical paths when possible and otherwise degrade locally: do not write to legacy or guessed fallback paths, report what could not be persisted, and continue when the main task is still safe to complete.
+- **Preserve todo migration semantics, not per-run artifact history.** Todos retain dual-read compatibility during the drain period; per-run artifact directories only change future writes.
+- **Keep one active planning chain.** Current operational surfaces should adopt the new contract directly, and earlier setup/todo requirements and plan docs should be folded into this plan rather than left as competing active guidance.
+- **Use contract tests for prompt surfaces that now matter operationally.** Existing converter and review contract tests already validate prompt text; add setup/ce-doctor or storage-focused contract coverage rather than relying only on manual inspection.
+
+## Open Questions
+
+### Resolved During Planning
+
+- **Should this plan assume review-agent config still exists?** No. Main has already removed setup-managed reviewer selection, so this refactor must not recreate it.
+- **Should the storage vocabulary keep a named project root variable?** No. Use `user_state_dir` and `repo_state_dir`; refer to `<user_state_dir>/projects/<project-slug>/` directly.
+- **How is the per-project slug derived?** Use the shared git identity from `git rev-parse --path-format=absolute --git-common-dir`, then derive a human-friendly directory-safe slug as `<sanitized-repo-name>-<short-hash>`. This is intentionally stable across linked worktrees of the same repo and intentionally different across separate clones.
+- **Which skills should carry migration warnings?** The concrete warning surfaces are [plugins/compound-engineering/skills/ce-setup/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-setup/SKILL.md), [plugins/compound-engineering/skills/ce-doctor/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-doctor/SKILL.md), [plugins/compound-engineering/skills/ce-brainstorm/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md), [plugins/compound-engineering/skills/ce-plan/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-plan/SKILL.md), [plugins/compound-engineering/skills/ce-work/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-work/SKILL.md), and [plugins/compound-engineering/skills/ce-review/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-review/SKILL.md). Non-core skills should inherit the contract only when they are independently invocable and actually need config or durable storage.
+- **Should every old reference be rewritten?** No. Active docs and tests should adopt the new contract. Historical requirements/plans should be preserved for traceability and only annotated when they could plausibly be mistaken for current runtime guidance.
+- **Is external research needed?** No. The repo already contains the relevant prompt, converter, and lifecycle patterns.
+
+### Deferred to Implementation
+
+- **Compatibility metadata shape:** The plan assumes a minimal compatibility contract, but execution should finalize whether that is a single revision key or a small structured object once the surrounding prompt text is updated.
+- **Shared reference artifact vs. AGENTS-only wording:** The plan assumes `AGENTS.md` is the primary source of truth for the config/storage contract section. Execution can decide whether a separate reference file materially reduces duplication.
+
+## High-Level Technical Design
+
+> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
+
+```text
+user_state_dir/
+  config.yaml                      # optional global defaults / compatibility state if needed
+  projects/
+    <project-slug>/
+      todos/
+      ce-review/<run-id>/
+      deepen-plan/<run-id>/
+      feature-video/<run-id>/
+      ...
+
+<repo>/repo_state_dir/
+  config.yaml                      # optional tracked repo-level CE config (reserved / future)
+  config.local.yaml                # optional machine-local CE config; gitignore this file, not the whole directory
+
+Resolution flow:
+1. Resolve repo_state_dir as `<repo>/.compound-engineering`
+2. Resolve user_state_dir from the documented fallback chain
+3. Derive the per-project path under user_state_dir/projects/<project-slug>/
+4. Read config layers only when they exist and the skill needs persisted CE values
+5. If compatibility or migration state is stale, route the user to /ce-setup
+
+Project slug:
+- identity source: `git rev-parse --path-format=absolute --git-common-dir`
+- readable prefix: sanitized basename of `${git_common_dir%/.git}`
+- stable suffix: short hash of the full absolute `git_common_dir`
+- format: `<sanitized-repo-name>-<short-hash>`
+
+Action model:
+- no repo-local CE file yet -> warn only when relevant, `/ce-doctor` explains current state, `/ce-setup` initializes or refreshes if needed
+- legacy `compound-engineering.local.md` present -> warn in core entry skills, `/ce-doctor` explains that it is obsolete, `/ce-setup` deletes it after explanation
+- new config below required contract -> warn in core entry skills, `/ce-doctor` explains rerun requirement, `/ce-setup` refreshes
+- current config -> proceed with no migration warning
+- canonical storage can be derived but CE state is incomplete -> proceed using canonical paths and warn when relevant
+- canonical storage cannot be derived safely -> do not write to legacy or guessed fallback paths; degrade locally, report what could not be persisted, and direct the user to `/ce-setup`
+```
+
+## Implementation Units
+
+- [ ] **Unit 1: Codify the state contract and authoring rules**
+
+**Goal:** Establish `user_state_dir` / `repo_state_dir` terminology and the standard config/storage contract section as a single prompt-authoring contract before touching individual skills.
+
+**Requirements:** R1-R5, R11-R14, R31-R32
+
+**Dependencies:** None
+
+**Files:**
+- Modify: [AGENTS.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/AGENTS.md)
+- Modify: [plugins/compound-engineering/AGENTS.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/AGENTS.md)
+- Modify: [plugins/compound-engineering/README.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/README.md)
+
+**Approach:**
+- Update the repo and plugin instruction surfaces so skill authors have one stable vocabulary and one two-tier authoring contract to copy:
+  - compact header required in every skill
+  - full config-resolution preamble required only in independently invocable config/storage consumers
+- Clarify that `repo_state_dir` is for repo-local CE config, `user_state_dir` is for user-level CE state, and the per-project path derives from the latter.
+- Define the compact header contents explicitly: state vocabulary, whether the skill resolves config itself or expects caller-passed values, and the rule to warn or route to `/ce-setup` when required config/storage cannot be resolved safely.
+- Define the full preamble trigger explicitly: use it only in independently invocable skills that diagnose migration/config state or that read/write durable CE-owned state.
+- Define the full preamble contents explicitly:
+  - prefer caller-passed resolved values
+  - resolve `repo_state_dir`, `user_state_dir`, and the per-project path deterministically
+  - read config layers only when needed and when present
+  - warn and route to `/ce-setup` when migration or rerun is needed
+  - do not write to legacy or guessed fallback paths when canonical storage cannot be derived
+  - degrade locally and report what could not be persisted instead of blocking the main task by default
+- Keep the guidance capability-first and cross-platform, following current plugin AGENTS conventions.
+
+**Patterns to follow:**
+- [plugins/compound-engineering/AGENTS.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/AGENTS.md)
+- [docs/solutions/skill-design/compound-refresh-skill-improvements.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/docs/solutions/skill-design/compound-refresh-skill-improvements.md)
+
+**Test scenarios:**
+- New skill author can determine where config is read from and where durable project state lives without inferring hidden terminology.
+- A skill author can tell from the contract whether a skill needs only the compact header or the full config-resolution preamble.
+- A spawned helper/delegate skill can rely on caller-passed resolved values rather than re-reading the config layers.
+- The documented config section still makes sense in Claude Code, Codex, Gemini, and copied-skill targets.
+
+**Verification:**
+- Both AGENTS files describe the same contract without conflicting path terminology.
+- The plan no longer leaves “header vs full preamble” as an implementation-time choice.
+- README no longer implies that CE runtime state belongs in repo-local `.context/compound-engineering/...`.
+
+- [ ] **Unit 2: Move `/ce-setup` and `/ce-doctor` to the new config and migration contract**
+
+**Goal:** Make `/ce-setup` own obsolete-file cleanup plus any surviving compatibility migration work, make `/ce-doctor` diagnose compatibility, storage state, and gitignore safety in addition to dependencies, and give core entry skills one consistent migration-warning contract.
+
+**Requirements:** R6-R10, R15-R16, R20, R24-R31
+
+**Dependencies:** Unit 1
+
+**Files:**
+- Modify: [plugins/compound-engineering/skills/ce-setup/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-setup/SKILL.md)
+- Modify: [plugins/compound-engineering/skills/ce-doctor/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-doctor/SKILL.md)
+- Modify: [plugins/compound-engineering/skills/ce-brainstorm/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md)
+- Modify: [plugins/compound-engineering/skills/ce-plan/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-plan/SKILL.md)
+- Modify: [plugins/compound-engineering/skills/ce-work/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-work/SKILL.md)
+- Modify: [plugins/compound-engineering/skills/ce-review/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-review/SKILL.md)
+- Modify: [plugins/compound-engineering/skills/ce-doctor/scripts/check-health](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-doctor/scripts/check-health)
+- Modify: [plugins/compound-engineering/skills/ce-doctor/references/dependency-registry.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-doctor/references/dependency-registry.md)
+- Create: [tests/ce-setup-skill-contract.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/ce-setup-skill-contract.test.ts)
+- Create: [tests/ce-doctor-skill-contract.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/ce-doctor-skill-contract.test.ts)
+- Create: [tests/entry-skill-config-warning-contract.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/entry-skill-config-warning-contract.test.ts)
+
+**Approach:**
+- Replace the current “dependency-only setup” language with a flow that also removes obsolete `compound-engineering.local.md` files after explaining why they are no longer used, and writes machine-local config only if the surviving CE contract truly requires persisted state.
+- Extend the doctor script and wrapper skill to report resolved config layers when present, the derived per-project storage path, whether a legacy file still needs cleanup, and repo-local gitignore safety for `.compound-engineering/config.local.yaml` when that file exists or is expected.
+- Make `/ce-setup` the remediation path for gitignore safety as well as diagnostics: if `.compound-engineering/config.local.yaml` should exist and is not ignored, `/ce-setup` should explain why the file is machine-local and offer to add the `.gitignore` entry.
+- Add a short shared warning contract to the core entry skills so they all route users toward `/ce-setup` from the same states, while full-preamble skills degrade locally rather than blocking or writing to stale paths when canonical CE storage cannot be resolved.
+- Keep dependency detection registry-driven and MCP-aware, but update the output model so dependency gaps and config/storage gaps share one diagnostic report.
+
+**Patterns to follow:**
+- [plugins/compound-engineering/skills/ce-doctor/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-doctor/SKILL.md)
+- [plugins/compound-engineering/skills/ce-doctor/scripts/check-health](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-doctor/scripts/check-health)
+- [tests/review-skill-contract.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/review-skill-contract.test.ts)
+
+**Test scenarios:**
+- Legacy `compound-engineering.local.md` exists; `/ce-doctor` reports obsolete-file cleanup needed and `/ce-setup` becomes the next action.
+- Legacy file and new repo-local CE files both exist; `/ce-doctor` reports that the legacy file is obsolete and `/ce-setup` deletes it without attempting a semantic merge.
+- New config exists but compatibility metadata is stale; `/ce-doctor` asks for rerun without relying on raw plugin semver.
+- `.compound-engineering/config.local.yaml` is required but not gitignored; `/ce-doctor` reports the issue and `/ce-setup` offers to add the `.gitignore` entry.
+- `ce:brainstorm` and `ce:plan` warn and continue because they can still read or write durable docs safely without project-state writes.
+- `ce:work` and `ce:review` share the same warning vocabulary, derive canonical paths when possible, and otherwise report degraded persistence instead of writing to legacy paths.
+- Dependency checks still distinguish CLI-present, MCP-present, and missing states.
+
+**Verification:**
+- `/ce-setup` prompt no longer implies a legacy markdown config target.
+- `/ce-doctor` output contract covers config/storage state in addition to dependency health.
+- `/ce-doctor` checks `.compound-engineering/config.local.yaml` gitignore safety rather than the old repo-local storage paths.
+- `/ce-setup` can remediate `.compound-engineering/config.local.yaml` gitignore safety instead of only surfacing the problem.
+- Core entry skills no longer invent their own migration wording or remediation instructions.
+- Canonical per-project storage is derivable without `/ce-setup` having to pre-write that path into config.
+- New contract tests pin the migration/reporting language so future edits do not regress it.
+
+- [ ] **Unit 3: Move the todo system to per-project durable storage with legacy reads**
+
+**Goal:** Re-home the durable todo lifecycle under `<user_state_dir>/projects/<project-slug>/todos/` while preserving the existing legacy-drain behavior from `todos/` and `.context/compound-engineering/todos/`.
+
+**Requirements:** R17-R23, R31-R32
+
+**Dependencies:** Unit 2
+
+**Files:**
+- Modify: [plugins/compound-engineering/skills/todo-create/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/todo-create/SKILL.md)
+- Modify: [plugins/compound-engineering/skills/todo-triage/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/todo-triage/SKILL.md)
+- Modify: [plugins/compound-engineering/skills/todo-resolve/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/todo-resolve/SKILL.md)
+- Modify: [plugins/compound-engineering/skills/ce-review/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-review/SKILL.md)
+- Modify: [plugins/compound-engineering/skills/test-browser/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/test-browser/SKILL.md)
+- Modify: [plugins/compound-engineering/skills/test-xcode/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/test-xcode/SKILL.md)
+- Create: [tests/todo-storage-contract.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/todo-storage-contract.test.ts)
+
+**Approach:**
+- Update `todo-create` to treat the per-project path under `user_state_dir` as canonical, but keep both legacy directories in the read/ID-generation story until the drain period ends.
+- Keep the status lifecycle unchanged: `pending` and `ready` remain load-bearing, only the storage location changes.
+- Update all todo-producing skills to defer to `todo-create` conventions instead of hardcoding canonical paths inline.
+
+**Patterns to follow:**
+- [docs/solutions/workflow/todo-status-lifecycle.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/docs/solutions/workflow/todo-status-lifecycle.md)
+- [plugins/compound-engineering/skills/todo-create/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/todo-create/SKILL.md)
+
+**Test scenarios:**
+- New todo creation writes to the per-project path under `user_state_dir`.
+- Next-ID generation avoids collisions when IDs exist across both legacy directories and the new canonical path.
+- `todo-triage` and `todo-resolve` still find pending/ready items from both legacy locations.
+- `ce:review`, `test-browser`, and `test-xcode` continue to create actionable todos without embedding stale paths.
+
+**Verification:**
+- Todo contract tests prove canonical-write + legacy-read behavior.
+- No todo-producing skill still claims `.context/compound-engineering/todos/` is the long-term canonical location.
+
+- [ ] **Unit 4: Move per-run artifact skills to derived per-project paths**
+
+**Goal:** Repoint per-run artifact instructions from repo-local `.context/compound-engineering/...` to `<user_state_dir>/projects/<project-slug>/<workflow>/...` without attempting historical migration.
+
+**Requirements:** R17-R23, R31-R32
+
+**Dependencies:** Unit 2
+
+**Files:**
+- Modify: [plugins/compound-engineering/skills/ce-review/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-review/SKILL.md)
+- Modify: [plugins/compound-engineering/skills/deepen-plan/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/deepen-plan/SKILL.md)
+- Modify: [plugins/compound-engineering/skills/feature-video/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/feature-video/SKILL.md)
+- Modify: [tests/review-skill-contract.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/review-skill-contract.test.ts)
+- Create: [tests/storage-skill-contract.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/storage-skill-contract.test.ts)
+
+**Approach:**
+- Update the run-artifact instructions to use the derived per-project path terminology rather than hardcoded `.context/compound-engineering/...`.
+- Keep report-only prohibitions path-agnostic where possible so the policy survives future directory changes.
+- Do not add active migration logic for old artifact directories; simply change future-write instructions.
+
+**Patterns to follow:**
+- [plugins/compound-engineering/skills/ce-review/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-review/SKILL.md)
+- [tests/review-skill-contract.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/review-skill-contract.test.ts)
+
+**Test scenarios:**
+- `ce:review` contract tests still enforce artifact-writing rules, but against the new path vocabulary.
+- `feature-video` and `deepen-plan` examples no longer require repo-local `.context/compound-engineering/...`.
+- Report-only guidance still forbids externalized writes regardless of exact path wording.
+
+**Verification:**
+- The highest-signal per-run artifact skills no longer treat `.context/compound-engineering/...` as their runtime contract.
+- Storage contract tests pin the new path expectations for future edits.
+
+- [ ] **Unit 5: Remove the old contract from converter and compatibility surfaces**
+
+**Goal:** Update converter instructions, fixtures, and contract tests so installed targets no longer assert `compound-engineering.local.md`, `todos/`, or `.context/compound-engineering/...` as the stable CE contract.
+
+**Requirements:** R31-R32
+
+**Dependencies:** Units 1-4
+
+**Files:**
+- Modify: [src/utils/codex-agents.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/src/utils/codex-agents.ts)
+- Modify: [src/converters/claude-to-pi.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/src/converters/claude-to-pi.ts)
+- Modify: [docs/solutions/skill-design/beta-skills-framework.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/docs/solutions/skill-design/beta-skills-framework.md)
+- Modify: [tests/converter.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/converter.test.ts)
+- Modify: [tests/codex-converter.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/codex-converter.test.ts)
+- Modify: [tests/copilot-converter.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/copilot-converter.test.ts)
+- Modify: [tests/pi-converter.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/pi-converter.test.ts)
+
+**Approach:**
+- Replace literal assertions about legacy config/todo paths with assertions about the new state vocabulary or about skill text that remains platform-agnostic after conversion.
+- Update PI/Codex helper text so converted skill guidance does not teach stale todo/config locations.
+- Update active solution docs that still present the old runtime contract as current guidance, while leaving clearly historical plan/requirements docs intact unless they need a brief superseded note.
+- Keep path rewriting logic minimal; if the new wording is sufficiently target-agnostic, prefer updating fixtures/tests over adding new target-specific rewriting behavior.
+
+**Patterns to follow:**
+- [docs/solutions/codex-skill-prompt-entrypoints.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/docs/solutions/codex-skill-prompt-entrypoints.md)
+- Existing converter tests in [tests/converter.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/converter.test.ts)
+
+**Test scenarios:**
+- Converted command/skill bodies no longer assert `compound-engineering.local.md` as the canonical config target.
+- PI conversion no longer describes todo workflows as `todos/ + /skill:todo-create`.
+- Copilot/Codex tests still prove target-specific rewriting where that target genuinely owns a path transformation.
+
+**Verification:**
+- `bun test` passes for converter and skill-contract suites.
+- Active docs that describe current CE runtime behavior no longer teach `compound-engineering.local.md` or repo-local durable storage as the live contract.
+- No test fixture still encodes the old CE runtime contract as expected behavior.
+
+## System-Wide Impact
+
+- **Interaction graph:** `/ce-setup` becomes the only migration writer; `/ce-doctor` and core workflow skills become migration-state readers; todo/review/media/planning skills become consumers of the derived per-project storage path.
+- **Error propagation:** Incorrect compatibility metadata or repo-identity resolution can cause stale-path fallbacks, false “rerun setup” warnings, or storage fragmentation across worktrees.
+- **State lifecycle risks:** Todo ID collisions, stale obsolete-file cleanup behavior, and accidental commits of `.compound-engineering/config.local.yaml` are the main durable-state hazards.
+- **User-experience risks:** If warning wording drifts between entry skills, users will receive contradictory guidance about whether they can proceed or must rerun `/ce-setup`.
+- **API surface parity:** Converter outputs and copied skills must continue to make sense across Claude Code, Codex, Copilot, PI, and other pass-through targets without assuming one platform’s shell/tool naming.
+- **Integration coverage:** Unit tests alone will not prove prompt-contract correctness; contract tests plus the converter suite need to cover the text surfaces that now encode the runtime model.
+
+## Risks & Dependencies
+
+- Legacy `compound-engineering.local.md` cleanup is intentionally destructive; the setup messaging has to be explicit so users understand the file is obsolete and no longer carries supported CE state.
+- The path derivation contract depends on stable project slug resolution across worktrees; if that is underspecified, users can end up with split project state.
+- The entry-skill warning contract spans multiple high-traffic workflows; if the copy is not kept deliberately short, this refactor could add prompt bloat to the plugin's most-used surfaces.
+- Root and plugin AGENTS changes are part of the runtime contract now; if they drift from skill bodies, future skills will regress into mixed terminology and shell-heavy config loading.
+- The converter/test cleanup depends on the final wording chosen for the new state vocabulary. Churn here is likely if execution changes the vocabulary again.
+
+## Documentation / Operational Notes
+
+- Update [plugins/compound-engineering/README.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/README.md) when setup/ce-doctor/storage behavior changes.
+- Run `bun test` because the converter and contract-test surfaces are directly affected.
+- Run `bun run release:validate` because skill descriptions and plugin docs are being updated.
+- Do not hand-edit release-owned versions or changelogs.
+
+## Sources & References
+
+- **Origin document:** [docs/brainstorms/2026-03-25-config-storage-redesign-requirements.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/docs/brainstorms/2026-03-25-config-storage-redesign-requirements.md)
+- Related code: [plugins/compound-engineering/skills/ce-doctor/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-doctor/SKILL.md)
+- Related code: [plugins/compound-engineering/skills/ce-setup/SKILL.md](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/plugins/compound-engineering/skills/ce-setup/SKILL.md)
+- Related tests: [tests/review-skill-contract.test.ts](/Users/tmchow/conductor/workspaces/compound-engineering-plugin/freetown-v1/tests/review-skill-contract.test.ts)

docs/plans/2026-03-26-001-feat-adversarial-review-agents-plan.md

@@ -0,0 +1,330 @@
+---
+title: "feat: Add adversarial review agents for code and documents"
+type: feat
+status: completed
+date: 2026-03-26
+deepened: 2026-03-26
+---
+
+# feat: Add adversarial review agents for code and documents
+
+## Overview
+
+Add two adversarial review agents to the compound-engineering plugin — one for code review and one for document review. These agents take a fundamentally different stance from existing reviewers: instead of evaluating quality against known criteria, they actively try to *falsify* the artifact by constructing scenarios that break it, challenging assumptions, and probing for problems that pattern-matching reviewers miss.
+
+Both agents integrate into the existing review ensembles as conditional reviewers, activated by skill-level filtering. Both auto-scale their depth internally based on artifact size and risk signals. Both produce findings using the standard JSON contract so they merge cleanly into existing synthesis pipelines.
+
+## Problem Frame
+
+The existing review infrastructure is comprehensive — 24 code review agents and 6 document review agents covering correctness, security, reliability, maintainability, performance, scope, feasibility, and coherence. But all reviewers share an *evaluative* stance: they check artifacts against known quality criteria.
+
+What's missing is a *falsification* stance — actively constructing scenarios that break the artifact, challenging the assumptions behind decisions, and probing for emergent failures that no single-pattern reviewer would catch. This is the gap that gstack's adversarial evaluation fills (cross-model challenge mode, spec review loops, proxy skepticism, shadow path tracing) and that compound-engineering currently lacks.
+
+## Requirements Trace
+
+- R1. Code adversarial-reviewer agent that tries to break implementations by constructing failure scenarios
+- R2. Document adversarial-reviewer agent that challenges premises, assumptions, and decisions in plans/requirements
+- R3. Both agents use the standard JSON findings contract for their respective pipelines
+- R4. Skill-level filtering: orchestrating skills decide whether to dispatch adversarial review
+- R5. Agent-level auto-scaling: agents modulate their own depth (quick/standard/deep) based on artifact size and risk
+- R6. Direct invocation: agents work when called directly, not only through skill pipelines
+- R7. Clear boundaries: each agent has explicit "do not flag" rules to prevent overlap with existing reviewers
+
+## Scope Boundaries
+
+- No cross-model adversarial review (no Codex/external model integration) — that's a separate feature
+- No changes to findings schemas — both agents use existing schemas as-is
+- No new skills — agents integrate into existing `ce-review` and `document-review` skills
+- No changes to synthesis/dedup pipelines — agents produce standard output that existing pipelines handle
+- No beta framework — these are additive conditional reviewers with no risk to existing behavior
+
+## Context & Research
+
+### Relevant Code and Patterns
+
+- `plugins/compound-engineering/agents/review/ce-*.agent.md` — 24 existing code review agents following consistent structure (identity, hunting list, confidence calibration, suppress conditions, output format)
+- `plugins/compound-engineering/agents/document-review/ce-*.agent.md` — 6 existing document review agents (identity, analysis focus, confidence calibration, suppress conditions)
+- `plugins/compound-engineering/skills/ce-review/SKILL.md` — code review orchestration with tiered persona ensemble
+- `plugins/compound-engineering/skills/ce-review/references/persona-catalog.md` — reviewer registry with always-on, cross-cutting conditional, and stack-specific conditional tiers
+- `plugins/compound-engineering/skills/document-review/SKILL.md` — document review orchestration with 2 always-on + 4 conditional personas
+- `plugins/compound-engineering/skills/ce-review/references/findings-schema.json` — code review findings contract
+- `plugins/compound-engineering/skills/document-review/references/findings-schema.json` — document review findings contract
+
+### Institutional Learnings
+
+- Reviewer selection is agent judgment, not keyword matching — the orchestrator reads the diff and reasons about which conditionals to activate
+- Per-persona confidence calibration and explicit suppress conditions are the primary noise-control mechanism
+- Intent shapes review depth (how hard each reviewer looks), not reviewer selection
+- Conservative routing on disagreement: merged findings narrow but never widen without evidence
+- Subagent template pattern wraps persona + schema + context for consistent dispatch
+
+### External References
+
+- gstack adversarial patterns analyzed: `/codex` challenge mode (chaos engineer prompting), `/plan-ceo-review` (proxy skepticism, independent spec review loop), `/plan-design-review` (auto-scaling by diff size), `/plan-eng-review` (error & rescue map, shadow path tracing), `/cso` (20 hard exclusion rules + 22 precedents)
+
+## Key Technical Decisions
+
+- **Two agents, not one**: Document and code adversarial review require fundamentally different reasoning techniques (strategic skepticism vs. chaos engineering). A single agent would need such a sprawling prompt that it loses sharpness at both.
+- **Conditional tier, not always-on**: Adversarial review is expensive. Small config changes and trivial fixes don't need it. Skill-level filtering gates dispatch; agent-level auto-scaling gates depth.
+- **Same short persona name in both pipelines**: Both agents use `"reviewer": "adversarial"` in their JSON output. This is safe because the two pipelines (ce-review and document-review) never merge findings across each other.
+- **Depth determined by artifact size + risk signals**: The agent reads the artifact and determines quick/standard/deep. Callers can override depth via the intent summary (e.g., "this is a critical auth change, review deeply").
+- **Agent-internal auto-scaling, not template-driven**: No existing review agent auto-scales depth — this is a novel pattern in the plugin. The subagent templates pass the full raw diff/document but no sizing metadata (no line count, word count, or risk classification). Rather than extending the shared templates with new variables (which would affect all reviewers), each adversarial agent estimates size from the raw content it already receives. The code agent counts diff hunk lines; the document agent estimates word/requirement count from the text. This keeps the change additive — no template modifications, no orchestrator changes.
+- **Auto-scaling thresholds grounded in gstack precedent**: The 50-line code threshold matches gstack's `plan-design-review` small-diff cutoff where adversarial review is skipped entirely. The 200-line threshold matches where gstack escalates to full multi-pass adversarial. Document thresholds (1000/3000 words) are set proportionally — a 1000-word doc is roughly a lightweight plan, a 3000-word doc is a Standard/Deep plan. These are starting values to tune based on usage.
+- **No overlap with existing reviewers by design**: Each agent's "What you don't flag" section explicitly defers to existing specialists. The adversarial agent finds problems that emerge from the *combination* or *assumptions* of the system, not problems in individual patterns.
+
+## Open Questions
+
+### Resolved During Planning
+
+- **Should the agents share a name?** Yes — both are `adversarial-reviewer` in their respective directories. The fully-qualified names (`compound-engineering:review:adversarial-reviewer` and `compound-engineering:document-review:adversarial-reviewer`) are distinct. The persona catalog uses FQ names.
+- **What model should they use?** `model: inherit` for both, matching all other review agents. Adversarial review benefits from the strongest available model.
+- **What confidence thresholds?** Code adversarial: 0.60 floor (matching ce-review pipeline). Document adversarial: 0.50 floor (matching document-review pipeline). High confidence (0.80+) requires a concrete constructed scenario with traceable evidence.
+
+### Deferred to Implementation
+
+- Exact wording of system prompt scenarios and examples — these will be refined during agent authoring based on what reads clearly
+- Whether the depth auto-scaling thresholds (50/200 lines for code, 1000/3000 words for docs) need tuning — start with these and adjust based on usage
+
+---
+
+## Implementation Units
+
+- [x] **Unit 1: Create code adversarial-reviewer agent**
+
+  **Goal:** Define the adversarial reviewer for code diffs that tries to break implementations by constructing failure scenarios
+
+  **Requirements:** R1, R3, R5, R6, R7
+
+  **Dependencies:** None
+
+  **Files:**
+  - Create: `plugins/compound-engineering/agents/review/ce-adversarial-reviewer.agent.md`
+
+  **Approach:**
+  Follow the standard code review agent structure (identity, hunting list, confidence calibration, suppress conditions, output format). The key differentiation is in the *hunting list* — these are not patterns to match but *scenario construction techniques*:
+
+  1. **Assumption violation** — identify assumptions the code makes about its environment (API always returns JSON, config always set, queue never empty, input always within range) and construct scenarios where those assumptions break. Different from correctness-reviewer which checks logic *given* assumptions.
+  2. **Composition failures** — trace interactions across component boundaries where each component is correct in isolation but the combination fails (ordering assumptions, shared state mutations, contract mismatches between caller and callee). Different from correctness-reviewer which examines individual code paths.
+  3. **Cascade construction** — build multi-step failure chains: "A times out, causing B to retry, overwhelming C." Different from reliability-reviewer which checks individual failure handling.
+  4. **Abuse cases** — find legitimate-seeming usage patterns that cause bad outcomes: "user submits this 1000 times," "request arrives during deployment," "two users edit the same resource simultaneously." Not security exploits (security-reviewer) and not performance anti-patterns (performance-reviewer) — emergent misbehavior.
+
+  Auto-scaling logic in the system prompt. The agent receives the full raw diff via the subagent template's `{diff}` variable and the intent summary via `{intent_summary}`. No sizing metadata is pre-computed — the agent estimates diff size from the content it receives and extracts risk signals from the free-text intent summary (e.g., "Simplify tax calculation" = low risk; "Add OAuth2 flow for payment provider" = high risk).
+
+  - **Quick** (<50 changed lines): assumption violation scan only — identify 2-3 assumptions the code makes and whether they could be violated
+  - **Standard** (50-199 lines): + scenario construction + abuse cases
+  - **Deep** (200+ lines OR risk signals like auth/payments/data mutations): + composition failures + cascade construction + multi-pass
+
+  Suppress conditions (what NOT to flag):
+  - Individual logic bugs without cross-component impact (correctness-reviewer)
+  - Known vulnerability patterns like SQL injection, XSS (security-reviewer)
+  - Individual missing error handling (reliability-reviewer)
+  - Performance anti-patterns like N+1 queries (performance-reviewer)
+  - Code style, naming, structure issues (maintainability-reviewer)
+  - Test coverage gaps (testing-reviewer)
+  - API contract changes (api-contract-reviewer)
+
+  **Patterns to follow:**
+  - `plugins/compound-engineering/agents/review/ce-correctness-reviewer.agent.md` — closest structural analog
+  - `plugins/compound-engineering/agents/review/ce-reliability-reviewer.agent.md` — for cascade/failure-chain framing
+
+  **Test scenarios:**
+  - Agent file parses with valid YAML frontmatter (name, description, model, tools, color fields present)
+  - System prompt contains all 4 hunting techniques with concrete descriptions
+  - Confidence calibration has 3 tiers matching ce-review thresholds (0.80+, 0.60-0.79, below 0.60)
+  - Suppress conditions explicitly name every existing reviewer whose territory is deferred
+  - Output format section matches standard JSON skeleton with `"reviewer": "adversarial"`
+  - Auto-scaling thresholds are documented in the system prompt
+
+  **Verification:**
+  - `bun run release:validate` passes
+  - Agent file follows the exact section ordering of existing review agents
+
+---
+
+- [x] **Unit 2: Create document adversarial-reviewer agent**
+
+  **Goal:** Define the adversarial reviewer for planning/requirements documents that challenges premises, assumptions, and decisions
+
+  **Requirements:** R2, R3, R5, R6, R7
+
+  **Dependencies:** None
+
+  **Files:**
+  - Create: `plugins/compound-engineering/agents/document-review/ce-adversarial-document-reviewer.agent.md`
+
+  **Approach:**
+  Follow the standard document review agent structure (identity, analysis focus, confidence calibration, suppress conditions). The analysis techniques:
+
+  1. **Premise challenging** — question whether the stated problem is the real problem. "The document says X is the goal — but the requirements described actually solve Y. Which is it?" Different from coherence-reviewer which checks internal consistency without questioning whether the goals themselves are right.
+  2. **Assumption surfacing** — force unstated assumptions into the open. "This plan assumes Z will always be true. Where is that stated? What happens if it's not?" Different from feasibility-reviewer which checks whether the approach works given its assumptions.
+  3. **Decision stress-testing** — for each major technical or scope decision: "What would make this the wrong choice? What evidence would falsify this decision?" Different from scope-guardian which checks alignment between stated scope and stated goals, not whether the goals themselves are well-chosen.
+  4. **Simplification pressure** — "What's the simplest version that would validate this? Does this abstraction earn its keep? What could be removed without losing the core value?" Different from scope-guardian which checks for scope creep, not for over-engineering within scope.
+  5. **Alternative blindness** — "What approaches were not considered? Why was this path chosen over the obvious alternatives?" Different from feasibility-reviewer which evaluates the proposed approach, not what was left on the table.
+
+  Auto-scaling logic. The agent receives the full document text via the subagent template's `{document_content}` variable and the document type ("requirements" or "plan") via `{document_type}`. No word count or requirement count is pre-computed — the agent estimates from the content. Risk signals come from the document content itself (domain keywords, abstraction proposals, scope size).
+
+  - **Quick** (small doc, <1000 words or <5 requirements): premise check + simplification pressure only
+  - **Standard** (medium doc): + assumption surfacing + decision stress-testing
+  - **Deep** (large doc, >3000 words or >10 requirements, or high-stakes domain like auth/payments/migrations): + alternative blindness + multi-pass
+
+  Suppress conditions:
+  - Internal contradictions or terminology drift (coherence-reviewer)
+  - Technical feasibility or architecture conflicts (feasibility-reviewer)
+  - Scope-goal alignment or priority dependency issues (scope-guardian-reviewer)
+  - UI/UX quality or user flow completeness (design-lens-reviewer)
+  - Security implications at plan level (security-lens-reviewer)
+  - Product framing or business justification (product-lens-reviewer)
+
+  **Patterns to follow:**
+  - `plugins/compound-engineering/agents/document-review/ce-scope-guardian-reviewer.agent.md` — closest structural analog (also challenges scope decisions)
+  - `plugins/compound-engineering/agents/document-review/ce-feasibility-reviewer.agent.md` — for assumption-adjacent framing
+
+  **Test scenarios:**
+  - Agent file parses with valid YAML frontmatter (name, description, model fields present)
+  - System prompt contains all 5 analysis techniques with concrete descriptions
+  - Confidence calibration has 3 tiers matching document-review thresholds (0.80+, 0.60-0.79, below 0.50)
+  - Suppress conditions explicitly name every existing document reviewer whose territory is deferred
+  - Auto-scaling thresholds are documented in the system prompt
+  - No output format section (document review agents get output contract from subagent template)
+
+  **Verification:**
+  - `bun run release:validate` passes
+  - Agent file follows the structural conventions of existing document review agents
+
+---
+
+- [x] **Unit 3: Integrate code adversarial-reviewer into ce-review skill**
+
+  **Goal:** Register the adversarial-reviewer as a cross-cutting conditional in the ce-review persona catalog and add selection logic to the skill
+
+  **Requirements:** R4, R5
+
+  **Dependencies:** Unit 1
+
+  **Files:**
+  - Modify: `plugins/compound-engineering/skills/ce-review/references/persona-catalog.md`
+  - Modify: `plugins/compound-engineering/skills/ce-review/SKILL.md`
+
+  **Approach:**
+
+  *Persona catalog:*
+  Add `adversarial` to the cross-cutting conditional tier table:
+  ```
+  | `adversarial` | `compound-engineering:review:adversarial-reviewer` | Select when diff is >=50 changed lines, OR touches auth, payments, data mutations, external API integrations, or other high-risk domains |
+  ```
+
+  *Skill selection logic (Stage 3):*
+  Add adversarial-reviewer to the conditional selection with these activation rules:
+  - Diff size >= 50 changed lines (excluding test files, generated files, lockfiles)
+  - OR diff touches high-risk domains: authentication/authorization, payment processing, data mutations/migrations, external API integrations, cryptography
+  - The intent summary is passed to the agent to inform auto-scaling depth (the agent decides quick/standard/deep, not the skill)
+
+  *Announcement format:*
+  ```
+  - adversarial -- 147 changed lines across auth controller and payment service
+  ```
+
+  **Patterns to follow:**
+  - How `security` is listed in the persona catalog cross-cutting conditional table
+  - How `reliability` selection logic is described in Stage 3
+
+  **Test scenarios:**
+  - Persona catalog has adversarial in the cross-cutting conditional table with correct FQ agent name
+  - Selection logic references both size threshold and risk domain triggers
+  - Announcement format matches existing conditional reviewer pattern (`name -- justification`)
+
+  **Verification:**
+  - `bun run release:validate` passes
+  - Persona catalog table renders correctly in markdown preview
+
+---
+
+- [x] **Unit 4: Integrate document adversarial-reviewer into document-review skill**
+
+  **Goal:** Register the adversarial-reviewer as a conditional reviewer in the document-review skill with activation signals
+
+  **Requirements:** R4, R5
+
+  **Dependencies:** Unit 2
+
+  **Files:**
+  - Modify: `plugins/compound-engineering/skills/document-review/SKILL.md`
+
+  **Approach:**
+
+  Add adversarial-reviewer to the conditional persona selection (Phase 1) with these activation signals:
+  - Document contains >5 distinct requirements or implementation units
+  - Document makes explicit architectural or scope decisions with stated rationale
+  - Document covers high-stakes domains (auth, payments, data migrations, external integrations)
+  - Document proposes new abstractions, frameworks, or significant architectural patterns
+
+  Announcement format:
+  ```
+  - adversarial-reviewer -- plan proposes new abstraction layer with 8 requirements across auth and payments
+  ```
+
+  **Patterns to follow:**
+  - How `scope-guardian-reviewer` activation signals are listed (bulleted under "activate when the document contains:")
+  - How `security-lens-reviewer` activation signals reference domain keywords
+
+  **Test scenarios:**
+  - Activation signals listed in the same format as existing conditional reviewers
+  - Announcement format matches existing pattern
+  - Maximum reviewer count updated if the skill documents a cap (currently 6 max — now 7 possible)
+
+  **Verification:**
+  - `bun run release:validate` passes
+
+---
+
+- [x] **Unit 5: Update plugin metadata and documentation**
+
+  **Goal:** Update agent counts and document the new adversarial reviewers in plugin README
+
+  **Requirements:** None (housekeeping)
+
+  **Dependencies:** Units 1-4
+
+  **Files:**
+  - Modify: `plugins/compound-engineering/README.md` (agent count, reviewer table if one exists)
+  - Modify: `.claude-plugin/marketplace.json` (if it tracks agent counts)
+  - Modify: `plugins/compound-engineering/.claude-plugin/plugin.json` (if it tracks agent counts)
+
+  **Approach:**
+  - Update any agent count references (24 code review agents -> 25, 6 document review agents -> 7)
+  - Add adversarial reviewers to any agent listing tables
+  - Keep descriptions consistent with the agent frontmatter descriptions
+
+  **Patterns to follow:**
+  - Existing README format for listing agents
+  - How previous agent additions updated metadata
+
+  **Test scenarios:**
+  - `bun run release:validate` passes (this validates agent counts match between plugin.json and actual files)
+  - README accurately reflects the new agent count
+
+  **Verification:**
+  - `bun run release:validate` passes with no warnings
+
+## System-Wide Impact
+
+- **Interaction graph:** The adversarial agents are read-only reviewers dispatched via subagent template. They do not modify code or documents. Their findings enter the existing synthesis pipeline (confidence gating, dedup, routing) unchanged.
+- **Error propagation:** If an adversarial agent fails or returns invalid JSON, the existing synthesis pipeline handles it the same way it handles any reviewer failure — the review continues with other reviewers' findings.
+- **Token cost:** Adversarial review adds one additional subagent per pipeline when activated. The auto-scaling mechanism (quick/standard/deep) bounds token usage proportionally to artifact size. At quick depth, the agent produces minimal findings; at deep depth, it may produce the most detailed findings in the ensemble.
+- **Dedup behavior with adversarial findings:** The ce-review dedup fingerprint is `normalize(file) + line_bucket(line, ±3) + normalize(title)`. Adversarial findings and pattern-based findings at the same code location will typically have different titles (e.g., "API assumes JSON response format" vs. "Missing null check on API response"), so `normalize(title)` prevents false merging. This was confirmed by analyzing existing overlap zones (correctness vs. reliability at the same `rescue` block, correctness vs. security at parameter parsing lines) — the title component is sufficient to discriminate genuinely different problems. The document-review pipeline uses `normalize(section) + normalize(title)` with even lower collision risk due to coarser granularity. The adversarial agents should use distinctive, scenario-oriented titles (e.g., "Cascade: payment timeout triggers unbounded retry loop") that naturally diverge from pattern-based reviewer titles.
+- **Intent summary interaction:** The code adversarial agent receives the intent summary as free-text 2-3 lines (e.g., "Add OAuth2 flow for payment provider. Must not regress existing session management."). The agent uses this to detect risk signals for auto-scaling — domain keywords like "auth", "payment", "migration" trigger deeper review. The intent is not structured data, so the agent must parse it heuristically. This matches how all other reviewers receive intent today.
+- **Ensemble dynamics:** Adding a conditional reviewer does not change the behavior of existing reviewers. Suppress conditions in each adversarial agent minimize overlap upstream; the dedup fingerprint handles residual incidental overlap at synthesis time.
+
+## Risks & Dependencies
+
+- **Risk: Noise generation** — Adversarial review by nature produces findings that may feel subjective or speculative. Mitigation: strict confidence calibration (0.80+ for high-confidence adversarial findings requires a concrete constructed scenario with traceable evidence), explicit suppress conditions, and the existing 0.60/0.50 confidence gates in synthesis.
+- **Risk: Reviewer overlap despite suppress conditions** — Some adversarial findings may target the same code location as correctness or reliability findings. Mitigation: the dedup fingerprint's `normalize(title)` component discriminates genuinely different problems (confirmed by analyzing existing reviewer overlap zones). The adversarial agents should use scenario-oriented titles that naturally diverge from pattern-based titles.
+- **Risk: Auto-scaling is prompt-controlled, not programmatic** — If the agent ignores depth guidance and goes deep on a small diff, there is no programmatic guard. This is inherent to all agent behavior in the plugin (no existing agent has programmatic depth controls either). Mitigation: the confidence calibration and suppress conditions bound finding volume regardless of depth; a noisy quick-mode review still gets gated at 0.60 confidence during synthesis.
+- **Dependency: Existing synthesis pipeline handles new persona** — The `"reviewer": "adversarial"` persona name is new but follows the same JSON contract. No pipeline changes needed.
+
+## Sources & References
+
+- Competitive analysis: gstack plugin at `~/Code/gstack/` — adversarial patterns in `/codex`, `/plan-ceo-review`, `/plan-design-review`, `/plan-eng-review`, `/cso` skills
+- Existing agent conventions: `plugins/compound-engineering/agents/review/ce-correctness-reviewer.agent.md`, `plugins/compound-engineering/agents/document-review/ce-scope-guardian-reviewer.agent.md`
+- Persona catalog: `plugins/compound-engineering/skills/ce-review/references/persona-catalog.md`
+- Findings schemas: `plugins/compound-engineering/skills/ce-review/references/findings-schema.json`, `plugins/compound-engineering/skills/document-review/references/findings-schema.json`

docs/plans/2026-03-26-001-refactor-merge-deepen-into-plan.md

@@ -0,0 +1,324 @@
+---
+title: "refactor: Merge deepen-plan into ce:plan as automatic confidence check"
+type: refactor
+status: completed
+date: 2026-03-26
+origin: docs/brainstorms/2026-03-26-merge-deepen-into-plan-requirements.md
+---
+
+# Merge deepen-plan into ce:plan as automatic confidence check
+
+## Overview
+
+Absorb the deepen-plan skill's confidence-gap evaluation and targeted research agent dispatching into ce:plan as an automatic post-write phase. Remove deepen-plan as a standalone skill. The user no longer decides whether to deepen — the agent evaluates and reports what it's strengthening.
+
+## Problem Frame
+
+The ce:plan and deepen-plan skills form a sequential workflow where the user is offered a choice ("want to deepen?") that they can't evaluate better than the agent can. When deepen-plan runs, it already self-gates (skips Lightweight, scores confidence gaps before acting). The user decision adds friction without adding value. (see origin: docs/brainstorms/2026-03-26-merge-deepen-into-plan-requirements.md)
+
+## Requirements Trace
+
+- R1. ce:plan automatically evaluates and deepens its own output after the initial plan is written, without asking the user for approval
+- R2. When deepening runs, ce:plan reports what sections it's strengthening and why (transparency without requiring a decision)
+- R3. Deepening is skipped for Lightweight plans unless high-risk topics are detected
+- R4. For Standard and Deep plans, ce:plan scores confidence gaps using checklist-first, risk-weighted scoring; if no gaps exceed threshold, reports "confidence check passed" and moves on
+- R5. When gaps are found, ce:plan dispatches targeted research agents to strengthen only the weak sections
+- R6. deepen-plan is removed as standalone command; re-deepening is handled through ce:plan resume mode with the same confidence-gap evaluation (doesn't force deepening unless user explicitly requests it)
+- R7. The "Run deepen-plan" post-generation option is removed; post-generation options become simpler
+
+## Scope Boundaries
+
+- This does not change what deepening does — only where it lives and who decides to run it
+- Deepen-plan's separate-file `-deepened` option is dropped — ce:plan always writes in-place, and automatic deepening has no reason to create a separate file
+- The confidence scoring checklist, agent mapping table, and synthesis rules are transplanted from deepen-plan, not rewritten
+- No changes to ce:brainstorm or ce:work
+- The planning boundary (no code, no commands) is preserved
+- Historical docs referencing deepen-plan are not updated — they are historical records
+
+## Context & Research
+
+### Relevant Code and Patterns
+
+- `plugins/compound-engineering/skills/ce-plan/SKILL.md` — 6 phases (0-5). Phase 5 has sub-phases: 5.1 (Review), 5.2 (Write), 5.3 (Post-gen options). The new confidence check inserts between 5.2 and 5.3
+- `plugins/compound-engineering/skills/deepen-plan/SKILL.md` — 409 lines, 7 phases (0-6). Phases 0-5 contain the logic to absorb; Phase 6 and Post-Enhancement Options are replaced by ce:plan's own post-gen flow
+- `plugins/compound-engineering/skills/lfg/SKILL.md` — Step 3 conditionally invokes deepen-plan. Must be removed
+- `plugins/compound-engineering/skills/slfg/SKILL.md` — Step 3 conditionally invokes deepen-plan. Must be removed
+- Skills are auto-discovered from filesystem (no registry in plugin.json). Deleting the directory removes the skill
+- The `deepened: YYYY-MM-DD` frontmatter field in plan templates signals that a plan was substantively strengthened
+
+### Institutional Learnings
+
+- `docs/solutions/skill-design/beta-skills-framework.md` — The workflow chain is `ce:brainstorm` -> `ce:plan` -> `deepen-plan` -> `ce:work`, orchestrated by lfg and slfg. When removing a skill, all callers must be updated atomically in one PR
+- `docs/solutions/skill-design/beta-promotion-orchestration-contract.md` — Treat the merge as an orchestration contract change. Update every workflow that invokes deepen-plan in the same PR to avoid a broken intermediate state
+- `docs/solutions/plugin-versioning-requirements.md` — Do not manually bump versions. Update README counts and tables. Run `bun run release:validate`
+
+## Key Technical Decisions
+
+- **New Phase 5.3 (Confidence Check and Deepening):** Insert between current 5.2 (Write Plan File) and current 5.3 (Post-Generation Options, renumbered to 5.4). This is the minimal structural change — only one sub-phase renumbers. Rationale: deepening operates on the written plan, so it must follow 5.2, and the user should see post-gen options only after deepening completes or is skipped
+- **Resume mode fast path for re-deepening:** When ce:plan detects an existing complete plan and the user's request is specifically about deepening, it short-circuits to Phase 5.3 directly (skipping Phases 1-4). Rationale: re-running the full planning workflow to re-deepen would be 3-5x more expensive than the old standalone deepen-plan. The fast path preserves efficiency
+- **Pipeline mode behavior:** Deepening runs in pipeline/disable-model-invocation mode using the same gate logic (Standard/Deep AND high-risk or confidence gaps). Rationale: lfg/slfg step 3 already had equivalent conditional logic; this preserves the same behavior internally
+- **Remove ultrathink auto-deepen clause:** Line 625 of ce:plan currently auto-runs deepen-plan on ultrathink. This becomes redundant since every plan run now auto-evaluates deepening. Removing it prevents double-deepening
+- **Scratch space:** Artifact-backed research uses `.context/compound-engineering/ce-plan/deepen/` with per-run subdirectory. Rationale: follows AGENTS.md namespace convention for ce-plan
+
+## Open Questions
+
+### Resolved During Planning
+
+- **Where does the confidence check phase land?** As Phase 5.3, between Write (5.2) and Post-gen Options (renumbered 5.4). Minimal structural change
+- **How does resume mode distinguish incomplete plan from re-deepen request?** Fast path: if the plan appears complete (all sections present, units defined, status: active) and the user's request is specifically about deepening, skip to Phase 5.3. Otherwise resume normal editing
+- **Does deepening run in pipeline mode?** Yes, with the same gate logic. Pipeline mode already skips interactive questions; deepening doesn't ask questions, only reports
+- **What replaces deepen-plan in post-gen options?** Nothing — the list shrinks by one. If auto-evaluation passed, the plan is adequately grounded. Users who disagree can re-invoke ce:plan with explicit deepening instructions
+- **What about failed or empty agent results during deepening?** Preserve deepen-plan's Phase 4.2 fallback: "if an artifact is missing or clearly malformed, re-run that agent or fall back to direct-mode reasoning"
+
+### Deferred to Implementation
+
+- Exact wording of the transparency status message (R2) — best determined when writing the actual Phase 5.3 content
+- Whether the deepen-plan Introduction section's distinction between `document-review` and `deepen-plan` should be preserved somewhere in ce:plan — likely as a brief note in Phase 5.3
+
+## Implementation Units
+
+- [ ] **Unit 1: Modify ce:plan SKILL.md — add Phase 5.3, update Phase 0.1, update post-gen options, update template**
+
+  **Goal:** Absorb deepen-plan's confidence-gap evaluation and targeted research into ce:plan as the new Phase 5.3. Update Phase 0.1 for re-deepen fast path. Renumber current Phase 5.3 to 5.4 and simplify it. Update plan template frontmatter comment.
+
+  **Requirements:** R1, R2, R3, R4, R5, R6, R7
+
+  **Dependencies:** None
+
+  **Files:**
+  - Modify: `plugins/compound-engineering/skills/ce-plan/SKILL.md`
+
+  **Approach:**
+
+  *Phase 5.3 (Confidence Check and Deepening):*
+  - Insert new sub-phase between current 5.2 and 5.3
+  - Transplant from deepen-plan (not rewrite):
+    - Phase 0.2-0.3 gating logic (Lightweight skip, risk profile assessment) → becomes the gate at the top of 5.3
+    - Phase 1 plan structure parsing → becomes a step within 5.3 (lighter version since ce:plan already knows its own structure)
+    - Phase 2 confidence scoring (the full checklist from deepen-plan lines 119-200) → transplanted wholesale
+    - Phase 3 deterministic section-to-agent mapping (lines 208-248) → transplanted wholesale
+    - Phase 3.2 agent prompt shape → transplanted
+    - Phase 3.3 execution mode decision (direct vs artifact-backed) → transplanted
+    - Phase 4 research execution (direct and artifact-backed modes) → transplanted
+    - Phase 5 synthesis and rewrite rules → transplanted
+    - Phase 6 final checks → merged into ce:plan's existing Phase 5.1 review logic
+  - Add transparency reporting (R2): before dispatching agents, report what sections are being strengthened and why. Example: "Strengthening [Key Technical Decisions, System-Wide Impact] — decision rationale is thin and cross-boundary effects aren't mapped"
+  - Add "confidence check passed" path (R4): when no gaps exceed threshold, report and proceed to 5.4
+  - Add pipeline mode note: deepening runs in pipeline mode using the same gate logic, no user interaction needed
+  - Update scratch space path to `.context/compound-engineering/ce-plan/deepen/`
+  - Transplant scratch cleanup logic from deepen-plan Phase 6 (lines 383-385): after the plan is safely written, clean up the temporary scratch directory. This is especially important since auto-deepening means users may never be aware artifacts were created
+
+  *Phase 0.1 (Resume mode fast path):*
+  - Add: when ce:plan detects an existing complete plan and the user's request is specifically about deepening or strengthening, short-circuit to Phase 5.3 directly
+  - "Complete plan" detection: all major sections present, implementation units defined, `status: active`
+  - Deepen-request detection: user's input contains signal words like "deepen", "strengthen", "confidence", "gaps", or explicitly says to re-deepen the plan. Normal editing requests (e.g., "update the test scenarios") should NOT trigger the fast path
+  - Preserve existing resume behavior for incomplete plans
+  - If plan already has `deepened: YYYY-MM-DD` and no explicit user request to re-deepen, apply the same confidence-gap evaluation (R6 — doesn't force deepening)
+
+  *Phase 5.4 (Post-Generation Options, was 5.3):*
+  - Remove option 2 ("Run `/deepen-plan`") and its handler
+  - Remove the ultrathink auto-deepen clause (line 625)
+  - Renumber remaining options (1-6 instead of 1-7)
+
+  *Plan template frontmatter:*
+  - Change comment on `deepened:` line from "set later by deepen-plan" to "set when confidence check substantively strengthens the plan"
+
+  **Patterns to follow:**
+  - deepen-plan SKILL.md is the source of truth for all transplanted content
+  - ce:plan's existing sub-phase structure (numbered sub-phases within Phase 5)
+  - ce:plan's existing pipeline mode handling (line 589)
+
+  **Test scenarios:**
+  - Fresh Lightweight plan → Phase 5.3 gates and skips deepening, reports "confidence check passed"
+  - Fresh Standard plan with thin decisions → Phase 5.3 identifies gaps, reports what it's strengthening, dispatches agents, updates plan
+  - Fresh Standard plan with strong confidence → Phase 5.3 evaluates and reports "confidence check passed"
+  - Pipeline mode (lfg/slfg) → deepening runs automatically with same gate logic, no interactive questions
+  - Resume mode with explicit deepen request → fast-paths to Phase 5.3
+  - Resume mode without deepen request → normal plan editing flow
+
+  **Verification:**
+  - Phase 5.3 contains the complete confidence scoring checklist from deepen-plan
+  - Phase 5.3 contains the complete section-to-agent mapping from deepen-plan
+  - Phase 0.1 has the re-deepen fast path
+  - No references to `/deepen-plan` remain in ce:plan SKILL.md
+  - The ultrathink clause is gone
+  - Plan template frontmatter comment is updated
+
+---
+
+- [ ] **Unit 2: Delete deepen-plan skill directory**
+
+  **Goal:** Remove the deepen-plan skill from the plugin
+
+  **Requirements:** R6
+
+  **Dependencies:** Unit 1 (ce:plan must absorb the logic before it's deleted)
+
+  **Files:**
+  - Delete: `plugins/compound-engineering/skills/deepen-plan/SKILL.md` (entire `deepen-plan/` directory)
+
+  **Approach:**
+  - Delete the directory `plugins/compound-engineering/skills/deepen-plan/`
+  - Skills are auto-discovered from filesystem, so no registry update needed
+
+  **Verification:**
+  - `plugins/compound-engineering/skills/deepen-plan/` no longer exists
+  - No `deepen-plan` skill appears when listing skills
+
+---
+
+- [ ] **Unit 3: Update lfg and slfg orchestrators**
+
+  **Goal:** Remove deepen-plan step from both orchestration skills since ce:plan now handles it internally
+
+  **Requirements:** R1, R6
+
+  **Dependencies:** Unit 1
+
+  **Files:**
+  - Modify: `plugins/compound-engineering/skills/lfg/SKILL.md`
+  - Modify: `plugins/compound-engineering/skills/slfg/SKILL.md`
+
+  **Approach:**
+
+  *lfg:*
+  - Remove step 3 (lines 16-20: conditional deepen-plan invocation and its GATE)
+  - Renumber steps 4-9 to 3-8
+  - Update the opening instruction to remove reference to step 3 plan verification
+  - Keep step 2 (`/ce:plan`) and its GATE unchanged — ce:plan now handles deepening internally
+
+  *slfg:*
+  - Remove step 3 (lines 14-17: conditional deepen-plan invocation)
+  - Renumber step 4 to 3 (`/ce:work`)
+  - Renumber steps 5-10 to 4-9
+  - Keep step 2 (`/ce:plan`) unchanged
+
+  **Patterns to follow:**
+  - lfg's existing step structure with GATE markers
+  - slfg's existing phase structure (Sequential, Parallel, Autofix, Finalize)
+
+  **Verification:**
+  - No references to `deepen-plan` or `deepen` in lfg or slfg
+  - Step numbers are sequential with no gaps
+  - lfg flow is: optional ralph-loop → ce:plan (with GATE) → ce:work (with GATE) → ce:review mode:autofix → todo-resolve → test-browser → feature-video → DONE. Preserve the existing GATE after ce:work
+  - slfg flow is: optional ralph-loop → ce:plan → ce:work (swarm) → parallel ce:review mode:report-only + test-browser → ce:review mode:autofix → todo-resolve → feature-video → DONE
+
+---
+
+- [ ] **Unit 4: Update peripheral references**
+
+  **Goal:** Remove stale deepen-plan references from README, AGENTS.md, learnings-researcher, and document-review
+
+  **Requirements:** R6, R7
+
+  **Dependencies:** Unit 2
+
+  **Files:**
+  - Modify: `plugins/compound-engineering/README.md`
+  - Modify: `plugins/compound-engineering/AGENTS.md`
+  - Modify: `plugins/compound-engineering/agents/research/ce-learnings-researcher.agent.md`
+  - Modify: `plugins/compound-engineering/skills/document-review/SKILL.md`
+
+  **Approach:**
+
+  *README.md:*
+  - Remove `/deepen-plan` row from the Core Workflow table
+  - Update the `/ce:plan` description to mention that it includes automatic confidence checking
+  - Verify skill count in the Components table still says "40+" (removing 1 skill, adding 0)
+
+  *AGENTS.md:*
+  - Line 116: Replace `/deepen-plan` example with another valid skill (e.g., `/ce:compound` or `/changelog`)
+
+  *learnings-researcher.md:*
+  - Remove the `/deepen-plan` integration point line. The deepening behavior is now inside ce:plan, which already invokes learnings-researcher in Phase 1.1. The Phase 5.3 agent mapping also includes learnings-researcher for "Context & Research" gaps, so the integration is preserved
+
+  *document-review SKILL.md:*
+  - Line 196: Update the "do not modify" caller list — remove both `deepen-plan-beta` and `ce-plan-beta` (both are stale beta names). Update to the current accurate callers: `ce-brainstorm`, `ce-plan`
+
+  **Verification:**
+  - No references to `deepen-plan` or `/deepen-plan` in any of these files
+  - README Core Workflow table has one fewer row
+  - `bun run release:validate` passes
+
+---
+
+- [ ] **Unit 5: Update converter and writer tests**
+
+  **Goal:** Replace deepen-plan references in test data with another skill name so tests still validate slash-command remapping behavior
+
+  **Requirements:** R6
+
+  **Dependencies:** Unit 2
+
+  **Files:**
+  - Modify: `tests/codex-writer.test.ts`
+  - Modify: `tests/codex-converter.test.ts`
+  - Modify: `tests/droid-converter.test.ts`
+  - Modify: `tests/copilot-converter.test.ts`
+  - Modify: `tests/pi-converter.test.ts`
+  - Modify: `tests/review-skill-contract.test.ts`
+
+  **Approach:**
+  - In each test file, replace `deepen-plan` in test input data and expected output with another existing skill name that has the same structural properties (a non-`ce:` prefixed skill with a hyphenated name). Good candidates: `reproduce-bug`, `git-commit`, or `todo-resolve`
+  - `review-skill-contract.test.ts` line 157: update the test description from "deepen-plan reviewer" to match whichever skill name replaces it (or update to reflect what the test actually validates — it tests `data-migration-expert` agent content)
+  - No converter source code changes needed — repo research confirmed no hardcoded deepen-plan references in `src/`
+
+  **Patterns to follow:**
+  - Existing test data structure in each file
+  - Use a consistent replacement skill name across all test files for clarity
+
+  **Test scenarios:**
+  - All existing test assertions pass with the replacement skill name
+  - Slash-command remapping behavior is still validated for each target (Codex, Droid, Copilot, Pi)
+
+  **Verification:**
+  - `bun test` passes
+  - No references to `deepen-plan` in any test file
+
+---
+
+- [ ] **Unit 6: Validate plugin consistency**
+
+  **Goal:** Ensure the skill removal doesn't break plugin metadata or marketplace consistency
+
+  **Requirements:** R6
+
+  **Dependencies:** Units 1-5
+
+  **Files:**
+  - Read (validation only): `plugins/compound-engineering/.claude-plugin/plugin.json`
+  - Read (validation only): `.claude-plugin/marketplace.json`
+
+  **Approach:**
+  - Run `bun run release:validate` to check consistency
+  - Run `bun test` to confirm all tests pass
+  - Verify no remaining references to `deepen-plan` in active skill files (historical docs excluded)
+
+  **Verification:**
+  - `bun run release:validate` passes
+  - `bun test` passes
+  - `grep -r "deepen-plan" plugins/compound-engineering/skills/` returns no results
+  - `grep -r "deepen-plan" plugins/compound-engineering/agents/` returns no results
+  - `grep -r "deepen-plan" plugins/compound-engineering/README.md` returns no results
+  - Note: CHANGELOG.md and historical docs in `docs/plans/`, `docs/brainstorms/`, `docs/solutions/` will still contain deepen-plan references — these are historical records and should not be updated
+
+## System-Wide Impact
+
+- **Interaction graph:** ce:plan's Phase 5.3 dispatches the same research and review agents that deepen-plan used. The agent contracts are unchanged — only the caller changes. lfg and slfg lose a step but gain nothing new since ce:plan handles deepening internally
+- **Error propagation:** If agent dispatch fails during Phase 5.3, the fallback from deepen-plan Phase 4.2 is preserved: re-run the agent or fall back to direct-mode reasoning. The plan is still written to disk even if deepening partially fails
+- **State lifecycle risks:** The `deepened:` frontmatter field continues to be set only when substantive changes are made. Plans that were deepened by the old standalone deepen-plan retain their `deepened:` date — no migration needed
+- **API surface parity:** The converter tests use deepen-plan as sample data for slash-command remapping. After updating to a different skill name, all target converters (Codex, Droid, Copilot, Pi) continue to validate the same remapping behavior
+- **Integration coverage:** The atomic update of all callers (lfg, slfg, ce:plan, README, AGENTS.md, learnings-researcher, document-review) in one PR prevents a broken intermediate state (per learnings from beta-promotion-orchestration-contract.md)
+
+## Risks & Dependencies
+
+- **Risk: Phase 5.3 content size.** Absorbing ~300 lines of deepen-plan logic into ce:plan makes it significantly longer (~950+ lines). Mitigation: the content is self-contained in one sub-phase and can be extracted to a reference file if token pressure becomes an issue
+- **Risk: Converter test fragility.** Changing test input data could reveal implicit assumptions in converter logic. Mitigation: repo research confirmed no hardcoded deepen-plan references in `src/`. The tests use it as generic sample data
+- **Risk: Orphaned scratch directories.** Existing `.context/compound-engineering/deepen-plan/` directories from prior runs will not be cleaned up. Mitigation: these are ephemeral scratch files with no functional impact; not worth special handling
+
+## Sources & References
+
+- **Origin document:** [docs/brainstorms/2026-03-26-merge-deepen-into-plan-requirements.md](docs/brainstorms/2026-03-26-merge-deepen-into-plan-requirements.md)
+- Deepen-plan source: `plugins/compound-engineering/skills/deepen-plan/SKILL.md`
+- Ce:plan source: `plugins/compound-engineering/skills/ce-plan/SKILL.md`
+- Learnings: `docs/solutions/skill-design/beta-skills-framework.md`, `docs/solutions/skill-design/beta-promotion-orchestration-contract.md`, `docs/solutions/plugin-versioning-requirements.md`

docs/plans/2026-03-27-001-refactor-ce-skill-prefix-rename-plan.md

@@ -0,0 +1,473 @@
+---
+title: "refactor: Rename all skills and agents to consistent ce- prefix"
+type: refactor
+status: completed
+date: 2026-03-27
+origin: docs/brainstorms/2026-03-27-ce-skill-prefix-rename-requirements.md
+deepened: 2026-03-27
+---
+
+# Rename All Skills and Agents to Consistent `ce-` Prefix
+
+## Overview
+
+Rename all 37 compound-engineering-owned skills and all 49 agents to use a consistent `ce-` hyphen prefix, eliminating namespace collisions with other plugins and removing the colon character that required filesystem sanitization. Agent files are renamed with `ce-` prefix within their existing category subdirs, and 3-segment fully-qualified references (`compound-engineering:<category>:<agent>`) are simplified to `<category>:ce-<agent>` (drop plugin prefix, keep category). This is a cross-cutting mechanical rename touching skill directories, agent files, frontmatter, cross-references, converter source code, tests, and documentation.
+
+## Problem Frame
+
+Generic skill names (`setup`, `plan`, `review`) collide when users install multiple Claude Code plugins. The current naming is inconsistent: 8 core workflow skills use `ce:` colon prefix while 33 others have no prefix. Agent references use verbose 3-segment format (`compound-engineering:review:adversarial-reviewer`). Standardizing on `ce-` eliminates collisions, aligns directory names with frontmatter names, and simplifies agent references. (see origin: docs/brainstorms/2026-03-27-ce-skill-prefix-rename-requirements.md)
+
+## Requirements Trace
+
+- R1. All owned skills AND agents adopt `ce-` hyphen prefix
+- R2. `ce:` colon prefix -> `ce-` hyphen prefix (e.g., `ce:plan` -> `ce-plan`)
+- R3. Unprefixed skills and agents get `ce-` prepended (e.g., `setup` -> `ce-setup`, `repo-research-analyst` -> `ce-repo-research-analyst`)
+- R4. `git-*` skills replace prefix with `ce-` (e.g., `git-commit` -> `ce-commit`)
+- R5. `report-bug-ce` normalizes to `ce-report-bug`
+- R6. `agent-browser` and `rclone` excluded (upstream)
+- R7. `lfg` and `slfg` excluded (memorable names), but internal references updated (R12)
+- R8. Skill/agent frontmatter `name:` must match; directories reflect new names
+- R9. All cross-references updated (slash commands, fully-qualified, prose, descriptions, intra-skill paths)
+- R10. Active documentation updated (README, AGENTS.md); historical docs left as-is
+- R11. Agent prompt files updated where they reference skill names
+- R11b. Skill prompt files updated where they reference agent names
+- R11c. Agent references `compound-engineering:<category>:<agent>` simplified to `<category>:ce-<agent>`
+- R12. lfg/slfg orchestration chains updated (skill AND agent invocations)
+- R13. Sanitization infrastructure preserved; add lint assertion for no-colon invariant
+- R14-R16. Tests pass, release:validate passes
+- R17. Codex converter hardcoded `ce:` checks updated
+- R18. Test fixtures updated appropriately
+- R19. Grep sanity check: new names correct, old names do not persist in active code
+
+## Scope Boundaries
+
+- Not removing `sanitizePathName()` (defense-in-depth for future colons)
+- Not adding backward-compatibility aliases (clean break)
+- Not updating historical docs in `docs/`
+- Not renaming `agent-browser`, `rclone`, `lfg`, `slfg`
+- All renames use `git mv`; fallback only with notification
+- Single commit for the entire change
+
+## Context & Research
+
+### Relevant Code and Patterns
+
+- `src/parsers/claude.ts:108` — Skill name from frontmatter `data.name`, fallback to dir basename
+- `src/utils/files.ts:84-86` — `sanitizePathName()` replaces colons with hyphens
+- `src/converters/claude-to-codex.ts:180-195` — Hardcoded `ce:` prefix checks for canonical workflow skills
+- `src/utils/codex-content.ts:75-86` — `normalizeCodexName()` for Codex flat naming
+- `tests/path-sanitization.test.ts` — Collision detection test loading real plugin
+
+### Institutional Learnings
+
+- `docs/solutions/integrations/colon-namespaced-names-break-windows-paths.md` — Documents the colon/hyphen duality and three-layer sanitization (target writers, sync paths, converter dedupe sets). After this rename, the duality is eliminated for CE skills but sanitization stays for other plugins.
+- `docs/solutions/codex-skill-prompt-entrypoints.md` — Codex derives skill names from directory basenames. The `isCanonicalCodexWorkflowSkill()` function identifies which skills get prompt wrappers. After rename, ALL skills start with `ce-`, so prefix-based detection breaks — needs frontmatter-field-based detection instead.
+- `docs/solutions/skill-design/beta-skills-framework.md` — Validates that stale cross-references after rename cause routing bugs. Must search all SKILL.md files for old names after rename.
+
+## Key Technical Decisions
+
+- **Codex canonical skill detection via frontmatter field**: After rename, `startsWith("ce-")` matches ALL skills. Rather than a hardcoded allowlist (fragile, poor discoverability), add `codex-prompt: true` to the 8 workflow SKILL.md frontmatter files, extend `ClaudeSkill` type with `codexPrompt?: boolean`, and parse it in `loadSkills()`. The converter then checks `skill.codexPrompt === true` instead of name patterns. This follows the codebase grain (parser already extracts frontmatter fields) and naturally propagates when copying workflow skill templates. New workflow skills are discoverable because the field is right where the skill is defined.
+- **`workflows:` alias mapping**: `toCanonicalWorkflowSkillName()` currently produces `ce:plan` from `workflows:plan`. Update to produce `ce-plan`. The `isDeprecatedCodexWorkflowAlias()` check (`startsWith("workflows:")`) is unaffected.
+- **Converter content-transformation is idempotent — no other converter code changes needed**: All 6 converters with slash-command rewriting (Windsurf, Droid, Kiro, Copilot, Pi, Codex) use generic `normalizeName()` that replaces colons with hyphens via `.replace(/[:\s]+/g, "-")`. So `/ce:plan` and `/ce-plan` both normalize to `ce-plan` — identical output. The 4 converters without slash-command rewriting (OpenClaw, Qwen, OpenCode, Gemini) pass skill content through untransformed. Only the Codex `isCanonicalCodexWorkflowSkill()` function needs updating.
+- **Droid converter behavioral change (expected, beneficial)**: Droid's `flattenCommandName()` strips everything before the last colon: `/ce:plan` -> `/plan`. After rename, `/ce-plan` has no colon so it passes through as `/ce-plan`. This preserves the `ce-` prefix in Droid target output, which is an improvement. No code change needed — it happens automatically from the content change.
+- **Test fixture strategy**: Fixtures testing compound-engineering-specific behavior (Codex prompt wrappers, review skill contracts) update to `ce-plan`. Fixtures testing abstract colon handling (path-sanitization) change examples to non-CE names like `other:skill` to preserve coverage of the colon path.
+- **Agent rename in place (no flattening)**: Category subdirs preserved for organization. Agent files renamed with `ce-` prefix within their category dir: `agents/review/adversarial-reviewer.md` -> `agents/review/ce-adversarial-reviewer.md`. References drop the `compound-engineering:` plugin prefix but keep category: `compound-engineering:review:adversarial-reviewer` -> `review:ce-adversarial-reviewer`.
+- **Major version bump**: This is a breaking change affecting all users; plugin version will bump major to signal it.
+- **git mv required**: All renames use `git mv` for history preservation per requirements. Fallback only with notification.
+- **Single atomic commit**: All directory renames, content changes, code changes, and test updates in one commit. Intermediate states would have broken tests and stale references.
+
+## Open Questions
+
+### Resolved During Planning
+
+- **Codex `isCanonicalCodexWorkflowSkill` fix strategy**: Use `codex-prompt: true` frontmatter field instead of prefix check or hardcoded allowlist. Follows the codebase grain, is self-documenting, and naturally propagates via skill template copying.
+- **Other converter content-transformation**: Verified all 6 converters with slash-command rewriting use generic `normalizeName()` — idempotent on colon/hyphen. No code changes needed beyond Codex `isCanonicalCodexWorkflowSkill`.
+- **Commit strategy**: Single commit. The PR is the review artifact.
+- **Test fixtures for colon handling**: Change `ce:plan` examples in path-sanitization tests to `other:skill` so colon sanitization is still tested without depending on CE skill names.
+- **`/sync` stale reference in README**: Clean up during documentation pass.
+- **Cross-reference scope**: Exhaustive inventory found 24 files with ~100+ replacements across 7 distinct reference patterns (see Unit 3).
+
+### Deferred to Implementation
+
+- Exact wording of the AGENTS.md "Why `ce-`?" rationale rewrite — depends on how the surrounding context reads after all name changes
+- Whether any additional agent files beyond the 5 identified contain skill name references — implementer should grep comprehensively
+
+## Implementation Units
+
+- [ ] **Unit 1: Skill directory renames**
+
+**Goal:** Rename all 29 skill directories that need new names via `git mv`.
+
+**Requirements:** R1, R3, R4, R5, R8
+
+**Dependencies:** None (first unit)
+
+**Files:**
+- `git mv` 29 directories under `plugins/compound-engineering/skills/`:
+  - 4 git-* replacements: `git-commit/` -> `ce-commit/`, `git-commit-push-pr/` -> `ce-commit-push-pr/`, `git-worktree/` -> `ce-worktree/`, `git-clean-gone-branches/` -> `ce-clean-gone-branches/`
+  - 1 normalization: `report-bug-ce/` -> `ce-report-bug/`
+  - 24 prefix additions: `agent-native-architecture/` -> `ce-agent-native-architecture/`, `agent-native-audit/` -> `ce-agent-native-audit/`, `andrew-kane-gem-writer/` -> `ce-andrew-kane-gem-writer/`, `changelog/` -> `ce-changelog/`, `claude-permissions-optimizer/` -> `ce-claude-permissions-optimizer/`, `deploy-docs/` -> `ce-deploy-docs/`, `dhh-rails-style/` -> `ce-dhh-rails-style/`, `document-review/` -> `ce-document-review/`, `dspy-ruby/` -> `ce-dspy-ruby/`, `every-style-editor/` -> `ce-every-style-editor/`, `feature-video/` -> `ce-feature-video/`, `frontend-design/` -> `ce-frontend-design/`, `gemini-imagegen/` -> `ce-gemini-imagegen/`, `onboarding/` -> `ce-onboarding/`, `orchestrating-swarms/` -> `ce-orchestrating-swarms/`, `proof/` -> `ce-proof/`, `reproduce-bug/` -> `ce-reproduce-bug/`, `resolve-pr-feedback/` -> `ce-resolve-pr-feedback/`, `setup/` -> `ce-setup/`, `test-browser/` -> `ce-test-browser/`, `test-xcode/` -> `ce-test-xcode/`, `todo-create/` -> `ce-todo-create/`, `todo-resolve/` -> `ce-todo-resolve/`, `todo-triage/` -> `ce-todo-triage/`
+- 8 `ce:` skills need NO directory rename (dirs already use hyphens: `ce-brainstorm/`, `ce-plan/`, etc.)
+
+**Approach:**
+- Execute all `git mv` operations in sequence
+- The 4 excluded skills remain: `agent-browser/`, `rclone/`, `lfg/`, `slfg/`
+
+**Verification:**
+- All 41 skill directories present with correct names
+- `git status` shows 29 renames tracked
+
+---
+
+- [ ] **Unit 1b: Agent file renames (in place)**
+
+**Goal:** Rename all 49 agent files with `ce-` prefix within their existing category subdirs.
+
+**Requirements:** R1, R3, R8
+
+**Dependencies:** None (can run in parallel with Unit 1)
+
+**Files:**
+- `git mv` 49 agent files within their category subdirs: `agents/<category>/<name>.md` -> `agents/<category>/ce-<name>.md`
+- Category subdirs preserved: `design/`, `docs/`, `document-review/`, `research/`, `review/`, `workflow/`
+
+**Approach:**
+- For each agent file: `git mv agents/<category>/<name>.md agents/<category>/ce-<name>.md`
+- See the complete agent rename map in the requirements doc for all 49 mappings
+
+**Verification:**
+- 49 `ce-*.md` files across category subdirs
+- Category directory structure unchanged
+- `git status` shows 49 renames tracked
+
+---
+
+- [ ] **Unit 2: Frontmatter and description updates**
+
+**Goal:** Update the `name:` and `description:` fields in all 37 renamed skills' SKILL.md files. Add `codex-prompt: true` to the 8 workflow skills.
+
+**Requirements:** R1, R2, R3, R4, R5, R8, R9, R17
+
+**Dependencies:** Unit 1 (directories exist at new paths)
+
+**Files:**
+- Modify: All 37 `SKILL.md` files in renamed skill directories
+  - 8 `ce:` skills: change `name: ce:X` to `name: ce-X` in frontmatter
+  - 29 others: change `name: X` to `name: ce-X` (with appropriate prefix rule)
+  - Update `description:` fields that reference old skill names (confirmed: `ce-work-beta` references "ce:work", `setup` references "ce:review", `ce-plan` references "ce:brainstorm")
+  - Add `codex-prompt: true` to frontmatter of the 8 workflow skills: `ce-brainstorm`, `ce-compound`, `ce-compound-refresh`, `ce-ideate`, `ce-plan`, `ce-review`, `ce-work`, `ce-work-beta`
+
+**Approach:**
+- For each SKILL.md, edit the YAML frontmatter `name:` field
+- Search each `description:` field for references to old skill names and update
+- Add `codex-prompt: true` field to the 8 workflow skill frontmatter blocks
+- Use the rename map from the requirements doc as the authoritative mapping
+
+**Patterns to follow:**
+- Frontmatter format: `name: ce-plan` (no colons)
+- Keep `description:` prose style consistent with existing descriptions
+
+**Test scenarios:**
+- Every SKILL.md has a `name:` field matching its directory name
+- No `name:` field contains a colon character
+- Exactly 8 SKILL.md files have `codex-prompt: true`
+
+**Verification:**
+- `grep -r "^name: ce:" plugins/compound-engineering/skills/` returns zero results
+- Every `name:` matches its containing directory name
+- `grep -rl "codex-prompt: true" plugins/compound-engineering/skills/` returns exactly 8 files
+
+---
+
+- [ ] **Unit 3: Intra-skill cross-reference updates**
+
+**Goal:** Update all skill-to-skill references inside SKILL.md content (not frontmatter). Exhaustive inventory: 20 SKILL.md files, ~100+ individual replacements across 7 reference patterns.
+
+**Requirements:** R9, R12
+
+**Dependencies:** Unit 2
+
+**Files:**
+- Modify (20 SKILL.md files with cross-references):
+  - `skills/ce-plan/SKILL.md` — ~8 `/ce:work` refs + 7 `document-review` backtick refs
+  - `skills/ce-brainstorm/SKILL.md` — ~12 `/ce:plan`, `/ce:work` refs + 1 `document-review` ref
+  - `skills/ce-compound/SKILL.md` — ~7 `/ce:compound-refresh`, `/ce:plan` refs
+  - `skills/ce-ideate/SKILL.md` — `/ce:brainstorm`, `/ce:plan` refs
+  - `skills/ce-review/SKILL.md` — routing table refs + 2 `todo-create` backtick refs
+  - `skills/ce-work/SKILL.md` — `/ce:plan`, `/ce:review` + `skill: git-worktree` loader ref
+  - `skills/ce-work-beta/SKILL.md` — same as ce-work + `frontend-design` backtick ref
+  - `skills/lfg/SKILL.md` — `/ce:plan`, `/ce:work`, `/ce:review` + `/compound-engineering:todo-resolve`, `:test-browser`, `:feature-video`
+  - `skills/slfg/SKILL.md` — same patterns as lfg
+  - `skills/ce-worktree/SKILL.md` — `/ce:review`, `/ce:work` + 20 `${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/` path refs + 2 `call git-worktree skill` self-refs
+  - `skills/ce-todo-create/SKILL.md` — `/ce:review` + `todo-triage` backtick ref + `/todo-resolve`, `/todo-triage` slash refs
+  - `skills/ce-todo-triage/SKILL.md` — `todo-create` backtick ref + 2 `/todo-resolve` slash refs
+  - `skills/ce-todo-resolve/SKILL.md` — `/ce:compound` + 2 `.context/compound-engineering/todo-resolve/` scratch paths
+  - `skills/ce-agent-native-audit/SKILL.md` — `/compound-engineering:agent-native-architecture` + bare name ref
+  - `skills/ce-test-browser/SKILL.md` — `agent-browser` backtick ref + `todo-create` backtick ref + 4 `/test-browser` self-refs
+  - `skills/ce-feature-video/SKILL.md` — 3 `agent-browser` backtick refs + 5 `/feature-video` self-refs + 11 `.context/compound-engineering/feature-video/` scratch paths
+  - `skills/ce-reproduce-bug/SKILL.md` — `agent-browser` backtick ref
+  - `skills/ce-frontend-design/SKILL.md` — `agent-browser` backtick ref
+  - `skills/ce-report-bug/SKILL.md` — `/report-bug-ce` self-ref
+  - `skills/ce-document-review/SKILL.md` — skill reference patterns (verify agent refs vs skill refs)
+
+**Approach:**
+- Seven reference patterns to update:
+  1. `/ce:X` -> `/ce-X` (slash command invocations of workflow skills)
+  2. `ce:X` -> `ce-X` (prose mentions of workflow skills without slash)
+  3. `/compound-engineering:X` -> `/compound-engineering:ce-X` (fully-qualified skill refs for skills that gained `ce-` prefix — e.g., `/compound-engineering:todo-resolve` -> `/compound-engineering:ce-todo-resolve`)
+  4. `${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/` -> `${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/` (intra-skill paths)
+  5. Backtick skill refs: `` `document-review` `` -> `` `ce-document-review` ``, `` `todo-create` `` -> `` `ce-todo-create` ``, `skill: git-worktree` -> `skill: ce-worktree`, etc.
+  6. Self-referencing slash commands: `/test-browser` -> `/ce-test-browser`, `/feature-video` -> `/ce-feature-video`, `/todo-resolve` -> `/ce-todo-resolve`, `/report-bug-ce` -> `/ce-report-bug`
+  7. Scratch space paths: `.context/compound-engineering/feature-video/` -> `.context/compound-engineering/ce-feature-video/`, `.context/compound-engineering/todo-resolve/` -> `.context/compound-engineering/ce-todo-resolve/`
+
+**Critical exclusions — do NOT update:**
+- `agent-browser` references — this skill is EXCLUDED from renaming (R6, upstream). Many skills reference it with `the \`agent-browser\` skill`; these must stay as-is
+- `rclone` references — also excluded
+- `lfg`/`slfg` references — excluded from renaming (R7), though their internal refs ARE updated
+
+**Note:** Agent references like `compound-engineering:review:code-simplicity-reviewer` ARE now in scope (R11c) — they will be updated in Unit 3b.
+
+**Test scenarios:**
+- `grep -r "/ce:" plugins/compound-engineering/skills/` returns zero results (after excluding agent refs like `compound-engineering:category:agent`)
+- lfg/slfg chains reference new skill names
+- ce-worktree script paths point to `ce-worktree/` directory
+- No stale bare skill name references for renamed skills in backtick patterns
+
+**Verification:**
+- No stale `/ce:` skill references remain in any SKILL.md
+- No stale `/compound-engineering:todo-resolve` (without `ce-` prefix) patterns remain for renamed skills
+- No stale bare `document-review`, `todo-create`, `git-worktree` backtick refs (replaced with `ce-` prefixed names)
+
+---
+
+- [ ] **Unit 3b: Agent reference updates across skills and agents**
+
+**Goal:** Update all agent references throughout skills and agent files. Drop `compound-engineering:` plugin prefix from 3-segment refs, keeping `<category>:ce-<agent>`. Update agent frontmatter `name:` fields.
+
+**Requirements:** R8, R11, R11b, R11c, R12
+
+**Dependencies:** Unit 1b (agent files at new paths)
+
+**Files:**
+- Modify: All 49 agent `.md` files — update frontmatter `name:` to `ce-<agent-name>`
+- Modify: All skill SKILL.md files that reference agents via `compound-engineering:<category>:<agent>` pattern (many files — ce-plan, ce-review, ce-brainstorm, ce-ideate, ce-document-review, ce-work, ce-work-beta, ce-orchestrating-swarms, ce-resolve-pr-feedback, lfg, slfg, and others)
+- Modify: Agent files that reference other agents via fully-qualified names
+- Modify: Agent `description:` frontmatter fields that may reference the old format
+- Modify: `project-standards-reviewer` agent — its review criteria explicitly enforce the old 3-segment convention; needs conceptual update
+
+**Approach:**
+- Update all 49 agent frontmatter `name:` fields to `ce-<agent-name>`
+- Replace all `compound-engineering:<category>:<agent>` references with `<category>:ce-<agent>` across ALL skill and agent files. Key patterns:
+  1. `Task compound-engineering:<category>:<agent>` -> `Task <category>:ce-<agent>` (Task tool invocations in skills)
+  2. `subagent_type: compound-engineering:<category>:<agent>` -> `subagent_type: <category>:ce-<agent>` (orchestrating-swarms and similar)
+  3. `` `compound-engineering:<category>:<agent>` `` -> `` `<category>:ce-<agent>` `` (backtick references in prose)
+  4. Bare prose mentions of fully-qualified agent names
+- Agent files that reference skill names (handled in Unit 6) — but agent files referencing OTHER agents by old name need updating here
+- lfg/slfg agent invocations updated per R12
+- `project-standards-reviewer` agent's review criteria updated to enforce `<category>:ce-<agent>` format instead of `compound-engineering:<category>:<agent>`
+
+**Test scenarios:**
+- `grep -r "compound-engineering:" plugins/compound-engineering/skills/ plugins/compound-engineering/agents/` returns zero results for agent references (skill fully-qualified refs like `/compound-engineering:ce-todo-resolve` may still exist)
+- Every agent frontmatter `name:` starts with `ce-`
+
+**Verification:**
+- No `compound-engineering:<category>:<agent>` references remain in active skill/agent files
+- All 49 agent `name:` fields updated
+- `project-standards-reviewer` enforces new naming convention
+
+---
+
+- [ ] **Unit 4: Codex converter and parser updates**
+
+**Goal:** Replace the Codex converter's hardcoded `ce:` prefix logic with a frontmatter-driven `codex-prompt` field. Update the parser and types to support the new field.
+
+**Requirements:** R17
+
+**Dependencies:** Unit 2 (the 8 workflow SKILL.md files must have `codex-prompt: true` in frontmatter)
+
+**Files:**
+- Modify: `src/types/claude.ts` — Add `codexPrompt?: boolean` to `ClaudeSkill` type
+- Modify: `src/parsers/claude.ts` — Extract `codex-prompt` from frontmatter in `loadSkills()`
+- Modify: `src/converters/claude-to-codex.ts`
+  - Replace `isCanonicalCodexWorkflowSkill(name)` with a check on `skill.codexPrompt === true`
+  - Update `toCanonicalWorkflowSkillName` to produce `ce-` instead of `ce:`
+
+**Approach:**
+- Add `codexPrompt?: boolean` to the `ClaudeSkill` type alongside existing fields like `disableModelInvocation`
+- In `loadSkills()`, extract `codex-prompt` from frontmatter: `codexPrompt: data['codex-prompt'] === true`
+- In the Codex converter, change `isCanonicalCodexWorkflowSkill` to accept the skill object (not just name) and check `skill.codexPrompt === true`. This may require adjusting the call sites to pass the full skill rather than just `skill.name`
+- Update `toCanonicalWorkflowSkillName` to produce `ce-` prefix: `ce-${name.slice("workflows:".length)}`
+- The `isDeprecatedCodexWorkflowAlias` function (`startsWith("workflows:")`) needs no change
+- No other converter code changes needed — all other content transformations are idempotent on colon/hyphen
+
+**Patterns to follow:**
+- Existing frontmatter field extraction pattern in `src/parsers/claude.ts` (see `disableModelInvocation` extraction)
+- Existing `ClaudeSkill` type field pattern in `src/types/claude.ts`
+
+**Test scenarios:**
+- A skill with `codex-prompt: true` gets identified as a workflow skill
+- A skill without the field (or `codex-prompt: false`) is NOT a workflow skill
+- `toCanonicalWorkflowSkillName("workflows:plan")` returns `"ce-plan"`
+- The 8 workflow skills from the real plugin all have `codexPrompt: true` when parsed
+
+**Verification:**
+- Codex converter correctly identifies the 8 canonical workflow skills via frontmatter field
+- `workflows:*` aliases map to `ce-*` names
+- No hardcoded skill name checks remain in converter code
+
+---
+
+- [ ] **Unit 5: Test fixture updates**
+
+**Goal:** Update all test files with hardcoded skill names to reflect the new `ce-` prefix.
+
+**Requirements:** R14, R15, R18
+
+**Dependencies:** Unit 4 (converter changes affect test expectations)
+
+**Files:**
+- Modify (compound-engineering specific fixtures — update to `ce-plan`):
+  - `tests/codex-converter.test.ts` — ~10 fixtures with `ce:plan`, `ce:brainstorm`
+  - `tests/codex-writer.test.ts` — ~5 fixtures
+  - `tests/review-skill-contract.test.ts` — string assertions for `/ce:review`
+  - `tests/compound-support-files.test.ts` — describe label
+  - `tests/release-metadata.test.ts` — mkdir and file content
+  - `tests/release-components.test.ts` — commit message parsing
+  - `tests/release-preview.test.ts` — title fixture
+  - Writer tests (all have `ce:plan` fixtures): `tests/kiro-writer.test.ts`, `tests/pi-writer.test.ts`, `tests/droid-writer.test.ts`, `tests/gemini-writer.test.ts`, `tests/copilot-writer.test.ts`, `tests/windsurf-writer.test.ts`
+  - `tests/windsurf-converter.test.ts` — collision dedup fixture
+  - `tests/copilot-converter.test.ts` — collision detection fixture
+  - `tests/openclaw-converter.test.ts` — fixture
+  - `tests/claude-home.test.ts` — frontmatter fixture
+- Modify (abstract colon-handling — change to non-CE example):
+  - `tests/path-sanitization.test.ts` — change `ce:brainstorm`/`ce:plan` examples to `other:skill`/`other:tool` to preserve colon sanitization coverage
+- Add: assertion in `tests/path-sanitization.test.ts` that no CE skill name contains a colon (R13 lint requirement)
+
+**Approach:**
+- For CE-specific tests: mechanically replace `ce:plan` with `ce-plan`, `ce:brainstorm` with `ce-brainstorm`, etc.
+- For path-sanitization tests: replace CE examples with generic colon examples to maintain coverage of the `sanitizePathName()` colon path
+- Add a new test case that loads the real plugin and asserts `!skill.name.includes(":")` for every skill
+
+**Test scenarios:**
+- All existing test assertions still pass with new fixture values
+- Path sanitization test still covers colon-to-hyphen conversion (with non-CE example)
+- New no-colon invariant test passes
+
+**Verification:**
+- `bun test` passes with zero failures
+
+---
+
+- [ ] **Unit 6: Skill-name references in agent files**
+
+**Goal:** Update agent `.md` files that reference skill names with old patterns (`/ce:plan`, bare `git-worktree`, etc.). Agent files are now at `agents/ce-*.md` after Unit 1b.
+
+**Requirements:** R11
+
+**Dependencies:** Unit 1b (agent files at new paths), Unit 3b (agent frontmatter and agent-to-agent refs already done)
+
+**Files:**
+- Modify (agent files with skill name references — paths reflect post-rename location):
+  - `plugins/compound-engineering/agents/research/ce-git-history-analyzer.agent.md` — references `/ce:plan`
+  - `plugins/compound-engineering/agents/research/ce-issue-intelligence-analyst.agent.md` — references `/ce:ideate`
+  - `plugins/compound-engineering/agents/research/ce-learnings-researcher.agent.md` — references `/ce:plan`
+  - `plugins/compound-engineering/agents/review/ce-code-simplicity-reviewer.agent.md` — references `/ce:plan`, `/ce:work`
+  - `plugins/compound-engineering/agents/research/ce-best-practices-researcher.agent.md` — references `agent-native-architecture`, `git-worktree` bare names (now `ce-agent-native-architecture`, `ce-worktree`)
+  - `bug-reproduction-validator` workflow agent reference — excluded, no change needed, verify only
+- Comprehensive grep to find any other agent files with old skill references
+
+**Approach:**
+- Replace `/ce:X` with `/ce-X` in skill slash-command references
+- Replace bare old skill names with `ce-` prefixed names in prose
+- Do NOT update `agent-browser` references (excluded per R6)
+
+**Verification:**
+- `grep -r "/ce:" plugins/compound-engineering/agents/` returns zero results
+- No agent file references old skill names (except excluded `agent-browser`)
+
+---
+
+- [ ] **Unit 7: Documentation updates**
+
+**Goal:** Update active documentation to reflect new skill AND agent names. Rewrite naming convention rationale. Update agent reference convention from 3-segment to flat `ce-` format.
+
+**Requirements:** R10
+
+**Dependencies:** Unit 1, Unit 1b (all names finalized)
+
+**Files:**
+- Modify: `plugins/compound-engineering/README.md` — skill tables, agent references
+- Modify: `plugins/compound-engineering/AGENTS.md` — command listing, "Why `ce:`?" section needs full conceptual rewrite to explain `ce-` convention for both skills and agents, agent reference convention section (was `compound-engineering:<category>:<agent>`, now `<category>:ce-<agent>`)
+- Modify: `README.md` (root) — Workflow table, prose references, Codex output notes. Clean up stale `/sync` reference.
+- Modify: `AGENTS.md` (root) — update agent reference convention if present
+
+**Approach:**
+- Skill tables: mechanical find-and-replace of `/ce:X` -> `/ce-X` and bare skill names
+- Agent references: update all `compound-engineering:<category>:<agent>` examples to `<category>:ce-<agent>`
+- AGENTS.md: rewrite naming convention section to explain unified `ce-` prefix for both skills and agents; update "Agent References in Skills" section to reflect new `<category>:ce-<agent>` format (was `compound-engineering:<category>:<agent>`)
+- Root README: update tables and remove stale `/sync` skill reference
+- Do NOT update historical docs in `docs/brainstorms/`, `docs/plans/`, `docs/solutions/`
+
+**Verification:**
+- No active doc references old `ce:` skill names or `compound-engineering:<category>:<agent>` agent patterns
+- AGENTS.md rationale section explains `ce-` convention coherently for both skills and agents
+- Agent reference convention updated from `compound-engineering:<category>:<agent>` to `<category>:ce-<agent>`
+
+---
+
+- [ ] **Unit 8: Verification sweep and commit**
+
+**Goal:** Final verification that no stale references remain for both skills AND agents, all tests pass, and release validation succeeds.
+
+**Requirements:** R14, R15, R16, R19
+
+**Dependencies:** All previous units
+
+**Files:**
+- No new files
+
+**Approach:**
+- Run comprehensive grep for stale SKILL names across the entire repo:
+  - `grep -r "ce:brainstorm\|ce:plan\|ce:review\|ce:work\|ce:ideate\|ce:compound" plugins/ src/ tests/` (should return zero outside historical docs)
+  - `grep -r "/git-commit\b\|/git-worktree\b\|/git-clean-gone\|/report-bug-ce\b" plugins/` (should return zero)
+  - `grep -r "/compound-engineering:todo-resolve\b\|/compound-engineering:test-browser\b\|/compound-engineering:feature-video\b\|/compound-engineering:setup\b" plugins/` (should return zero)
+- Run comprehensive grep for stale AGENT references:
+  - `grep -r "compound-engineering:review:\|compound-engineering:research:\|compound-engineering:design:\|compound-engineering:workflow:\|compound-engineering:document-review:\|compound-engineering:docs:" plugins/ src/ tests/` (should return zero — all converted to `ce-<agent>`)
+  - Verify no agent files remain in category subdirs
+- Run `bun test`
+- Run `bun run release:validate`
+- Fix any stragglers found
+- Commit all changes in a single commit
+
+**Verification:**
+- `bun test` passes with zero failures
+- `bun run release:validate` passes
+- No stale skill or agent name references in active code (plugins/, src/, tests/)
+- No 3-segment agent references remain
+
+## System-Wide Impact
+
+- **Interaction graph:** Skill-to-skill handoff chains (`brainstorm` -> `plan` -> `work` -> `review`) are the primary interaction surface. lfg/slfg orchestrate these chains. Skills dispatch agents via `Task` or `subagent_type` — these change from `compound-engineering:<category>:<agent>` to `<category>:ce-<agent>`. All handoff and dispatch references must use new names.
+- **Error propagation:** A missed cross-reference would cause skill invocation to fail at runtime with "skill not found". Grep-based verification in Unit 8 is the primary defense.
+- **State lifecycle risks:** Existing scratch directories at `.context/compound-engineering/ce-review/` are unaffected (already use hyphens). Renamed skills' scratch dirs (e.g., `feature-video/` -> `ce-feature-video/`) will start creating new paths; old orphaned scratch dirs from previous runs are harmless and ephemeral.
+- **Converter content-transformation (verified safe):** All 6 converters with slash-command rewriting (Windsurf, Droid, Kiro, Copilot, Pi, Codex) use generic `normalizeName()` that is idempotent on colon/hyphen — `/ce:plan` and `/ce-plan` both produce `ce-plan`. The 4 converters without content transformation (OpenClaw, Qwen, OpenCode, Gemini) pass content through unmodified. Only the Codex `isCanonicalCodexWorkflowSkill()` function needs code changes.
+- **Droid target behavioral change:** Droid's `flattenCommandName()` strips everything before the last colon: `/ce:plan` -> `/plan`. After rename, `/ce-plan` has no colon so it passes through as `/ce-plan`. This preserves the `ce-` prefix in Droid target output — an improvement, no code change needed.
+- **API surface parity:** `sanitizePathName()` becomes a no-op for CE skills but remains functional for other plugins that may use colons.
+- **Integration coverage:** The collision detection test in `tests/path-sanitization.test.ts` loads the real plugin — it will validate that no two renamed skills collide after sanitization.
+
+## Risks & Dependencies
+
+- **Very large diff size**: 29 skill directory renames + 49 agent file renames + content changes across 70+ files. Mitigation: single commit with clear commit message; PR description with summary table.
+- **Agent reference blast radius**: 3-segment `compound-engineering:<category>:<agent>` references appear in many skill files (ce-plan, ce-review, ce-brainstorm, ce-ideate, ce-document-review, ce-work, ce-orchestrating-swarms, ce-resolve-pr-feedback, lfg, slfg). All must be updated to `ce-<agent>`. Mitigation: comprehensive grep in Unit 8 verification.
+- **Missed cross-references**: 7+ distinct reference patterns across skills, plus agent reference patterns. Mitigation: exhaustive skill inventory from deepening; grep-based verification for both skills and agents.
+- **Codex converter behavioral change**: Moving from prefix-based to frontmatter-field-based detection. Mitigation: explicit test scenarios; field is self-documenting and follows existing codebase patterns.
+- **`agent-browser` exclusion discipline**: Many skills reference `the \`agent-browser\` skill` — these must NOT be updated since agent-browser is excluded (R6). Mitigation: explicit exclusion list in Unit 3 approach notes.
+- **User muscle memory**: `/ce:plan` stops working; `compound-engineering:review:adversarial-reviewer` format stops working. Mitigation: clean break is intentional; major version bump signals the change.
+
+## Sources & References
+
+- **Origin document:** [docs/brainstorms/2026-03-27-ce-skill-prefix-rename-requirements.md](docs/brainstorms/2026-03-27-ce-skill-prefix-rename-requirements.md)
+- Related issue: [#337](https://github.com/EveryInc/compound-engineering-plugin/issues/337)
+- Related learning: `docs/solutions/integrations/colon-namespaced-names-break-windows-paths.md`
+- Related learning: `docs/solutions/codex-skill-prompt-entrypoints.md`
+- Related learning: `docs/solutions/skill-design/beta-skills-framework.md`

docs/plans/2026-03-28-001-feat-ce-review-headless-mode-plan.md

@@ -0,0 +1,330 @@
+---
+title: "feat(ce-review): Add headless mode for programmatic callers"
+type: feat
+status: completed
+date: 2026-03-28
+origin: docs/brainstorms/2026-03-28-ce-review-headless-mode-requirements.md
+---
+
+# feat(ce-review): Add headless mode for programmatic callers
+
+## Overview
+
+Add `mode:headless` to ce:review so other skills can invoke it programmatically and receive structured findings without interactive prompts. Follows the pattern established by document-review's headless mode (PR #425).
+
+## Problem Frame
+
+ce:review has three modes (interactive, autofix, report-only), but none is designed for skill-to-skill invocation where the caller wants structured findings returned as parseable output. Autofix applies fixes and writes todos; report-only is read-only and outputs a human-readable report. Neither returns structured output for a calling workflow to consume and route. (see origin: `docs/brainstorms/2026-03-28-ce-review-headless-mode-requirements.md`)
+
+## Requirements Trace
+
+- R1. Add `mode:headless` argument, parsed alongside existing mode flags
+- R2. In headless mode, apply `safe_auto` fixes silently (matching autofix behavior)
+- R3. Return all non-auto findings as structured text output, preserving severity, autofix_class, owner, requires_verification, confidence, evidence[], pre_existing
+- R4. No `AskUserQuestion` or other interactive prompts in headless mode
+- R5. End with a clear completion signal so callers can detect when the review is done
+- R6. Follow document-review's structural output *pattern* (completion header, metadata block, autofix-class-grouped findings, trailing sections) while using ce:review's own section headings and per-finding fields
+
+## Scope Boundaries
+
+- Not changing existing three modes (interactive, autofix, report-only)
+- Not adding new reviewer personas or changing the review pipeline (Stages 3-5)
+- Not building a specific caller workflow — just enabling the capability
+- Not adding headless invocations to existing orchestrators (lfg, slfg) in this change
+
+## Context & Research
+
+### Relevant Code and Patterns
+
+- `plugins/compound-engineering/skills/ce-review/SKILL.md` — the skill to modify (mode detection at line 32, argument parsing at line 19, post-review flow at line 440)
+- `plugins/compound-engineering/skills/ce-review/references/review-output-template.md` — existing output template with pipe-delimited tables and severity-grouped sections
+- `plugins/compound-engineering/skills/ce-review/references/findings-schema.json` — ce:review's findings schema with `safe_auto|gated_auto|manual|advisory` autofix_class and `review-fixer|downstream-resolver|human|release` owner
+- `plugins/compound-engineering/skills/document-review/SKILL.md` — headless mode pattern to follow (Phase 0 parsing, Phase 4 headless output, Phase 5 immediate return)
+- `tests/review-skill-contract.test.ts` — contract test to extend
+
+### Institutional Learnings
+
+- `docs/solutions/skill-design/beta-promotion-orchestration-contract.md` — contract tests must be extended atomically with new mode flags
+- `docs/solutions/skill-design/compound-refresh-skill-improvements.md` — explicit opt-in only for autonomous modes (no auto-detection from tool availability); conservative treatment of borderline cases
+- `docs/solutions/skill-design/git-workflow-skills-need-explicit-state-machines.md` — walk all mode x state combinations when adding a new mode branch
+- `docs/solutions/agent-friendly-cli-principles.md` — structured parseable output with stable field contracts for programmatic callers
+
+## Key Technical Decisions
+
+- **Headless is a fourth explicit mode, not an overlay**: Each mode is self-contained with its own complete behavior specification. This avoids whack-a-mole regressions from overlay interactions (per state-machine learning). Headless has its own rules section parallel to autofix and report-only.
+
+- **No shared checkout switching, but NOT safe for concurrent use**: Headless follows report-only's checkout guard — if a PR/branch target is passed, headless must run in an isolated worktree or stop. However, unlike report-only, headless mutates files (applies safe_auto fixes). Callers must not run headless concurrently with other mutating operations on the same checkout. The headless rules section should explicitly state this.
+
+- **Single-pass, no re-review rounds**: Headless applies `safe_auto` fixes in one pass and returns. No bounded fixer loop. Rationale: autofix uses max_rounds:2 because it operates autonomously within a larger workflow; headless returns structured output to a caller that can re-invoke if needed. The caller owns the iteration decision, keeping headless simple and predictable. Applied fixes that introduce new issues will be caught on a subsequent invocation if the caller chooses to re-review.
+
+- **Write run artifacts, skip todos**: Run artifacts (`.context/compound-engineering/ce-review/<run-id>/`) provide an audit trail of what headless did. Todo files are skipped because the caller receives structured findings and routes downstream work itself.
+
+- **Reject conflicting mode flags**: `mode:headless` is incompatible with `mode:autofix` and `mode:report-only`. If multiple mode tokens appear, emit an error and stop. This follows the "fail fast with actionable errors" principle.
+
+- **Require diff scope with structured error**: Like document-review requiring a document path in headless mode, ce:review headless requires that a diff scope is determinable (branch, PR, or `base:` ref). If scope cannot be determined, emit a structured error: `Review failed (headless mode). Reason: <no diff scope detected | merge-base unresolved | conflicting mode flags>`. No agents are dispatched. The same structured error format applies to conflicting mode flags.
+
+## Open Questions
+
+### Resolved During Planning
+
+- **Fourth mode vs overlay?** Fourth mode. Self-contained behavior avoids overlay ambiguity. (Grounded in state-machine learning and the fact that all three existing modes have independent rules sections.)
+- **Artifacts and todos?** Write artifacts (audit trail), skip todos (caller routes findings). Headless owns mutation but not downstream handoff.
+- **Checkout behavior?** No shared checkout switching. Same guard as report-only, since headless callers need stable checkouts.
+- **Re-review rounds?** Single-pass. Callers can re-invoke if needed.
+
+### Deferred to Implementation
+
+- **Conflicting flags and missing scope error messages**: Decision made (reject with structured error), but exact wording and error envelope format deferred to implementation
+- Whether the run artifact format needs any headless-specific metadata (e.g., marking the run as headless)
+
+## High-Level Technical Design
+
+> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
+
+### Mode x Behavior Decision Matrix
+
+| Behavior | Interactive | Autofix | Report-only | **Headless** |
+|----------|------------|---------|-------------|--------------|
+| User questions | Yes | No | No | **No** |
+| Checkout switching | Yes | Yes | No (worktree or stop) | **No (worktree or stop)** |
+| Intent ambiguity | Ask user | Infer conservatively | Infer conservatively | **Infer conservatively** |
+| Apply safe_auto fixes | After policy question | Automatically | Never | **safe_auto only, single pass** |
+| Apply gated_auto/manual fixes | After user approval | Never | Never | **Never (returned in output)** |
+| Re-review rounds | max_rounds: 2 | max_rounds: 2 | N/A | **Single pass (no re-review)** |
+| Write run artifact | Yes | Yes | No | **Yes** |
+| Create todo files | No (user decides) | Yes (downstream-resolver) | No | **No (caller routes)** |
+| Structured text output | No (interactive report) | No (interactive report) | No (interactive report) | **Yes (headless envelope)** |
+| Commit/push/PR | Offered | Never | Never | **Never** |
+| Completion signal | N/A | Stops after artifacts | Stops after report | **"Review complete"** |
+| Safe for concurrent use | No | No | Yes (read-only) | **No (mutates files)** |
+
+### Headless Output Envelope
+
+Follows document-review's structural pattern adapted for ce:review's schema:
+
+```
+Code review complete (headless mode).
+
+Scope: <scope-line>
+Intent: <intent-summary>
+Reviewers: <reviewer-list with conditional justifications>
+Verdict: <Ready to merge | Ready with fixes | Not ready>
+Artifact: .context/compound-engineering/ce-review/<run-id>/
+
+Applied N safe_auto fixes.
+
+Gated-auto findings (concrete fix, changes behavior/contracts):
+
+[P1][gated_auto -> downstream-resolver][needs-verification] File: <file:line> -- <title> (<reviewer>, confidence <N>)
+  Why: <why_it_matters>
+  Suggested fix: <suggested_fix or "none">
+  Evidence: <evidence[0]>
+  Evidence: <evidence[1]>
+
+Manual findings (actionable, needs handoff):
+
+[P1][manual -> downstream-resolver] File: <file:line> -- <title> (<reviewer>, confidence <N>)
+  Why: <why_it_matters>
+  Evidence: <evidence[0]>
+
+Advisory findings (report-only):
+
+[P2][advisory -> human] File: <file:line> -- <title> (<reviewer>, confidence <N>)
+  Why: <why_it_matters>
+
+Pre-existing issues:
+- <file:line> -- <title> (<reviewer>)
+
+Residual risks:
+- <risk>
+
+Testing gaps:
+- <gap>
+```
+
+The `[needs-verification]` marker appears only on findings where `requires_verification: true`. The `Artifact:` line gives callers the path to the full run artifact for machine-readable access to the complete findings schema. The text envelope is the primary handoff; the artifact is for debugging and full-fidelity access.
+
+Findings with `owner: release` appear in the Advisory section (they are operational/rollout items, not code fixes). Findings with `pre_existing: true` appear in the Pre-existing section regardless of autofix_class.
+
+Omit any section with zero items. If all reviewers fail or time out, emit a degraded signal: `Code review degraded (headless mode). Reason: 0 of N reviewers returned results.` followed by "Review complete" so the caller can detect the failure and decide how to proceed.
+
+Then output "Review complete" as the terminal signal.
+
+## Implementation Units
+
+- [ ] **Unit 1: Mode Infrastructure**
+
+**Goal:** Add `mode:headless` to argument parsing, mode detection, and error handling for conflicting flags / missing scope.
+
+**Requirements:** R1, R4
+
+**Dependencies:** None
+
+**Files:**
+- Modify: `plugins/compound-engineering/skills/ce-review/SKILL.md`
+
+**Approach:**
+- Add `mode:headless` row to the Argument Parsing token table (alongside `mode:autofix` and `mode:report-only`)
+- Add headless row to the Mode Detection table with behavior summary
+- Add a "Headless mode rules" subsection parallel to "Autofix mode rules" and "Report-only mode rules"
+- Update the `argument-hint` frontmatter to include `mode:headless`
+- Add conflicting-flag guard: if multiple mode tokens appear in arguments, emit an error message listing the conflict and stop
+- Add scope-required guard: if headless mode cannot determine diff scope without user interaction, emit an error with re-invocation syntax (matching document-review's nil-path pattern)
+
+**Patterns to follow:**
+- Existing mode detection table structure at SKILL.md line 34
+- Existing mode rules subsections at SKILL.md lines 40-54
+- document-review Phase 0 parsing and nil-path guard at document-review SKILL.md lines 12-37
+
+**Test scenarios:**
+- Happy path: `mode:headless` token is parsed and headless mode is activated
+- Happy path: `mode:headless` with a branch name or PR number parses both correctly
+- Error path: `mode:headless mode:autofix` is rejected with a clear error
+- Error path: `mode:headless mode:report-only` is rejected with a clear error
+- Edge case: `mode:headless` alone with no branch/PR and no determinable scope emits a scope-required error
+
+**Verification:**
+- SKILL.md contains `mode:headless` in argument-hint, token table, mode detection table, and a dedicated rules subsection
+- Conflicting-flag and missing-scope guard text is present
+
+---
+
+- [ ] **Unit 2: Pipeline Behavior Adjustments**
+
+**Goal:** Add headless-specific behavior for Stage 1 (checkout guard) and Stage 2 (intent ambiguity).
+
+**Requirements:** R1, R4
+
+**Dependencies:** Unit 1
+
+**Files:**
+- Modify: `plugins/compound-engineering/skills/ce-review/SKILL.md`
+
+**Approach:**
+- In Stage 1 scope detection, add headless to the checkout guard alongside report-only: `mode:headless` and `mode:report-only` must not run `gh pr checkout` or `git checkout` on the shared checkout. They must run in an isolated worktree or stop. When headless stops due to the checkout guard, emit a structured error with re-invocation syntax (e.g., "Re-invoke with base:\<ref\> to review the current checkout, or run from an isolated worktree.").
+- In Stage 1 untracked file handling, add headless behavior: if the UNTRACKED list is non-empty, proceed with tracked changes only and note excluded files in the Coverage section of the structured output. Never stop to ask the user — this matches the "infer conservatively" pattern.
+- In Stage 2 intent discovery, add headless to the non-interactive path alongside autofix and report-only: infer intent conservatively, note uncertainty in Coverage/Verdict reasoning instead of blocking.
+- All changes are small additions to existing conditional text — add headless to the existing mode lists where report-only and autofix are already distinguished.
+
+**Patterns to follow:**
+- Existing report-only checkout guard at SKILL.md line 53 ("mode:report-only cannot switch the shared checkout")
+- Existing autofix/report-only intent handling at SKILL.md (~line 298)
+
+**Test scenarios:**
+- Happy path: headless mode with a PR target uses a worktree or stops instead of switching the shared checkout
+- Happy path: headless mode infers intent conservatively when diff metadata is thin
+- Happy path: headless mode with untracked files proceeds with tracked changes only and notes exclusions
+- Error path: headless stops due to checkout guard and emits re-invocation syntax
+
+**Verification:**
+- SKILL.md mentions headless alongside report-only in checkout guard sections
+- SKILL.md mentions headless alongside autofix/report-only in intent discovery sections
+- SKILL.md specifies headless behavior for untracked files (proceed, don't prompt)
+
+---
+
+- [ ] **Unit 3: Headless Output Format and Post-Review Flow**
+
+**Goal:** Define the headless structured text output and the headless post-review behavior (apply safe_auto, write artifacts, skip todos, output structured text, return completion signal).
+
+**Requirements:** R2, R3, R4, R5, R6
+
+**Dependencies:** Unit 1, Unit 2
+
+**Files:**
+- Modify: `plugins/compound-engineering/skills/ce-review/SKILL.md`
+- Modify: `plugins/compound-engineering/skills/ce-review/references/review-output-template.md`
+
+**Approach:**
+
+*Stage 6 output:*
+- Add a headless-specific output section to SKILL.md that defines the structured text envelope format
+- The envelope follows document-review's structural pattern: completion header, metadata (scope/intent/reviewers/verdict), applied fixes count, findings grouped by autofix_class with severity/route/file/line per finding, trailing sections (pre-existing, residual risks, testing gaps)
+- Per-finding format: `[severity][autofix_class -> owner] File: <file:line> -- <title> (<reviewer>, confidence <N>)` with Why and Suggested fix lines
+- Omit sections with zero items
+- In headless mode, output this structured text instead of the interactive pipe-delimited table report
+
+*Post-review flow (After Review section):*
+- Add "Headless mode" to Step 2 (Choose policy by mode) parallel to autofix and report-only
+- Headless rules: ask no questions; apply `safe_auto -> review-fixer` queue in a single pass (no re-review rounds); skip Step 3's bounded loop entirely
+- Step 4 (Emit artifacts): headless writes run artifacts (like autofix) but does NOT create todo files (caller handles routing from structured output)
+- Step 5: headless stops after structured text output and "Review complete" signal. No commit/push/PR.
+
+*Review output template:*
+- Add a "Headless mode format" section to `review-output-template.md` with the structured text template and formatting rules
+- Update the Mode line documentation to include `headless`
+
+**Patterns to follow:**
+- document-review headless output format at document-review SKILL.md lines 219-248
+- Existing autofix and report-only post-review steps at SKILL.md lines 471-483
+- Existing review-output-template.md formatting rules
+
+**Test scenarios:**
+- Happy path: headless mode with safe_auto findings applies fixes and returns structured output listing remaining findings
+- Happy path: headless mode with no actionable findings returns "Applied 0 safe_auto fixes" and the completion signal
+- Happy path: headless mode with mixed findings (safe_auto + gated_auto + manual + advisory) applies safe_auto, returns all others in structured output grouped by autofix_class
+- Edge case: headless mode with only advisory findings returns structured output with no fixes applied
+- Edge case: headless mode with only pre-existing findings separates them into the pre-existing section
+- Integration: headless output includes Verdict line so callers can make merge decisions
+- Integration: run artifact is written under `.context/compound-engineering/ce-review/<run-id>/`
+- Error path: clean review (zero findings) returns the completion signal with no findings sections
+
+**Verification:**
+- SKILL.md has a headless output format section with the structured text envelope
+- review-output-template.md includes headless mode format
+- Post-review flow has a headless branch in Steps 2, 4, and 5
+- No AskUserQuestion or interactive prompts reachable in headless mode
+
+---
+
+- [ ] **Unit 4: Contract Test Extension**
+
+**Goal:** Extend `tests/review-skill-contract.test.ts` to assert headless mode contract invariants.
+
+**Requirements:** R1, R4, R5
+
+**Dependencies:** Units 1-3
+
+**Files:**
+- Modify: `tests/review-skill-contract.test.ts`
+- Test: `tests/review-skill-contract.test.ts`
+
+**Approach:**
+- Add assertions to the existing "documents explicit modes and orchestration boundaries" test for headless mode presence
+- Add a new test case for headless-specific contract invariants: completion signal text, no-checkout-switching guard, artifact behavior, no-todo rule, structured output format presence, conflicting-flags guard
+- Assert `mode:headless` appears in argument-hint and mode detection table
+- Assert headless rules section exists with key behavioral commitments
+
+**Patterns to follow:**
+- Existing contract test structure at `tests/review-skill-contract.test.ts` — string containment assertions against SKILL.md content
+
+**Test scenarios:**
+- Happy path: contract test passes with all headless mode assertions
+- Edge case: if any headless rule text is accidentally removed from SKILL.md, the contract test fails
+
+**Verification:**
+- `bun test tests/review-skill-contract.test.ts` passes
+- Test covers: mode detection, checkout guard, artifact/todo behavior, completion signal, conflicting flags guard
+
+## System-Wide Impact
+
+- **Interaction graph:** No new callbacks or middleware. Headless mode is a new branch in existing mode-dispatch logic. Existing callers (lfg, slfg) are not changed — they continue using autofix and report-only.
+- **Error propagation:** New error paths (conflicting flags, missing scope) emit text errors and stop. No cascading failure risk.
+- **State lifecycle risks:** Headless writes run artifacts but not todos. A caller that expects todos from headless would get none — this is intentional and documented.
+- **API surface parity:** Headless mode is a new API surface for skill-to-skill invocation. Future orchestrators may adopt it, but existing ones are unchanged.
+- **Unchanged invariants:** Stages 3-5 (reviewer selection, sub-agent dispatch, merge/dedup pipeline) are completely unchanged. The findings schema is unchanged. The confidence threshold (0.60) is unchanged.
+
+## Risks & Dependencies
+
+| Risk | Mitigation |
+|------|------------|
+| Headless checkout guard text diverges from report-only over time | Both share the same guard language — mention headless alongside report-only in the same sentences so they stay in sync |
+| Caller assumes headless creates todos and depends on them | Headless rules section explicitly states no todos; contract test asserts it |
+| Structured output format drifts from document-review's envelope | Format is documented in review-output-template.md and tested by contract; changes require deliberate updates |
+
+## Sources & References
+
+- **Origin document:** [docs/brainstorms/2026-03-28-ce-review-headless-mode-requirements.md](docs/brainstorms/2026-03-28-ce-review-headless-mode-requirements.md)
+- Related code: `plugins/compound-engineering/skills/ce-review/SKILL.md`, `plugins/compound-engineering/skills/document-review/SKILL.md`
+- Related PRs: #425 (document-review headless mode)
+- Learnings: `docs/solutions/skill-design/beta-promotion-orchestration-contract.md`, `docs/solutions/skill-design/compound-refresh-skill-improvements.md`, `docs/solutions/skill-design/git-workflow-skills-need-explicit-state-machines.md`