---
name: plan-queue
description: Author detailed, weak-model-executable plan files into the current repo's plans/ queue (plans/queue|active|done|failed + INDEX.md). The strong model does ALL exploration and thinking up front so a cheap executor can later apply the plan with zero codebase discovery. Use when the user says "/plan-queue <task>", "queue a plan for X", "add X to the plan queue", "plan this for the weak model". Companion skill: run-queue executes the queue. Manually-triggered only.
---

# plan-queue

Turn a task description into a **self-contained plan file** in the repo's
`plans/queue/`, detailed enough that a weak/cheap model can execute it without
exploring the codebase. Multiple tasks in one invocation → one plan file each.

## Layout (create on first use in a repo)

```
plans/
  INDEX.md      # ordered table of all plans
  queue/        # not started
  active/       # currently executing (max 1)
  done/
  failed/
```

`INDEX.md` starts as:

```markdown
# Plan Queue Index

| Seq | ID | Title | Status | Commit | Notes |
|-----|----|-------|--------|--------|-------|
```

## Procedure

1. **Scaffold**: if `plans/INDEX.md` doesn't exist, create the layout above
   (`.gitkeep` in the four dirs so git tracks them).
2. **Explore deeply** (strong-model work): read every file the change touches,
   find existing utilities to reuse, note exact paths, line anchors, and
   signatures. The goal: the executor must need **zero** exploration.
3. **Name the plan**: next `NNN` = highest seq across all four dirs + 1
   (zero-padded 3 digits). `HASH` = first 6 chars of
   `sha1(title + timestamp)`. Filename: `NNN-<kebab-slug>-<HASH>.md` in
   `plans/queue/`.
4. **Write the plan** following `plan-template.md` in this skill directory.
   Every section is mandatory. Be near-diff-level specific in Steps for
   anything non-trivial; paste real code snippets into Context.
5. **Index**: append a row to `INDEX.md` (`Status: queued`, Commit blank).
6. **Commit** the new plan file(s) + INDEX.md: `plan: add NNN-<slug>`.
   Do NOT push. Never add AI attribution to the commit.

## Rules for plan quality (this is the whole point)

- **Front-load context.** Paste the actual current code of the region being
  changed into the plan. The executor should never have to grep.
- **Steps are mechanical.** "Edit `src/auth.ts:42`: change X to Y" — not
  "improve the auth flow".
- **Guardrails.** Always fill "Out of scope / do NOT touch" — weak models
  drift without it.
- **Verification is copy-pasteable.** Exact commands + expected output.
- **Independence.** Each plan must leave the repo working (buildable/tests
  green) on its own, since it gets its own commit. If a task can't, split it
  differently or use `depends_on`.
- `depends_on:` in frontmatter lists plan IDs (the NNN-slug-hash basename)
  that must be in `done/` first. Use it so many plans can be queued without
  conflict.

## Conflict avoidance when queueing many plans

When authoring several plans in one batch, keep their file footprints
disjoint where possible; where they must overlap, chain them with
`depends_on` and write the later plan against the code **as it will be after
the earlier plan** (say so explicitly in its Context section).