--- title: "feat(ce-review): Add headless mode for programmatic callers" description: "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)." type: skill canonical_url: https://claudary.paisolsolutions.com/skills/2026-03-28-001-feat-ce-review-headless-mode-plan source: "Claudary" difficulty: intermediate author: "Claude Code Knowledge Pack" date: 2026-07-10T10:59:03.529Z license: CC-BY-4.0 attribution: "feat(ce-review): Add headless mode for programmatic callers — Claudary (https://claudary.paisolsolutions.com/skills/2026-03-28-001-feat-ce-review-headless-mode-plan)" --- # feat(ce-review): Add headless mode for programmatic callers 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). ## Overview --- 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-2026-03-27.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//`) 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 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: Intent: Reviewers: Verdict: Artifact: .context/compound-engineering/ce-review// Applied N safe_auto fixes. Gated-auto findings (concrete fix, changes behavior/contracts): [P1][gated_auto -> downstream-resolver][needs-verification] File: -- (<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 --- Source: [Claudary](https://claudary.paisolsolutions.com/skills/2026-03-28-001-feat-ce-review-headless-mode-plan) · https://claudary.paisolsolutions.com