CRUX · a roadmap format in plain Markdown

Get your team and your AI on the same page. Literally one page.

CRUX describes a whole project in plain Markdown — north star, roadmaps, projects, down to a single checkbox. Humans read the outline. Agents parse the meta line. Everyone works from the same source of truth — no toolchain required.

> status: active · progress: 33% · id: core

Explore the live roadmap →Read it on GitHub

It's just Markdown. That's the whole trick.

CRUX has five levels — north star, roadmap, initiative, project, task — and every one is written the same way: a heading, one meta line, and checkboxes for the work. Heading depth is the hierarchy. A blockquote > key: value · … line under any heading carries its state. Leaf work is a real - [ ] checkbox you can tick in any editor.

A status column you read down the left edge.

Lead each heading with a status emoji — ⚪ todo · 🔵 active · 🟡 at-risk · 🔴 blocked · 🟢 done · ⚫ dropped — and the whole document scans as a column.

One meta line, three audiences.

Skimmable by humans, greppable on the CLI, deterministically parseable by machines.

Renders everywhere, installs nowhere.

GitHub, any editor, Obsidian — no rendering step, no tool you must install. Tools are optional and only ever derive views.

---
crux: 0.1
title: Weekend project
north_star: A working CLI I actually use.
---

## 🗺 v1
### 🔵 Core commands
> status: active · progress: 33% · id: core
- [x] Parse args
- [ ] Read config
- [ ] Print output

Weekend project

A working CLI I actually use.

crux 0.1

Core commandsinitiativeactive33%1/3 tasks
- done: Parse args
- todo: Read config
- todo: Print output

The same nine lines, two ways: an outline a person edits, and the tree a renderer draws. Same file. No sync.

Roadmaps rot. CRUX is built to stay true.

Most roadmaps live in a tool that hides the truth behind a login, drifts from the code, and reads differently to every person — and to no machine at all. So the strategy deck, the ticket tracker, and the actual repo slowly disagree, and nobody's sure which one to believe.

CRUX puts the roadmap back where the work is: one plain-Markdown file in your repo, canonical by rule. State lives on the meta line, not in a database you have to trust. And it ships with a contract — keep it true — plus a dependency-free validator that flags drift, broken dependencies, dependency cycles, stale due dates, and rollups that no longer match the checkboxes.

The file is only useful if it is current — so we made staying current the one rule everything else enforces.

Alignment isn't a meeting. It's a file.

