diff --git a/AGENTS.md b/AGENTS.md index f7c2e5eff..0da037268 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -235,8 +235,8 @@ This applies equally to any platform's variables — a skill converted from Code ## Repository Docs Convention -- **Requirements** live in `docs/brainstorms/` — requirements exploration and ideation. -- **Plans** live in `docs/plans/` — implementation plans and progress tracking. +- **Plans** live in `docs/plans/` — unified plan artifacts. New `ce-brainstorm` outputs are requirements-only unified plans (`artifact_readiness: requirements-only`); `ce-plan` enriches them to implementation-ready plans (`artifact_readiness: implementation-ready`). Historical `docs/brainstorms/*-requirements.*` files remain readable legacy inputs and should not be migrated just because a new plan is created. +- **Brainstorm evidence / legacy requirements** may live in `docs/brainstorms/` — historical requirements docs and specialized analysis artifacts such as `docs/brainstorms/riffrec-feedback/`. Do not treat this as the canonical output path for new `ce-brainstorm` artifacts. - **Solutions** live in `docs/solutions/` — documented solutions to past problems (bugs, best practices, workflow patterns), organized by category with YAML frontmatter (`module`, `tags`, `problem_type`). Relevant when implementing or debugging in documented areas. - **Specs** live in `docs/specs/` — target platform format specifications. diff --git a/README.md b/README.md index 51b3ed613..9859a37cd 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Traditional development accumulates technical debt. Every feature adds complexit Compound engineering inverts this. 80% is in planning and review, 20% is in execution: -- Plan thoroughly before writing code with `/ce-brainstorm` and `/ce-plan` +- Plan thoroughly before writing code with `/ce-brainstorm` and `/ce-plan` using one readiness-based plan artifact - Review to catch issues and calibrate judgment with `/ce-code-review` and `/ce-doc-review` - Codify knowledge so it is reusable with `/ce-compound` - Keep quality high so future changes are easy @@ -30,9 +30,9 @@ The core loop is six steps: **brainstorm** the requirements, **plan** the implem | Skill | Purpose | |-------|---------| -| `/ce-brainstorm` | Interactive Q&A to think through a feature or problem and write a right-sized requirements doc | -| `/ce-plan` | Turn the requirements into a detailed implementation plan with guardrails | -| `/ce-work` | Execute the plan with worktrees and task tracking | +| `/ce-brainstorm` | Interactive Q&A to think through a feature or problem and write a requirements-only unified plan before planning | +| `/ce-plan` | Enrich feature ideas or requirements-only plans into implementation-ready plans | +| `/ce-work` | Execute implementation-ready plans with worktrees and task tracking | | `/ce-simplify-code` | Refine the freshly written code for clarity and reuse before review | | `/ce-code-review` | Multi-agent review against the plan before merging | | `/ce-compound` | Capture the learning into `docs/solutions/` so the next loop starts smarter | diff --git a/docs/plans/2026-06-18-001-refactor-unified-plan-doc-artifact-plan.md b/docs/plans/2026-06-18-001-refactor-unified-plan-doc-artifact-plan.md new file mode 100644 index 000000000..748434cc2 --- /dev/null +++ b/docs/plans/2026-06-18-001-refactor-unified-plan-doc-artifact-plan.md @@ -0,0 +1,761 @@ +--- +title: "refactor: Unify brainstorm and plan artifacts" +type: refactor +date: 2026-06-18 +--- + +# refactor: Unify brainstorm and plan artifacts + +## Summary + +Unify `ce-brainstorm` and `ce-plan` around one canonical document in `docs/plans/`: a requirements-first plan skeleton that `ce-plan` later enriches in place with technical decisions, implementation units, verification, and goal-mode completion criteria. + +This preserves the current WHAT/HOW workflow separation in the skills while removing the artifact split that causes requirements drift, weak shareability, and inefficient traceability. + +--- + +## Problem Frame + +Today `ce-brainstorm` writes a requirements document under `docs/brainstorms/`, and `ce-plan` writes a separate implementation plan under `docs/plans/`. That mirrors common human documentation practice, but it creates a fragile handoff for agents: the implementation agent primarily reads the plan, the requirements live elsewhere, and later requirement changes can drift from the technical plan. + +The proposed change makes "plan" mean the whole decision artifact: product contract, scenarios, technical planning, implementation units, and definition of done. `ce-brainstorm` creates the artifact when requirements exploration is warranted; `ce-plan` can either enrich that artifact or create the same artifact directly when brainstorming is skipped. + +--- + +## Requirements + +**Unified artifact** + +- R1. `ce-brainstorm` writes a requirements-first unified plan document under `docs/plans/`, not a new canonical `docs/brainstorms/*-requirements.*` document. +- R2. `ce-plan` enriches an existing unified plan in place when invoked from `ce-brainstorm`, preserving product decisions and stable IDs. +- R3. `ce-plan` still works as a direct entry point and can create a unified plan with both product and technical sections from a bare request. +- R4. Existing legacy brainstorm documents and plans with `origin: docs/brainstorms/...` continue to resolve indefinitely. +- R4a. Brainstorm-sourced unified plans carry an origin-equivalent metadata field so reviewers can distinguish `ce-brainstorm` product contracts from greenfield `ce-plan` bootstraps. + +**Agent execution quality** + +- R5. The unified document uses stable section headings and a `Goal Capsule` near the top so downstream agents wayfind by heading scan and route themselves without reading the whole file. +- R6. The document includes a `Definition of Done` section with global and per-unit completion criteria suitable for `/goal` or equivalent long-running workflows. +- R7. The launch prompt for an artifact's current readiness is **emitted by the skill at handoff** — printed as a copyable `/goal` prompt on hosts where `/goal` is user-typed (Claude Code), or started directly via a callable goal tool (Codex `create_goal`). It is **not** baked into the document as a section, so it never goes stale as the template evolves. The single source is `ce-work`'s `references/execution-engines.md`. +- R7a. `ce-plan` may offer to kick off that launch prompt only when the output has a concrete goal-shaped deliverable, done criteria, and stop condition. Implementation-ready code plans get implementation goals; approach-plans and "plan for a plan" outputs may get planning or knowledge-work goals, but never a code-execution goal unless the accepted deliverable is itself a software implementation plan. +- R8. Each implementation unit remains self-contained enough that a subagent can execute that unit after reading the `Goal Capsule`, `Definition of Done`, and that unit. +- R8a. Implementation-ready plan docs include repo-specific verification commands, quality gates, and test scenarios discovered during planning; the emitted launch prompt must not depend on the launching agent already knowing the repo's test commands or review conventions. + +**Format and workflow compatibility** + +- R9. Markdown and HTML output modes remain supported as exclusive alternatives, with HTML gaining stronger navigation for longer unified artifacts. +- R10. `ce-work`, `ce-doc-review`, `ce-proof`, `ce-code-review`, and docs pages understand the unified artifact and do not misclassify a requirements-only plan skeleton as execution-ready. +- R10a. `ce-work` may use goal-mode as an implementation engine when the host exposes a callable goal tool (Codex `create_goal`), while retaining `ce-work` ownership of implementation-engine selection, bounded plan reading, unit execution, and standalone quality gates. `create_goal` sets the active objective for the current session, so it is used standalone, never in return-to-caller (which must return control). +- R10b. `lfg` always invokes `ce-work` for implementation after `ce-plan` produces an implementation-ready code plan. `ce-work`, not LFG, decides whether to execute inline, with subagents, or with goal-mode. LFG's changes are limited to unified-plan readiness gating, explicit plan-path handoff, return-to-caller invocation, and post-`ce-work` pipeline continuation. +- R10c. `ce-work` supports a return-to-caller mode for LFG: it implements and verifies the plan, then returns control so LFG can run its larger simplify/review/test/PR/CI pipeline without duplicating `ce-work`'s standalone handoff. +- R10d. `ce-work` treats dynamic workflows / ultracode-style orchestration as a distinct execution engine from goal-mode when the host platform supports it. +- R10e. Adjacent skills with plan discovery or brainstorm handoffs, including `ce-work-beta`, `ce-ideate`, and `ce-riffrec-feedback-analysis`, are either updated or explicitly documented as out of scope with a guard. +- R11. Tests enforce the new single-artifact contract, legacy compatibility, heading-scan wayfinding, skill-emitted launch behavior, and downstream discovery behavior. + +--- + +## Key Technical Decisions + +- **Keep one canonical artifact under `docs/plans/`:** This aligns with `ce-work`, which already treats plan documents as the execution source, and avoids teaching every downstream skill to stitch together two files. +- **Use readiness metadata, not mutable progress status:** Add explicit artifact-shape metadata such as `artifact_contract: ce-unified-plan/v1`, `artifact_readiness: requirements-only|implementation-ready`, and `product_contract_source`, but do not introduce an execution `status:` lifecycle. Progress still lives in git, task trackers, commits, and final summaries. +- **Replace `origin:` with an origin-equivalent only for new unified artifacts:** New brainstorm-sourced unified plans should use `product_contract_source: ce-brainstorm`. Direct `ce-plan` bootstraps should use `product_contract_source: ce-plan-bootstrap`. Legacy plans keep `origin: docs/brainstorms/...`, and readers must continue to resolve that field. +- **Retain legacy `docs/brainstorms/` as read-only historical input:** Do not migrate or rewrite old brainstorm documents. `ce-plan` and reviewers should search both legacy requirements docs and unified plan docs during the transition. +- **Top-load the reader contract:** The first screen of the document must tell agents what to read for their role. Long documents are acceptable only if readers can avoid loading appendices and unrelated sections. +- **Make the document the authority; emit the launch prompt, don't bake it:** The launch prompt is generated by the skill at handoff (a copyable `/goal` on Claude Code, or `create_goal` on Codex) from a single living template — it is **not** a section in the document. The durable authority for scope, decisions, verification, and completion lives in the document body, because any goal or agent that reads the plan uses those sections after the initial prompt is forgotten or summarized. Baking a rendered prompt into each doc would only let it drift from the current template as the template evolves. +- **Make completion criteria visible prose, not hidden machine data:** The goal and DoD sections should be normal markdown or visible HTML so humans and agents consume the same authority. +- **Do not let brainstorm leak implementation detail:** The unified artifact can be plan-shaped before it is implementation-ready, but `ce-brainstorm` still owns product behavior, scope, scenarios, and success criteria only. +- **Make verification portable:** `ce-plan` must write concrete repo-specific commands and quality gates into the plan from local research, such as `bun test`, `bun run release:validate`, `pytest`, `npm test`, `rails test`, lint/typecheck commands, review requirements, and any skill-specific validation like `skill-creator`. A goal launched weeks later should not need to infer the test suite from scratch. +- **Gate launch behavior by goal kind:** The unified contract applies to code implementation artifacts. `ce-plan` also supports universal planning, answer-seeking, and approach-altitude "plan for a plan" outputs; those are valid `ce-plan` outcomes and some can be goal-shaped, but they must not invent a third unified readiness state such as `artifact_readiness: approach-plan`. Implementation launch offers require both `execution: code` and `artifact_readiness: implementation-ready`. Planning or knowledge-work launch offers require a saved approach-plan with a concrete deliverable, authority sources, done criteria, and a stop condition. +- **Probe for a callable goal tool, not a command name:** The literal `/goal` slash command is not skill-invocable on any host. Codex exposes a callable goal **tool** (`create_goal`/`update_goal`) that a skill can use to start a goal directly; Claude Code exposes no goal tools at all (confirmed empirically). So skills probe for the tool: where present (Codex), call `create_goal` to start the goal in the current session; where absent (Claude Code), emit a copyable `/goal` prompt for the user to paste, or fall back to inline/subagent/dynamic-workflow execution. `create_goal` sets the current session's active objective — it is not a background worker and returns no awaitable envelope — and the working session marks completion via `update_goal`, so the launching skill does not call `update_goal` itself. +- **Keep blank discovery conservative:** Blank `ce-work` must not silently skip a newest requirements-only, knowledge-work, or approach-plan artifact to execute an older implementation plan. Auto-execution should require an implementation-ready code artifact or an unambiguous user-supplied path/match. +- **Keep one owner for the tail:** Simplification, review, PR, and CI can belong to a top-level goal/dynamic workflow, standalone `ce-work`, or LFG, but not more than one at the same time. Launch prompts and skill modes must declare whether they are implementation-only or end-to-end. +- **Default Claude Code launch to `/goal`, escalate to `ultracode` only by shape:** For implementation-ready unified plans, the normal Claude Code recommendation is `/goal` because the plan already supplies the objective, authority, U-ID decomposition, and DoD. Recommend a dynamic workflow / `ultracode:` prompt only when the plan needs script-owned orchestration: many independent U-IDs, codebase-wide sweeps, large migrations, adversarial cross-checking, or multi-angle research/planning where intermediate results should stay out of the main context. + +--- + +## Proposed Unified Document Contract + +Required top-level shape for markdown: + +```markdown +--- +title: Example capability - Plan +type: feat +date: 2026-06-18 +artifact_contract: ce-unified-plan/v1 +artifact_readiness: requirements-only # requirements-only | implementation-ready +product_contract_source: ce-brainstorm # ce-brainstorm | ce-plan-bootstrap | legacy-requirements +execution: code # optional; same semantics as today +--- + +# Example capability - Plan + +## Goal Capsule +## Product Contract +## Planning Contract # implementation-ready only +## Implementation Units # implementation-ready only +## Verification Contract # implementation-ready only +## Definition of Done # implementation-ready, optional draft in requirements-only +## Sources & Research +## Appendix +``` + +There is no `Goal Launch Block` section, and no `Reader Index`: the launch prompt is skill-emitted at handoff (copyable `/goal` on Claude Code, `create_goal` on Codex) from `ce-work`'s `references/execution-engines.md`, and consumers wayfind by scanning the stable section headings (markdown) or `

`–`

