compound-engineering-plugin-mirror/plugins/compound-engineering/skills/ce-plan/references/markdown-rendering.md

Markdown Rendering

This is a format-rendering reference — it describes how to render any artifact in markdown, independent of which skill is producing it.

It is paired with a section contract (plan-sections.md, brainstorm-sections.md, etc.) that describes what the artifact contains. This reference describes how markdown specifically presents it. The same content rendered by different skills shares the same markdown principles.

Hard invariants

These hold regardless of which skill produced the artifact.

• YAML frontmatter at the top of the file. Standard --- delimited block containing the artifact's stable metadata (title, status, date, type, etc. — exact fields are per-skill, defined in the section contract). Editable in place; tools and agents that do status flips (active → completed) update the YAML directly.
• ASCII identifiers in anchors. Markdown headings auto-generate anchors from the heading text. Keep headings ASCII so anchors are predictable (#implementation-units, not #implementación-units).
• Repo-relative paths for file references. Always. Never absolute paths — they break portability across machines, worktrees, teammates.
• No HTML mixed in. Keep the markdown pure. No <div>, no <details>, no inline <style>. If a layout idea only works as HTML, defer it to the HTML rendering. Markdown stays markdown.

Format principles

These shape what "good" markdown looks like; the agent applies them per artifact based on content shape.

ID prefix format

Stable IDs (R, U, A, F, AE, KTD) appear as plain prefixes at the start of the bullet or heading — do NOT bold the prefix. The prefix is visually distinctive on its own; bolding it inflates visual noise.

- R1. The plan returns paginated sessions.   ← right
- **R1.** The plan returns paginated sessions.   ← wrong (bolded prefix)

Same applies to unit headings: ### U1. Cloak detection in preflight contract.

Content shape: prose vs bullets vs tables

The same content can be rendered three ways; the agent picks per content shape, not by template default.

• Prose when the content has narrative flow (motivation, decision rationale, problem framing). Bullets fragment narrative into disconnected pieces.
• Bullets when items share a parallel shape but each carries enough prose to not fit a table cell.
• Tables when 5+ items share uniform structure (ID + body, name + value, decision + rationale, risk + mitigation). Tables scan faster at that scale and unlock additional columns (status, traceability, severity) that bullets can't accommodate cleanly.

The test: which shape would a reader scan fastest for this content? If items have parallel structure and 5+ instances, table. If items are 3-5 and each has a few lines of prose, bullets. If the content is a single narrative thought, prose.

Bold leader labels within bullets

When a bullet has substructure that benefits from named fields (Key Flows with Trigger / Actors / Steps / Outcome, Acceptance Examples with Covers / Given / When / Then), use bold leader labels at the start of nested bullets — not deeper heading levels.

- F1. Anonymous capture
  - **Trigger:** Agent enters Step 2a with no session.
  - **Actors:** A1, A2
  - **Steps:** Preflight detects cloak; agent launches; capture proceeds.
  - **Covered by:** R1, R2, R5

This gives the bullet structure without needing H4/H5 headings that would clutter the doc and break TOC generation.

Section separators

For substantial artifacts, use horizontal rules (---) between top-level H2 sections. Omit for short docs where separators would dominate.

Tables for genuinely comparative info only

Use tables for the uniform-shape case in "Content shape" above. Don't use tables to render content lists that are really bullets — markdown tables are noisier in raw form and worse for diffs.

Section anatomy

How section types commonly render in markdown. These are patterns, not contracts — the agent picks the shape that fits the content.

• Summary / Problem Frame — prose paragraphs.
• Requirements — bullets with R<N>. prefix. When requirements span more than one concern, grouping under bold inline headers is the default shape, not optional polish (group by capability, not by discussion order); render a flat list only when every requirement is about the same thing. When requirements have status, traceability, or severity that warrant additional columns, escalate to a table.
• Implementation Units — H3 heading per unit with U<N>. prefix. Fields (Goal, Files, Patterns, Test Scenarios, Verification) render as bullets with bold leader labels, or as sub-headings if the field has multi-paragraph content.
• Key Technical Decisions — bullets with bold decision name + prose rationale, or numbered KTD-N pattern when traceability matters.
• Key Flows / Acceptance Examples — bullets with bold leader labels (Trigger / Actors / Steps / Outcome / Covers / Given-When-Then).
• Scope Boundaries — bullets, optionally split into "Deferred for later" / "Outside this product's identity" sub-headings when the positioning distinction matters.

The agent picks more elaborate or simpler shapes based on what each specific artifact's content needs.

Diagrams

When the section contract calls for a diagram (architecture, sequence, flowchart, state machine, swim lane, data-flow), markdown renders it as a fenced mermaid block:

` ``mermaid
flowchart TB
  A[Start] --> B{Decision}
  B -->|yes| C[Action]
  B -->|no| D[Other action]
` ``

(TB direction default — keeps diagrams narrow in source view and in narrow rendered viewports.)

Markdown's diagram affordances are limited compared to HTML. For quantitative comparisons (bar charts, scatter plots) markdown has no native equivalent — use a table with the data and let prose or caption carry the interpretation. The richer visualization happens in the HTML rendering.

Inline code and code blocks

• Inline code for identifiers (variable names, function names, flag names, file paths, IDs that aren't section anchors).
• Fenced code blocks with language tag for code, shell commands, API request/response samples. Always specify the language for syntax highlighting and accessibility.

The flag `--cdp-url` accepts a URL.

` ``bash
browser-use --cdp-url http://localhost:9222
` ``

No process exhaust

Engineering process metadata stays out of the artifact:

• No "captured at Phase X" notes
• No ## Next Steps pointing to the next skill
• No italic provenance lines ("Brainstorm completed 2026-05-13")
• No engineering-flow shepherding ("Now read this file:", "Next, run that command:")

This information belongs in commit messages, tool output, and agent transcripts — not in the artifact a reader returns to weeks later.

Frontmatter shape

Per-skill frontmatter fields are defined in each skill's section contract (plan-sections.md lists plan frontmatter; brainstorm-sections.md lists brainstorm frontmatter). Common rules:

• YAML at the top of the file, delimited by --- on its own line above and below.
• Field names in lowercase snake_case (status, created_at, not Status, CreatedAt).
• Status lifecycle is per-contract. When the section contract defines a status field with a lifecycle (plans use active → completed, flipped by ce-work at shipping time via direct YAML edit), it is editable in place. When the section contract does not define a status lifecycle (brainstorms, for example, have no active → completed flip — they are upstream of plans and referenced via the plan's origin:), do not introduce one.
• Stable across artifact revisions — never rename or repurpose a field.

Post-write audit

Before declaring the markdown file written, scan it for these common slips:

• All stable IDs are plain-prefix format, not bolded.
• No HTML elements mixed in.
• All file paths are repo-relative.
• Horizontal rule separators between H2s (for Standard / Deep artifacts).
• No process exhaust (Phase X notes, Next Steps pointers, provenance lines).
• Tables only where 5+ uniform-shape items justify them.
• Frontmatter has all the per-skill required fields with reasonable values.