hermesdevagent/.claude/skills/plan-queue/SKILL.md

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 ", "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:

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