Plan CLI

Problem

Developers using spec-driven workflows have Markdown planning files in their repos but no way to browse them as a cohesive project view. The files are readable individually but the relationships between them — which specs have work items, which work items are blocked, what the milestone progress looks like — are invisible without opening every file and tracing references manually.

Existing tools (Spec Kit, CCPM, planning-with-files) provide no visual interface. The planning content is raw files that never render into anything browsable.

Design Principles

Part of the refrakt CLI. The plan commands live under refrakt plan alongside the existing refrakt dev, refrakt build, and refrakt inspect commands. One CLI, one ecosystem.

Plugin architecture. The @refrakt-md/plan package registers its subcommands when installed. Without it, refrakt plan prompts to install the package. This follows the same pattern as rune packages — @refrakt-md/storytelling adds runes, @refrakt-md/plan adds runes and CLI commands.

Zero friction. refrakt plan serve works immediately. No config file, no signup, no hosting. Point it at a directory and get a dashboard.

Read from the repo, write to the repo. The CLI reads Markdoc files and renders them. The create command writes new Markdoc files. The source of truth is always the files in the repo — the CLI is a lens, not a database.

CI-friendly. The validate command exits with appropriate codes. Add it to GitHub Actions in one line.

Plugin Registration

When @refrakt-md/plan is installed, it registers its subcommands under refrakt plan:

refrakt plan serve      # Browse the plan dashboard
refrakt plan status     # Terminal status summary
refrakt plan create     # Scaffold new items
refrakt plan validate   # Check structure and references
refrakt plan build      # Generate static HTML site
refrakt plan init       # Scaffold plan structure
refrakt plan update     # Update plan item attributes
refrakt plan next       # Find next work item to pick up

When the package is not installed:

$ refrakt plan serve

  The plan commands require @refrakt-md/plan.
  Install it: npm install @refrakt-md/plan

The package exports a CLI plugin that the refrakt CLI discovers:

// @refrakt-md/plan/cli-plugin.ts
export const commands = {
  namespace: 'plan',
  commands: [
    { name: 'serve', handler: serveHandler, description: 'Browse the plan dashboard' },
    { name: 'status', handler: statusHandler, description: 'Terminal status summary' },
    { name: 'create', handler: createHandler, description: 'Scaffold new plan items' },
    { name: 'validate', handler: validateHandler, description: 'Validate plan structure' },
    { name: 'build', handler: buildHandler, description: 'Build static plan site' },
    { name: 'init', handler: initHandler, description: 'Scaffold plan structure' },
    { name: 'update', handler: updateHandler, description: 'Update plan item attributes' },
    { name: 'next', handler: nextHandler, description: 'Find next work item' },
  ],
};

The refrakt CLI discovers installed packages that export a cli-plugin entry and registers their commands under the declared namespace. This same pattern could be used by other packages in the future — @refrakt-md/docs could register refrakt docs commands, @refrakt-md/storytelling could register refrakt story commands.

For users without the refrakt CLI installed globally, npx works:

npx refrakt plan serve

Commands

serve

Starts a local dev server that renders the plan dashboard from planning files.

refrakt plan serve [directory]

Arguments:

Options:

Behaviour:

1. Scans directory recursively for .md files containing plan runes (work, bug, decision, milestone, spec)
2. Scans --specs directory for spec rune files
3. Builds the entity registry from all discovered runes
4. Runs the cross-page pipeline (phases 2–4) to resolve references, compute spec coverage, and build dependency graphs
5. Generates a dashboard index page if none exists
6. Starts a dev server with hot reload — editing a file triggers re-scan and browser refresh

Auto-generated dashboard: If the directory doesn’t contain an index.md with a dashboard layout, the CLI generates one in memory (not written to disk):

# Plan Dashboard

## Active Milestone
{% milestone name="[most recent active milestone]" %}

## Ready for Work
{% backlog filter="status:ready" sort="priority" %}

## In Progress
{% backlog filter="status:in-progress" sort="priority" %}

## Recent Decisions
{% decision-log sort="date" %}