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
/plugin marketplace add yrangana/Plans
/plans:plans init
Project rules load automatically via a session hook, no CLAUDE.md edit
Git-excluded by default, plans stay local
In Claude Code, run /plugin marketplace add yrangana/Plans, then /plugin install plans@yrangana-plans.
Run /plans:plans init. Creates plans/ and keeps it out of git by default.
Run npx serve . in your project root, then open localhost:3000/plans/roadmap.html.
Type /plans:plans new in Claude Code.
npx skills add, then /plans init
/plans init offers to append a planning section to CLAUDE.md, AGENTS.md, or .cursorrules
Git-excluded by default, plans stay local
Install the skill: npx skills add yrangana/Plans (about 70 assistants).
In your assistant, run /plans init. It scaffolds plans/, handles git exclusion, and offers the rules snippet.
Open plans/roadmap.html from any static server. Update later with npx skills update.
Replace the example plan in plans/active/ with a real one, or run /plans new in your AI assistant.
Prefer plain scripts? The CLI path is still supported.
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