From 9afa056dbeb41ef7d589a266f2ed3f3a2e0ba389 Mon Sep 17 00:00:00 2001 From: Ben Wilson Date: Thu, 23 Apr 2026 16:10:16 -0700 Subject: [PATCH 1/7] feat(ce-compound): add mode:autofix and mode:autofix-full for unattended documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ce-compound had no headless affordance. Its Execution Strategy enforces four mandatory blocking prompts (Full-vs-Lightweight mode selection, session-history opt-in, Discoverability Check consent, post-completion "What's next?" menu), each using the platform's blocking question tool with "Never silently skip" guarantees. This blocked programmatic callers (post-merge hooks, CI, orchestrator pipelines) — the blocking question tool errors in headless sessions and the documented fallback is "present in chat," with no user to respond. The inconsistency was visible against sibling skills in the same plugin: ce-compound-refresh ships mode:autofix, ce-code-review ships mode:autofix/mode:headless/mode:report-only, ce-doc-review ships mode:headless. ce-compound was the lone holdout. This PR adds two mode tokens: - mode:autofix — autofix + Lightweight execution (default headless). Low-cost single-pass capture; overlap drift caught later by ce-compound-refresh. - mode:autofix-full — autofix + Full execution (opt-in thorough). Phase 1 research subagents, overlap-update, Phase 3 specialized reviewers; session-history defaults to off. Mutually exclusive with a conflict error mirroring ce-code-review. All four interactive prompts are guarded in both modes. Discoverability Check becomes a recommendation in the output rather than an instruction- file edit. "What's next?" menu is suppressed. No-op output shape explains which precondition blocked when preconditions aren't met. Learning doc added at docs/solutions/skill-design/compound-skill-improvements.md covers the design decisions (explicit opt-in, Lightweight as default depth, two distinct mode tokens vs nested colons, tokenization rule for the mode:autofix-full prefix ambiguity). Tests: compound-specific (compound-support-files, pipeline-review-contract) 51/51 pass. release:validate clean. Full test suite: same 896/9 as main (the 9 failures are pre-existing in tests/skills/ce-polish-beta-project-type.test.ts, verified by stashing edits and rerunning). --- .../compound-skill-improvements.md | 110 ++++++++++++ .../skills/ce-compound/SKILL.md | 157 +++++++++++++++++- 2 files changed, 264 insertions(+), 3 deletions(-) create mode 100644 docs/solutions/skill-design/compound-skill-improvements.md diff --git a/docs/solutions/skill-design/compound-skill-improvements.md b/docs/solutions/skill-design/compound-skill-improvements.md new file mode 100644 index 000000000..f109d4d7e --- /dev/null +++ b/docs/solutions/skill-design/compound-skill-improvements.md @@ -0,0 +1,110 @@ +--- +title: "ce-compound autofix modes (mode:autofix and mode:autofix-full) for unattended documentation capture" +category: skill-design +date: 2026-04-23 +module: plugins/compound-engineering/skills/ce-compound +component: SKILL.md +tags: + - skill-design + - ce-compound + - autofix-mode + - platform-agnostic + - pipeline-invocation +severity: medium +description: "Add mode:autofix and mode:autofix-full to ce-compound so it can be invoked programmatically (post-merge hooks, CI, orchestrator pipelines) without the four mandatory interactive prompts that normally block unattended runs. mode:autofix routes through the existing Lightweight execution path for low-cost capture at scale; mode:autofix-full routes through Full with prompts guarded for thorough capture when quality matters more than token cost. Mirrors the pattern already established by ce-compound-refresh and ce-code-review, extended with a depth variant so callers can pick fast vs thorough." +related: + - docs/solutions/skill-design/compound-refresh-skill-improvements.md + - plugins/compound-engineering/skills/ce-compound-refresh/SKILL.md + - plugins/compound-engineering/skills/ce-code-review/SKILL.md + - plugins/compound-engineering/skills/ce-doc-review/SKILL.md +--- + +## Problem + +`ce-compound` had no headless affordance. Its Execution Strategy section enforced four mandatory blocking prompts — a Full-vs-Lightweight mode selection, a session-history opt-in (Full only), a Discoverability Check consent question, and a post-completion "What's next?" menu — each requiring the platform's blocking question tool (`AskUserQuestion` / `request_user_input` / `ask_user`) and each explicitly forbidden from silent skips ("Do NOT pre-select a mode. Do NOT skip this prompt."). + +This blocked programmatic callers. A post-merge hook, CI step, or orchestrator pipeline invoking `claude -p "/ce-compound ..."` or `codex exec "Run /ce-compound" --ephemeral` had no way to drive the skill to completion: the blocking question tool errors in headless sessions, the documented fallback is "present options in chat" with "Never silently skip the question," and there is no user to respond. The result was hang, partial execution, or undefined degradation depending on the harness. + +The inconsistency was especially visible against the other compound-engineering skills in the same plugin: + +- `ce-compound-refresh` — ships `mode:autofix` for unattended sweeps. +- `ce-code-review` — ships both `mode:autofix` and `mode:headless` for programmatic review. +- `ce-doc-review` — ships `mode:headless` for pipeline callers. +- `ce-compound` — no mode affordance. + +`ce-compound` is the lone holdout among the high-traffic skills. Pipelines that want to capture learnings after successful work (e.g., a Jira-driven dev orchestrator running `/ce-compound-refresh mode:autofix` post-merge to maintain `docs/solutions/`) are forced to either invoke `ce-compound` interactively (not possible in the pipeline context) or skip new-learning capture entirely. + +A second gap, related but distinct: even a user who knows they want Lightweight execution has **no way to request it via argument**. The Lightweight Mode section exists and is fully specified, but the only entry point is the interactive prompt. There is no `/ce-compound lightweight` or equivalent flag — `$ARGUMENTS` is not parsed for mode hints. Exposing Lightweight through a no-prompt argument benefits both programmatic callers and users who already know what depth they want. + +## Root Cause + +Three independent pressures pushed ce-compound toward interactive-only: + +1. **The mode-selection prompt is load-bearing in interactive mode.** Full mode vs Lightweight mode is a real tradeoff (token cost, overlap-check depth, specialized reviewer dispatch), and upstream correctly wants a human to pick. Past fixes (#460, #620) *tightened* the prompt's enforcement to stop silent skips, not loosen it. +2. **The Discoverability Check can edit project config.** A skill that modifies `AGENTS.md` / `CLAUDE.md` should have consent in interactive mode. The current text carries explicit consent gating for that reason. +3. **The "What's next?" menu is a guided next-step prompt.** It chains to follow-up skills (`ce-compound-refresh`, linking docs, etc.) and assumes a human will pick. + +None of these pressures require interactive-only. A headless caller has different defaults that stay safe: + +1. **Route through an execution path that has no inline prompts.** Lightweight is already this — single-pass, no parallel subagents. Full mode's Phase 1 research subagents and Phase 3 specialized reviewers return text data and do not themselves prompt the user; Full's interactive prompts are all *outside* its execution body (mode-selection, session-history opt-in, Discoverability consent, post-completion menu). So both paths can be made headless-safe by guarding those four external prompts. +2. **Surface Discoverability as a recommendation, not an edit.** Instruction-file edits are project config, not the skill's scope in headless mode. Print the suggested addition in the output and let a human apply it. +3. **Make the output the sole deliverable.** No "What's next?" menu — programmatic callers parse the output; they do not respond to interactive menus. + +## Solution + +Add **two** mode tokens as explicit opt-in arguments. Mirror the pattern established by `ce-compound-refresh` (commit `699f4840`, originally introduced as `mode:autonomous` and later renamed to `mode:autofix` for consistency with `ce-code-review`), and extend it with a depth variant so callers can pick the execution path: + +- **`mode:autofix`** — autofix + Lightweight execution. Default headless mode: cheap, fast, single-pass. No overlap check, no Phase 3 reviewers. Duplicates are caught later by `ce-compound-refresh`. +- **`mode:autofix-full`** — autofix + Full execution. Opt-in thorough headless mode: Phase 1 parallel research, overlap-update behavior, Phase 3 specialized reviewers. Session-history defaults to off (the opt-in is interactive-only). Higher token cost for higher quality capture. + +Mutually exclusive — if both appear in arguments, the skill halts before any subagent dispatch and emits a conflict error mirroring `ce-code-review`'s conflict handling. + +### Edits + +One SKILL.md file, eight targeted edits: + +1. **Frontmatter** — `argument-hint: "[mode:autofix or mode:autofix-full] [brief context]"`. +2. **New `## Mode Detection` section** — placed between Support Files and Execution Strategy. Defines the three-row mode table (Interactive default, Autofix, Autofix-full), the tokenization rule (`mode:autofix-full` is a distinct whole-token match, not a superstring of `mode:autofix`), the conflict rule, shared autofix rules, and per-variant specifics (including `mode:autofix-full`'s session-history-defaults-to-off decision). +3. **Execution Strategy guard** — at the top of the section: `mode:autofix` jumps to Lightweight, `mode:autofix-full` executes Full with prompts guarded per Mode Detection. +4. **Full Mode intro note** — clarifies that Full is used both by the interactive Full path and by `mode:autofix-full`, and that the Phase 1/Phase 3 subagents run unchanged because they don't prompt the user. +5. **Session-history follow-up note** — extended to cover both autofix variants: `mode:autofix` routes through Lightweight and never reaches the prompt; `mode:autofix-full` defaults session-history to off without a prompt. +6. **Discoverability Check step 4c** — add the autofix branch: "In both autofix modes (`mode:autofix` and `mode:autofix-full`), include it as a `Discoverability recommendation` line in the output — do not attempt to edit instruction files (autofix scope is doc capture, not project config)." +7. **Lightweight Mode intro** — note that this path is the execution target for `mode:autofix` specifically, and that `mode:autofix-full` uses Full Mode instead. +8. **Success Output "What's next?" guard + new `### Autofix mode output` subsection** — explicit "In both autofix modes, do NOT present the 'What's next?' prompt" plus four machine-parseable output shapes distinguished by their first line: (a) `✓ Documentation complete (mode:autofix)` — Lightweight doc-written; (b) `✓ Documentation complete (mode:autofix-full)` — Full new doc written; (c) `✓ Documentation updated (mode:autofix-full)` — Full overlap-update path; (d) `✓ No documentation written (autofix mode)` — preconditions failed. + +### Design decisions + +Six decisions, each paralleling a deliberate choice in compound-refresh's PR (#260 / commit `699f4840`) or in `ce-code-review`'s existing multi-mode grammar: + +- **Explicit opt-in only.** Both `mode:autofix` and `mode:autofix-full` must appear in arguments. Auto-detection based on question-tool availability is explicitly rejected — a user in an interactive agent without a blocking-question tool (e.g., some harness variants) is still interactive; they just use plain-text replies. Headless is an invocation-context property, not a tool-availability property. +- **Lightweight is the default headless depth.** `mode:autofix` alone routes through Lightweight. Rationale: the most common headless invocation is a post-merge or CI hook firing on every successful work unit; cost matters more than cross-referencing for that use case. Callers who want thorough capture can opt in with `mode:autofix-full`. This also reuses Lightweight's existing "overlap-drift is acceptable, compound-refresh catches it later" contract. +- **Two distinct mode tokens, not a sub-mode.** Follows `ce-code-review`'s precedent of multiple distinct `mode:` tokens (`mode:autofix`, `mode:report-only`, `mode:headless`) rather than a nested `mode:autofix:full` sub-syntax. Parsing stays consistent with the rest of the plugin. Whole-token match handles the `mode:autofix` prefix-of-`mode:autofix-full` ambiguity cleanly. +- **Mutually exclusive with conflict error.** Two autofix modes cannot be combined. If both appear, halt before subagent dispatch and emit a conflict error mirroring `ce-code-review`'s format. Prevents callers from specifying contradictory intent silently. +- **`mode:autofix-full` defaults session-history to off.** The session-history opt-in is a user-preference question — there is no safe default without a user to ask. Off is the conservative default: it's cheaper (no Session Historian dispatch), it's predictable (no cross-session effects on the output), and callers that want session history can invoke interactively or pass curated context. Documented explicitly in the `mode:autofix-full` rules section. +- **Discoverability Check becomes a recommendation, not an edit.** Instruction files are project config outside the skill's doc-capture scope. In both autofix modes, print the suggested addition in the output; let a human apply it. +- **Conservative no-op path (both modes).** Autofix callers may invoke on any successful run regardless of whether something substantive was solved. The advisory Preconditions (`problem_solved`, `solution_verified`, `non_trivial`) become actionable in autofix mode: if they fail, emit a no-op output explaining which precondition blocked and what context was considered, rather than writing a low-quality doc. The `Mode:` line distinguishes which variant triggered the no-op for caller diagnostics. + +## Prevention + +### Consistency checklist for multi-mode skills + +When any one skill in the plugin gains a `mode:autofix` / `mode:headless` / `mode:report-only` affordance, every sibling skill in its workflow neighborhood should be reviewed for the same affordance. Callers compose these skills (`ce-work` invokes `ce-code-review mode:autofix`; `adv:jira-*` pipelines invoke `ce-compound-refresh mode:autofix`), and a single gap forces callers to either abandon the automation or shadow-maintain the missing skill's logic. + +### Anti-patterns worth naming + +| Anti-pattern | Better pattern | +|---|---| +| Interactive-only skill in a workflow neighborhood where siblings have autofix | Add an explicit opt-in autofix mode that routes through an existing no-prompt execution path | +| Auto-detecting "no question tool = headless" | Explicit `mode:autofix` argument — invocation context is not the same as tool availability | +| Autofix writes to project config (AGENTS.md / CLAUDE.md) without consent | In autofix mode, surface config suggestions as recommendations in the output; let humans apply | +| Post-completion "What's next?" prompt that blocks autofix callers | Guard the prompt with a mode check; the output is the sole deliverable in autofix | +| Silent degradation when a blocking prompt errors in headless | Detect mode up front, route to a no-prompt path; never rely on fallback-in-chat for headless | +| Single-depth autofix when the skill already has two depth variants | Expose each variant via a distinct mode token with a documented conflict rule (see `ce-code-review`'s `mode:autofix` / `mode:report-only` / `mode:headless` grammar) | +| Nested colon sub-modes (`mode:autofix:full`) when the rest of the plugin uses distinct whole-token modes | Use distinct tokens with a whole-token tokenization rule to avoid prefix ambiguity (`mode:autofix` vs `mode:autofix-full`) | + +## Cross-References + +- `docs/solutions/skill-design/compound-refresh-skill-improvements.md` — the precedent autofix addition for `ce-compound-refresh`, including the "explicit opt-in only" design rationale. +- Commit `699f4840 feat(skills): add autonomous mode to ce:compound-refresh` — original autonomous-mode introduction (later renamed to autofix for consistency). +- `ce-code-review` SKILL.md — the canonical template for `mode:autofix` and `mode:headless` coexistence. +- `ce-doc-review` SKILL.md — the canonical template for `mode:headless` in pipeline invocations. diff --git a/plugins/compound-engineering/skills/ce-compound/SKILL.md b/plugins/compound-engineering/skills/ce-compound/SKILL.md index 9809d8aa7..09f4a1140 100644 --- a/plugins/compound-engineering/skills/ce-compound/SKILL.md +++ b/plugins/compound-engineering/skills/ce-compound/SKILL.md @@ -1,6 +1,7 @@ --- name: ce-compound description: Document a recently solved problem to compound your team's knowledge +argument-hint: "[mode:autofix or mode:autofix-full] [brief context]" --- # /ce-compound @@ -30,8 +31,56 @@ These files are the durable contract for the workflow. Read them on-demand at th When spawning subagents, pass the relevant file contents into the task prompt so they have the contract without needing cross-skill paths. +## Mode Detection + +Tokenize `$ARGUMENTS` by whitespace and match recognized mode tokens exactly (so `mode:autofix-full` is a distinct token from `mode:autofix`). Strip the matched token from arguments; treat the remainder as the brief context hint. + +| Mode | Token | Execution path | Prompts | +|------|-------|----------------|---------| +| **Interactive** (default) | (none) | User picks Full or Lightweight at the Execution Strategy prompt | All interactive prompts per the documented flow | +| **Autofix** | `mode:autofix` | Lightweight Mode (single-pass, no subagents, no overlap check) | None — all four interactive prompts skipped | +| **Autofix-full** | `mode:autofix-full` | Full Mode (Phase 1 parallel research, overlap-update, Phase 3 specialized reviewers) | None — session-history defaults to off; Discoverability becomes a recommendation; "What's next?" suppressed | + +**Conflicting mode flags.** If both `mode:autofix` and `mode:autofix-full` appear in arguments, stop before any subagent dispatch and emit: `ce-compound failed. Reason: conflicting mode flags — mode:autofix and mode:autofix-full cannot be combined.` This mirrors the conflict handling in `ce-code-review`. + +### Shared autofix rules (both `mode:autofix` and `mode:autofix-full`) + +- **Skip all user questions.** Never pause for input — the mode-selection prompt, Discoverability Check consent, and "What's next?" menu are all suppressed. `mode:autofix-full` additionally skips the session-history opt-in (defaults to off — see below). +- **Do not edit instruction files.** The Discoverability Check (AGENTS.md / CLAUDE.md edit) requires user consent. In both autofix modes, surface the gap as a `Discoverability recommendation` line in the output and move on. +- **Be conservative about writing.** Respect the advisory Preconditions (`problem_solved`, `solution_verified`, `non_trivial`). If the conversation and context hint do not evidence a substantive, verified fix, do **not** write a doc — emit the no-op autofix output (see **Autofix mode output** under Success Output) explaining what was missing. +- **Always print the full output block.** The success output (or the no-op autofix output when no doc is warranted) is the sole deliverable since no user is present to follow up. + +### `mode:autofix` (default headless) + +Routes through the **Lightweight Mode** execution path (see the Lightweight Mode section below). Single-pass, no Phase 1 parallel subagents, no overlap check, no Phase 3 specialized reviewers. Overlap drift is accepted and caught later by `ce-compound-refresh`. + +Use when: +- The caller wants low-cost, low-latency learning capture at scale (post-merge hooks, CI). +- Fresh problem-solving context is present; cross-referencing existing docs is not a requirement for this run. + +### `mode:autofix-full` (opt-in thorough headless) + +Routes through the **Full Mode** execution path — Phase 1 parallel research subagents, overlap-update behavior, Phase 3 specialized reviewers — with the interactive prompts guarded: + +- **Mode-selection prompt** → skipped (Full is already chosen by the caller). +- **Session-history opt-in** → defaults to **off**. The opt-in is interactive-only; autofix cannot decide between sessions-yes and sessions-no without a user, so the conservative default is off (no Session Historian dispatch). A caller that wants session history included must invoke the skill interactively or run session analysis separately and pass the findings as context. +- **Discoverability Check consent** → surfaced as a recommendation in the output, per the shared rule above. +- **"What's next?" menu** → skipped, per the shared rule above. + +Phase 1 research subagents (Context Analyzer, Solution Extractor, Related Docs Finder) and Phase 3 specialized reviewers (`ce-performance-oracle`, `ce-security-sentinel`, etc.) run as usual in `mode:autofix-full` — they return text data to the orchestrator and do not themselves prompt the user. + +Use when: +- The caller wants thorough capture with overlap-update (so duplicates fold into existing docs rather than create fresh ones), cross-referencing to related docs, and specialized-reviewer validation of the written doc. +- The token cost of a Full-mode run is acceptable for the quality gain. + ## Execution Strategy +**Autofix modes:** Skip this entire section. +- `mode:autofix` → jump directly to the Lightweight Mode execution path below. +- `mode:autofix-full` → execute Full Mode below with the interactive prompts guarded per the Mode Detection section. + +**Interactive mode** (default): + Present the user with two options before proceeding, using the platform's blocking question tool: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_user` in Gemini, `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to presenting options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. ``` @@ -55,16 +104,18 @@ for relevant knowledge to help the Compound process? This adds time and token usage. ``` -If the user says yes, dispatch the Session Historian in Phase 1. If no, skip it. Do not ask this in lightweight mode. +If the user says yes, dispatch the Session Historian in Phase 1. If no, skip it. Do not ask this in lightweight mode, in `mode:autofix` (which routes through Lightweight and never reaches this prompt), or in `mode:autofix-full` (which defaults session-history to off without a prompt — see Mode Detection). --- ### Full Mode +Used by Interactive mode when the user picks Full, and by `mode:autofix-full` with interactive prompts guarded per Mode Detection (mode-selection, session-history opt-in, Discoverability consent, and "What's next?" menu are all suppressed in `mode:autofix-full`; the Phase 1 subagents and Phase 3 reviewers run unchanged since they return text data and do not themselves prompt the user). + **The primary output is ONE file - the final documentation.** -Phase 1 subagents return TEXT DATA to the orchestrator. They must NOT use Write, Edit, or create any files. Only the orchestrator writes files: the solution doc in Phase 2, and — if the Discoverability Check finds a gap — a small edit to a project instruction file (AGENTS.md or CLAUDE.md). The instruction-file edit is maintenance, not a second deliverable; it ensures future agents can discover the knowledge store. +Phase 1 subagents return TEXT DATA to the orchestrator. They must NOT use Write, Edit, or create any files. Only the orchestrator writes files: the solution doc in Phase 2, and — if the Discoverability Check finds a gap and the run is in full interactive mode — a small edit to a project instruction file (AGENTS.md or CLAUDE.md). In `mode:autofix-full` the instruction-file edit is never written; the gap is surfaced as a Discoverability recommendation in the output instead. ### Phase 0.5: Auto Memory Scan @@ -304,7 +355,7 @@ After the learning is written and the refresh decision is made, check whether th `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. ``` - c. In full mode, explain to the user why this matters — agents working in this repo (including fresh sessions, other tools, or collaborators without the plugin) won't know to check `docs/solutions/` unless the instruction file surfaces it. Show the proposed change and where it would go, then use the platform's blocking question tool to get consent before making the edit: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_user` in Gemini, `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to presenting the proposal in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. In lightweight mode, output a one-liner note and move on + c. In full mode, explain to the user why this matters — agents working in this repo (including fresh sessions, other tools, or collaborators without the plugin) won't know to check `docs/solutions/` unless the instruction file surfaces it. Show the proposed change and where it would go, then use the platform's blocking question tool to get consent before making the edit: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_user` in Gemini, `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to presenting the proposal in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. In lightweight mode, output a one-liner note and move on. In both autofix modes (`mode:autofix` and `mode:autofix-full`), include it as a `Discoverability recommendation` line in the output — do not attempt to edit instruction files (autofix scope is doc capture, not project config). ### Phase 3: Optional Enhancement @@ -333,6 +384,8 @@ Based on problem type, optionally invoke specialized agents to review the docume **Single-pass alternative — same documentation, fewer tokens.** This mode skips parallel subagents entirely. The orchestrator performs all work in a single pass, producing the same solution document without cross-referencing or duplicate detection. + +**This path is also the execution target for `mode:autofix`** (see Mode Detection). `mode:autofix` adds no-prompt guardrails on top of Lightweight — the execution steps below are identical, but autofix uses a dedicated output block (see **Autofix mode output** under Success Output) so callers can parse the result programmatically. `mode:autofix-full` uses the Full Mode execution path instead, not this one. The orchestrator (main conversation) performs ALL of the following in one sequential pass: @@ -462,6 +515,104 @@ What's next? **After displaying the success output, present the "What's next?" options using the platform's blocking question tool:** `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_user` in Gemini, `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to numbered options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. Do not continue the workflow or end the turn without the user's selection. +**In both autofix modes (`mode:autofix` and `mode:autofix-full`), do NOT present the "What's next?" prompt.** The success output (or the no-op autofix output below) is the sole deliverable. End the turn cleanly after printing it — autofix callers parse the output programmatically and do not respond to interactive menus. + +### Autofix mode output + +In both autofix modes the output is the sole deliverable since no user is present to follow up. Print the full block — do not abbreviate, summarize, or skip sections. All output shapes below are machine-parseable: callers detect which shape was emitted by the first line (`✓ Documentation complete (mode:autofix)`, `✓ Documentation complete (mode:autofix-full)`, `✓ Documentation updated (mode:autofix-full)`, or `✓ No documentation written (autofix mode)`) and extract the file path from the `File created:` or `File updated:` block. + +**`mode:autofix` — doc written** (Lightweight path, preconditions met): + +``` +✓ Documentation complete (mode:autofix) + +File created: +- docs/solutions/[category]/[filename].md + +Track: [bug|knowledge] +Category: [category]/ + +[If a specific older doc in docs/solutions/ looks stale given this new learning:] +Refresh candidate: docs/solutions/[path/to/stale-doc].md + Reason: [one-line rationale — contradicts new fix, superseded, etc.] + Follow-up: /ce-compound-refresh mode:autofix [scope hint] + +[If discoverability check found instruction files don't surface the knowledge store:] +Discoverability recommendation: AGENTS.md/CLAUDE.md does not surface docs/solutions/ + Suggested addition: [one-liner or small section — do NOT apply the edit in autofix mode] + +Note: mode:autofix runs the Lightweight path (no overlap check against existing docs). +ce-compound-refresh will catch duplicates on its next sweep. +``` + +**`mode:autofix-full` — new doc written** (Full path, preconditions met, overlap low): + +``` +✓ Documentation complete (mode:autofix-full) + +File created: +- docs/solutions/[category]/[filename].md + +Track: [bug|knowledge] +Category: [category]/ + +Phase 1 subagents: + - Context Analyzer: [one-line summary] + - Solution Extractor: [one-line summary] + - Related Docs Finder: overlap=[low|moderate|none], refresh_candidates=[count] + - Session Historian: off (mode:autofix-full default) + +Phase 3 specialized reviewers: + - [each agent invoked and its one-line verdict, or "none applicable"] + +[If overlap was moderate — Phase 2.5 flagged consolidation review:] +Refresh candidate: docs/solutions/[path/to/overlapping-doc].md + Reason: [moderate overlap — same area, different angle/root cause/solution] + Follow-up: /ce-compound-refresh mode:autofix [scope hint] + +[If discoverability check found instruction files don't surface the knowledge store:] +Discoverability recommendation: AGENTS.md/CLAUDE.md does not surface docs/solutions/ + Suggested addition: [one-liner or small section — do NOT apply the edit in autofix mode] +``` + +**`mode:autofix-full` — existing doc updated** (Full path, preconditions met, overlap high — updated existing doc per Phase 2 overlap rule): + +``` +✓ Documentation updated (mode:autofix-full) + +Overlap detected: docs/solutions/[category]/[existing-filename].md + Matched dimensions: [problem statement, root cause, solution, referenced files, prevention] + +File updated: +- docs/solutions/[category]/[existing-filename].md (added last_updated: YYYY-MM-DD) + +Phase 1 subagents: + - [same four lines as the new-doc shape] + +Phase 3 specialized reviewers: + - [same as the new-doc shape] + +[Discoverability recommendation block, same as new-doc shape, if applicable] +``` + +**Either autofix mode — no doc written** (preconditions not met — trivial fix, unverified solution, or nothing substantive in context): + +``` +✓ No documentation written (autofix mode) + +Mode: [mode:autofix|mode:autofix-full] + +Reason: [which precondition failed — e.g., "non_trivial check: change was a one-character typo" + or "solution_verified: no verification evidence in conversation or context hint" + or "problem_solved: solution still in progress"] + +Context considered: +- [one-line summary of what was available — e.g., "brief context hint: ''", + "recent commits on branch: 3", "conversation history: empty"] + +No action required. A human can invoke /ce-compound interactively if this was a misjudgment. +``` + **Alternate output (when updating an existing doc due to high overlap):** ``` From 75b8a72834842127974017ca49c96aa0dffba542 Mon Sep 17 00:00:00 2001 From: Ben Wilson Date: Thu, 23 Apr 2026 16:22:01 -0700 Subject: [PATCH 2/7] fix(ce-compound): suppress Phase 2.5 refresh prompt in autofix modes Phase 2.5's multi-candidate branch unconditionally asked the user whether to run a targeted refresh, which would block unattended mode:autofix-full runs (mode:autofix already dodged it via the lightweight rule, but the guard was implicit). Add an explicit autofix guard: recommend ce-compound-refresh via the Follow-up line instead of prompting, and enumerate this prompt in the shared autofix skip list. Co-Authored-By: Claude Opus 4.7 (1M context) --- plugins/compound-engineering/skills/ce-compound/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/compound-engineering/skills/ce-compound/SKILL.md b/plugins/compound-engineering/skills/ce-compound/SKILL.md index 09f4a1140..7374a8d96 100644 --- a/plugins/compound-engineering/skills/ce-compound/SKILL.md +++ b/plugins/compound-engineering/skills/ce-compound/SKILL.md @@ -45,7 +45,7 @@ Tokenize `$ARGUMENTS` by whitespace and match recognized mode tokens exactly (so ### Shared autofix rules (both `mode:autofix` and `mode:autofix-full`) -- **Skip all user questions.** Never pause for input — the mode-selection prompt, Discoverability Check consent, and "What's next?" menu are all suppressed. `mode:autofix-full` additionally skips the session-history opt-in (defaults to off — see below). +- **Skip all user questions.** Never pause for input — the mode-selection prompt, the Phase 2.5 selective-refresh prompt (multi-candidate case), Discoverability Check consent, and "What's next?" menu are all suppressed. `mode:autofix-full` additionally skips the session-history opt-in (defaults to off — see below). - **Do not edit instruction files.** The Discoverability Check (AGENTS.md / CLAUDE.md edit) requires user consent. In both autofix modes, surface the gap as a `Discoverability recommendation` line in the output and move on. - **Be conservative about writing.** Respect the advisory Preconditions (`problem_solved`, `solution_verified`, `non_trivial`). If the conversation and context hint do not evidence a substantive, verified fix, do **not** write a doc — emit the no-op autofix output (see **Autofix mode output** under Success Output) explaining what was missing. - **Always print the full output block.** The success output (or the no-op autofix output when no doc is warranted) is the sole deliverable since no user is present to follow up. @@ -300,7 +300,7 @@ It does **not** make sense to invoke `ce-compound-refresh` when: Use these rules: - If there is **one obvious stale candidate**, invoke `ce-compound-refresh` with a narrow scope hint after the new learning is written -- If there are **multiple candidates in the same area**, ask the user whether to run a targeted refresh for that module, category, or pattern set +- If there are **multiple candidates in the same area**, ask the user whether to run a targeted refresh for that module, category, or pattern set. In both autofix modes (`mode:autofix` and `mode:autofix-full`), do not ask — recommend `ce-compound-refresh` via the `Follow-up` line in the output with the broadest useful scope (module, category, or pattern set) and move on. - If context is already tight or you are in lightweight mode, do not expand into a broad refresh automatically; instead recommend `ce-compound-refresh` as the next step with a scope hint When invoking or recommending `ce-compound-refresh`, be explicit about the argument to pass. Prefer the narrowest useful scope: From 198859405303a70973a3623838e76b4fb06be8d7 Mon Sep 17 00:00:00 2001 From: Ben Wilson Date: Fri, 24 Apr 2026 15:13:38 -0700 Subject: [PATCH 3/7] feat(ce-compound)!: orthogonal mode:autofix + depth grammar, shrink SKILL.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Responds to @tmchow's PR 662 review. Replaces `mode:autofix` / `mode:autofix-full` with orthogonal `mode:autofix` + optional `depth:lightweight|full|thorough` (default `lightweight`). Collapses Mode Detection to sibling shape (one table + one rules block, 23 lines). Consolidates four ~90-line output templates into one parameterized success template + one short no-op template. Cuts runtime-neutral rationale flagged in review (per-variant Use-when bullets, subagent- safety paragraph, Note: in the output template, parser-contract paragraph). Moves the parser-facing contract to a new reference file not loaded at runtime. Deletes docs/solutions/skill-design/compound- skill-improvements.md — it does not meet the docs/solutions/ institutional-memory bar. BREAKING CHANGE: removes `mode:autofix-full`. Callers must use `mode:autofix depth:full` (full path, session history off) or `mode:autofix depth:thorough` (full path, session history on). No alias or migration shim — the token was introduced in this PR and has no merged users. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../compound-skill-improvements.md | 110 -------------- .../skills/ce-compound/SKILL.md | 143 ++++++------------ .../autofix-output-parse-contract.md | 47 ++++++ 3 files changed, 91 insertions(+), 209 deletions(-) delete mode 100644 docs/solutions/skill-design/compound-skill-improvements.md create mode 100644 plugins/compound-engineering/skills/ce-compound/references/autofix-output-parse-contract.md diff --git a/docs/solutions/skill-design/compound-skill-improvements.md b/docs/solutions/skill-design/compound-skill-improvements.md deleted file mode 100644 index f109d4d7e..000000000 --- a/docs/solutions/skill-design/compound-skill-improvements.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: "ce-compound autofix modes (mode:autofix and mode:autofix-full) for unattended documentation capture" -category: skill-design -date: 2026-04-23 -module: plugins/compound-engineering/skills/ce-compound -component: SKILL.md -tags: - - skill-design - - ce-compound - - autofix-mode - - platform-agnostic - - pipeline-invocation -severity: medium -description: "Add mode:autofix and mode:autofix-full to ce-compound so it can be invoked programmatically (post-merge hooks, CI, orchestrator pipelines) without the four mandatory interactive prompts that normally block unattended runs. mode:autofix routes through the existing Lightweight execution path for low-cost capture at scale; mode:autofix-full routes through Full with prompts guarded for thorough capture when quality matters more than token cost. Mirrors the pattern already established by ce-compound-refresh and ce-code-review, extended with a depth variant so callers can pick fast vs thorough." -related: - - docs/solutions/skill-design/compound-refresh-skill-improvements.md - - plugins/compound-engineering/skills/ce-compound-refresh/SKILL.md - - plugins/compound-engineering/skills/ce-code-review/SKILL.md - - plugins/compound-engineering/skills/ce-doc-review/SKILL.md ---- - -## Problem - -`ce-compound` had no headless affordance. Its Execution Strategy section enforced four mandatory blocking prompts — a Full-vs-Lightweight mode selection, a session-history opt-in (Full only), a Discoverability Check consent question, and a post-completion "What's next?" menu — each requiring the platform's blocking question tool (`AskUserQuestion` / `request_user_input` / `ask_user`) and each explicitly forbidden from silent skips ("Do NOT pre-select a mode. Do NOT skip this prompt."). - -This blocked programmatic callers. A post-merge hook, CI step, or orchestrator pipeline invoking `claude -p "/ce-compound ..."` or `codex exec "Run /ce-compound" --ephemeral` had no way to drive the skill to completion: the blocking question tool errors in headless sessions, the documented fallback is "present options in chat" with "Never silently skip the question," and there is no user to respond. The result was hang, partial execution, or undefined degradation depending on the harness. - -The inconsistency was especially visible against the other compound-engineering skills in the same plugin: - -- `ce-compound-refresh` — ships `mode:autofix` for unattended sweeps. -- `ce-code-review` — ships both `mode:autofix` and `mode:headless` for programmatic review. -- `ce-doc-review` — ships `mode:headless` for pipeline callers. -- `ce-compound` — no mode affordance. - -`ce-compound` is the lone holdout among the high-traffic skills. Pipelines that want to capture learnings after successful work (e.g., a Jira-driven dev orchestrator running `/ce-compound-refresh mode:autofix` post-merge to maintain `docs/solutions/`) are forced to either invoke `ce-compound` interactively (not possible in the pipeline context) or skip new-learning capture entirely. - -A second gap, related but distinct: even a user who knows they want Lightweight execution has **no way to request it via argument**. The Lightweight Mode section exists and is fully specified, but the only entry point is the interactive prompt. There is no `/ce-compound lightweight` or equivalent flag — `$ARGUMENTS` is not parsed for mode hints. Exposing Lightweight through a no-prompt argument benefits both programmatic callers and users who already know what depth they want. - -## Root Cause - -Three independent pressures pushed ce-compound toward interactive-only: - -1. **The mode-selection prompt is load-bearing in interactive mode.** Full mode vs Lightweight mode is a real tradeoff (token cost, overlap-check depth, specialized reviewer dispatch), and upstream correctly wants a human to pick. Past fixes (#460, #620) *tightened* the prompt's enforcement to stop silent skips, not loosen it. -2. **The Discoverability Check can edit project config.** A skill that modifies `AGENTS.md` / `CLAUDE.md` should have consent in interactive mode. The current text carries explicit consent gating for that reason. -3. **The "What's next?" menu is a guided next-step prompt.** It chains to follow-up skills (`ce-compound-refresh`, linking docs, etc.) and assumes a human will pick. - -None of these pressures require interactive-only. A headless caller has different defaults that stay safe: - -1. **Route through an execution path that has no inline prompts.** Lightweight is already this — single-pass, no parallel subagents. Full mode's Phase 1 research subagents and Phase 3 specialized reviewers return text data and do not themselves prompt the user; Full's interactive prompts are all *outside* its execution body (mode-selection, session-history opt-in, Discoverability consent, post-completion menu). So both paths can be made headless-safe by guarding those four external prompts. -2. **Surface Discoverability as a recommendation, not an edit.** Instruction-file edits are project config, not the skill's scope in headless mode. Print the suggested addition in the output and let a human apply it. -3. **Make the output the sole deliverable.** No "What's next?" menu — programmatic callers parse the output; they do not respond to interactive menus. - -## Solution - -Add **two** mode tokens as explicit opt-in arguments. Mirror the pattern established by `ce-compound-refresh` (commit `699f4840`, originally introduced as `mode:autonomous` and later renamed to `mode:autofix` for consistency with `ce-code-review`), and extend it with a depth variant so callers can pick the execution path: - -- **`mode:autofix`** — autofix + Lightweight execution. Default headless mode: cheap, fast, single-pass. No overlap check, no Phase 3 reviewers. Duplicates are caught later by `ce-compound-refresh`. -- **`mode:autofix-full`** — autofix + Full execution. Opt-in thorough headless mode: Phase 1 parallel research, overlap-update behavior, Phase 3 specialized reviewers. Session-history defaults to off (the opt-in is interactive-only). Higher token cost for higher quality capture. - -Mutually exclusive — if both appear in arguments, the skill halts before any subagent dispatch and emits a conflict error mirroring `ce-code-review`'s conflict handling. - -### Edits - -One SKILL.md file, eight targeted edits: - -1. **Frontmatter** — `argument-hint: "[mode:autofix or mode:autofix-full] [brief context]"`. -2. **New `## Mode Detection` section** — placed between Support Files and Execution Strategy. Defines the three-row mode table (Interactive default, Autofix, Autofix-full), the tokenization rule (`mode:autofix-full` is a distinct whole-token match, not a superstring of `mode:autofix`), the conflict rule, shared autofix rules, and per-variant specifics (including `mode:autofix-full`'s session-history-defaults-to-off decision). -3. **Execution Strategy guard** — at the top of the section: `mode:autofix` jumps to Lightweight, `mode:autofix-full` executes Full with prompts guarded per Mode Detection. -4. **Full Mode intro note** — clarifies that Full is used both by the interactive Full path and by `mode:autofix-full`, and that the Phase 1/Phase 3 subagents run unchanged because they don't prompt the user. -5. **Session-history follow-up note** — extended to cover both autofix variants: `mode:autofix` routes through Lightweight and never reaches the prompt; `mode:autofix-full` defaults session-history to off without a prompt. -6. **Discoverability Check step 4c** — add the autofix branch: "In both autofix modes (`mode:autofix` and `mode:autofix-full`), include it as a `Discoverability recommendation` line in the output — do not attempt to edit instruction files (autofix scope is doc capture, not project config)." -7. **Lightweight Mode intro** — note that this path is the execution target for `mode:autofix` specifically, and that `mode:autofix-full` uses Full Mode instead. -8. **Success Output "What's next?" guard + new `### Autofix mode output` subsection** — explicit "In both autofix modes, do NOT present the 'What's next?' prompt" plus four machine-parseable output shapes distinguished by their first line: (a) `✓ Documentation complete (mode:autofix)` — Lightweight doc-written; (b) `✓ Documentation complete (mode:autofix-full)` — Full new doc written; (c) `✓ Documentation updated (mode:autofix-full)` — Full overlap-update path; (d) `✓ No documentation written (autofix mode)` — preconditions failed. - -### Design decisions - -Six decisions, each paralleling a deliberate choice in compound-refresh's PR (#260 / commit `699f4840`) or in `ce-code-review`'s existing multi-mode grammar: - -- **Explicit opt-in only.** Both `mode:autofix` and `mode:autofix-full` must appear in arguments. Auto-detection based on question-tool availability is explicitly rejected — a user in an interactive agent without a blocking-question tool (e.g., some harness variants) is still interactive; they just use plain-text replies. Headless is an invocation-context property, not a tool-availability property. -- **Lightweight is the default headless depth.** `mode:autofix` alone routes through Lightweight. Rationale: the most common headless invocation is a post-merge or CI hook firing on every successful work unit; cost matters more than cross-referencing for that use case. Callers who want thorough capture can opt in with `mode:autofix-full`. This also reuses Lightweight's existing "overlap-drift is acceptable, compound-refresh catches it later" contract. -- **Two distinct mode tokens, not a sub-mode.** Follows `ce-code-review`'s precedent of multiple distinct `mode:` tokens (`mode:autofix`, `mode:report-only`, `mode:headless`) rather than a nested `mode:autofix:full` sub-syntax. Parsing stays consistent with the rest of the plugin. Whole-token match handles the `mode:autofix` prefix-of-`mode:autofix-full` ambiguity cleanly. -- **Mutually exclusive with conflict error.** Two autofix modes cannot be combined. If both appear, halt before subagent dispatch and emit a conflict error mirroring `ce-code-review`'s format. Prevents callers from specifying contradictory intent silently. -- **`mode:autofix-full` defaults session-history to off.** The session-history opt-in is a user-preference question — there is no safe default without a user to ask. Off is the conservative default: it's cheaper (no Session Historian dispatch), it's predictable (no cross-session effects on the output), and callers that want session history can invoke interactively or pass curated context. Documented explicitly in the `mode:autofix-full` rules section. -- **Discoverability Check becomes a recommendation, not an edit.** Instruction files are project config outside the skill's doc-capture scope. In both autofix modes, print the suggested addition in the output; let a human apply it. -- **Conservative no-op path (both modes).** Autofix callers may invoke on any successful run regardless of whether something substantive was solved. The advisory Preconditions (`problem_solved`, `solution_verified`, `non_trivial`) become actionable in autofix mode: if they fail, emit a no-op output explaining which precondition blocked and what context was considered, rather than writing a low-quality doc. The `Mode:` line distinguishes which variant triggered the no-op for caller diagnostics. - -## Prevention - -### Consistency checklist for multi-mode skills - -When any one skill in the plugin gains a `mode:autofix` / `mode:headless` / `mode:report-only` affordance, every sibling skill in its workflow neighborhood should be reviewed for the same affordance. Callers compose these skills (`ce-work` invokes `ce-code-review mode:autofix`; `adv:jira-*` pipelines invoke `ce-compound-refresh mode:autofix`), and a single gap forces callers to either abandon the automation or shadow-maintain the missing skill's logic. - -### Anti-patterns worth naming - -| Anti-pattern | Better pattern | -|---|---| -| Interactive-only skill in a workflow neighborhood where siblings have autofix | Add an explicit opt-in autofix mode that routes through an existing no-prompt execution path | -| Auto-detecting "no question tool = headless" | Explicit `mode:autofix` argument — invocation context is not the same as tool availability | -| Autofix writes to project config (AGENTS.md / CLAUDE.md) without consent | In autofix mode, surface config suggestions as recommendations in the output; let humans apply | -| Post-completion "What's next?" prompt that blocks autofix callers | Guard the prompt with a mode check; the output is the sole deliverable in autofix | -| Silent degradation when a blocking prompt errors in headless | Detect mode up front, route to a no-prompt path; never rely on fallback-in-chat for headless | -| Single-depth autofix when the skill already has two depth variants | Expose each variant via a distinct mode token with a documented conflict rule (see `ce-code-review`'s `mode:autofix` / `mode:report-only` / `mode:headless` grammar) | -| Nested colon sub-modes (`mode:autofix:full`) when the rest of the plugin uses distinct whole-token modes | Use distinct tokens with a whole-token tokenization rule to avoid prefix ambiguity (`mode:autofix` vs `mode:autofix-full`) | - -## Cross-References - -- `docs/solutions/skill-design/compound-refresh-skill-improvements.md` — the precedent autofix addition for `ce-compound-refresh`, including the "explicit opt-in only" design rationale. -- Commit `699f4840 feat(skills): add autonomous mode to ce:compound-refresh` — original autonomous-mode introduction (later renamed to autofix for consistency). -- `ce-code-review` SKILL.md — the canonical template for `mode:autofix` and `mode:headless` coexistence. -- `ce-doc-review` SKILL.md — the canonical template for `mode:headless` in pipeline invocations. diff --git a/plugins/compound-engineering/skills/ce-compound/SKILL.md b/plugins/compound-engineering/skills/ce-compound/SKILL.md index 7374a8d96..d7e9083a9 100644 --- a/plugins/compound-engineering/skills/ce-compound/SKILL.md +++ b/plugins/compound-engineering/skills/ce-compound/SKILL.md @@ -1,7 +1,7 @@ --- name: ce-compound description: Document a recently solved problem to compound your team's knowledge -argument-hint: "[mode:autofix or mode:autofix-full] [brief context]" +argument-hint: "[mode:autofix] [depth:lightweight|full|thorough] [brief context]" --- # /ce-compound @@ -33,51 +33,33 @@ When spawning subagents, pass the relevant file contents into the task prompt so ## Mode Detection -Tokenize `$ARGUMENTS` by whitespace and match recognized mode tokens exactly (so `mode:autofix-full` is a distinct token from `mode:autofix`). Strip the matched token from arguments; treat the remainder as the brief context hint. +Parse `$ARGUMENTS` for `mode:autofix` and an optional `depth:` token. Strip matched tokens; treat the remainder as the brief context hint. -| Mode | Token | Execution path | Prompts | -|------|-------|----------------|---------| -| **Interactive** (default) | (none) | User picks Full or Lightweight at the Execution Strategy prompt | All interactive prompts per the documented flow | -| **Autofix** | `mode:autofix` | Lightweight Mode (single-pass, no subagents, no overlap check) | None — all four interactive prompts skipped | -| **Autofix-full** | `mode:autofix-full` | Full Mode (Phase 1 parallel research, overlap-update, Phase 3 specialized reviewers) | None — session-history defaults to off; Discoverability becomes a recommendation; "What's next?" suppressed | +| Mode | When | Behavior | +|------|------|----------| +| **Interactive** (default) | No `mode:autofix` token | User picks Full or Lightweight at the Execution Strategy prompt; all documented interactive prompts run. | +| **Autofix** | `mode:autofix` in arguments | No user interaction. Execution path and session-history default resolve from `depth:` (default `lightweight`). | -**Conflicting mode flags.** If both `mode:autofix` and `mode:autofix-full` appear in arguments, stop before any subagent dispatch and emit: `ce-compound failed. Reason: conflicting mode flags — mode:autofix and mode:autofix-full cannot be combined.` This mirrors the conflict handling in `ce-code-review`. +**Depth presets** (autofix mode only): -### Shared autofix rules (both `mode:autofix` and `mode:autofix-full`) +- `depth:lightweight` (default) — Lightweight Mode: single-pass, no subagents, no overlap check. +- `depth:full` — Full Mode: Phase 1 parallel research, overlap-update, Phase 3 specialized reviewers. Session history off. +- `depth:thorough` — Full Mode + session history on. -- **Skip all user questions.** Never pause for input — the mode-selection prompt, the Phase 2.5 selective-refresh prompt (multi-candidate case), Discoverability Check consent, and "What's next?" menu are all suppressed. `mode:autofix-full` additionally skips the session-history opt-in (defaults to off — see below). -- **Do not edit instruction files.** The Discoverability Check (AGENTS.md / CLAUDE.md edit) requires user consent. In both autofix modes, surface the gap as a `Discoverability recommendation` line in the output and move on. -- **Be conservative about writing.** Respect the advisory Preconditions (`problem_solved`, `solution_verified`, `non_trivial`). If the conversation and context hint do not evidence a substantive, verified fix, do **not** write a doc — emit the no-op autofix output (see **Autofix mode output** under Success Output) explaining what was missing. -- **Always print the full output block.** The success output (or the no-op autofix output when no doc is warranted) is the sole deliverable since no user is present to follow up. +Invalid `depth:` values halt before subagent dispatch and emit `ce-compound failed. Reason: unknown depth:. Valid values: lightweight, full, thorough.` -### `mode:autofix` (default headless) +### Autofix mode rules -Routes through the **Lightweight Mode** execution path (see the Lightweight Mode section below). Single-pass, no Phase 1 parallel subagents, no overlap check, no Phase 3 specialized reviewers. Overlap drift is accepted and caught later by `ce-compound-refresh`. - -Use when: -- The caller wants low-cost, low-latency learning capture at scale (post-merge hooks, CI). -- Fresh problem-solving context is present; cross-referencing existing docs is not a requirement for this run. - -### `mode:autofix-full` (opt-in thorough headless) - -Routes through the **Full Mode** execution path — Phase 1 parallel research subagents, overlap-update behavior, Phase 3 specialized reviewers — with the interactive prompts guarded: - -- **Mode-selection prompt** → skipped (Full is already chosen by the caller). -- **Session-history opt-in** → defaults to **off**. The opt-in is interactive-only; autofix cannot decide between sessions-yes and sessions-no without a user, so the conservative default is off (no Session Historian dispatch). A caller that wants session history included must invoke the skill interactively or run session analysis separately and pass the findings as context. -- **Discoverability Check consent** → surfaced as a recommendation in the output, per the shared rule above. -- **"What's next?" menu** → skipped, per the shared rule above. - -Phase 1 research subagents (Context Analyzer, Solution Extractor, Related Docs Finder) and Phase 3 specialized reviewers (`ce-performance-oracle`, `ce-security-sentinel`, etc.) run as usual in `mode:autofix-full` — they return text data to the orchestrator and do not themselves prompt the user. - -Use when: -- The caller wants thorough capture with overlap-update (so duplicates fold into existing docs rather than create fresh ones), cross-referencing to related docs, and specialized-reviewer validation of the written doc. -- The token cost of a Full-mode run is acceptable for the quality gain. +- **Skip all user questions.** Never pause — the mode-selection prompt, Phase 2.5 selective-refresh prompt (multi-candidate case), session-history opt-in, Discoverability Check consent, and "What's next?" menu are all suppressed. +- **Do not edit instruction files.** Surface the Discoverability gap as a `Discoverability recommendation` line in the output; do not modify AGENTS.md / CLAUDE.md. +- **Be conservative about writing.** Respect the advisory Preconditions (`problem_solved`, `solution_verified`, `non_trivial`). If the conversation and context hint do not evidence a substantive, verified fix, emit the no-op autofix output explaining what was missing. +- **Always print the full output block** — do not abbreviate, summarize, or skip sections. ## Execution Strategy -**Autofix modes:** Skip this entire section. -- `mode:autofix` → jump directly to the Lightweight Mode execution path below. -- `mode:autofix-full` → execute Full Mode below with the interactive prompts guarded per the Mode Detection section. +**Autofix mode:** Skip this entire section. +- `depth:lightweight` (default when `depth:` is absent) → jump directly to the Lightweight Mode execution path below. +- `depth:full` or `depth:thorough` → execute Full Mode below with the interactive prompts guarded per the Mode Detection section. **Interactive mode** (default): @@ -104,18 +86,18 @@ for relevant knowledge to help the Compound process? This adds time and token usage. ``` -If the user says yes, dispatch the Session Historian in Phase 1. If no, skip it. Do not ask this in lightweight mode, in `mode:autofix` (which routes through Lightweight and never reaches this prompt), or in `mode:autofix-full` (which defaults session-history to off without a prompt — see Mode Detection). +If the user says yes, dispatch the Session Historian in Phase 1. If no, skip it. Do not ask this in lightweight mode or in autofix mode — `mode:autofix` with `depth:thorough` dispatches the Session Historian without asking; all other autofix paths skip it (see Mode Detection). --- ### Full Mode -Used by Interactive mode when the user picks Full, and by `mode:autofix-full` with interactive prompts guarded per Mode Detection (mode-selection, session-history opt-in, Discoverability consent, and "What's next?" menu are all suppressed in `mode:autofix-full`; the Phase 1 subagents and Phase 3 reviewers run unchanged since they return text data and do not themselves prompt the user). +Used by Interactive mode when the user picks Full, and by `mode:autofix depth:full|thorough` with interactive prompts guarded per Mode Detection. **The primary output is ONE file - the final documentation.** -Phase 1 subagents return TEXT DATA to the orchestrator. They must NOT use Write, Edit, or create any files. Only the orchestrator writes files: the solution doc in Phase 2, and — if the Discoverability Check finds a gap and the run is in full interactive mode — a small edit to a project instruction file (AGENTS.md or CLAUDE.md). In `mode:autofix-full` the instruction-file edit is never written; the gap is surfaced as a Discoverability recommendation in the output instead. +Phase 1 subagents return TEXT DATA to the orchestrator. They must NOT use Write, Edit, or create any files. Only the orchestrator writes files: the solution doc in Phase 2, and — if the Discoverability Check finds a gap and the run is in full interactive mode — a small edit to a project instruction file (AGENTS.md or CLAUDE.md). In autofix mode the instruction-file edit is never written; the gap is surfaced as a Discoverability recommendation in the output instead. ### Phase 0.5: Auto Memory Scan @@ -300,7 +282,7 @@ It does **not** make sense to invoke `ce-compound-refresh` when: Use these rules: - If there is **one obvious stale candidate**, invoke `ce-compound-refresh` with a narrow scope hint after the new learning is written -- If there are **multiple candidates in the same area**, ask the user whether to run a targeted refresh for that module, category, or pattern set. In both autofix modes (`mode:autofix` and `mode:autofix-full`), do not ask — recommend `ce-compound-refresh` via the `Follow-up` line in the output with the broadest useful scope (module, category, or pattern set) and move on. +- If there are **multiple candidates in the same area**, ask the user whether to run a targeted refresh for that module, category, or pattern set. In autofix mode, do not ask — recommend `ce-compound-refresh` via the `Follow-up` line in the output with the broadest useful scope (module, category, or pattern set) and move on. - If context is already tight or you are in lightweight mode, do not expand into a broad refresh automatically; instead recommend `ce-compound-refresh` as the next step with a scope hint When invoking or recommending `ce-compound-refresh`, be explicit about the argument to pass. Prefer the narrowest useful scope: @@ -355,7 +337,7 @@ After the learning is written and the refresh decision is made, check whether th `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. ``` - c. In full mode, explain to the user why this matters — agents working in this repo (including fresh sessions, other tools, or collaborators without the plugin) won't know to check `docs/solutions/` unless the instruction file surfaces it. Show the proposed change and where it would go, then use the platform's blocking question tool to get consent before making the edit: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_user` in Gemini, `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to presenting the proposal in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. In lightweight mode, output a one-liner note and move on. In both autofix modes (`mode:autofix` and `mode:autofix-full`), include it as a `Discoverability recommendation` line in the output — do not attempt to edit instruction files (autofix scope is doc capture, not project config). + c. In full mode, explain to the user why this matters — agents working in this repo (including fresh sessions, other tools, or collaborators without the plugin) won't know to check `docs/solutions/` unless the instruction file surfaces it. Show the proposed change and where it would go, then use the platform's blocking question tool to get consent before making the edit: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_user` in Gemini, `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to presenting the proposal in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. In lightweight mode, output a one-liner note and move on. In autofix mode, include it as a `Discoverability recommendation` line in the output — do not attempt to edit instruction files (autofix scope is doc capture, not project config). ### Phase 3: Optional Enhancement @@ -385,7 +367,7 @@ Based on problem type, optionally invoke specialized agents to review the docume This mode skips parallel subagents entirely. The orchestrator performs all work in a single pass, producing the same solution document without cross-referencing or duplicate detection. -**This path is also the execution target for `mode:autofix`** (see Mode Detection). `mode:autofix` adds no-prompt guardrails on top of Lightweight — the execution steps below are identical, but autofix uses a dedicated output block (see **Autofix mode output** under Success Output) so callers can parse the result programmatically. `mode:autofix-full` uses the Full Mode execution path instead, not this one. +**This path is also the execution target for `mode:autofix depth:lightweight`** (see Mode Detection). Autofix adds no-prompt guardrails on top of Lightweight — the execution steps below are identical, but autofix uses a dedicated output block (see **Autofix mode output** under Success Output) so callers can parse the result programmatically. `mode:autofix depth:full|thorough` uses the Full Mode execution path instead, not this one. The orchestrator (main conversation) performs ALL of the following in one sequential pass: @@ -515,40 +497,14 @@ What's next? **After displaying the success output, present the "What's next?" options using the platform's blocking question tool:** `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_user` in Gemini, `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to numbered options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. Do not continue the workflow or end the turn without the user's selection. -**In both autofix modes (`mode:autofix` and `mode:autofix-full`), do NOT present the "What's next?" prompt.** The success output (or the no-op autofix output below) is the sole deliverable. End the turn cleanly after printing it — autofix callers parse the output programmatically and do not respond to interactive menus. - ### Autofix mode output -In both autofix modes the output is the sole deliverable since no user is present to follow up. Print the full block — do not abbreviate, summarize, or skip sections. All output shapes below are machine-parseable: callers detect which shape was emitted by the first line (`✓ Documentation complete (mode:autofix)`, `✓ Documentation complete (mode:autofix-full)`, `✓ Documentation updated (mode:autofix-full)`, or `✓ No documentation written (autofix mode)`) and extract the file path from the `File created:` or `File updated:` block. - -**`mode:autofix` — doc written** (Lightweight path, preconditions met): +**Success** — a new doc was written, or (only on `depth:full|thorough` overlap-high) an existing doc was updated: ``` ✓ Documentation complete (mode:autofix) -File created: -- docs/solutions/[category]/[filename].md - -Track: [bug|knowledge] -Category: [category]/ - -[If a specific older doc in docs/solutions/ looks stale given this new learning:] -Refresh candidate: docs/solutions/[path/to/stale-doc].md - Reason: [one-line rationale — contradicts new fix, superseded, etc.] - Follow-up: /ce-compound-refresh mode:autofix [scope hint] - -[If discoverability check found instruction files don't surface the knowledge store:] -Discoverability recommendation: AGENTS.md/CLAUDE.md does not surface docs/solutions/ - Suggested addition: [one-liner or small section — do NOT apply the edit in autofix mode] - -Note: mode:autofix runs the Lightweight path (no overlap check against existing docs). -ce-compound-refresh will catch duplicates on its next sweep. -``` - -**`mode:autofix-full` — new doc written** (Full path, preconditions met, overlap low): - -``` -✓ Documentation complete (mode:autofix-full) +Depth: [lightweight|full|thorough] File created: - docs/solutions/[category]/[filename].md @@ -556,18 +512,27 @@ File created: Track: [bug|knowledge] Category: [category]/ +[When an existing doc was updated instead (only on depth:full|thorough, overlap high), + replace the first line with "✓ Documentation updated (mode:autofix)" and replace the + "File created:" block above with:] +Overlap detected: docs/solutions/[category]/[existing-filename].md + Matched dimensions: [problem statement, root cause, solution, referenced files, prevention] +File updated: +- docs/solutions/[category]/[existing-filename].md (added last_updated: YYYY-MM-DD) + +[If depth:full or depth:thorough:] Phase 1 subagents: - Context Analyzer: [one-line summary] - Solution Extractor: [one-line summary] - - Related Docs Finder: overlap=[low|moderate|none], refresh_candidates=[count] - - Session Historian: off (mode:autofix-full default) + - Related Docs Finder: overlap=[low|moderate|none|high], refresh_candidates=[count] + - Session Historian: [off (depth:full) | one-line summary (depth:thorough)] Phase 3 specialized reviewers: - [each agent invoked and its one-line verdict, or "none applicable"] -[If overlap was moderate — Phase 2.5 flagged consolidation review:] -Refresh candidate: docs/solutions/[path/to/overlapping-doc].md - Reason: [moderate overlap — same area, different angle/root cause/solution] +[If Phase 2.5 flagged a refresh candidate:] +Refresh candidate: docs/solutions/[path/to/stale-or-overlapping-doc].md + Reason: [one-line rationale] Follow-up: /ce-compound-refresh mode:autofix [scope hint] [If discoverability check found instruction files don't surface the knowledge store:] @@ -575,32 +540,12 @@ Discoverability recommendation: AGENTS.md/CLAUDE.md does not surface docs/soluti Suggested addition: [one-liner or small section — do NOT apply the edit in autofix mode] ``` -**`mode:autofix-full` — existing doc updated** (Full path, preconditions met, overlap high — updated existing doc per Phase 2 overlap rule): - -``` -✓ Documentation updated (mode:autofix-full) - -Overlap detected: docs/solutions/[category]/[existing-filename].md - Matched dimensions: [problem statement, root cause, solution, referenced files, prevention] - -File updated: -- docs/solutions/[category]/[existing-filename].md (added last_updated: YYYY-MM-DD) - -Phase 1 subagents: - - [same four lines as the new-doc shape] - -Phase 3 specialized reviewers: - - [same as the new-doc shape] - -[Discoverability recommendation block, same as new-doc shape, if applicable] -``` - -**Either autofix mode — no doc written** (preconditions not met — trivial fix, unverified solution, or nothing substantive in context): +**No-op** — preconditions not met (trivial fix, unverified solution, or nothing substantive in context): ``` -✓ No documentation written (autofix mode) +✓ No documentation written (mode:autofix) -Mode: [mode:autofix|mode:autofix-full] +Depth: [lightweight|full|thorough] Reason: [which precondition failed — e.g., "non_trivial check: change was a one-character typo" or "solution_verified: no verification evidence in conversation or context hint" diff --git a/plugins/compound-engineering/skills/ce-compound/references/autofix-output-parse-contract.md b/plugins/compound-engineering/skills/ce-compound/references/autofix-output-parse-contract.md new file mode 100644 index 000000000..ed6927fbb --- /dev/null +++ b/plugins/compound-engineering/skills/ce-compound/references/autofix-output-parse-contract.md @@ -0,0 +1,47 @@ +# Autofix output parse contract + +Audience: downstream parsers (orchestrators, post-merge hooks, CI steps) that invoke `/ce-compound mode:autofix ...` and parse the output programmatically. + +This file is not loaded by the skill at runtime. It documents the stable anchors callers can rely on. + +## Output shapes + +The skill emits one of three first-line strings: + +- `✓ Documentation complete (mode:autofix)` — a new doc was written +- `✓ Documentation updated (mode:autofix)` — an existing doc was updated (`depth:full|thorough`, overlap high) +- `✓ No documentation written (mode:autofix)` — preconditions unmet; nothing written + +## Depth anchor + +Every autofix output includes: + +``` +Depth: [lightweight|full|thorough] +``` + +This carries the execution path the skill took. `lightweight` is the default when `depth:` is absent from arguments. + +## Parser-anchor fields + +Callers key off these labels. All are present when meaningful for the shape; none appear when not applicable. + +| Field | Shape(s) | Meaning | +|-------|----------|---------| +| `File created:` | complete | Path to the new doc written | +| `File updated:` | updated | Path to the existing doc that was refreshed | +| `Overlap detected:` | updated | Path to the existing doc that matched; matched dimensions on the next line | +| `Track:` | complete, updated | `bug` or `knowledge` | +| `Category:` | complete, updated | Category directory under `docs/solutions/` | +| `Refresh candidate:` | complete, updated | Path to an older doc that may be stale given this new learning | +| `Discoverability recommendation:` | complete, updated | Present when the project's AGENTS.md/CLAUDE.md does not surface `docs/solutions/` | +| `Reason:` | no-op; also on `Refresh candidate:` blocks | Which precondition failed (no-op), or one-line rationale for the refresh candidate | +| `Context considered:` | no-op | Bulleted summary of what was available when the skill decided not to write | + +## Invalid-argument error + +If the caller passes an unknown `depth:` value, the skill halts before dispatching any subagents and emits: + +``` +ce-compound failed. Reason: unknown depth:. Valid values: lightweight, full, thorough. +``` From 6f409f8b272977753bb6c3a8c647ee1ce9918bb3 Mon Sep 17 00:00:00 2001 From: Ben Wilson Date: Fri, 24 Apr 2026 15:54:13 -0700 Subject: [PATCH 4/7] fix(ce-compound): dispatch Session Historian on depth:thorough in autofix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 1 step 4 was written for interactive mode only ("only if the user opted in"); it never had an autofix branch. In `mode:autofix depth:thorough` — which the Mode Detection contract promises dispatches the Session Historian — the executing agent correctly followed the literal Phase 1 text and skipped dispatch. Rewrites the step 4 header and lead bullets to explicitly list both dispatch and skip conditions with their mode triggers, so the rule at the dispatch site matches the contract in Mode Detection. Caught by a headless `claude -p` test run against a scratch repo, which showed "Session Historian — mode:autofix arg implies skip" even though depth:thorough was passed. Co-Authored-By: Claude Opus 4.7 (1M context) --- plugins/compound-engineering/skills/ce-compound/SKILL.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/plugins/compound-engineering/skills/ce-compound/SKILL.md b/plugins/compound-engineering/skills/ce-compound/SKILL.md index d7e9083a9..e19a83af4 100644 --- a/plugins/compound-engineering/skills/ce-compound/SKILL.md +++ b/plugins/compound-engineering/skills/ce-compound/SKILL.md @@ -199,8 +199,9 @@ Launch research subagents. Each returns text data to the orchestrator. -#### 4. **Session Historian** (foreground, after launching the above — only if the user opted in) - - **Skip entirely** if the user declined session history in the follow-up question +#### 4. **Session Historian** (foreground, after launching the above — see dispatch rule) + - **Dispatch when:** the user opted in during the follow-up question (interactive mode), OR `mode:autofix depth:thorough` was passed (autofix mode — `depth:thorough` is the one autofix path that dispatches Session Historian). + - **Skip when:** the user declined in the follow-up question, OR `mode:autofix` was passed with any depth other than `thorough` (the `depth:lightweight` default and `depth:full` both skip Session Historian). - Dispatched as `ce-session-historian` - Dispatch in **foreground** — this agent reads session files outside the working directory (`~/.claude/projects/`, `~/.codex/sessions/`, `~/.cursor/projects/`) which background agents may not have access to - Searches prior Claude Code, Codex, and Cursor sessions for the same project to find related investigation context From 77d9de66645ec87991fb53ffc045d33fd30878ed Mon Sep 17 00:00:00 2001 From: Ben Wilson Date: Fri, 24 Apr 2026 16:08:36 -0700 Subject: [PATCH 5/7] refactor(ce-compound): tighten Session Historian dispatch rule MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Prior commit (6f409f8b) restated the dispatch rule at the Phase 1 step 4 site, which was necessary to fix the skipped-dispatch bug, but included parenthetical rationale that just repeated what the condition already said: "(autofix mode — depth:thorough is the one autofix path that dispatches Session Historian)" and "(the depth:lightweight default and depth:full both skip Session Historian)". Per AGENTS.md rationale discipline, rationale that would not change runtime behavior if removed belongs elsewhere, not in SKILL.md. Also collapses the paired Dispatch/Skip bullets into one: the Skip condition was the logical inverse of Dispatch, so two bullets doubled text without adding runtime-actionable information. Net: 3 lines of dispatch guidance down to 1; same runtime effect. Co-Authored-By: Claude Opus 4.7 (1M context) --- plugins/compound-engineering/skills/ce-compound/SKILL.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/plugins/compound-engineering/skills/ce-compound/SKILL.md b/plugins/compound-engineering/skills/ce-compound/SKILL.md index e19a83af4..bf61b551d 100644 --- a/plugins/compound-engineering/skills/ce-compound/SKILL.md +++ b/plugins/compound-engineering/skills/ce-compound/SKILL.md @@ -199,9 +199,8 @@ Launch research subagents. Each returns text data to the orchestrator. -#### 4. **Session Historian** (foreground, after launching the above — see dispatch rule) - - **Dispatch when:** the user opted in during the follow-up question (interactive mode), OR `mode:autofix depth:thorough` was passed (autofix mode — `depth:thorough` is the one autofix path that dispatches Session Historian). - - **Skip when:** the user declined in the follow-up question, OR `mode:autofix` was passed with any depth other than `thorough` (the `depth:lightweight` default and `depth:full` both skip Session Historian). +#### 4. **Session Historian** (foreground, after launching the above) + - Dispatch if the user opted in during the follow-up question, or if `mode:autofix depth:thorough` was passed. Otherwise skip. - Dispatched as `ce-session-historian` - Dispatch in **foreground** — this agent reads session files outside the working directory (`~/.claude/projects/`, `~/.codex/sessions/`, `~/.cursor/projects/`) which background agents may not have access to - Searches prior Claude Code, Codex, and Cursor sessions for the same project to find related investigation context From a8cf13a43a6fe1341e99c22a06738879691ca8dd Mon Sep 17 00:00:00 2001 From: Ben Wilson Date: Fri, 24 Apr 2026 16:10:02 -0700 Subject: [PATCH 6/7] fix(ce-compound): guard What's next? prompt in autofix mode The Success Output section still carried an unconditional "present the 'What's next?' options ... Do not continue the workflow or end the turn without the user's selection" instruction at the prompt site. The Autofix mode rules block in Mode Detection lists the "What's next?" menu as suppressed, but that was too weak to override the direct imperative next to the prompt template, and a headless test run confirmed agents were emitting the menu anyway. Adds a four-word guard at the prompt site: "In autofix mode, skip this step." Load-bearing, no rationale, at the exact location where the drift was happening. Addresses https://github.com/EveryInc/compound-engineering-plugin/pull/662#discussion_r3140572986 Co-Authored-By: Claude Opus 4.7 (1M context) --- plugins/compound-engineering/skills/ce-compound/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/compound-engineering/skills/ce-compound/SKILL.md b/plugins/compound-engineering/skills/ce-compound/SKILL.md index bf61b551d..d49038f87 100644 --- a/plugins/compound-engineering/skills/ce-compound/SKILL.md +++ b/plugins/compound-engineering/skills/ce-compound/SKILL.md @@ -495,7 +495,7 @@ What's next? 5. Other ``` -**After displaying the success output, present the "What's next?" options using the platform's blocking question tool:** `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_user` in Gemini, `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to numbered options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. Do not continue the workflow or end the turn without the user's selection. +**After displaying the success output, present the "What's next?" options using the platform's blocking question tool:** `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_user` in Gemini, `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to numbered options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. Do not continue the workflow or end the turn without the user's selection. In autofix mode, skip this step. ### Autofix mode output From 3d032e1dccd0e4561439d9d1c4d3489e10a4d03e Mon Sep 17 00:00:00 2001 From: Ben Wilson Date: Fri, 24 Apr 2026 16:23:34 -0700 Subject: [PATCH 7/7] fix(ce-compound): scope depth: parsing and validation to autofix mode MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Prior text treated any depth: token as control input regardless of mode, and the invalid-depth halt rule applied unconditionally. An interactive call whose free-form context happened to include a depth: token (pasted logs, prose, error messages) would hard-fail with an autofix-shaped error envelope even though the user never opted into autofix routing. Scopes both parsing and the halt rule to mode:autofix being present. When mode:autofix is absent, depth: is not parsed, not stripped, not validated — it stays in the context hint. Verified headless: /ce-compound depth:bogus (no mode:autofix) now enters Interactive mode instead of emitting the halt envelope. Addresses https://github.com/EveryInc/compound-engineering-plugin/pull/662#discussion_r3140572989 Co-Authored-By: Claude Opus 4.7 (1M context) --- plugins/compound-engineering/skills/ce-compound/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/compound-engineering/skills/ce-compound/SKILL.md b/plugins/compound-engineering/skills/ce-compound/SKILL.md index d49038f87..980c77bef 100644 --- a/plugins/compound-engineering/skills/ce-compound/SKILL.md +++ b/plugins/compound-engineering/skills/ce-compound/SKILL.md @@ -33,7 +33,7 @@ When spawning subagents, pass the relevant file contents into the task prompt so ## Mode Detection -Parse `$ARGUMENTS` for `mode:autofix` and an optional `depth:` token. Strip matched tokens; treat the remainder as the brief context hint. +Parse `$ARGUMENTS` for `mode:autofix`. If present, also parse an optional `depth:` token. Strip matched tokens; the remainder is the context hint. | Mode | When | Behavior | |------|------|----------| @@ -46,7 +46,7 @@ Parse `$ARGUMENTS` for `mode:autofix` and an optional `depth:` token. Str - `depth:full` — Full Mode: Phase 1 parallel research, overlap-update, Phase 3 specialized reviewers. Session history off. - `depth:thorough` — Full Mode + session history on. -Invalid `depth:` values halt before subagent dispatch and emit `ce-compound failed. Reason: unknown depth:. Valid values: lightweight, full, thorough.` +In autofix mode, invalid `depth:` values halt before subagent dispatch and emit `ce-compound failed. Reason: unknown depth:. Valid values: lightweight, full, thorough.` ### Autofix mode rules