From 9b22088ce443ac99a42334ddbabd705ac63dd356 Mon Sep 17 00:00:00 2001 From: Trevin Chow Date: Thu, 18 Jun 2026 00:35:22 -0700 Subject: [PATCH 01/29] docs(plan): add unified artifact refactor plan --- ...refactor-unified-plan-doc-artifact-plan.md | 775 ++++++++++++++++++ 1 file changed, 775 insertions(+) create mode 100644 docs/plans/2026-06-18-001-refactor-unified-plan-doc-artifact-plan.md 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..ee9628143 --- /dev/null +++ b/docs/plans/2026-06-18-001-refactor-unified-plan-doc-artifact-plan.md @@ -0,0 +1,775 @@ +--- +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 includes a compact `Reader Index` and `Goal Capsule` near the top so downstream agents can 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 document includes a top-loaded `Goal Launch Block` that contains the right next prompt for the artifact's current readiness, including a copyable `/goal` prompt when the artifact is implementation-ready. +- 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 `/goal` 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 platform supports it and the plan has a bounded implementation Goal Launch Block, while retaining `ce-work` ownership of implementation-engine selection, bounded plan reading, unit execution, and standalone quality gates. +- 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, caller-owned-tail invocation, and post-`ce-work` pipeline continuation. +- R10c. `ce-work` supports a caller-owned-tail 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, reader-index requirements, goal-mode sections, 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, not the prompt:** The Goal Launch Block is a launcher and router. The durable authority for scope, decisions, verification, and completion must live in the document body, because any goal or agent that reads the plan will use those sections after the initial prompt is forgotten or summarized. +- **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. +- **Treat goal-mode as a capability, not a slash-command assumption:** `/goal` is user-facing on some hosts and is not necessarily a callable subroutine. Skills may use goal-mode as an engine only after probing that the host exposes a callable persistent-objective primitive that can return control and a structured summary; otherwise they must fall back to inline, subagent, or dynamic-workflow execution. For Claude Code skills specifically, do not assume a skill can invoke `/goal` or dynamic workflows inside the current session; emit a copyable command/prompt block instead. +- **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: "feat: Example capability" +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: +execution: code # optional; same semantics as today +--- + +# feat: Example capability + +## Goal Launch Block +## Reader Index +## 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 +``` + +`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 Launch Block | `## Goal Launch Block` | `goal-launch-block` | `^## Goal Launch Block$` / `#goal-launch-block` | +| Reader Index | `## Reader Index` | `reader-index` | `^## Reader Index$` / `#reader-index` | +| 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 `Reader Index` is a stable extraction target, not the primary instruction source. + +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, Reader Index, 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, Reader Index, Goal Capsule, Definition of Done, Verification Contract, Implementation Units heading list, first candidate U-ID, Goal Launch Block when considering goal-mode | 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, Reader Index, 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 | + +`Reader Index` should therefore be compact and extractable, but it is not enough on its own. The skills must know to locate it with grep/heading scans 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 platform exposes a callable persistent-objective primitive that can run to completion, return control, and provide a structured completion summary. On hosts where `/goal` is only a top-level user command, `ce-work` should surface the Goal Launch Block or run inline/subagents instead of trying to call it internally. Claude Code falls in this copy/paste bucket for in-session skills unless a future API exposes command invocation to skills. 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. + +After a goal-mode implementation returns, `ce-work` should inspect the diff and continue at the right tail for its caller. In standalone mode, it continues through its normal post-implementation quality gates and handoff. In LFG caller-owned-tail mode, it performs implementation verification, reports changed files and observed verification, and returns control to LFG before simplify/review/PR/CI. This makes goal-mode a way to get better sustained implementation focus, not a way to skip the owning workflow's finish discipline. + +Caller-owned-tail invocation should be explicit, for example `ce-work mode:caller-owned-tail ` 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:caller-owned-tail` | 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 Reader Index / 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 caller-owned-tail mode. It should not parse Goal Launch Blocks, 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. + +### Goal Launch Block + +Required near the top of every unified artifact, ideally within the first 100 lines. This is the section `ce-plan` can surface immediately after writing or enriching a plan. It is not a generic instruction blob; it is a readiness-specific next action. + +The Goal Launch Block should stay thin. It names the action, path, read order, tail profile, and stop condition, then points into document sections. It should not duplicate requirements, implementation details, full verification matrices, or product rationale. Duplicating that material creates drift inside the same file; the plan body is the authority. + +For `artifact_readiness: requirements-only`, the block must route to planning, not execution: + +````markdown +## Goal Launch Block + +Recommended next prompt: + +```text +/goal Enrich docs/plans/example-plan.md into an implementation-ready plan. + +Use the Product Contract as authority. Produce Planning Contract, Implementation Units, Definition of Done, and a final Goal Launch Block for execution. 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 block must route to implementation and declare which tail profile owns quality gates. Generated artifacts should prefer a standalone top-level prompt for humans and an implementation-only prompt for skill callers that need an internal engine. + +````markdown +## Goal Launch Block + +Standalone top-level prompt: + +```text +/goal Implement docs/plans/example-plan.md through its Definition of Done. + +First read: Reader Index, Goal Capsule, Definition of Done, and the Implementation Units heading map. 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 Reader Index, Goal Capsule, Definition of Done, and active U-IDs. 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, read Reader Index, Goal Capsule, Definition of Done, and the Implementation Units heading map 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 unified implementation `Goal Launch Block` 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 Goal Launch Block prompt, or to hand off to `ce-work` where that is the platform's execution primitive. | +| 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 caller-owned-tail 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. +``` + +### Reader Index + +Compact routing table. Required fields: + +| Field | Purpose | +|---|---| +| Artifact readiness | Says whether this is requirements-only or implementation-ready. | +| Product contract source | Says whether product scope came from `ce-brainstorm`, `ce-plan` bootstrap, or a legacy origin path. | +| Read first | Points every agent to `Goal Launch Block` and `Goal Capsule`; points to `Definition of Done` only when present. | +| Implementer path | Names the sections `ce-work` and worker agents must read. | +| Reviewer path | Names the sections reviewers should inspect first. | +| Token notes | Names sections safe to skip unless needed, especially appendices. | + +### 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. | +| Known skips | Checks intentionally skipped and the reason the skip is acceptable. | + +The Goal Launch Block 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. + +### 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. +- **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 | +``` + +### Goal-Mode Prompt Compatibility + +The old section name `Goal-Mode Prompt` should be replaced by `Goal Launch Block` for new unified artifacts. Legacy readers may continue to recognize `## Goal-Mode Prompt` as an alias during migration, but new docs should emit only `## Goal Launch Block` to avoid duplicate competing prompts. + +--- + +## 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: `plugins/compound-engineering/skills/ce-plan/references/plan-sections.md` + - Modify or replace: `plugins/compound-engineering/skills/ce-brainstorm/references/brainstorm-sections.md` + - Modify: `plugins/compound-engineering/skills/ce-plan/references/markdown-rendering.md` + - Modify: `plugins/compound-engineering/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 Launch Block`, `Reader Index`, `Goal Capsule`, `Product Contract`, `Planning Contract`, `Verification Contract`, and `Definition of Done` as the new contract. 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 `reader-index`, `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: `plugins/compound-engineering/skills/ce-brainstorm/SKILL.md` + - Modify: `plugins/compound-engineering/skills/ce-brainstorm/references/handoff.md` + - Modify: `plugins/compound-engineering/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 `Reader Index`, `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 Reader Index does not point implementers at missing `Definition of Done` or `Implementation Units` sections. + - Requirements-only Goal Launch Block points to `ce-plan` enrichment, not execution. + - `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: `plugins/compound-engineering/skills/ce-plan/SKILL.md` + - Modify: `plugins/compound-engineering/skills/ce-plan/references/synthesis-summary.md` + - Modify: `plugins/compound-engineering/skills/ce-plan/references/deepening-workflow.md` + - Modify: `plugins/compound-engineering/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`, `Definition of Done`, and the implementation-ready Goal Launch Block, 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: `plugins/compound-engineering/skills/ce-work/SKILL.md` + - Modify or explicitly guard: `plugins/compound-engineering/skills/ce-work-beta/SKILL.md` + - Modify: `plugins/compound-engineering/skills/lfg/SKILL.md` + - Modify: `plugins/compound-engineering/skills/ce-doc-review/SKILL.md` + - Modify: `plugins/compound-engineering/skills/ce-doc-review/references/subagent-template.md` + - Modify: `plugins/compound-engineering/skills/ce-doc-review/references/synthesis-and-presentation.md` + - Modify: `plugins/compound-engineering/skills/ce-proof/SKILL.md` + - Modify: `plugins/compound-engineering/skills/ce-code-review/SKILL.md` + - Modify or document exception: `plugins/compound-engineering/skills/ce-riffrec-feedback-analysis/SKILL.md` + - Modify or document exception: `plugins/compound-engineering/skills/ce-riffrec-feedback-analysis/references/extensive-analysis.md` + - Modify or document exception: `plugins/compound-engineering/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, Reader Index, 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 caller-owned-tail 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:caller-owned-tail ` (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, Reader Index, 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. + - Generated Goal Launch Blocks 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 caller-owned-tail mode, then to `ce-code-review mode:agent plan:` and later pipeline steps. + - `ce-work mode:caller-owned-tail` 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 Launch Block`, `Reader Index`, `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: `plugins/compound-engineering/skills/ce-ideate/SKILL.md` + - Modify: `plugins/compound-engineering/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 Launch Block`, `Reader Index`, `Goal Capsule`, and, when implementation-ready, `Verification Contract` and `Definition of Done`. + - Goal Launch Block 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 caller-owned-tail 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 Launch Block 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 | Goal Launch Block says to stop on blocker, wrong naming/config migration, or unsatisfied DoD. | Ready | +| Tail ownership | Goal Launch Block is top-level: it owns implementation quality gates but does not open a PR. | Ready | +| Context discipline | Goal Launch Block and Reader Strategy tell the agent what to read first and when to avoid full-doc reads. | Ready | +| Deferred decisions | Open Questions identify naming/config decisions that may need to stop execution. | Ready with known open questions | + +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 mandatory `Reader Index`, `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 | + +--- + +## Goal Launch Block + +```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. Reader Index +3. Goal Capsule +4. Verification Contract +5. Definition of Done +6. Implementation Units heading map +7. Product Contract and Planning Contract sections only as referenced by the active U-ID + +Authority: +- Product Contract requirements define the behavior that must hold after the refactor. +- Planning Contract and 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. +- 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 Reader Index entries 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 `Reader Index` as an extraction target, not as 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, caller-owned-tail 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 Goal Launch Blocks 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 caller-owned-tail 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? From 11fe6e989931e8cf6171b943709a7198ccf1e979 Mon Sep 17 00:00:00 2001 From: Trevin Chow Date: Thu, 18 Jun 2026 00:35:31 -0700 Subject: [PATCH 02/29] feat(skills): unify brainstorm and plan artifacts --- skills/ce-brainstorm/SKILL.md | 52 ++++---- .../references/brainstorm-sections.md | 75 ++++++++--- skills/ce-brainstorm/references/handoff.md | 78 +++++++---- .../references/html-rendering.md | 33 +++++ .../references/markdown-rendering.md | 27 ++++ .../references/synthesis-summary.md | 28 ++-- .../references/universal-brainstorming.md | 10 +- skills/ce-code-review/SKILL.md | 33 ++++- skills/ce-doc-review/SKILL.md | 28 ++-- .../references/subagent-template.md | 6 +- skills/ce-ideate/SKILL.md | 4 +- skills/ce-ideate/references/html-rendering.md | 33 +++++ .../references/markdown-rendering.md | 27 ++++ .../references/post-ideation-workflow.md | 4 +- skills/ce-plan/SKILL.md | 45 +++++-- .../ce-plan/references/approach-altitude.md | 2 +- skills/ce-plan/references/html-rendering.md | 33 +++++ .../ce-plan/references/markdown-rendering.md | 27 ++++ skills/ce-plan/references/plan-handoff.md | 10 +- skills/ce-plan/references/plan-sections.md | 122 +++++++++++++++--- .../ce-plan/references/universal-planning.md | 1 + skills/ce-proof/SKILL.md | 7 +- skills/ce-riffrec-feedback-analysis/SKILL.md | 4 +- .../references/extensive-analysis.md | 4 +- .../scripts/analyze_riffrec_zip.py | 4 +- skills/ce-work-beta/SKILL.md | 15 ++- skills/ce-work/SKILL.md | 47 ++++++- skills/lfg/SKILL.md | 8 +- 28 files changed, 620 insertions(+), 147 deletions(-) diff --git a/skills/ce-brainstorm/SKILL.md b/skills/ce-brainstorm/SKILL.md index 9e6f5ab80..b0801dd7b 100644 --- a/skills/ce-brainstorm/SKILL.md +++ b/skills/ce-brainstorm/SKILL.md @@ -1,16 +1,16 @@ --- name: ce-brainstorm -description: 'Explore vague or ambitious ideas into right-sized requirements. Use when the user wants to brainstorm, think through scope, decide what to build, or needs collaborative product framing before planning.' +description: 'Explore vague or ambitious ideas into a right-sized requirements-only unified plan. Use when the user wants to brainstorm, think through scope, decide what to build, or needs collaborative product framing before planning.' 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`. The document must include Goal Launch Block, Reader Index, Goal Capsule, and Product Contract. The Goal Launch Block points to `/ce-plan ` for enrichment, not `/ce-work` or `/goal` execution. 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..d3e28e199 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 includes: + +- `## Goal Launch Block` that routes to `ce-plan` enrichment, not execution. +- `## Reader Index` that points readers to Goal Capsule and Product Contract, + and explicitly does not point them to missing implementation sections. +- `## Goal Capsule` with objective, product authority, open blockers, and a + stop condition: do not execute until `artifact_readiness: + implementation-ready`. +- `## Product Contract` containing the brainstorm sections below. + +It 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. + +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,38 @@ 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`** — verbatim artifact title. Matches the H1 (markdown) or + document `

