Add plan-queue and run-queue skills

2026-07-16 20:49:27 +08:00
parent b833ede901
commit 58b0f4d2fd
5 changed files with 307 additions and 0 deletions
--- a/.claude/skills/plan-queue/SKILL.md
+++ b/.claude/skills/plan-queue/SKILL.md
@@ -0,0 +1,71 @@
+---
+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).
--- a/.claude/skills/plan-queue/plan-template.md
+++ b/.claude/skills/plan-queue/plan-template.md
@@ -0,0 +1,59 @@
+---
+id: NNN-slug-hash            # matches filename (without .md)
+title: Short imperative title
+created: YYYY-MM-DD
+depends_on: []               # e.g. [001-add-user-model-a3f9c2]
+est_files: 2                 # rough count of files the executor will touch
+---
+
+# NNN — Title
+
+## Objective
+
+One paragraph: what "done" looks like, in behavioral terms.
+
+## Context the executor must NOT rediscover
+
+Everything a weak model needs so it never explores:
+
+- Exact file paths with line anchors (`src/foo.ts:120-145`) and what's there.
+- Signatures of functions/utilities to REUSE (with their paths).
+- Pasted snippets of the current code around each edit site.
+- Any project conventions that apply (naming, error handling, test style).
+
+```lang
+// paste the relevant current code here
+```
+
+## Steps
+
+1. Edit `path/to/file.ext` — concrete, mechanical instruction. For tricky
+   edits, show the exact before/after or a unified diff.
+2. Create `path/to/new-file.ext` with: (full contents or precise spec).
+3. ...
+
+## Out of scope / do NOT touch
+
+- Files/behaviors the executor must leave alone.
+- Refactors NOT to attempt, even if tempting.
+
+## Verification
+
+Run exactly:
+
+```bash
+<build/test/lint commands>
+```
+
+Expected: <what passing looks like, specific output to check>.
+
+## Report format (executor: follow exactly)
+
+Output ONLY the following, no other prose:
+
+1. `git diff` (unified) of all changes.
+2. Raw output of the Verification commands.
+3. `Findings:` — max 10 lines: surprises, deviations from the steps, anything
+   skipped and why.
+
+Do not commit. Do not push. Do not touch files outside the Steps.
--- a/.claude/skills/plan-queue/sync-to-repos.sh
+++ b/.claude/skills/plan-queue/sync-to-repos.sh
@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# sync-to-repos.sh — copy the canonical plan-queue + run-queue skills from
+# ~/.claude/skills/ into .claude/skills/ of every git repo under
+# ~/development/personal/. Re-run after editing the skills to prevent drift.
+set -euo pipefail
+
+SRC="$HOME/.claude/skills"
+BASE="$HOME/development/personal"
+
+for gitdir in "$BASE"/*/.git; do
+  repo="$(dirname "$gitdir")"
+  dest="$repo/.claude/skills"
+  mkdir -p "$dest"
+  rm -rf "$dest/plan-queue" "$dest/run-queue"
+  cp -r "$SRC/plan-queue" "$SRC/run-queue" "$dest/"
+  echo "synced: $repo"
+done
--- a/.claude/skills/run-queue/SKILL.md
+++ b/.claude/skills/run-queue/SKILL.md
@@ -0,0 +1,93 @@
+---
+name: run-queue
+description: Execute the repo's plan queue (plans/queue/) sequentially - dispatch each plan to a cheap executor (claude-custom gateway via delegate.sh by default, or an in-session haiku Agent), review the returned diff + findings, verify, fix if needed, commit per plan, and push to all remotes only when the entire queue is done and verified. Resumable after token exhaustion or crashes via plans/active/. Use when the user says "/run-queue", "run the plan queue", "execute the queued plans". Companion skill: plan-queue authors the plans. Manually-triggered only.
+---
+
+# run-queue
+
+Sequentially execute every plan in `plans/queue/` (authored by `plan-queue`).
+The strong model (you) orchestrates and reviews; a weak model executes.
+Token contract: you read only plan files, returned diffs/findings, and
+verification output — never re-explore the repo yourself unless a fix round
+requires it.
+
+## Invocation
+
+```
+/run-queue [--executor gateway|agent] [--model TIER] [--max-fix N] [--dry-run]
+```
+
+Defaults: `--executor gateway --model haiku --max-fix 2`.
+`--dry-run`: print the resolved execution order (respecting `depends_on`) and
+exit without dispatching.
+
+## Orchestration loop
+
+### 0. Preconditions
+- Repo has `plans/INDEX.md`; working tree is clean (if not, stop and ask —
+  never clobber uncommitted user work).
+
+### 1. Resume check
+If `plans/active/` contains a plan (previous run died / tokens exhausted):
+- The plan-start commit is the checkpoint, so `git checkout -- . && git clean -fd`
+  (confirm nothing untracked is user work first) to reset any half-applied
+  edits, then re-dispatch that plan (step 3). This is always safe because
+  every plan starts from a clean committed state.
+
+### 2. Pick next plan
+- Lowest `NNN` in `plans/queue/` whose `depends_on` entries are ALL in
+  `plans/done/`. If a plan is blocked, skip to the next unblocked one; if
+  everything remaining is blocked, report and stop.
+- `git mv plans/queue/<plan> plans/active/`, set its INDEX.md row to
+  `in-progress`, commit: `plan: start NNN-<slug>`. This commit is the resume
+  checkpoint.
+
+### 3. Dispatch to the executor
+Build the prompt with `run-plan.sh` (this skill dir):
+
+- **gateway** (default): `~/.claude/skills/run-queue/run-plan.sh -d <repo-root> [-m TIER] plans/active/<plan>.md`
+  — wraps the plan in the executor preamble and calls
+  `~/.claude/skills/delegate-task/delegate.sh` (timeout 1800s, retries on).
+- **agent**: `run-plan.sh -p plans/active/<plan>.md` prints the prompt only;
+  pass it to the Agent tool (`subagent_type: general-purpose`,
+  `model: haiku`, `run_in_background: false`, cwd = repo).
+
+### 4. Review (strong model, diff-only)
+Read ONLY the executor's report (diff + verification output + findings).
+Then **run the plan's Verification commands yourself** — never trust the
+executor's pasted output.
+
+- **Pass** → step 5.
+- **Fail** → up to `--max-fix` rounds:
+  - Small gap: fix it directly yourself (Edit tool).
+  - Larger miss: reset the tree (`git checkout -- . && git clean -fd`),
+    re-dispatch with a corrective addendum appended to the prompt
+    (`run-plan.sh -a "addendum text" ...`).
+- **Exhausted fix rounds** → reset tree, append `## Failure notes` (what
+  failed, last error) to the plan file, `git mv` it to `plans/failed/`,
+  INDEX row → `failed`, commit `plan: fail NNN-<slug>`, continue with the
+  next plan that doesn't depend on it.
+
+### 5. Complete the plan
+- Append `## Execution log` to the plan file: executor+model, attempts,
+  fix rounds, the executor's Findings verbatim.
+- `git mv plans/active/<plan> plans/done/`, INDEX row → `done` + commit hash
+  placeholder, then ONE commit containing code changes + plan move + INDEX:
+  message = the plan's title, plain human style. **Never** add
+  Co-Authored-By/AI attribution (global rule). Backfill the commit hash into
+  the INDEX row on the next commit or amend before creating it.
+- Loop to step 2.
+
+### 6. Ship gate (only when queue/ is empty)
+- If `plans/failed/` is non-empty: report the failures, do NOT push. Done.
+- Else: run the repo's full verification once more (union of the plans'
+  Verification commands, or the project's standard build/test), then push
+  every local branch's current state to **all** configured remotes
+  (`git remote` loop), ship-it style.
+- **Webhook warning**: if the repo auto-deploys on push (e.g. BarangaySystem
+  via Gitea webhooks), say so before pushing and ask, unless the user already
+  told you to ship in this conversation.
+
+## Reporting
+End with: plans completed/failed (titles), one-line finding per plan, commits
+created, and whether the push happened.
--- a/.claude/skills/run-queue/run-plan.sh
+++ b/.claude/skills/run-queue/run-plan.sh
@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# run-plan.sh — dispatch one plan-queue plan file to a cheap executor.
+#
+# Usage:
+#   run-plan.sh [-d REPO_DIR] [-m TIER] [-t SECS] [-a "addendum"] [-p] plans/active/NNN-slug-hash.md
+#
+#   -d DIR   repo root the executor works in (default: cwd)
+#   -m TIER  model tier alias for delegate.sh (default: haiku)
+#   -t SECS  timeout (default: 1800)
+#   -a TEXT  corrective addendum appended to the prompt (fix rounds)
+#   -p       print the built prompt to stdout and exit (for Agent-tool mode)
+set -euo pipefail
+
+DIR="$(pwd)"
+MODEL="haiku"
+TIMEOUT=1800
+ADDENDUM=""
+PRINT_ONLY=0
+
+while getopts "d:m:t:a:p" opt; do
+  case "$opt" in
+    d) DIR="$OPTARG" ;;
+    m) MODEL="$OPTARG" ;;
+    t) TIMEOUT="$OPTARG" ;;
+    a) ADDENDUM="$OPTARG" ;;
+    p) PRINT_ONLY=1 ;;
+    *) exit 2 ;;
+  esac
+done
+shift $((OPTIND - 1))
+PLAN="${1:?usage: run-plan.sh [opts] <plan-file>}"
+[ -f "$PLAN" ] || { echo "plan file not found: $PLAN" >&2; exit 1; }
+
+PROMPT_FILE="$(mktemp)"
+trap 'rm -f "$PROMPT_FILE"' EXIT
+
+{
+  cat <<'PREAMBLE'
+You are a plan EXECUTOR. Apply the plan below exactly.
+
+Rules:
+- Follow the Steps in order. Do not explore beyond the files the plan names.
+- Do not refactor, rename, or "improve" anything outside the Steps.
+- Respect the "Out of scope / do NOT touch" section absolutely.
+- Run the Verification commands after making the changes.
+- Do NOT commit, do NOT push, do NOT create branches.
+- Your final output must be ONLY, in this order:
+  1. The full `git diff` (unified) of your changes.
+  2. The raw output of the Verification commands.
+  3. `Findings:` followed by at most 10 lines (surprises, deviations, skips).
+No other prose, no explanations, no step-by-step narration.
+
+=== PLAN ===
+PREAMBLE
+  cat "$PLAN"
+  if [ -n "$ADDENDUM" ]; then
+    printf '\n=== CORRECTION (a previous attempt failed — apply this too) ===\n%s\n' "$ADDENDUM"
+  fi
+} > "$PROMPT_FILE"
+
+if [ "$PRINT_ONLY" -eq 1 ]; then
+  cat "$PROMPT_FILE"
+  exit 0
+fi
+
+exec "$HOME/.claude/skills/delegate-task/delegate.sh" \
+  -m "$MODEL" -d "$DIR" -t "$TIMEOUT" -f "$PROMPT_FILE"