---
name: agent-plans
description: > 
  Manages a FIFO queue of markdown plan files in docs/plans/ (or a custom directory) to coordinate work between humans and agents. 
   Use this skill whenever the user says "work on the next plan", "execute the next task", "check the plans", "what's next to do", 
   or whenever you need to pick up a task from a structured plan queue. Each plan goes through the states pending → review → approved → completed, 
   keeping humans in control of every step.
compatibility: Designed for Claude Code (or similar agentic products). Requires Node.js.
license: MIT
---

# 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):

```bash
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:

| `action`    | Meaning                                               |
|-------------|-------------------------------------------------------|
| `"execute"` | An `approved` plan is ready — go work on it           |
| `"plan"`    | A `pending` plan needs a `## Task` written            |
| `"none"`    | Nothing to do — tell the user                         |

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):
```markdown
## Execution

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

5. 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):
```markdown
## Task

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

5. 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:

```bash
node scripts/plan.js status
```

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

## Plan file format

```markdown
---
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)

```bash
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