Plans CLAUDE.md

CLAUDE.md, plans repo

This file is for AI assistants (Claude Code, Antigravity, Cursor) and human contributors working on the plans repo itself, not for projects that adopt the system.

Maintainers may keep additional personal context in a CLAUDE.local.md next to this file. That file is gitignored and overrides nothing here, it just adds local conveniences (paths, preferences) on top.

---

What this repo is

A shareable spec-driven planning convention. The repo contains:

• Documentation explaining the system (README.md, docs/)
• A drop-in template users copy into their own projects, bundled inside the skill (template/skills/plans/template/plans/)
• A bootstrap script that automates the copy (scripts/init.sh)
• A Claude Code plugin (.claude-plugin/) that delivers the /plans skill as the primary adoption path; the scripts remain the fallback for other assistants
• A static site rendered by GitHub Pages from web/ (landing page, live roadmap demo, status demo, slides, docs)
• Static assets used by the README (examples/demo.svg, screenshots)

This repo does not itself adopt the planning convention by default. It's the system, not a user of the system. (See "Using the system on this repo" below if you change your mind.)

---

Repo structure

plans/
├── README.md                    # Top-level pitch + quick start
├── LICENSE                      # MIT
├── CLAUDE.md                    # This file
├── docs/                        # Standalone guide for adopters
│   ├── reference.md             # Full technical spec
│   ├── blog-post.md             # Narrative explanation
│   └── presentation.html        # Slideshow
├── template/                    # What users copy into their projects
│   └── skills/
│       └── plans/               # The /plans skill (self-sufficient package)
│           ├── SKILL.md
│           ├── references/      # Per-mode logic loaded on demand
│           └── template/        # Bundled project template
│               ├── CLAUDE.md.snippet   # Section adopters paste into their CLAUDE.md (skills/plans/template)
│               └── plans/              # The directory adopters drop into their repo
│                   ├── README.md       # Onboarding for adopters
│                   ├── STATUS.md       # Empty front-door template
│                   ├── plans.json      # Empty starter ({ project, plans } shape; see docs/reference.md)
│                   ├── roadmap.html    # Interactive dashboard
│                   ├── active/         # With EXAMPLE_PLAN.md showing the format
│                   ├── shipped/
│                   └── superseded/
├── scripts/
│   ├── init.sh                  # Bootstraps plans/ and installs skill in a target project
│   └── update.sh                # Updates system files (roadmap.html, README.md, skill)
├── .claude-plugin/              # Claude Code plugin manifest, delivers /plans as the primary path
├── web/                         # GitHub Pages site (deployed by .github/workflows)
│   ├── index.html               # Landing page
│   ├── roadmap.html             # Live roadmap demo (inline data)
│   ├── status.html              # Live STATUS.md demo
│   ├── presentation.html        # Slides
│   └── docs.html                # Browsable docs
└── examples/                    # Static assets for the README
    ├── demo.svg                 # Animated terminal demo
    ├── screenshot-dashboard.png
    └── screenshot-status.png