Plan

Plan is a structured project planning system built into refrakt.md. It replaces issue trackers and project boards with version-controlled Markdoc files that live in your repository.

Every plan entity — specs, work items, bugs, decisions, milestones — is a .md file in your plan/ directory. The CLI manages these files, tracks acceptance criteria, resolves dependencies, and validates cross-references. PlanHub provides a web dashboard for browsing and sharing your roadmap.

Why plan in the repo?

• Single source of truth — plans live next to the code they describe
• Git history is your changelog — every status transition, criterion check-off, and resolution is a commit
• AI-agent friendly — structured Markdoc files are easy for coding agents to read and update
• No external dependencies — no SaaS accounts, no sync issues, no stale boards

Quick start

New standalone project

npm create refrakt my-plan --type plan
cd my-plan
npm install

Add to an existing project

npx refrakt plan init

This creates the plan/ directory structure with example files and optionally wires up your AI coding agent (Claude, Cursor, Copilot, etc.) with plan context.

See Plan Init for all options.

Project structure

plan/
  specs/        SPEC-001-auth-system.md, SPEC-002-api-design.md, ...
  work/         WORK-001-setup-project.md, WORK-002-add-search.md, ...
  bugs/         BUG-001-crash-fix.md, BUG-002-login-error.md, ...
  decisions/    ADR-001-use-postgres.md, ADR-002-api-style.md, ...
  milestones/   v1.0.0.md, v1.1.0.md, ...

Files follow the {ID}-{slug}.md naming convention. IDs are auto-assigned when you create entities with the CLI.

Entity types at a glance

Next steps

• Workflow — learn the day-to-day create/next/update cycle
• Entities — deep dive into each entity type and its attributes
• CLI Reference — full command reference
• PlanHub — browse your plan on the web