` (HTML). +- **`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..e98744eb8 100644 --- a/skills/ce-brainstorm/references/handoff.md +++ b/skills/ce-brainstorm/references/handoff.md @@ -1,12 +1,18 @@ # 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 `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: - **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. @@ -28,7 +34,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,22 +44,22 @@ 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. **Plan implementation with `ce-plan` (Recommended)** - Move to `ce-plan` to enrich the same unified plan file to `artifact_readiness: implementation-ready`. Shown only when `Resolve Before Planning` is empty. +2. **Agent review of Product Contract with `ce-doc-review`** - Dispatch reviewer agents to check the Product Contract for coherence, feasibility, scope, and other persona-specific issues; auto-apply safe fixes; route remaining findings 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: `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 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). +3. **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. +4. **Build it now with `ce-work` (skip planning)** - Skip planning and move to `ce-work`; suited only to lightweight, well-defined changes where the chat or artifact already contains a sufficient Definition of Done. Hidden by default for requirements-only artifacts because they are not implementation-ready. 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. +6. **Done for now** - Pause; the unified plan artifact 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. +**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 Product Contract\" 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. #### 4.2 Handle the Selected Option @@ -61,31 +67,52 @@ Selections may be the literal option label (when the user types the label or a c **If user selects "Plan implementation with `ce-plan` (Recommended)":** -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. +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 "Agent review of requirements doc with `ce-doc-review`":** +**If user selects "Agent review of Product Contract with `ce-doc-review`":** -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. +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 Product Contract 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. **If user selects "Build it now with `ce-work` (skip planning)":** -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. +Only show this option when the direct-to-work gate explicitly found a +sufficient Definition of Done in chat or in the artifact. Immediately load the +`ce-work` skill in the current session using the finalized brainstorm output +as context. If a compact unified plan exists, pass its path. 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 direct-to-work 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. @@ -93,20 +120,23 @@ If the upload fails (network error, Proof API down), retry once after a short wa 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 +144,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..8002ac077 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-launch-block`, `reader-index`, `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,28 @@ 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 Launch Block | `goal-launch-block` | +| Reader Index | `reader-index` | +| 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..4ba90dcb1 100644 --- a/skills/ce-brainstorm/references/markdown-rendering.md +++ b/skills/ce-brainstorm/references/markdown-rendering.md @@ -23,6 +23,16 @@ These hold regardless of which skill produced the artifact. - **No HTML mixed in.** Keep the markdown pure. No `
`, no `
`, no inline `