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
| Flag | Description |
|---|---|
--dir <path> | Plan directory (default: plan/) |
--milestone <name> | Filter to a specific milestone |
--format json | Output 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
| Flag | Description |
|---|---|
--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 json | Output JSON instead of human-readable text |
Output
For each item: ID, title, type, priority, complexity, file path, acceptance criteria progress, and references.
Exit codes
| Code | Meaning |
|---|---|
0 | Found items |
1 | No matches found |
2 | Invalid 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
| Flag | Description |
|---|---|
<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 json | Output JSON instead of human-readable text |
Valid statuses
| Type | Statuses |
|---|---|
| work | draft, ready, in-progress, review, done, blocked, pending, cancelled, superseded |
| bug | reported, confirmed, in-progress, fixed, wontfix, duplicate |
| spec | draft, review, accepted, implemented, shipped, superseded, deprecated |
| decision | proposed, accepted, rejected, superseded, deprecated |
| milestone | planning, active, complete |
Valid enums
| Attribute | Values |
|---|---|
| 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
| Flag | Description |
|---|---|
<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 json | Output JSON instead of human-readable text |
File locations
| Type | Directory |
|---|---|
| work | plan/work/ |
| bug | plan/work/ |
| spec | plan/specs/ |
| decision | plan/decisions/ |
| milestone | plan/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
| Flag | Description |
|---|---|
<type> | Required: work, bug, spec, or decision |
--dir <path> | Plan directory (default: plan/) |
--format json | Output 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
| Flag | Description |
|---|---|
--dir <path> | Plan directory (default: plan/) |
--strict | Treat warnings as errors |
--against <ref> | Also report IDs this branch adds that the ref added too since the two diverged |
--format json | Output 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
| Type | Severity | Description |
|---|---|---|
broken-ref | error | Entity references an undefined ID |
duplicate-id | error | Same ID appears in multiple files |
invalid-status | error | Status not valid for the entity type |
invalid-priority | error | Priority not in allowed values |
invalid-severity | error | Severity not in allowed values |
circular-dependency | error | Cycle in work/bug dependency graph |
no-milestone | warning | Work/bug item not assigned to a milestone |
complete-milestone-open-item | warning | Completed 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
| Subcommand | What it does |
|---|---|
filenames | Renames files to {ID}-{slug}.md, and a milestone to its name (v1.0.0.md) |
dependencies | Rewrites 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-attrs | Sets 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 |
ids | Renumbers a branch's entity whose ID collides with one on --against <ref>. The ID already on the ref keeps it |
Options
| Flag | Description |
|---|---|
--dir <path> | Plan directory (default: plan/) |
--dry-run | Preview the changes (the default) |
--apply | Write the changes |
--git | Rename with git mv, so history follows the file |
--against <ref> | For ids: the branch to compare with, as in validate --against |
--format json | Output 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
| Flag | Description |
|---|---|
--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-json | Skip modifying the host package.json |
--no-hooks | Skip writing .claude/settings.json SessionStart hook |
--no-wrapper | Skip writing ./plan.sh wrapper script |
--minimal | Equivalent to --no-package-json --no-hooks --no-wrapper — only scaffolds plan/ content and agent files |
--format json | Output JSON instead of human-readable text |
What it creates
Plan content (always):
plan/specs/,plan/work/,plan/decisions/,plan/milestones/— directories for each entity typeplan/index.md— overview page with quick startplan/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 toAGENTS.md. Auto-detected or specified via--agent. See Agent auto-detection.
Host project wiring (unless --no-package-json or --minimal):
- Adds
@refrakt-md/cliand@refrakt-md/plantodevDependencies, pinned to the version of@refrakt-md/planrunning the command - Adds a
planscript that runsrefrakt plan - Never clobbers existing keys. Walks up to the install root, preferring workspace roots (
npm/yarnworkspaces,pnpm-workspace.yaml,lerna.json).
Claude SessionStart hook (when Claude is targeted and --no-hooks/--minimal are not set):
.claude/settings.jsongets aSessionStarthook that runsinstallifnode_modules/.bin/refraktisn'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. Existingsettings.jsonfiles 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 tonpx refrakt plan. Uses the.shsuffix because the content directory is also calledplan/.
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
| Flag | Description |
|---|---|
[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 |
--all | Include content-only events in global mode (omitted by default) |
--format json | Output JSON instead of human-readable text |
Event kinds
| Kind | Meaning |
|---|---|
created | Entity file first appeared |
attributes | Tag attributes changed (status, priority, etc.) |
criteria | Acceptance criteria checkboxes changed |
resolution | A ## Resolution section was added or modified |
content | File 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
| Variable | Description |
|---|---|
REFRAKT_PLAN_DIR | Default 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.