plan - SKILL.md Agent Skill

name: plan description: OPT-IN file-based planning for multi-session tasks. Only use when user explicitly requests it or work spans multiple sessions. For single-session work, prefer your platform's native planning features. metadata: internal: true disable-model-invocation: true

File-Based Task Plan Template

Default: Use Your Platform's Native Planning

For single-session work, prefer your AI platform's built-in planning features. This file-based approach adds overhead that's only justified for specific scenarios.

When to Use THIS Skill (Opt-In)

Only use this file-based plan template when:

User explicitly requests it ("use the plan template", "create a plan file")
Work spans multiple sessions and must survive context resets
Handoff to another AI/human who needs full written context
Complex multi-PR coordination requiring persistent state

Setup

Copy this template to AI_PROGRESS/[task_name]/plan.md
Replace all [placeholders] with actual values
Fill out Context sections completely
Start with Step 1 marked as IN_PROGRESS

Critical Meta-Goals

THIS PLAN MUST BE:

FULLY SELF-DESCRIBING: All context needed to resume work is IN THIS FILE
CONSTANTLY UPDATED: Every action's results recorded IMMEDIATELY in the step
THE SINGLE SOURCE OF TRUTH: If it's not in the plan, it didn't happen
SAFE TO RESUME: Any AI can pick up work by reading ONLY this file

REMEMBER: External memory is unreliable. This plan is your ONLY memory.

Anti-Drift Protocol

The Three Commandments

RELOAD BEFORE EVERY ACTION: Your memory has been wiped. This plan is all you have.
UPDATE AFTER EVERY ACTION: If you don't write it down, it never happened.
TRUST ONLY THE PLAN: Not your memory, not your assumptions, ONLY what's written here.

Critical Rules

ONE TASK AT A TIME - Never jump ahead
NO ASSUMPTIONS - The plan is the only truth
NO OFFROADING - If it's not in the plan, don't do it

Step Execution Protocol

BEFORE EVERY SINGLE ACTION:

RELOAD PLAN: cat AI_PROGRESS/[task_name]/plan.md | head -200
FIND YOUR TASK: Locate the current IN_PROGRESS step
EXECUTE: ONLY do what that step says
UPDATE IMMEDIATELY: Edit this plan with results BEFORE doing anything else
VERIFY: tail -50 AI_PROGRESS/[task_name]/plan.md

If Confused

STOP
Reload this plan
Find the last completed step
Continue from there

Plan Template

# [Task Name] Plan
**THIS PLAN FILE**: `AI_PROGRESS/[task_name]/plan.md`
**Created**: [DATE TIME TIMEZONE]
**Current Branch**: [from `git branch --show-current`]
**PRs**: [PR number + title + plan role]
**PR Target Branch**: [where this will merge]
**Base branch**: [FILL ME IN, TYPICALLY PR TARGET BRANCH]

## Context (READ-ONLY)

### Plan Overview
**Raw Prompt**: [What the user said, verbatim]
**Goal**: [What we're trying to achieve]
**Description**: [Brief description of the task]
**Success Criteria**: [How we know we're done]
**Key Constraints**: [Important limitations or requirements]

### Technical Context
**Initial State**:
- Working Directory: [pwd output]
- Current Branch: `[branch-name]` (forked from `[parent]` at `[SHA]`)
- Target Branch: `[where this merges to]`

### Strategy
**Approach**: [High-level plan]
**Key Decisions**:
- [Decision 1]: [Reasoning]
- [Decision 2]: [Reasoning]

## Quick Reference
```bash
# Reload plan
cat AI_PROGRESS/[task_name]/plan.md | head -200

# Local validation before pushing
./bin/ruff check --fix && ./bin/mypy

# CI monitoring
gh pr checks [PR] --watch

Status Legend

TODO: Not started
IN_PROGRESS: Currently working on this
DONE: Completed successfully
FAILED: Failed, needs retry
SKIPPED: Not needed
BLOCKED: Can't proceed

LIVE PLAN

Steps

Step 1: [Description]

Status: IN_PROGRESS Action: [What to do] Success Criteria: [How to verify] Result:

[Fill in with commands, output, decisions, errors]

Step 2: [Description]

Status: TODO Action: [What to do] Success Criteria: [How to verify]


## Step Compaction

**Every ~30 completed steps, compact the plan:**
1. Create history file: `AI_PROGRESS/[task_name]/history/steps<start>-to-<end>.md`
2. Replace archived steps with summary in plan
3. Continue with next step number