feat(document-review): add headless mode for programmatic callers#425
Merged
Conversation
Enable other skills and pipelines to invoke document-review without interactive prompts. In headless mode (mode:headless), auto and batch_confirm fixes are applied automatically, present-tier findings are returned as structured text, and Phase 5 returns immediately. Interactive mode is unchanged when mode:headless is not present. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
…mode batch_confirm findings are no longer auto-applied in headless mode. Headless mode changes the interaction model (no prompts, return text), not the classification boundaries. batch_confirm and present findings are both returned with their original classifications intact so the caller can make its own tier-2 decisions. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e8daca4797
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
- Phase 0: explicitly strip mode:* tokens from arguments before using the remainder as document path (fixes parsing ambiguity) - Phase 1: auto-resolve document in headless mode instead of prompting (prevents pipeline stalls when no path provided) Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Headless callers always know what document they want reviewed. Return an actionable error message instead of auto-resolving. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 307a08ba85
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Return "Review failed:" instead of "Review complete" so callers can distinguish a bad invocation from a successful no-findings review. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
tmchow
added a commit
that referenced
this pull request
Mar 28, 2026
Add mode:headless as a fourth explicit mode for skill-to-skill invocation. Headless applies safe_auto fixes in a single pass, returns structured text output with the full findings envelope, writes run artifacts, and emits "Review complete" as a terminal signal. No interactive prompts, no todos, no checkout switching. Follows the pattern established by document-review's headless mode (#425), adapted for ce:review's richer findings schema (autofix_class, owner, requires_verification, evidence[], pre_existing). 🤖 Generated with Claude Opus 4.6 via [Claude Code](https://claude.com/claude-code) + Compound Engineering v2.58.1 Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
mode:headlesssupport to document-review for programmatic callers (other skills, pipelines)autofixes applied silently,batch_confirm+presentfindings returned as structured text with classifications intact — no interactive promptsmode:headlessis not presentMotivation
Other plugins (e.g., open-source-contributor) want to use document-review as a utility in their plan-creation pipelines. The current interactive flow (AskUserQuestion for batch confirms, present-tier findings) doesn't fit pipelines where the calling skill should handle remaining findings with domain-specific knowledge.
Headless mode enables a multi-tier auto-fix cascade:
autoitems (deterministic, same as interactive)batch_confirm+presentfindings as structured text with classificationsChanges
Single file:
plugins/compound-engineering/skills/document-review/SKILL.mdmode:headlessin skill arguments.mode:*tokens are flags, not file paths — stripped from arguments before the remainder is used as the document path."Review failed: ..."with re-invocation guidance if missing — distinct from"Review complete"so callers can tell a bad invocation from a successful review.[batch_confirm]and[present]tags. Interactive path unchanged.Test plan
/document-reviewinteractively on a plan doc — verify no behavior change/document-review docs/plans/some-plan.md mode:headless— verify onlyautoitems applied,batch_confirm+presentreturned as text, no AskUserQuestion calls/document-review mode:headless(no path) — verify"Review failed:"returned, no agents dispatched, distinct from"Review complete"[batch_confirm]vs[present])🤖 Generated with Claude Code