--- crux: 0.1 title: CRUX Studio north_star: Every software product can publish, explore, and maintain a visual CRUX roadmap at `/roadmap`. owners: [@pv] updated: 2026-06-26 --- # ๐Ÿงญ North Star > **Every software product can publish, explore, and maintain a visual CRUX roadmap at `/roadmap`.** > > CRUX Studio turns plain Markdown roadmaps into an expandable, tech-tree style > product map โ€” roadmaps, initiatives, projects, and tasks become navigable > nodes โ€” while the Markdown stays the portable source of truth. Status: โšช todo ยท ๐Ÿ”ต active ยท ๐ŸŸก at-risk ยท ๐Ÿ”ด blocked ยท ๐ŸŸข done ยท โšซ dropped  |  Size: XSยทSยทMยทLยทXL  |  Priority: P0โ€“P3  |  grammar in [SPEC.md](SPEC.md) --- ## ๐Ÿงฑ Constraints > Non-functional requirements every slice must honor. Invariants, not tasks โ€” they are never "done". Global unless scoped; the `**Verify:**` line is how we'd actually check. - **C1 ยท Runtime: Bun** *(enforced)* โ€” all code, scripts, builds, and tooling run on Bun (โ‰ฅ 1.x). No Node-only assumptions; package scripts call `bun`, never `node`/`npm`. - **Applies to:** whole project - **Verify:** `bun` shebangs; `engines.bun` set; `bun run validate` green; no `node`/`npm` in scripts. - **C2 ยท Markdown is the source of truth** *(enforced)* โ€” the parsed model is always derivable from, and subordinate to, the canonical `.md`. No roadmap state lives only in the app. - **Applies to:** whole project - **Verify:** every model field round-trips to Markdown; export reproduces the file byte-for-byte where possible. - **C3 ยท Minimal dependencies** *(enforced)* โ€” the parser and validator stay dependency-free; any runtime dependency elsewhere must be justified. - **Applies to:** parser, validator, renderer package - **Verify:** `bin/` imports only `node:*` / Bun built-ins; new deps reviewed in PR. - **C4 ยท Accessibility: WCAG 2.1 AA** *(adopting)* โ€” the tree is keyboard-navigable and screen-reader friendly from the first render. - **Applies to:** the renderer - **Verify:** axe checks in CI; a manual keyboard + screen-reader pass before release. - **C5 ยท Performance: `/roadmap` is fast** *(proposed)* โ€” a 1,000-node roadmap renders interactively in under ~1s; prefer static-first output. - **Applies to:** the renderer and hosted publishing - **Verify:** budget check against a 1k-node fixture; static snapshot served by default. - **C6 ยท Pure TypeScript (strict)** *(enforced)* โ€” all source and tests are TypeScript, type-checked under `strict`. No plain JS; types are the contract. - **Applies to:** whole project - **Verify:** `bun run typecheck` (`tsc --noEmit`) clean; no `.js`/`.mjs` source files. - **C7 ยท Test-driven** *(adopting)* โ€” every slice lands with tests; write the failing test first, then the code (red โ†’ green โ†’ refactor). - **Applies to:** whole project - **Verify:** `bun test` green; new behaviour arrives with its tests in the same change. - **C8 ยท Browser testing: Playwright** *(proposed)* โ€” the renderer and `/roadmap` pages are covered by Playwright end-to-end tests. - **Applies to:** the renderer, hosted publishing - **Verify:** `bunx playwright test` green against the built `/roadmap`. - **C9 ยท Deployed on Vercel** *(adopting)* โ€” the app, `/roadmap` pages, and AI endpoints ship on Vercel; design for its serverless model (edge-friendly, pooled data access). - **Applies to:** hosting, the renderer, AI endpoints - **Verify:** production is a Vercel project; no host-specific assumptions outside Vercel primitives. - **C10 ยท Data store: Postgres (Supabase)** *(proposed)* โ€” when persistence is needed, managed Postgres via Supabase (Auth + Storage + row-level security). Markdown stays canonical per **C2** โ€” the DB is a sync, auth, and billing layer, never the source of truth. - **Applies to:** accounts, storage, hosted publishing, AI endpoints - **Verify:** the canonical `.md` round-trips out of storage unchanged; no roadmap state lives only in the DB. - **C11 ยท Payments: Stripe** *(adopting)* โ€” all payments and subscriptions run through Stripe; entitlements are reconciled from Stripe webhooks, never hand-set. No card data touches our servers. - **Applies to:** billing, entitlements, license gating - **Verify:** purchase/upgrade goes through Stripe Checkout; webhooks drive license state; no payment data stored outside Stripe + the entitlements table. - **C12 ยท Continuous deployment** *(enforced)* โ€” `main` is always shippable: every merge to `main` is promoted to production behind a green `bun run check` (typecheck + test + strict-validate) plus a post-deploy smoke gate, and every PR gets an isolated preview deploy. No manual release step ever ships code; rollback is a `git revert` that auto-redeploys, never a hand-applied hotfix. - **Applies to:** hosting, CI/CD, the homepage and `/roadmap`, the renderer, hosted publishing, AI endpoints - **Verify:** a `.github/workflows` job (or Vercel Git integration) promotes production on every push to `main` only after `bun run check` is green; each PR shows a unique preview URL; a post-deploy Playwright smoke hits the live `/` and `/roadmap` before promotion is final; no human "deploy" step exists in any runbook. Now *enforced* (2026-06-24) โ€” the `deploy` job in [.github/workflows/check.yml](.github/workflows/check.yml) is the **sole** production promoter (Vercel's `main` auto-deploy is off, `vercel.json` `git.deploymentEnabled.main: false`); it gates on `bun run check` + E2E, stages a build, runs a post-deploy smoke of `/` and `/roadmap`, and promotes only on green โ€” a failing smoke has already skipped a promote. Previews stay automatic on every PR. - **C13 ยท App stack** *(adopting)* โ€” the web app is built with [Next.js](https://nextjs.org) (App Router) on the [bulletproof-react](https://github.com/alan2207/bulletproof-react) architecture (feature-based `app/` / `features/` / `shared/`, unidirectional deps shared โ†’ features โ†’ app), styled with Tailwind CSS + [FlyonUI](https://flyonui.com), and builds โ€” and, where request-time compute is later needed, runs โ€” on Bun within Vercel, not Node. One stack for every interactive surface. - **Applies to:** the web app, the renderer, the homepage, and later React surfaces - **Verify:** the `app/` workspace follows the bulletproof-react layout (features don't import each other; only the app-layer route Server Components import features + the build-time parser; the dep-free parser **C3** never enters client code โ€” interactivity is isolated to `"use client"` islands); styling is Tailwind utilities + FlyonUI semantic component classes (CSS-only โ€” FlyonUI's interactive JS is not loaded, so a JS-off reader still gets the full static tree per **C5**; no competing CSS framework); native `
` disclosure is kept for the static-first tree (not a JS-only accordion) per **C5**; pages are rendered at build time by Next's static export (`output: "export"`, `next build` โ†’ `app/out`), and `vercel.json` sets `"bunVersion": "1.x"` + `"framework": null` so `bun install && bun run build` produces a fully static deploy served as files, with no Node-only assumptions and no serverless functions (the Bun function runtime, Public Beta, is reserved for `hosted-publish` / `ai-endpoint`). - **C14 ยท Safe agent writes** *(proposed)* โ€” agents may write CRUX, **up to and including autonomously** (CRUX is meant to support AI autonomy, not gate it behind a human). The invariant is *safety and reversibility*, not a person in the loop: every agent write passes the **same validation gate as a human save**, is guarded by a **content hash** (no blind clobbering of newer state), and is **auditable and reversible**. Requiring human approval is a *policy you can switch on per roadmap or token* โ€” never a built-in precondition. - **Applies to:** AI endpoints, the AI assistant/skill, the agentic substrate - **Verify:** every agent write passes the validator and an `If-Match` content-hash check (a stale hash is rejected); writes land in an append-only audit and can be reverted; approval gating is configurable, off by default; an unattended autonomous write is still validated, hashed, audited, and reversible. - **C15 ยท Backwards-compatible standard** *(proposed)* โ€” the CRUX format and the `/roadmap` contract grow **additively** and are versioned; a `crux: 0.1` file keeps parsing and rendering as the format evolves; a breaking change bumps the version and ships with a migration, never a silent break. - **Applies to:** the format/spec, the renderer-model contract, the renderer package, hosted publishing - **Verify:** older CRUX fixtures still parse and render under each release; the model carries its own `version`; deprecations are staged behind a documented migration, never removed in place. - **C16 ยท Data ownership, no lock-in** *(proposed)* โ€” users own their Markdown: one-click export of the exact canonical `.md` is always available, private roadmaps stay private, and nothing requires keeping the file in CRUX Studio to keep using it. - **Applies to:** storage, hosted publishing, accounts, billing, integrations - **Verify:** export reproduces the canonical `.md` byte-for-byte where possible (per **C2**); a cancelled or deleted account can still retrieve its files; private visibility is enforced on every read path, including the AI endpoints. --- ## ๐Ÿ’ณ Access tiers > How CRUX Studio stays free to start and cheap to grow. Local use is free and needs no account; you pay only to host, share, or bring AI. - **Free ยท Local & anonymous** โ€” drop in your `CRUX.md`, explore the tree, edit, and export back out. Entirely in-browser; nothing is uploaded; no signup. - **$3 / user ยท Storage & sharing** โ€” sign up to host, store, version, and publish roadmaps at a `/roadmap` URL (public or private). Priced to spread โ€” the more people share and view, the more it grows. - **$50 ยท AI** โ€” unlocks the AI endpoints (`/roadmap.crux.md`, `/roadmap.crux.json`) and the CRUX Studio AI skill for reading and safely proposing roadmap changes. Each slice below names its tier in prose; the free tier never requires an account. --- ## ๐Ÿšฉ Milestones > The execution sequence. Solo and self-paced โ€” ordered by risk reduction, each one demoable. Targets are relative (*now / next / later*), not dates. Work the slices top-to-bottom within a milestone. - **M0 ยท Live walking skeleton, continuously deployed** *(now)* โ€” `cruxroadmap.com` is live and auto-deploying: a minimal homepage at `/` links to this roadmap read-only at `/roadmap` as a navigable tech-tree, and every merge to `main` ships itself. - **Proves:** the whole vertical thread end-to-end at once โ€” parse โ†’ typed model โ†’ expandable tree โ†’ served at `/roadmap`, fronted by a real homepage, on a real domain, promoted to production automatically with PR previews. The core product bet *and* the delivery machine, with the least code. - **Exit:** open `cruxroadmap.com`: a hero (one line on the format, one on the product) with a CTA into the live `/roadmap`; expand branches down to task leaves and read status/progress; then open a throwaway PR, watch it get its own preview URL, merge it, and watch production auto-redeploy behind a green check+smoke gate. No editing, no accounts. - **Slices:** `parser-model`, `tree-render`, `roadmap-route`, `domain`, `cd-pipeline`, `site-shell`, `homepage`, `dogfood-deploy` - **M1 ยท Navigable demo & explainer homepage** *(next)* โ€” the live `/roadmap` is genuinely usable on a big real roadmap and the live homepage now explains and sells CRUX โ€” both still shipping on every merge. - **Proves:** people can orient and find things in a deep tree, trust what they see, and understand what CRUX is before they arrive โ€” site and engine improving in lockstep on every deploy. - **Exit:** on the live site: collapse/expand and focus a branch, filter to blocked/at-risk, deep-link a node, and see validator problems flagged in-place โ€” each shipped via its own preview deploy then auto-promoted. (The explainer homepage shipped early, in M0.) - **Slices:** `expansion`, `node-cards`, `search-filter`, `quality-signals`, `derived-views`, `share-export` - **M2 ยท The `/roadmap` standard, live as adoption docs** *(later)* โ€” any product can drop in the renderer package and expose `/roadmap`, with a second sample product live and an adoption/docs section on the site โ€” all continuously deployed, including the package release. - **Proves:** the renderer and the `/roadmap` contract are portable and stable beyond this repo, the site itself teaches adoption, and releasing the package is a push, not a ceremony. - **Exit:** a second sample product renders its own CRUX file at `/roadmap` via the published package; the site gains a live "Add `/roadmap` to your product" adoption/docs section plus the in-browser, no-account `local-workspace` demo; a merge to `main` both auto-deploys the docs/standard pages and publishes a package version. - **Slices:** `route-contract`, `renderer-model`, `renderer-package`, `cli`, `visual-language`, `local-workspace`, `adoption`, `site-docs` - **M3 ยท SaaS foundation & pricing site** *(later)* โ€” sign in, upload/host/publish a roadmap others trust as the source of truth, fronted by a real pricing/tiers page โ€” all continuously deployed behind a green migration+smoke gate. - **Proves:** people will keep their canonical CRUX file in the product without lock-in, the site can convert a visitor into a paying ($3 / $50) customer, and the stateful SaaS surface ships safely on every merge. - **Exit:** from `cruxroadmap.com`: read the pricing page (Free local ยท $3 storage & sharing ยท $50 AI), sign in, upload/edit a CRUX file, publish it to a public or private URL, fetch it back as Markdown/JSON, and check out via Stripe; the pricing page and the SaaS endpoints shipped together via the pipeline. - **Slices:** `accounts`, `file-lifecycle`, `storage`, `hosted-publish`, `ai-endpoint`, `public-api`, `embed-hosted`, `billing`, `site-pricing` - **M4 ยท Safe editing loop, demoed on the site** *(later)* โ€” edit visually or in Markdown with the file always valid and reviewable, and the live site hosts a no-account, in-browser editor demo of exactly that loop โ€” continuously deployed behind the validation gate. - **Proves:** visual edits and raw Markdown round-trip without corrupting the source of truth, and the site can show that loop to anyone instantly, in-browser, free and accountless. - **Exit:** on the site's free local-first editor demo: change a node in the tree, see the Markdown patch, edit Markdown back, hit the validation gate, undo, and export a clean `CRUX.md` โ€” entirely in-browser, no account; the same editor powers the app; every merge auto-deploys behind the validation gate and a smoke test. - **Slices:** `visual-editing`, `md-editor`, `validation-gate`, `templates`, `merge` - **M5 ยท Intelligence & integrations, showcased live** *(later)* โ€” AI helps maintain the roadmap and it syncs to GitHub/Linear, with a public site showcase of AI-derived views and the $50 AI-tier narrative โ€” all continuously deployed. - **Proves:** AI reduces maintenance effort without hiding or overwriting the source of truth, and the value is legible on the public site. - **Exit:** AI summarises health and suggests rollups for approval; the roadmap syncs to GitHub/Linear; the site gains an AI showcase (derived timeline / dependency graph / now-next-later board generated from a real CRUX file) plus the AI-tier narrative; each merge auto-deploys AI endpoints + site behind the gate with preview deploys. - **Slices:** `ai-assistant`, `ai-skill`, `roadmap-chat`, `github-sync`, `linear-sync`, `slack-notify`, `site-ai-showcase` > **M6โ€“M10 are exploratory horizons, not the committed sequence.** M0โ†’M5 is the risk-ordered spine. M6โ€“M10 below are real bets that branch *off* it (mostly off M2/M3/M5) and run in parallel; their order and scope are provisional and will firm up as M0โ€“M5 lands. Each still earns its place by retiring a distinct risk for one of CRUX's identities โ€” the open standard, the AI-native substrate, the collaborative product, and the sharp solo tool. - **M6 ยท Format v0.2 & conformance** *(later)* โ€” the format takes its next version: a richer task/dependency graph, multi-file manifests, profiles, and a published JSON Schema + conformance suite โ€” so the standard others adopt is precise and testable, and every `0.1` file still renders (**C15**). - **Proves:** the format can grow without breaking `0.1` files, and "CRUX-compatible" becomes something you can *test*, not just claim. - **Exit:** `crux: 0.2` is specified with a machine-readable JSON Schema and a conformance test suite; `0.1` fixtures still parse and render; task-level ids participate in the dependency graph; a multi-file roadmap resolves through a manifest. - **Slices:** `spec-v02`, `task-graph`, `multi-file-manifest`, `json-schema`, `conformance-suite`, `profiles` - **M7 ยท Agentic substrate** *(later)* โ€” CRUX becomes the read/write **state layer** agents operate on: an MCP server, a typed write-protocol, packaged agent skills & instructions, and an autonomous maintainer that writes safely (**C14**). The AI-native bet, beyond the M5 assistant. - **Proves:** a fleet of agents can keep a roadmap current through a safe, validated, reversible loop โ€” autonomously where trusted โ€” the most differentiated thing CRUX can be. - **Exit:** an agent connects over MCP, reads a roadmap, and writes a validated change against a content hash โ€” applying it autonomously when trusted, or queuing it for approval when policy asks; an autonomous maintainer flags drift and drafts rollups on a schedule. - **Slices:** `mcp-server`, `write-protocol`, `agent-sdk`, `auto-maintainer` - **M8 ยท Multiplayer & collaboration** *(later)* โ€” the hosted product becomes a team surface: real-time presence, node-level comments and threads, review/approval, mentions, and notifications โ€” while the Markdown stays the one source of truth (**C2**) and nobody is locked in (**C16**). - **Proves:** more than one person can maintain a CRUX roadmap together without fighting the file or losing the canonical Markdown. - **Exit:** two people edit the same hosted roadmap with live presence; a change goes through comment โ†’ review โ†’ approve; @mentions notify; an activity feed records who changed what. - **Slices:** `realtime-coedit`, `node-comments`, `review-approval`, `notifications`, `activity-feed`, `sharing-permissions` - **M9 ยท Ecosystem & the open standard** *(later)* โ€” `/roadmap` becomes a convention with a body around it: a public registry, embeds and status badges, editor extensions, a second independent renderer, themes, and open format governance (**C15**). - **Proves:** CRUX is portable and self-sustaining beyond this product โ€” others render, embed, discover, and extend it. - **Exit:** a public registry indexes products exposing `/roadmap`; a badge and an embeddable widget drop into any README; a VS Code/Obsidian extension previews CRUX live; a second renderer passes the conformance suite; a published governance/versioning process exists. - **Slices:** `registry`, `embed-badge`, `editor-extensions`, `second-renderer`, `themes`, `governance` - **M10 ยท Insight & portfolio** *(later)* โ€” from one roadmap to many: cross-roadmap rollups, derived analytics (velocity, burn-up, risk), an executive now/next/later, and a multi-roadmap dependency graph โ€” all *derived and regenerable* (SPEC ยง9), never a second source of truth. - **Proves:** CRUX scales from a single file to an organisation's whole map without leaving Markdown behind. - **Exit:** several roadmaps roll up into one portfolio with an org north star; velocity/burn-up/risk views derive from `done`/`due`/`status`; a cross-file dependency graph spans roadmaps; an exec rollup exports cleanly. - **Slices:** `portfolio`, `analytics`, `cross-roadmap-graph`, `exec-rollup` > โ–ถ **Start here:** `parser-model`, `tree-render`, and `roadmap-route` are done โ€” the parser emits the published JSON model ([MODEL.md](MODEL.md)); a React app (Tailwind + FlyonUI, **C13**) statically renders it as the accessible, expandable tree (axe-clean **C4**, JS-disabled **C5**, Playwright-covered **C8**); and that tree is now served at the canonical `/roadmap` URL with empty/error/invalid-CRUX states and model-derived page metadata. `cd-pipeline` is done too โ€” every push to `main` promotes to production only through a `bun run check` + post-deploy-smoke gate, and that gate is the **sole** promoter (**C12** enforced). `site-shell` and `homepage` shipped together as one rich landing page at `/` (the **Convergence/Luminous** brand, light/dark/auto, and an embedded animated `/roadmap` preview); the post-deploy smoke now distinguishes the homepage at `/` from the tree at `/roadmap`. `domain` is done โ€” `cruxroadmap.com` is live over HTTPS with the production domain wired to Vercel โ€” and `dogfood-deploy` closes M0: *this* roadmap is published through the gated pipeline at `cruxroadmap.com/roadmap`, a post-promote smoke checks the live page, and the README links it. **M0 and M1 are complete.** M1's `navigate` initiative shipped end to end โ€” `expansion` (progressive expand/collapse, hash-addressed focus + breadcrumbs, keyboard nav), `node-cards` (cards + detail panel), `quality-signals` (in-tree validator findings), `search-filter` (search, filters, minimap), `derived-views` (deterministic Timeline / boards / dependency graph, switchable + exportable), and `share-export` (full-state permalinks, tree PNG/SVG export, a print stylesheet, and an "open the raw `.md`" link) โ€” alongside the `homepage` explainer; the **Visual Roadmap is now fully navigable**. Next is **M2** โ€” make the renderer portable so any product exposes `/roadmap` (`route-contract`, `renderer-model`, `renderer-package`) with an adoption/docs section on the site. Beyond the committed M0โ†’M5 spine, **M6โ€“M10** open exploratory horizons โ€” **Format v0.2 & conformance**, an **Agentic substrate**, **Multiplayer**, the **Ecosystem / open standard**, and **Insight & portfolio** โ€” branching off M2/M3/M5 rather than running in strict sequence. --- ## ๐ŸŸข Visual Roadmap > status: done ยท progress: 100% ยท owner: @pv ยท id: visual ยท horizon: now The core product: turn a CRUX file into an expandable tech-tree you start at the north star and open down to task leaves. The Markdown stays the source of truth; the tree is a trustworthy projection of it. ### ๐ŸŸข Render pipeline > status: done ยท progress: 100% ยท owner: @pv ยท id: render-pipeline ยท milestone: M0 ยท priority: P0 ยท horizon: now The thinnest path that proves the whole product: a CRUX file becomes a navigable tree served at `/roadmap`. Everything here is M0. #### ๐ŸŸข Parser & document model > status: done ยท progress: 100% ยท owner: @pv ยท id: parser-model ยท milestone: M0 ยท estimate: M ยท priority: P0 ยท done: 2026-06-23 ยท constraints: C3, C6, C7 **Outcome:** a CRUX file becomes a typed model any renderer or agent can consume โ€” the same shape `crux validate --json` already emits. - [x] Define the CRUX grammar in [SPEC.md](SPEC.md) ยท done: 2026-06-23 - [x] Parse frontmatter, north star, and the heading hierarchy into nodes - [x] Parse checkbox tasks as task leaves - [x] Parse blockquote meta lines and inline task metadata into structured fields - [x] Ship a dependency-free CLI parser + validator (`bin/crux.ts`) - [x] Extract the parser into an importable module (`parseText` / `validateDocs`) - [x] Author in strict TypeScript, type-checked with `tsc --noEmit` - [x] Cover the parser and validator with `bun test` - [x] Preserve source line ranges on every node for round-trip editing ยท done: 2026-06-23 - [x] Publish the typed JSON model as the documented renderer contract ยท done: 2026-06-23 #### ๐ŸŸข Static tech-tree render > status: done ยท progress: 100% ยท owner: @pv ยท id: tree-render ยท milestone: M0 ยท estimate: L ยท priority: P0 ยท depends: parser-model ยท done: 2026-06-23 ยท constraints: C4, C5, C8, C13 **Outcome:** as a visitor I see the roadmap as an expandable tree rooted on the north star. - [x] Root layout anchored on the north star ยท done: 2026-06-23 - [x] Roadmaps as primary branches, initiatives and projects nested beneath ยท done: 2026-06-23 - [x] Task leaves as compact terminal nodes ยท done: 2026-06-23 - [x] Show status emoji and progress on each node ยท done: 2026-06-23 - [x] Expand/collapse via native disclosure (native `
`; React renders it, works pre-hydration) ยท done: 2026-06-23 - [x] Render the whole tree from the JSON model in one static page ยท done: 2026-06-23 - [x] Playwright E2E: open the page and expand down to a task leaf ยท done: 2026-06-23 #### ๐ŸŸข `/roadmap` route (static) > status: done ยท progress: 100% ยท owner: @pv ยท id: roadmap-route ยท milestone: M0 ยท estimate: S ยท priority: P0 ยท depends: tree-render ยท done: 2026-06-23 **Outcome:** the tree is served at a predictable `/roadmap` URL. - [x] Static build that reads `CRUX.md` and emits the `/roadmap` page ยท done: 2026-06-23 - [x] Empty, loading, error, and invalid-CRUX states ยท done: 2026-06-23 - [x] Page metadata: product name, north star, updated date ยท done: 2026-06-23 #### ๐ŸŸข Continuous-deploy pipeline > status: done ยท progress: 100% ยท owner: @pv ยท id: cd-pipeline ยท milestone: M0 ยท estimate: S ยท priority: P0 ยท depends: roadmap-route, domain ยท constraints: C9, C12 ยท done: 2026-06-24 **Outcome:** `main` is always shippable โ€” every merge auto-deploys to production, every PR previews, and the promote is gated on a green check. This slice *is* C12 made real. - [x] Wire Vercel Git integration: production = `main`, preview = every PR ยท done: 2026-06-23 - [x] Gate production promotion on `bun run check` (typecheck + test + strict-validate) ยท done: 2026-06-24 - [x] Post a unique preview URL on every PR ยท done: 2026-06-23 - [x] Post-deploy Playwright smoke against `/` and `/roadmap` before the promote is final ยท done: 2026-06-24 - [x] Document rollback = `git revert` + auto-redeploy (no manual hotfix) ยท done: 2026-06-24 #### ๐ŸŸข Dogfood deploy > status: done ยท progress: 100% ยท owner: @pv ยท id: dogfood-deploy ยท milestone: M0 ยท estimate: S ยท priority: P0 ยท depends: roadmap-route, domain, cd-pipeline, site-shell ยท constraints: C8, C9, C12 ยท done: 2026-06-25 **Outcome:** *this* roadmap is publicly live at `/roadmap` โ€” the MVP cut line โ€” published *through* the pipeline, not by hand. - [x] Serve `/` (site shell) and `/roadmap` from one continuously-deployed Vercel project ยท done: 2026-06-25 - [x] Publish and confirm the live page matches the file ยท done: 2026-06-25 - [x] Confirm the publishing merge went through the auto-deploy + smoke gate, not a manual push ยท done: 2026-06-25 - [x] Playwright smoke test against the live `/roadmap` ยท done: 2026-06-25 - [x] Link the live `/roadmap` from [README.md](README.md) ยท done: 2026-06-25 ### ๐ŸŸข Make it navigable > status: done ยท progress: 100% ยท owner: @pv ยท id: navigate ยท milestone: M1 ยท priority: P1 ยท horizon: next Turn the static tree into something usable for a large, real roadmap. #### ๐ŸŸข Progressive expansion > status: done ยท progress: 100% ยท owner: @pv ยท id: expansion ยท milestone: M1 ยท estimate: M ยท priority: P1 ยท depends: tree-render ยท done: 2026-06-25 **Outcome:** I can keep opening nodes without losing orientation. - [x] Collapse/expand any roadmap, initiative, project, or task group ยท done: 2026-06-25 - [x] Child-count and completion summary on collapsed nodes ยท done: 2026-06-25 - [x] Focus mode for a single branch ยท done: 2026-06-25 - [x] Breadcrumbs from the selected node back to the north star ยท done: 2026-06-25 - [x] Persist expansion state per session ยท done: 2026-06-25 - [x] Keyboard controls for expand, collapse, focus, and back ยท done: 2026-06-25 #### ๐ŸŸข Node cards & detail panel > status: done ยท progress: 100% ยท owner: @pv ยท id: node-cards ยท milestone: M1 ยท estimate: M ยท priority: P1 ยท depends: expansion ยท done: 2026-06-25 **Outcome:** every node is legible at a glance, with deeper detail on demand. - [x] Card shows type, title, status, progress, owner, due, and health ยท done: 2026-06-25 - [x] Blocked / at-risk indicators bubble up to parent branches ยท done: 2026-06-25 - [x] Task checkbox state on task leaves ยท done: 2026-06-25 - [x] Detail panel: prose, metadata, child list, and source Markdown ยท done: 2026-06-25 - [x] Detail-panel fields link back to the exact Markdown source range ยท done: 2026-06-25 #### ๐ŸŸข In-tree quality signals > status: done ยท progress: 100% ยท owner: @pv ยท id: quality-signals ยท milestone: M1 ยท estimate: S ยท priority: P1 ยท depends: node-cards, parser-model ยท done: 2026-06-25 **Outcome:** the structural problems the validator already finds are visible in the tree. - [x] Surface duplicate/missing ids, broken `depends:`, and dependency cycles ยท done: 2026-06-25 - [x] Flag stale due dates and orphaned split files ยท done: 2026-06-25 - [x] Flag progress-rollup drift against task completion ยท done: 2026-06-25 - [x] Badge affected nodes and list them in an "issues" panel ยท done: 2026-06-25 #### ๐ŸŸข Search & filters > status: done ยท progress: 100% ยท owner: @pv ยท id: search-filter ยท milestone: M1 ยท estimate: M ยท priority: P2 ยท depends: node-cards ยท done: 2026-06-25 **Outcome:** I can move around a large CRUX file quickly. - [x] Search by title, owner, id, tag, status, and due date ยท done: 2026-06-25 - [x] Filter by status, health, owner, horizon, tag, and milestone ยท done: 2026-06-25 - [x] Jump directly to blocked, at-risk, or overdue branches ยท done: 2026-06-25 - [x] Copy a deep link to any node ยท done: 2026-06-25 - [x] Minimap for large roadmaps ยท done: 2026-06-25 #### ๐ŸŸข Derived views in the tree > status: done ยท progress: 100% ยท owner: @pv ยท id: derived-views ยท milestone: M1 ยท estimate: M ยท priority: P2 ยท depends: node-cards ยท done: 2026-06-26 **Outcome:** the same data renders as more than a tree โ€” **deterministically, for accuracy** (no AI). The *inferred, flexible* counterpart โ€” views generated even when the data is missing or fuzzy โ€” lives in `ai-assistant`; CRUX keeps both, exact and inferred, side by side. - [x] Timeline / Gantt view from `start` + `due` ยท done: 2026-06-26 - [x] Dependency graph from `depends:` ยท done: 2026-06-26 - [x] Now / Next / Later board grouped by `horizon:` ยท done: 2026-06-26 - [x] Milestone board grouped by `milestone:` with rollup ยท done: 2026-06-26 - [x] Switch views with shared selection and filters ยท done: 2026-06-26 - [x] Each view deep-links and exports (PNG / SVG) ยท done: 2026-06-26 #### ๐ŸŸข Share, permalink & export > status: done ยท progress: 100% ยท owner: @pv ยท id: share-export ยท milestone: M1 ยท estimate: S ยท priority: P2 ยท depends: search-filter ยท done: 2026-06-26 **Outcome:** any view of the roadmap is a URL I can hand to someone โ€” or take with me. - [x] Encode full view state (focus, filters, expansion) in the URL ยท done: 2026-06-26 - [x] Copy a permalink to any node or filtered view ยท done: 2026-06-26 - [x] Export the current view to PNG / SVG ยท done: 2026-06-26 - [x] Print stylesheet: a clean one-page roadmap ยท done: 2026-06-26 - [x] "Open the raw `.md`" link from any shared view (C2) ยท done: 2026-06-26 --- ## ๐ŸŸข Launch & Narrative > status: done ยท progress: 100% ยท owner: @pv ยท id: launch ยท horizon: next Give CRUX a public front door: a domain, and a homepage that explains both **CRUX the format** and **CRUX Studio the product**, with the live `/roadmap` demo one click away. ### ๐ŸŸข Public face > status: done ยท progress: 100% ยท owner: @pv ยท id: public-face ยท priority: P1 ยท horizon: next #### ๐ŸŸข Domain & hosting > status: done ยท progress: 100% ยท owner: @pv ยท id: domain ยท milestone: M0 ยท estimate: S ยท priority: P1 ยท done: 2026-06-25 **Outcome:** CRUX has a real home โ€” homepage at `/`, the dogfood roadmap at `/roadmap`. Registered 2026-06-23: **`cruxroadmap.com`** โ€” the home for the homepage and the live `/roadmap` demo. (`crux.page` was the shorter exact-match pick; sticking with the `.com` for now.) - [x] Register `cruxroadmap.com` ยท done: 2026-06-23 - [x] Point DNS at the host and enforce HTTPS ยท done: 2026-06-25 - [x] Set the Vercel project's production domain to `cruxroadmap.com` ยท done: 2026-06-25 - [x] Reserve the matching GitHub org and a social handle ยท done: 2026-06-25 #### ๐ŸŸข Site shell > status: done ยท progress: 100% ยท owner: @pv ยท id: site-shell ยท milestone: M0 ยท estimate: S ยท priority: P1 ยท depends: domain ยท constraints: C4, C5, C12 ยท done: 2026-06-24 **Outcome (free):** a public website exists the moment the engine does โ€” a landing at `/`, served from the same deploy as the dogfood `/roadmap`. Shipped together with `homepage` as one rich page, on the **Convergence/Luminous** brand with light/dark/auto theming. - [x] Hero: one line on the format + one line on the product - [x] A single clear CTA into the live `/roadmap` - [x] Footer linking [SPEC.md](SPEC.md) and the GitHub repo - [x] Responsive, accessible (C4); static-first fast load (C5) - [x] Ships from the same Vercel deploy as `/roadmap` - [x] Brand system: the Convergence/Luminous identity (type, color, motion, depth) - [x] Light / dark / auto theming, persisted, no flash-of-wrong-theme #### ๐ŸŸข Homepage: format & product explainer > status: done ยท progress: 100% ยท owner: @pv ยท id: homepage ยท milestone: M0 ยท estimate: M ยท priority: P1 ยท depends: site-shell, domain ยท constraints: C4, C5, C6, C8, C12 ยท done: 2026-06-24 **Outcome:** a first-time visitor understands CRUX in 30 seconds and can open the live demo. Built on the M0 `site-shell` into the full explainer (pulled into M0 โ€” shipped as one rich landing page). `depends` is build-order, so a done homepage may depend on the still-in-progress `domain`. - [x] Hero: one line on the format + one line on the product, with a clear CTA - [x] "What is CRUX" โ€” the Markdown format: a real snippet beside the tree it renders to - [x] "What is CRUX Studio" โ€” the product: expandable tech-tree + `/roadmap` publishing - [x] Live demo: an embedded animated preview of this repo's own `/roadmap` tree - [x] "Why" section: Markdown stays the source of truth; for people *and* AI; one file โ†’ many - [x] Get-started + GitHub links; footer linking the spec, cruxroadmap.com, and the repo - [x] Responsive and accessible (C4); fast, static-first load (C5) - [x] Playwright E2E: hero renders and the demo link works - [x] Provocative alignment narrative โ€” align teams, AIs, and companies (operational alignment, honest, no value-alignment overclaim) - [x] Agentic-future section โ€” from harnesses augmenting developers to fully agentic processes; CRUX as the shared, trustworthy state - [x] Convergence/Luminous brand system + light / dark / auto theming applied site-wide - [x] Portability & human/AI readability: one file โ†’ many surfaces, examples from the real canon (C2) --- ## โšช The `/roadmap` Standard > status: todo ยท progress: 0% ยท owner: @pv ยท id: standard ยท horizon: later Make the renderer portable so any product can expose its roadmap at a predictable `/roadmap` URL without inventing custom roadmap UX. ### โšช Portable renderer & adoption > status: todo ยท progress: 0% ยท owner: @pv ยท id: portable-renderer ยท milestone: M2 ยท priority: P2 ยท horizon: later #### โšช Route & discovery contract > status: todo ยท progress: 0% ยท owner: @pv ยท id: route-contract ยท milestone: M2 ยท estimate: S ยท priority: P2 **Outcome:** a product knows exactly what to provide to adopt the standard. - [ ] Canonical public URL: `/roadmap` - [ ] Source discovery: `/CRUX.md`, `/roadmap.md`, or explicit config - [ ] AI-readable endpoints: `/roadmap.crux.md` and `/roadmap.crux.json` - [ ] Required empty / loading / error / invalid states - [ ] Deep-link format for individual nodes #### โšช Renderer input/output model > status: todo ยท progress: 0% ยท owner: @pv ยท id: renderer-model ยท milestone: M2 ยท estimate: M ยท priority: P2 ยท depends: route-contract, parser-model **Outcome:** a stable, typed contract between CRUX Markdown and any renderer (formalises `crux validate --json`). - [ ] Typed JSON model for north star, roadmap, initiative, project, and task nodes - [ ] All meta fields: status, health, progress, owner, dates, depends, tags, link, planning fields - [ ] Parent-child tree edges and dependency-graph edges - [ ] Warnings for invalid or partially parsed input #### โšช Visual language spec > status: todo ยท progress: 0% ยท owner: @pv ยท id: visual-language ยท milestone: M2 ยท estimate: M ยท priority: P3 **Outcome:** a documented visual grammar every renderer follows. - [ ] Node shapes for north star, roadmap, initiative, project, and task - [ ] Status, health, owner, due, progress, and dependency indicators - [ ] Collapsed / expanded / focused / selected / blocked / stale states - [ ] Accessibility rules: keyboard nav, focus order, screen readers #### โšช Embeddable renderer package > status: todo ยท progress: 0% ยท owner: @pv ยท id: renderer-package ยท milestone: M2 ยท estimate: L ยท priority: P2 ยท depends: renderer-model, tree-render, expansion ยท constraints: C4, C8 **Outcome:** anyone can install a package and render a CRUX file. - [ ] Package accepts CRUX Markdown as input - [ ] Framework-agnostic web component - [ ] React bindings - [ ] Static rendering for docs/marketing sites - [ ] Client-side hydration for expansion, filtering, and search - [ ] Playwright tests for the packaged renderer #### โšช Adoption modes & docs > status: todo ยท progress: 0% ยท owner: @pv ยท id: adoption ยท milestone: M2 ยท estimate: M ยท priority: P3 ยท depends: renderer-package **Outcome:** a product team can copy the pattern in an afternoon. - [ ] Static, client, hosted, embedded, and private adoption modes - [ ] "Add `/roadmap` to your product" guide content - [ ] Required vs optional fields for good rendering; a11y + SEO expectations - [ ] Public-vs-internal field guidance and a launch checklist - [ ] Example integrations: SaaS marketing site, OSS project, docs site #### โšช Adoption docs on the live site > status: todo ยท progress: 0% ยท owner: @pv ยท id: site-docs ยท milestone: M2 ยท estimate: S ยท priority: P3 ยท depends: adoption ยท constraints: C4, C5, C12 **Outcome:** the M2 website increment โ€” the "Add `/roadmap` to your product" story rendered live on `cruxroadmap.com`, so the site teaches adoption as the standard ships. - [ ] Render the "add `/roadmap` to your product" guide on the live site - [ ] Showcase the second sample product's `/roadmap` - [ ] Surface the documented visual language (links `visual-language`) - [ ] Embed the in-browser `local-workspace` demo as a live playground entry #### โšช The `crux` CLI > status: todo ยท progress: 0% ยท owner: @pv ยท id: cli ยท milestone: M2 ยท estimate: M ยท priority: P2 ยท depends: renderer-package ยท constraints: C1, C3 **Outcome:** the format has a first-class command line beyond `validate` โ€” scaffold, render, and format from the terminal. - [ ] `crux init` scaffolds a starter `CRUX.md` from a template - [ ] `crux render` emits a static `/roadmap` (HTML) from a file - [ ] `crux fmt` normalises meta lines and spacing without changing meaning - [ ] `crux view` opens a local, live-reloading preview - [ ] `crux validate --watch` for tight editing loops - [ ] Publish as a `bunx`/`npx`-runnable package --- ## โšช SaaS Foundation > status: todo ยท progress: 0% ยท owner: @pv ยท id: saas ยท horizon: later The **$3/user** tier: accounts, storage, and publishing โ€” built on Supabase Postgres + Auth + Storage (per **C10**). Host and publish roadmaps so people trust CRUX Studio with their source of truth, without ever trapping the Markdown. Local use stays free (see Local-First Workspace). ### โšช Host & publish roadmaps > status: todo ยท progress: 0% ยท owner: @pv ยท id: host-publish ยท milestone: M3 ยท priority: P2 ยท horizon: later #### โšช Accounts & workspaces > status: todo ยท progress: 0% ยท owner: @pv ยท id: accounts ยท milestone: M3 ยท estimate: M ยท priority: P2 ยท constraints: C10 - [ ] Email/password or OAuth login - [ ] Personal and team workspaces - [ ] Role model: owner, editor, viewer #### โšช Markdown file lifecycle > status: todo ยท progress: 0% ยท owner: @pv ยท id: file-lifecycle ยท milestone: M3 ยท estimate: M ยท priority: P2 ยท depends: parser-model **Outcome:** the roadmap is never trapped โ€” upload, edit, download, replace at any time. - [ ] Upload a `CRUX.md` or compatible `.md` file - [ ] Paste raw CRUX Markdown to create a roadmap - [ ] Edit the canonical Markdown directly in the app - [ ] Download the current canonical `CRUX.md` at any time - [ ] Replace a roadmap by uploading a new file - [ ] Validate and preview before replacing stored content #### โšช Storage & revisions > status: todo ยท progress: 0% ยท owner: @pv ยท id: storage ยท milestone: M3 ยท estimate: M ยท priority: P2 ยท depends: file-lifecycle ยท constraints: C10 - [ ] Store canonical Markdown per roadmap; keep parsed model in sync - [ ] Version revisions and restore a previous one - [ ] Track import source, timestamp, editor, and validation status - [ ] Raw Markdown stays the source of truth even as the parsed model changes #### โšช Hosted `/roadmap` publishing > status: todo ยท progress: 0% ยท owner: @pv ยท id: hosted-publish ยท milestone: M3 ยท estimate: L ยท priority: P2 ยท depends: renderer-package, accounts, storage ยท constraints: C9, C10, C12 - [ ] Publish to a public URL - [ ] Publish to a private, authenticated URL - [ ] Custom domain or path target - [ ] Choose public vs internal-only fields - [ ] Static snapshot for fast public loads #### โšช AI-readable CRUX endpoint > status: todo ยท progress: 0% ยท owner: @pv ยท id: ai-endpoint ยท milestone: M3 ยท estimate: M ยท priority: P2 ยท depends: hosted-publish, storage, renderer-model ยท constraints: C9, C10, C12 **Outcome (AI tier, $50):** agents can read and safely propose changes without scraping the UI. - [ ] Serve canonical Markdown at `/roadmap.crux.md` - [ ] Serve parsed JSON at `/roadmap.crux.json` - [ ] Schema/version, updated timestamp, source hash, and visibility metadata - [ ] Public, private, and token-scoped access - [ ] ETag / content-hash check before AI-written updates are accepted - [ ] Gate access behind a valid AI license ($50) - [ ] Document how agents fetch, diff, validate, and propose CRUX edits #### โšช Billing & licenses (Stripe) > status: todo ยท progress: 0% ยท owner: @pv ยท id: billing ยท milestone: M3 ยท estimate: L ยท priority: P3 ยท depends: accounts, hosted-publish ยท constraints: C9, C11, C12 **Outcome:** two simple Stripe license products โ€” cheap to start, AI as a premium add-on โ€” with entitlements driven by webhooks, not hand-set. - [ ] Stripe products + prices: **Storage license $3/user** and **AI license $50** - [ ] Stripe Checkout flow to upgrade from the free tier - [ ] Stripe webhooks โ†’ reconcile entitlements into Supabase (the access source of truth) - [ ] Free tier is local-only (no account); the storage license unlocks hosting/storage/publishing - [ ] The AI license gates the AI endpoints and the CRUX Studio AI skill - [ ] Entitlement checks across the app (free ยท storage ยท AI) - [ ] Self-serve subscription management via the Stripe billing portal #### โšช Pricing & tiers page > status: todo ยท progress: 0% ยท owner: @pv ยท id: site-pricing ยท milestone: M3 ยท estimate: S ยท priority: P3 ยท depends: billing ยท constraints: C5, C9, C11, C12 **Outcome:** the M3 website increment โ€” a public pricing page that converts a visitor into a paying customer, wired to Stripe Checkout. - [ ] Pricing page reflecting the three tiers in prose (Free local ยท $3 storage & sharing ยท $50 AI) - [ ] Sign-in / upload front door from the page - [ ] Free tier stated as local-only, accountless - [ ] CTA into Stripe Checkout for the $3 and $50 licenses (via `billing`) #### โšช Public API & webhooks > status: todo ยท progress: 0% ยท owner: @pv ยท id: public-api ยท milestone: M3 ยท estimate: M ยท priority: P3 ยท depends: hosted-publish, storage ยท constraints: C9, C16 **Outcome:** CRUX is integratable at every level โ€” a hosted roadmap is reachable programmatically, not just as a page. This REST surface underpins the AI layer (`ai-endpoint`, `mcp-server`) so agents and tools read and write through one contract. - [ ] REST endpoints to read *and write* a roadmap's model and revisions - [ ] Scoped API tokens per workspace (human, tool, or agent) - [ ] Webhooks on publish / change / validation-failure - [ ] Rate limits and usage visibility - [ ] OpenAPI description, so any client (or agent) can self-integrate #### โšช Embeddable hosted roadmap > status: todo ยท progress: 0% ยท owner: @pv ยท id: embed-hosted ยท milestone: M3 ยท estimate: S ยท priority: P3 ยท depends: hosted-publish **Outcome:** a published roadmap drops into any site or doc. - [ ] Iframe / embed snippet for a hosted `/roadmap` - [ ] oEmbed support for rich link unfurls - [ ] Themeable to match the host site - [ ] Honours public/private visibility (C16) --- ## โšช Local-First Workspace (free) > status: todo ยท progress: 0% ยท owner: @pv ยท id: editing ยท horizon: later The **free, no-account tier**: open your own `CRUX.md`, work on it entirely in the browser, and export it back out. Move freely between the visual tree and raw Markdown; every edit path keeps the file valid and exportable. Nothing is uploaded โ€” hosting and storage are the paid tier. ### โšช Work locally, no account > status: todo ยท progress: 0% ยท owner: @pv ยท id: edit-loop ยท priority: P2 ยท horizon: later #### โšช Local workspace (anonymous) > status: todo ยท progress: 0% ยท owner: @pv ยท id: local-workspace ยท milestone: M2 ยท estimate: M ยท priority: P1 ยท depends: tree-render ยท constraints: C2, C4, C6 **Outcome (free):** open any `CRUX.md` from your machine, use the full tree, and export โ€” no signup, nothing leaves the browser. - [ ] Open a file via the File System Access API, drag-drop, or paste - [ ] Parse, validate, and render entirely client-side (offline-capable) - [ ] Export / download the current `CRUX.md` at any time - [ ] Make explicit that nothing is uploaded and no account is required #### โšช Visual node editing > status: todo ยท progress: 0% ยท owner: @pv ยท id: visual-editing ยท milestone: M4 ยท estimate: L ยท priority: P3 ยท depends: node-cards - [ ] Edit title, status, owner, due, health, and progress from the tree - [ ] Add roadmap, initiative, project, and task nodes - [ ] Move nodes within the hierarchy - [ ] Mark tasks done from the visual view - [ ] Emit a Markdown patch for each visual edit #### โšช Markdown editor & two-way sync > status: todo ยท progress: 0% ยท owner: @pv ยท id: md-editor ยท milestone: M4 ยท estimate: L ยท priority: P3 ยท depends: visual-editing - [ ] Markdown editor beside the visual tree - [ ] Visual edits sync into Markdown immediately - [ ] Markdown edits sync back into the tree after validation - [ ] Before/after Markdown preview for every structural edit - [ ] Preserve comments, prose, and unknown metadata where possible - [ ] Undo/redo for roadmap edits - [ ] Export a clean `CRUX.md` #### โšช Validation gate > status: todo ยท progress: 0% ยท owner: @pv ยท id: validation-gate ยท milestone: M4 ยท estimate: S ยท priority: P3 ยท depends: md-editor, parser-model ยท constraints: C12 **Outcome:** nothing invalid can be saved or published โ€” reuses the validator. - [ ] Run grammar + integrity checks before save - [ ] Block on errors; warn on warnings, shown inline - [ ] Suggest progress rollups from task completion - [ ] The pre-save validation gate runs identically in the deploy pipeline (no save can ship invalid Markdown) #### โšช Templates & starters > status: todo ยท progress: 0% ยท owner: @pv ยท id: templates ยท milestone: M4 ยท estimate: S ยท priority: P3 ยท depends: local-workspace **Outcome:** a blank page is never the starting point. - [ ] A gallery of starter roadmaps (OSS project, SaaS, solo, team) - [ ] "New from template" in the local workspace and the app - [ ] Turn any roadmap into a reusable template (strip values, keep shape) - [ ] Inline guidance/snippets for each level and meta key #### โšช Revision diff & merge > status: todo ยท progress: 0% ยท owner: @pv ยท id: merge ยท milestone: M4 ยท estimate: M ยท priority: P3 ยท depends: md-editor, storage **Outcome:** two divergent edits of the same file reconcile without losing work. - [ ] Side-by-side diff between any two revisions - [ ] Three-way merge when local and remote both changed - [ ] Conflict resolution at node granularity, not raw text - [ ] Restore or cherry-pick a node from an older revision --- ## โšช Intelligence & Integrations > status: todo ยท progress: 0% ยท owner: @pv ยท id: intelligence ยท horizon: later The **$50 AI license** tier. Reduce roadmap-maintenance effort with AI, and sync to the tools where work is executed โ€” never hiding the source of truth. ### โšช AI assistance & sync > status: todo ยท progress: 0% ยท owner: @pv ยท id: ai-sync ยท milestone: M5 ยท priority: P3 ยท horizon: later #### โšช AI roadmap assistant > status: todo ยท progress: 0% ยท owner: @pv ยท id: ai-assistant ยท milestone: M5 ยท estimate: L ยท priority: P3 ยท depends: quality-signals, md-editor, ai-endpoint, validation-gate ยท constraints: C14 **Outcome (AI tier, $50):** one assistant that can do everything to a roadmap โ€” read it, reason about it, and author it from natural language โ€” safely (C14), autonomously where you let it. - [ ] Summarise roadmap health, top risks, and what ships next - [ ] Suggest progress/status updates from completed checkboxes and linked PRs - [ ] Detect stale due dates and blocked dependencies - [ ] Author from natural language: "add an initiative for X with three projects" โ†’ a validated patch - [ ] Generate a starter roadmap from a prose brief; restructure, re-tag, re-estimate on request - [ ] Generate derived views (timeline, dep-graph, now/next/later) โ€” *inferred* where the data is missing, the flexible counterpart to deterministic `derived-views` - [ ] Every change is validated and reversible; apply autonomously or gate on approval per policy (C14) #### โšช CRUX Studio AI skill > status: todo ยท progress: 0% ยท owner: @pv ยท id: ai-skill ยท milestone: M5 ยท estimate: M ยท priority: P3 ยท depends: ai-endpoint, md-editor - [ ] Teach the grammar, hierarchy, status/progress rules, and derived-view contract - [ ] Discover `/roadmap`, `/roadmap.crux.md`, and `/roadmap.crux.json` - [ ] Fetch source hash / ETag before proposing or applying edits - [ ] Preserve ids, prose, comments, unknown metadata, and formatting - [ ] Validate dependencies, rollups, and split-file pointers - [ ] Use the upload/download/storage/publish APIs - [ ] Require human approval before destructive or published changes #### โšช Conversational roadmap โ€” ask ยท propose ยท apply > status: todo ยท progress: 0% ยท owner: @pv ยท id: roadmap-chat ยท milestone: M5 ยท estimate: M ยท priority: P3 ยท depends: ai-endpoint, ai-assistant ยท constraints: C14 **Outcome (AI tier, $50):** talk to the roadmap in three modes โ€” read it, draft changes, or apply them โ€” the conversational surface over `ai-assistant`. - [ ] **Ask** mode: "what's blocked and why?", "what ships next?" answered from the model, citing exact nodes and source lines - [ ] **Propose** mode: draft a change as a validated diff to review - [ ] **Apply** mode: write the change โ€” autonomously when policy allows, validated and reversible either way (C14) - [ ] Summarise a branch or a milestone on demand - [ ] Switch modes per message; the mode is explicit, never guessed #### โšช GitHub sync > status: todo ยท progress: 0% ยท owner: @pv ยท id: github-sync ยท milestone: M5 ยท estimate: M ยท priority: P3 ยท depends: storage - [ ] Connect a repository and import its `CRUX.md` - [ ] Open a pull request for roadmap edits - [ ] Detect remote changes before overwriting #### โšช Work-tracker sync โ€” Linear ยท Jira ยท GitHub Projects > status: todo ยท progress: 0% ยท owner: @pv ยท id: linear-sync ยท milestone: M5 ยท estimate: L ยท priority: P3 ยท depends: ai-assistant, storage **Outcome:** connect a CRUX roadmap to where execution happens โ€” **both directions** โ€” across Linear, Jira, and GitHub Projects. - [ ] Link CRUX nodes to Linear / Jira / GitHub Projects items - [ ] Show linked external status beside roadmap nodes - [ ] **Two-way sync:** roadmap edits push out; external status/changes flow back - [ ] **Import a tracker project โ†’ generate a `CRUX.md`** (e.g. a Jira project becomes a roadmap) - [ ] Generate issue drafts from roadmap tasks - [ ] Per-connector field mapping and conflict handling #### โšช Slack digest & alerts > status: todo ยท progress: 0% ยท owner: @pv ยท id: slack-notify ยท milestone: M5 ยท estimate: S ยท priority: P3 ยท depends: ai-assistant - [ ] Post roadmap-health digests to Slack - [ ] Alert on new blockers, slips, and overdue nodes - [ ] Weekly "what changed" summary from revisions #### โšช AI showcase on the live site > status: todo ยท progress: 0% ยท owner: @pv ยท id: site-ai-showcase ยท milestone: M5 ยท estimate: S ยท priority: P3 ยท depends: ai-assistant ยท constraints: C5, C12 **Outcome (AI tier, $50):** the M5 website increment โ€” a public showcase of AI-derived views so the site keeps growing alongside the engine through the final milestone. - [ ] Render derived timeline / dependency-graph / now-next-later views from a live CRUX file - [ ] AI-tier narrative explaining the $50 license - [ ] Link the AI-readable endpoints (`/roadmap.crux.md`, `/roadmap.crux.json`) --- ## โšช Format & Conformance > status: todo ยท progress: 0% ยท owner: @pv ยท id: format ยท horizon: later Evolve the format itself โ€” carefully, additively, never breaking a `0.1` file (**C15**). The spec is the real moat: the more precise and testable "CRUX" is, the more renderers, agents, and teams can trust it. This roadmap is the home for **CRUX 0.2**. (Studio + light spec evolution โ€” the spec stays `0.1` until these slices actually ship.) ### โšช CRUX 0.2 & the conformance suite > status: todo ยท progress: 0% ยท owner: @pv ยท id: spec-evolution ยท milestone: M6 ยท priority: P3 ยท horizon: later ยท constraints: C15 #### โšช Format v0.2 proposal > status: todo ยท progress: 0% ยท owner: @pv ยท id: spec-v02 ยท milestone: M6 ยท estimate: M ยท priority: P3 ยท constraints: C15 **Outcome:** a written, reviewed `crux: 0.2` that only *adds* โ€” every `0.1` file still valid. - [ ] Draft the 0.2 delta against [SPEC.md](SPEC.md), additive-only - [ ] An `x-` extension namespace for custom fields the validator tolerates - [ ] A comment/annotation syntax distinct from prose - [ ] Milestone targets (date/horizon) and capacity as first-class - [ ] Migration notes and a `0.1 โ†’ 0.2` checklist - [ ] Backwards-compat fixtures: every 0.1 example still parses (C15) #### โšช Task-level dependency graph > status: todo ยท progress: 0% ยท owner: @pv ยท id: task-graph ยท milestone: M6 ยท estimate: M ยท priority: P3 ยท depends: spec-v02, renderer-model **Outcome:** tasks become first-class graph citizens (today they are leaf data โ€” see [MODEL.md](MODEL.md)). - [ ] Stable ids on tasks that participate in `depends:` - [ ] `blocks` / `blocked-by` symmetry alongside `depends` - [ ] Task-level owner / estimate / priority in the model - [ ] Validate task-level cycles and cross-node task deps - [ ] Surface task edges in the dependency view #### โšช Multi-file manifest > status: todo ยท progress: 0% ยท owner: @pv ยท id: multi-file-manifest ยท milestone: M6 ยท estimate: M ยท priority: P3 ยท depends: spec-v02 **Outcome:** a roadmap split across many files resolves as one graph, losslessly ([SPEC ยง7](SPEC.md), formalised). - [ ] A manifest listing member files and their parent links - [ ] Resolve ids, `depends:`, and rollups across the whole set - [ ] Detect orphaned / dangling split pointers as errors - [ ] Reassemble (inline) and explode (extract) as tooling operations #### โšช Published JSON Schema > status: todo ยท progress: 0% ยท owner: @pv ยท id: json-schema ยท milestone: M6 ยท estimate: S ยท priority: P3 ยท depends: renderer-model **Outcome:** the model ([MODEL.md](MODEL.md)) gets a machine-checkable schema consumers can validate against. - [ ] JSON Schema for `CruxModel` / `CruxNodeModel` / `CruxTaskModel` - [ ] Versioned and published alongside the model - [ ] `crux validate --schema` checks emitted JSON against it - [ ] Generated types stay in sync with the schema #### โšช Conformance suite & levels > status: todo ยท progress: 0% ยท owner: @pv ยท id: conformance-suite ยท milestone: M6 ยท estimate: M ยท priority: P3 ยท depends: json-schema ยท constraints: C15 **Outcome:** "CRUX-compatible" is something a renderer or agent can *pass*, not just claim. - [ ] A golden corpus of CRUX files + their expected models - [ ] Conformance levels: parse ยท render ยท edit ยท agent-write - [ ] Agent-write level: hash-checking, id preservation, gate-respecting tests - [ ] A runner any implementation (renderer *or* agent) can point at itself - [ ] A pass/fail report and a compatibility badge (for tools and agents) #### โšช Profiles > status: todo ยท progress: 0% ยท owner: @pv ยท id: profiles ยท milestone: M6 ยท estimate: S ยท priority: P3 ยท depends: spec-v02 **Outcome:** opinionated subsets for common uses without forking the grammar. - [ ] A "strategy-only" profile (no planning fields) - [ ] A "backlog" profile (planning fields required) - [ ] An "agent" profile (ids + content hashes required for safe writes) - [ ] A validator flag to check a file against a named profile --- ## โšช Agentic Substrate > status: todo ยท progress: 0% ยท owner: @pv ยท id: agentic ยท horizon: later The AI-native bet, taken seriously: CRUX as the shared, trustworthy **state layer** a fleet of agents and their humans converge on โ€” read it, reason about it, and **write it, autonomously where trusted**. Beyond the M5 assistant: the skills, instructions, and protocol that make any agent CRUX-fluent. Writes aren't human-gated by default โ€” they're validated, hashed, audited, and reversible (**C14**); the $50 AI tier. ### โšช Agents read & write CRUX safely > status: todo ยท progress: 0% ยท owner: @pv ยท id: agent-layer ยท milestone: M7 ยท priority: P3 ยท horizon: later ยท constraints: C14 #### โšช MCP server for CRUX > status: todo ยท progress: 0% ยท owner: @pv ยท id: mcp-server ยท milestone: M7 ยท estimate: L ยท priority: P3 ยท depends: ai-endpoint ยท constraints: C14 **Outcome:** any MCP-capable agent can read a roadmap and write to it through tools. - [ ] Read tools: fetch model, query nodes, diff revisions - [ ] Write tools that apply validated changes (or return a proposed diff when approval is on) - [ ] Resource discovery for `/roadmap.crux.md` and `.json` - [ ] Auth + scoping per roadmap and per token - [ ] Ship as an installable MCP server others can run #### โšช Typed write-protocol > status: todo ยท progress: 0% ยท owner: @pv ยท id: write-protocol ยท milestone: M7 ยท estimate: M ยท priority: P3 ยท depends: ai-endpoint, validation-gate ยท constraints: C14, C2 **Outcome:** a documented, safe loop for any agent: fetch โ†’ diff โ†’ validate โ†’ apply (autonomously when trusted, else propose for approval) โ†’ audit. - [ ] Content-hash / `If-Match` on every write (reject on drift) - [ ] Patches expressed against node ids and source ranges, not blind text - [ ] Server-side validation gate identical to human saves - [ ] Every change carries rationale and a reversible undo - [ ] Append-only audit of who/what changed, applied or proposed - [ ] Approval is an optional policy per roadmap/token (C14), not a built-in step #### โšช Agent skills & instructions > status: todo ยท progress: 0% ยท owner: @pv ยท id: agent-sdk ยท milestone: M7 ยท estimate: M ยท priority: P3 ยท depends: mcp-server, write-protocol, ai-skill **Outcome:** making an agent CRUX-fluent is a matter of *skills and instructions*, not a code SDK โ€” package the knowledge, not a client library (extends `ai-skill`). - [ ] A packaged CRUX skill agents load: grammar, hierarchy, rollups, the write-protocol - [ ] Clear tool/instruction descriptions for the MCP read/write tools - [ ] Playbooks for common agents (status-updater, triager, planner, importer) - [ ] Rules to preserve ids, prose, comments, and unknown meta on every edit - [ ] A reference agent: keep *this* roadmap current from linked PRs #### โšช Autonomous maintainer > status: todo ยท progress: 0% ยท owner: @pv ยท id: auto-maintainer ยท milestone: M7 ยท estimate: L ยท priority: P3 ยท depends: agent-sdk, ai-assistant ยท constraints: C14 **Outcome:** a scheduled agent keeps the roadmap honest โ€” applying directly when trusted, proposing when policy asks. - [ ] Detect drift: stale due dates, rollup mismatch, dead deps - [ ] Draft and apply status/progress updates from linked PRs and issues - [ ] Run on a schedule; apply validated changes autonomously, or queue them for review (C14) - [ ] Every run is hashed, audited, and reversible โ€” autonomy without losing the trail (C14) --- ## โšช Multiplayer & Collaboration > status: todo ยท progress: 0% ยท owner: @pv ยท id: collab ยท horizon: later The $3 tier grows from "host my file" into "maintain it together": real-time presence, comments, and review โ€” while the Markdown stays the one source of truth (**C2**) and nobody is ever locked in (**C16**). ### โšช Maintain a roadmap together > status: todo ยท progress: 0% ยท owner: @pv ยท id: teamwork ยท milestone: M8 ยท priority: P3 ยท horizon: later ยท constraints: C2 #### โšช Real-time co-editing > status: todo ยท progress: 0% ยท owner: @pv ยท id: realtime-coedit ยท milestone: M8 ยท estimate: L ยท priority: P3 ยท depends: md-editor, storage ยท constraints: C2 - [ ] Live presence and cursors in the editor - [ ] Conflict-free sync that still serialises to canonical Markdown - [ ] Per-node soft locks to avoid clobbering - [ ] Offline edits reconcile via the `merge` engine #### โšช Node comments & threads > status: todo ยท progress: 0% ยท owner: @pv ยท id: node-comments ยท milestone: M8 ยท estimate: M ยท priority: P3 ยท depends: hosted-publish - [ ] Comment on any node or task - [ ] Threaded replies and resolve/unresolve - [ ] Comments live *beside* the roadmap, never inside the canonical `.md` (C2) - [ ] Reactions for lightweight signal #### โšช Review & approval > status: todo ยท progress: 0% ยท owner: @pv ยท id: review-approval ยท milestone: M8 ยท estimate: M ยท priority: P3 ยท depends: storage, validation-gate - [ ] Propose changes as a reviewable set (a "roadmap PR") - [ ] Require approval before publishing to the canonical file - [ ] Inline diff with the validation gate enforced - [ ] Approvals recorded in the activity feed #### โšช Mentions & notifications > status: todo ยท progress: 0% ยท owner: @pv ยท id: notifications ยท milestone: M8 ยท estimate: S ยท priority: P3 ยท depends: accounts - [ ] @mention owners on nodes and in comments - [ ] Email / in-app / Slack delivery (reuses `slack-notify`) - [ ] Per-workspace and per-roadmap notification settings - [ ] Digest vs real-time choice #### โšช Activity feed > status: todo ยท progress: 0% ยท owner: @pv ยท id: activity-feed ยท milestone: M8 ยท estimate: S ยท priority: P3 ยท depends: storage - [ ] A chronological feed of changes per roadmap - [ ] Filter by author, node, and type of change - [ ] Link every entry back to the revision and source range #### โšช Sharing & granular permissions > status: todo ยท progress: 0% ยท owner: @pv ยท id: sharing-permissions ยท milestone: M8 ยท estimate: M ยท priority: P3 ยท depends: accounts, hosted-publish ยท constraints: C16 - [ ] Share links with viewer / commenter / editor scopes - [ ] Per-branch visibility (public roadmap, private branches) - [ ] Guest access without a full account - [ ] Revoke and audit access (C16) --- ## โšช Ecosystem & Open Standard > status: todo ยท progress: 0% ยท owner: @pv ยท id: ecosystem ยท horizon: later Make `/roadmap` a convention with a community around it โ€” like `sitemap.xml`, `robots.txt`, or `llms.txt`. Win by ubiquity: many products expose a CRUX roadmap, more than one tool renders it, and the format is governed in the open (**C15**). ### โšช A standard others can adopt & extend > status: todo ยท progress: 0% ยท owner: @pv ยท id: standard-body ยท milestone: M9 ยท priority: P3 ยท horizon: later ยท constraints: C15 #### โšช Public roadmap registry > status: todo ยท progress: 0% ยท owner: @pv ยท id: registry ยท milestone: M9 ยท estimate: M ยท priority: P3 ยท depends: route-contract, hosted-publish **Outcome:** a directory of products exposing `/roadmap` โ€” discovery, and proof the standard is real. - [ ] Submit / crawl products that publish a CRUX `/roadmap` - [ ] Validate and badge listed roadmaps - [ ] Browse and search the registry - [ ] An opt-in "ping" so a site can announce its roadmap #### โšช Status badge & embeds > status: todo ยท progress: 0% ยท owner: @pv ยท id: embed-badge ยท milestone: M9 ยท estimate: S ยท priority: P3 ยท depends: renderer-package **Outcome:** a roadmap advertises itself anywhere a README or site can render an image. - [ ] A shields-style status/progress badge from any CRUX file - [ ] An embeddable mini-tree widget - [ ] Copy-paste snippets for GitHub READMEs and docs sites - [ ] Badges reflect live validation + rollup #### โšช Editor extensions > status: todo ยท progress: 0% ยท owner: @pv ยท id: editor-extensions ยท milestone: M9 ยท estimate: M ยท priority: P3 ยท depends: renderer-package, cli **Outcome:** CRUX previews live where people actually write it. - [ ] VS Code extension: live tree preview + validation - [ ] Obsidian plugin: render CRUX notes as a tree - [ ] Inline lints from the validator as you type - [ ] An "open /roadmap preview" command #### โšช Second independent renderer > status: todo ยท progress: 0% ยท owner: @pv ยท id: second-renderer ยท milestone: M9 ยท estimate: L ยท priority: P3 ยท depends: conformance-suite, renderer-model **Outcome:** the contract is real because more than one implementation honours it. - [ ] A second renderer on a different stack, from the same model - [ ] Passes the conformance suite - [ ] Documents any gaps as spec feedback #### โšช Themes & visual skins > status: todo ยท progress: 0% ยท owner: @pv ยท id: themes ยท milestone: M9 ยท estimate: S ยท priority: P3 ยท depends: visual-language **Outcome:** the tree can look like the brand around it without forking the grammar. - [ ] A theming contract over the visual language - [ ] Built-in themes (light / dark / high-contrast / print) - [ ] Custom theme tokens per hosted roadmap #### โšช Format governance > status: todo ยท progress: 0% ยท owner: @pv ยท id: governance ยท milestone: M9 ยท estimate: S ยท priority: P3 ยท depends: spec-v02 ยท constraints: C15 **Outcome:** the format evolves in the open, predictably. - [ ] A public changelog and versioning policy (C15) - [ ] An RFC/proposal process for new fields - [ ] A compatibility promise and deprecation policy - [ ] A reference test corpus the community can extend --- ## โšช Insight & Portfolio > status: todo ยท progress: 0% ยท owner: @pv ยท id: insight ยท horizon: later From one roadmap to many. Cross-roadmap rollups, derived analytics, and an executive view โ€” all *derived and regenerable* ([SPEC ยง9](SPEC.md)), never a second source of truth competing with the Markdown. ### โšช See across many roadmaps > status: todo ยท progress: 0% ยท owner: @pv ยท id: portfolio-view ยท milestone: M10 ยท priority: P3 ยท horizon: later #### โšช Portfolio of roadmaps > status: todo ยท progress: 0% ยท owner: @pv ยท id: portfolio ยท milestone: M10 ยท estimate: L ยท priority: P3 ยท depends: storage, hosted-publish **Outcome:** several CRUX files roll up under one org north star. - [ ] Group roadmaps into a portfolio / workspace - [ ] An org-level north star over many roadmaps - [ ] Roll up status / progress / health across files - [ ] Drill from the portfolio into any single roadmap #### โšช Derived analytics > status: todo ยท progress: 0% ยท owner: @pv ยท id: analytics ยท milestone: M10 ยท estimate: M ยท priority: P3 ยท depends: storage **Outcome:** the numbers a CRUX file already implies, surfaced over time. - [ ] Velocity and burn-up from `done` dates - [ ] Risk heatmap from status / health / overdue - [ ] Aging report for stale and blocked nodes - [ ] Every view derived from the model, never hand-maintained #### โšช Cross-roadmap dependency graph > status: todo ยท progress: 0% ยท owner: @pv ยท id: cross-roadmap-graph ยท milestone: M10 ยท estimate: M ยท priority: P3 ยท depends: portfolio, task-graph **Outcome:** dependencies that cross file / team boundaries become visible. - [ ] Resolve `depends:` across roadmaps in a portfolio - [ ] Flag cross-team blockers and cycles - [ ] A portfolio-wide dependency view #### โšช Executive rollup > status: todo ยท progress: 0% ยท owner: @pv ยท id: exec-rollup ยท milestone: M10 ยท estimate: S ยท priority: P3 ยท depends: portfolio, analytics **Outcome:** a clean now/next/later + health summary for people who won't open the tree. - [ ] Auto-generated exec now / next / later board - [ ] One-page health summary per portfolio - [ ] Export to PDF / slide / Markdown - [ ] Scheduled snapshot delivery --- ## โšช Later / Parking > status: todo ยท id: later ยท horizon: later Not committed. Captured so it is not lost. ### โšช Desktop app > status: todo ยท horizon: later ยท id: desktop - [ ] Reassess if users strongly prefer local-first roadmap editing ### โšช Enterprise governance > status: todo ยท horizon: later ยท id: enterprise-governance - [ ] Approval workflows, audit log, SSO/SAML, data-residency controls ### โšช Native mobile & offline PWA > status: todo ยท horizon: later ยท id: mobile-pwa - [ ] Reassess once hosted roadmaps see real mobile traffic ### โšช Templates & agents marketplace > status: todo ยท horizon: later ยท id: marketplace - [ ] Reassess if a registry/template community forms โ€” paid templates, themes, and packaged agents ### โšซ Proprietary roadmap format > status: dropped ยท id: proprietary-format Dropped: CRUX Studio should enhance CRUX Markdown, not replace it with a locked-in format. --- ## ๐Ÿ“Š Derived views Generated from the data above โ€” regenerate after edits; do not hand-maintain.
Milestone sequence (solo, self-paced) ```mermaid flowchart LR M0["M0 ยท Live walking skeleton
continuously deployed"] --> M1["M1 ยท Navigable demo
& explainer homepage"] M1 --> M2["M2 ยท /roadmap standard
+ adoption docs"] M2 --> M3["M3 ยท SaaS foundation
& pricing site"] M3 --> M4["M4 ยท Safe editing,
demoed on the site"] M4 --> M5["M5 ยท Intelligence,
showcased live"] M2 -.-> M6["M6 ยท Format v0.2
& conformance"] M5 -.-> M7["M7 ยท Agentic
substrate"] M3 -.-> M8["M8 ยท Multiplayer
& collaboration"] M6 -.-> M9["M9 ยท Ecosystem
& open standard"] M2 -.-> M9 M3 -.-> M10["M10 ยท Insight
& portfolio"] M5 -.-> M10 M6 -.-> M7 ``` Solid = committed M0โ†’M5 spine. Dotted = exploratory horizons (M6โ€“M10), branching off M2/M3/M5 in parallel; order provisional.
Critical path to MVP (M0) โ€” engine + site + pipeline, rejoining at the live deploy ```mermaid flowchart LR parser["parser-model ยท M (done)"] --> tree["tree-render ยท L (done)"] tree --> route["roadmap-route ยท S (done)"] route --> cd["cd-pipeline ยท S (done)"] domain["domain ยท S (done)"] --> cd domain --> shell["site-shell ยท S (done)"] shell --> home["homepage ยท M (done)"] domain --> home cd --> deploy["dogfood-deploy ยท S (done)"] home --> deploy deploy --> live(["cruxroadmap.com live
& auto-deploying"]) ```
Dependencies (full) ```mermaid graph LR parser-model --> tree-render tree-render --> roadmap-route --> cd-pipeline --> dogfood-deploy roadmap-route --> dogfood-deploy domain --> cd-pipeline domain --> site-shell --> dogfood-deploy domain --> dogfood-deploy domain --> homepage site-shell --> homepage tree-render --> expansion --> node-cards node-cards --> search-filter node-cards --> quality-signals parser-model --> quality-signals route-contract --> renderer-model parser-model --> renderer-model renderer-model --> renderer-package tree-render --> renderer-package expansion --> renderer-package tree-render --> local-workspace renderer-package --> adoption --> site-docs parser-model --> file-lifecycle --> storage renderer-package --> hosted-publish accounts --> hosted-publish storage --> hosted-publish hosted-publish --> ai-endpoint storage --> ai-endpoint renderer-model --> ai-endpoint accounts --> billing hosted-publish --> billing --> site-pricing node-cards --> visual-editing --> md-editor --> validation-gate parser-model --> validation-gate quality-signals --> ai-assistant md-editor --> ai-assistant ai-endpoint --> ai-assistant ai-endpoint --> ai-skill md-editor --> ai-skill storage --> github-sync ai-assistant --> linear-sync ai-assistant --> site-ai-showcase node-cards --> derived-views search-filter --> share-export renderer-package --> cli hosted-publish --> public-api storage --> public-api hosted-publish --> embed-hosted local-workspace --> templates md-editor --> merge storage --> merge validation-gate --> ai-assistant ai-endpoint --> roadmap-chat ai-assistant --> roadmap-chat storage --> linear-sync ai-assistant --> slack-notify %% --- exploratory horizons (M6โ€“M10) --- spec-v02 --> task-graph renderer-model --> task-graph spec-v02 --> multi-file-manifest renderer-model --> json-schema json-schema --> conformance-suite spec-v02 --> profiles ai-endpoint --> mcp-server ai-endpoint --> write-protocol validation-gate --> write-protocol mcp-server --> agent-sdk write-protocol --> agent-sdk ai-skill --> agent-sdk agent-sdk --> auto-maintainer ai-assistant --> auto-maintainer md-editor --> realtime-coedit storage --> realtime-coedit hosted-publish --> node-comments storage --> review-approval validation-gate --> review-approval accounts --> notifications storage --> activity-feed accounts --> sharing-permissions hosted-publish --> sharing-permissions route-contract --> registry hosted-publish --> registry renderer-package --> embed-badge renderer-package --> editor-extensions cli --> editor-extensions conformance-suite --> second-renderer renderer-model --> second-renderer visual-language --> themes spec-v02 --> governance storage --> portfolio hosted-publish --> portfolio storage --> analytics portfolio --> cross-roadmap-graph task-graph --> cross-roadmap-graph portfolio --> exec-rollup analytics --> exec-rollup ```
--- ## ๐Ÿค Keeping this file true 1. Update the meta line when reality changes: status, progress, dates, owner, health. 2. `id`s are forever โ€” rename titles freely, never reuse or change an `id`. 3. One north star per file. 4. Leaf work is a checkbox; if it cannot be ticked, it is a project, not a task. 5. A slice's checkboxes are its definition of done; recompute `progress:` from them on edit. 6. Every `milestone:` must be declared in the Milestones section; keep slices in dependency order. 7. Constraints are invariants โ€” declare them in the Constraints section and reference with `constraints:`; never turn one into a task. 8. Derived views are disposable; regenerate them from the canonical roadmap data. Validate with `bun bin/crux.ts validate CRUX.md` ยท grammar in [SPEC.md](SPEC.md)