Plans

You ship fast.
Your plans don't keep up.

Plans is a lightweight planning convention for AI-assisted projects. Markdown files, one command to set up, your AI assistant reads it automatically.

Claude Code Antigravity Cursor Any AI assistant

The problem

A few weeks of AI velocity and you can't answer "what's in flight?"

Dozens of *_PLAN.md files at the repo root. Active, stale, and shipped all mixed together.
Every new AI session starts with 15 minutes of re-explaining context you shouldn't need to re-explain.
Plans quietly go stale. Code ships. The plan still says "Not started".
You don't have a clear picture. Neither does your AI.

repo rootnobody knows what's current

FEATURE_A_PLAN.md
FEATURE_B_PLAN.md (stale?)
FEATURE_C_PLAN.md (shipped?)
OLD_IDEA_PLAN.md (abandoned?)
NEW_PLAN.md (conflicts with B?)

Nobody knows.

Is this for you?

Built for solo devs and small teams moving fast with AI.

Good fit

Solo or small team (1 to 3 people)
3 or more features committed and in flight at once
You're losing track of what's done vs what's active
You re-explain context to your AI every session
You want visibility without a PM tool

Not the right fit

Single-feature scope or one-off scripts
Team of 5+: use Linear, Jira, or similar
You need a git-tracked audit trail
Open-source project with public issue tracker

Not a PM tool replacement. Operates at plan and phase level, not task level.

The outcome

Monday morning. One file. You know exactly where you stand.

STATUS.md

# MyProject: Project Status
*Last updated: 2026-05-06*

<!-- AUTO-GENERATED -->

## In flight

| Initiative        | Status      | Progress    | ETA        |
| ----------------- | ----------- | ----------- | ---------- |
| Dark Mode         | In progress | Phase 2/3   | 2026-05-12 |
| Search Index      | In progress | Phase 1/2   | 2026-05-09 |

## Up next

| Initiative        | Depends on  | Effort  |
| ----------------- | ----------- | ------- |
| Theme Picker      | Dark Mode   | 1 week  |
| Search autocomplete | Search index | 1 week |

<!-- END AUTO-GENERATED -->

## Recently shipped

| What               | Shipped    |
| ------------------ | ---------- |
| First-run onboarding | 2026-04-23 |

## Backlog
- Export to CSV
- Keyboard shortcuts

Open live demo (rendered)

You open this instead of ten files

In flight, up next, shipped, backlog. One read. Two minutes. You know what's happening.

Your AI reads it at session start

No re-explaining. It already knows what's in flight and which plan to update when you ship.

The three auto-generated sections

In flight, Up next, and Recently shipped are regenerated by /plans sync. You never update them manually.

Setup

Two commands. Under two minutes. Nothing to maintain.

curl -sSL https://raw.githubusercontent.com/yrangana/Plans/main/install.sh | bash
plans-init /path/to/your/project

Install once

Clones the repo, symlinks plans-init and plans-update to ~/.local/bin/.

Bootstrap your project

Scaffolds plans/, adds it to .git/info/exclude, detects your AI instruction file and offers to append the planning snippet. Nothing happens without confirmation.

Run /plans new

Five questions. Writes your first plan file with correct structure. Add a row to STATUS.md. You're done.

Stay current with plans-update

Pulls dashboard improvements and skill updates without touching your data. Backups go to .bak.

The plan file

One markdown file per feature. Two layers that must agree.

Frontmatter is machine-readable. The status banner is human-readable. If they disagree, frontmatter wins. Run /plans sync to catch disagreements automatically.

Frontmatter8 fields, written once, updated as work progresses

---
status: active
priority: P1
owner: yash
type: feature
depends_on: [AUTH_PLAN]
blocks: [DASHBOARD_PLAN]
last_updated: 2026-05-06
in_flight: true
---

Set in_flight: true when work starts. This drives the dashboard "In flight" vs "Up next" split.

Status bannerthe second heading in every plan

## Status

- **Overall:** In progress, Phase 2 of 3
- **Phase 0 (Design):** Done (2026-04-28)
- **Phase 1 (Backend):** Done (2026-05-01)
- **Phase 2 (Frontend):** In progress
- **Phase 3 (Tests):** Not started

**Next action:** Wire up the API client.
**Last updated:** 2026-05-06

/plans new

Never write a plan from scratch. Five questions, one correct file.

A guided command installed by plans-init. It asks five questions and writes a correctly structured plan file — correct frontmatter, correct banner template, correct filename.

Five questions

Plan name (becomes SCREAMING_SNAKE_CASE.md)

Type: feature, bug, research, spike, or plan

Priority: P0 (critical) to P3 (nice to have)

Dependencies: what this waits on, what it blocks

Owner: your username or name

One correctly structured file

Created plans/active/AUTH_REFACTOR.md

Next steps:
  1. Fill in Context, Goals, and Phases
  2. Add a row to STATUS.md "Up next":
     | AUTH_REFACTOR | feature | P1 | TBD |
  3. Set in_flight: true when work starts

No blank-page problem. No format errors. /plans sync won't flag it immediately.

/plans sync

Plans drift from reality. /plans sync catches it before it compounds.

Run it weekly. It reads all plan frontmatter, runs git log since last sync, finds every discrepancy, regenerates derived files, and shows you a diff. You confirm before anything is written.

What it catches

Shipped code, plan still "Not started"
Active plan, no commits in 14+ days
Frontmatter and status banner disagree
STATUS.md row with no underlying plan file
Dependency edges that don't reciprocate

What it regenerates

plans.json rebuilt from all plan frontmatter
STATUS.md In flight and Up next tables

Review and confirm:

Apply these changes? (y/n/select)
  y      apply all
  n      apply nothing
  select choose per file

15-minute manual audit becomes a 2-minute review.

Visual layer

roadmap.html: a shareable dashboard that never needs a server.

A static HTML file included in plans/. Reads plans.json directly. Open it with python -m http.server 8080 and share the URL with anyone.

Gantt chart

Interactive timeline. Progress bars per phase. Shipped items in green. Today button auto-scrolls to the current date.

Dependency graph

Which plans block which. Zoom, pan, reset. Visualises blockers before they become surprises.

Plan cards

Filter by status. Phase breakdown per plan. Next action shown inline. No markdown knowledge needed.

Kept current automatically: /plans sync regenerates plans.json, the dashboard reads it fresh on every open.

AI integration

Your AI reads the same files. Sessions start in two messages.

plans-init appends a snippet to your CLAUDE.md, AGENTS.md, or .cursorrules. The AI reads it at session start. No re-explaining required.

What goes in CLAUDE.md

Read plans/STATUS.md at session start.
Active plans in plans/active/,
completed in plans/shipped/,
replaced in plans/superseded/.

Two-source rule: frontmatter and banner
must agree. Frontmatter wins on conflict.

Lifecycle:
- New idea: backlog bullet only
- Committed: run /plans new
- Work starts: set in_flight: true
- Done: mv active/ to shipped/
- Replaced: mv active/ to superseded/

Audit drift: /plans sync
Create a plan: /plans new

The AI now knows

Where to look first every session
What each directory means and when to use it
How to create a plan with correct structure
How and when to move files through the lifecycle

Works across platforms

plans/ is pure markdown and JSON. Install skill to .claude/skills/ for Claude Code, .agents/skills/ for Antigravity. The data never changes.