feat(ce-compound): add mode:headless for non-interactive use#813
Merged
feat(ce-compound): add mode:headless for non-interactive use#813
Conversation
Enables automations and skill-to-skill callers to run /ce-compound without blocking on user questions. In headless mode: - skip the Full/Lightweight question and the session-history follow-up; run Full without session history - apply the Discoverability Check edit silently when an instruction file lacks a docs/solutions/ mention - skip Phase 3 specialized agent reviews to bound token usage - end with a structured terminal report (Documentation complete / Documentation skipped) instead of the interactive "What's next?" menu The doc itself is identical to what an interactive Full run produces. Classification work (track, category, overlap) follows the same rules and writes nothing extra into the artifact. Modeled on ce-doc-review's mode:headless pattern.
Hard rename mode:autofix to mode:headless for naming parity with the rest of the CE skill family (ce-compound, ce-doc-review, ce-code-review, ce-plan), all of which use mode:headless for their non-interactive paths. Semantics are unchanged. Also adds an argument-hint so the flag is discoverable to humans, not just model auto-invocation. No alias for the old token — callers passing mode:autofix will need to update to mode:headless.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: dc5c835f75
ℹ️ 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".
The previous wording framed "non-interactive mode" as the clearest example of when un-validated bets need a visible Assumptions section. That framing assumes synchronous = validated, which doesn't hold for skills like ce-compound where the interactive flow asks only meta-questions (Full vs Lightweight, session-history opt-in) and never validates the substantive inferences (track, category, filename, overlap). Reframe the test: compare per skill, not per mode. An Assumptions section is audit content when the corresponding interactive mode would have validated content that the headless run skips. When neither mode validates the inferences, labeling them only in headless is misleading — it implies interactive runs validated content they didn't. Prompted by Codex review feedback on the ce-compound mode:headless PR, where the literal reading of the old rule generated incorrect guidance for a skill whose interactive mode doesn't validate the relevant content.
Merged
LLMpsycho
pushed a commit
to LLMpsycho/compound-engineering-plugin
that referenced
this pull request
May 10, 2026
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
/ce-compoundnow runs end-to-end without blocking on user questions when invoked withmode:headless, enabling automations (CI jobs, scheduled tasks, LFG pipelines) to capture learnings as part of broader workflows.A second change renames
ce-compound-refresh'smode:autofixflag tomode:headlessso the compound family speaks the same word.ce-doc-review,ce-code-review, andce-planalready usemode:headlessfor their non-interactive paths.A third change refines an authoring rule in
plugins/compound-engineering/AGENTS.mdthat incorrectly demanded an## Assumptionssection for any non-interactive doc, regardless of what the corresponding interactive mode actually validates. See "AGENTS.md rule refinement" below.What changes for headless callers
In headless mode,
/ce-compound:docs/solutions/mentionDocumentation completeorDocumentation skipped), not the interactive "What's next?" menuThe resulting doc is identical to what an interactive Full run produces. Classification work (track, category, overlap) follows the same rules and writes nothing extra into the artifact.
Headless forces Full and does not enter Lightweight. Automations get cross-reference and overlap detection at the cost of three parallel subagent dispatches. Lightweight remains interactive-only.
Breaking change for ce-compound-refresh callers
Hard rename.
mode:autofixis no longer accepted byce-compound-refresh. Callers passing that token must update tomode:headless. No alias. Semantics are unchanged.AGENTS.md rule refinement
The old "process exhaust vs audit content" guidance framed non-interactive mode as the clearest example of when un-validated bets need a visible Assumptions section. That framing assumes synchronous = validated, which is not true for skills like
ce-compoundwhose interactive flow asks only meta-questions (Full vs Lightweight, session-history opt-in) and never validates the substantive inferences (track, category, filename, overlap). Applied literally, the old rule would have requiredce-compoundheadless to label as un-validated the same inferences that interactive runs also do not validate, implying interactive runs confirm content they don't.The reframed test: an
## Assumptionssection is audit content when the corresponding interactive mode would have validated content that the headless run skips. Compare per skill, not per mode.ce-planheadless skips a HITL walkthrough that interactive performs, so its headless artifact warrants Assumptions.ce-compoundheadless does not, because its interactive counterpart also does not walk the user through the substantive inferences.Design decisions
ce-doc-review: stripmode:headlessfrom$ARGUMENTS, treat presence as a flag for the entire run, use the remainder as the optional context hint.docs/solutions/store. Reported in the terminal output for traceability.## Assumptionssection in headless docs. See the AGENTS.md rule refinement above for the reasoning./ce-compound-refreshwould later have to consolidate.Test plan
bun testandbun run release:validateboth pass. End-to-end headless trace verified in both skills: every interactive prompt site is scoped to interactive mode with an explicit headless callout in the same paragraph, so no blocking question can fire whenmode:headlessis present.