feat(ce-plan,ce-brainstorm): add output:html mode

docs/skills/ce-brainstorm.md

@@ -175,6 +175,7 @@ The Phase 4 handoff offers planning, agent doc review, Proof iteration, direct-t
 | `<feature idea>` | Open-ended brainstorm |
 | `<problem>` | Routes via the product pressure test |
 | Existing `*-requirements.md` path or topic | Resume offer |
+| `output:html` | Write the requirements doc as a single self-contained HTML file instead of markdown. Exclusive — the doc is `.md` OR `.html`, never both. Default is markdown. Set `brainstorm_output: html` in `.compound-engineering/config.local.yaml` to make HTML the default. Pipeline mode (LFG, `disable-model-invocation`) always forces markdown so downstream automation gets a stable text shape. |
 
 ---
 

docs/skills/ce-plan.md

@@ -193,6 +193,7 @@ In universal-planning mode, the U-IDs, dependency ordering, scope boundaries, an
 | `deepen the plan` / `deepening pass` | Re-deepen fast path (interactive mode) |
 | `<bug description>` | Routes to `ce-debug` suggestion menu |
 | `<task in another repo>` | Cross-repo announcement, plan lands in target |
+| `output:html` | Write the plan as a single self-contained HTML file instead of markdown. Exclusive — the plan is `.md` OR `.html`, never both. Default is markdown. Set `plan_output: html` in `.compound-engineering/config.local.yaml` to make HTML the default. Pipeline mode (LFG, `disable-model-invocation`) always forces markdown so downstream automation gets a stable text shape. |
 
 ---
 

plugins/compound-engineering/README.md

@@ -25,8 +25,8 @@ The primary entry points for engineering work, invoked as slash commands. Detail
 |-------|-------------|
 | [`/ce-strategy`](../../docs/skills/ce-strategy.md) | Create or maintain `STRATEGY.md` — the product's target problem, approach, persona, key metrics, and tracks. Re-runnable to update. Read as grounding by `/ce-ideate`, `/ce-brainstorm`, and `/ce-plan` when present |
 | [`/ce-ideate`](../../docs/skills/ce-ideate.md) | Optional big-picture ideation: generate and critically evaluate grounded ideas, then route the strongest one into brainstorming |
-| [`/ce-brainstorm`](../../docs/skills/ce-brainstorm.md) | Interactive Q&A to think through a feature or problem and write a right-sized requirements doc before planning |
-| [`/ce-plan`](../../docs/skills/ce-plan.md) | Create structured plans for any multi-step task -- software features, research workflows, events, study plans -- with automatic confidence checking |
+| [`/ce-brainstorm`](../../docs/skills/ce-brainstorm.md) | Interactive Q&A to think through a feature or problem and write a right-sized requirements doc before planning. Pass `output:html` to write the doc as a single self-contained HTML file instead of markdown (exclusive — md OR html, never both) |
+| [`/ce-plan`](../../docs/skills/ce-plan.md) | Create structured plans for any multi-step task -- software features, research workflows, events, study plans -- with automatic confidence checking. Pass `output:html` to write the plan as a single self-contained HTML file instead of markdown (exclusive — md OR html, never both) |
 | [`/ce-code-review`](../../docs/skills/ce-code-review.md) | Structured code review with tiered persona agents, confidence gating, and dedup pipeline |
 | [`/ce-work`](../../docs/skills/ce-work.md) | Execute work items systematically |
 | [`/ce-debug`](../../docs/skills/ce-debug.md) | Systematically find root causes and fix bugs -- traces causal chains, forms testable hypotheses, and implements test-first fixes |

plugins/compound-engineering/skills/ce-brainstorm/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ce-brainstorm
 description: 'Explore requirements and approaches through collaborative dialogue, then write a right-sized requirements document. Use when the user says "let''s brainstorm", "what should we build", or "help me think through X", presents a vague or ambitious feature request, or seems unsure about scope or direction -- even without explicitly asking to brainstorm.'
