Work Items

Add a planLayout alongside the existing docsLayout and blogArticleLayout in the transform package's layout configs.The plan layout is structurally simple: a fixed sidebar slot for navigation and a main content area. No TOC, no breadcrumbs, no version switcher — just the two slots.

Convert the existing buildNavigation() output (NavGroup[]) into a renderable tag tree that can be passed as a layout region to renderFullPage().Currently the sidebar HTML is hand-rolled in the HTML shell template. This work item replaces that with a buildNavRegion() function that produces serialized tags with BEM classes matching the existing .rf-plan-sidebar__* selectors.

The main refactor: replace the bespoke HTML shell template in @refrakt-md/plan with calls to renderFullPage() from @refrakt-md/html. This removes the hand-rolled document structure, inline styles, and direct HTML string concatenation.

Replace the flat entity list in the plan sidebar with status-grouped, collapsible sections. Items are grouped by status within each entity type, with active statuses expanded and terminal statuses collapsed by default. Collapse state persists in localStorage.

Add a text input at the top of the sidebar that filters visible items in real-time. Supports plain text fuzzy matching across ID, title, tags, assignee, and milestone, plus structured field:value filter syntax matching the {% backlog %} rune.

The plan site's renderPage() in runes/plan/src/commands/render-pipeline.ts manually assembles HTML using a local planTheme/planLayout definition, bypassing the shared layout engine in @refrakt-md/transform. Meanwhile, packages/transform/src/layouts.ts already exports a planLayout config (WORK-037) that goes through the standard layout engine but isn't used by the plan site's renderer.Converge the plan site's renderer to use the shared layout engine so it can leverage declarative layout features — computed ToC, conditional slots, behaviors array, computed content — rather than hand-building HTML. This unblocks ToC ("on this page"), dependency visualization (WORK-049), keyboard nav behaviors (WORK-048), and any future layout-level features without custom rendering code.

Extend the refrakt plan update command to accept resolution content and append a ## Resolution section to work item and bug files.

Prerequisite for all framework adapters. Two modules in @refrakt-md/svelte are framework-agnostic and needed by every adapter package.

Migrate the straightforward core runes that use @group decorators with sequential or sectioned patterns. These have no custom processChildren logic — they map directly to sequence, sections, or delimited content models.

Migrate community package runes that use straightforward @group decorator patterns. These map directly to sequence or sections content models with no custom processChildren logic.

Migrate runes that have multiple groups, context-dependent group logic, or light custom processing. These need more careful mapping but don't require the custom escape hatch.

Migrate the remaining runes that have custom processChildren overrides with stateful parsing, text pattern matching, or DOM surgery. All will use the custom content model type.

Once all runes are migrated to createContentModelSchema, delete the legacy API surface from @refrakt-md/runes.

Phase 1 of ADR-005. Update createComponentRenderable to accept either the current Type first argument or a new inline { rune: string, schemaOrgType?: string } form. Update RuneDescriptor and Rune class to carry typeName?: string and schemaOrgType?: string instead of type?: Type.Both signatures must work simultaneously so Phase 2 migration can happen incrementally.

Phase 2a of ADR-005. Update all ~37 core rune transforms in packages/runes/src/tags/ to use the new inline { rune: 'name' } signature for createComponentRenderable instead of importing schema.X from the registry. Each update is a 2-3 line change per file.Depends on WORK-105 (dual-signature support) being complete.

Phase 2b of ADR-005. Update all ~65 community package rune transforms across 8 packages to use the new inline { rune: 'name' } signature for createComponentRenderable. Same mechanical change as WORK-106 but across community packages.Depends on WORK-105 (dual-signature support) being complete.

Extend ModifierConfig with valueMap and mapTarget fields so that modifier values can be declaratively mapped to different data attribute values. This is the smallest SPEC-033 feature and eliminates 2 existing postTransform uses.

Remove the hardcoded COMPACT_CONTEXTS and MINIMAL_CONTEXTS sets from the identity transform engine and replace them with a childDensity field on RuneConfig. This lets community packages declare density behavior without modifying the engine.

Add a slots array to RuneConfig and slot/order fields to StructureEntry. The engine assembles children by iterating slots in declared order instead of using binary before/after placement. This is the core structural change in SPEC-033 that enables multi-zone layouts.

Extend the plan scanner to extract ## Resolution sections from work item and bug files into a structured resolution field on PlanEntity.

Four small bugs identified in the SPEC-037 audit that need immediate fixes.

The validate command has blind spots: source attribute references to non-existent specs/decisions go undetected, milestone references to non-existent milestones pass silently, and complexity values aren't checked at all. These gaps let broken references and invalid data persist.

