CLI›Plan commands

Plan commands

The @refrakt-md/plan package extends the refrakt CLI with subcommands for managing your project plan. All commands read Markdown files from your plan directory (default: plan/, configurable via --dir or the REFRAKT_PLAN_DIR environment variable).

refrakt plan status

Terminal status summary showing milestone progress, entity counts, blocked items, and warnings.

refrakt plan status
refrakt plan status --milestone v1.0
refrakt plan status --format json

Options

FlagDescription
--dir <path>Plan directory (default: plan/)
--milestone <name>Filter to a specific milestone
--format jsonOutput JSON instead of human-readable text

Output

  • Milestone progress — progress bar for the active milestone (or the one specified with --milestone)
  • Status counts — breakdown by entity type (specs, work, bugs, decisions) and status
  • Blocked items — items with status blocked, showing what they're waiting on
  • Ready items — top 5 actionable items sorted by priority then complexity
  • Warnings — broken references, orphaned work items, completed milestones with open items

refrakt plan next

Find the next actionable work item. Filters to items with status ready (work) or confirmed (bug) whose dependencies are all complete.

refrakt plan next
refrakt plan next --count 5
refrakt plan next --milestone v1.0 --type work
refrakt plan next --tag backend --assignee alice

Options

FlagDescription
--dir <path>Plan directory (default: plan/)
--milestone <name>Filter to a specific milestone
--tag <tag>Filter by comma-separated tags
--assignee <name>Filter by assignee
--type <type>Filter by type: work, bug, or all (default: all)
--count <n>Number of items to return (default: 1)
--format jsonOutput JSON instead of human-readable text

Output

For each item: ID, title, type, priority, complexity, file path, acceptance criteria progress, and references.

Exit codes

CodeMeaning
0Found items
1No matches found
2Invalid arguments

refrakt plan update

Update plan item attributes or toggle acceptance criteria checkboxes.

refrakt plan update WORK-042 --status in-progress
refrakt plan update WORK-042 --source "SPEC-021,ADR-005"
refrakt plan update WORK-042 --check "Add unit tests"
refrakt plan update WORK-042 --uncheck "Add unit tests"
refrakt plan update BUG-003 --severity major --assignee alice
refrakt plan update WORK-042 --status done

Options

FlagDescription
<id>Required: entity ID (matches id or name attribute)
--dir <path>Plan directory (default: plan/)
--status <value>Update status (validated per entity type)
--check "<text>"Check off an acceptance criterion (partial text matching)
--uncheck "<text>"Uncheck an acceptance criterion
--<attr> <value>Set any allowed attribute (priority, complexity, assignee, etc.)
--format jsonOutput JSON instead of human-readable text

Valid statuses

TypeStatuses
workdraft, ready, in-progress, review, done, blocked, pending, cancelled, superseded
bugreported, confirmed, in-progress, fixed, wontfix, duplicate
specdraft, review, accepted, implemented, shipped, superseded, deprecated
decisionproposed, accepted, rejected, superseded, deprecated
milestoneplanning, active, complete

Valid enums

AttributeValues
priority (work)critical, high, medium, low
complexity (work)trivial, simple, moderate, complex, unknown
severity (bug)critical, major, minor, cosmetic
source (work, bug)Comma-separated entity IDs, e.g. SPEC-001,ADR-002

refrakt plan create

Scaffold a new plan item from a template. When --id is omitted, the next available ID is assigned automatically by scanning existing plan files. Duplicate IDs are rejected at create time.

refrakt plan create work --title "Add search indexing"
refrakt plan create bug --title "Login fails on Safari" --severity critical
refrakt plan create spec --title "Search API"
refrakt plan create decision --title "Use SQLite for local storage"
refrakt plan create milestone --id v2.0 --title "Version 2.0"

You can also specify an explicit ID if needed:

refrakt plan create work --id WORK-042 --title "Add search indexing"

Options

FlagDescription
<type>Required: work, bug, spec, decision, or milestone
--id <id>Unique identifier. Auto-assigned when omitted (required for milestone)
--title "..."Required: item title
--dir <path>Plan directory (default: plan/)
--<attr> <value>Set optional attributes (e.g., --priority high)
--format jsonOutput JSON instead of human-readable text

File locations

TypeDirectory
workplan/work/
bugplan/work/
specplan/specs/
decisionplan/decisions/
milestoneplan/milestones/

refrakt plan next-id

Show the next available ID for a given entity type without creating anything. Useful for previewing what ID will be assigned.

refrakt plan next-id work
refrakt plan next-id spec --format json

Options

FlagDescription
<type>Required: work, bug, spec, or decision
--dir <path>Plan directory (default: plan/)
--format jsonOutput JSON instead of human-readable text

