averello/compound-engineering-plugin-mirror

0 Fork 0

mirror of https://github.com/EveryInc/compound-engineering-plugin.git synced 2026-10-03 20:57:31 +02:00

Files

T

Hally Maschine 980f959024 feat(harness): add opencode as a named peer and work engine

Operators can set cross_model_peer and work_engine harness to opencode.
Review and POV run `opencode run` with OPENCODE_CONFIG_CONTENT denying
edit and bash. Work uses --auto. Output is parsed as OpenCode NDJSON
text events, not grok or Cursor envelopes.

2026-08-31 12:30:49 -07:00

18 KiB

Raw Permalink Blame History

`ce-doc-review`

Review a requirements or plan document with parallel persona agents, apply mechanical fixes, and route the rest.

ce-doc-review is the on-demand findings skill for documents. Point it at a requirements-only unified plan, an implementation-ready plan, or a legacy requirements/plan doc. It picks reviewer personas from what the doc actually contains, dispatches them in parallel, applies only full-confidence mechanical fixes in the document's native format, then routes everything else.

It is the sibling of /ce-code-review for the docs side. It is not a verdict. Use /ce-pov when you want a holistic take (strengths, risks, bottom line) rather than an issue list. Use /ce-code-review for findings on a diff, and /ce-debug when something is actually broken.

ce-brainstorm and ce-plan both invoke it on the artifacts they write. You can also run it on any planning doc on disk.

TL;DR