Define the core TypeScript types for the git-native entity history system and implement the per-entity extraction algorithm that derives structured lifecycle events from git commits.This is the foundational piece that all other SPEC-038 work items depend on. The extraction algorithm walks a file's git history, parses each version's attributes/criteria/resolution, and diffs consecutive snapshots to emit typed HistoryEvent objects.

Implement the plan history <ID> CLI subcommand for viewing the git-derived lifecycle timeline of a single plan entity.

Add a tab panel to plan entity pages (spec, work, bug, decision) that separates the main authored content from pipeline-generated metadata views. Each entity page gets tabs:

Apply @refrakt-md/highlight to the plan render pipeline so code fences in plan content get proper syntax coloring. Currently code blocks render as plain <pre><code> with no highlighting.

Wire @refrakt-md/behaviors into the plan site via initPage() from @refrakt-md/html/client. This enables copy-to-clipboard buttons on code blocks and provides the foundation for future interactive behaviors.

Update the plan site's resolveThemeCss() to read refrakt.config.json when no --theme flag is provided, so the plan site automatically uses the project's installed theme.When a theme package is specified in config, resolve its CSS (design tokens + base styles) and layer it under the plan rune CSS. When resolution fails or no config exists, fall back to the built-in default theme.

Update plan rune CSS to reference --rf-* tokens (the standard refrakt token namespace) as primary values, with --plan-* as fallbacks. This allows plan styles to adapt to any installed theme's token palette while remaining functional in standalone mode.

Improve the auto-generated dashboard to show project health at a glance: status count summaries, a blocked items callout, per-milestone grouping when multiple milestones exist, and a recent activity section.

Auto-generate pages that group entities by tag, assignee, or milestone. These appear in a "Views" section in the sidebar and use the {% backlog %} rune with appropriate filters.

Add three resolution-related checks to refrakt plan validate as specified in SPEC-027.

Show resolution data (completion date, PR link) in the plan status output and the plan serve dashboard.

Build the Nuxt framework adapter. Nuxt is Vite-based like SvelteKit, so the existing Vite plugin logic (virtual modules, content HMR) can be substantially reused.

Build the Next.js framework adapter. Uses React Server Components + renderToHtml() for zero-hydration content rendering, with a thin client component for behavior initialization.

Extend create-refrakt to scaffold projects for Astro, Nuxt, Next.js, and Eleventy in addition to the existing SvelteKit and HTML targets.

Remove or rewrite documentation that references the legacy Model class, decorators, and createSchema. After this work, the authoring docs present createContentModelSchema as the single path.

Phase 2c of ADR-005. Update refrakt inspect and related tooling to use the Rune.typeName string field instead of rune.type?.name. Small change (~4 lines) but needed before Phase 3 cleanup can remove the Type class.Depends on WORK-105 (dual-signature support) being complete.

Phase 3 of ADR-005 (breaking change). Once all runes are migrated (WORK-106, WORK-107) and tooling updated (WORK-108), remove the legacy Type class system entirely.Depends on WORK-106, WORK-107, and WORK-108 all being complete.

Extend StructureEntry with a repeat field that generates N copies of a template element, with optional filled/unfilled distinction. Eliminates the testimonial rune's postTransform for star ratings.

Add a projection field to RuneConfig that enables declarative structural reshaping of the output tree. Projection runs as a distinct pass after BEM class application but before meta tag filtering, operating on data-name addresses. This is SPEC-033's most powerful feature, giving themes control over schema-produced elements.

The Next.js adapter currently renders all runes via renderToHtml() (identity transform only). To support React component overrides — where theme or site authors provide custom React components for specific runes — we need a @refrakt-md/react renderer package that dispatches on typeof/data-rune and provides the ADR-008 framework-native interface (props + named children).

The Nuxt adapter currently renders all runes via renderToHtml() (identity transform only). To support Vue component overrides — where theme or site authors provide custom Vue components for specific runes — we need a @refrakt-md/vue renderer package that dispatches on typeof/data-rune and provides the ADR-008 framework-native interface (props + named slots).

Astro is a special case per ADR-008: it is both an adapter (routing, build integration) and has its own component format with native named slots. Unlike Next.js and Nuxt which need separate renderer packages (@refrakt-md/react, @refrakt-md/vue), Astro component overrides can be handled directly in packages/astro/ using Astro's built-in <slot name="..."> mechanism.For interactive runes rendered inside Astro islands, the island's framework renderer (React, Svelte, or Vue) handles extraction — that is covered by WORK-123, WORK-124, and WORK-119 respectively. This work item covers static .astro component overrides only.