We mean operational alignment: every participant — teammates, you, your agents, leadership — working from the same legible source of truth, so intent and state never fork. (Not model value-alignment or AI safety — that's a different, harder problem. CRUX aligns what everyone is building and where it stands.)

A roadmap only works if everyone — and everything — reads the same thing. CRUX is that thing. Four ways it converges:

Person ↔ person. Your strategist's north star and your engineer's checkbox live in the same file — so the deck and the backlog can't quietly disagree.
Person ↔ AI. A human ticks a box; an agent updates the meta line — the same line, no translation layer.
AI ↔ AI. Hand any agent the typed JSON model (crux validate --json) and it sees exactly what every other agent sees — one machine contract, not a screen to scrape.
Execution ↔ strategy. Tick a task and progress rolls up the tree to the north star — the gap between planned and shipped becomes a number you can see.

The "keep it true" contract is the alignment mechanism. The typed model is the machine handshake. The Markdown is the one source everyone signs.

Engineering is going agentic. Shared intent is about to be the scarcest thing in the building.

The work is moving along a spectrum — from harnesses that augment a developer to processes that mostly run themselves. At every point, the bottleneck is the same: not compute, not models — trustworthy, shared, legible state. An agent is only as good as the intent it's pointed at and the truth it can read back.

CRUX is built to be that substrate. An agent reads the north star and the dependency graph, proposes a change as a Markdown diff, and a human reviews it — the file stays canonical the whole way. No agent silently rewrites your roadmap; it edits the same file you do, under the same rules, and you approve the diff.

The free, local tier is forever accountless — drop in your CRUX.md and explore. The AI tier (planned) opens the endpoints agents read and propose changes through — every write goes through validation and your review.

Write it once. Read it everywhere.

The same CRUX file is, with no extra work:

an outline in any editor,
a todo list on GitHub (real checkboxes that tick off),
a tech-tree at /roadmap,
a typed JSON model for tools and agents (crux validate --json),
and derived views — timeline, dependency graph, now/next/later — generated on demand and regenerable, never canonical.

It's fractal: the grammar for a north star is the grammar for a checkbox. So you can split one file into many or merge them back — losslessly. When the zero-downtime initiative grew its own long thread, it moved into its own file and kept everyid, link, and dependency intact.

This isn't a mockup. It's our actual roadmap.

Everything above is true of this very page's source. The tree below is CRUX Studio's own CRUX.md — north star, milestone M0, real status and rollups — parsed and rendered live. We ship CRUX by using CRUX.

CRUX Studio

Every software product can publish, explore, and maintain a visual CRUX roadmap at `/roadmap`.

crux 0.1

Updated 2026-06-26

Visual Roadmaproadmapdone100%@pv61/61 tasks2 initiatives
1. Render pipelineinitiativedone100%@pv30/30 tasks5 projects
  Parser & document modelprojectdone100%@pv10/10 tasks
  done: Define the CRUX grammar in [SPEC.md](SPEC.md)
  done: Parse frontmatter, north star, and the heading hierarchy into nodes
  done: Parse checkbox tasks as task leaves
  done: Parse blockquote meta lines and inline task metadata into structured fields
  done: Ship a dependency-free CLI parser + validator (`bin/crux.ts`)
  done: Extract the parser into an importable module (`parseText` / `validateDocs`)
  done: Author in strict TypeScript, type-checked with `tsc --noEmit`
  done: Cover the parser and validator with `bun test`
  done: Preserve source line ranges on every node for round-trip editing
  done: Publish the typed JSON model as the documented renderer contract
  Static tech-tree renderprojectdone100%@pv7/7 tasks
  done: Root layout anchored on the north star
  done: Roadmaps as primary branches, initiatives and projects nested beneath
  done: Task leaves as compact terminal nodes
  done: Show status emoji and progress on each node
  done: Expand/collapse via native disclosure (native `<details>`; React renders it, works pre-hydration)
  done: Render the whole tree from the JSON model in one static page
  done: Playwright E2E: open the page and expand down to a task leaf
  roadmap` route (static)projectdone100%@pv3/3 tasks
  done: Static build that reads `CRUX.md` and emits the `/roadmap` page
  done: Empty, loading, error, and invalid-CRUX states
  done: Page metadata: product name, north star, updated date
  Continuous-deploy pipelineprojectdone100%@pv5/5 tasks
  done: Wire Vercel Git integration: production = `main`, preview = every PR
  done: Gate production promotion on `bun run check` (typecheck + test + strict-validate)
  done: Post a unique preview URL on every PR
  done: Post-deploy Playwright smoke against `/` and `/roadmap` before the promote is final
  done: Document rollback = `git revert` + auto-redeploy (no manual hotfix)
  Dogfood deployprojectdone100%@pv5/5 tasks
  done: Serve `/` (site shell) and `/roadmap` from one continuously-deployed Vercel project
  done: Publish and confirm the live page matches the file
  done: Confirm the publishing merge went through the auto-deploy + smoke gate, not a manual push
  done: Playwright smoke test against the live `/roadmap`
  done: Link the live `/roadmap` from [README.md](README.md)
2. Make it navigableinitiativedone100%@pv31/31 tasks6 projects
  Progressive expansionprojectdone100%@pv6/6 tasks
  done: Collapse/expand any roadmap, initiative, project, or task group
  done: Child-count and completion summary on collapsed nodes
  done: Focus mode for a single branch
  done: Breadcrumbs from the selected node back to the north star
  done: Persist expansion state per session
  done: Keyboard controls for expand, collapse, focus, and back
  Node cards & detail panelprojectdone100%@pv5/5 tasks
  done: Card shows type, title, status, progress, owner, due, and health
  done: Blocked / at-risk indicators bubble up to parent branches
  done: Task checkbox state on task leaves
  done: Detail panel: prose, metadata, child list, and source Markdown
  done: Detail-panel fields link back to the exact Markdown source range
  In-tree quality signalsprojectdone100%@pv4/4 tasks
  done: Surface duplicate/missing ids, broken `depends:`, and dependency cycles
  done: Flag stale due dates and orphaned split files
  done: Flag progress-rollup drift against task completion
  done: Badge affected nodes and list them in an "issues" panel
  Search & filtersprojectdone100%@pv5/5 tasks
  done: Search by title, owner, id, tag, status, and due date
  done: Filter by status, health, owner, horizon, tag, and milestone
  done: Jump directly to blocked, at-risk, or overdue branches
  done: Copy a deep link to any node
  done: Minimap for large roadmaps
  Derived views in the treeprojectdone100%@pv6/6 tasks
  done: Timeline / Gantt view from `start` + `due`
  done: Dependency graph from `depends:`
  done: Now / Next / Later board grouped by `horizon:`
  done: Milestone board grouped by `milestone:` with rollup
  done: Switch views with shared selection and filters
  done: Each view deep-links and exports (PNG / SVG)
  Share, permalink & exportprojectdone100%@pv5/5 tasks
  done: Encode full view state (focus, filters, expansion) in the URL
  done: Copy a permalink to any node or filtered view
  done: Export the current view to PNG / SVG
  done: Print stylesheet: a clean one-page roadmap
  done: "Open the raw `.md`" link from any shared view (C2)
Launch & Narrativeroadmapdone100%@pv23/23 tasks1 initiative
1. Public faceinitiativedone100%@pv23/23 tasks3 projects
  Domain & hostingprojectdone100%@pv4/4 tasks
  done: Register `cruxroadmap.com`
  done: Point DNS at the host and enforce HTTPS
  done: Set the Vercel project's production domain to `cruxroadmap.com`
  done: Reserve the matching GitHub org and a social handle
  Site shellprojectdone100%@pv7/7 tasks
  done: Hero: one line on the format + one line on the product
  done: A single clear CTA into the live `/roadmap`
  done: Footer linking [SPEC.md](SPEC.md) and the GitHub repo
  done: Responsive, accessible (C4); static-first fast load (C5)
  done: Ships from the same Vercel deploy as `/roadmap`
  done: Brand system: the Convergence/Luminous identity (type, color, motion, depth)
  done: Light / dark / auto theming, persisted, no flash-of-wrong-theme
  Homepage: format & product explainerprojectdone100%@pv12/12 tasks
  done: Hero: one line on the format + one line on the product, with a clear CTA
  done: "What is CRUX" — the Markdown format: a real snippet beside the tree it renders to
  done: "What is CRUX Studio" — the product: expandable tech-tree + `/roadmap` publishing
  done: Live demo: an embedded animated preview of this repo's own `/roadmap` tree
  done: "Why" section: Markdown stays the source of truth; for people *and* AI; one file → many
  done: Get-started + GitHub links; footer linking the spec, cruxroadmap.com, and the repo
  done: Responsive and accessible (C4); fast, static-first load (C5)
  done: Playwright E2E: hero renders and the demo link works
  done: Provocative alignment narrative — align teams, AIs, and companies (operational alignment, honest, no value-alignment overclaim)
  done: Agentic-future section — from harnesses augmenting developers to fully agentic processes; CRUX as the shared, trustworthy state
  done: Convergence/Luminous brand system + light / dark / auto theming applied site-wide
  done: Portability & human/AI readability: one file → many surfaces, examples from the real canon (C2)

Open the full /roadmap →

Real files. Copy them.

The smallest valid CRUX file is nine lines:

---
crux: 0.1
title: Weekend project
north_star: A working CLI I actually use.
---

## 🗺 v1
### 🔵 Core commands
> status: active · progress: 33% · id: core
- [x] Parse args
- [ ] Read config
- [ ] Print output

examples/CRUX.example.md — a full reference roadmap you can copy and overwrite.
examples/crux/zero-downtime-deploys.md — a node split into its own file: the multi-file pattern in practice.
CRUX.md — this project's own live roadmap. We dogfood the format.

No signup. No build step. One command.

CRUX is just a file — start by writing one. To check it against the spec, run the dependency-free validator on Bun:

bun bin/crux.ts validate CRUX.md examples

It reports grammar, integrity, and freshness problems with file:line. Add--strict to fail on warnings, or --json to get the typed model for your tools.

Explore the live demo → Star it on GitHub