-argument-hint: "[feature idea or problem to explore]"
+argument-hint: "[feature idea or problem to explore] [output:html]"
 ---
 
 # Brainstorm a Feature or Improvement
@@ -53,12 +53,38 @@ Do not proceed until you have a feature description from the user.
 
 ### Phase 0: Resume, Assess, and Route
 
+#### 0.0 Resolve Output Mode
+
+Determine `OUTPUT_FORMAT` before any other phase fires. Output mode is **exclusive** — the requirements doc is written as either markdown (`.md`) OR HTML (`.html`), never both. Precedence: CLI arg > config > default (`md`), with a hard pipeline-mode override.
+
+**Read config (pre-resolved at skill load):**
+!`cat "$(git rev-parse --show-toplevel 2>/dev/null)/.compound-engineering/config.local.yaml" 2>/dev/null || echo '__NO_CONFIG__'`
+
+Resolution steps:
+
+1. **CLI arg.** Scan `$ARGUMENTS` for a token starting with the literal prefix `output:`. If found, strip it from arguments before treating the remainder as the feature description, and match its value case-insensitively against `md` and `html`.
+   - `output:` alone (no value) → no-op, fall through to step 2.
+   - `output:<unknown>` (e.g., `output:pdf`) → drop the token, fall through to step 2, and remember to emit a one-line note above the post-generation menu after final resolution: `Ignored unknown output: value '<value>' — using <resolved_format> instead.` where `<resolved_format>` is the value `OUTPUT_FORMAT` actually resolved to after steps 2-4. Do not hardcode `md` in the note — that misleads users when config has set HTML.
+2. **Config.** If step 1 did not resolve and the pre-resolved YAML above has an **active (non-commented)** `brainstorm_output:` key whose value matches `md` or `html` (case-insensitive), use it. Missing, invalid, or commented values fall through silently. Critical: lines starting with `#` are YAML comments and must be ignored — the shipped config template includes commented examples like `# brainstorm_output: html` to document the option, and matching those as active settings would silently force HTML mode on every run without the user having opted in.
+3. **Default.** Otherwise `OUTPUT_FORMAT=md`.
+4. **Pipeline override.** When invoked from LFG or any `disable-model-invocation` context, force `OUTPUT_FORMAT=md` regardless of steps 1-3. Downstream consumers (`ce-plan`, `ce-work`) parse markdown reliably; HTML in pipeline runs is unnecessary friction.
+
+**Token-parsing convention:** only literal-prefix flag tokens (`output:`, `mode:`, `delegate:` where applicable) are consumed and stripped. Other `<word>:<word>` tokens — including conventional commit prefixes like `feat:`, `fix:`, `chore:` that may appear inside a feature description — pass through verbatim.
+
+**Load the format-rendering reference based on the resolved value.** Section content is the same in either format; presentation differs. Both rendering references are paired with `references/brainstorm-sections.md`, which describes what the brainstorm contains regardless of format.
+
+- When `OUTPUT_FORMAT=md`, read `references/markdown-rendering.md` for format principles.
+- When `OUTPUT_FORMAT=html`, read `references/html-rendering.md` for format principles.
+
+The `output:` preference does NOT auto-propagate to `ce-plan` on handoff — ce-plan re-resolves its own `plan_output` config independently. Asymmetric output (`requirements.html` + `plan.md`) is acceptable; users who want HTML for both set both keys in `.compound-engineering/config.local.yaml`.
+
 #### 0.1 Resume Existing Work When Appropriate
 
-If the user references an existing brainstorm topic or document, or there is an obvious recent matching `*-requirements.md` file in `docs/brainstorms/`:
+If the user references an existing brainstorm topic or document, or there is an obvious recent matching `*-requirements.{md,html}` file in `docs/brainstorms/`:
 - Read the document
 - Confirm with the user before resuming: "Found an existing requirements doc for [topic]. Should I continue from this, or start fresh?"
 - If resuming, summarize the current state briefly, continue from its existing decisions and outstanding questions, and update the existing document instead of creating a duplicate