Question	Answer
What does it do?	Selects reviewer personas from the doc, dispatches them in parallel, applies mechanical fixes, and routes remaining findings
When to use it	After a requirements-only plan lands, after `ce-plan` writes or enriches a plan, or any time you want structured findings on a planning doc
What it produces	An updated markdown or HTML doc with mechanical fixes applied in its native format, plus structured handling of proposed fixes and decisions
Modes	Interactive (direct invoke, or a caller's follow-up option). Non-interactive (default when `ce-plan` chains it)

Example invocations

A path, no path, or non-interactive. Markdown and HTML plans use the same review and mutation routes.

# Review a specific requirements or plan document. Interactive by default:
# mechanical fixes land, then you route the rest.
/ce-doc-review docs/plans/notification-mute.md

# Same, on an implementation-ready plan
/ce-doc-review docs/plans/2026-05-04-001-feat-notification-mute-plan.md

# No path: asks which doc, or finds the most recent file in the project's plans directory
/ce-doc-review

# Non-interactive: requires a path. Applies mechanical fixes, returns the rest as structured text
/ce-doc-review mode:non-interactive docs/plans/notification-mute.md

# Deprecated alias for the same non-interactive contract
/ce-doc-review mode:headless docs/plans/notification-mute.md

For HTML, edits preserve the artifact's existing structure and never insert markdown syntax.

The Problem

Document review is harder than code review in specific ways:

No type checker. A requirements doc can contradict itself with no compiler error
No execution. You cannot "run" a plan to see if its scope fits its goals
A generalist pass says "looks good" and misses the design gap, the security implication, or the unstated scope expansion
Product framing, security, design, scope, and feasibility need different lenses. One reviewer prioritizes one
Findings lack ownership. "Consider revising" does not say who decides or what to do
Rejected findings re-surface because the rejection was never recorded

The Solution

ce-doc-review runs document review as a pipeline with explicit gates:

Always-on personas for coherence and feasibility
Conditional personas selected from doc content: product-lens, design-lens, security-lens, scope-guardian, adversarial
Parallel persona dispatch with bounded concurrency
Synthesis that promotes on cross-persona agreement, resolves contradictions, and routes on confidence and fix class together. Only a mechanical correction at full confidence applies unattended. Everything else that touches meaning is batched into one confirmation. Only a real fork becomes a question
Decision primer: round-to-round suppression so rejected findings do not re-surface, and applied findings get verification
Four-option interaction over the remaining decisions: per-finding walk-through, auto-resolve with best judgment, append to Open Questions, report-only

What Makes It Novel

Doc-content-aware persona selection

Conditional personas activate from what the doc says, not keyword matching:

product-lens when the doc stakes an unsettled product position — what to build, why, or what comes first — that a stakeholder could challenge, or the work carries strategic weight; a choice among mechanisms is not a product position
design-lens when it contains UI/UX references, user flows, or visual design language
security-lens when it touches auth, public APIs, sensitive data, payments, or third-party trust boundaries
scope-guardian when it has multiple priority tiers, a large requirement count, or scope-boundary language that looks misaligned
adversarial when it touches high-stakes domains, proposes new abstractions, has missing or extended origin, contains requirements-shape premise content, or presents explicit alternatives

coherence-reviewer and feasibility-reviewer run on every review.

Personas also scope their techniques by doc shape. On plan-shape docs with validated upstream Product Contract provenance, product-lens, adversarial, and scope-guardian suppress premise-level techniques and run only implementation-level checks. On requirements-shape docs they run their full technique set. Feasibility inverts: deep implementability checks on plan-shape docs, a tight "would this direction force a fundamental rework?" check on requirements docs.

Classification happens once from readiness metadata, content-shape signals, frontmatter, R-IDs vs U-IDs, and section structure. Unified artifacts are sliced: a requirements-only plan reviews the Product Contract. An implementation-ready plan reviews Product Contract, Planning Contract, Implementation Units, Verification Contract, and Definition of Done.

Three surfaces, not a flat list

After personas return, synthesis validates, drops unanchored findings, deduplicates, promotes on agreement, and routes:

Applied (reported): only safe_auto at confidence 100. Mechanical corrections. One right answer
Proposed fixes (grouped confirmation): everything with a concrete fix that touches meaning, plus obligations the document already entailed. One question over the batch, shown in full first
Decisions: genuine forks. The question is which remedy, never whether to proceed with something already settled
FYI: observational items. No question

The output is one consolidated set, not every persona's raw list.

Decision primer

When you run multiple rounds in the same session, the primer carries forward what was applied vs rejected:

Applied findings flow back so the next round can verify the fix landed
Rejected findings (skip / defer / acknowledge) are suppressed by fingerprint plus evidence-substring overlap, so the same issue does not re-surface

Without the evidence snippet, suppression falls back to title-only and either re-surfaces rejected findings or suppresses too aggressively.

Four-option interaction

After mechanical fixes land and the grouped confirmation is answered, remaining decisions get one routing question over the whole remaining set:

Option	Effect
Review each finding one by one	Step through each decision. Apply, skip, defer to Open Questions, or auto-resolve the rest
Auto-resolve with best judgment	Applies what it judges safe. You review a bulk preview before it commits
Append to Open Questions	All remaining findings deferred to the doc's `Deferred / Open Questions` section as a batch
Report only	No further edits. Report stays in chat

The walk-through itself supports an "auto-resolve the rest" escape mid-flow. Bulk actions show a preview (section, title, action, brief rationale) before anything lands.

Each per-finding step prints a terminal block and duplicates What's wrong / Proposed fix / If left as-is into the blocking question, so modal harnesses stay decidable without scrolling.

Interactive vs non-interactive

Mode	When	Behavior
Interactive	Direct invoke, brainstorm's "Pressure-test the requirements", or `ce-plan`'s "Decide on the review's open items"	Grouped confirmation, routing question, walk-through, bulk-preview confirmations
Non-interactive	`mode:non-interactive` (deprecated alias `mode:headless`). Default when `ce-plan` chains the review	Apply full-confidence mechanical corrections silently. Return everything else as structured text. No prompts

Non-interactive requires a path. Without one it errors rather than guessing.

Coverage, settled decisions, and the rendering floor

The output names which personas ran, which were activated by what signals, and whether any failed or timed out.

Decisions you examined and settled carry a session-settled: annotation. The safe-auto pass never strips it. A persona that wants to challenge a settled decision must frame the challenge as infeasibility, not preference, and it is never auto-applied.

Findings lead with a recommendation and a one-sentence consequence that names no opaque token. Document IDs (R6, U3) keep the ID and get a handle. Code symbols are translated to the role they play. You can decide Apply / Defer / Skip without opening the reviewed codebase.

Cross-model judgment pass

When the conditional judgment trio (adversarial, product-lens, security-lens) activates, those lenses also run through one different model provider than the host, in a separate read-only process. Agreement between a peer return and its in-process twin is the strongest promotion signal in synthesis. Coherence, scope-guardian, and feasibility stay single-model so the pass does not spawn a peer on every review.

A single whole-document sweep has one different-provider peer review the entire document as a general reviewer, folding in as whole-doc-<provider>. On unified plans the focused trio peers are sliced to match their in-process twins. The sweep reads the whole document.

The pass needs a peer agent CLI (codex, claude, grok, cursor-agent, or opencode) — an API key alone does not enable it, and Gemini has no standalone target. Peers are found on PATH or inside the Codex desktop app bundle; see the prerequisite note in ce-code-review.

cross_model_review_mode: off in CE config keeps this pass from running at all — no peer is resolved and nothing leaves the host; the in-process reviewers cover the lens and Coverage says the pass was disabled by checkout config. A direct request in conversation for a peer overrides it for one run. Which target runs the peer is auto-chosen and overridable: conversation, cross_model_peer: in CE config, active project instructions, then codex → claude → grok → composer. Cursor means cursor-agent using its configured default/Auto model. Composer means a Composer model through Cursor. Grok binds the native grok CLI when it is installed; Grok through Cursor is a different route, used when asked or when the grok CLI is missing and Cursor is allowed. cross_model_model: and cross_model_effort: in CE config pin that target's model (e.g. fable for claude or gpt-5.6-sol for codex, or a namespace-qualified codex id such as openai.gpt-5.6-sol when that CLI routes through a non-default model_provider) and reasoning effort; a value the peer cannot honor skips the pass with a stated reason rather than substituting. See the configuration reference.

The pass embeds the document into the peer prompt and sends it to an external provider. CROSS_MODEL_PEERS restricts which providers may receive content. Peers are strictly read-only. Failures are non-blocking; an exact provider-overload 529 gets one same-route retry, never an unbounded retry loop. A second target remains opt-in (CROSS_MODEL_MAX_PEERS=2).

Quick Example

/ce-plan finishes a Standard plan for a notification-mute feature and invokes /ce-doc-review in mode:non-interactive with the plan path.

The skill reads the doc, classifies it as a plan from content-shape signals (U-IDs, plan section structure), and analyzes content for conditional personas. The plan touches a UI surface (mute toggle copy) but no high-stakes domains and proposes no new abstractions. It activates coherence (always-on), feasibility (always-on, plan-shape techniques), and design-lens (UI surface). Adversarial, scope-guardian, security-lens, and product-lens skip.

Three reviewers return 9 raw findings. Synthesis merges them into 6: 2 mechanical fixes (typo, broken cross-reference), 3 proposed fixes (wording on a durability tradeoff, a missing edge case in test scenarios for U2, a design-lens flag on the toggle copy), 1 FYI.

The 2 mechanical fixes apply directly. Non-interactive mode returns the rest as structured text. A single summary line surfaces above the post-generation menu: Doc review applied 2 fixes. 3 proposed fixes and 1 FYI remain; no decisions requiring judgment. The user can pick Start /ce-work and go, or Decide on the review's open items to walk the three proposed fixes interactively.

When to Reach For It

Use ce-doc-review when:

A requirements-only unified plan just landed from /ce-brainstorm and you want a structured Product Contract review before planning
A plan just landed from /ce-plan and you want a deeper review before execution
You want round-to-round refinement on a planning doc. The decision primer prevents loops
A programmatic caller needs review with structured output (mode:non-interactive)

Skip ce-doc-review when:

The doc is trivially short (a 2-bullet plan). Review overhead exceeds yield
You want a holistic take, not an issue list → /ce-pov
You want code review, not doc review → /ce-code-review
The doc is purely informational (a learning doc, a release note). There is nothing to review for shipping

Use as Part of the Workflow

ce-doc-review is invoked from the skills that write planning docs:

/ce-brainstorm post-doc menu offers Pressure-test the requirements for markdown or HTML unified plans. It runs interactively with full premise scrutiny and is hidden when a prototype offer is on the same menu
/ce-plan after the plan is written runs mode:non-interactive by default on markdown and HTML plans. Mechanical fixes apply silently in the native format. Remaining findings surface as a one-line summary above the post-generation menu, where Decide on the review's open items opts into the interactive walkthrough
In non-interactive mode, callers receive structured findings and route the user-decision options themselves

Use Standalone

Specific path: /ce-doc-review docs/plans/2026-05-04-001-feat-notification-mute-plan.md
No path: /ce-doc-review asks which doc to review, or auto-finds the most recent file in the project's plans directory
Non-interactive: /ce-doc-review mode:non-interactive docs/plans/.../plan.md returns structured findings without prompts

Reference

Argument	Effect
(empty, interactive)	Asks which doc to review, or auto-finds the most recent file under the project's plans directory
`<doc path>`	Reviews that specific doc. Interactive unless a mode token is also present
`mode:non-interactive <doc path>`	Non-interactive mode. Structured text output, no prompts. Requires a path. Deprecated alias: `mode:headless`

Non-interactive mode without a path errors out rather than guessing.

FAQ

What's the difference between this and ce-code-review? ce-code-review reviews diffs (code changes). ce-doc-review reviews docs (requirements, plans). Different reviewer personas, different findings shape, different routing. Both share multi-persona dispatch plus synthesis, and both can run a cross-model pass. Lens policy differs: ce-code-review runs its adversarial lens cross-model. ce-doc-review runs the three-lens judgment trio plus a whole-doc sweep, because doc-review judgment is spread across more lenses.

What's the difference between this and ce-pov? ce-pov gives a holistic take: bottom line, strengths, risks. This skill gives issue-shaped findings and can edit markdown or HTML in place.

Which lenses run cross-model, and why not all of them? Only the judgment trio (adversarial, product-lens, security-lens) get a dedicated cross-model twin. Those are where a second model's different priors produce genuinely different findings. Coherence and scope-guardian are convergent. Feasibility is always-on, so giving it a twin would spawn a peer on every review. The separate whole-document sweep still gives feasibility, coherence, and scope broad cross-model coverage through one general-reviewer read.

Why does the decision primer matter? Without it, every round re-surfaces the same findings, including ones you already rejected. The primer uses fingerprint plus evidence-snippet matching to suppress rejected findings and verify applied fixes.

What's "Append to Open Questions" for? For findings you want to address later, not now. They get appended to the doc's visible Deferred / Open Questions section in its native format so they survive the session and the next planner or implementer sees them.

Why a bulk preview? Mass changes deserve a confirmation step. "Auto-resolve with best judgment" is delegation. The preview shows the changes before they commit so you can cancel.

What if a persona times out or fails? The skill proceeds with findings from agents that completed and notes the failure in Coverage. A single agent failure does not block the review.

Can it review documents other than requirements and plans? The personas are tuned for those two types. Reviewing a learning doc or release note works mechanically, but the persona advice may not be calibrated. For a planning doc this is the right tool. For other types the personas may surface noise.

18 KiB Raw Permalink Blame History

ce-doc-review