plans

name	plans
disable-model-invocation	true
argument-hint	[rebuild | next | details | work N [auto] [every SCHEDULE] [now]] | stop | next-run
description	Plan dashboard and batch executor. View plan status, find the next ready plan, or work through plans automatically. Usage: /plans [rebuild | next | work N [auto] [every SCHEDULE]]

/plans [rebuild | next | details | work N] — Plan Dashboard & Executor

Maintains plans/PLAN_INDEX.md — a structured index of all plan files with their classification, status, and priority. Also supports batch execution of ready plans.

Modes:

• bare /plans — display the current index (highlights top-priority ready plan)
• rebuild /plans rebuild — scan all plans, classify, regenerate
• next /plans next — show the highest-priority ready-to-run plan with command
• details /plans details — show every plan with a one-line description
• work /plans work N [auto] — batch-execute next N ready plans
• stop /plans stop — cancel scheduled runs
• next-run /plans next-run — when does the next scheduled run fire?

Mode: Show (bare /plans)

1. Read plans/PLAN_INDEX.md

2. If the file does not exist, auto-run rebuild (Mode: Rebuild below) to create it, then display the newly generated index.

3. If the file exists, display a actionable dashboard — not a one-line summary. Show the actual plan names and status so the user can decide what to work on:

   Plans: 5 ready, 2 in progress, 10 complete
   
   Ready to Run:
     RENDERING_GAPS_PLAN.md           9 gaps     High
     GENETICS_PLAN.md                 4 phases   Medium
     AQUARIUM_FEATURES_PLAN.md        5 phases   Medium
   
   In Progress:
     BEHAVIOR_PLAN.md                 Phase 4b   4/8 done
     PERFORMANCE_PLAN.md              Phase 1    1/3 done
   
   Needs Review: 3 plans (old format, status ambiguous)
   
   Next: /run-plan plans/RENDERING_GAPS_PLAN.md
   

   Show Ready and In Progress tables with plan names, phase info, and priority. Collapse Complete/Reference into counts. Highlight the top-priority ready plan with a suggested /run-plan command.

4. If the file is older than 24 hours (check mtime), append:

   Warning: Index is older than 24 hours. Run /plans rebuild to refresh.

5. Exit.

Mode: Details (/plans details)

Show every plan with a one-line description, grouped by status. Useful when you have many plans and can't remember what each one is about.

1. Read plans/PLAN_INDEX.md (auto-rebuild if missing).

2. For each plan in the index, read its ## Overview section (first paragraph only) and extract a one-line blurb.

3. Display grouped by status (Ready, In Progress, Complete), with the blurb after each plan name:

   Ready to Run:
     RENDERING_GAPS_PLAN.md (5 phases, Medium)
       Fix rendering gaps: missing animations, stale sprite counts, broken effects
   
     GENETICS_EXPANSION_PLAN.md (4 phases, Medium)
       Add 15 new heritable traits via phased genetics system updates
   
   In Progress:
     PERFORMANCE_PLAN.md (13 phases, 7/13 done)
       Systematic frame rate improvements with benchmark reference tests
   
   Complete:
     AUDIO_PLAN.md (7 phases)
       Background music and sound effects system with 5 modes
     ...
   

4. Exit.

Mode: Rebuild (/plans rebuild)

Scan plans/, classify every .md file, and write a fresh plans/PLAN_INDEX.md.

Step 1 — Inventory