`/anchor ids (HTML) rather than from an in-doc index. A requirements-only artifact is slim: `Goal Capsule` + `Product Contract` only; `ce-plan` adds the implementation sections when it enriches in place. + +`artifact_readiness: requirements-only` means the artifact is not yet executable by `ce-work`. `artifact_readiness: implementation-ready` means `ce-plan` has supplied implementation units, verification, and DoD material. These are document-readiness values, not work-progress values; tests should reject progress words such as `active`, `in_progress`, `completed`, or `done`. + +This contract is for software implementation plans. Universal-planning outputs and approach-plans should keep their domain-appropriate formats unless the deliverable itself is a software implementation plan. In those modes, `ce-plan` can still produce strong plans, but it must not label them `artifact_contract: ce-unified-plan/v1` unless they include the Product Contract, Planning Contract, Implementation Units, and Definition of Done required for code execution. + +HTML must render the same metadata visibly in the document header and provide persistent navigation to each major section. For long unified HTML artifacts, the left or top navigation should distinguish "Read first", "Product", "Planning", "Units", "Done", and "Appendix" rather than presenting a flat heading list. + +--- + +## Section Semantics + +### Section ID Registry + +The unified artifact contract needs a stable section registry so consumers know what to grep before reading the whole document. This registry belongs in the skill instructions and rendering references, not only inside generated documents. + +| Logical section | Markdown heading | HTML id | Grep / selector hint | +|---|---|---|---| +| Goal Capsule | `## Goal Capsule` | `goal-capsule` | `^## Goal Capsule$` / `#goal-capsule` | +| Product Contract | `## Product Contract` | `product-contract` | `^## Product Contract$` / `#product-contract` | +| Product Requirements | `### Requirements` under Product Contract | `product-requirements` | nearest `### Requirements` after Product Contract / `#product-requirements` | +| Planning Contract | `## Planning Contract` | `planning-contract` | `^## Planning Contract$` / `#planning-contract` | +| Implementation Units | `## Implementation Units` | `implementation-units` | `^## Implementation Units$` / `#implementation-units` | +| Unit | `### U. ` | `u` | `^### U[0-9]+\\.` / `[id^="u"]` | +| Verification Contract | `## Verification Contract` | `verification-contract` | `^## Verification Contract$` / `#verification-contract` | +| Definition of Done | `## Definition of Done` | `definition-of-done` | `^## Definition of Done$` / `#definition-of-done` | +| Appendix | `## Appendix` | `appendix` | `^## Appendix$` / `#appendix` | + +HTML rendering must make these ids visible as normal anchors on section elements. Do not rely on hidden JSON, duplicate metadata, or data attributes as the primary reader contract. + +### Reader Strategy + +The document does not teach efficient reading by itself. Consuming skills must carry the read algorithm before they open the file. The stable section **headings** (markdown) and anchor ids (HTML) are the extraction target; the consumer scans them to wayfind rather than reading the whole file. + +Every consuming skill that accepts a unified plan should use this order: + +1. **Pre-read only metadata and heading map.** + - Markdown: read the YAML frontmatter plus the first screen, then run a heading scan equivalent to `rg -n '^(#|##|### U[0-9]+\\.)' `. + - HTML: read the visible metadata/header region, then scan for the section ids in the Section ID Registry. +2. **Classify artifact readiness.** + - If `artifact_readiness: requirements-only`, execution skills stop and route to `ce-plan`. + - If `artifact_readiness: implementation-ready`, execution skills continue. + - If metadata is absent, fall back to legacy plan behavior. +3. **Extract role-specific sections by heading range.** + - Do not read the entire unified document first unless the file is small or the role genuinely requires full-document review. + - Read appendices only when a selected section explicitly cites them or the user asks for source detail. +4. **Escalate only on ambiguity.** + - If heading extraction fails, metadata conflicts with content, or a required section is missing, then read wider context and report the contract problem. + +Role-specific defaults: + +| Consumer | First sections to read | Skip by default | Escalate when | +|---|---|---|---| +| `ce-plan` enriching a skeleton | Metadata, Goal Capsule, full Product Contract, Open Questions, cited Sources | Appendix details and unrelated legacy docs | Product Contract conflicts with repo research or planning needs missing product decisions | +| `ce-work` executing | Metadata, Goal Capsule, Definition of Done, Verification Contract, Implementation Units heading list, first candidate U-ID | Appendix, full Product Contract, unrelated U-IDs | Plan is requirements-only, active unit references an R/F/AE/KTD not yet read, verification cannot be assessed, or no supported execution engine is available | +| `lfg` pipeline | Metadata, artifact readiness, execution mode, plan path, Definition of Done availability | Interactive menus, HTML artifacts, universal/approach outputs unless explicitly pipeline-safe | `ce-plan` did not produce an implementation-ready code plan, no plan path is discoverable, or `ce-work` cannot be invoked | +| `ce-doc-review` | Metadata, Goal Capsule, then reviewer-specific section slices | Sending the full document to every persona | A consistency reviewer needs cross-section trace or a section slice is insufficient | +| `ce-code-review` | Metadata, Product Contract > Requirements, Verification Contract, Definition of Done, implemented U-IDs from PR body or branch context | Full plan body and appendices | Requirements are nested unexpectedly or PR claims work outside cited U-IDs | +| `ce-proof` | Metadata and title only for publishing label, then full file as publish payload | None for upload payload | Publishing label or format cannot be determined | + +Wayfinding is size-aware: a short plan (lightweight or requirements-only) can be read in full, but for a long implementation-ready plan the skills must locate sections with heading/anchor scans and read only the needed ranges before doing expensive full reads. + +For `ce-work`, the same rule must apply to subagent dispatch. The parent should pass the plan path plus a compact packet containing Goal Capsule, Definition of Done, the selected U-ID section, and any referenced R/F/AE/KTD excerpts. It should not send "read the whole plan file" as the default worker prompt for unified artifacts. + +Blank `ce-work` discovery must be conservative. The newest matching `docs/plans/*` file should be classified before execution. If the newest artifact is `artifact_readiness: requirements-only`, `execution: knowledge-work`, an approach-plan, or an unclassified universal plan, blank `ce-work` should stop and explain the required explicit path or next planning step. It should not silently fall back to an older implementation-ready plan unless the user supplied an unambiguous path, branch context, or keyword that identifies that older plan. + +`ce-work` may choose an implementation engine after it has classified an implementation-ready code plan: + +- **Inline/subagent engine:** current default. `ce-work` owns task creation, unit sequencing, subagent dispatch, verification, review escalation, commits, and handoff. +- **Goal-mode engine:** available only when the host exposes a callable goal tool (Codex `create_goal`). `create_goal` sets the active objective for the **current session** — it is not a background worker and returns no awaitable summary — so the session itself continues toward the DoD, and the goal lifecycle marks completion (`ce-work` does not call `update_goal`). Because it steers the current session, goal-mode is for standalone use only, never return-to-caller (which must return control). On hosts with no goal tool (Claude Code), `ce-work` emits a copyable `/goal` prompt for the user or runs inline/subagents instead of trying to call anything internally. The goal must not open the PR, finalize the session, or bypass the owning workflow's gates. +- **Dynamic-workflow engine:** available only when the host platform exposes a callable dynamic workflow / ultracode-style orchestration primitive. Prefer this over goal-mode for large fan-out plans, many independent U-IDs, cross-checking loops, or migrations where intermediate worker state should live outside the main conversation. Claude Code dynamic workflows are triggered by user prompt opt-in such as `ultracode:` or by `/effort ultracode`; skills should output a prompt block for the user rather than trying to start the workflow internally. Dynamic workflows must return structured results and blockers; they must not require mid-run user decisions. + +Because `create_goal` steers the current session rather than dispatching a separate worker, goal-mode is used only in standalone `ce-work`: the session works toward the DoD and then continues through `ce-work`'s normal post-implementation quality gates and handoff. Return-to-caller mode (LFG) never uses `create_goal` — it must return a structured envelope to LFG, so it runs inline/subagents and returns control before simplify/review/PR/CI. Goal-mode is a way to get better sustained implementation focus, not a way to skip the owning workflow's finish discipline. + +Return-to-caller invocation should be explicit, for example `ce-work mode:return-to-caller ` or `ce-work caller:lfg `. `ce-work` should parse the mode before normal input triage, execute implementation units and relevant local verification, then return a structured summary containing: status, plan path, changed files beyond the plan, U-IDs attempted/completed, verification commands/results, blockers, whether behavior changed, and confirmation that the standalone shipping tail was skipped. + +Tail ownership profiles: + +| Profile | Owner | Includes simplify/review/PR/CI? | Use when | +|---|---|---|---| +| Implementation-only engine | `ce-work` under LFG or another caller | No; return to caller before tail | LFG will run `ce-simplify-code`, `ce-code-review`, PR, and CI itself. | +| Standalone `ce-work` | `ce-work` | Yes for `ce-work`'s normal quality/handoff gates | User invoked `ce-work` directly or `ce-plan` handed off interactively. | +| Top-level `/goal` | Goal runner | Yes when the prompt says the goal owns quality gates | User manually launches a goal from the plan and no wrapper will run those gates afterward. | +| E2E dynamic workflow | Workflow script | Yes, if encoded in the script and returned as structured evidence | Host supports ultracode/dynamic workflows and the workflow is intended to replace, not sit inside, LFG. | + +If a top-level goal or dynamic workflow owns simplification/review/PR/CI, LFG should not run those same steps afterward. Conversely, if LFG is the caller, the goal or workflow launched beneath `ce-work` should be implementation-only so LFG can run its deterministic outer pipeline. + +Claude Code launch decision for generated docs: + +| Plan shape | Recommended Claude Code launch | Why | +|---|---|---| +| Normal implementation-ready plan with sequential or modest U-ID decomposition | `/goal` | The plan already defines the end condition; `/goal` keeps turns going until the DoD is visibly satisfied. | +| Large fan-out plan with many independent U-IDs or broad codebase sweep | `ultracode:` dynamic workflow | Workflow scripts hold branching, loops, and intermediate results outside the main context and can coordinate many agents. | +| Hard planning/research artifact needing several independent angles before committing | `ultracode:` dynamic workflow | Workflows can cross-check findings and synthesize competing drafts before reporting. | +| LFG/autopilot pipeline | LFG -> `ce-work mode:return-to-caller` | LFG owns the outer shipping tail; `ce-work` owns implementation strategy. | +| Host without callable/top-level goal or workflow support | `ce-work` fallback prompt | Preserve the same heading-scan / DoD / U-ID discipline without relying on unavailable host features. | + +The generated document should name one recommended Claude Code launch path, not present `/goal` and `ultracode:` as equally likely choices. It may include the non-recommended alternative under "Advanced / large-scale option" only when the plan shape plausibly warrants it. + +For `lfg`, the unified artifact is not a launch menu. It is a machine gate between `ce-plan` and `ce-work`. LFG should invoke `ce-plan`, record the produced plan path, inspect metadata/readiness, and proceed only when the artifact is an implementation-ready code plan. It should then invoke `ce-work` with the exact plan path in return-to-caller mode. It should not look for a launch prompt in the doc, should not rely on `ce-plan`'s interactive post-generation offer, should not launch `/goal` directly, and should not auto-run implementation on a requirements-only skeleton, universal plan, answer, or approach-plan unless that path explicitly created an implementation-ready software plan first. + +After `ce-work` returns, LFG must verify implementation changed files beyond the plan and continue its own downstream pipeline: run `ce-simplify-code` when applicable, run `ce-code-review mode:agent plan:`, apply eligible review fixes, run browser tests, commit/push/open PR, and watch CI. The goal-mode decision is centralized inside `ce-work`; LFG remains the outer autonomous shipping pipeline. + +### Launch prompts (emitted at handoff) + +The launch prompt is **not a section in the artifact**. It is generated by the skill at handoff — printed as a copyable block on Claude Code, or passed to `create_goal` on Codex — from a single living template (`ce-work`'s `references/execution-engines.md`). It is readiness-specific: a planning prompt for requirements-only, an implementation prompt for implementation-ready. + +Each emitted prompt stays thin. It names the action, path, read order, tail profile, and stop condition, then points into the document's sections rather than duplicating requirements, implementation details, full verification matrices, or product rationale — the plan body is the authority. + +For `artifact_readiness: requirements-only`, the emitted prompt routes to planning, not execution: + +```text +/goal Enrich docs/plans/example-plan.md into an implementation-ready plan. + +Use the Product Contract as authority. Produce Planning Contract, Implementation Units, Verification Contract, and Definition of Done. Do not implement code. If open product questions would change behavior, stop and report the exact questions instead of inventing scope. +``` + +For `artifact_readiness: implementation-ready` with `execution: code`, the emitted prompt routes to implementation and declares which tail profile owns quality gates. Generated handoffs prefer a standalone top-level prompt for humans and an implementation-only prompt for skill callers that need an internal engine. + +```text +/goal Implement docs/plans/example-plan.md through its Definition of Done. + +First read: Goal Capsule, Definition of Done, and the Implementation Units heading map (scan headings to find sections; do not read the whole plan). Work unit-by-unit. For each U-ID, read only that unit plus referenced R/F/AE/KTD sections. Track progress outside the doc. + +This top-level goal owns implementation quality gates. Run simplification and code review when the plan or diff meets the repo's normal criteria, apply eligible fixes, and surface any residual findings. Do not open a PR unless the prompt explicitly requests a shipping goal. + +The condition is satisfied when the transcript shows: all non-deferrable U-IDs are completed; each Per-Unit DoD row has an observed verification result; required repo checks passed or are documented as not applicable; applicable simplification/review gates ran or were explicitly skipped with reason; no plan body progress/status was written; and no PR was opened by this goal. Stop early only when a named blocker prevents completion. +``` + +When a skill caller needs an internal implementation engine, use a shorter implementation-only variant: + +```text +/goal Implement docs/plans/example-plan.md as an implementation-only engine for the owning workflow. + +Read Goal Capsule, Definition of Done, and active U-IDs (scan headings to find them). Complete implementation and local verification only. Do not run simplification, code review, PR creation, CI watching, or final handoff; return a summary with changed files, U-IDs completed, verification results, and blockers so the owning workflow can run its tail. +``` + +Fallback when callable goal-mode is unavailable: + +```text +Use ce-work on docs/plans/example-plan.md. + +First classify artifact_readiness and execution mode. If implementation-ready code, scan headings and read Goal Capsule, Definition of Done, and the Implementation Units heading map (not the whole doc) before choosing inline, subagent, or dynamic-workflow execution. Preserve U-ID references, read only active-unit sections plus cited R/F/AE/KTD excerpts, and finish through the owning workflow's tail profile. +``` + +Keep each prompt under 4,000 characters. Put the literal path in the prompt. Include an action verb, the artifact readiness assumption, the tail ownership profile, the read order, the unit strategy, and an evaluator-visible stop condition. Goal prompts should require the agent to surface verification results in the transcript before declaring completion. When goal-mode is unavailable, the fallback prompt should preserve the same read order and tail ownership semantics through `ce-work`. + +Claude Code-specific launch guidance: + +- For `/goal`, `ce-plan` or `ce-work` should print the copyable command block for the user to paste at the start of a message. Do not try to invoke `/goal` internally from a skill. +- For dynamic workflows, print a copyable prompt beginning with `ultracode:` or equivalent natural-language workflow request. Use this only when the plan shape warrants workflow orchestration rather than ordinary goal persistence. +- For normal skill-driven execution, continue with `ce-work` inline/subagents when the user does not paste the goal/workflow prompt. + +Example dynamic-workflow launch for a large fan-out plan: + +```text +ultracode: Execute docs/plans/example-plan.md as an end-to-end dynamic workflow. + +Use the plan as authority. First build a workflow around the Implementation Units and Definition of Done. Parallelize only independent U-IDs with disjoint file ownership, keep intermediate agent results inside the workflow, run simplification/review/verification gates inside the workflow tail, and return a final summary with changed files, U-IDs completed, verification results, residual findings, and blockers. +``` + +For universal-planning mode, answer-seeking mode, and approach-altitude "plan for a plan" outputs, do not emit this implementation launch prompt unless the output is explicitly a software implementation plan. Those modes may still offer a `/goal` launch when the output is saved, goal-shaped, and has its own done criteria. The prompt must name the real deliverable, such as "produce the implementation plan from this approach-plan" or "execute this research plan and deliver the synthesis," not "implement code." + +After writing a plan, `ce-plan` should use this launch matrix: + +| Output classification | `ce-plan` post-output offer | +|---|---| +| Unified artifact, `artifact_readiness: requirements-only` | Offer to continue with `ce-plan` enrichment using the plan path. Do not offer execution. | +| Unified artifact, `artifact_readiness: implementation-ready`, `execution: code` | Offer to start the launch prompt (copyable `/goal` on Claude Code, `create_goal` on Codex), or to hand off to `ce-work`. | +| Universal plan, `execution: knowledge-work` | Offer a knowledge-work goal only when the saved plan has a concrete deliverable and DoD; otherwise offer the domain-appropriate next step from universal-planning. | +| Answer-seeking universal-planning output | Deliver the answer; no saved-plan launch offer. | +| Approach-altitude / plan-for-a-plan output | Offer the checkpoint choices from `references/approach-altitude.md`: execute now, save/deepen, start a planning/knowledge-work goal, or stop. Only route into code implementation if the accepted deliverable is an implementation-ready software plan. | +| LFG / pipeline caller | No interactive offer. Return the plan path, readiness, and execution mode to the caller; the caller enforces the pipeline gate and invokes `ce-work` in return-to-caller mode. | + +Approach-plans are especially good goal inputs when the expensive work is cognitive rather than code execution: reading sources, reconciling constraints, producing a PRD, producing the real implementation plan, or generating a decision memo. Their launch prompt should make the next artifact explicit and bounded: + +```text +/goal Execute docs/plans/example-approach-plan.md to produce the implementation plan it describes. + +Use the approach-plan as process authority. Produce the named deliverable only. Do not implement code. Stop when the deliverable's acceptance criteria are satisfied or when a blocker invalidates the approach. +``` + +### Goal Capsule + +Ten to twenty lines. It must summarize: + +- the outcome being pursued +- the non-negotiable scope boundaries +- the current readiness +- the next expected workflow +- the shortest route to verify done + +### Product Contract + +Former brainstorm content: + +- Summary +- Problem Frame +- Actors +- Key Flows +- Requirements +- Acceptance Examples +- Scope Boundaries +- Dependencies / Assumptions +- Open Questions + +### Planning Contract + +Former plan content, included only when `artifact_readiness: implementation-ready`: + +- Key Technical Decisions +- High-Level Technical Design +- System-Wide Impact +- Risks & Dependencies +- Documentation / Operational Notes +- Sources & Research + +### Implementation Units + +Preserve the existing `### U1. Name` unit heading contract. Required unit fields remain: + +- Goal +- Requirements +- Dependencies +- Files +- Approach +- Execution note, when material +- Patterns to follow +- Test scenarios +- Verification + +### Verification Contract + +Required once the artifact is implementation-ready. This section makes the plan portable across agents and time by recording the repo-specific verification surface discovered during planning. + +Required fields: + +| Field | Purpose | +|---|---| +| Required commands | Exact commands to run before done, such as `bun test`, `npm test`, `pytest`, `rails test`, `go test ./...`, `bun run release:validate`, lint, typecheck, or build commands. | +| Conditional commands | Commands that run only for certain surfaces, such as browser tests, Xcode tests, migrations, generated fixtures, or release validation when plugin inventory changes. | +| Quality gates | Simplification, code review, doc review, security review, or design review triggers with concrete thresholds or conditions. | +| Manual verification | Human-visible checks, screenshots, browser flows, CLI examples, generated artifact inspection, or operational validation. | +| Test coverage expectations | Happy path, edge case, error path, integration, and regression categories that apply to this plan. | +| Metric thresholds | When the goal is optimization-shaped (build time, latency, coverage, bundle size), a measurable exit threshold (e.g., "p95 latency < 200ms", "build time reduced 30%") rather than a boolean check. Route metric-driven loops to `ce-optimize`. | +| Known skips | Checks intentionally skipped and the reason the skip is acceptable. | + +The emitted launch prompt and Definition of Done should reference this section rather than relying on generic phrases like "run tests." Per-unit `Verification` fields still name local unit checks; the Verification Contract names global and conditional repo checks. A metric target is a sharper done signal for a long-running goal than a boolean check, because the goal runner re-evaluates it after each turn (Claude Code) or drives toward it autonomously over hours (Codex) — see the `/goal` guide in Sources & Research. + +### Definition of Done + +Required once the artifact is implementation-ready. Requirements-only skeletons may include a product-level draft DoD when it helps goal shaping, but should omit plan-only sections that would be empty padding. + +```markdown +## Definition of Done + +### Global DoD +- **Scope complete:** All non-deferred R-IDs are satisfied or explicitly reclassified. +- **Implementation complete:** All required U-IDs are complete or intentionally deferred. +- **Verification complete:** Each unit's Verification field has an observed result. +- **Tests complete:** Feature-bearing changes have tests for applicable happy path, edge case, failure, and integration scenarios. +- **Regression check:** Relevant repo checks pass, or remaining failures are documented as unrelated. +- **Docs / ops complete:** Required docs, config, migration, rollout, or operational notes are updated. +- **Review readiness:** No unresolved P0/P1 doc-review or code-review findings remain. +- **Cleanup complete:** Dead-end and experimental code from approaches that did not pan out is removed from the diff, not left behind (matters most for long autonomous goal runs that accumulate abandoned attempts). +- **Handoff complete:** Final summary names changed files, checks run, deferred work, and residual risks. + +### Per-Unit DoD +| Unit | Done Signal | Required Verification | Blocking Dependencies | Deferrable? | +|---|---|---|---|---| +| U1 | Concrete observable outcome | Test/manual check result | Named dependency | no | +``` + +### Legacy launch-prompt sections + +New unified artifacts contain **no** launch-prompt section — the launch prompt is skill-emitted (see "Launch prompts (emitted at handoff)"). Older docs may carry a `## Goal-Mode Prompt` or `## Goal Launch Block` section; readers treat any such section as stale and rely on the skill-emitted prompt instead, never executing a frozen in-doc prompt. + +--- + +## Implementation Units + +### U1. Define the unified artifact contract + +- **Goal:** Replace the separate brainstorm/plan artifact model with a single documented contract that both skills consume. +- **Requirements:** R1, R2, R3, R5, R6, R7, R8, R9. +- **Files:** + - Modify: `skills/ce-plan/references/plan-sections.md` + - Modify or replace: `skills/ce-brainstorm/references/brainstorm-sections.md` + - Modify: `skills/ce-plan/references/markdown-rendering.md` + - Modify: `skills/ce-plan/references/html-rendering.md` + - Mirror rendering changes into `ce-brainstorm` and `ce-ideate` reference copies if parity tests still require them. +- **Approach:** Introduce `artifact_contract: ce-unified-plan/v1`, `artifact_readiness`, `product_contract_source`, `Goal Capsule`, `Product Contract`, `Planning Contract`, `Verification Contract`, and `Definition of Done` as the new contract (the launch prompt is skill-emitted and consumers wayfind by heading scan, so neither is a section). Keep no-status language, and define readiness as document completeness rather than work progress. +- **Test scenarios:** + - Contract tests detect required metadata fields and reject `status:`. + - Contract tests reject progress-like readiness values such as `active`, `in_progress`, `completed`, and `done`. + - Contract tests require the Section ID Registry in the skill/reference instructions. + - Rendering tests require visible metadata and navigation for HTML. + - HTML rendering tests require stable ids such as `goal-capsule`, `product-contract`, `implementation-units`, and `definition-of-done`. + - Markdown tests require pure markdown, top-loaded reader sections, and no hidden machine copy. +- **Verification:** Tests identify the unified contract and no longer require a standalone requirements filename for new brainstorm outputs. + +### U2. Update `ce-brainstorm` to create plan skeletons + +- **Goal:** Make `ce-brainstorm` write the first version of the unified plan in `docs/plans/`. +- **Requirements:** R1, R2, R5, R9. +- **Files:** + - Modify: `skills/ce-brainstorm/SKILL.md` + - Modify: `skills/ce-brainstorm/references/handoff.md` + - Modify: `skills/ce-brainstorm/references/synthesis-summary.md` + - Modify tests under `tests/skills/ce-brainstorm-*` +- **Approach:** Phase 3 writes `docs/plans/YYYY-MM-DD-NNN---plan.` with `artifact_readiness: requirements-only` and `product_contract_source: ce-brainstorm`. It fills `Goal Capsule` and `Product Contract`, omits empty plan-only sections, and routes next steps to `ce-plan` with the same path. +- **Test scenarios:** + - `output:md` writes a markdown unified plan skeleton under `docs/plans/`. + - `output:html` writes an HTML unified plan skeleton with visible readiness metadata. + - Handoff to `ce-plan` passes the plan path, not a requirements path. + - Requirements-only skeletons do not claim to be executable. + - Requirements-only artifacts do not point implementers at missing `Definition of Done` or `Implementation Units` sections. + - Requirements-only artifacts emit no launch-prompt section; the next step (ce-plan enrichment) is conveyed by the handoff menu, not the doc. + - `Build it now` / direct-to-`ce-work` handoff is hidden unless a requirements-only artifact is explicitly deemed small enough to skip planning and the needed DoD is present in chat or the artifact. +- **Verification:** New tests fail if `ce-brainstorm` points new outputs at `docs/brainstorms/*-requirements.*`. + +### U3. Update `ce-plan` to enrich unified plans in place + +- **Goal:** Make `ce-plan` detect requirements-only unified plans, preserve product contract content, and enrich the same file. +- **Requirements:** R2, R3, R4, R6, R7, R8, R11. +- **Files:** + - Modify: `skills/ce-plan/SKILL.md` + - Modify: `skills/ce-plan/references/synthesis-summary.md` + - Modify: `skills/ce-plan/references/deepening-workflow.md` + - Modify: `skills/ce-plan/references/plan-handoff.md` + - Modify tests under `tests/skills/ce-plan-*` +- **Approach:** Phase 0 searches for explicit paths first, then recent unified plans with `artifact_readiness: requirements-only`, then legacy `docs/brainstorms/*-requirements.*`. When enriching, `ce-plan` updates `artifact_readiness: implementation-ready`, fills `Planning Contract`, `Implementation Units`, `Verification Contract`, and `Definition of Done`, and preserves R/A/F/AE IDs. +- **Test scenarios:** + - Direct `ce-plan` creates a complete unified plan without an origin doc. + - `ce-plan ` updates that file rather than creating a duplicate. + - Legacy `origin: docs/brainstorms/...` still resolves. + - Brainstorm-sourced unified plans use `product_contract_source: ce-brainstorm` and do not trigger greenfield/adversarial bootstrap review behavior. + - Product Contract conflicts discovered during planning become explicit questions or assumptions, not silent rewrites. + - `ce-plan` post-output menu offers to launch the goal prompt only for implementation-ready code plans; universal-planning, answer-seeking, and approach-altitude outputs keep their own handoff/checkpoint behavior. +- **Verification:** A plan sourced from a unified skeleton has origin-equivalent metadata without requiring a separate `origin:` path. + +### U4. Make downstream readers readiness-aware + +- **Goal:** Prevent downstream skills from treating requirements-only unified plans as implementation-ready. +- **Requirements:** R4, R8, R10. +- **Files:** + - Modify: `skills/ce-work/SKILL.md` + - Modify or explicitly guard: `skills/ce-work-beta/SKILL.md` + - Modify: `skills/lfg/SKILL.md` + - Modify: `skills/ce-doc-review/SKILL.md` + - Modify: `skills/ce-doc-review/references/subagent-template.md` + - Modify: `skills/ce-doc-review/references/synthesis-and-presentation.md` + - Modify: `skills/ce-proof/SKILL.md` + - Modify: `skills/ce-code-review/SKILL.md` + - Modify or document exception: `skills/ce-riffrec-feedback-analysis/SKILL.md` + - Modify or document exception: `skills/ce-riffrec-feedback-analysis/references/extensive-analysis.md` + - Modify or document exception: `skills/ce-riffrec-feedback-analysis/scripts/analyze_riffrec_zip.py` + - Modify related docs and tests. +- **Approach:** `ce-work` should route `artifact_readiness: requirements-only` files to `ce-plan` when explicitly receiving a plan, and blank `ce-work` should stop rather than silently falling back when the newest plan artifact is requirements-only, knowledge-work, approach-plan, or otherwise not implementation-ready code. For implementation-ready unified plans, `ce-work` must replace its current full-document-first read with the metadata, heading-map, Goal Capsule, DoD, and active-unit extraction strategy. `ce-work` may also choose a supported goal-mode or dynamic-workflow engine for implementation, but must resume the correct tail after implementation: standalone quality gates in normal use, or return-to-caller return when invoked by LFG. `lfg` should verify that `ce-plan` produced an implementation-ready code plan before invoking `ce-work`, pass the exact plan path to `ce-work mode:return-to-caller ` (or equivalent explicit syntax), and stop with a clear message for requirements-only, universal, answer-seeking, or approach-plan outputs that are not code-executable. `ce-doc-review` should classify unified artifacts by readiness and `product_contract_source`, reviewing Product Contract and Planning Contract with different lenses. HTML unified artifacts should remain report-only or skipped until `ce-doc-review` has a real HTML-safe mutation path; do not claim safe HTML mutation without implementing it. `ce-proof` should publish markdown unified plans only and label them by readiness; HTML unified artifacts stay on the local browser/open path. +- **Test scenarios:** + - Blank `ce-work` stops when the newest plan artifact is requirements-only, knowledge-work, approach-plan, or unclassified universal output, unless the user supplied an explicit path or unambiguous branch/keyword match. + - Explicit `ce-work ` tells the user the plan needs `ce-plan` enrichment. + - Explicit `ce-work ` still routes to the existing non-code execution carve-out. + - `ce-work` no longer instructs agents to read large unified documents completely before metadata, heading-map, Goal Capsule, DoD, and active-unit extraction. + - `ce-work` subagent prompts pass a bounded unit packet rather than only a full plan path when executing unified artifacts. + - `ce-work` can use a supported goal-mode engine for implementation, then resumes standalone review/simplification/testing/commit/handoff gates when not caller-owned. + - `ce-work` can use a supported dynamic-workflow engine for large fan-out plans and returns structured results/blockers. + - Goal-mode `ce-work` prompts are scoped to implementation only and explicitly do not open PRs, finalize handoff, or bypass the owning workflow's gates. + - Emitted launch prompts distinguish standalone top-level goals from implementation-only engine prompts, and only the standalone profile owns simplify/review gates by default. + - `lfg` stops after `ce-plan` when the produced artifact is not `artifact_readiness: implementation-ready` plus `execution: code`. + - `lfg` passes the recorded unified plan path to `ce-work` in return-to-caller mode, then to `ce-code-review mode:agent plan:` and later pipeline steps. + - `ce-work mode:return-to-caller` returns status, plan path, changed files, U-IDs attempted/completed, verification results, blockers, behavior-change signal, and confirmation that standalone shipping was skipped. + - LFG never launches `/goal` directly; when goal-mode is appropriate, `ce-work` launches it and returns control to LFG after implementation verification. + - LFG's post-`ce-work` pipeline still runs `ce-simplify-code`, `ce-code-review mode:agent plan:`, review-fix application, tests, PR, and CI watch. + - `ce-doc-review` can review requirements-only and implementation-ready markdown unified artifacts by section slice. + - HTML unified artifacts are either skipped with the current markdown-only message or reviewed in report-only mode with no mutation path. + - `ce-doc-review` routes persona agents by section slice instead of blindly sending the full unified document to every reviewer. + - `ce-doc-review` has a unified-artifact classification path distinct from legacy standalone requirements docs and legacy implementation plans. + - `ce-code-review` protects and discovers `docs/plans/*.{md,html}` and extracts requirements from `Product Contract > Requirements`, legacy top-level `## Requirements`, and legacy `## Requirements Trace`. + - `ce-code-review` classifies readiness before requirements completeness; requirements-only unified plans can inform product intent but must not trigger implementation-unit completeness findings. + - `ce-proof` publishes markdown unified artifacts with readiness-aware labels and does not try to upload HTML artifacts. + - `ce-work-beta` either matches stable `ce-work` unified-plan guards or explicitly rejects `artifact_contract: ce-unified-plan/v1` with a route to stable `ce-work`. + - `ce-riffrec-feedback-analysis` either keeps `docs/brainstorms/riffrec-feedback/` as a documented analysis-artifact exception or migrates its defaults/help text to the new convention. +- **Verification:** Downstream consumers no longer key only on path prefixes like `docs/brainstorms/`. + +### U5. Strengthen output-mode and HTML navigation behavior + +- **Goal:** Keep markdown and HTML parity while making long unified HTML documents navigable. +- **Requirements:** R9, R10. +- **Files:** + - Modify: shared `markdown-rendering.md` copies. + - Modify: shared `html-rendering.md` copies. + - Modify: `tests/skills/html-output-invariants.test.ts` + - Modify: `tests/compound-support-files.test.ts` if the parity strategy changes. +- **Approach:** Preserve exclusive output mode. Re-evaluate separate `brainstorm_output` and `plan_output` config keys because both skills now write the same artifact class. Prefer a backward-compatible config migration: keep both keys initially, but document exact enrichment precedence: explicit path format wins for in-place enrichment; explicit `output:` may convert only with a visible old-path/new-path note; pipeline mode may force markdown only by writing the canonical markdown path and leaving the HTML artifact untouched with a clear note. When a conversion or pipeline override creates same-basename `.md` and `.html` siblings, the new artifact path is canonical for later automated discovery, and the old sibling must be marked or reported as non-canonical so `ce-plan`/`ce-work` do not treat both as competing latest plans. +- **Test scenarios:** + - HTML unified plans include visible readiness metadata and a navigation region. + - Long HTML documents expose anchors for `Goal Capsule`, `Product Contract`, `Planning Contract`, `Implementation Units`, and `Definition of Done`. + - Markdown documents include the same sections without embedded HTML. + - `brainstorm_output: html` followed by `ce-plan` preserves HTML unless an explicit conversion or pipeline override applies. + - Explicit `ce-plan output:md ` documents the conversion path instead of silently forking canonical artifacts. + - Pipeline mode behavior is tested for a requirements-only HTML skeleton. + - Same-basename `.md` and `.html` siblings have one canonical discovery target after conversion or pipeline override. +- **Verification:** Existing HTML mode tests pass after being updated from requirements/plan sibling assumptions to unified plan assumptions. + +### U6. Update documentation and examples + +- **Goal:** Teach users that `ce-brainstorm -> ce-plan -> ce-work` is now one artifact moving through readiness states. +- **Requirements:** R1, R2, R3, R4, R10. +- **Files:** + - Modify: `skills/ce-ideate/SKILL.md` + - Modify: `skills/ce-ideate/references/post-ideation-workflow.md` + - Modify: `docs/skills/ce-brainstorm.md` + - Modify: `docs/skills/ce-ideate.md` + - Modify: `docs/skills/ce-plan.md` + - Modify: `docs/skills/ce-work.md` + - Modify: `docs/skills/ce-doc-review.md` + - Modify: `docs/skills/ce-proof.md` + - Modify: `docs/skills/README.md` + - Modify: `README.md` + - Modify: `plugins/compound-engineering/README.md` + - Modify: `AGENTS.md` +- **Approach:** Replace "requirements doc plus plan doc" language with readiness-based unified-plan language. Update the canonical repo convention so new brainstorm-produced unified artifacts live in `docs/plans/`, while `docs/brainstorms/` is documented as legacy/historical input that remains readable. Update `ce-ideate` handoff language so "Brainstorm one idea" points to a requirements-only unified plan, not a standalone requirements artifact. +- **Test scenarios:** + - Documentation convention tests no longer assert new brainstorm output under `docs/brainstorms/`. + - README examples show `docs/plans/...-plan.md` after both brainstorm and plan. +- **Verification:** `bun run release:validate` passes if plugin descriptions or counts change. + +### U7. Add compatibility and migration tests + +- **Goal:** Guard the refactor against the highest-risk regressions. +- **Requirements:** R4, R10, R11. +- **Files:** + - Modify: `tests/skills/ce-brainstorm-output-mode.test.ts` + - Modify: `tests/skills/ce-brainstorm-section-order.test.ts` + - Modify: `tests/skills/ce-plan-output-mode.test.ts` + - Modify: `tests/skills/ce-plan-handoff-routing.test.ts` + - Modify: `tests/pipeline-review-contract.test.ts` + - Modify: `tests/review-skill-contract.test.ts` + - Modify: `tests/skills/ce-ideate-output-mode.test.ts` + - Modify: `tests/compound-support-files.test.ts` + - Add: `tests/skills/unified-plan-artifact-contract.test.ts` + - Add or extend fixtures for markdown/HTML section extraction and same-basename canonical path selection. + - Add fixtures for requirements-only, implementation-ready, and legacy requirements artifacts. +- **Approach:** Write tests against skill prose and reference contracts because these behaviors are largely prompt-contract changes. Include fixture-driven tests where parsers or helper scripts exist. +- **Test scenarios:** + - New brainstorm output path is `docs/plans/`. + - Legacy requirements docs still appear in ce-plan discovery guidance. + - Unified artifacts include `Goal Capsule` and `Product Contract`, and, when implementation-ready, `Planning Contract`, `Verification Contract`, and `Definition of Done`. No `Goal Launch Block` or `Reader Index` section exists. + - The skill-emitted launch prompt stays thin and points to authoritative sections instead of duplicating requirements, verification, or implementation details. + - Unified artifact consumers define a pre-read algorithm before any full-document read. + - Heading scans can find major markdown sections and U-ID ranges. + - HTML extraction guidance can find visible metadata and section anchors without parsing hidden machine data. + - Section ID registry tests cover markdown headings and HTML ids for every required logical section. + - `ce-work` guidance rejects requirements-only execution. + - Blank `ce-work` does not auto-execute latest knowledge-work, approach-plan, or unclassified universal artifacts from `docs/plans/`. + - `ce-work-beta` matches stable `ce-work` unified-artifact guards or explicitly rejects unified artifacts with a route to stable `ce-work`. + - `lfg` invokes `ce-work` with an explicit return-to-caller mode and the recorded plan path. + - `ce-doc-review` guidance distinguishes Product Contract from Planning Contract. + - `ce-code-review` handles markdown and HTML unified plans and nested Product Contract requirements. + - `ce-code-review` tests cover readiness classification before requirements completeness. + - Implementation-ready fixtures include repo-specific verification commands and quality gate applicability, not generic "run tests" prose. + - `ce-ideate` handoff tests no longer assert a standalone requirements artifact from `ce-brainstorm`. + - Canonical selection tests cover same-basename `.md`/`.html` artifacts after conversion or pipeline override. +- **Verification:** `bun test` passes. + +--- + +## System-Wide Impact + +- **Docs convention:** `docs/brainstorms/` changes from the primary brainstorm output directory to a legacy/historical input surface. Update `AGENTS.md` in the implementation PR so the canonical repo convention matches the new skill behavior. +- **Skill invocation flow:** `ce-brainstorm` no longer hands a requirements file to `ce-plan`; it hands the unified plan path. +- **Auto-discovery:** Any "latest plan" behavior becomes readiness-sensitive. +- **Review behavior:** Reviewers need to know whether they are reviewing product scope, implementation plan, or both. +- **HTML behavior:** Unified HTML artifacts will be longer than current requirements or plan docs, so navigation becomes load-bearing. + +--- + +## Goal Execution Readiness + +This document is suitable for top-level `/goal` execution only if the launching agent can answer these questions from the document without inventing scope: + +| Readiness check | Required evidence in this plan | Current state | +|---|---|---| +| Concrete objective | Summary and Goal Capsule name the refactor and target artifact. | Ready | +| Authority source | Requirements, Key Technical Decisions, and System-Wide Impact define what must hold. | Ready | +| Work decomposition | Implementation Units have U-IDs, goals, files, approaches, tests, and verification. | Ready | +| Completion criteria | Global DoD and Per-Unit DoD define observable done signals. | Ready | +| Verification commands | Verification Contract and DoD name `bun test`, `bun run release:validate` when applicable, and `skill-creator` behavioral evaluation. | Ready | +| Stop conditions | The emitted launch prompt sets the stop condition (blocker, wrong naming/config migration, or unsatisfied DoD). | Ready | +| Tail ownership | The emitted standalone launch prompt owns implementation quality gates but does not open a PR. | Ready | +| Context discipline | The emitted launch prompt and the Reader Strategy tell the agent what to read first and when to avoid full-doc reads. | Ready | +| Deferred decisions | Open Questions are **non-blocking**: naming/config decisions carried sensible defaults during implementation (e.g., `requirements-only`/`implementation-ready`; both output config keys retained). Per the readiness rule, a *blocking* open question would have kept this `requirements-only`; these did not. | Ready (open questions deferred) | + +For top-level `/goal`, the launch prompt should include: + +- exact plan path +- read order +- authority hierarchy +- U-ID execution strategy +- verification commands +- explicit no-progress-mutation rule +- tail ownership profile +- stop conditions +- evaluator-visible completion condition + +If any readiness row is not satisfied, the correct goal is not "implement"; it is a planning/enrichment goal that updates the document until the row becomes satisfied. + +--- + +## Risks & Mitigations + +- **Risk: requirements-only plans are executed by mistake.** Mitigate with `artifact_readiness`, `ce-work` readiness checks, and tests. +- **Risk: readiness metadata becomes a disguised mutable status field.** Mitigate by documenting readiness as artifact completeness, not work progress, and keeping "no `status:`" tests. +- **Risk: unified docs become too large for downstream agents.** Mitigate with stable headings for heading-scan wayfinding, a top-loaded `Goal Capsule`, self-contained U-IDs, and appendix routing. +- **Risk: legacy artifacts break.** Mitigate by keeping legacy discovery and origin resolution indefinitely. +- **Risk: output config becomes confusing.** Mitigate with a backward-compatible transition and clear docs around format preservation. +- **Risk: HTML review remains weaker.** Mitigate by documenting the existing markdown-only `ce-doc-review` limitation and not overstating HTML review coverage. +- **Risk: goal-mode behavior varies by host.** Mitigate by treating goal-mode as an optional capability with a probe and fallback, not as a universal callable slash command. +- **Risk: dynamic workflows are collapsed into `/goal`.** Mitigate by modeling dynamic workflows / ultracode-style orchestration as a separate `ce-work` execution engine for large fan-out or cross-checking tasks. + +--- + +## Definition of Done + +### Global DoD + +- **Artifact contract landed:** Skill references define the unified plan contract, metadata, readiness semantics, goal launch block, reader index, goal capsule, and DoD. +- **Brainstorm flow updated:** `ce-brainstorm` writes requirements-only unified plans under `docs/plans/` and hands the same path to `ce-plan`. +- **Plan flow updated:** `ce-plan` enriches requirements-only unified plans in place and still supports direct planning plus legacy requirements docs. +- **Downstream readers updated:** `ce-work`, `lfg`, `ce-doc-review`, `ce-proof`, `ce-code-review`, `ce-work-beta`, and relevant review/adjacent flows are readiness-aware or explicitly guarded. +- **Formats preserved:** Markdown and HTML output modes both render the unified artifact with agent-readable navigation. +- **Compatibility preserved:** Historical `docs/brainstorms/*-requirements.*` documents and old `origin:` references still resolve. +- **Tests complete:** Verification Contract commands pass, including `bun test` with coverage for unified, requirements-only, implementation-ready, and legacy artifacts. +- **Release validation complete:** `bun run release:validate` passes if skill inventory, descriptions, or marketplace metadata are affected. +- **Skill behavior evaluated:** Behavioral skill changes are tested through the `skill-creator` eval workflow, not cached in-session plugin invocation. + +### Per-Unit DoD + +| Unit | Done Signal | Required Verification | Blocking Dependencies | Deferrable? | +|---|---|---|---|---| +| U1 | Unified artifact contract is documented and tested. | Contract tests pass. | Agreement on `artifact_readiness` naming. | No | +| U2 | `ce-brainstorm` writes requirements-only unified plans. | Brainstorm output-mode and handoff tests pass. | U1 contract. | No | +| U3 | `ce-plan` enriches unified plans in place. | Plan output, resume, and legacy-origin tests pass. | U1 and U2. | No | +| U4 | Downstream readers are readiness-aware. | `ce-work` and review routing tests pass. | U1 metadata. | No | +| U5 | HTML and markdown rendering support long unified docs. | HTML invariant and support-file parity tests pass. | U1 section contract. | No | +| U6 | User-facing docs describe readiness-based unified plans. | Documentation tests and `release:validate` pass. | U1-U5 final terminology. | Yes, only if docs are split into a follow-up PR | +| U7 | Migration and compatibility tests guard legacy behavior. | Full `bun test` passes. | U1-U4 behavior. | No | + +--- + +## Execution Prompt (record) + +> This is a **pre-contract meta-plan**: it *defines* the `ce-unified-plan/v1` +> contract and therefore predates it. It uses classic plan sections (Summary, +> Requirements, Key Technical Decisions, Implementation Units, Definition of +> Done) rather than the v1 registry (Goal Capsule / Product Contract / +> Planning Contract / Verification Contract). Under the contract this +> plan landed, the launch prompt is skill-emitted at handoff, not a baked +> section; the prompt below is retained only as a record of how this plan was +> executed. The read-first list names the sections this document actually +> contains. + +```text +/goal Implement docs/plans/2026-06-18-001-refactor-unified-plan-doc-artifact-plan.md through its Definition of Done. + +Read first: +1. Goal Execution Readiness +2. Summary +3. Requirements +4. Key Technical Decisions +5. Implementation Units heading map +6. Definition of Done +7. Risks & Mitigations + +Authority: +- Requirements define the behavior that must hold after the refactor. +- Key Technical Decisions define pinned design choices. +- Implementation Units define the work order and verification expectations. +- Risks & Mitigations define constraints to preserve during implementation. + +Execution rules: +- First verify the Goal Execution Readiness table is still satisfied. If not, stop and report the missing readiness row instead of implementing. +- Work unit-by-unit and preserve U-ID references in task updates and final summaries. +- Do not migrate or rewrite historical docs/brainstorms artifacts. +- Do not introduce a mutable execution status lifecycle. +- This is a top-level goal: run applicable simplification and code-review gates before declaring done, but do not open a PR. +- If implementation shows that artifact_readiness naming or config migration is wrong, stop and surface that decision before proceeding. + +Done when: +- The transcript shows every non-deferrable Per-Unit DoD row is satisfied. +- The transcript shows Global DoD is satisfied. +- The transcript shows `bun test` passed. +- The transcript shows `bun run release:validate` passed when applicable or was explicitly not applicable. +- The transcript shows applicable simplification/code-review gates ran or were explicitly skipped with reason. +- No plan body progress/status was written. +- No PR was opened by this goal. +``` + +--- + +## Rollout Strategy + +1. Land the unified artifact contract and tests first. +2. Update `ce-brainstorm` to write requirements-only unified plans. +3. Update `ce-plan` to enrich unified plans and preserve legacy requirements inputs. +4. Update downstream readers to be readiness-aware. +5. Update docs and examples. +6. Run `bun test` and `bun run release:validate`. +7. Use `skill-creator` eval workflow to test edited skill behavior from disk, because plugin skill definitions cache at session start in Claude Code. + +Do not migrate historical `docs/brainstorms/` files. They are durable records and compatibility fixtures. + +--- + +## Sources & Research + +- OpenAI Codex manual, fetched with the local `openai-docs` skill helper from `https://developers.openai.com/codex/codex-manual.md`: Codex recommends prompts include goal, context, constraints, and done criteria; Goal mode uses a persistent objective and completion criteria; subagents help isolate noisy exploration. +- Anthropic Claude Code goal docs: `https://code.claude.com/docs/en/goal`. Claude `/goal` evaluates a visible condition after each turn; effective conditions need a measurable end state, a stated check, and important constraints. +- Dominik Kundel (OpenAI), "A guide to /goal": `https://www.linkedin.com/pulse/guide-goal-dominik-kundel-webic` (also posted at `https://x.com/dkundel/status/2062650378089594955`). Codex goal mode drives toward a concrete outcome autonomously over hours/days (120+ hour runs cited). Key reinforcements adopted here: the goal prompt is direction-plus-exit-criteria and must stay short (durable scope belongs in the document, not the prompt, because long runs forget it); prefer measurable thresholds as exit criteria; provide a starting point and progress-measurement tooling; avoid pure-visual done criteria; review and remove dead-end/experimental code after completion. Codex's draft-PR progress-visibility pattern is intentionally NOT adopted — it conflicts with this plan's tail-ownership rule that the goal does not open a PR. +- Anthropic dynamic workflows docs: `https://code.claude.com/docs/en/workflows`. Dynamic workflows move orchestration into a script so intermediate results stay out of the main context. +- Anthropic Claude Code commands docs: `https://code.claude.com/docs/en/commands`. Commands are recognized at the start of a user message and include workflow controls. +- Anthropic Claude Code skills docs: `https://code.claude.com/docs/en/skills`. Skills are prompt-based instructions that Claude loads or users invoke with `/skill-name`; they are not documented as a general mechanism for invoking arbitrary slash commands from inside a skill. +- Anthropic subagent docs: `https://code.claude.com/docs/en/sub-agents`. Subagents preserve context by doing high-volume work in separate context windows and returning summaries. +- Matt Pocock `grilling` skill: `https://raw.githubusercontent.com/mattpocock/skills/main/skills/productivity/grilling/SKILL.md`. The useful pattern is one-question-at-a-time decision-tree resolution with recommended answers and codebase exploration when the code can answer. +- Matt Pocock `grill-with-docs` wrapper: `https://raw.githubusercontent.com/mattpocock/skills/main/skills/engineering/grill-with-docs/SKILL.md`. The wrapper points the grilling session at documentation-producing workflows. +- Search note: I found a separate X post about "Grill to Goal" building on Matt Pocock's `grill-me`, but not a Matt-authored `/grill-to-goal` source. The plan therefore borrows from verified `grill-me`/`grilling` mechanics rather than attributing a specific goal artifact shape to Matt. + +--- + +## Review Reconciliation + +Cursor reviewed the reader strategy through an Orca-managed `cursor` worktree and agreed with the direction, but flagged that the previous draft still treated efficient reading as too document-local. The accepted changes are: + +- Add a Section ID Registry so "what to grep" is mechanical for markdown and HTML. +- Require consumer SKILL.md files to carry the pre-read algorithm before they open unified artifacts. +- Make requirements-only artifacts avoid pointing to absent DoD or implementation sections. +- Ensure `ce-work` subagents receive bounded unit packets instead of only a full plan path. +- Add explicit `ce-doc-review` unified-artifact classification and section-slice routing. +- Extend tests around stable section IDs, HTML ids, and no-full-doc-first consumer behavior. + +Claude was requested separately through Orca-managed `claude`, but did not produce a review because the session failed with `API Error: 401 Invalid authentication credentials` after workspace trust prompts. No Claude findings were incorporated. + +Rationale: Cursor's feedback is consistent with the core design principle: the document can expose stable affordances, but skills must own the reading algorithm. The plan now treats the stable section **headings/anchors** as the extraction target, not an in-doc index, and never the source of reader behavior. + +Two additional Codex subagent reviews were run after the LFG/`ce-work` goal-mode discussion: + +- **Skill impact review:** Accepted findings that blank `ce-work` discovery must be conservative, return-to-caller needs explicit syntax and a return envelope, `ce-doc-review` HTML behavior must remain skipped/report-only until mutation is safe, and impacted scope must include `ce-work-beta`, `ce-ideate`, `ce-riffrec-feedback-analysis`, `tests/review-skill-contract.test.ts`, and same-basename output-mode tests. +- **Goal/dynamic workflow review:** Accepted findings that goal-mode must be treated as a host capability rather than a universally callable slash command, implementation launch prompts need evaluator-visible completion conditions, requirements-only enrichment goals must stop on product blockers, and dynamic workflows / ultracode-style orchestration deserve a separate engine lane from `/goal`. + +Rejected/adjusted feedback: LFG should not choose goal-mode directly. The reconciled design keeps LFG as the outer pipeline caller and centralizes implementation-engine selection inside `ce-work`; LFG invokes `ce-work` in return-to-caller mode and resumes its own pipeline afterward. + +--- + +## Open Questions + +- Should `artifact_readiness` values be exactly `requirements-only|implementation-ready`, or should the requirements value be more explicit, such as `product-contract-only`? +- Should the old `brainstorm_output` config key remain indefinitely, or should it be deprecated in favor of a unified `plan_output` key after one release? +- Should requirements-only unified plans include a draft `Definition of Done`, or should `Definition of Done` be reserved for `ce-plan` finalization? diff --git a/docs/skills/README.md b/docs/skills/README.md index 4862d59da..aaeaf9cb1 100644 --- a/docs/skills/README.md +++ b/docs/skills/README.md @@ -35,9 +35,9 @@ The steps of every engineering iteration. `/ce-ideate` runs only when you need t | Skill | Description | |-------|-------------| | [`/ce-ideate`](./ce-ideate.md) | *Optional first step* — discover strong, qualified directions worth exploring with six conceptual frames, warrant requirement, adversarial filtering | -| [`/ce-brainstorm`](./ce-brainstorm.md) | Define what something should become — collaborative dialogue, named gap lenses, right-sized requirements doc | -| [`/ce-plan`](./ce-plan.md) | Bound execution with guardrails — U-IDs, test scenarios, automatic confidence check; WHAT decisions, not HOW code | -| [`/ce-work`](./ce-work.md) | Execute against the plan's guardrails — figure out the HOW with code in front of you, ship through quality gates | +| [`/ce-brainstorm`](./ce-brainstorm.md) | Define what something should become — collaborative dialogue, named gap lenses, requirements-only unified plan | +| [`/ce-plan`](./ce-plan.md) | Bound execution with guardrails — enrich unified plans with U-IDs, test scenarios, automatic confidence check; WHAT decisions, not HOW code | +| [`/ce-work`](./ce-work.md) | Execute against implementation-ready plan guardrails — figure out the HOW with code in front of you, ship through quality gates | | [`/ce-compound`](./ce-compound.md) | Close the loop by capturing what you learned into `docs/solutions/` so the next iteration starts smarter — bug track + knowledge track | --- diff --git a/docs/skills/ce-brainstorm.md b/docs/skills/ce-brainstorm.md index a530633f8..945efc7b3 100644 --- a/docs/skills/ce-brainstorm.md +++ b/docs/skills/ce-brainstorm.md @@ -1,10 +1,10 @@ # `ce-brainstorm` -> Think through what something should become — collaboratively, one question at a time — then write a right-sized requirements doc. +> Think through what something should become — collaboratively, one question at a time — then write a right-sized requirements-only unified plan. -`ce-brainstorm` is the **definition** skill. It's a thinking partner that asks one question at a time, pressure-tests your premises against named gap lenses, explores 2-3 concrete approaches before recommending one, and produces a right-sized requirements document strong enough that planning never has to invent product behavior. +`ce-brainstorm` is the **definition** skill. It's a thinking partner that asks one question at a time, pressure-tests your premises against named gap lenses, explores 2-3 concrete approaches before recommending one, and, for software work, produces a requirements-only unified plan strong enough that planning never has to invent product behavior. -It runs equally well on software features, on entirely non-software topics (event planning, business decisions, personal-project framing, travel itineraries, naming briefs), and anywhere in between. The same one-question-at-a-time discipline; the same right-sized template; the same Synthesis Summary before any artifact lands. +It runs equally well on software features, on entirely non-software topics (event planning, business decisions, personal-project framing, travel itineraries, naming briefs), and anywhere in between. The same one-question-at-a-time discipline applies everywhere. Software brainstorms write the requirements-only unified plan artifact; non-software brainstorms stay in facilitation mode and can hand their synthesis to `ce-plan` for a domain-appropriate plan. This is the middle step in the compound-engineering ideation chain: @@ -23,9 +23,9 @@ It's also the most common standalone entry point — for any feature, decision, | Question | Answer | |----------|--------| -| What does it do? | Collaborative dialogue to clarify scope, pressure-test premises, explore approaches, and write a right-sized requirements doc | +| What does it do? | Collaborative dialogue to clarify scope, pressure-test premises, explore approaches, and write a requirements-only unified plan | | When to use it | Vague feature ideas, "let's brainstorm", multiple plausible directions, unclear scope; non-software decisions and projects | -| What it produces | Requirements doc in `docs/brainstorms/` (with R-IDs, A-IDs, F-IDs, AE-IDs in software mode) | +| What it produces | Software: requirements-only unified plan in `docs/plans/` with `artifact_readiness: requirements-only` and R/A/F/AE IDs. Non-software: chat synthesis plus optional handoff to `ce-plan`, not a software unified artifact. | | What's next | `/ce-plan`, `/ce-work` for trivial scope, doc review, or publish to Proof | --- @@ -53,7 +53,7 @@ A typical "let's brainstorm" with an AI also has shape problems: it asks five qu - **Opt-in visual probes** for decisions that are faster to judge as rough sketches than prose - **Synthesis Summary** as the last opportunity to correct scope before the doc lands - **Fresh-context claim verification** checks the doc's repo claims before it lands -- **Right-sized requirements document** with stable identifiers (R/A/F/AE) that flow into planning +- **Right-sized Product Contract** inside a unified plan with stable identifiers (R/A/F/AE) that flow into planning --- @@ -93,19 +93,19 @@ Before writing the doc, `ce-brainstorm` emits a **scoping synthesis** shaped lik ### 7. Stable identifiers that flow downstream -The requirements doc carries plan-feeding identifiers — R-IDs (Requirements), A-IDs (Actors), F-IDs (Key Flows), AE-IDs (Acceptance Examples). `ce-plan` consumes these and traces every implementation unit and test scenario back to them. Origin scope boundaries (especially "Outside this product's identity") flow through unchanged. +The Product Contract carries plan-feeding identifiers — R-IDs (Requirements), A-IDs (Actors), F-IDs (Key Flows), AE-IDs (Acceptance Examples). `ce-plan` consumes these and traces every implementation unit and test scenario back to them. Origin scope boundaries (especially "Outside this product's identity") flow through unchanged. ### 8. Universal brainstorming for non-software Building a software feature? Standard flow. Naming a product? Choosing a vacation? Deciding a career move? `ce-brainstorm` routes to a domain-agnostic facilitator that preserves the one-question-at-a-time discipline and right-sized output. -### 9. Implementation kept out of the requirements doc by default +### 9. Implementation kept out of the Product Contract by default Requirements describe **what** behavior is expected from the user's perspective. They do not describe libraries, schemas, endpoints, file layouts, or code structure — unless the brainstorm is itself about a technical or architectural decision. This keeps planning's job clean: invent the **how**, not the **what**. ### 10. Grounding and verification ride inside your think-time -On Standard and Deep brainstorms, a cheap extraction-tier scout is dispatched in the background while you answer the first question. It writes a grounding dossier — verbatim quotes with `file:line` pointers — to scratch storage and hands back a short gist, so the dialogue stays lean while the evidence stays available on demand. Before the requirements doc is written, a fresh-context verifier (a mid-tier model that never saw the dialogue) checks the doc's repo claims — absence claims, file references — against the codebase, running while you review the synthesis confirmation. Refuted claims are corrected before the doc lands; unverifiable ones become explicit assumptions. The dossier path is handed to `ce-plan` so planning starts from verified quotes instead of re-scanning. On platforms without per-agent model selection, both run on the inherited model with the same read budgets; with no subagent support at all, the skill falls back to inline scanning and verification. +On Standard and Deep brainstorms, a cheap extraction-tier scout is dispatched in the background while you answer the first question. It writes a grounding dossier — verbatim quotes with `file:line` pointers — to scratch storage and hands back a short gist, so the dialogue stays lean while the evidence stays available on demand. Before the requirements-only unified plan is written, a fresh-context verifier (a mid-tier model that never saw the dialogue) checks the Product Contract's repo claims — absence claims, file references — against the codebase, running while you review the synthesis confirmation. Refuted claims are corrected before the plan lands; unverifiable ones become explicit assumptions. The dossier path is handed to `ce-plan` so planning starts from verified quotes instead of re-scanning. On platforms without per-agent model selection, both run on the inherited model with the same read budgets; with no subagent support at all, the skill falls back to inline scanning and verification. --- @@ -117,7 +117,7 @@ The pressure test detects a specificity gap (who are these "users"?) and an atta Three approaches surface — per-notification-type mute with TTL, a global do-not-disturb schedule, mute on the rule rather than the channel — with tradeoffs and a recommendation. The Synthesis Summary reads back the shape that emerged ("per-channel mute on notification rules, 24h preset for the 3 AM support pings"), names the trade-offs made in dialogue (per-channel over per-user, mute lives on the rule), what's deferred (presence-based mute, quiet-hours schedules), and a single call-out about the rule-delete loss path. You confirm and add a 24h preset. -A right-sized requirements doc is written and the Phase 4 menu offers next steps — `/ce-plan` (recommended), agent doc review, publish to Proof, or skip-to-build for trivial scope. +A requirements-only unified plan is written under `docs/plans/` and the Phase 4 menu offers next steps — `/ce-plan` (recommended), Product Contract review, publish to Proof, or skip-to-build only for trivial scope with a sufficient Definition of Done. --- @@ -148,19 +148,19 @@ Skip `ce-brainstorm` when: | picks one survivor + carries warrant + rationale v /ce-brainstorm - | produces requirements / brief + | produces requirements-only unified plan | software mode: R-IDs, A-IDs, F-IDs, AE-IDs + scope boundaries | universal mode: a domain-appropriate brief v /ce-plan - | reads the doc as origin + | enriches the same plan to implementation-ready | R-IDs flow into Requirements; A/F/AE-IDs trace into units and tests | origin scope boundaries are preserved verbatim v /ce-work ``` -When `ce-plan` loads with a requirements doc as input, it does not re-litigate product behavior. The doc is authoritative. Plan-time decisions are about execution guardrails — not what's being built. +When `ce-plan` loads with a requirements-only unified plan as input, it does not re-litigate product behavior. The Product Contract is authoritative. Plan-time decisions are about execution guardrails — not what's being built. --- @@ -185,8 +185,8 @@ The Phase 4 handoff offers planning, agent doc review, publish to Proof, direct- | _(empty)_ | Asks for the feature description | | `` | Open-ended brainstorm | | `` | 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. | +| Existing requirements-only plan path, legacy `*-requirements.md` path, or topic | Resume offer | +| `output:html` | Write the requirements-only unified plan as a single self-contained HTML file instead of markdown. Exclusive — the artifact 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. | --- @@ -198,14 +198,14 @@ Stacking three questions per turn produces diluted answers — users pick the ea **Why does it pressure-test my premise? I just want to brainstorm.** The named gap lenses catch the most common ways feature briefs fail downstream. They fire only when the gap is actually present in your opening — a concrete, well-framed prompt may earn zero probes. -**Can I skip the requirements doc?** +**Can I skip the requirements-only plan?** Yes. The Lightweight tier and the announce-mode fast path support that. If you only need brief alignment, no doc is written. **What if I already have a PRD or detailed GitHub issue?** Skip `ce-brainstorm` and go directly to `/ce-plan`. The plan skill consumes any kind of input. **What does "Inferred" mean in the synthesis?** -The agent composes an internal three-bucket draft (Stated / Inferred / Out of scope) as a thinking step before presenting the scoping synthesis. Inferred items are the agent's bets to fill dialogue gaps. Those that survive the keep test surface as call-outs in the scoping synthesis; the rest dissolve into the requirements doc's Key Decisions when the user confirms. +The agent composes an internal three-bucket draft (Stated / Inferred / Out of scope) as a thinking step before presenting the scoping synthesis. Inferred items are the agent's bets to fill dialogue gaps. Those that survive the keep test surface as call-outs in the scoping synthesis; the rest dissolve into the Product Contract when the user confirms. **Does it work for non-software topics?** Yes — a domain-agnostic facilitator preserves the one-question-at-a-time discipline and right-sizing for naming, decisions, planning, etc. @@ -215,7 +215,7 @@ Yes — a domain-agnostic facilitator preserves the one-question-at-a-time disci ## See Also - [`ce-ideate`](./ce-ideate.md) — upstream "what's worth exploring" discovery -- [`ce-plan`](./ce-plan.md) — turn the requirements doc into an implementation plan -- [`ce-doc-review`](./ce-doc-review.md) — persona-based review of the requirements doc +- [`ce-plan`](./ce-plan.md) — enrich the requirements-only unified plan into an implementation-ready plan +- [`ce-doc-review`](./ce-doc-review.md) — persona-based review of the Product Contract or full plan - [`ce-work`](./ce-work.md) — execute lightweight changes directly from a brainstorm - [`ce-strategy`](./ce-strategy.md) — anchor brainstorms to a documented product strategy diff --git a/docs/skills/ce-code-review.md b/docs/skills/ce-code-review.md index 8d8524248..01a83714a 100644 --- a/docs/skills/ce-code-review.md +++ b/docs/skills/ce-code-review.md @@ -106,7 +106,7 @@ When autofix mode runs and the in-skill fixer can't resolve everything, the resi ### 8. Protected artifacts -Compound-engineering pipeline artifacts (`docs/brainstorms/*`, `docs/plans/*.md`, `docs/solutions/*.md`) are protected — reviewers' findings to delete or gitignore them are discarded during synthesis. These are decision artifacts the pipeline depends on; reviewers shouldn't garbage-collect them. +Compound-engineering pipeline artifacts (`docs/brainstorms/*` legacy/evidence artifacts, `docs/plans/*.{md,html}` unified plans, `docs/solutions/*.md`) are protected — reviewers' findings to delete or gitignore them are discarded during synthesis. These are decision artifacts the pipeline depends on; reviewers shouldn't garbage-collect them. --- @@ -114,7 +114,7 @@ Compound-engineering pipeline artifacts (`docs/brainstorms/*`, `docs/plans/*.md` You invoke `/ce-code-review` on a feature branch with a Rails auth change that includes a database migration. -The skill detects you're on a feature branch (no PR yet), resolves the base from `origin/HEAD` (or PR metadata when an open PR exists), and computes the diff. Stage 2 reads commit messages and writes a 2-3 line intent summary. Stage 2b auto-discovers the plan in `docs/plans/` from the branch name and reads its Requirements (R1-R8, U1-U6). +The skill detects you're on a feature branch (no PR yet), resolves the base from `origin/HEAD` (or PR metadata when an open PR exists), and computes the diff. Stage 2 reads commit messages and writes a 2-3 line intent summary. Stage 2b auto-discovers the plan in `docs/plans/` from the branch name, classifies readiness, and reads Product Contract Requirements plus implementation U-IDs when the artifact is implementation-ready. Stage 3 selects reviewers: the 6 always-on, plus security (auth touched), reliability (background job for token cleanup), data-migration (migration file present), and deployment-verification agent when the migration is risky. Seven or eight reviewers total, dispatched in parallel. diff --git a/docs/skills/ce-doc-review.md b/docs/skills/ce-doc-review.md index ec36a34e4..acd7b552e 100644 --- a/docs/skills/ce-doc-review.md +++ b/docs/skills/ce-doc-review.md @@ -2,7 +2,7 @@ > Review requirements or plan documents using parallel persona agents that surface role-specific issues. -`ce-doc-review` is the **document review** skill — sibling to `/ce-code-review` for the docs side of the chain. It analyzes a requirements doc or implementation plan, selects reviewer personas based on what the doc contains (product framing, design surfaces, security implications, scope sprawl), dispatches them in parallel, then auto-applies safe fixes and routes the rest through a structured four-option interaction (per-finding walk-through, auto-resolve with best judgment, append to Open Questions, report-only). +`ce-doc-review` is the **document review** skill — sibling to `/ce-code-review` for the docs side of the chain. It analyzes a requirements-only unified plan, implementation-ready plan, or legacy document, selects reviewer personas based on what the doc contains (product framing, design surfaces, security implications, scope sprawl), dispatches them in parallel, then auto-applies safe markdown fixes and routes the rest through a structured four-option interaction (per-finding walk-through, auto-resolve with best judgment, append to Open Questions, report-only). The compound-engineering ideation chain is `/ce-ideate → /ce-brainstorm → /ce-plan → /ce-work`. `ce-doc-review` is the **review skill for the artifacts produced by `ce-brainstorm` and `ce-plan`** — invoked at their respective Phase 4 / Phase 5.3.8 handoffs, and also directly when you want a structured review of a doc on disk. @@ -13,8 +13,8 @@ The compound-engineering ideation chain is `/ce-ideate → /ce-brainstorm → /c | Question | Answer | |----------|--------| | What does it do? | Selects reviewer personas based on doc content, dispatches them in parallel, applies `safe_auto` fixes, routes remaining findings through structured interaction | -| When to use it | After `ce-brainstorm` produces a requirements doc; after `ce-plan` writes a plan; before handing either to implementation | -| What it produces | An updated doc with `safe_auto` fixes applied, plus structured handling of `gated_auto` / `manual` findings | +| When to use it | After `ce-brainstorm` produces a requirements-only unified plan; after `ce-plan` writes or enriches a plan; before handing an implementation-ready plan to execution | +| What it produces | An updated markdown doc with `safe_auto` fixes applied, plus structured handling of `gated_auto` / `manual` findings; HTML unified plans are report-only/skipped until HTML-safe mutation exists | | Modes | Interactive (direct invocation), Headless (default when chained from `/ce-plan`) | --- @@ -57,7 +57,7 @@ Conditional personas activate based on what the doc actually says, not keyword m The 2 always-on (`coherence-reviewer`, `feasibility-reviewer`) run on every review. Conditional personas add depth where the doc's content warrants it. -Personas also **scope their techniques by doc shape**. On plan-shape docs with `Origin:` set — meaning premise has already been pressure-tested at brainstorm — `product-lens-reviewer`, `adversarial-document-reviewer`, and `scope-guardian-reviewer` suppress their premise-level techniques and run only implementation-level checks (technical assumptions, decision stress-testing, architectural alternatives, deferred-work scope creep). On requirements-shape docs they run their full technique set. `feasibility-reviewer` inverts: shadow-path tracing, implementability, and migration mechanics are scoped to plan-shape docs; on requirements docs it runs a tight "would this direction force a fundamental rework?" check. Doc-type classification happens once in the orchestrator (content-shape signals — frontmatter, R-IDs vs U-IDs, section structure) and the result is passed to every persona via the `Origin:` slot, so personas don't re-classify themselves. +Personas also **scope their techniques by doc shape**. On plan-shape docs with validated upstream Product Contract provenance — legacy `Origin:` requirements docs, `product_contract_source: ce-brainstorm`, or `product_contract_source: legacy-requirements` — `product-lens-reviewer`, `adversarial-document-reviewer`, and `scope-guardian-reviewer` suppress their premise-level techniques and run only implementation-level checks (technical assumptions, decision stress-testing, architectural alternatives, deferred-work scope creep). On requirements-shape docs they run their full technique set. `feasibility-reviewer` inverts: shadow-path tracing, implementability, and migration mechanics are scoped to plan-shape docs; on requirements docs it runs a tight "would this direction force a fundamental rework?" check. Doc-type classification happens once in the orchestrator (readiness metadata, content-shape signals, frontmatter, R-IDs vs U-IDs, section structure) and the result is passed to every persona. Unified artifacts are sliced: requirements-only plans review the Product Contract, while implementation-ready plans review Product Contract, Planning Contract, Implementation Units, Verification Contract, and Definition of Done without sending the whole artifact to every reviewer by default. ### 2. Synthesis pipeline with three-tier routing @@ -134,7 +134,7 @@ The 2 `safe_auto` apply directly. Headless mode returns the rest as structured t Reach for `ce-doc-review` when: -- A requirements doc just landed from `/ce-brainstorm` and you want a structured review before planning +- 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're in headless mode and a programmatic caller (the chain skills) needs review with structured output - You want round-to-round refinement on a doc — the decision primer prevents loops @@ -151,7 +151,7 @@ Skip `ce-doc-review` when: `ce-doc-review` is invoked from doc-producing skills as their review pass: -- **`/ce-brainstorm` Phase 4** — offered as one of the post-doc options ("Agent review of requirements doc"); runs interactive with full premise scrutiny, since validating premise is exactly what brainstorm exists for +- **`/ce-brainstorm` Phase 4** — offered as one of the post-doc options ("Agent review of Product Contract"); runs interactive with full premise scrutiny, since validating premise is exactly what brainstorm exists for - **`/ce-plan` Phase 5.3.8** — runs in `mode:headless` by default after the confidence check. `safe_auto` fixes apply silently; remaining findings surface as a one-line summary above the post-generation menu, where `Run deeper doc review` is exposed as a first-class option for users who want the interactive walkthrough - **`/ce-resolve-pr-feedback`** — when reviewer feedback lands on a brainstorm or plan doc rather than code @@ -161,7 +161,7 @@ In headless mode, callers receive structured findings and route the user-decisio ## Use Standalone -The skill works directly on any requirements or plan doc: +The skill works directly on unified plan artifacts, legacy requirements docs, and plan docs: - **Specific path** — `/ce-doc-review docs/plans/2026-05-04-001-feat-notification-mute-plan.md` - **Ask the user** — `/ce-doc-review` with no path asks which doc to review (or auto-finds the most recent in `docs/brainstorms/` or `docs/plans/`) @@ -205,7 +205,7 @@ The personas are tuned for those two types specifically. Reviewing a learning do ## See Also -- [`ce-brainstorm`](./ce-brainstorm.md) — produces the requirements docs this skill reviews +- [`ce-brainstorm`](./ce-brainstorm.md) — produces requirements-only unified plans whose Product Contract this skill reviews - [`ce-plan`](./ce-plan.md) — produces the plan docs this skill reviews; invokes this skill at Phase 5.3.8 - [`ce-code-review`](./ce-code-review.md) — sibling skill for code (diffs); same multi-persona pattern, different artifact - [`ce-proof`](./ce-proof.md) — publish a doc to Every's collaborative editor for human review and sharing; complementary, not a substitute diff --git a/docs/skills/ce-ideate.md b/docs/skills/ce-ideate.md index 131a31bc4..a2ad11362 100644 --- a/docs/skills/ce-ideate.md +++ b/docs/skills/ce-ideate.md @@ -204,7 +204,7 @@ A subject-identification gate asks one scope question when the prompt refers onl ## See Also -- [`ce-brainstorm`](./ce-brainstorm.md) — once you've picked a survivor, brainstorm the chosen direction into a requirements doc +- [`ce-brainstorm`](./ce-brainstorm.md) — once you've picked a survivor, brainstorm the chosen direction into a requirements-only unified plan - [`ce-plan`](./ce-plan.md) — once requirements are clear, plan the implementation - [`ce-strategy`](./ce-strategy.md) — anchor ideation to a documented product strategy - [`ce-doc-review`](./ce-doc-review.md) — review the saved ideation artifact for clarity and completeness (markdown output only — run with `output:md` first) diff --git a/docs/skills/ce-plan.md b/docs/skills/ce-plan.md index 9f670dea2..11ba76f57 100644 --- a/docs/skills/ce-plan.md +++ b/docs/skills/ce-plan.md @@ -17,7 +17,7 @@ This is the third step in the compound-engineering ideation chain: this?" ``` -But it stands alone just as well — many teams reach for `ce-plan` directly with a requirements doc, GitHub issue, PRD, rough description, or non-software multi-step task. +But it stands alone just as well — many teams reach for `ce-plan` directly with a requirements-only unified plan, legacy requirements doc, GitHub issue, PRD, rough description, or non-software multi-step task. --- @@ -27,8 +27,8 @@ But it stands alone just as well — many teams reach for `ce-plan` directly wit |----------|--------| | What does it do? | Researches context, captures decisions and scope, breaks work into atomic units with stable IDs, enumerates test scenarios per unit, and auto-strengthens weak sections via a confidence check | | When to use it | Requirements ready and execution guardrails needed; solo planning when the task is clear; non-software multi-step tasks (study plans, research, maintenance, events, trips) | -| What it produces | Plan in `docs/plans/YYYY-MM-DD-NNN---plan.md` | -| What's next | `/ce-work`, create a tracked issue, publish to Proof for sharing, or pause | +| What it produces | Unified plan in `docs/plans/YYYY-MM-DD-NNN---plan.md`; brainstorm-sourced plans move from `artifact_readiness: requirements-only` to `implementation-ready` in place | +| What's next | `/ce-work`, goal-mode prompt when supported, create a tracked issue, publish to Proof for sharing, or pause | | Distinguishing | Guardrails over choreography (WHAT, not HOW); U-IDs (stable); origin tracing (R/A/F/AE → U); test scenarios per unit; automatic deepening; multi-agent research | --- @@ -76,7 +76,7 @@ This matters because `ce-work` references units by U-ID across plan edits. Renum ### 3. Origin tracing — R/A/F/AE IDs from brainstorm flow through the plan -When the plan is sourced from a `ce-brainstorm` requirements doc, identifiers flow through: Requirements (R-IDs) trace into the plan's Requirements section; Actors (A-IDs) carry forward when they affect behavior or permissions; Key Flows (F-IDs) cite into implementation units that realize them; Acceptance Examples (AE-IDs) cite into test scenarios that enforce them (`Covers AE3. `). Every section of the origin doc is verified against the plan before finalization. Nothing silently drops. +When the plan is sourced from a `ce-brainstorm` requirements-only unified plan, identifiers flow through in the same file: Requirements (R-IDs) stay in the Product Contract; Actors (A-IDs) carry forward when they affect behavior or permissions; Key Flows (F-IDs) cite into implementation units that realize them; Acceptance Examples (AE-IDs) cite into test scenarios that enforce them (`Covers AE3. `). Every Product Contract section is verified against the Planning Contract before finalization. Nothing silently drops. ### 4. Test scenarios per unit, in named categories @@ -104,7 +104,7 @@ For a hard problem, `ce-plan` can answer one level up: produce a grounded **appr ## Quick Example -You invoke `ce-plan` with a requirements doc from `ce-brainstorm`. The skill detects the origin, uses it as primary input, and verifies no resolve-before-planning blockers remain. +You invoke `ce-plan` with a requirements-only unified plan from `ce-brainstorm`. The skill detects `artifact_readiness: requirements-only`, uses the Product Contract as primary input, and verifies no resolve-before-planning blockers remain. It dispatches research in parallel — repo analyst, learnings researcher — and detects strong local patterns with no external comparison requested, so it skips external research (an explicit "research competitors" or "best practices from the web" request would have overridden that and run a landscape or implementation-guidance scan instead). A spec-flow analyzer runs to surface edge cases. The brainstorm-sourced scoping synthesis surfaces a tier-shaped summary (prose, bullets, or mix depending on plan depth and what communicates best) plus zero or more "Call outs" — the plan-time forks where another reasonable agent might choose differently (e.g., "mute state stored on the subscription, not the user"). Confirm or redirect; the auto-proceed skip only fires for Lightweight plans with no forks worth flagging — Standard and Deep plans always get the explicit checkpoint. @@ -118,7 +118,7 @@ Document review then runs in headless mode. The cheap minimum dispatches (cohere Reach for `ce-plan` when: -- You have a requirements doc from `ce-brainstorm` ready +- You have a requirements-only unified plan from `ce-brainstorm` ready - You have a GitHub issue, PRD, or feature description that's clear enough - The work is multi-step and benefits from sequencing, dependency ordering, and scope boundaries - You want test or verification scenarios enumerated before execution @@ -140,7 +140,7 @@ Skip `ce-plan` when: | v /ce-brainstorm (define one direction) - | requirements / brief — R/A/F/AE-IDs in software mode + | requirements-only unified plan — R/A/F/AE-IDs in software mode v /ce-plan | guardrails — U-IDs traced to R/A/F/AE-IDs @@ -194,7 +194,8 @@ In universal-planning mode, the U-IDs, dependency ordering, scope boundaries, an |----------|--------| | _(empty)_ | Asks for the task description | | `` | Solo planning; runs the bootstrap | -| `` | Origin-sourced planning | +| `` | Enrich the same unified plan in place | +| `` | Origin-sourced planning into a new unified plan | | `` | Resume offer (or deepen, if intent matches) | | `deepen the plan` / `deepening pass` | Re-deepen fast path (interactive mode) | | `` | Routes to `ce-debug` suggestion menu | @@ -227,7 +228,7 @@ Yes — and it's increasingly common. Universal-planning preserves the U-ID conc ## See Also -- [`ce-brainstorm`](./ce-brainstorm.md) — produce the requirements doc that becomes the plan's origin +- [`ce-brainstorm`](./ce-brainstorm.md) — produce the requirements-only unified plan that `ce-plan` enriches - [`ce-ideate`](./ce-ideate.md) — upstream "what to even work on" ideation - [`ce-work`](./ce-work.md) — execute the plan U-ID by U-ID - [`ce-doc-review`](./ce-doc-review.md) — persona-based review of the plan diff --git a/docs/skills/ce-proof.md b/docs/skills/ce-proof.md index 90637ea4d..6b0e54fe3 100644 --- a/docs/skills/ce-proof.md +++ b/docs/skills/ce-proof.md @@ -176,7 +176,7 @@ Skip `ce-proof` when: `ce-proof` integrates with the chain at multiple publish touchpoints: -- **`/ce-brainstorm` Phase 4** — "Publish to Proof" handoff for sharing the requirements doc +- **`/ce-brainstorm` Phase 4** — "Publish to Proof" handoff for sharing the markdown requirements-only unified plan - **`/ce-plan` Phase 5.4** — "Publish to Proof" handoff for sharing the plan - **`/ce-ideate` Phase 5** — "Publish to Proof" option (markdown output only) - **`/ce-compound`** — for sharing a learning before committing to `docs/solutions/` diff --git a/docs/skills/ce-riffrec-feedback-analysis.md b/docs/skills/ce-riffrec-feedback-analysis.md index 59e03f97d..d4de7d3e8 100644 --- a/docs/skills/ce-riffrec-feedback-analysis.md +++ b/docs/skills/ce-riffrec-feedback-analysis.md @@ -71,7 +71,7 @@ This is what makes the skill useful beyond Riffrec — any recorded feedback fit ### 4. Context-aware output location -In repos with `docs/brainstorms/`, the default output directory is `docs/brainstorms/riffrec-feedback/` so the analysis lands where downstream skills (`ce-brainstorm`, `ce-plan`) expect to find requirements material. The quick path overrides to a temp location so it doesn't pollute the repo with single-issue bug reports. +In repos with `docs/brainstorms/`, the default output directory remains `docs/brainstorms/riffrec-feedback/` as an evidence/kickoff-artifact exception. The durable downstream artifact is still produced by `ce-brainstorm` as a requirements-only unified plan under `docs/plans/`. The quick path overrides to a temp location so it doesn't pollute the repo with single-issue bug reports. ### 5. Compound Engineering output format for extensive analysis @@ -99,7 +99,7 @@ The analyzer extracts: synchronized voice transcript, screen capture frames at e It produces a structured analysis at `docs/brainstorms/riffrec-feedback/2026-05-04-checkout-flow-analysis.md` with each issue, the relevant frames, and timestamps. Raw recording stays local-only. -The skill loads `/ce-brainstorm` with the analysis as the starting point. Brainstorm clarifies which issue to address first, what success looks like, and produces the requirements doc. +The skill loads `/ce-brainstorm` with the analysis as the starting point. Brainstorm clarifies which issue to address first, what success looks like, and produces the requirements-only unified plan. --- @@ -185,6 +185,6 @@ The skill inspects length and event count first. If still unclear, it asks the u ## See Also - [`ce-brainstorm`](./ce-brainstorm.md) — extensive-analysis output feeds directly into brainstorm -- [`ce-plan`](./ce-plan.md) — downstream of brainstorm; receives the requirements doc that came from the recording +- [`ce-plan`](./ce-plan.md) — downstream of brainstorm; enriches the unified plan that came from the recording - [`ce-debug`](./ce-debug.md) — when a quick-path bug report has a clear root cause to investigate - [Riffrec](https://github.com/kieranklaassen/riffrec) — the capture-side tool (separate project) diff --git a/docs/skills/ce-work.md b/docs/skills/ce-work.md index f46070f68..f15e1e881 100644 --- a/docs/skills/ce-work.md +++ b/docs/skills/ce-work.md @@ -21,8 +21,8 @@ This is the fourth and final step in the compound-engineering ideation chain: | Question | Answer | |----------|--------| -| What does it do? | Reads a plan (or scopes a bare prompt), executes against the guardrails, runs tests continuously, ships a reviewed PR | -| When to use it | Implementing a `ce-plan` plan; small/medium bare-prompt work; resuming partly-shipped work | +| What does it do? | Reads an implementation-ready plan (or scopes a bare prompt), executes against the guardrails, runs tests continuously, ships a reviewed PR | +| When to use it | Implementing a `ce-plan` plan with `artifact_readiness: implementation-ready`; small/medium bare-prompt work; resuming partly-shipped work | | What it produces | Commits + a PR (or just commits, no-PR path) | | What's next | Review the PR; run `/ce-compound` to capture learnings | | Distinguishing | Plan-aware idempotency, subagent dispatch with worktree isolation, tiered review with residual gate, operational validation in PR | @@ -57,7 +57,7 @@ Asking an agent "implement this plan" goes wrong in predictable ways: ### 1. Plan-aware execution — honors the WHAT/HOW separation -`ce-work` reads the plan as a decision artifact, not a script. Scope, decisions, U-IDs, files, test scenarios, and verification criteria are authoritative — the agent figures out the actual implementation itself. The plan body stays read-only during execution; progress lives in git commits and the task tracker. +`ce-work` reads the plan as a decision artifact, not a script. For unified plans, it first checks metadata and refuses `artifact_readiness: requirements-only` artifacts until `ce-plan` enriches them. Scope, decisions, U-IDs, files, test scenarios, and verification criteria are authoritative — the agent figures out the actual implementation itself. The plan body stays read-only during execution; progress lives in git commits and the task tracker. ### 2. Idempotent re-execution @@ -125,10 +125,10 @@ Skip `ce-work` when: | v /ce-brainstorm - | requirements / brief + | requirements-only unified plan v /ce-plan - | guardrails — U-IDs, files, test scenarios, scope, risks + | implementation-ready guardrails — U-IDs, files, test scenarios, scope, risks v /ce-work | honors the guardrails; figures out the HOW with code in front of it diff --git a/skills/ce-brainstorm/SKILL.md b/skills/ce-brainstorm/SKILL.md index 6bf44434e..e173f6420 100644 --- a/skills/ce-brainstorm/SKILL.md +++ b/skills/ce-brainstorm/SKILL.md @@ -1,16 +1,16 @@ --- 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.' +description: 'Explore requirements and approaches through collaborative dialogue, then write a right-sized requirements-only unified plan. 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] [output:html]" --- # Brainstorm a Feature or Improvement -**Note: The current year is 2026.** Use this when dating requirements documents. +**Note: The current year is 2026.** Use this when dating requirements-only unified plans. -Brainstorming helps answer **WHAT** to build through collaborative dialogue. It precedes `/ce-plan`, which answers **HOW** to build it. +Brainstorming helps answer **WHAT** to build through collaborative dialogue. It precedes `/ce-plan`, which enriches the same unified plan artifact with **HOW** to build it. -The durable output of this workflow is a **requirements document**. In other workflows this might be called a lightweight PRD or feature brief. In compound engineering, keep the workflow name `brainstorm`, but make the written artifact strong enough that planning does not need to invent product behavior, scope boundaries, or success criteria. +The durable output of this workflow is a **requirements-only unified plan**. In other workflows this might be called a lightweight PRD or feature brief. In compound engineering, keep the workflow name `brainstorm`, but write the first version of the plan artifact under `docs/plans/` with `artifact_readiness: requirements-only` so planning does not need to invent product behavior, scope boundaries, or success criteria. This skill does not implement code. It explores, clarifies, and documents decisions for later planning or execution. @@ -21,8 +21,8 @@ This skill does not implement code. It explores, clarifies, and documents decisi 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 requirements doc 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 document or brief alignment. Larger work gets a fuller document. Do not add ceremony that does not help 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, but low-cost polish or delight is worth including when its ongoing cost is small and easy to maintain. ## Interaction Rules @@ -47,7 +47,7 @@ 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 doc run in the main conversation on the orchestrator's model; nothing is dispatched for them. +- **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. **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. @@ -65,7 +65,7 @@ Do not proceed until you have a feature description from the user. #### 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. +Determine `OUTPUT_FORMAT` before any other phase fires. Output mode is **exclusive** — the requirements-only unified plan 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.** The repo root is pre-resolved at skill load: !`git rev-parse --show-toplevel 2>/dev/null || true` @@ -85,16 +85,18 @@ Resolution steps: **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 names the load. 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. Asymmetric output (`requirements.html` + `plan.md`) is acceptable; users who want HTML for both set both keys in `.compound-engineering/config.local.yaml`. +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; pipeline mode may force markdown by writing the canonical markdown plan path and leaving any HTML sibling untouched as non-canonical for automated discovery. #### 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,html}` file in `docs/brainstorms/`: +If the user references an existing brainstorm topic or document, or there is an obvious recent matching unified plan in `docs/plans/` with `artifact_contract: ce-unified-plan/v1`, `artifact_readiness: requirements-only`, and `product_contract_source: ce-brainstorm`: - Read the document -- Confirm with the user before resuming: "Found an existing requirements doc for [topic]. Should I continue from this, or start fresh?" +- 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, 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. +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. @@ -107,7 +109,7 @@ Before proceeding to Phase 0.2, classify whether this is a software task. The ke **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. -**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 in this main body; improvising them produces an unstructured chat with no synthesis and no handoff. The **Core Principles and Interaction Rules above still apply unchanged** — including one-question-per-turn and the default to the platform's blocking question tool — and are the only part of this file that survives the route. +**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 in this main body; 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` or `artifact_readiness: requirements-only`; those fields are reserved for software Product Contracts that can later become implementation-ready code plans. The **Core Principles and Interaction Rules above still apply unchanged** — including one-question-per-turn and the default to the platform's blocking question tool — and are the only part of this file that survives the route. #### 0.2 Assess Whether Brainstorming Is Needed @@ -118,7 +120,7 @@ Before proceeding to Phase 0.2, classify whether this is a software task. The ke - 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. Only write a short requirements document when a durable handoff to planning or later review would be valuable. Skip Phase 1.1 and 1.2 entirely — go straight to Phase 1.3 or Phase 2.5 in announce-mode (synthesis emitted for visibility, no blocking confirmation), then to Phase 3. +Keep the interaction brief. Confirm understanding and present concise next-step options rather than forcing a long brainstorm. Only write a short requirements-only unified plan when a durable handoff to planning or later review would be valuable. Skip Phase 1.1 and 1.2 entirely — go straight to Phase 1.3 or Phase 2.5 in announce-mode (synthesis emitted for visibility, no blocking confirmation), then to Phase 3. #### 0.3 Assess Scope @@ -134,7 +136,7 @@ If the scope is unclear, ask one targeted question to disambiguate and then proc - **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 sections in the requirements document. Feature-tier uses the current Deep behavior unchanged. +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 and remember that a visual-probe gate is pending. Strong signals include freehand vs constrained drawing behavior, canvas annotation tools, layout comparisons, and state/flow placement. Loading the reference here is readiness only; do not offer the visual path until the first concrete shape/behavior decision. If the user later chooses visual, run the helper at `scripts/visual-probe-server.js` by resolving it relative to this loaded `ce-brainstorm` skill directory; if the runtime does not expose a concrete skill directory, do not guess from the project CWD — use the text path. @@ -148,7 +150,7 @@ Scan the repo before substantive brainstorming. Match depth to scope: **Standard and Deep** — Two passes: -*Constraint Check (inline)* — Use the project's active instructions and conventions already in your context for workflow, product, or scope constraints that affect the brainstorm — no need to open or name specific instruction files. Also read `STRATEGY.md` if it exists — the product's target problem, approach, persona, and active tracks are direct input to what this brainstorm should deliver and should shape scope, success criteria, and which approaches are aligned vs out-of-scope. Also read `CONCEPTS.md` at repo root if it exists — the project's authoritative vocabulary. Use these names in dialogue, approaches, and the requirements doc; map user-offered synonyms back. If any of these add nothing, move on. This pass stays in the main conversation — the dialogue needs this material in context to shape its questions. +*Constraint Check (inline)* — Use the project's active instructions and conventions already in your context for workflow, product, or scope constraints that affect the brainstorm — no need to open or name specific instruction files. Also read `STRATEGY.md` if it exists — the product's target problem, approach, persona, and active tracks are direct input to what this brainstorm should deliver and should shape scope, success criteria, and which approaches are aligned vs out-of-scope. Also read `CONCEPTS.md` at repo root if it exists — the project's authoritative vocabulary. Use these names in dialogue, approaches, and the Product Contract; map user-offered synonyms back. If any of these add nothing, move on. This pass stays in the main conversation — the dialogue needs this material in context to shape its questions. *Topic Scan (grounding scout)* — Create a scratch dir at `/tmp/compound-engineering/ce-brainstorm//` (short unique slug), then dispatch one extraction-tier sub-agent via the platform's subagent primitive (`Agent`/`Task` in Claude Code, `spawn_agent` in Codex) where available; otherwise run the work inline or serially. In harnesses that support background dispatch, proceed to Phase 1.2/1.3 **without waiting**: the scout runs during the user's think-time on the opening questions. Scout prompt: @@ -205,7 +207,7 @@ Favor moves that compound value, reduce future carrying cost, or make the produc - 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 requirements document. +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. #### 1.3 Collaborative Dialogue @@ -218,7 +220,7 @@ This gate **takes precedence over the default blocking-question path** (Interact **Guidelines:** - Ask what the user is already thinking before offering your own ideas. This surfaces hidden context and prevents fixation on AI-generated framings. - Start broad (problem, users, value) then narrow (constraints, exclusions, edge cases) -- **Rigor probes fire before Phase 2 and are open-ended, not menus.** Each scope-appropriate gap found in Phase 1.2 fires as a **separate** direct open-ended probe — one probe satisfies one gap, not multiple. Surface them progressively across the conversation — interleaving with narrowing moves is fine — as long as every gap found in Phase 1.2 has been probed before Phase 2. A menu would signal which kinds of evidence count and let the user pick rather than produce; an open probe forces real observation or surfaces real uncertainty. Each of Phase 1.2's "when present, ask..." lines is the probe; phrase it per Interaction Rule 6. **Attachment is the final rigor probe before Phase 2 when that gap is present — presence is judged from the opening per Phase 1.2, and narrowing having already produced a shape is not a reason to skip it; its job is to pressure-test the user's implicit framing before Phase 2 inherits it.** If a probe's answer reveals genuine uncertainty, record it as an explicit assumption in the requirements document rather than skipping the probe. +- **Rigor probes fire before Phase 2 and are open-ended, not menus.** Each scope-appropriate gap found in Phase 1.2 fires as a **separate** direct open-ended probe — one probe satisfies one gap, not multiple. Surface them progressively across the conversation — interleaving with narrowing moves is fine — as long as every gap found in Phase 1.2 has been probed before Phase 2. A menu would signal which kinds of evidence count and let the user pick rather than produce; an open probe forces real observation or surfaces real uncertainty. Each of Phase 1.2's "when present, ask..." lines is the probe; phrase it per Interaction Rule 6. **Attachment is the final rigor probe before Phase 2 when that gap is present — presence is judged from the opening per Phase 1.2, and narrowing having already produced a shape is not a reason to skip it; its job is to pressure-test the user's implicit framing before Phase 2 inherits it.** If a probe's answer reveals genuine uncertainty, record it as an explicit assumption in the Product Contract rather than skipping the probe. - Clarify the problem frame, validate assumptions, and ask about success criteria - Make requirements concrete enough that planning will not need to invent behavior - Surface dependencies or prerequisites only when they materially affect scope @@ -266,7 +268,7 @@ If relevant, call out whether the choice is: **STOP. Before composing the synthesis, read `references/synthesis-summary.md`.** The two-stage shape (internal three-bucket draft → chat-time scoping synthesis), the four scoping synthesis sections with their keep tests, the per-bullet affirmability and detail tests, the tier-aware bullet budget with re-cut rule, anti-pattern guidance, soft-cut behavior, self-redirect support, and internal-draft routing into doc body sections all live there — none of them appear in this main body. Composing a synthesis without these rules loaded reliably produces malformed output: the full internal three-bucket draft pasted verbatim into chat, implementation detail leaking into the scoping synthesis, the proposal-pitch anti-pattern. The Path A / Path B routing below decides only *whether* a confirmation fires — it is not the synthesis spec. -Surface a scoping synthesis to the user before Phase 3 writes the requirements doc — the user's last opportunity to correct scope before the artifact lands. The scoping synthesis is shaped like what two product collaborators would confirm before writing a PRD, not like a comprehensive audit or a one-line preview. +Surface a scoping synthesis to the user before Phase 3 writes the requirements-only unified plan — the user's last opportunity to correct scope before the artifact lands. The scoping synthesis is shaped like what two product collaborators would confirm before writing a PRD, not like a comprehensive audit or a one-line preview. Fires for **all tiers** including Lightweight. Skip Phase 2.5 entirely on the Phase 0.1b non-software (universal-brainstorming) route. @@ -279,30 +281,30 @@ Fires for **all tiers** including Lightweight. Skip Phase 2.5 entirely on the Ph #### 2.6 Claim Verification (inside the Path B confirmation wait) -When the upcoming requirements doc will assert checkable claims about the repo — absence claims ("no retry logic exists"), references to specific files, config, or dependencies, anything planning would build on — dispatch one generation-tier verifier at the same moment the Path B confirmation question goes up, so it runs during the user's think-time. Pass it the claim list (one line each), the grounding dossier path if one exists, and this instruction: verify each claim directly against the codebase — budget ~15 targeted reads — and return a per-claim verdict: **confirmed** (with `file:line`), **refuted** (with the contradicting evidence), or **unverifiable**. Do not block the confirmation question on the verifier. +When the upcoming Product Contract will assert checkable claims about the repo — absence claims ("no retry logic exists"), references to specific files, config, or dependencies, anything planning would build on — dispatch one generation-tier verifier at the same moment the Path B confirmation question goes up, so it runs during the user's think-time. Pass it the claim list (one line each), the grounding dossier path if one exists, and this instruction: verify each claim directly against the codebase — budget ~15 targeted reads — and return a per-claim verdict: **confirmed** (with `file:line`), **refuted** (with the contradicting evidence), or **unverifiable**. Do not block the confirmation question on the verifier. Consume the verdicts at Phase 3: correct refuted claims before writing, label unverifiable ones as explicit assumptions. A fresh-context verifier replaces self-graded verification — the author confirming its own claims is anchored; the verifier never saw the dialogue. Skip when Path A fires, when the doc will make no checkable claims, or on the non-software route. If the verifier dispatch fails, fall back to verifying the claims inline before the Phase 3 write — Phase 1.1's verify-before-claiming rule still holds either way. -### Phase 3: Capture the Requirements +### Phase 3: Capture the Requirements-Only Unified Plan -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. +Write or update a requirements-only unified plan 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). +- `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. **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`: 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. Before declaring the doc written, run the named test there — could a reader find a contradiction in each section in one pass? -Write to `docs/brainstorms/YYYY-MM-DD--requirements.` — extension follows `OUTPUT_FORMAT`. Confirm with the absolute path so the reference is clickable. +Write to `docs/plans/YYYY-MM-DD-NNN---plan.` — extension follows `OUTPUT_FORMAT`. Include `artifact_contract: ce-unified-plan/v1`, `artifact_readiness: requirements-only`, and `product_contract_source: ce-brainstorm`. Title is ` - Plan` (matching the H1; no conventional-commit prefix). Keep the doc light and standalone-readable: a Goal Capsule (objective, product authority, open blockers) and the Product Contract. Do **not** emit a Goal Launch Block or Reader Index — the launch prompt is skill-emitted at handoff, not a doc section, and the `artifact_readiness` frontmatter carries the requirements-only signal for agents. The next step (planning) is conveyed by the Phase 4 handoff menu. See `references/brainstorm-sections.md`. Confirm with the absolute path so the reference is clickable. -#### Vocabulary Capture — after the requirements doc (only if CONCEPTS.md already exists) +#### 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** — creation is owned by ce-compound and ce-compound-refresh. -Run this **after** the approaches, the scope synthesis, and the requirements doc — 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 requirements doc 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. +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. diff --git a/skills/ce-brainstorm/references/brainstorm-sections.md b/skills/ce-brainstorm/references/brainstorm-sections.md index c8598510a..3cb63ad39 100644 --- a/skills/ce-brainstorm/references/brainstorm-sections.md +++ b/skills/ce-brainstorm/references/brainstorm-sections.md @@ -1,12 +1,14 @@ # Brainstorm Sections -This reference describes what makes a great brainstorm requirements document. +This reference describes what makes a great requirements-only unified plan +artifact produced by `ce-brainstorm`. 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: +A great brainstorm produces the first version of the same plan artifact that +`ce-plan` later enriches. It 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 @@ -18,6 +20,38 @@ A great brainstorm produces a doc that enables three audiences to act: Sections earn their place by serving one of these audiences. Omit padding. +## Unified plan skeleton contract + +New `ce-brainstorm` outputs live under `docs/plans/` and use the unified plan +artifact contract: + +- **Path:** `docs/plans/YYYY-MM-DD-NNN---plan.`. +- **`artifact_contract: ce-unified-plan/v1`**. +- **`artifact_readiness: requirements-only`**. +- **`product_contract_source: ce-brainstorm`**. +- **`execution`** only when the brainstorm has enough signal to classify the + eventual execution domain. For software features, use `execution: code`. + For non-code deliverables, follow the universal-brainstorming route instead + of pretending the artifact is executable code. + +A requirements-only unified plan is kept **light and standalone-readable** — it +is a shareable requirements doc, not an agent-scaffolding dump. It includes: + +- `## Goal Capsule` with objective, product authority, and open blockers. +- `## Product Contract` containing the brainstorm sections below. + +Do **not** emit a `## Goal Launch Block` or `## Reader Index`: the launch prompt +is skill-emitted at handoff, not a doc section, and the contract carries no +Reader Index — consumers wayfind by scanning headings. It also omits empty +`Planning Contract`, `Implementation Units`, `Verification Contract`, and +`Definition of Done` sections — empty placeholders make requirements-only docs +look executable and waste downstream tokens. `ce-plan` adds those sections when +it enriches the same file in place. The next step (planning) is conveyed by the +Phase 4 handoff menu, not by a section in the doc. + +Historical `docs/brainstorms/*-requirements.*` files remain valid legacy +inputs. Do not migrate or rewrite them when creating new artifacts. + ## Decide whether a doc is warranted at all Brainstorm dialogue does not always need to produce a durable document. @@ -90,9 +124,10 @@ contradiction in each section in one pass? A sentence carrying more than one parenthetical, or a requirement specifying two outcomes, fails the test — split it or defer it. -## Hard floor +## Product Contract hard floor -When a doc is warranted, these are present. +When a requirements-only unified plan is warranted, these are present inside +`## Product Contract`. - **Summary** — what is being proposed, in 1-3 lines. Forward-looking. Orients the reader before they invest in detail. @@ -216,30 +251,41 @@ about the same thing, with continuous R-IDs across groups.) ## Brainstorm metadata fields -Every brainstorm carries a small set of stable metadata fields that +Every requirements-only unified plan carries a small set of stable metadata fields that downstream tooling depends on. The contract is format-independent: in markdown these fields appear as YAML frontmatter at the top of the file; in HTML they appear as visible header text (typically a `
` of `
`/`
` pairs or a stats strip). Field names and semantics are the same across both -formats so consumers can locate them without knowing which format produced -the brainstorm. +formats so consumers can locate them without knowing which format produced the +artifact. ### Required +- **`title`** — the artifact's descriptive name with a ` - Plan` suffix + (e.g., `Highlighter Tool - Plan`), matching the H1 (markdown) or document + `

