Persistent Planning

Persistent Planning

Create, update, and track a structured project plan in PLAN.md.

Context

• Existing plan: !cat PLAN.md 2>/dev/null | head -50 || echo "No PLAN.md found"
• Project structure: !ls -la 2>/dev/null | head -20
• Current branch: !git branch --show-current
• Recent commits: !git log --oneline -5 2>/dev/null || echo "No commits"

Behavior Based on Arguments

Interpret $ARGUMENTS to determine the action:

If $ARGUMENTS is "status" or "show":

• Read PLAN.md and display current progress
• Show completion percentage for each phase
• Highlight the next actionable task
• List any open questions or blockers

If $ARGUMENTS is "complete" or "done":

• Update the current phase to "done"
• If all phases are done, add a completion timestamp
• Summarize what was accomplished

If PLAN.md already exists and $ARGUMENTS is a new task/description:

• Read the existing plan
• Add the new task(s) to the appropriate phase
• Preserve all existing progress (checked items stay checked)
• Update the plan status

If PLAN.md does NOT exist:

• Create a new PLAN.md with the structure below
• Populate based on $ARGUMENTS description
• Set phase to "planning"

PLAN.md Structure

When creating or updating PLAN.md, use this exact structure:

# Project Plan

> Status: **[planning | implementing | verifying | done]**
> Created: [date]
> Last Updated: [date]

## Objective

[Clear, concise statement of what this plan achieves]

## Tasks

### Phase 1: [Phase Name]

- [ ] Task 1.1 — [description]
  - Depends on: [nothing | task X.Y]
- [ ] Task 1.2 — [description]
  - Depends on: Task 1.1
- [x] Task 1.3 — [completed task description]
  - Depends on: nothing
  - Completed: [date]

### Phase 2: [Phase Name]

- [ ] Task 2.1 — [description]
  - Depends on: Phase 1
- [ ] Task 2.2 — [description]
  - Depends on: Task 2.1

### Phase 3: Verification

- [ ] Run all tests
- [ ] Review changes
- [ ] Update documentation

## Architecture Decisions

| Decision   | Options Considered   | Chosen   | Rationale |
| ---------- | -------------------- | -------- | --------- |
| [decision] | [option A, option B] | [chosen] | [why]     |

## Open Questions

- [ ] [Question 1 — what needs to be answered]
- [x] [Question 2 — answered: [answer]]

## Progress Log

| Date   | Update          |
| ------ | --------------- |
| [date] | [what was done] |

Rules for Plan Management

1. Never delete completed tasks — mark them with [x] and add completion date
2. Respect dependencies — do not mark a task complete if its dependencies are incomplete
3. Add discovered tasks — when implementation reveals new work, add it to the appropriate phase
4. Update status — move through phases: planning -> implementing -> verifying -> done
5. Log progress — every significant update gets a Progress Log entry
6. Keep it current — the plan should always reflect the true state of work
7. Track decisions — any architectural or design decisions go in the Architecture Decisions table
8. Resolve questions — when open questions are answered, mark them [x] with the answer

Workflow

1. Check if PLAN.md exists in the project root
2. If it exists, read it fully to understand current state
3. Based on $ARGUMENTS, either show status, add tasks, or update progress
4. Write the updated PLAN.md back to disk
5. Display a summary of what changed and what is next

$ARGUMENTS