feat(ce-brainstorm, ce-plan): unify brainstorm and plan into one readiness-staged artifact#972
Draft
tmchow wants to merge 16 commits into
Draft
feat(ce-brainstorm, ce-plan): unify brainstorm and plan into one readiness-staged artifact#972tmchow wants to merge 16 commits into
tmchow wants to merge 16 commits into
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 51a84d91da
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
tmchow
added a commit
that referenced
this pull request
Jun 22, 2026
- ce-work Phase 0 now strips a leading mode:caller-owned-tail token so
lfg's invocation isn't mistaken for a bare prompt (P1)
- ce-code-review Stage 2b discovers docs/plans/*.{md,html} and extracts
Product Contract > Requirements, matching its completeness contract (P2)
- ce-plan 5.1.5 scoping-synthesis gate fires for requirements-only
unified-plan sources, not only legacy *-requirements docs (P2)
- contract tests cover all three
tmchow
added a commit
that referenced
this pull request
Jun 22, 2026
- execution-engines: add a Codex lane (top-level /goal is a thread mode, not an awaitable nested engine), a progress-visibility lane independent of final-PR tail ownership, and a compaction re-read instruction - plan-sections: Goal Launch Block must be evaluator-complete (prompt is also the completion criteria) and split human vs pipeline launch; implementation-ready requires zero launch-blocking open questions; markdown is the canonical execution artifact, HTML is report-only - ce-plan: record a Product Contract preservation note on in-place enrichment so the WHAT/HOW review boundary stays visible - plan doc: fix its own Goal Launch Block to reference sections it has (it is a pre-contract meta-plan) and mark open questions non-blocking - contract tests cover all of the above
tmchow
changed the title
Add the execution-engine selection lane that the unified-plan refactor specified but under-implemented: a references/execution-engines.md covering host-capability probing, goal-mode/dynamic-workflow vs inline/subagent selection, copyable /goal and ultracode: prompts, and resume-correct-tail rules; wire a concise engine-selection step into ce-work Phase 1. Reconcile reference drift left by the refactor: ce-plan synthesis-summary and ce-doc-review synthesis-and-presentation now describe the unified Product/Planning Contract nesting and readiness-aware next-stage routing; align the plan doc's legacy product_contract_source value. Adopt two refinements from Kundel's /goal guide: prefer measurable exit thresholds for optimization-shaped goals, and require dead-end/experimental code cleanup before done. Add HTML nav/id and contract-test coverage for the above.
- ce-work Phase 0 now strips a leading mode:caller-owned-tail token so
lfg's invocation isn't mistaken for a bare prompt (P1)
- ce-code-review Stage 2b discovers docs/plans/*.{md,html} and extracts
Product Contract > Requirements, matching its completeness contract (P2)
- ce-plan 5.1.5 scoping-synthesis gate fires for requirements-only
unified-plan sources, not only legacy *-requirements docs (P2)
- contract tests cover all three
- execution-engines: add a Codex lane (top-level /goal is a thread mode, not an awaitable nested engine), a progress-visibility lane independent of final-PR tail ownership, and a compaction re-read instruction - plan-sections: Goal Launch Block must be evaluator-complete (prompt is also the completion criteria) and split human vs pipeline launch; implementation-ready requires zero launch-blocking open questions; markdown is the canonical execution artifact, HTML is report-only - ce-plan: record a Product Contract preservation note on in-place enrichment so the WHAT/HOW review boundary stays visible - plan doc: fix its own Goal Launch Block to reference sections it has (it is a pre-contract meta-plan) and mark open questions non-blocking - contract tests cover all of the above
…ption The post-plan menu offered no way to get the copyable /goal prompt on hosts where ce-work is skill-invocable (Claude Code) — picking 'Start /ce-work' ran the skill instead. Verified (claude-code-guide + Codex's own docs) that a skill cannot invoke /goal on either platform; it can only emit a copyable prompt. So /goal becomes its own menu option, mutually exclusive with 'Start /ce-work' (only one executor runs the plan — tail-ownership guard), gated to implementation-ready code plans and opt-in so the long prompt never auto-dumps. Also make the menu-rendering guidance declarative — drop the runtime 'Per the AGENTS.md' authoring-file reference. Contract tests cover the new option, the mutual-exclusion guard, and the absence of the meta-ref.
- drop the 'Done for now' option from both the ce-plan and ce-brainstorm
handoff menus — the blocking question already waits, so pausing is
implicit (dismiss/Esc or say you're finished); the artifact is saved
either way. ce-brainstorm's closing summary still fires on the natural
finish/dismiss path.
- reword 'Start /ce-work' to plain user language ('Implement this plan
now, in this session') instead of the internal 'owns the tail' jargon
- gate the 'Give me the /goal prompt' option to hosts that actually have
a top-level /goal command (Claude Code and Codex); omit it elsewhere
'Run deeper doc review' didn't say what it does. Rename it to 'Review remaining findings' and rewrite the description to explain the model: the auto-pass already applied the safe mechanical fixes; this option walks through what it left for the user's judgment — proposed edits that change the plan's meaning/scope (confirm or skip) and judgment calls with no single right answer (decide, or defer into Open Questions). Renamed the routing-key references in lockstep.
…view's open items'
'Review remaining findings' still didn't signal the user has decisions to
make. Rename to 'Decide on the review's open items' with a plain secondary
line ('Confirm or skip the suggested edits, and settle the judgment calls
the auto-pass left for you'). Routing-key references and tests updated in
lockstep.
…enus ce-brainstorm: rename the menu to plain actions and add a skip-planning path that doesn't force ce-work. One slot renders the most autonomous available option — 'Create a /goal prompt' on /goal hosts (Claude Code, Codex), else 'Build it now' via ce-work — never both, since at the requirements stage choosing between them is confusing. ce-plan stays the recommended path (sharpest requirements, least rework). Rename the 'Agent review of Product Contract' option to 'Pressure-test the requirements' — at this stage no review has run yet, so it is the first critique, not adjudicating leftovers. ce-plan: both ce-work and /goal stay shown (the plan is real, so it's a preference), with descriptions that state the deciding factor — shorter work / watch-and-steer vs longer / autonomous-to-DoD. Rename 'Give me the /goal prompt' to 'Create a /goal prompt' for consistency. Wording informed by asking Codex (the /goal authority) why one picks /goal vs a direct implement instruction. Tests updated for all renames.
The (recommended) marker is now dynamic: /goal carries it when the host has a top-level /goal command (Claude Code, Codex); ce-work carries it otherwise (when the /goal option is omitted). Exactly one option is ever marked. Reflects that the autonomous run-to-DoD is the preferred default when available, with ce-work as the in-session fallback.
…opy-paste Corrects a wrong claim in execution-engines.md. Confirmed empirically: a Codex skill CAN start goal-mode via the create_goal tool (gated by features.goals); Claude Code exposes no goal tools at all. So: - execution-engines.md: goal-mode is a callable engine where a goal tool exists. create_goal sets+activates the objective and the CURRENT session works toward it (not a background worker, no awaitable envelope). The skill does NOT call update_goal — the goal session marks its own completion. create_goal is standalone-only, never caller-owned-tail (which must return control). - ce-plan and ce-brainstorm /goal options: on a callable-goal-tool host, selecting it calls create_goal directly (no copy-paste); on a user-typed-/goal host (Claude Code) it emits the copyable prompt; ce-work never also runs. ce-brainstorm's skip-planning slot falls back to ce-work only where there is no goal mode at all. The literal /goal slash command remains user-typed-only everywhere; the tool path is what makes Codex callable. Tests updated.
'Create a /goal prompt' implied a copy-paste prompt, but on a host with a callable goal tool (Codex create_goal) there is no prompt — the session just starts. 'Run it as a /goal' is truthful for both paths (direct start or copy-paste), with the mechanism in the description. One label, one routing key, across ce-plan and ce-brainstorm. Tests updated.
Rebase reconciliation: keep main's capability-based tracker routing and its category-style menu label (e.g., GitHub Issues, Linear, Jira) instead of the closed '(GitHub or Linear)' set, satisfying main's new contract test.
tmchow
force-pushed
the
tmchow/feat-unified-brainstorm-plan-docs
branch
from
b5589eb to
9348929
Compare
Collaborator
Author
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9348929e20
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Comment on lines
+162
to
+164
| Launch prompts name the canonical **markdown** plan path: markdown is the | ||
| execution artifact for `ce-work`, `lfg`, and `/goal`; an HTML rendering is a | ||
| human-facing/report-only view and is never the goal-launch target. |
There was a problem hiding this comment.
When OUTPUT_FORMAT=html, the handoff reference says the run writes a single .html file with no markdown sibling, yet this contract requires every Goal Launch Block to name a canonical markdown path and says HTML is never the launch target. In an HTML plan, that makes the generated /goal or ce-work mode:caller-owned-tail prompt point at a nonexistent .md sibling, so choosing the post-plan execution options can fail before the executor can read the plan. Either emit launch prompts for the actual artifact path or create the markdown execution sibling before advertising it.
Useful? React with 👍 / 👎.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
ce-brainstormandce-plannow produce one artifact indocs/plans/that moves through readiness states, instead of a brainstorm requirements doc plus a separate plan doc.ce-brainstormwrites a requirements-only skeleton;ce-planenriches that same file in place to implementation-ready; and every downstream reader is readiness-aware, so a requirements-only skeleton can no longer be mistaken for executable work. Legacydocs/brainstorms/*-requirements.*inputs andorigin:references keep resolving indefinitely — nothing is migrated.The win: the implementing agent reads one durable authority (scope, decisions, verification, done criteria) instead of stitching two files, and requirement changes can't drift away from the plan that executes them.
The artifact contract
A unified plan carries readiness as document-completeness metadata — never a mutable work-progress status:
artifact_contract: ce-unified-plan/v1artifact_readiness: requirements-only | implementation-readyproduct_contract_source: ce-brainstorm | ce-plan-bootstrap | legacy-requirementsFixed section order (Goal Launch Block, Reader Index, Goal Capsule, Product Contract, then — when implementation-ready — Planning Contract, Implementation Units, Verification Contract, Definition of Done) with a stable Section ID Registry so consumers grep before reading the whole file.
Design decisions worth a look
/goalrun the prompt is summarized away, so durable scope must live in the doc.status:lifecycle. Readiness answers "executable?", not "done?"; progress stays in git, task trackers, and commits. Tests reject progress-like values (active,in_progress,completed,done).ce-workgained an execution-engine lane (skills/ce-work/references/execution-engines.md): inline/subagent (default, and the only callable engine on Claude Code) vs goal-mode vs dynamic-workflow, gated on a host-capability probe, with explicit resume-the-correct-tail rules. Acaller-owned-tailmode letslfgown simplify/review/PR/CI whilece-workowns implementation strategy.ce-workwon't auto-execute a requirements-only/knowledge-work/approach-plan artifact;ce-doc-reviewclassifies by readiness and reviews Product vs Planning Contract by section slice instead of sending the whole artifact to every persona;ce-code-reviewclassifies readiness before flagging unit completeness;ce-proofpublishes markdown only./goalguide by Dominik Kundel (readable mirror): prefer measurable exit thresholds for optimization-shaped goals, and require dead-end/experimental-code cleanup before "done." The Codex draft-PR progress pattern is deliberately not adopted — it conflicts with the rule that the goal never opens a PR.Validation
Non-observable change (skill prose, references, tests, docs — no runtime UI/CLI surface), so no demo artifact. Verified against current
main:bun test— 1600 pass, 0 fail (includes a newunified-plan-artifact-contractsuite and added HTML nav/anchor invariants).bun run release:validate— metadata in sync (0 agents, 27 skills).Rebased onto main's skills-only / root-native refactor (#967); all changes are root-native under
skills/,docs/, andtests/.