Output

Displays the next ID and the current highest existing ID (if any):

WORK-076  (highest existing: WORK-075)

refrakt plan validate

Check plan structure for errors and inconsistencies.

refrakt plan validate
refrakt plan validate --strict
refrakt plan validate --against origin/main
refrakt plan validate --format json

Options

FlagDescription
--dir <path>Plan directory (default: plan/)
--strictTreat warnings as errors
--against <ref>Also report IDs this branch adds that the ref added too since the two diverged
--format jsonOutput JSON instead of human-readable text

Catching a duplicate ID before it merges

Two branches can each create WORK-120. Plain validate reports the duplicate only once both files are on the same branch, after the merge, when every reference to the ID has become ambiguous. --against reports it on the branch, before the merge:

refrakt plan validate --against origin/main

It compares the branch with the ref from the point where they diverged, so a file the branch deleted is not reported as a collision. A shallow clone that does not reach that point fails with an error rather than a clean result; run git fetch --unshallow first. To renumber the branch's copy, see plan migrate ids.

Issues detected

TypeSeverityDescription
broken-referrorEntity references an undefined ID
duplicate-iderrorSame ID appears in multiple files
invalid-statuserrorStatus not valid for the entity type
invalid-priorityerrorPriority not in allowed values
invalid-severityerrorSeverity not in allowed values
circular-dependencyerrorCycle in work/bug dependency graph
no-milestonewarningWork/bug item not assigned to a milestone
complete-milestone-open-itemwarningCompleted milestone still has open items

refrakt plan migrate

Rewrite plan files to the current conventions. Every subcommand previews by default and changes nothing until you pass --apply.

refrakt plan migrate filenames
refrakt plan migrate filenames --apply --git
refrakt plan migrate dependencies --apply
refrakt plan migrate pr-attrs --apply
refrakt plan migrate ids --against origin/main --apply --git
SubcommandWhat it does
filenamesRenames files to {ID}-{slug}.md, and a milestone to its name (v1.0.0.md)
dependenciesRewrites legacy ## Dependencies headings to ## Blocked by. Entries whose wording reads like the opposite direction are listed for you to move to ## Blocks by hand
pr-attrsSets the pr attribute on finished items from the pull request that merged them, read from git history. Items with no merge found, or more than one, are listed and left alone
idsRenumbers a branch's entity whose ID collides with one on --against <ref>. The ID already on the ref keeps it

Options

FlagDescription
--dir <path>Plan directory (default: plan/)
--dry-runPreview the changes (the default)
--applyWrite the changes
--gitRename with git mv, so history follows the file
--against <ref>For ids: the branch to compare with, as in validate --against
--format jsonOutput JSON instead of human-readable text

migrate ids renumbers an entity only when nothing outside it refers to the colliding ID, because it cannot tell which of the two entities a reference meant. Otherwise it changes nothing and lists the references that stopped it, with file and line, for you to resolve by hand.

refrakt plan init

Wire @refrakt-md/plan into a host project. plan init does several things at once so that running refrakt plan next works immediately — it scaffolds the plan directory, writes the canonical AGENTS.md with the full workflow guide, wires @refrakt-md/cli and @refrakt-md/plan into your package.json, and (for Claude users) installs a SessionStart hook that runs install if the CLI isn't resolvable yet. Each side effect has an opt-out flag.

refrakt plan init                     # full setup with agent auto-detection
refrakt plan init --agent cursor      # target a specific AI tool
refrakt plan init --minimal           # plan/ + AGENTS.md only
refrakt plan init --no-hooks          # skip .claude/settings.json
refrakt plan init --agent none --dir planning

Options

FlagDescription
--dir <path>Plan directory (default: plan/)
--project-root <path>Project root for agent file detection, package.json wiring, and hook/wrapper placement (default: .)
--agent <tool>AI tool instruction file to update: claude, cursor, copilot, windsurf, cline, or none. Auto-detects when omitted.
--no-package-jsonSkip modifying the host package.json
--no-hooksSkip writing .claude/settings.json SessionStart hook
--no-wrapperSkip writing ./plan.sh wrapper script
--minimalEquivalent to --no-package-json --no-hooks --no-wrapper — only scaffolds plan/ content and agent files
--format jsonOutput JSON instead of human-readable text

What it creates

Plan content (always):

  • plan/specs/, plan/work/, plan/decisions/, plan/milestones/ — directories for each entity type
  • plan/index.md — overview page with quick start
  • plan/INSTRUCTIONS.md — full workflow guide (tool-agnostic; kept in-tree for convenience)
  • Example work item, spec, decision, and milestone files