+- **Resume preserves the existing artifact's format, except pipeline mode.** Write back in whatever format the existing artifact uses — markdown if the existing file is `.md`, HTML if it is `.html`. Explicit `output:` arguments on this run override (e.g., resuming an `.html` doc with `output:md` switches the artifact to markdown). Pipeline mode (LFG, any `disable-model-invocation` context) always wins per Phase 0.0: even when resuming an existing `.html` brainstorm, pipeline runs force `OUTPUT_FORMAT=md` so downstream automation receives the markdown shape it expects. The resume rewrites the markdown file at the parallel path and the original `.html` is left in place untouched.
 
 #### 0.1b Classify Task Domain
 
@@ -231,9 +257,14 @@ Fires for **all tiers** including Lightweight. Skip Phase 2.5 entirely on the Ph
 
 ### Phase 3: Capture the Requirements
 
-Write or update a requirements document only when the conversation produced durable decisions worth preserving. Read `references/requirements-capture.md` for the document template, formatting rules, visual aid guidance, and completeness checks.
+Write or update a requirements document only when the conversation produced durable decisions worth preserving — see `references/brainstorm-sections.md` "Decide whether a doc is warranted at all" for the criteria and the bug-fix stress test. Skip document creation when the user only needs brief alignment and the decisions can flow downstream (ce-plan, commit message, docs/solutions/) without a brainstorm artifact in the middle.
+
+When a doc is warranted, compose it using:
+
+- `references/brainstorm-sections.md` — section contract (outcomes, hard floor, include-when-material catalog, agency rules, ID conventions).
+- The format-specific rendering reference loaded at Phase 0.0 (`markdown-rendering.md` OR `html-rendering.md`) — how the resolved format presents the sections.
 
-For **Lightweight** brainstorms, keep the document compact. Skip document creation when the user only needs brief alignment and no durable decisions need to be preserved.
+Write to `docs/brainstorms/YYYY-MM-DD-<topic>-requirements.<md|html>` — extension follows `OUTPUT_FORMAT`. Confirm with the absolute path so the reference is clickable.
 
 ### Phase 4: Handoff
 

plugins/compound-engineering/skills/ce-brainstorm/references/brainstorm-sections.md

