Plan Tracking

Plan Tracking

Plan Lifecycle

                     ┌──────────────┐
                     │   CREATED    │
                     └──────┬───────┘
                            │
                     ┌──────▼───────┐
                     │   ACTIVE     │
                     └──────┬───────┘
                            │
              ┌─────────────┼────────────┐
              │             │            │
       ┌──────▼──────┐ ┌────▼────┐ ┌─────▼─────┐
       │   DONE      │ │ BLOCKED │ │ ABANDONED │
       └─────────────┘ └─────────┘ └───────────┘

Lifecycle Rules

1. Every plan starts active (YYYY-MM-DD-<name>.md) in <USER_HOME>/agent-notes/planner/plans/
2. Active plans transition to exactly one terminal state by appending -DONE.md, -BLOCKED.md, or -ABANDONED.md
3. Terminal states are final — do not resume a done plan; create a new one
4. All transitions must include metadata explaining the why
5. The date prefix MUST match the creation date, not the completion date

Scripts

plan-list.sh — List Plans by Status

plan-list.sh                    # All plans grouped by status
plan-list.sh --status active    # Only active plans
plan-list.sh --status done
plan-list.sh --status blocked
plan-list.sh --status abandoned
plan-list.sh --format detailed  # Show descriptions and metadata

plan-mark.sh — Transition Plan Status

# Mark done
plan-mark.sh <plan.md> --status done \
  --commits "abc1234 - Fixed the thing | def5678 - Added tests" \
  --by "Agent Name" \
  --results "What was accomplished"

# Mark blocked
plan-mark.sh <plan.md> --status blocked \
  --reason "Waiting on API credentials from third party"

# Mark abandoned
plan-mark.sh <plan.md> --status abandoned \
  --reason "Requirements changed, superseded by new plan"

Always prefer this script over manual renaming — it ensures consistent metadata.

plan-verify.sh — Check Plan Integrity

plan-verify.sh              # Check all plans
plan-verify.sh <plan.md>    # Check one plan
plan-verify.sh --fix        # Auto-fix common issues

Checks: file exists, has markdown heading, date prefix present, status suffix consistent, commit references exist in git history.

Run plan-verify.sh --fix periodically to catch and repair issues.

plan-report.sh — Generate Status Report

plan-report.sh                     # Full report to stdout
plan-report.sh --output report.md  # Write to file
plan-report.sh --journal           # Journal-friendly format (paste into daily journal)

Marking Plans Complete

Mark done only when ALL of these are true:

1. All tasks in the plan have been executed
2. A reviewer has confirmed the work
3. Commit IDs are known (if code was written)
4. The user has seen and acknowledged the results

Completion Metadata (appended by plan-mark.sh)

---

## ✅ PLAN COMPLETED

**Completion Date:** YYYY-MM-DD
**Completed By:** [Agent name and role]
**Commit ID(s):**
- abc1234 - "Commit message"

**What Was Done:**
- Brief summary of what was implemented

**Result:** Final outcome and verification that objectives were met

Partial Completion

If some tasks are done and some remain — do NOT rename the file. Append instead:

---

## ⚠️ Partial Progress (YYYY-MM-DD)

**Completed:**
- [x] Task 1: Done (commit abc1234)

**Remaining:**
- [ ] Task 2: In progress
- [ ] Task 3: Not started

**Reason:** <why it's not finished>

Plan Blocking & Abandonment

plan-mark.sh <plan.md> --status blocked \
  --reason "Waiting on third-party API keys"

Blocked plans append:

## 🔒 PLAN BLOCKED

**Date Blocked:** YYYY-MM-DD
**Reason:** <what's blocking>
**Blocking Dependencies:** <specific, actionable items needed to unblock>

Good reasons to abandon: requirements changed fundamentally; problem solved another way; superseded by a newer plan. Do not abandon: because it was hard (use blocked); because you ran out of time (use partial).

Verification Issues Reference

Plan Review Workflow

1. Implementer completes the work
2. Reviewer confirms the work
3. Orchestrator runs plan-verify.sh
4. Orchestrator runs plan-mark.sh --status done
5. Orchestrator references the completed plan in the daily journal

Script Reference