plan
Work
Work item with acceptance criteria, references, and implementation tracking
Install
- Add the package:
npm install @refrakt-md/plan - Add it to the
pluginsarray inrefrakt.config.json:"plugins": ["@refrakt-md/plan"]
Source
import { createContentModelSchema, slotSections } from '@refrakt-md/runes';
import type { EmitsDeclaration } from '@refrakt-md/runes';
import { VALID_STATUS, VALID_PRIORITY, VALID_COMPLEXITY } from '../commands/enums.js';
export const workEmits = {
rune: 'work',
tag: 'article',
properties: {
id: '',
status: 'draft',
priority: 'medium',
complexity: 'unknown',
assignee: '',
milestone: '',
source: '',
supersedes: '',
pr: '',
tags: '',
created: { from: ['attrs.created', 'file.created'], default: '' },
modified: { from: ['attrs.modified', 'file.modified'], default: '' },
},
slots: {
title: { as: 'region', el: 'header' },
blurb: { from: 'description', as: 'region', omitWhenEmpty: true },
intro: { as: 'region', omitWhenEmpty: true, role: 'body' },
body: { from: 'sections', as: 'region' },
},
} satisfies EmitsDeclaration;
export const workSections = slotSections(workEmits);
export const work = createContentModelSchema({
provides: ['prose'],
attributes: {
id: { type: String, required: true, description: 'Unique identifier (e.g., "WORK-042").' },
status: {
type: String,
required: false,
matches: [...VALID_STATUS.work],
description:
'Current status: draft, ready, in-progress, review, done, blocked, pending, cancelled, or superseded.',
},
priority: {
type: String,
required: false,
matches: [...VALID_PRIORITY],
description: 'Priority level: critical, high, medium, or low.',
},
complexity: {
type: String,
required: false,
matches: [...VALID_COMPLEXITY],
description: 'Complexity signal: trivial, simple, moderate, complex, or unknown.',
},
assignee: { type: String, required: false, description: 'Person or agent working on this.' },
milestone: { type: String, required: false, description: 'Milestone this belongs to.' },
source: {
type: String,
required: false,
description: 'Comma-separated IDs of specs or decisions this item implements.',
},
supersedes: {
type: String,
required: false,
description: 'ID of the work item this replaces (set when status="superseded").',
},
pr: {
type: String,
required: false,
description:
'Comma-separated PR references that implemented this item (e.g. "refrakt-md/refrakt#142").',
},
tags: { type: String, required: false, description: 'Comma-separated labels.' },
created: {
type: String,
required: false,
description: 'Creation date (ISO 8601). Defaults to file creation date from git.',
},
modified: {
type: String,
required: false,
description: 'Last modified date (ISO 8601). Defaults to file modification date from git.',
},
},
contentModel: () => ({
type: 'sections' as const,
sectionHeading: 'heading:2',
fields: [
{ name: 'title', match: 'heading', optional: false },
{ name: 'description', match: 'paragraph', optional: true, greedy: true },
{ name: 'intro', match: 'any', optional: true, greedy: true },
],
sectionModel: {
type: 'sequence' as const,
fields: [{ name: 'body', match: 'any', optional: true, greedy: true }],
},
knownSections: {
'Acceptance Criteria': {
alias: ['Criteria', 'AC', 'Done When'],
},
'Blocked by': {
alias: ['Depends On', 'Requires', 'Deps', 'Needs', 'Dependencies'],
},
Blocks: {
alias: ['Unblocks', 'Enables', 'Required By'],
},
Approach: {
alias: ['Technical Notes', 'Implementation Notes', 'How'],
},
References: {
alias: ['Refs', 'Related', 'Context'],
},
'Edge Cases': {
alias: ['Exceptions', 'Corner Cases'],
},
Verification: {
alias: ['Test Cases', 'Tests'],
},
},
}),
emits: workEmits,
});
A discrete piece of implementation work with acceptance criteria, priority, complexity, and status tracking. Not a user story — a clear description of what needs to change.
Also available as {% task %}.
Ready work item
A work item ready for implementation with acceptance criteria and approach.
{% work id="WORK-9142" status="ready" priority="high" complexity="moderate" milestone="v0.5.0" tags="tint,theming" %}
# Implement tint rune dark mode support
The tint rune currently handles single-scheme color tokens. It needs to support dual light/dark definitions.
## Acceptance Criteria
- [ ] Tint rune accepts light and dark content sections
- [ ] Dark values apply when the reader's system is in dark mode
- [ ] Theme CSS swaps tokens in prefers-color-scheme: dark
- [ ] Inline tints without dark values fall back to page tokens
- [ ] Inspector audits contrast ratios for both variants
## Approach
Authors write the light and dark values under their own headings in the tint body. Each set applies in its color scheme, and a tint with only light values keeps the page's dark colors.
{% /work %}<article data-rune="work" data-rune-fields="{"id":"WORK-9142","status":"ready","priority":"high","complexity":"moderate","assignee":"","milestone":"v0.5.0","source":"","supersedes":"","pr":"","tags":"tint,theming","created":"2026-11-11","modified":"2026-11-11"}">
<header data-name="title">
<h1 id="implement-tint-rune-dark-mode-support">Implement tint rune dark mode support</h1>
</header>
<div data-name="blurb">
<p>The tint rune currently handles single-scheme color tokens. It needs to support dual light/dark definitions.</p>
</div>
<div data-name="body">
<section data-name="acceptance-criteria">
<h2 id="acceptance-criteria" data-known-section="Acceptance Criteria">Acceptance Criteria</h2>
<ul>
<li>[ ] Tint rune accepts light and dark content sections</li>
<li>[ ] Dark values apply when the reader's system is in dark mode</li>
<li>[ ] Theme CSS swaps tokens in prefers-color-scheme: dark</li>
<li>[ ] Inline tints without dark values fall back to page tokens</li>
<li>[ ] Inspector audits contrast ratios for both variants</li>
</ul>
</section>
<section data-name="approach">
<h2 id="approach" data-known-section="Approach">Approach</h2>
<p>Authors write the light and dark values under their own headings in the tint body. Each set applies in its color scheme, and a tint with only light values keeps the page's dark colors.</p>
</section>
</div>
</article>Implement tint rune dark mode support
The tint rune currently handles single-scheme color tokens. It needs to support dual light/dark definitions.
Acceptance Criteria
- Tint rune accepts light and dark content sections
- Dark values apply when the reader's system is in dark mode
- Theme CSS swaps tokens in prefers-color-scheme: dark
- Inline tints without dark values fall back to page tokens
- Inspector audits contrast ratios for both variants
Approach
Authors write the light and dark values under their own headings in the tint body. Each set applies in its color scheme, and a tint with only light values keeps the page's dark colors.
<article class="rf-work rf-work--WORK-9142 rf-work--ready rf-work--high rf-work--moderate" data-id="WORK-9142" data-status="ready" data-priority="high" data-complexity="moderate" data-assignee="" data-milestone="v0.5.0" data-source="" data-supersedes="" data-pr="" data-tags="tint,theming" data-created="2026-11-11" data-modified="2026-11-11" data-rune="work" data-density="full">
<div data-name="eyebrow" data-zone="eyebrow" data-zone-layout="bar" class="rf-work__eyebrow">
<span data-meta-type="id" data-field="id">WORK-9142</span>
<span data-meta-type="status" data-meta-sentiment="neutral" data-align="end" data-field="status">ready</span>
</div>
<header data-name="title" class="rf-work__title" data-section="title">
<h1 id="implement-tint-rune-dark-mode-support">Implement tint rune dark mode support</h1>
</header>
<div data-name="blurb" class="rf-work__blurb" data-section="description">
<p>The tint rune currently handles single-scheme color tokens. It needs to support dual light/dark definitions.</p>
</div>
<dl data-name="metadata" data-zone="metadata" data-zone-layout="definition-list" class="rf-work__metadata">
<div data-name="row" data-field="priority" class="rf-work__row">
<dt data-meta-label="">Priority</dt>
<dd>
<span data-meta-type="category" data-meta-sentiment="caution">high</span>
</dd>
</div>
<div data-name="row" data-field="complexity" class="rf-work__row">
<dt data-meta-label="">Complexity</dt>
<dd>
<span data-meta-type="quantity">moderate</span>
</dd>
</div>
<div data-name="row" data-field="milestone" class="rf-work__row">
<dt data-meta-label="">Milestone</dt>
<dd>
<span data-meta-type="tag">v0.5.0</span>
</dd>
</div>
<div data-name="row" data-field="created" class="rf-work__row">
<dt data-meta-label="">Created</dt>
<dd>
<time data-meta-type="temporal" datetime="2026-11-11">2026-11-11</time>
</dd>
</div>
<div data-name="row" data-field="modified" class="rf-work__row">
<dt data-meta-label="">Modified</dt>
<dd>
<time data-meta-type="temporal" datetime="2026-11-11">2026-11-11</time>
</dd>
</div>
</dl>
<div data-name="tags" data-zone="tags" data-zone-layout="bar" class="rf-work__tags">
<span data-meta-type="tag" data-field="tags">tint</span>
<span data-meta-type="tag" data-field="tags">theming</span>
</div>
<div data-name="body" class="rf-work__body" data-section="body">
<section data-name="acceptance-criteria" class="rf-work__acceptance-criteria">
<h2 id="acceptance-criteria" data-known-section="Acceptance Criteria">Acceptance Criteria</h2>
<ul>
<li data-checked="unchecked">Tint rune accepts light and dark content sections</li>
<li data-checked="unchecked">Dark values apply when the reader's system is in dark mode</li>
<li data-checked="unchecked">Theme CSS swaps tokens in prefers-color-scheme: dark</li>
<li data-checked="unchecked">Inline tints without dark values fall back to page tokens</li>
<li data-checked="unchecked">Inspector audits contrast ratios for both variants</li>
</ul>
</section>
<section data-name="approach" class="rf-work__approach">
<h2 id="approach" data-known-section="Approach">Approach</h2>
<p>Authors write the light and dark values under their own headings in the tint body. Each set applies in its color scheme, and a tint with only light values keeps the page's dark colors.</p>
</section>
</div>
</article>How Markdown is read
| You write | It becomes |
|---|---|
| A heading | The item's title |
| The paragraphs right after it | The item's lead |
Anything else before the first ##, such as a > Ref: blockquote, a list or a table | An intro above the sections |
A ## heading | A named section, such as Acceptance Criteria or Approach; the content up to the next ## is its body |
A ## Blocked by or ## Blocks section listing IDs | The item's dependencies, which plan next and plan validate read |
Blocked work item
A work item blocked by a dependency.
{% work id="WORK-9215" status="blocked" priority="medium" complexity="complex" assignee="alice" %}
# Alignment system migration
Migrate all runes from manual alignment classes to the new alignment system.
## Acceptance Criteria
- [ ] All runes use alignment utilities instead of manual classes
- [ ] No visual regressions in existing content
- [ ] Migration guide published
{% /work %}<article data-rune="work" data-rune-fields="{"id":"WORK-9215","status":"blocked","priority":"medium","complexity":"complex","assignee":"alice","milestone":"","source":"","supersedes":"","pr":"","tags":"","created":"2026-11-11","modified":"2026-11-11"}">
<header data-name="title">
<h1 id="alignment-system-migration">Alignment system migration</h1>
</header>
<div data-name="blurb">
<p>Migrate all runes from manual alignment classes to the new alignment system.</p>
</div>
<div data-name="body">
<section data-name="acceptance-criteria">
<h2 id="acceptance-criteria" data-known-section="Acceptance Criteria">Acceptance Criteria</h2>
<ul>
<li>[ ] All runes use alignment utilities instead of manual classes</li>
<li>[ ] No visual regressions in existing content</li>
<li>[ ] Migration guide published</li>
</ul>
</section>
</div>
</article>Alignment system migration
Migrate all runes from manual alignment classes to the new alignment system.
Acceptance Criteria
- All runes use alignment utilities instead of manual classes
- No visual regressions in existing content
- Migration guide published
<article class="rf-work rf-work--WORK-9215 rf-work--blocked rf-work--medium rf-work--complex" data-id="WORK-9215" data-status="blocked" data-priority="medium" data-complexity="complex" data-assignee="alice" data-milestone="" data-source="" data-supersedes="" data-pr="" data-tags="" data-created="2026-11-11" data-modified="2026-11-11" data-rune="work" data-density="full">
<div data-name="eyebrow" data-zone="eyebrow" data-zone-layout="bar" class="rf-work__eyebrow">
<span data-meta-type="id" data-field="id">WORK-9215</span>
<span data-meta-type="status" data-meta-sentiment="negative" data-align="end" data-field="status">blocked</span>
</div>
<header data-name="title" class="rf-work__title" data-section="title">
<h1 id="alignment-system-migration">Alignment system migration</h1>
</header>
<div data-name="blurb" class="rf-work__blurb" data-section="description">
<p>Migrate all runes from manual alignment classes to the new alignment system.</p>
</div>
<dl data-name="metadata" data-zone="metadata" data-zone-layout="definition-list" class="rf-work__metadata">
<div data-name="row" data-field="priority" class="rf-work__row">
<dt data-meta-label="">Priority</dt>
<dd>
<span data-meta-type="category" data-meta-sentiment="neutral">medium</span>
</dd>
</div>
<div data-name="row" data-field="complexity" class="rf-work__row">
<dt data-meta-label="">Complexity</dt>
<dd>
<span data-meta-type="quantity">complex</span>
</dd>
</div>
<div data-name="row" data-field="assignee" class="rf-work__row">
<dt data-meta-label="">Assignee</dt>
<dd>
<span data-meta-type="tag">alice</span>
</dd>
</div>
<div data-name="row" data-field="created" class="rf-work__row">
<dt data-meta-label="">Created</dt>
<dd>
<time data-meta-type="temporal" datetime="2026-11-11">2026-11-11</time>
</dd>
</div>
<div data-name="row" data-field="modified" class="rf-work__row">
<dt data-meta-label="">Modified</dt>
<dd>
<time data-meta-type="temporal" datetime="2026-11-11">2026-11-11</time>
</dd>
</div>
</dl>
<div data-name="body" class="rf-work__body" data-section="body">
<section data-name="acceptance-criteria" class="rf-work__acceptance-criteria">
<h2 id="acceptance-criteria" data-known-section="Acceptance Criteria">Acceptance Criteria</h2>
<ul>
<li data-checked="unchecked">All runes use alignment utilities instead of manual classes</li>
<li data-checked="unchecked">No visual regressions in existing content</li>
<li data-checked="unchecked">Migration guide published</li>
</ul>
</section>
</div>
</article>Retiring a work item
Not every work item ships. Rather than deleting the file (which loses the reasoning trail) or marking it done (which lies to progress rollups), use one of the two terminal-but-non-achieving states:
cancelled— the work is deliberately dropped and no longer wanted. Record the reason in the body or a## Resolution.superseded— the work is replaced by a different item. Pair it withsupersedes="WORK-xxx"pointing at the replacement.
Both statuses end the item's lifecycle without counting as completion — they are excluded from plan next, from milestone progress, and from plan-progress achieved counts. A ## Resolution explaining the retirement is allowed on either.
Attributes
| Attribute | Type | Required | Description |
|---|---|---|---|
id | string | ✓ | Unique identifier (e.g., "WORK-042"). |
status | "draft" | "ready" | "in-progress" | "review" | "done" | "blocked" | "pending" | "cancelled" | "superseded" | — | Current status: draft, ready, in-progress, review, done, blocked, pending, cancelled, or superseded. |
priority | "critical" | "high" | "medium" | "low" | — | Priority level: critical, high, medium, or low. |
complexity | "trivial" | "simple" | "moderate" | "complex" | "unknown" | — | Complexity signal: trivial, simple, moderate, complex, or unknown. |
assignee | string | — | Person or agent working on this. |
milestone | string | — | Milestone this belongs to. |
source | string | — | Comma-separated IDs of specs or decisions this item implements. |
supersedes | string | — | ID of the work item this replaces (set when status="superseded"). |
pr | string | — | Comma-separated PR references that implemented this item (e.g. "refrakt-md/refrakt#142"). |
tags | string | — | Comma-separated labels. |
created | string | — | Creation date (ISO 8601). Defaults to file creation date from git. |
modified | string | — | Last modified date (ISO 8601). Defaults to file modification date from git. |
Universal attributes
bg
The background layer: image, video, gradient, flat overlay wash and legibility scrim, in a single injected layer behind the rune's content.
| Attribute | Type | Required | Description |
|---|---|---|---|
bg | string | — | Background preset applied to this block |
bg-from | string | — | Gradient start colour — a semantic token name (→ var(--rf-color-*)) |
bg-gradient | "to-t" | "to-b" | "to-l" | "to-r" | "to-tr" | "to-br" | "to-bl" | "to-tl" | — | Gradient direction (bounded named set) |
bg-gradient-type | "linear" | "radial" | "conic" | — | Gradient type |
bg-to | string | — | Gradient end colour — a semantic token name |
bg-via | string | — | Optional middle gradient stop — a semantic token name |
scrim | "top" | "bottom" | "left" | "right" | "none" | — | Scrim direction (heaviest edge); presence turns the scrim on, "none" opts out of the default cover scrim |
scrim-blur | "none" | "sm" | "md" | "lg" | — | Frost scrim blur amount |
scrim-strength | "sm" | "md" | "lg" | — | Gradient scrim strength |
scrim-tone | "dark" | "light" | — | Whether the scrim darkens (for light text) or lightens (for dark text) |
scrim-type | "gradient" | "frost" | — | Scrim treatment: gradient (default) or frost (backdrop blur) |
dropcap
Per-instance drop-cap opt-in.
| Attribute | Type | Required | Description |
|---|---|---|---|
dropcap | boolean | — | Style the opening letter of a prose body as a drop cap. Honoured only when the body reads as prose; ignored otherwise. |
elevation
How far the rune sits off the page, from sunken to overlay. The theme decides what each step looks like.
| Attribute | Type | Required | Description |
|---|---|---|---|
elevation | "sunken" | "flush" | "flat" | "raised" | "floating" | "overlay" | "none" | "sm" | "md" | "lg" | — | Surface depth, from sunken to overlay. Deprecated: none, sm, md and lg (read as flat, raised, raised and floating) |
inset
Internal padding override.
| Attribute | Type | Required | Description |
|---|---|---|---|
inset | "flush" | "tight" | "default" | "loose" | "breathe" | — | Inner padding of this block |
motion
Scroll-reveal entrance. You choose its character; the theme decides how it moves.
| Attribute | Type | Required | Description |
|---|---|---|---|
reveal | "none" | "fade" | "slide" | "scale" | "blur" | — | Scroll-reveal entrance character (none|fade|slide|scale|blur); the theme owns the choreography |
stagger | boolean | — | Cascade this block's items in as it reveals (no-op on single-child runes) |
prominence
Header emphasis. Scales a rune's header, or its featured quotation; the theme decides the type size for each step.
| Attribute | Type | Required | Description |
|---|---|---|---|
prominence | "quiet" | "normal" | "prominent" | "display" | "marquee" | — | Emphasis of a page-section header or a featured quotation (only on runes that have one) |
reading
Editorial register for body text. You pick the register; the theme decides how it looks.
| Attribute | Type | Required | Description |
|---|---|---|---|
reading | "fine" | "ui" | "prose" | — | Reading register for this block’s body: fine | ui | prose. The theme sets how each one looks. |
spacing
Block-level rhythm override.
| Attribute | Type | Required | Description |
|---|---|---|---|
spacing | "flush" | "tight" | "default" | "loose" | "breathe" | — | Vertical spacing above and below this block |
substrate
Generated pattern fills behind the content, drawn by the theme.
| Attribute | Type | Required | Description |
|---|---|---|---|
substrate | "dots" | "grid" | "lines" | "cross" | "checker" | "none" | — | Generated surface pattern |
substrate-fill | "inherit" | "inset" | — | Surface fill the pattern sits on (full colour stays with tint) |
substrate-opacity | "sm" | "md" | "lg" | — | Pattern ink strength |
substrate-size | "sm" | "md" | "lg" | — | Pattern cell size |
substrate-target | "self" | "media" | — | Which surface the pattern fills (overrides the rune/theme default) |
tint
Per-rune colour override: a named tint from the theme registry, with inline per-token overrides layered on top.
| Attribute | Type | Required | Description |
|---|---|---|---|
tint | string | — | Color tint preset applied to this block |
tint-mode | "auto" | "dark" | "light" | — | Whether the tint adapts to auto, dark, or light mode |
width
The track a block rune occupies.
| Attribute | Type | Required | Description |
|---|---|---|---|
width | "compact" | "narrow" | "content" | "wide" | "full" | — | Maximum width constraint for this block |
| Not available | Why |
|---|---|
| frame | this rune declares neither a `frameTarget` nor a media section |