@@ -0,0 +1,199 @@
+# Brainstorm Sections
+
+This reference describes what makes a great brainstorm requirements document.
+It does NOT prescribe how the doc looks on the page — rendering is handled by
+the format-specific references (`markdown-rendering.md`, `html-rendering.md`).
+
+## The outcome
+
+A great brainstorm produces a doc that enables three audiences to act:
+
+- **The planning agent** (`ce-plan` or a human) produces an implementation
+  plan without inventing user behavior, scope boundaries, or success
+  criteria — the brainstorm answered those.
+- **The reviewer** sees the framing choices, distinguishes pinned from open,
+  and catches scope gaps before planning.
+- **The future reader** traces why the proposed thing matters, who it's for,
+  and what success looks like.
+
+Sections earn their place by serving one of these audiences. Omit padding.
+
+## Decide whether a doc is warranted at all
+
+Brainstorm dialogue does not always need to produce a durable document.
+Skip document creation when **both** hold:
+
+- The user only needs brief alignment — no exploration produced novel scope,
+  framing, or decisions worth preserving in IDed shape.
+- Any durable decisions made during the dialogue can flow naturally to
+  downstream artifacts (`ce-plan`, the commit message, `docs/solutions/`)
+  without a brainstorm doc as an intermediary.
+
+The trigger for creating a doc is when the dialogue surfaced enough
+structural decisions, scope boundaries, or acceptance criteria that
+downstream consumers (planner, reviewer, future reader) need them in a
+durable, IDed form — not just as conversational artifacts.
+
+**Stress test:** a brainstorm about a tiny bug fix where the user asks "fix
+this with a null check or with upstream validation?" and the agent confirms
+"upstream validation, here's why" doesn't need a brainstorm doc. The
+decision flows to `ce-plan` (or directly to commit message, or to
+`docs/solutions/` if it's a pattern worth carrying) without a brainstorm
+artifact in the middle.
+
+Conversely, a brainstorm about a multi-actor feature with contested scope
+and several behavioral conditions probably does need a doc — the planning
+agent needs the structured content the dialogue produced.
+
+## Match depth to content
+
+When a doc IS warranted, depth matches what the dialogue produced. A
+brainstorm with sparse content produces a sparse doc; one with rich content
+produces a rich doc. Don't add ceremony to make a slim brainstorm look
+substantial.
+
+## Hard floor
+
+When a doc is warranted, these are present.
+
+- **Summary** — what is being proposed, in 1-3 lines. Forward-looking.
+  Orients the reader before they invest in detail.
+- **Requirements** (with stable R-IDs) — what must be true about the
+  proposed thing. For very sparse brainstorms (≤3 simple items where the
+  bullets ARE the summary), plain bullets without IDs are acceptable; the
+  trigger for R-IDs is whether downstream consumers will reference them.
+  When requirements span distinct concerns (e.g., "Packaging" /
+  "Migration and compatibility" / "Contributor workflow"), group them
+  under bold inline headers within the Requirements section — group by
+  capability or concern, not by the order requirements were discussed.
+  R-IDs stay continuous across groups (R1, R2 in the first group; R3, R4
+  in the second; never restart at R1 per group).
+
+## Include when material
+
+The agent decides per brainstorm whether each section carries information
+that isn't covered elsewhere. Filling a section with placeholder prose is
+worse than omitting it.
+
+- **Problem Frame** — include when motivation isn't obvious from Summary
+  alone (the *why* needs paragraphs, not a sentence). Backward-looking /
+  situational. Does NOT restate the proposal; the remedy lives in Summary.
+
+- **Key Decisions** — include when the brainstorm produced opinionated
+  framing choices (defaults, scope narrowings, foundational technical picks)
+  that constrain Requirements / Flows / Scope below. Each entry names the
+  decision in bold with prose rationale. Sits high in the rendered doc so
+  readers encounter the framing choices before descending into detail.
+
+- **Actors** — include when the proposed thing has multi-party behavior
+  (multiple humans, agents, or systems meaningfully involved). Skip for
+  non-behavioral brainstorms (naming briefs, data-shape briefs, pure
+  research, decision frameworks).
+
+- **Key Flows** — include when the proposed thing has multi-step behavior.
+  Expected by default for behavioral brainstorms unless the proposed thing
+  is genuinely non-flow-shaped (pure API surface, policy, artifact output)
+  and Actors / Requirements / Scope Boundaries / Acceptance Examples
+  together prevent downstream invention of paths. When omitting from a
+  behavioral brainstorm, note the reason in the doc.
+
+- **Acceptance Examples** — include when any requirement has a
+  state-dependent or conditional shape ("When X, Y") where prose alone leaves
+  ambiguity about edge cases. **Always include AEs covering
+  behavioral-conditional requirements** — that's where the ambiguity bites
+  hardest. Skip when all requirements are unconditional and unambiguous.
+
+- **Success Criteria** — include when there are quality / metric / handoff
+  signals that Requirements don't already carry: quantitative metrics ("p95
+  latency under 200ms"), qualitative criteria ("the agent's output reads as
+  one voice"), process / handoff quality ("ce-doc-review can act on this
+  without follow-ups"). Skip when Requirements ARE the success criteria
+  (every R is "done when the R is true").
+
+- **Scope Boundaries** — include when scope is contested or there are
+  tempting non-goals worth naming explicitly. When the brainstorm is about
+  positioning a product against adjacent ones the team could have built but
+  is rejecting, split into "Deferred for later" (eventually but not v1) and
+  "Outside this product's identity" (positioning decision). Otherwise, a
+  single list is fine.
+
+- **Dependencies / Assumptions** — include when material upstream
+  dependencies exist or when load-bearing assumptions need to be surfaced.
+
+- **Outstanding Questions** — include when there are unresolved items.
+  Distinguish "Resolve Before Planning" (blocks planning) from "Deferred to
+  Planning" (answered during planning or codebase exploration).
+
+- **Sources / Research** — surface research that orients the planner or
+  justifies framing choices. The test: *"if I were the planner reading this
+  cold, would this breadcrumb help me make better choices?"* Yes → surface
+  (code locations, external docs, RFCs, constraints, prior plans — the
+  category is inclusive, not enumerated). Process exhaust (reading the
+  user's prompt, glancing at obvious files) → omit.
+
+## Agent agency
+
+The catalog is a floor, not a ceiling. When the brainstorm's content doesn't
+fit any catalog section, introduce a new one — don't force the content into
+a section it doesn't belong in. Content drives section choices, not vice
+versa.
+
+The agent also picks per artifact:
+
+- Whether Acceptance Examples render as a separate section or embed in each
+  requirement
+- How much depth each present section gets
+
+(Requirements grouping is covered above in the Hard Floor item — group by
+concern when they span distinct areas, with continuous R-IDs across groups.)
+
+## ID and content rules
+
+Same shape as plan rules.
+
+- **Stable IDs.** R-IDs (Requirements), A-IDs (if Actors fire), F-IDs (if
+  Flows fire), AE-IDs (if Acceptance Examples fire). No other ID namespaces.
+- **Plain prefix.** `R1.`, `A1.`, `F1.`, `AE1.` as bullet prefixes. Do not
+  bold; the prefix is visually distinctive on its own.
+- **Bold leader labels** inside Flows and Acceptance Examples
+  (`**Trigger:**`, `**Covers R4, R8.**`) provide structure without deeper
+  heading levels.
+- **Repo-relative paths.** Always. Never absolute paths.
+- **No process exhaust.** No "captured at Phase X" notes, no `## Next Steps`
+  pointing to ce-plan, no italic provenance lines. Engineering process
+  metadata belongs in commit messages and tool output, not the artifact.
+- **No implementation details by default.** Libraries, schemas, endpoints,
+  file layouts, code structure stay out unless the brainstorm itself is
+  inherently about a technical or architectural change and those details are
+  the subject of the decision.
+
+## Discipline: Summary vs Problem Frame
+
+When both sections are present, they earn separate sections only by holding
+to different purposes:
+
+| Section | Question it answers | Time direction | Length |
+|---|---|---|---|
+| `## Summary` | What is this doc proposing? | Forward-looking | 1-3 lines |
+| `## Problem Frame` | Why does this proposal exist? | Backward-looking / situational | Paragraphs |
+
+- **Summary doesn't need problem context.** A reader scanning Summary gets
+  the proposal at a glance.
+- **Problem Frame doesn't restate the proposal.** It establishes the
+  situation, the specific moment of pain, and the cost shape — then stops.
+  The remedy lives in Summary; restating it in Problem Frame is the
+  duplication that makes the two sections feel redundant.
+
+## Rendering
+
+The format-specific references describe how to render these sections in each
+output format:
+
+- **Markdown rendering:** `references/markdown-rendering.md`
+- **HTML rendering:** `references/html-rendering.md`
+
+This reference (`brainstorm-sections.md`) is about WHAT the brainstorm
+contains; rendering references are about HOW each format presents it. The
+brainstorm is written in one format — markdown OR HTML, never both — based
+on the resolved output mode. The section catalog is the same regardless of
+format.