Once knownSections are declared in the plan rune content models (WORK-024), the scanner and validator need to become section-aware. Today, refs are extracted from the entire file without knowing which section they belong to. With knownSections, refs get tagged with their canonical section name, enabling the next command to distinguish blocking dependencies from informational references.

After the SPEC-037 work items ship, the documentation needs to reflect the new capabilities: pending status, knownSections, attribute clearing, and the updated validation checks.

The plan content has a systemic gap: most cross-references are plain text (- SPEC-028 (Standard 2)) rather than machine-readable ref tags ({% ref "SPEC-028" /%}). Out of ~125 work items, only 44 use ref tags. References sections are the worst: 79 use plain text vs 22 with ref tags. Dependencies sections are split roughly evenly (21 plain text, 20 with refs).This means the next command's dependency blocking is essentially non-functional for most work items — it can only resolve {% ref %} tags, so plain text ID mentions are invisible to it. The knownSections work (WORK-024, WORK-129) will make the system section-aware, but it's only useful if refs are actually machine-readable.This work item converts existing plan content to use ref tags and adopts the knownSections conventions so the full dependency graph comes alive.

Long plan entities (specs, work items, decisions) are hard to navigate on mobile — you have to scroll through the entire document to reach a section. The toolbar scrolls away so you can't even reach the sidebar nav. On desktop, the TOC sidebar lists every H2/H3 heading, which becomes a wall of text for detailed specs and is hard to scan.Plan runes already declare known sections with canonical names (Acceptance Criteria, Dependencies, Approach, etc.) and the transform wraps them in <section data-name="..."> elements. We can leverage this to build focused section navigation for both mobile and desktop.

Implement efficient batch extraction of history for all plan entities and integrate with the existing .plan-cache.json caching mechanism. Handle shallow clone edge cases.

Implement the global history feed and all filter flags for the plan history CLI command. The global mode shows recent events across all entities, grouped by commit.

Implement the plan-history Markdoc tag as a self-closing aggregation rune following the established plan rune pattern (sentinel + meta tags + placeholder → aggregate → postProcess resolution). Supports both per-entity and global feed modes.

Restructure the identity transform config for plan entity runes (spec, work, bug, decision, milestone) so the header badges are split into two groups around the title, matching the visual hierarchy already used by backlog cards:

refrakt plan init currently hardcodes writing workflow instructions to CLAUDE.md. Decouple the init command from any specific AI tool so the plan package works naturally for users of Cursor, GitHub Copilot, Windsurf, Cline, Aider, or no AI tool at all.

Change the plan package's directory convention from singular to plural: spec/ to specs/, decision/ to decisions/, milestone/ to milestones/. Keep work/ unchanged (collective noun).

Add a planning-only scaffold option to create-refrakt that produces a minimal package.json + .gitignore and delegates the plan/ tree creation to refrakt plan init. Single-command entry point for users who want refrakt just for plan management.

Plan files currently live under plan/{work,specs,decisions}/ with slug-only filenames (e.g. plan-validate-command.md). The ID (WORK-033) lives in the {% work %} frontmatter tag but doesn't appear in the filename. A few recent items (WORK-149 through WORK-156) started prefixing the ID, producing an inconsistent mix: 8 prefixed vs. 196 unprefixed across work/specs/decisions.Standardising on {ID}-{slug}.md for every auto-ID type (work, bug, spec, decision) makes files grep-friendly, gives unambiguous references in commits/PRs/chat ("see WORK-158" points at exactly one file without a frontmatter scan), and sorts items by ID naturally in directory listings. Milestones keep their semver names (v1.0.0.md) since they don't use the numeric ID scheme.

Add keyboard shortcuts for fast navigation: / to focus search, j/k to move between sidebar items, Enter to navigate, [/] to jump between entity type groups, o to toggle collapse, Escape to clear.

Surface cross-entity relationships by scanning content for ID references (WORK-XXX, SPEC-XXX, BUG-XXX, ADR-XXX). Build a bidirectional relationship index and render relationships in a dedicated layout slot on each entity page.

Update the workflow section that refrakt plan init writes to CLAUDE.md to include guidance on using --resolve when completing work items.

Build the Eleventy (11ty v3) framework adapter. The simplest integration — no Vite, no bundler, no framework. Just global data files, templates, and renderToHtml().

The update command can set or replace attribute values but cannot remove them. Once you set --assignee claude or --milestone v1.0.0, there's no way to unset it. Support empty string as "clear": --assignee "" removes the attribute from the tag.

Style the plan-history rune with a vertical timeline layout following the design conventions established by the timeline rune (connected line, circle markers) and the diff rune (add/remove coloring).