feat(ce-plan,_shared): add --html flag and shared HTML output reference#809
feat(ce-plan,_shared): add --html flag and shared HTML output reference#809mvanhorn wants to merge 1 commit intoEveryInc:mainfrom
Conversation
Adds an opt-in `--html` flag to ce-plan and a shared HTML output reference at plugins/compound-engineering/skills/_shared/html-output.md that the remaining 13 document-producing ce-* skills can layer onto in follow-up PRs. Default ce-plan behavior is unchanged. When invoked with `--html` (or a bare `html` keyword for harnesses that strip dashes), ce-plan writes a self-contained HTML5 document at docs/plans/YYYY-MM-DD-NNN-<type>-<slug>-plan.html with embedded CSS, real tables for Requirements traceability and Test Scenarios, inline SVG for diagrams, anchored navigation, status pills, dark-mode and mobile breakpoints. No external CSS, JS, fonts, or images. Phase 1 of a planned 6-phase rollout. Subsequent phases extend `--html` to ce-brainstorm, ce-strategy, ce-ideate, ce-debug, ce-doc-review, ce-code-review, ce-compound, ce-product-pulse, ce-sessions, plus the document tail. Each phase ships as its own PR after this lands and the shared infrastructure design is validated.
![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: 6eec05858f
ℹ️ 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".
| HTML output is opt-in. Set `OUTPUT_FORMAT=html` only when `$ARGUMENTS` contains either: | ||
| - `--html` | ||
| - a bare `html` keyword, accepted as a fallback for harnesses that strip leading dashes |
There was a problem hiding this comment.
For plans about HTML work, e.g. ce-plan build an HTML email renderer, $ARGUMENTS contains a bare html token even though the user did not request the HTML output format. This flips the plan to .html, and the new handoff text explicitly says not to invoke ce-work for HTML plans, so ordinary web/UI planning requests can no longer flow into the default implementation workflow. Consider accepting the fallback only when html is the whole argument or an explicit format argument, not just any token in the task description.
Useful? React with 👍 / 👎.
| <style> | ||
| /* Use the embedded CSS theme from ../_shared/html-output.md. */ | ||
| </style> |
There was a problem hiding this comment.
In converted installs this reference is not available: I checked the Claude parser and target writers, and they register/copy only directories that contain a SKILL.md, so the new skills/_shared directory is not included with the ce-plan skill. When ce-plan --html follows this template it is told to pull CSS from a missing sibling resource, which can leave generated plans without the required embedded theme or with the placeholder comment instead. Duplicate the needed shared content under ce-plan/references or otherwise make it part of the shipped skill directory.
Useful? React with 👍 / 👎.
|
Thanks @mvanhorn let me take a look. i have my own branch goign for this so may cherry pick some stuff from it. Hang tight. |
|
Sounds good — holding pattern on this end. Cherry-pick whatever's useful and I'll close this out (or rebase on yours) once your branch lands. |
2 participants
Summary
ce-plan can now write plans as a single self-contained HTML file when invoked with
--html. Default markdown output is unchanged.The HTML view is a static read-mode artifact: human reviewers can open it in any browser without an editor, and frontmatter survives as both pill chips and a parseable JSON script tag. ce-work and the review skills continue to consume markdown plans, and a clear Implementation Note at the top of every HTML plan tells anyone who picks one up to run ce-plan without
--htmlto produce the markdown source ce-work expects.Why this matters
fix(ce-plan): render Implementation Units as headings, not bulleted list items) and #765 (ce-plan Implementation Units template breaks markdown rendering). The pain of "plans should look right when a human reads them" is felt and recent.plugins/compound-engineering/skills/_shared/html-output.md) that other document-producing skills can adopt without re-writing CSS or HTML skeletons.Demo
The committed fixture at
tests/fixtures/ce-plan/sample-plan.htmlis whatce-plan --htmlproduces for a sample input. Download and open it in any browser to see the rendered output: status / type / date pills at the top, anchored TOC on the left, real<table>for Requirements traceability, real<table>for Test Scenarios nested inside each Implementation Unit's<article id="uN">, an inline SVG dependency diagram, the Implementation Note callout, and a dark-mode variant via@media (prefers-color-scheme: dark). The fixture is 14KB, well under the 80KB anti-bloat budget.Light mode, dark mode, and mobile (400px) viewports all render correctly when opened locally with headless Chrome.
Scope
This is Phase 1 of a planned 6-phase rollout. Subsequent phases extend
--htmlto the rest of the document-producing ce-* surface (ce-brainstorm, ce-strategy, ce-ideate, ce-debug, ce-doc-review, ce-code-review, ce-compound, ce-product-pulse, ce-sessions, plus the document tail), then a Phase 6 end-to-end pipeline integration test. Each phase ships as its own PR after this lands and the shared infrastructure design is validated.Files in this PR:
plugins/compound-engineering/skills/_shared/html-output.md(new) - shared HTML output reference: document skeleton, ~250-line embedded CSS theme with dark-mode and mobile breakpoints, frontmatter-as-JSON contract, anchor-ID conventions, inline-SVG patterns for data flow / sequence / dependency diagrams, anti-bloat rules, reuse contract.plugins/compound-engineering/skills/ce-plan/references/html-plan-template.md(new) - per-skill template that extends the shared skeleton with plan-specific structure: Requirements traceability<table>, Implementation Units as<article id="uN">, nested Test Scenarios tables, Implementation Note callout.plugins/compound-engineering/skills/ce-plan/SKILL.md(modified) - new "## Output Format" section, OUTPUT_FORMAT branch in Phase 4.2, post-generation menu shows "Open in browser" instead of "Start /ce-work" when in HTML mode.plugins/compound-engineering/skills/ce-plan/references/visual-communication.md(modified) - "## HTML Mode Diagrams" section pointing at the three SVG patterns in the shared reference.tests/skills/ce-plan-html-output.test.ts(new) - 10 Bun tests: HTML5 structure, frontmatter JSON round-trip, status/type/date pills, U-ID anchors matching nav, real table semantics, no external resource references, size budget under 80KB.tests/fixtures/ce-plan/sample-plan.html(new) - committed snapshot of expected output.plugins/compound-engineering/README.md(modified) - ce-plan row mentions--html.tests/skill-agent-ce-prefix.test.ts(modified) - exempts underscore-prefixed support directories from thece-prefix invariant so_shared/is not treated as an installable skill. Necessary side effect of adding the shared directory; no other behavior change.Out of Scope (intentional follow-ups)
--htmlin Phases 2-5.Tests
bun test: 1355 pass, 0 fail (10 new tests for HTML output mode).bun run release:validate: passes; metadata still reports 49 agents, 37 skills, 0 MCP servers (the new_shared/directory is exempted from the installable-skill count by the prefix-invariant test).Open question
Where should the shared HTML output reference live?
A.
plugins/compound-engineering/skills/_shared/html-output.md(this PR)B.
plugins/compound-engineering/references/html-output.md(plugin-level, not skill-scoped)C. A new sibling skill
ce-html-renderthat other skills delegate toI went with A because
references/files already extend single skills today and the shared file is genuinely shared infrastructure rather than its own skill. The_shared/directory uses the underscore-prefix convention to signal "not an installable skill." Open to flipping if either of you prefer B or C; the next time this decision becomes load-bearing is when Phase 2 templates start importing from it.AI was used for assistance.