Agent instruction files (always):

  • AGENTS.md — canonical agent-facing workflow at the project root, following the AGENTS.md convention. Contains the full plan workflow guide.
  • Tool-specific file (e.g. CLAUDE.md, .cursorrules) — gets a single-line pointer back to AGENTS.md. Auto-detected or specified via --agent. See Agent auto-detection.

Host project wiring (unless --no-package-json or --minimal):

  • Adds @refrakt-md/cli and @refrakt-md/plan to devDependencies, pinned to the version of @refrakt-md/plan running the command
  • Adds a plan script that runs refrakt plan
  • Never clobbers existing keys. Walks up to the install root, preferring workspace roots (npm/yarn workspaces, pnpm-workspace.yaml, lerna.json).

Claude SessionStart hook (when Claude is targeted and --no-hooks/--minimal are not set):

  • .claude/settings.json gets a SessionStart hook that runs install if node_modules/.bin/refrakt isn't present. The hook detects the package manager at execution time by reading lockfiles (bun.lockb, pnpm-lock.yaml, yarn.lock, package-lock.json), so switching package managers later just works. Existing settings.json files are merged into, not replaced.

Wrapper script (unless --no-wrapper or --minimal):

  • ./plan.sh — POSIX shell wrapper for environments where hooks aren't available. Installs dependencies on first run, then defers to npx refrakt plan. Uses the .sh suffix because the content directory is also called plan/.

Agent auto-detection

When --agent is omitted, plan init checks the project root for known instruction files (CLAUDE.md, .cursorrules, .github/copilot-instructions.md, .windsurfrules, .clinerules) and appends a pointer to AGENTS.md in each that exists. If none are found, it falls back to creating a CLAUDE.md pointer file and targeting Claude for the SessionStart hook.

Idempotent re-runs

Every side effect is safe to repeat. Existing keys in package.json, existing hook commands in .claude/settings.json, and existing pointer markers in agent instruction files are detected and left alone. Running plan init on an already-initialized project prints Plan structure already exists. No changes made. and exits successfully.

refrakt plan history

View the git-derived lifecycle history for a single entity or for the entire project. Every status transition, priority change, criteria check-off, and resolution is extracted from consecutive git commits.

Single-entity mode

refrakt plan history WORK-024
refrakt plan history SPEC-038 --limit 10
refrakt plan history WORK-024 --format json

Shows a reverse-chronological timeline for a single entity: date, structured changes, and short commit hash.

WORK-024: Add knownSections to content model framework

Apr 12  status: ready → done                              a295513
        ☑ knownSections supported in the content model framework
        ☑ Work rune declares known sections with aliases
        ☑ Bug rune declares known sections with aliases
Apr 12  status: blocked → ready                            1676387
        priority: low → medium
Apr 10  source: +SPEC-003, +SPEC-021                       f262d7b
Apr 08  Created (blocked, low, moderate)                   da12420

Global mode

refrakt plan history
refrakt plan history --limit 20
refrakt plan history --since 7d --type work --status done

Shows recent events across all entities, grouped by commit:

Apr 12  a295513  Mark all SPEC-037 work items done
        WORK-024  status: ready → done  (☑ 8/8 criteria)
        WORK-127  status: ready → done  (☑ 3/3 criteria)

Apr 12  1676387  Accept SPEC-037 and break into work items
        SPEC-037  status: draft → accepted
        WORK-127  Created (ready, high, simple)

Options

FlagDescription
[id]Entity ID for single-entity mode. Omit for global feed.
--dir <path>Plan directory (default: plan/)
--limit <n>Maximum events/commits to show (default: 20)
--since <duration|date>Time filter: 7d, 30d, or ISO date. Passed to git log --since.
--type <types>Entity type filter: work, spec, bug, decision (comma-separated)
--author <name>Filter by commit author (substring match)
--status <status>Show only events where an entity transitioned to this status
--allInclude content-only events in global mode (omitted by default)
--format jsonOutput JSON instead of human-readable text

Event kinds

KindMeaning
createdEntity file first appeared
attributesTag attributes changed (status, priority, etc.)
criteriaAcceptance criteria checkboxes changed
resolutionA ## Resolution section was added or modified
contentFile changed but no structured diff detected

Viewing and publishing a plan as a site

There is no built-in dev server or static-site generator for plans. A plan site is an ordinary refrakt site: scaffold a deployable one with npx create-refrakt --type plan (or refrakt plan init --target <adapter>), then use the standard adapter npm run dev / npm run build. You can also wire plan routes into a refrakt site you already run. See Publish a Plan Site for both paths.

Environment variables

VariableDescription
REFRAKT_PLAN_DIRDefault plan directory, overridden by --dir

JSON output

All commands support --format json for machine-readable output. This is useful for scripting, CI pipelines, and AI tool integration.