diff --git a/.claude/skills/plan-queue/SKILL.md b/.claude/skills/plan-queue/SKILL.md new file mode 100644 index 0000000..67f8e71 --- /dev/null +++ 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 ", "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--.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-`. + 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). diff --git a/.claude/skills/plan-queue/plan-template.md b/.claude/skills/plan-queue/plan-template.md new file mode 100644 index 0000000..553d1f1 --- /dev/null +++ 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 + +``` + +Expected: . + +## 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. diff --git a/.claude/skills/plan-queue/sync-to-repos.sh b/.claude/skills/plan-queue/sync-to-repos.sh new file mode 100755 index 0000000..baf58b1 --- /dev/null +++ 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 diff --git a/.claude/skills/run-queue/SKILL.md b/.claude/skills/run-queue/SKILL.md new file mode 100644 index 0000000..8ce723f --- /dev/null +++ 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/ plans/active/`, set its INDEX.md row to + `in-progress`, commit: `plan: start NNN-`. 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 [-m TIER] plans/active/.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/.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-`, 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/ 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. diff --git a/.claude/skills/run-queue/run-plan.sh b/.claude/skills/run-queue/run-plan.sh new file mode 100755 index 0000000..ccb288b --- /dev/null +++ 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] }" +[ -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"