Plan›Work

plan

Work

Work item with acceptance criteria, references, and implementation tracking

Install

  1. Add the package: npm install @refrakt-md/plan
  2. Add it to the plugins array in refrakt.config.json: "plugins": ["@refrakt-md/plan"]

About the plugin and its runes

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,
});

View plugins/plan/src/tags/work.ts on GitHub

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="{&quot;id&quot;:&quot;WORK-9142&quot;,&quot;status&quot;:&quot;ready&quot;,&quot;priority&quot;:&quot;high&quot;,&quot;complexity&quot;:&quot;moderate&quot;,&quot;assignee&quot;:&quot;&quot;,&quot;milestone&quot;:&quot;v0.5.0&quot;,&quot;source&quot;:&quot;&quot;,&quot;supersedes&quot;:&quot;&quot;,&quot;pr&quot;:&quot;&quot;,&quot;tags&quot;:&quot;tint,theming&quot;,&quot;created&quot;:&quot;2026-11-11&quot;,&quot;modified&quot;:&quot;2026-11-11&quot;}">
  <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>
WORK-9142ready

Implement tint rune dark mode support

The tint rune currently handles single-scheme color tokens. It needs to support dual light/dark definitions.

tinttheming

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 writeIt becomes
A headingThe item's title
The paragraphs right after itThe item's lead
Anything else before the first ##, such as a > Ref: blockquote, a list or a tableAn intro above the sections
A ## headingA named section, such as Acceptance Criteria or Approach; the content up to the next ## is its body
A ## Blocked by or ## Blocks section listing IDsThe 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="{&quot;id&quot;:&quot;WORK-9215&quot;,&quot;status&quot;:&quot;blocked&quot;,&quot;priority&quot;:&quot;medium&quot;,&quot;complexity&quot;:&quot;complex&quot;,&quot;assignee&quot;:&quot;alice&quot;,&quot;milestone&quot;:&quot;&quot;,&quot;source&quot;:&quot;&quot;,&quot;supersedes&quot;:&quot;&quot;,&quot;pr&quot;:&quot;&quot;,&quot;tags&quot;:&quot;&quot;,&quot;created&quot;:&quot;2026-11-11&quot;,&quot;modified&quot;:&quot;2026-11-11&quot;}">
  <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>
WORK-9215blocked

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 with supersedes="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

AttributeTypeRequiredDescription
idstring✓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.
assigneestring—Person or agent working on this.
milestonestring—Milestone this belongs to.
sourcestring—Comma-separated IDs of specs or decisions this item implements.
supersedesstring—ID of the work item this replaces (set when status="superseded").
prstring—Comma-separated PR references that implemented this item (e.g. "refrakt-md/refrakt#142").
tagsstring—Comma-separated labels.
createdstring—Creation date (ISO 8601). Defaults to file creation date from git.
modifiedstring—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.

AttributeTypeRequiredDescription
bgstring—Background preset applied to this block
bg-fromstring—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-tostring—Gradient end colour — a semantic token name
bg-viastring—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.

AttributeTypeRequiredDescription
dropcapboolean—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.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
reveal"none" | "fade" | "slide" | "scale" | "blur"—Scroll-reveal entrance character (none|fade|slide|scale|blur); the theme owns the choreography
staggerboolean—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.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
spacing"flush" | "tight" | "default" | "loose" | "breathe"—Vertical spacing above and below this block
substrate

Generated pattern fills behind the content, drawn by the theme.

AttributeTypeRequiredDescription
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.

AttributeTypeRequiredDescription
tintstring—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.

AttributeTypeRequiredDescription
width"compact" | "narrow" | "content" | "wide" | "full"—Maximum width constraint for this block
Not availableWhy
framethis rune declares neither a `frameTarget` nor a media section