` (HTML). It is a unified plan at every readiness state, so the title + stays stable when `ce-plan` enriches it. Do not put a conventional-commit + prefix (`feat:`/`fix:`) in the title — the `type` field carries that. +- **`type`** — conventional-commit-prefix-aligned classification (`feat`, + `fix`, `refactor`, `docs`, etc.). - **`date`** — creation date in ISO 8601 (`YYYY-MM-DD`), ASCII digits only. - Used in the filename (`docs/brainstorms/YYYY-MM-DD--requirements.`). + Used in the filename (`docs/plans/YYYY-MM-DD-NNN---plan.`). - **`topic`** — kebab-case slug identifying the brainstorm subject (e.g., - `surface-scope-earlier`, `demo-reel-local-save`). Used in the filename - alongside `date` and as the resume-detection key when `ce-brainstorm`'s - Phase 0.1 scans `docs/brainstorms/` for an existing artifact to continue. + `surface-scope-earlier`, `demo-reel-local-save`). Used in the filename and + as the resume-detection key when `ce-brainstorm` scans for an existing + artifact to continue. +- **`artifact_contract`** — always `ce-unified-plan/v1` for new outputs. +- **`artifact_readiness`** — always `requirements-only` for new + `ce-brainstorm` outputs. Do not use `active`, `in_progress`, `completed`, + or `done`. +- **`product_contract_source`** — always `ce-brainstorm`. ### No status field -Brainstorm artifacts have no `status` field and no `active → completed` -lifecycle — a brainstorm is a one-time output that downstream consumers -(`ce-plan`, `ce-doc-review`) reference via the plan's `origin:` field. No -CE artifact carries a mutable status; whether work shipped is derived from -git, not stored in the doc. Do not introduce one. +Unified plan artifacts have no `status` field and no `active → completed` +lifecycle. `artifact_readiness` is document completeness, not execution +progress. No CE artifact carries mutable progress state; whether work shipped +is derived from git, not stored in the doc. Do not introduce one. ### Field-name stability diff --git a/skills/ce-brainstorm/references/handoff.md b/skills/ce-brainstorm/references/handoff.md index 77dcb117e..9f9d604d1 100644 --- a/skills/ce-brainstorm/references/handoff.md +++ b/skills/ce-brainstorm/references/handoff.md @@ -1,15 +1,22 @@ # Handoff -This content is loaded when Phase 4 begins — after the requirements document is written. +This content is loaded when Phase 4 begins — after the requirements-only +unified plan is written. --- #### 4.1 Present Next-Step Options -The Phase 4 menu's visible option count varies by state: no requirements doc hides the review and Proof options, `OUTPUT_FORMAT=html` also hides the review option (ce-doc-review is markdown-only today), unresolved `Resolve Before Planning` hides `Plan implementation` and `Build it now`, a failing direct-to-work gate hides `Build it now`. Count the visible options for the current state and choose the rendering mode accordingly: +The Phase 4 menu's visible option count varies by state: no unified plan +artifact hides the review and Proof options, `OUTPUT_FORMAT=html` also hides +the review option (ce-doc-review is markdown-only today), unresolved `Resolve +Before Planning` hides both `Create the implementation plan` and `Ship it +autonomously with lfg`, and the lfg option is also hidden for non-software +brainstorms (`execution` other than `code`). Count the visible options for the +current state and choose the rendering mode accordingly: - **4 or fewer visible:** use the platform's blocking question tool (`AskUserQuestion` in Claude Code — call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded; `request_user_input` in Codex; `ask_question` in Antigravity CLI (`agy`), `ask_user` in Pi (requires the `pi-ask-user` extension)). This is the default. -- **5 or more visible:** render as a numbered list in chat. This is the narrow option-overflow fallback; trimming would hide legitimate choices (plan, review, Proof, build, refine, pause are all distinct destinations). Include a hint that free-form input is accepted ("Pick a number or describe what you want.") so the numbered list retains the blocking tool's open-endedness. +- **5 or more visible:** render as a numbered list in chat. This is the narrow option-overflow fallback; trimming would hide legitimate choices (plan, ship, review, Proof, refine, pause are all distinct destinations). Include a hint that free-form input is accepted ("Pick a number or describe what you want.") so the numbered list retains the blocking tool's open-endedness. Never silently skip the question. @@ -17,7 +24,7 @@ If `Resolve Before Planning` contains any items: - Ask the blocking questions now, one at a time, by default - If the user explicitly wants to proceed anyway, first convert each remaining item into an explicit decision, assumption, or `Deferred to Planning` question - If the user chooses to pause instead, present the handoff as paused or blocked rather than complete -- Do not offer the `Plan implementation` or `Build it now` options while `Resolve Before Planning` remains non-empty +- Do not offer the `Create the implementation plan` or `Ship it autonomously with lfg` options while `Resolve Before Planning` remains non-empty In both preambles below, the "Pick a number or describe what you want." hint applies only in numbered-list mode. When using the blocking tool, omit that line and pass the remaining stem as the question. @@ -28,7 +35,7 @@ In both preambles below, the "Pick a number or describe what you want." hint app ``` Brainstorm complete. -Requirements doc: # omit line if no doc was created +Plan artifact: # omit line if no artifact was created What would you like to do next? (Pick a number or describe what you want.) ``` @@ -38,75 +45,110 @@ What would you like to do next? (Pick a number or describe what you want.) ``` Brainstorm paused. Planning is blocked until the remaining questions are resolved. -Requirements doc: # omit line if no doc was created +Plan artifact: # omit line if no artifact was created What would you like to do next? (Pick a number or describe what you want.) ``` Present only the options that apply. Renumber so visible options stay contiguous starting at 1. -1. **Plan implementation with `ce-plan` (Recommended)** - Move to `ce-plan` for structured implementation planning. Shown only when `Resolve Before Planning` is empty. -2. **Agent review of requirements doc with `ce-doc-review`** - Dispatch reviewer agents to check the doc for coherence, feasibility, scope, and other persona-specific issues; auto-apply safe fixes; route remaining findings interactively. Shown only when a requirements document exists **and `OUTPUT_FORMAT=md`** — ce-doc-review's walkthrough applies markdown-only mutations (`##`/`###` heading inserts, single-file markdown edits via apply-set) and would corrupt an HTML artifact, so HTML brainstorms skip this option until ce-doc-review gains HTML-aware mutation support. Under HTML mode, surface a one-line note above the menu: `Agent review unavailable in output:html mode — ce-doc-review is markdown-only today. Switch to output:md if you want a review pass.` -3. **Publish to Proof — shareable link** - Publish the requirements doc to Every's Proof editor and get a shareable link to read, comment on, or share with others. One-way: the local doc stays canonical. Shown only when a requirements document exists. **Render only when `OUTPUT_FORMAT=md`** (Proof operates on markdown and cannot ingest HTML). -3. **Open in browser** — open the HTML requirements file locally for review and sharing. Shown only when a requirements document exists. **Render only when `OUTPUT_FORMAT=html`.** Replaces "Publish to Proof" at the same slot under exclusive output mode — the doc is either markdown OR HTML, never both, so exactly one of the two labels applies per run. -4. **Build it now with `ce-work` (skip planning)** - Skip planning and move to `ce-work`; suited to lightweight, well-defined changes. Shown only when `Resolve Before Planning` is empty **and** scope is lightweight, success criteria are clear, scope boundaries are clear, and no meaningful technical or research questions remain (the "direct-to-work gate"). +1. **Create the implementation plan** *(recommended)* - Hand off to `ce-plan` and sharpen the requirements into a complete, testable plan. Shown only when `Resolve Before Planning` is empty. +2. **Ship it autonomously with `lfg`** - Hand the requirements to the full autonomous pipeline: `lfg` plans (`ce-plan`), implements, simplifies, runs independent code review and applies the fixes, opens a PR, and watches CI to green — hands-off, no check-ins. It plans first (unlike a raw `/goal` straight from requirements), so it's the safer autonomous path. Best when you trust the requirements and want it built and shipped without steering. **Opens a PR and pushes a branch.** Shown only for software brainstorms (`execution: code`) with `Resolve Before Planning` empty — the same gate as option 1; for a quicker plan-then-decide flow, or to run a `/goal` yourself, pick option 1 and choose at the `ce-plan` handoff. +3. **Pressure-test the requirements** - Dispatch reviewer agents with `ce-doc-review` to find gaps, conflicts, weak premises, and scope issues in the requirements; auto-apply safe fixes; route the rest interactively. Shown only when a markdown unified plan exists **and `OUTPUT_FORMAT=md`** — ce-doc-review's walkthrough applies markdown-only mutations (`##`/`###` heading inserts, single-file markdown edits via apply-set) and would corrupt an HTML artifact, so HTML brainstorms skip this option until ce-doc-review gains HTML-aware mutation support. Under HTML mode, surface a one-line note above the menu: `Requirements review unavailable in output:html mode — ce-doc-review is markdown-only today. Switch to output:md if you want a review pass.` +4. **Publish to Proof — shareable link** - Publish the markdown unified plan to Every's Proof editor and get a shareable link to read, comment on, or share with others. One-way: the local doc stays canonical. Shown only when a markdown unified plan exists. **Render only when `OUTPUT_FORMAT=md`** (Proof operates on markdown and cannot ingest HTML). +4. **Open in browser** — open the HTML unified plan locally for review and sharing. Shown only when an HTML unified plan exists. **Render only when `OUTPUT_FORMAT=html`.** Replaces "Publish to Proof" at the same slot under exclusive output mode — the artifact is either markdown OR HTML, never both, so exactly one of the two labels applies per run. 5. **More clarifying questions to sharpen the doc** - Keep refining scope, edge cases, constraints, and preferences through further dialogue. Always shown. -6. **Done for now** - Pause; the requirements doc is saved and can be resumed later. Always shown. -**Post-review nudge (subsequent rounds only):** If the user has already run `ce-doc-review` this session and residual P0/P1 findings remain unaddressed, add a one-line prose nudge adjacent to the menu (e.g., "Document review flagged 2 P1 findings you may want to address — pick \"Agent review of requirements doc\" to run another pass."). Reference the option by label, not number: the menu renumbers when `Resolve Before Planning` hides `Plan implementation` and `Build it now`, so a hardcoded option number can point users at the wrong action. Do not add a separate menu option; reuse the existing agent-review option. Suppress this nudge when `OUTPUT_FORMAT=html` — the agent-review option is hidden in that mode, so the nudge would point users at a missing action. +There is no "done" / "pause" option — the blocking question already waits, and the user ends by dismissing it (Esc) or saying they're finished. The unified plan artifact is already saved. + +**Post-review nudge (subsequent rounds only):** If the user has already run `ce-doc-review` this session and residual P0/P1 findings remain unaddressed, add a one-line prose nudge adjacent to the menu (e.g., "Document review flagged 2 P1 findings you may want to address — pick \"Pressure-test the requirements\" to run another pass."). Reference the option by label, not number: the menu renumbers when `Resolve Before Planning` hides `Create the implementation plan` and the lfg option, so a hardcoded option number can point users at the wrong action. Do not add a separate menu option; reuse the existing `Pressure-test the requirements` option. Suppress this nudge when `OUTPUT_FORMAT=html` — that option is hidden in that mode, so the nudge would point users at a missing action. #### 4.2 Handle the Selected Option Selections may be the literal option label (when the user types the label or a close paraphrase) or the option number. Match numbers against the currently-rendered (post-trim) list. Free-form input that doesn't match an option or describe an alternative action should be treated as clarification — ask a follow-up rather than guessing. -**If user selects "Plan implementation with `ce-plan` (Recommended)":** +**If user selects "Create the implementation plan":** + +Immediately load the `ce-plan` skill in the current session. Pass the unified +plan artifact path when one exists; otherwise pass a concise summary of the +finalized brainstorm decisions. When the Phase 1.1 grounding scout produced a +dossier and the file still exists, also pass its path +(`/tmp/compound-engineering/ce-brainstorm//grounding.md`) — it gives +planning verified quotes with `file:line` pointers to start from instead of +re-scanning the repo. Do not print the closing summary first. + +**If user selects "Pressure-test the requirements":** -Immediately load the `ce-plan` skill in the current session. Pass the requirements document path when one exists; otherwise pass a concise summary of the finalized brainstorm decisions. When the Phase 1.1 grounding scout produced a dossier and the file still exists, also pass its path (`/tmp/compound-engineering/ce-brainstorm//grounding.md`) — it gives planning verified quotes with `file:line` pointers to start from instead of re-scanning the repo. Do not print the closing summary first. +Load the `ce-doc-review` skill, passing the unified plan path as the argument. +When ce-doc-review returns "Review complete", return to the Phase 4 options +and re-render the menu (the requirements may have changed, so re-evaluate +`Resolve Before Planning`, the lfg software gate, and residual findings). If +residual P0/P1 findings remain unaddressed, include the post-review nudge +above the menu. Do not show the closing summary yet. -**If user selects "Agent review of requirements doc with `ce-doc-review`":** +**If user selects "Ship it autonomously with `lfg`":** -Load the `ce-doc-review` skill, passing the requirements document path as the argument. When ce-doc-review returns "Review complete", return to the Phase 4 options and re-render the menu (the doc may have changed, so re-evaluate `Resolve Before Planning`, direct-to-work gate, and residual findings). If residual P0/P1 findings remain unaddressed, include the post-review nudge above the menu. Do not show the closing summary yet. +Immediately invoke the `lfg` skill in the current session via the platform's +skill-invocation primitive, passing the unified plan artifact path as its +argument so `lfg`'s `ce-plan` step enriches *this* requirements-only artifact in +place rather than bootstrapping a new plan. `lfg` then owns the full pipeline +autonomously — plan, implement (`ce-work` in `return-to-caller` mode), simplify, +independent code review and applied fixes, commit/push/open PR, and CI watch to +green. Do not also start a `/goal` or load `ce-work` directly — `lfg` +orchestrates them. Unlike a goal tool, `lfg` is host-agnostic: it works wherever +skills run (plus `git`/`gh` for the PR/CI tail, which it guards when absent). -**If user selects "Build it now with `ce-work` (skip planning)":** +Where the host exposes no skill-invocation primitive, print the `lfg ` +invocation for the user to run and note that it will plan, build, review, and +open a PR from this artifact. -Immediately load the `ce-work` skill in the current session using the finalized brainstorm output as context. If a compact requirements document exists, pass its path. Do not print the closing summary first. +Do not print the closing summary first. **If user selects "More clarifying questions to sharpen the doc":** Return to Phase 1.3 (Collaborative Dialogue) and continue asking the user clarifying questions one at a time to further refine scope, edge cases, constraints, and preferences. Continue until the user is satisfied, then return to Phase 4. Do not show the closing summary yet. **If user selects "Publish to Proof — shareable link":** -Load the `ce-proof` skill to publish the requirements doc. Pass: +Load the `ce-proof` skill to publish the markdown unified plan. Pass: -- **source file:** `docs/brainstorms/YYYY-MM-DD--requirements.md` -- **doc title:** `Requirements: ` +- **source file:** `docs/plans/YYYY-MM-DD-NNN---plan.md` +- **doc title:** `Plan: (requirements-only)` - **identity:** `ai:compound-engineering` / `Compound Engineering` -ce-proof creates a shared Proof doc from the requirements file (Create and Share workflow), binds the display name, and returns the share URL. Surface the URL to the user — they can open it to read, comment, or share with others — then return to the Phase 4 options and re-render the menu. This is a one-way publish: the local doc stays canonical and nothing syncs back, so option eligibility is unchanged (no need to re-evaluate `Resolve Before Planning`, the direct-to-work gate, or residual findings on account of Proof). +ce-proof creates a shared Proof doc from the markdown plan file (Create and +Share workflow), binds the display name, and returns the share URL. Surface +the URL to the user — they can open it to read, comment, or share with others +— then return to the Phase 4 options and re-render the menu. This is a one-way +publish: the local doc stays canonical and nothing syncs back, so option +eligibility is unchanged (no need to re-evaluate `Resolve Before Planning`, +the lfg software gate, or residual findings on account of Proof). If the upload fails (network error, Proof API down), retry once after a short wait. If it still fails, tell the user the upload didn't succeed and briefly explain why, then return to the Phase 4 options — don't leave them wondering why the option did nothing. -**If user selects "Open in browser":** Display the absolute path to the `.html` requirements file so the user can open it locally. Where the platform exposes a browser-opening primitive (e.g., `open` on macOS, `xdg-open` on Linux, `start` on Windows), the agent may invoke it directly; otherwise print the absolute path and let the user open it. After the path is displayed (or the browser is opened), return to the Phase 4 options so the user can pick a follow-up action. +**If user selects "Open in browser":** Display the absolute path to the `.html` unified plan so the user can open it locally. Where the platform exposes a browser-opening primitive (e.g., `open` on macOS, `xdg-open` on Linux, `start` on Windows), the agent may invoke it directly; otherwise print the absolute path and let the user open it. After the path is displayed (or the browser is opened), return to the Phase 4 options so the user can pick a follow-up action. -**If user selects "Done for now":** Display the closing summary (see 4.3) and end the turn. +**If the user indicates they're finished** (says "done"/"that's all", or dismisses the menu without picking an option): display the closing summary (see 4.3) and end the turn. #### 4.3 Closing Summary Use the closing summary only when this run of the workflow is ending or handing off, not when returning to the Phase 4 options. -In both templates below, substitute `` with the actual file path written this run — `.md` for `OUTPUT_FORMAT=md`, `.html` for `OUTPUT_FORMAT=html`. Do not emit a hardcoded `.md` path when the artifact is HTML, or the closing summary will point users at a file that was never written. +In both templates below, substitute `` with the +actual file path written this run — `.md` for `OUTPUT_FORMAT=md`, `.html` for +`OUTPUT_FORMAT=html`. Do not emit a hardcoded `.md` path when the artifact is +HTML, or the closing summary will point users at a file that was never written. When complete and ready for planning, display: ```text Brainstorm complete! -Requirements doc: # omit line if no doc was created +Plan artifact: # omit line if no artifact was created Key decisions: - [Decision 1] - [Decision 2] -Recommended next step: `ce-plan` +Recommended next step: `ce-plan ` ``` If the user pauses with `Resolve Before Planning` still populated, display: @@ -114,7 +156,7 @@ If the user pauses with `Resolve Before Planning` still populated, display: ```text Brainstorm paused. -Requirements doc: # omit line if no doc was created +Plan artifact: # omit line if no artifact was created Planning is blocked by: - [Blocking question 1] diff --git a/skills/ce-brainstorm/references/html-rendering.md b/skills/ce-brainstorm/references/html-rendering.md index 53e291edd..9259d1b4d 100644 --- a/skills/ce-brainstorm/references/html-rendering.md +++ b/skills/ce-brainstorm/references/html-rendering.md @@ -55,6 +55,17 @@ These hold regardless of which skill produced the artifact. leaves readers unable to tell how stale the rendering is. - **ASCII identifiers.** Class names, element IDs, data attribute names are ASCII-only. +- **Unified plan navigation.** Unified plan artifacts include a visible + navigation region near the top of the document. It links to stable section + anchors for `goal-capsule`, + `product-contract`, `planning-contract`, `implementation-units`, + `verification-contract`, `definition-of-done`, and `appendix` when those + sections exist. Requirements-only artifacts omit links to absent + implementation sections. +- **Visible readiness metadata.** If the artifact has `artifact_contract`, + `artifact_readiness`, `product_contract_source`, or `execution`, render + those values in the visible header metadata. Do not hide a duplicate copy in + JSON, `data-*`, or `` tags. ## Precedence stack for style preferences @@ -244,6 +255,26 @@ mentions of paths or PRs inside paragraph prose stay as code or text. Linking every mention would clutter; readers expect clickable jumps where the doc presents itself as a reference index. +### Stable section anchors for unified plans + +When rendering a unified plan, every major logical section gets a stable +anchor ID and visible heading text: + +| Logical section | Required id | +|---|---| +| Goal Capsule | `goal-capsule` | +| Product Contract | `product-contract` | +| Product Requirements | `product-requirements` | +| Planning Contract | `planning-contract` | +| Implementation Units | `implementation-units` | +| Verification Contract | `verification-contract` | +| Definition of Done | `definition-of-done` | +| Appendix | `appendix` | + +Long HTML plans are agent-consumed as source text as often as they are read in +a browser. Keep the heading text visible and adjacent to the `id`; do not rely +on a nav link alone to carry the section name. + ### Text contrast is local Every text-on-background pairing must hold up on its own. A color that diff --git a/skills/ce-brainstorm/references/markdown-rendering.md b/skills/ce-brainstorm/references/markdown-rendering.md index 8e20a6b57..707569906 100644 --- a/skills/ce-brainstorm/references/markdown-rendering.md +++ b/skills/ce-brainstorm/references/markdown-rendering.md @@ -23,6 +23,22 @@ These hold regardless of which skill produced the artifact. - **No HTML mixed in.** Keep the markdown pure. No `
`, no `
`, no inline `