Example Plan Entities

This page contains sample plan entities that populate the backlog, decision log, progress, and activity aggregation rune examples throughout this section.

Content model validation errors

Improve error messages when content model validation fails during transform. Current errors show internal node types instead of author-facing rune names.

Acceptance Criteria

Error messages include source file and line numbers
Validation errors show expected vs actual structure
Nested rune errors reference the parent rune context

Token fallback chain for nested tints

When tint runes are nested, child tints should fall back to the parent tint value rather than the global default.

Acceptance Criteria

Nested tints inherit parent tint custom properties
Fallback chain works three levels deep

Interactive rune playground

Build a live editor where users can write Markdoc with runes and see the rendered output side by side.

Acceptance Criteria

Editor supports syntax highlighting for Markdoc
Preview updates on every keystroke with debounce
Errors display inline in the editor gutter
Shareable URLs encode the editor content

Heading level auto-detection for nested runes

When runes are nested, inner headings should auto-increment their level so the document outline remains valid.

Acceptance Criteria

Engine tracks current heading depth during transform
Child rune headings offset by parent depth
Inspector warns when manual heading levels conflict with auto-detection

Snapshot tests for identity transform output

Add snapshot tests that capture the full HTML output of the identity transform for each core rune.

Acceptance Criteria

Snapshot test harness reads fixture .md files
Snapshots cover all core rune variants
CI fails on unexpected snapshot changes

Add copy button to code fences

Add a click-to-copy button to all code fence blocks in the documentation site.

Acceptance Criteria

Copy button appears on hover
Clicking copies fence content to clipboard
Visual feedback confirms the copy action

Theme marketplace architecture

Design the architecture for a theme marketplace where community themes can be published, discovered, and installed.

Acceptance Criteria

Architecture document covers package format, registry, and discovery
Security model for third-party theme code defined

Responsive modifier system

Allow runes to accept responsive modifiers that change layout at different breakpoints.

Acceptance Criteria

Engine parses responsive modifier syntax
Identity transform emits breakpoint-specific data attributes
CSS uses container queries for responsive behaviour
Documentation covers responsive modifier usage

Pipeline crashes on circular entity references

When two work items reference each other (e.g. WORK-A mentions WORK-B and vice versa), the relationship builder enters an infinite loop.

Steps to Reproduce

Create two work items that reference each other by ID
Run the build

Expected

Circular references produce a bidirectional "related" relationship.

Actual

Build hangs indefinitely during the aggregate phase.

Backlog card wraps awkwardly at narrow widths

At viewport widths below 400px, the backlog card header badges overlap the title text.

Steps to Reproduce

Open a page with a backlog rune
Resize the browser below 400px

Expected

Badges wrap below the title on small screens.

Actual

Badges overlap the title text.

Decision log ignores date filter

Passing filter="date:2026-03" to the decision-log rune returns all decisions instead of filtering to March 2026.

Steps to Reproduce

Add decisions with varied dates
Use {% decision-log filter="date:2026-03" /%}

Expected

Only decisions from March 2026 appear.

Actual

All decisions appear regardless of date.

Plan progress bar label misaligned in Safari

The status count label in the plan-progress rune shifts 2px down in Safari compared to Chrome.

Steps to Reproduce

Open a page with plan-progress in Safari
Compare with Chrome

Expected

Identical alignment in both browsers.

Actual

2px vertical offset in Safari.

Design Token Architecture

Specification for the two-tier design token system: global tokens and component tokens.

Overview

Global tokens define the colour palette, spacing scale, and typographic scale. Component tokens map global tokens to specific rune parts. Themes override global tokens; rune configs may override component tokens.

Token Naming

All tokens use the --rf- prefix followed by category and name: --rf-color-primary, --rf-space-md, --rf-font-size-lg.

Cross-Package Entity References

Allow entities registered by one package to reference entities from another package.

Problem

Currently, entity references (e.g. WORK-001 mentioning SPEC-002) only resolve within the same package's pipeline hooks. Cross-package references are ignored.

Proposed Solution

Add a second pass in the pipeline's aggregate phase that resolves references across package boundaries using the shared EntityRegistry.

Block Editor Protocol

Define the protocol for structured editing of rune content in visual editors.

This specification is in early draft. It will define how editors discover rune schemas, present editing UI for rune attributes, and handle content model constraints.

Use pipeline hooks instead of plugin system

Context

The content pipeline needs extensibility for community packages. Two approaches were considered: a plugin system with lifecycle events, or declarative pipeline hooks on the RunePackage interface.

Decision

Pipeline hooks on RunePackage. Each package declares register, aggregate, and postProcess functions.

Rationale

Hooks are simpler to implement, easier to test in isolation, and enforce a clear execution order. A plugin system would add indirection without meaningful flexibility gains at this stage.

Consequences

Packages cannot hook into arbitrary build phases
Hook execution order is deterministic (package registration order)
Adding new hook points requires a types package release

BEM naming convention for identity transform

Context

The identity transform needs a consistent class naming strategy for rune output. Options: utility classes, CSS modules, or BEM.

Decision

BEM with the rf- prefix: .rf-{block}, .rf-{block}--{modifier}, .rf-{block}__{element}.

Rationale

BEM is framework-agnostic, human-readable in browser devtools, and allows themes to target specific rune parts without coupling to internal structure. The rf- prefix avoids collisions with user styles.

Consequences

Class names are verbose but predictable
Themes can reliably target any rune element
No build tooling required for class generation

Lazy entity registration for large sites

Context

Sites with thousands of plan entities experience slow builds because the register phase walks every page's full renderable tree. Most pages have zero plan entities.

Options Considered

Walk all pages (current) — simple, O(pages * tree_depth)
Frontmatter hint — pages declare has-plan-entities: true, register skips others
AST-level index — build an index during parse phase, register reads the index

Decision

Pending discussion. Leaning toward option 2 for simplicity.