ls plans/*.md

Get all plan files. Ignore subdirectories.

Step 2 — Classify each file

For each file, read the first ~50 lines. Classify into one of three categories:

1. Executable plan — has ## Phase sections (numbered phases with work items) OR has a Progress Tracker table (| Phase | Status |). These are plans that /run-plan can execute.

   Meta-plan detection: If the plan's phases use ### Execution: delegate /run-plan directives referencing other plan files, it's a meta-plan. Record which sub-plan files it references. In the index, sub-plans should be indented under their meta-plan rather than listed independently.

2. Issue tracker — filename ends in _ISSUES.md OR has an "Issue Tracker" or "Issue List" heading OR is primarily a table of GitHub issue numbers. List separately — these are not executable by /run-plan. Deterministic rule: Files ending in _ISSUES.md are ALWAYS classified as issue trackers, regardless of other content (e.g., phase sections). The filename suffix takes precedence over content-based classification.

3. Reference document — everything else (research docs, overviews, gap analyses). List separately.

Step 3 — Determine status for executable plans

For each executable plan, determine its status:

1. Read the Progress Tracker (if present) — a table with phase rows and status indicators:

   • All phases marked Done / Complete / has a commit hash -> Complete
   • Some phases done, others pending -> In Progress (note the current phase name and the next incomplete phase)
   • No phases done (all Not Started / empty) -> Ready

2. No Progress Tracker? Check for other completion signals:

   • Sections with **Status:** Done or **Status:** Complete -> count as done
   • If all phase sections have completion markers -> Complete
   • If some do -> In Progress
   • If the plan has phases but no status indicators at all -> Needs Review (old-format plan; status is ambiguous — may be complete, may not be)
   • Only classify as Ready if the plan clearly hasn't been started (e.g., freshly created by /draft-plan)

Step 4 — Determine priority for "Ready to Run" plans

Rank ready plans by:

1. Recently created plans — sort by git creation date (newest first). Use git log --diff-filter=A --format=%aI -- <file> to get each file's initial commit date. This avoids conflating "recently written" with "recently touched by any edit."
2. Alphabetical — tiebreaker.

Assign priority labels: High (newest / most urgent), Medium (recent), Low (older/alphabetical fallback).

Step 5 — Write plans/PLAN_INDEX.md

Write the index file with this structure:

# Plan Index

Auto-generated by `/plans rebuild`. Last rebuilt: YYYY-MM-DD HH:MM ET.

## Ready to Run

| Plan | Phases | Next Phase | Priority | Notes |
|------|--------|------------|----------|-------|
| [EXAMPLE_PLAN.md](EXAMPLE_PLAN.md) | 5 | 1 -- Setup | High | Recently created |

## In Progress

| Plan | Phases | Current Phase | Next Phase | Notes |
|------|--------|---------------|------------|-------|
| [BEHAVIOR_PLAN.md](BEHAVIOR_PLAN.md) | 8 | 4b -- Schooling | 4c -- Predation | 4 of 8 phases done |

## Needs Review

Old-format plans without progress trackers. Status is ambiguous — may be
complete, partially done, or not started. Triage these once: mark as
Complete, move to Ready, or rewrite with `/draft-plan plans/FILE.md`.

| Plan | Phases | Issue | Notes |
|------|--------|-------|-------|
| [REFACTOR_PLAN.md](REFACTOR_PLAN.md) | 3 | No progress tracker | Check if refactor was implemented |

## Complete

| Plan | Phases | Notes |
|------|--------|-------|
| [GENETICS_META.md](GENETICS_META.md) | 4 | Meta-plan — all sub-plans done |
|   -> [TRAIT_SYSTEM_PLAN.md](TRAIT_SYSTEM_PLAN.md) | 3 | Sub-plan of GENETICS_META |
|   -> [BREEDING_PLAN.md](BREEDING_PLAN.md) | 2 | Sub-plan of GENETICS_META |
| [AUDIO_PLAN.md](AUDIO_PLAN.md) | 3 | All phases done |

## Reference (not executable)

| File | Type | Description |
|------|------|-------------|
| [OVERVIEW.md](OVERVIEW.md) | Reference | Project overview |
| [ISSUES_PLAN.md](ISSUES_PLAN.md) | Issue Tracker | Master issue index |

Notes for each section:

• If a section would be empty, include the table header with a single row: | (none) | | | | |
• Use relative links (just the filename, since index is in plans/)
• Count phases by counting ## Phase headings (or progress tracker rows)
• For "In Progress" plans, identify both the current phase (last done) and the next phase (first incomplete)
• Meta-plan grouping: If a plan is a meta-plan (has delegate /run-plan phases referencing other plan files), indent its sub-plans beneath it with -> prefix. Sub-plans should NOT appear as separate top-level entries. This makes the hierarchy visible.

Mode: Next (/plans next)

1. Read plans/PLAN_INDEX.md
2. If the file does not exist, auto-run rebuild to create it first.
3. Find the first entry in the "Ready to Run" table (highest priority)
4. If found, output:

   Next plan to run: EXAMPLE_PLAN.md Phases: 5, starting at Phase 1 -- Setup Priority: High

   Run with: /run-plan plans/EXAMPLE_PLAN.md

5. If the "Ready to Run" table is empty or has only (none):

   No plans ready to run. All executable plans are either in progress or complete. Check "In Progress" plans in the index for plans that need attention.

6. Exit.

Key Rules

• Rebuild is idempotent — running it twice produces the same result (assuming no plan files changed between runs).
• Never modify plan files — the index is read-only metadata. It reads plans but never changes them.
• Skip PLAN_INDEX.md itself — don't index the index.
• Relative links — since the index lives in plans/, links are just filenames (e.g., [FOO.md](FOO.md)), not plans/FOO.md.
• Timezone — always use America/New_York (ET) for the "Last rebuilt" timestamp.