dsh-compound-engineering 0.0.0-stage → 0.1.0

package/skills/ce-brainstorm/references/interaction-rules.md

@@ -0,0 +1,33 @@
+# Core Principles, Interaction Rules, and Output Guidance
+
+Read this before the first question of any brainstorm, including the non-software route.
+
+## Core Principles
+
+1. **Assess scope first** - Match the amount of ceremony to the size and ambiguity of the work.
+2. **Be a thinking partner** - Suggest alternatives, challenge assumptions, and explore what-ifs instead of only extracting requirements.
+3. **Resolve product decisions here** - User-facing behavior, scope boundaries, and success criteria belong in this workflow. Detailed implementation belongs in planning.
+4. **Keep implementation out of the Product Contract by default** - Do not include libraries, schemas, endpoints, file layouts, or code-level design unless the brainstorm itself is inherently about a technical or architectural change.
+5. **Right-size the artifact** - Simple work gets a compact requirements-only unified plan or brief alignment. Larger work gets a fuller Product Contract. Do not add ceremony that does not help planning.
+6. **Apply YAGNI to carrying cost, not coding effort** - Prefer the simplest approach that delivers meaningful value. Avoid speculative complexity and hypothetical future-proofing. Polish or delight the user did not ask for is an option to offer, not a default.
+7. **Do not turn coverage into decomposition** - For software brainstorms, treat named devices, providers, and data sources as coverage requirements, not automatically as separate integration workstreams. Split them only when a shared access path cannot satisfy a named requirement. Leave connector selection to planning unless that choice materially changes product scope or behavior.
+8. **Keep one coherent work unit per artifact** - When a request contains independently valuable outcomes that can be planned and delivered separately, choose one as the current focus before deep exploration. Preserve how the surrounding work is currently understood without turning tentative future areas into requirements for this plan.
+
+## Interaction Rules
+
+These rules apply to every brainstorm, including the universal (non-software) flow routed to `references/universal-brainstorming.md`.
+
+1. **Ask one question at a time** - One question per turn, even when sub-questions feel related. Stacking several questions in a single message produces diluted answers; pick the single most useful one and ask it.
+2. **Prefer single-select multiple choice** - Use single-select when choosing one direction, one priority, or one next step.
+3. **Use multi-select rarely and intentionally** - Use it only for compatible sets such as goals, constraints, non-goals, or success criteria that can all coexist. If prioritization matters, follow up by asking which selected item is primary.
+4. **Default to the host's blocking question tool** — use the host's blocking question tool already in the current tool list (match by capability, not by a host-specific name). Presence in the current tool list is proof the tool exists; never call a user-facing question tool to discover whether it exists. If a matching tool is listed but unloaded, use the host's tool-discovery primitive to load that capability — do not search for another host's tool name. These tools include a free-text fallback, so well-chosen options scaffold the answer without confining it. This default holds for opening and elicitation questions too, not only narrowing. Fall back to numbered options on the host's user-visible chat surface only when no such tool is in the list or a real question call errors. Never silently skip the question. **Exception — visual-probe gate:** if the next decision is a shape, behavior, or layout question that does not meet Rule 7, the visual-probe gate in `references/visual-probes.md` takes precedence.
+5. **Use an open-ended question only when the question is genuinely open** - Drop the blocking tool when the answer is inherently narrative, when presented options would steer a diagnostic or introspective answer, or when you cannot write 3-4 genuinely distinct, plausibly-correct options without padding. The test: if you'd be straining to fill the option slots, the question is open — ask it open-ended. Rule 1 still applies: one question per turn.
+6. **Open-ended questions earn their place only when they're specific enough to elicit a substantive answer** - Apply Rule 5 silently: just ask the question, never narrate the form choice. The question must give the user something concrete to anchor on. Good: *"What's the most concrete thing someone's already done about this — paid for it, built a workaround, quit a tool over it?"* — it names what counts as an answer. Too thin: *"What's your take?"* — nothing to bite into, and framings that imply a short answer ("briefly", yes/no) waste the open question the same way.
+7. **Offer `ce-prototype` when the decision is expensive to unravel.** This skill states the routing test once, here; every other site in this skill cites it. The test: committing an approach would be expensive to unravel — later planning and implementation will treat it as given — **and** neither talk nor a cheap one-decision sketch can settle it. A purely visual decision qualifies on the same terms as a behavioral one: finish and motion are dimensions a rough sketch strips by definition, so a question turning on them is already past the sketch tier. Unravel cost is a precondition, not decoration — a decision that is cheap to reverse does not escalate, however visual it is. Offer once — when you recognize that bar, not at a fixed phase. Do not offer for routine UI that follows an existing pattern (adding a known button, placing a standard control), and do not offer for a visual choice that follows an existing token, type scale, or component-library pattern. On accept, invoke `ce-prototype` via the host's normal skill-invocation mechanism, passing the named question, the surface, any hard constraints, and any artifact path; do not build it here. On decline, continue here; do not re-offer unless the decision itself changes.
+8. **Ask only for user decisions** — Look up answers available in the repository, existing research, or other reachable sources. A lookup in progress does not delay unrelated questions. The user decides unresolved product direction, preferences, and scope. Choose technical details from project evidence within the request instead of asking the user to choose them.
+
+9. **Recommend what the user's goal needs, and nothing it does not.** Offering ideas the user did not ask for is part of being a thinking partner; what you recommend is what gets built when the user says "your call." Recommend adding scope, a safeguard, or a process the user did not name only when the goal behind the request is not actually met without it (what they are trying to achieve, not only the words they used), or when leaving it out lets harm land before anyone would catch it. An idea that would be expensive or hard to add later (stored data, a shared interface, money, security) but that neither of those requires is worth putting to the user as an explicit choice, without recommending it. Offer any other idea as a non-default option, or list it with the synthesis's deferred items instead of spending a question on it. A recommendation never narrows something the user asked for. This rule governs what you recommend and commit, not what you ask: questions that help the user understand their problem, including whether a related area should be part of this work, are still the job.
+
+## Output Guidance
+
+- **Prioritize decision-relevant detail** - Preserve the facts, tradeoffs, and caveats needed for the next decision; trim introductions, repetition, and optional background first.

