Agent Plans

A FIFO plan queue system where humans write instructions and agents plan, execute, and report back — one task at a time.

Overview of the flow

pending  →  (agent adds ## Task)  →  review  →  (human approves)  →  approved  →  (agent executes)  →  completed

Humans write ## Instructions. Agents write ## Task and ## Execution. Humans stay in control at every handoff.

Step 1 — Find the next plan

Run the helper script (path relative to the skill root):

node scripts/plan.js next
# Custom directory:
node scripts/plan.js next --dir path/to/plans

The script returns JSON. Parse the action field to know what to do:

The script also returns filePath — the absolute path to the target file. Always use it.

Step 2a — If action is "execute" (approved plan)

1. Read the file at filePath
2. Read the ## Task section carefully — this is what you must do
3. Do the work
4. Update the file:

• Change status: approved → status: completed in the YAML frontmatter
• Append a ## Execution section at the end, summarizing what you did (be brief and precise — this is for the human's log)

Execution summary format (keep it short):

## Execution

Brief description of what was done. List key files created/modified if relevant.

1. Tell the user the task is complete and what you did.

Step 2b — If action is "plan" (pending plan)

1. Read the file at filePath
2. Read the ## Instructions section — understand what the human wants
3. Think through the approach
4. Update the file:

• Change status: pending → status: review in the YAML frontmatter
• Append a ## Task section describing what you plan to do (brief, precise, actionable)

Task format (keep it short — this is your plan, not the execution):

## Task

Brief description of the approach. What will be created, changed, or implemented. No fluff.

1. Tell the user you've written the task plan and it's ready for their review. Remind them to change the status to approved when they're happy with it.

Step 2c — If action is "none"

Tell the user there are no approved or pending plans to work on. Suggest running:

node scripts/plan.js status

...so they can see the current state of all plans.

Plan file format

---
name: short-kebab-name
description: One-line summary of what this plan achieves
status: pending | review | approved | completed
---

# Optional long title

Optional summary paragraph.

## Instructions

What the human wants done. Written by the human.

## Task

What the agent plans to do. Written by the agent when status moves pending → review.

## Execution

What the agent did. Written by the agent when status moves approved → completed.

File naming convention: NNNN-short-description.md — e.g. 0001-create-auth-endpoints.md. The numeric prefix determines FIFO order. Always create new plans with the next available number.

Checking status (for humans)

node scripts/plan.js status
node scripts/plan.js status --dir path/to/plans

This prints a human-friendly summary of all plans with their current status.

Key rules

• Always process one plan at a time — the script selects the oldest eligible plan (FIFO)
• Priority order: approved before pending — always finish approved work before planning new tasks
• Never skip the script — always run plan.js next first; don't guess which file to work on
• Never change status to `approved` — that's the human's job
• Keep `## Task` and `## Execution` brief — precision over verbosity, saves tokens and is easier to read
• Edit frontmatter in place — only change the status: line, leave everything else untouched