claude-code/plans/README.md

Plans

Implementation plans for features, enhancements, and investigations.

Structure

plans/
├── index.json              # Status registry (source of truth)
├── README.md               # This file
└── *.md                    # Individual plan files

Plan Naming

• Dated plans: YYYY-MM-DD-descriptive-name.md (design docs)
• Generated names: adjective-verb-scientist.md (brainstorming outputs)

Status Registry (index.json)

Central tracking for all plans:

{
  "plan-name": {
    "title": "Human readable title",
    "status": "pending|implemented|partial|abandoned|superseded",
    "created": "YYYY-MM-DD",
    "implemented": "YYYY-MM-DD",
    "category": "feature|enhancement|bugfix|diagnostic|design",
    "notes": "Optional notes"
  }
}

Status Values

Status	Meaning
pending	Not yet implemented
implemented	Fully implemented
partial	Partially implemented
abandoned	Decided not to implement
superseded	Replaced by another plan

Categories

Category	Meaning
feature	New capability
enhancement	Improve existing feature
bugfix	Fix an issue
diagnostic	One-time investigation
design	Design document for reference

Querying Plans

# List pending plans
jq -r '.plans | to_entries[] | select(.value.status == "pending") | .key' index.json

# List by category
jq '.plans | to_entries[] | select(.value.category == "feature")' index.json

# Count by status
jq '.plans | to_entries | group_by(.value.status) | map({status: .[0].value.status, count: length})' index.json

Workflow

1. Create plan: Write plans/plan-name.md
2. Register: Add entry to index.json with status: "pending"
3. Implement: Execute the plan
4. Update: Set status: "implemented" and add implemented date