package/skills/ce-brainstorm/references/markdown-rendering.md

@@ -0,0 +1,242 @@
+# Markdown Rendering
+
+This is a format-rendering reference — it describes how to render any
+artifact in markdown, independent of which skill is producing it.
+
+It is paired with a section contract (`plan-sections.md`,
+`brainstorm-sections.md`, etc.) that describes *what* the artifact contains.
+This reference describes *how* markdown specifically presents it. The same
+content rendered by different skills shares the same markdown principles.
+
+## Hard invariants
+
+These hold regardless of which skill produced the artifact.
+
+- **YAML frontmatter at the top of the file.** Standard `---` delimited block
+  containing the artifact's stable metadata (title, date, type, etc.
+  — exact fields are per-skill, defined in the section contract).
+- **ASCII identifiers in anchors.** Markdown headings auto-generate anchors
+  from the heading text. Keep headings ASCII so anchors are predictable
+  (`#implementation-units`, not `#implementación-units`).
+- **Repo-relative paths for file references.** Always. Never absolute paths
+  — they break portability across machines, worktrees, teammates.
+- **No HTML mixed in.** Keep the markdown pure. No `<div>`, no `<details>`,
+  no inline `<style>`. The only exception is a contract-defined invisible
+  semantic marker such as `<!-- ce-section: work-relationships -->`; it carries
+  section meaning for downstream agents and does not create layout. If a layout
+  idea only works as HTML, defer it to the HTML rendering. Markdown stays
+  markdown.
+- **No fixed-width line wrapping.** Do not hard-wrap prose to a column (e.g.
+  80 chars). Write one sentence per line, or let each paragraph flow as a
+  single line. The artifact is read rendered and shared, where fixed wraps add
+  nothing and only produce noisy mid-sentence diffs; markdown joins soft line
+  breaks within a paragraph, so wrapping never changes the rendered output.
+- **Unified plan sections use stable headings.** For unified plan artifacts,
+  render the required sections with exact ASCII headings so agents can find
+  them by heading scan: `## Goal Capsule`, `## Product Contract`,
+  `## Planning Contract`, `## Implementation Units`, `## Verification Contract`,
+  `## Definition of Done`, and optional `## Appendix`. Requirements-only
+  artifacts omit the plan-only sections rather than emitting empty placeholders.
+  These stable headings are the wayfinding contract: consumers scan them
+  (markdown headings, or `<h1>`–`<h3>` / anchor ids in HTML) instead of reading
+  the whole document.
+- **Goal Capsule is top-loaded.** It appears before Product Contract and long
+  appendices for fast orientation — not a hidden machine copy.
+
+## Format principles
+
+These shape what "good" markdown looks like; the agent applies them per
+artifact based on content shape.
+
+### ID prefix format
+
+Stable IDs (R, U, A, F, AE, KTD) appear as plain prefixes at the start of
+the bullet or heading — do NOT bold the prefix. The prefix is visually
+distinctive on its own; bolding it inflates visual noise.
+
+```markdown
+- R1. The plan returns paginated sessions.   ← right
+- **R1.** The plan returns paginated sessions.   ← wrong (bolded prefix)
+```
+
+Same applies to unit headings: `### U1. Cloak detection in preflight contract`.
+
+### Content shape: prose vs bullets vs tables
+
+The same content can be rendered three ways; the agent picks per content
+shape, not by template default.
+
+- **Prose** when the content has narrative flow (motivation, decision
+  rationale, problem framing). Bullets fragment narrative into
+  disconnected pieces.
+- **Bullets** when items share a parallel shape but each carries enough
+  prose to not fit a table cell.
+- **Tables** when 5+ items share uniform structure (`ID + body`,
+  `name + value`, `decision + rationale`, `risk + mitigation`). Tables
+  scan faster at that scale and unlock additional columns (status,
+  traceability, severity) that bullets can't accommodate cleanly.
+
+The test: which shape would a reader scan fastest for this content? If
+items have parallel structure and 5+ instances, table. If items are 3-5
+and each has a few lines of prose, bullets. If the content is a single
+narrative thought, prose.
+
+### Bold leader labels within bullets
+
+When a bullet has substructure that benefits from named fields (Key Flows
+with Trigger / Actors / Steps / Outcome, Acceptance Examples with Covers
+/ Given / When / Then), use bold leader labels at the start of nested
+bullets — not deeper heading levels.
+
+```markdown
+- F1. Anonymous capture
+  - **Trigger:** Agent enters Step 2a with no session.
+  - **Actors:** A1, A2
+  - **Steps:** Preflight detects cloak; agent launches; capture proceeds.
+  - **Covered by:** R1, R2, R5
+```
+
+This gives the bullet structure without needing H4/H5 headings that would
+clutter the doc and break TOC generation.
+
+### Section separators
+
+For substantial artifacts, use horizontal rules (`---`) between top-level
+H2 sections. Omit for short docs where separators would dominate.
+
+### Tables for genuinely comparative info only
+
+Use tables for the uniform-shape case in "Content shape" above. Don't use
+tables to render content lists that are really bullets — markdown tables
+are noisier in raw form and worse for diffs.
+
+## Section anatomy
+
+How section types commonly render in markdown. These are patterns, not
+contracts — the agent picks the shape that fits the content.
+
+- **Goal Capsule** — bullets or a small table for objective, means (only
+  when an approach is fixed), authority, execution profile, stop conditions, and who finishes the remaining work.
+- **Product Contract** — H2 section containing Summary, Problem Frame,
+  Requirements, and product-scope subsections. Put Requirements under
+  `### Requirements` so review tools can distinguish Product Requirements
+  from implementation detail.
+- **Planning Contract** — H2 section for KTDs, high-level technical design,
+  assumptions, and sequencing.
+- **Summary / Problem Frame** — prose paragraphs.
+- **Requirements** — bullets with `R<N>.` prefix. When requirements span
+  more than one concern, grouping under bold inline headers is the default
+  shape, not optional polish (group by capability, not by discussion order);
+  render a flat list only when every requirement is about the same thing.
+  When requirements have status, traceability, or severity that warrant
+  additional columns, escalate to a table.
+- **Implementation Units** — H3 heading per unit with `U<N>.` prefix.
+  Fields (Goal, Files, Patterns, Test Scenarios, Verification) render as
+  bullets with bold leader labels, or as sub-headings if the field has
+  multi-paragraph content.
+- **Verification Contract / Definition of Done** — use tables when commands,
+  applicability, unit IDs, and done signals share a uniform shape. Name
+  concrete repo commands such as `bun test` rather than generic "run tests"
+  when the repo has known commands.
+- **Key Technical Decisions** — bullets with `KTD<N>.` plain prefix (same
+  format as `R1.`/`U1.`) + bold decision name + prose rationale. Legacy
+  plans with unnumbered KTDs stay readable by label; do not renumber
+  existing numbered ones. A `session-settled:` annotation renders as part
+  of the KTD bullet's visible text, stem preserved verbatim.
+- **Key Flows / Acceptance Examples** — bullets with bold leader labels
+  (Trigger / Actors / Steps / Outcome / Covers / Given-When-Then).
+- **Scope Boundaries** — bullets, optionally split into "Deferred for
+  later" / "Outside this product's identity" sub-headings when the
+  positioning distinction matters.
+
+The agent picks more elaborate or simpler shapes based on what each
+specific artifact's content needs.
+
+## Diagrams
+
+When the section contract calls for a diagram (architecture, sequence,
+flowchart, state machine, swim lane, data-flow), markdown renders it as
+a fenced mermaid block:
+
+```markdown
+` ``mermaid
+flowchart TB
+  A[Start] --> B{Decision}
+  B -->|yes| C[Action]
+  B -->|no| D[Other action]
+` ``
+```
+
+(`TB` direction default — keeps diagrams narrow in source view and in
+narrow rendered viewports.)
+
+Markdown's diagram affordances are limited compared to HTML. For
+quantitative comparisons (bar charts, scatter plots) markdown has no
+native equivalent — use a table with the data and let prose or caption
+carry the interpretation. The richer visualization happens in the HTML
+rendering.
+
+For a **UI/layout shape** that would be a wireframe in HTML, markdown has
+no inline-SVG wireframe affordance. Render the region composition as a
+mermaid layout `flowchart` (or describe it in prose) — never hand-draw a
+box-drawing/ASCII wireframe; it violates the no-box-drawing-characters rule
+and reads poorly. The wireframe proper is an HTML-only affordance.
+
+## Inline code and code blocks
+
+- **Inline code** for identifiers (variable names, function names,
+  flag names, file paths, IDs that aren't section anchors).
+- **Fenced code blocks** with language tag for code, shell commands,
+  API request/response samples. Always specify the language for syntax
+  highlighting and accessibility.
+
+```markdown
+The flag `--cdp-url` accepts a URL.
+
+` ``bash
+browser-use --cdp-url http://localhost:9222
+` ``
+```
+
+## No process exhaust
+
+Engineering process metadata stays out of the artifact:
+
+- No "captured at Phase X" notes
+- No `## Next Steps` pointing to the next skill
+- No italic provenance lines ("*Brainstorm completed 2026-05-13*")
+- No engineering-flow shepherding ("Now read this file:", "Next, run that
+  command:")
+
+This information belongs in commit messages, tool output, and agent
+transcripts — not in the artifact a reader returns to weeks later.
+
+## Frontmatter shape
+
+Per-skill frontmatter fields are defined in each skill's section contract
+(`plan-sections.md` lists plan frontmatter; `brainstorm-sections.md` lists
+brainstorm frontmatter). Common rules:
+
+- YAML at the top of the file, delimited by `---` on its own line above
+  and below.
+- Field names in lowercase snake_case (`created_at`, `topic`, not
+  `CreatedAt`, `Topic`).
+- **No status / lifecycle field.** Artifacts are point-in-time records
+  (decision or discovery), not tracked work items. Do not introduce a
+  mutable `status` field or an `active → completed` lifecycle — whether
+  the work shipped is derived from git, not stored in the doc.
+- Stable across artifact revisions — never rename or repurpose a field.
+
+## Post-write audit
+
+Before declaring the markdown file written, scan it for these common
+slips:
+
+- All stable IDs are plain-prefix format, not bolded.
+- No HTML elements mixed in.
+- All file paths are repo-relative.
+- Horizontal rule separators between H2s (for Standard / Deep artifacts).
+- No process exhaust (Phase X notes, Next Steps pointers, provenance
+  lines).
+- Tables only where 5+ uniform-shape items justify them.
+- Frontmatter has all the per-skill required fields with reasonable values.

package/skills/ce-brainstorm/references/model-tiers.md

@@ -0,0 +1,13 @@
+# Model Tiers
+
+Read this when dispatching a sub-agent (the Phase 1.1 grounding scout, the Phase 2.6 claim verifier, or the opt-in Slack researcher). Sub-agent dispatch is tiered by task shape, never hardcoded to a model name:
+
+- **Extraction tier** — the grounding scout: retrieval and quoting work. Use the platform's cheapest capable model when the current harness exposes a known override. "Capable" is part of the spec — escalate to the generation tier when the repo is large or the stack obscure.
+- **Generation tier** — the claim verifier: evidence-driven mechanical verification. Use the platform's mid-tier model when the current harness exposes a known override. If model names are unknown, omit the override and inherit rather than guessing.
+- **Ceiling tier** — the dialogue itself. Questions, approaches, synthesis, and the requirements-only unified plan run in the main conversation on the orchestrator's model; nothing is dispatched for them.
+
+If the user's or project's active instructions or the live prompt name a model for this subagent, use that model instead of the default tier above. They can name it by the subagent's tier, by its prompt-asset name, or for the subagents being dispatched. Without such an instruction, a model configured for this subagent's role takes precedence over the default tier.
+
+**Degradation rule.** When the platform's subagent primitive does not support per-agent model selection, dispatch the scout and verifier on the inherited model and keep their read budgets and output caps — cost control then comes from structure, not tiering. When the platform has no subagent primitive at all, do the topic scan inline at Phase 1.1 — still writing the grounding dossier to the scratch path, because downstream consumers (the Phase 2.6 verifier, the ce-plan handoff) receive that path — and verify claims inline before the Phase 3 write, with the same budgets.
+
+Classify a rejected native dispatch by whether an agent launched: correct a pre-launch argument rejection once, leave capacity-limited work queued, and send any other failure to the inline degradation above.

package/skills/ce-brainstorm/references/output-mode.md

@@ -0,0 +1,26 @@
+# Resolving the output mode (Phase 0.0)
+
+#### 0.0 Resolve Output Mode
+
+`SKILL.md` states the two rules that must hold even when this file is not read: the mode is exclusive, and markdown is written unless HTML was requested. This file states the precedence that decides the rest — in-prompt request > user-stated preference > config > default (`md`) — and the token-parsing convention.
+
+**Read config.** Resolve `<repo-root>` with `git rev-parse --show-toplevel`, then apply the ordinary-key rule stated in `SKILL.md`. Read both files when they exist. If the root cannot be resolved, fall through to the defaults below.
+
+Resolution steps:
+
+1. **In-prompt request.** Reason over the user's prompt for this run for a request about *this document's* output format, expressed either as the `output:` shorthand or in plain language ("make this a webpage", "I want this in HTML"). On an explicit format, match it case-insensitively to `md`/`html`, and ignore the `output:` shorthand token when reading the rest of the prompt as the feature description. Distinguish a request about the document's format from a format named as subject matter: "explore an HTML export feature" is the work, not a doc-format request — do not switch on it.
+   - `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 the remaining precedence steps. Do not hardcode `md` in the note — that misleads users when config has set HTML.
+2. **User-stated preference.** If this prompt holds no format request, honor an output-format preference (markdown vs HTML) the user established earlier — earlier in this session, in your memory, or written into their active instructions — that is already in your context (match `md`/`html` case-insensitively). A remembered preference is more current than the rarely-edited config, so it **overrides** the config in step 3. Do not open or search instruction files to find it — act only on a preference already present in your context; if none is, fall through to the config.
+3. **Config.** If steps 1-2 did not resolve, apply the ordinary-key rule: first **active (non-commented)** `brainstorm_output:` in `config.local.yaml` then `config.yaml` matching `md` or `html` (case-insensitive) wins. Missing, invalid, or commented values continue to the next layer, then step 4. 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.
+4. **Default.** Otherwise `OUTPUT_FORMAT=md`.
+
+There is no pipeline override. A headless or non-interactive run resolves the format by the same four steps; if it asked for HTML, or its config or project instructions say HTML, it gets HTML. Downstream skills read either format.
+
+**Token-parsing convention:** only literal-prefix flag tokens (`output:`, `mode:`, `brainstorm_model:<alias>`, `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. A stripped `brainstorm_model:<alias>` token (passed by an orchestrator) is kept for the model-elevation step before approach generation; it is not woven into the feature description.
+
+**Model-elevation visibility.** Treat a stripped `brainstorm_model:<alias>` token, or a `brainstorm_model` config value you have read, as a pending input to Phase 2 (Explore Approaches), not a resolved choice. Phase 2 resolves the choice from the current conversation, the token, and the config immediately before generating approaches, so later user intent cannot be lost. A headless or non-interactive run still evaluates the token and the config.
+
+**Resolve the format here; load the rendering reference at Phase 3, not now.** The format-rendering reference (`references/markdown-rendering.md` for `md`, `references/html-rendering.md` for `html`) is consumed only when the doc is composed — loading it during Phase 0 would carry 200+ lines through the entire dialogue. Phase 3 (write the plan) says when to load it. Section content is the same in either format; presentation differs.
+
+The `output:` preference does NOT auto-propagate to `ce-plan` on handoff — ce-plan re-resolves its own `plan_output` config independently. Because both skills now operate on the same unified artifact, an explicit conversion by `ce-plan` must report the old path and new canonical path, and leaves the other-format sibling in place as non-canonical for automated discovery.

package/skills/ce-brainstorm/references/phase-0.md

@@ -0,0 +1,104 @@
+# Phase 0: resume, classify, route, and scope
+
+#### 0.1 Resume Existing Work When Appropriate
+
+This resume scan needs `<root>/plans/`, so it applies only to a repo-backed run. If there is no git repository, or resolving `<root>` fails (a bad `docs_root`), skip the scan and continue — do not fail the run here, since Phase 0.1b may route non-software work to `references/universal-brainstorming.md`, whose contract does not write a unified plan under `<root>/plans/`.
+
+Only when that check passes — a repo-backed run whose `<root>` resolved — evaluate this resume condition; never resolve `<root>` here on a run the check told you to skip. When it applies, if the user references an existing brainstorm topic or document, or there is an obvious recent matching unified plan in `<root>/plans/` with `artifact_contract: ce-unified-plan/v1` and `product_contract_source: ce-brainstorm`, whose contents are still a Product Contract without implementation planning:
+- Read the document
+- Confirm with the user before resuming: "Found an existing requirements-only plan 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.** 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). A headless run resumes in the existing format like any other run. When the format switches, the resume writes the new-format file at the parallel path and the original is left in place untouched.
+
+Historical `docs/brainstorms/*-requirements.{md,html}` files remain legacy inputs for `ce-plan`, but new `ce-brainstorm` outputs do not write there.
+
+#### 0.1b Classify Task Domain
+
+Before proceeding to Phase 0.2, classify whether this is a software task. The key question is: **does the task involve building, modifying, or architecting software?** -- not whether the task *mentions* software topics.
+
+**Software** (continue to Phase 0.2) -- the task references code, repositories, APIs, databases, or asks to build/modify/debug/deploy software.
+
+**Non-software brainstorming** (route to universal brainstorming) -- BOTH conditions must be true:
+- None of the software signals above are present
+- The task describes something the user wants to explore, decide, or think through in a non-software domain
+
+**Neither** (respond directly, skip all brainstorming phases) -- the input is a quick-help request, error message, factual question, or single-step task that doesn't need a brainstorm.
+
+**Verdict-shape carve-out — do not exit before the 0.1c check.** A request weighing whether to **adopt / switch to / replace** a *named external technology, library, pattern, platform, or architecture* for this project is a **software** decision even when it only names the tool and asks the bare question ("should we adopt Biome here?"). Classify it as **Software** and continue so the 0.1c check below can catch it — do **not** route it to *Neither* or *Non-software*, which would skip that check and lose the exact verdict-shape prompts it exists for.
+
+**If non-software brainstorming is detected:** Read `references/universal-brainstorming.md` now and follow it — it replaces Phases 0.2–4 entirely. Scope assessment, exploration moves, convergence, and the wrap-up menu for this route live there, not here; improvising them produces an unstructured chat with no synthesis and no handoff. The non-software route does **not** write `artifact_contract: ce-unified-plan/v1`; that contract is reserved for software Product Contracts that can later become implementation-ready code plans. The **Core Principles and Interaction Rules in `references/interaction-rules.md` still apply unchanged** — including one-question-per-turn, asking only decisions the environment cannot settle, and the default to the platform's blocking question tool — and are the only part of this workflow that survives the route.
+
+#### 0.1c Route a Verdict Question to ce-pov
+
+A brainstorm scopes **what to build** once a direction is chosen. Deciding **whether to adopt, switch to, or replace** a *specific named external candidate* (technology, library, pattern, platform, or architecture) judged against this project is a different job — a decisive, project-grounded verdict, which is `ce-pov`'s purpose.
+
+**The verdict shape — all three hold:** a **named external candidate** (one outside thing, or a bounded set the user already named like "X vs Y vs Z" — not an open field for *you* to enumerate); a **whether-to-commit intent** (adopt / switch to / migrate / replace / is-it-time-for / revisit — not "how should we design or scope Y"); judged **against this project** (fit, migration cost, worth it here), not a neutral explainer. Open-ended design or scoping where *you'd* invent the options stays here. The whether-to-commit trigger separates the two: "help me **pick** between X, Y, Z" is a verdict; "I'm **mulling** X, Y, Z" stays here.
+
+When the shape matches — at intake, or whenever later dialogue (Phases 1.3–2) clarifies a request into it — read `references/verdict-routing.md` and follow it: offer the `ce-pov` handoff interactively (never silently switch), invoke `ce-pov` on accept, drop the offer and continue the normal workflow unchanged on decline. That reference defines how to build the offer, how to map its fields, and what to pass to `ce-pov`.
+
+#### 0.2 Assess Whether Brainstorming Is Needed
+
+**Clear requirements indicators:**
+- Specific acceptance criteria provided
+- Referenced existing patterns to follow
+- Described exact expected behavior
+- Constrained, well-defined scope
+
+**If requirements are already clear:**
+Keep the interaction brief. Confirm understanding and present concise next-step options rather than forcing a long brainstorm. Whether a file is written is decided by the Lightweight rule in 0.3 below. Skip Phase 1.1's scan and scout and all of Phase 1.2 — Pack discovery at the top of 1.1 still runs, because declared packs constrain the synthesis on every path — still classify tier in Phase 0.3, then go straight to Phase 1.3 or Phase 2.5 and follow `references/synthesis-summary.md`'s Path A / Path B rule exactly. Do not assume the synthesis is announce-only: a richly pre-loaded prompt classifies as Standard or Deep, which routes to Path B (full scoping synthesis + confirmation), not Path A — collapsing that rule is the defect `synthesis-summary.md` warns against.
+
+#### 0.3 Assess Scope
+
+Use the feature description plus a light repo scan to classify the work:
+- **Lightweight** - small, well-bounded, low ambiguity
+- **Standard** - normal feature or bounded refactor with some decisions to make
+- **Deep** - cross-cutting, strategic, or highly ambiguous
+
+If the scope is unclear, ask one targeted question to disambiguate and then proceed; when it stays uncertain, take the heavier tier.
+
+**Lightweight ends in chat.** The result is a paragraph in the synthesis: what is being built, the one or two decisions made, and where they go next (`ce-plan`'s prompt, the commit message). No file is written, and Phase 1.1's scout, Phase 2's approach generation, and Phase 2.6's verifier do not run. A file is written only when the dialogue produced a decision that a downstream consumer needs recorded under a stable ID, or when the user asks for one; then Phase 3 (write the plan) writes it from the dialogue's decisions, and the Ready for Planning Check covers what the dialogue established.
+
+**Coherent-work gate.** Before entering Phase 1, check whether the request contains more than one independently plannable product outcome: each has its own user value or acceptance boundary and could be delivered without completing the others. Shared actors, one end-to-end outcome, or coverage across named devices/providers do not by themselves justify a split.
+
+When this check finds multiple coherent areas:
+
+1. Propose a plain-language breakdown and state only relationships supported now: which areas depend on or enable others, share a product rule, or can proceed independently.
+2. Ask which one area this brainstorm should own. If the user already chose one, carry it forward instead of asking again.
+3. Treat that area as the sole source of Requirements, Flows, Acceptance Examples, and later Implementation Units. Other areas remain contextual candidates, not scope.
+4. Preserve the current broader understanding for Phase 3's **How This Work Fits Together** section. Mark tentative relationships as tentative; later brainstorms may revise, split, merge, or discard them.
+5. Carry the boundary into the Goal Capsule: name the current area in its objective and state that the surrounding areas are not active scope.
+
+Keep the work together when the outcomes cannot be independently useful or validated, or when separating them would force this Product Contract to invent the missing shared behavior. This check narrows the active artifact; it does not create a parent plan or a roadmap.
+
+**Deep sub-mode: feature vs product.** For Deep scope, also classify whether the brainstorm must establish product shape or inherit it:
+
+- **Deep — feature** (default): existing product shape anchors decisions. Primary actors, core outcome, positioning, and primary flows are already established in the product or repo. The brainstorm extends or refines within that shape.
+- **Deep — product**: the brainstorm must establish product shape rather than inherit it. Primary actors, core outcome, positioning against adjacent products, or primary end-to-end flows are materially unresolved. Existing code lowers the odds of product-tier but does not by itself rule it out — a half-built tool with ambiguous shape is still product-tier.
+
+Product-tier triggers additional Phase 1.2 questions and additional Product Contract sections. Feature-tier uses the current Deep behavior unchanged.
+
+**Visual probe tripwire.** If the feature is inherently visual or spatial — drawing/canvas tools, annotation behavior, visual editors, UI layout or navigation, interaction states, charts, diagrams, animation, maps, timelines, or spatial flows — read `references/visual-probes.md` now. Strong signals include freehand vs constrained drawing behavior, canvas annotation tools, layout comparisons, and state/flow placement. Loading the reference here only prepares you; that reference decides when the offer must be made (state-based, at the first shape/behavior/state/layout/flow/diagram decision), the wording of the text-vs-visual offer, and how to invoke the display helper.
+
+**Unfamiliarity tripwire.** If the user signals they lack working knowledge of the domain or the territory the topic touches — "I know nothing about X", "never touched the auth modules", "I don't know what's possible / what I should be asking" — read `references/blindspot-pass.md` now. Loading it here only prepares you; that reference decides when the offer is made (territory-scoped, before the first substantive question into the flagged territory), the shape of the map, and how mapped decisions re-enter the dialogue.
+
+#### 0.4 Surface the Workflow Spine
+
+For **Standard and Deep** scope, use the platform's task-tracking capability when available (`TaskCreate`/`TaskUpdate`/`TaskList` in Claude Code, `update_plan` in Codex, `todo_write` in DeepSeek Harness, or the equivalent on other harnesses). Skip it entirely for Lightweight and on the Phase 0.1b non-software route. Create it here, not earlier — 0.1b and 0.1c exit before this point, and the tier is unknown until 0.3.
+
+If the harness exposes no task-tracking capability — including `ToolSearch` or its equivalent returning no match — continue normally without simulating a task list in chat.
+
+The task list is the user's view of the run. The spine is five tasks, in order:
+
+1. Check what already exists
+2. Ask scoping questions
+3. Weigh approaches and recommend
+4. Confirm scope before writing
+5. Write the requirements plan
+
+**Conditional work gets a task only once its condition is met** — never at creation, and never as a placeholder for a branch that may not run. A branch gets one when the user is either waiting on it or would be surprised to learn it happened: an accepted blindspot pass, a dispatched Slack researcher, a Phase 2.6 verifier working in the background. A step that runs once per decision rather than once per run does not get one — it would thrash the list. Insert the task at the position where the work runs.
+
+**Name every task you add the way the spine is named:** verb first, five words or fewer, naming the outcome the user can hold you to — not the phase, the internal activity, or the tool. `Verify claims against the code`, not `Phase 2.6 claim verification`. Never restate counts, quotas, or pacing in a name; that contract lives in the phase that defines it.
+
+**When a condition resolves so that a listed task will not run, record the skip — never mark it plainly complete, and never let it vanish unexplained.** In order of preference: set a `cancelled` or `skipped` status if the harness has one; otherwise rename the task to name the skip (`Skipped: no doc warranted`) and then mark it complete; only if the name cannot be changed, delete it. Say why in the conversation either way — the list carries the fact, not the reason. If Phase 3 decides no doc is warranted, that is task 5. If the 0.1c handoff is accepted mid-dialogue, clear the list entirely — `ce-pov` runs the rest of the session. A task you find yourself skipping routinely is misnamed: it encodes a branch rather than an outcome, so rename it to what happens in the common case.
+
+The list is a view for the user, not an instruction to you. It does not change when a phase runs or what that phase requires, and it never substitutes for a phase's own exit condition.

package/skills/ce-brainstorm/references/plan-write.md

@@ -0,0 +1,32 @@
+# Phase 3: capture the requirements-only unified plan
+
+### Phase 3: Capture the Requirements-Only Unified Plan
+
+Write or update a requirements-only unified plan only when a file is warranted — see `references/brainstorm-sections.md` "Decide whether a doc is warranted at all" for the condition and the bug-fix stress test. Otherwise the chat paragraph from Phase 2.5 is the result and the decisions flow downstream (ce-plan's prompt, commit message, <root>/solutions/) without a brainstorm artifact in the middle.
+
+When a doc is warranted, compose it using:
+
+- `references/brainstorm-sections.md` — section contract (unified plan skeleton contract, Product Contract hard floor, include-when-material catalog, agency rules, ID conventions).
+- The format-specific rendering reference for the `OUTPUT_FORMAT` resolved at Phase 0.0 — read `references/markdown-rendering.md` (md) or `references/html-rendering.md` (html) **now**, before composing. It defines how the format presents the sections and was deliberately deferred from Phase 0.0; composing without it produces format drift the section contract alone cannot prevent.
+
+Session-settled decisions land in the Product Contract's Key Decisions section carrying their `session-settled:` annotation (shape in `references/settled-decisions.md`), so `ce-plan` enrichment inherits the label into plan KTDs.
+
+If the grounding scout's gist listed any `pack:<id>` matches, read those entries in the dossier and cite each requirement or decision they shaped with `(pack: <id>, <path within the pack>)` (shape in `references/brainstorm-sections.md` Sources / Research). A pack quote that shaped nothing is not cited, and a Product Contract that used none never mentions packs.
+
+**Write tight.** A section being material is not license to pad it. Hold every kept section to the prose-economy discipline in `references/brainstorm-sections.md`: lead with the decision or outcome, one idea per sentence, a requirement is intent plus at most one qualifier, defer forks to Outstanding Questions rather than specifying both arms, resolve superseded text in place rather than stacking strata.
+
+`SKILL.md` states the artifact contract — path shape, frontmatter fields, title, and the Goal-Capsule-plus-Product-Contract body — and it is not restated here. What this step adds: do not allocate a daily sequence number; reserve the candidate path atomically with exclusive creation, retrying the smallest available numeric collision suffix (`-2`, `-3`, …) before the extension rather than overwriting; the extension follows `OUTPUT_FORMAT`; the Goal Capsule holds objective, product authority, and open blockers; there is no conventional-commit prefix on the title. `references/brainstorm-sections.md` defines the artifact content rules, including repo-relative file paths inside the doc.
+
+**Ready for Planning Check.** After writing the actual file, run the four checks in `references/brainstorm-sections.md`: Complete, Consistent, Focused, and Usable by planning. Fix failures in place when the correction preserves settled intent, then rerun the failed checks. If a correction would choose or change product behavior or scope, ask one targeted question, update the artifact after the answer, and rerun the checks. When confirming in chat after the pass, report the artifact with its absolute path so the reference is clickable.
+
+#### Vocabulary Capture — after the requirements-only unified plan (only if CONCEPTS.md already exists)
+
+**Skip this step entirely if `CONCEPTS.md` does not exist at repo root** — only ce-compound and ce-compound-refresh create it.
+
+Run this **after** the approaches, the scope synthesis, and the requirements-only unified plan — that is where the canonical term often gets chosen or corrected, so capturing during early dialogue (before this point) would miss the final resolved name. If it exists, scan the full dialogue and the Product Contract for **resolved** domain terms — terms where the conversation actively pinned down a precise local meaning, not terms merely mentioned in passing. **Resolved means the definition is settled, not still under discussion.** Provisional terms that may still revise stay in the conversation only.
+
+For each resolved term: if missing, add it; if present but new precision surfaced, refine it; if already consistent, no action. A term whose whole meaning an existing entry already carries is a refinement of that entry, not a new heading. Only ce-compound and ce-compound-refresh fold an existing entry; only ce-compound-refresh retires or deletes one.
+
+**Domain entities, named processes, and status concepts with project-specific meaning only.** Not file paths, class names, function signatures, or implementation decisions — `CONCEPTS.md` is a glossary, not a spec or catch-all.
+
+Follow the format set by existing entries. Apply edits silently. (If Phase 3 skipped the doc, still run this against the resolved dialogue.)

package/skills/ce-brainstorm/references/product-pressure-test.md

@@ -0,0 +1,42 @@
+# Product Pressure Test — rigor-gap lenses
+
+Read this at Phase 1.2, before generating approaches. This is agent-internal analysis, not a user-facing checklist. Read the opening, note which gaps actually exist, and raise only those as questions during Phase 1.3 (Collaborative Dialogue) — folded into the normal flow of dialogue, not asked as a pre-flight gauntlet. A fuzzy opening may earn three or four probes; a concrete, well-framed one may earn zero because no scope-appropriate gaps were found.
+
+Match depth to the Phase 0.3 scope.
+
+## Lightweight
+
+- Is this solving the real user problem?
+- Are we duplicating something that already covers this?
+- Is there a clearly better framing with near-zero extra cost?
+
+## Standard — scan for these gaps
+
+- **Evidence gap.** The opening asserts want or need, but doesn't point to anything the would-be user has already done — time spent, money paid, workarounds built — that would make the want observable. When present, ask for the most concrete thing someone has already done about this.
+
+- **Specificity gap.** The opening describes the beneficiary at a level of abstraction where the agent couldn't design without silently inventing who they are and what changes for them. When present, ask the user to name a specific person or narrow segment, and what changes for that person when this ships.
+
+- **Counterfactual gap.** The opening doesn't make visible what users do today when this problem arises, nor what changes if nothing ships. When present, ask what the current workaround is, even if it's messy — and what it costs them.
+
+- **Attachment gap.** The opening treats a particular solution shape as the thing being built, rather than the value that shape is supposed to deliver, and hasn't been examined against smaller forms that might deliver the same value. When present, ask what the smallest version that still delivers real value would look like.
+
+Plus these synthesis questions — not gap lenses, product-judgment the agent weighs in its own reasoning:
+- Is there a nearby framing that creates more user value without more carrying cost? If so, what complexity does it add?
+- Given the current project state, user goal, and constraints, what is the single highest-leverage move right now: the request as framed, a reframing, one adjacent addition, a simplification, or doing nothing?
+
+Favor moves that compound value, reduce future carrying cost, or make the product meaningfully more useful or compelling. Use the result to sharpen the conversation, not to bulldoze the user's intent.
+
+## Deep — Standard lenses and synthesis questions plus
+
+- Is this a local patch, or does it move the broader system toward where it wants to be?
+
+## Deep — product — Deep plus
+
+- **Durability gap.** The opening's value proposition rests on a current state of the world that may shift in predictable ways within the horizon the user cares about. When present, ask how the idea fares under the most plausible near-term shifts — and push past rising-tide answers every competitor could make.
+
+- What adjacent product could we accidentally build instead, and why is that the wrong one?
+- What would have to be true in the world for this to fail?
+
+These questions force an explicit product thesis and feed the Scope Boundaries subsections ("Deferred for later" and "Outside this product's identity") and Dependencies / Assumptions in the Product Contract.
+
+Phase 1.3 decides how these gaps are asked as probes: each scope-appropriate gap found here becomes a separate open-ended probe (the "when present, ask..." line is the probe), asked progressively but all probed before Phase 2 (Explore Approaches).