A PLANNING CONVENTION
A markdown convention for solo devs and small teams. One source of truth for what's active, shipped, and next.
AI assistants (Claude Code, Cursor, Antigravity) read it natively, as a bonus.
No accounts. No SaaS. Plain files in your repo.
The real problem
It wasn't the AI. I didn't have a picture either.
Before
After
plans/ ├── active/ │ ├── SEARCH_INDEX.md │ ├── DARK_MODE.md │ └── MOBILE_RESPONSIVE.md ├── shipped/ │ ├── ONBOARDING.md │ └── AUTH_REWRITE.md ├── superseded/ ├── STATUS.md ├── plans.json └── roadmap.html
THE SYSTEM
One file per feature. One file that answers "where are we?".
One static dashboard for everyone else. Plain markdown and JSON — no database, no account, no daemon.
01
plans/active/*.md
YAML frontmatter machines can parse. A status banner humans can read. Both must agree — frontmatter wins on conflict.
--- status: active priority: P1 owner: alex type: feature depends_on: [] blocks: [THEME_PICKER] last_updated: 2026-05-06 in_flight: true --- ## Dark mode # Phase 2 of 3. Token layer done. # Next: component audit.
02
plans/STATUS.md
Open it in the morning. In flight, up next, recently shipped — one file answers "where are we?" for you and your AI.
| Initiative | Phase | State |
|---|---|---|
| Search index | 1 of 2 | in flight |
| Dark mode | 2 of 3 | in flight |
| Mobile | 0 of 2 | up next |
| Onboarding | 1 of 1 | shipped |
03
plans/roadmap.html
A static file that reads plans.json. Gantt timeline, blocking-chain graph, filterable list. No server.
LIVE DASHBOARD
Real plans.json from the demo project, rendered by roadmap.html.
Gantt timeline, blocking-chain dependencies, filterable plan list.
INSTALL
~/.local/share/plans — re-run any time to update
Run plans-init in any project to bootstrap
Auto-detects CLAUDE.md, AGENTS.md, .cursorrules
Git-excluded by default — plans stay local
curl -sSL https://raw.githubusercontent.com/yrangana/Plans/main/install.sh | bash
One curl. Re-run any time to update the system itself. Installs to ~/.local/share/plans.
Run plans-init /path/to/project. Creates plans/, excludes it from git, wires up your assistant.
Run npx serve . in your project root, then open localhost:3000/plans/roadmap.html.
Replace the example plan with a real one, or type /plans new in your AI assistant.
PLATFORM COMPATIBILITY
The plans/ directory is identical across every platform. Only the instruction file your assistant reads changes. Switch tools without rewriting a single plan.
active/ DARK_MODE.md SEARCH_INDEX.md shipped/ ONBOARDING.md STATUS.md plans.json roadmap.html
Same directory.
Every project.
CLAUDE.md
AGENTS.md
.cursorrules
.windsurfrules
manual · no config
What changes vs what stays
Always the same
Per assistant