refrakt.md

Docs Runes Roadmap Blog Changelog

Plan in your repo. Track on the web.

Keep your project plan in Git alongside your code. Track progress from the terminal, see your roadmap on the web. No SaaS accounts, no sync issues — just Markdoc files and the CLI.

npm create refrakt my-plan --type plan

  1. Create a plan

    Start a new standalone planning project, or add planning to an existing repo. Either way, your plan/ directory becomes the single source of truth.

    # New project
npm create refrakt my-plan --type plan

# Existing repo
npx refrakt plan init  # adds @refrakt-md/cli + @refrakt-md/plan to package.json
npm install

  2. Work with the CLI

    Create entities, find what to work on next, check off acceptance criteria, and mark items done — all from the terminal.

    npx refrakt plan next
npx refrakt plan update WORK-042 --status in-progress
npx refrakt plan update WORK-042 --check "Login validates email"
npx refrakt plan update WORK-042 --status done --resolve "Implemented in PR #42"

  3. Browse on PlanHub

    Push your plan/ directory to GitHub, then visit plan.refrakt.md and connect your repository. Your plan is rendered as an interactive dashboard with search, filtering, and cross-references.

Why Plan?

Your project plan belongs in the repo

Issue trackers live outside your code. Boards go stale. Status updates get lost in chat. Plan puts your project plan where it belongs — in version control, next to the code it describes.

Every change is a commit
Status transitions, criterion check-offs, and resolutions are tracked in git history — not a proprietary database.
AI-agent friendly
Structured Markdoc files are first-class input for coding agents. Wire up Claude, Cursor, or Copilot with plan init --agent.
CLI-driven workflow
Find the next task, update status, check off criteria, validate cross-references — all without leaving the terminal.
Dependency and cross-reference tracking
Work items declare dependencies. Specs link to decisions. plan next respects blockers, plan validate catches broken references.
PlanHub dashboard
Push to GitHub, visit plan.refrakt.md/{owner}/{repo}. An interactive web view of your plan — no build step, no hosting.
Works offline, zero lock-in
No network needed for the CLI. Your plan is plain text in your repo — stop using the tools and the files are still useful.