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, date, type, etc. — exact fields are per-skill, defined in the section contract).
• 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).
• File references are repo-relative unless the producing skill's section contract explicitly defines a qualified local artifact citation.
• No HTML mixed in. Keep the markdown pure. No <div>, no <details>, no inline <style>. The only exception is a contract-defined invisible semantic marker such as <!-- ce-section: work-relationships -->; it carries section meaning for downstream agents and does not create layout. If a layout idea only works as HTML, defer it to the HTML rendering. Markdown stays markdown.
• No fixed-width line wrapping. Do not hard-wrap prose to a column (e.g. 80 chars). Write one sentence per line, or let each paragraph flow as a single line. The artifact is read rendered and shared, where fixed wraps add nothing and only produce noisy mid-sentence diffs; markdown joins soft line breaks within a paragraph, so wrapping never changes the rendered output.
• Unified plan sections use stable headings. For unified plan artifacts, render the required sections with exact ASCII headings so agents can find them by heading scan: ## Goal Capsule, ## Product Contract, ## Planning Contract, ## Implementation Units, ## Verification Contract, ## Definition of Done, and optional ## Appendix. Requirements-only artifacts omit the plan-only sections rather than emitting empty placeholders. These stable headings are the wayfinding contract: consumers scan them (markdown headings, or <h1>–<h3> / anchor ids in HTML) instead of reading the whole document.
• Goal Capsule is top-loaded. It appears before Product Contract and long appendices for fast orientation — not a hidden machine copy.

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.

• Goal Capsule — bullets or a small table for objective, means (only when an approach is fixed), authority, execution profile, stop conditions, and who finishes the remaining work.
• Product Contract — H2 section containing Summary, Problem Frame, Requirements, and product-scope subsections. Put Requirements under ### Requirements so review tools can distinguish Product Requirements from implementation detail.
• Planning Contract — H2 section for KTDs, high-level technical design, assumptions, and sequencing.
• 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. When the work ships as several PRs, each PR group is an H3 heading (### PR<N>: <title>; executors name the group by its PR<N> label) followed by its Waits on: line, and the group's units follow as their own H3 U<N>. headings.
• Verification Contract / Definition of Done — use tables when commands, applicability, unit IDs, and done signals share a uniform shape. Name concrete repo commands such as bun test rather than generic "run tests" when the repo has known commands.
• Key Technical Decisions — bullets with KTD<N>. plain prefix (same format as R1./U1.) + bold decision name + prose rationale. Legacy plans with unnumbered KTDs stay readable by label; do not renumber existing numbered ones. A session-settled: annotation renders as part of the KTD bullet's visible text, stem preserved verbatim.
• 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.

For a UI/layout shape that would be a wireframe in HTML, markdown has no inline-SVG wireframe affordance. Render the region composition as a mermaid layout flowchart (or describe it in prose) — never hand-draw a box-drawing/ASCII wireframe; it violates the no-box-drawing-characters rule and reads poorly. The wireframe proper is an HTML-only affordance.

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 (created_at, topic, not CreatedAt, Topic).
• No status / lifecycle field. Artifacts are point-in-time records (decision or discovery), not tracked work items. Do not introduce a mutable status field or an active → completed lifecycle — whether the work shipped is derived from git, not stored in the doc.
• 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.
• File paths are repo-relative except for qualified local artifact citations defined by the producing skill's section contract.
• 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.