Specs
Draft 12
SPEC-007 main
Local Runes — Declarative Rune Extension (v1) SPEC-010 main
Theme Studio — AI-Powered Theme Generator apps/theme-studio — Dependencies: @refrakt-md/transform, @refrakt-md/lumina, @refrakt-md/runes, @refrakt-md/svelte, @refrakt-md/ai
32/34 criteria
SPEC-021 main
Plan Runes Runes for spec-driven project management in AI-native development workflows. Package: @refrakt/plan.
0/5 criteria
SPEC-023 main
Storytelling World Engine Cross-page pipeline hooks, entity graph, auto-linking, validation, and CLI tooling for the @refrakt-md/storytelling package — turning isolated rune pages into a navigable, interconnected world bible.
SPEC-029 main
File-Derived Timestamps for Runes Expose file-level created and modified timestamps as Markdoc variables so any rune can consume them as attribute defaults, with explicit attribute values taking precedence.
SPEC-031 main
Vite Plugin — Framework-Agnostic Rune Integration A standalone @refrakt-md/vite plugin that lets developers use refrakt runes in existing Vite-based projects without adopting the full refrakt site editor or routing system. Complements SPEC-030 (Framework Adapter System) by providing a lighter-weight, framework-agnostic entry point.
0/6 work items
SPEC-034 main
Theme Structural Template Language (Design Exploration) A design exploration of a spatial template syntax for theme developers to express structural overrides — compiled to the declarative RuneConfig model defined in SPEC-033. This is not a committed implementation. It documents a possible future authoring surface so the idea is preserved and can be revisited if real theme development reveals the need.
SPEC-036 main
Claude Code Skills and Hooks for Plan Workflow Replace procedural CLAUDE.md instructions with Claude Code skills (custom slash commands) and hooks (automated enforcement) to make the plan workflow invocable, context-efficient, and enforceable.
SPEC-038 main
Git-Native Entity History Derive structured lifecycle timelines for plan entities from git history — attribute transitions, criteria progress, and resolution events — surfaced through the CLI and as a site rune.
SPEC-039 main
Plan Package Onboarding & Conventions Review Review and improve the @refrakt-md/plan package's conventions, folder structure, and onboarding experience. Three concerns drive this spec: the package is currently coupled to Claude Code as an AI tool, the folder naming convention uses singular nouns where plural would be more natural, and there is no path for users who already have planning documents to adopt the system.
SPEC-042 main
Plan Target for create-refrakt Add a planning-only scaffold option to create-refrakt so users who want to adopt refrakt primarily as a plan management tool have a one-command entry point, matching the experience for sites and themes.
1/1 work items
Review 4
SPEC-004 main
Layout System — Specification Standardised layout attributes for grid and section runes, page-level breakout, showcase effects, background media Tint Rune Specification, Community Runes Specification, Vite Plugin Specification
SPEC-008 main
Unbuilt Runes — High-Level Spec Runes listed in plan/spec/community-runes.md that do not yet have schemas in packages/runes/src/tags/
2/6 criteria
0/13 work items
SPEC-015 main
Plan Site UX at Scale Future UX improvements for the plan site to handle large projects with many work items, specs, bugs, and decisions.
SPEC-028 main
Rune Output Standards Codify the structural patterns established by the recipe rune as the reference standard for all rune output — schema transforms, engine configs, and identity-transformed HTML.
Accepted 19
SPEC-001 main
Community Runes — Specification Package system, namespacing, rune extension, ecosystem architecture
0/4 work items
SPEC-002 main
Cross-Page Pipeline — Specification Build pipeline phases, entity registry, content aggregation, post-processing hooks Community Runes Specification, Storytelling Runes Specification
0/4 work items
SPEC-003 main
Declarative Content Model — Specification Schema-driven content parsing that replaces per-rune processChildren methods Alignment Specification, Media Runes Specification, Layout Specification
SPEC-006 main
Media Runes — Specification Playlist, track, and audio rune content models, compact format, and player integration Related: Unbuilt Runes Spec, Sandbox Futures (audio visualisation synergy)
SPEC-009 main
Rune Editor Compatibility Spec This spec covers all remaining runes that need updates for editor compatibility. Three runes have already been updated: recipe, hero, and feature. This document covers everything else.
137/137 criteria
SPEC-012 main
Rune Inspector — Transformation Pipeline Debugger for VS Code @refrakt-md/vscode, @refrakt-md/language-server
SPEC-014 main
Plan Site via HTML Adapter Refactor plan serve and plan build to render through @refrakt-md/html instead of a bespoke HTML pipeline, and introduce a planLayout in the transform layer.
SPEC-022 main
Plan CLI Plan management subcommands for the refrakt CLI. Package: @refrakt-md/plan.
0/4 criteria
SPEC-025 main
Universal Theming Dimensions Cross-rune semantic data attributes — surface, density, section anatomy, interactive state, media slots, checklist, and sequential items — so themes can style every rune generically with ~54 CSS rules instead of per-rune overrides. Builds on the metadata system (SPEC-024) to complete the ten-dimension universal theming model.
SPEC-026 main
Lumina Theme — Reference Implementation Lumina is the default theme and reference implementation of the universal theming dimensions (SPEC-024, SPEC-025). This spec documents Lumina's concrete choices for surface assignments, sentiment colours, density behaviour, media sizing, and per-rune overrides — proving the dimension model works end-to-end and serving as the template for community themes.
0/9 criteria
SPEC-027 main
Work Item Resolution Summaries When a work item or bug is completed, append a structured Resolution section capturing what was done, linking to branches/PRs, and recording implementation notes. Designed for agent workflows where the completing agent's context is lost after the session ends.
1/1 work items
SPEC-030 main
Framework Adapter System Extend refrakt beyond SvelteKit to support Astro, Next.js, Eleventy, and Nuxt — four framework adapters built on the existing framework-agnostic core. This spec defines the shared prerequisites, per-adapter scope, and phased delivery plan derived from ADR-001 (Astro readiness) and ADR-002 (Next.js, Eleventy, Nuxt readiness).
0/1 work items
SPEC-032 main
Remove Legacy Model Class and Decorators Migrate all runes from the imperative Model + decorator pattern to createContentModelSchema, then remove the legacy API surface entirely.
SPEC-033 main
Structure Slots and Declarative Flexibility Extend the identity transform's StructureEntry system with named slots, ordered placement, value mapping, repeated element generation, and element projection — giving theme developers structural creative freedom without resorting to postTransform.
0/2 work items
SPEC-037 main
Plan Package Hardening Fix bugs, close validation gaps, implement knownSections for plan runes, and add missing CLI capabilities — all before building the Claude Code plugin layer (SPEC-036).
SPEC-040 main
Edge Runtime Compatibility for Plan Package Refactor @refrakt-md/plan so that its pure logic — parsing, diffing, filtering, relationship building, entity card construction — can be imported in edge runtimes (Cloudflare Workers, Deno Deploy, Vercel Edge Functions) without pulling in Node.js APIs (node:fs, node:child_process, node:path).
SPEC-041 main
Agent Rune Reference A CLI surface that lets a coding agent (Claude Code, Cursor, Copilot, etc.) discover the input syntax of any installed rune — tag name, attributes, content interpretation, and a minimal example — without invoking an LLM.
8/8 work items
Superseded 0
Deprecated 0