From 54d2f0f7db44f17eefa8347430aa3fcd7d4527d6 Mon Sep 17 00:00:00 2001 From: KrishP147 Date: Sat, 17 Oct 2026 03:05:13 -0400 Subject: [PATCH 01/16] docs(install): Needs lines name the guard-git hook any agent install brings Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01WHwM2TcQBo9oHdCrYCtdMn --- agents/README.md | 8 ++++---- lanes/README.md | 2 +- meta-orchestrator/README.md | 2 +- pair/README.md | 2 +- scripts/test_site_detail.py | 2 +- scripts/workflow_deps.py | 6 ++++-- 6 files changed, 12 insertions(+), 10 deletions(-) diff --git a/agents/README.md b/agents/README.md index 6accd23..14af9f5 100644 --- a/agents/README.md +++ b/agents/README.md @@ -18,7 +18,7 @@ Installed by `scripts/install-skills.*` into `~/.claude/agents/`, with `hooks/` ## planner -Needs: `divide`, `next` (installed with it). +Needs: `divide`, `next`, the `guard-git` hook (installed with it). - **Role:** picks the next single unit of work from the board and writes the kickoff brief. - Read-only: `disallowedTools: Edit, Write, NotebookEdit`; never creates issues. @@ -59,7 +59,7 @@ Needs: `divide`, `next` (installed with it). ## manager -Needs: `handoff-auto`, `kanban-setup`, `next`, `session-handoff`, `implementer` (installed with it). +Needs: `handoff-auto`, `kanban-setup`, `next`, `session-handoff`, `implementer`, the `guard-git` hook (installed with it). - **Role:** owns one task end to end in a worktree. - Never implements itself: briefs an implementer, then reviews its work as if it didn't trust it. @@ -113,7 +113,7 @@ Needs: `handoff-auto`, `kanban-setup`, `next`, `session-handoff`, `implementer` ## implementer -Needs: `handoff-auto`, `kanban-setup`, `next`, `session-handoff` (installed with it). +Needs: `handoff-auto`, `kanban-setup`, `next`, `session-handoff`, the `guard-git` hook (installed with it). - **Role:** implements one well-specified issue from a kickoff brief on its own branch. - `maxTurns: 200`. @@ -149,7 +149,7 @@ Needs: `handoff-auto`, `kanban-setup`, `next`, `session-handoff` (installed with ## verifier -Needs: `consult-plan`, `next`, `update-progress` (installed with it). +Needs: `consult-plan`, `next`, `update-progress`, the `guard-git` hook (installed with it). - **Role:** verifies an implementation session and closes the loop. - `maxTurns: 120`. diff --git a/lanes/README.md b/lanes/README.md index da13155..ee8e63f 100644 --- a/lanes/README.md +++ b/lanes/README.md @@ -2,7 +2,7 @@ *`SKILL.md` is the prompt Claude follows; this file is for you.* -Needs: `consult-plan`, `divide`, `handoff-auto`, `kanban-setup`, `meta-orchestrator`, `next`, `pair`, `progress-report`, `session-handoff`, `update-progress`, `implementer`, `manager`, `planner`, `verifier` (installed with it). +Needs: `consult-plan`, `divide`, `handoff-auto`, `kanban-setup`, `meta-orchestrator`, `next`, `pair`, `progress-report`, `session-handoff`, `update-progress`, `implementer`, `manager`, `planner`, `verifier`, the `guard-git` hook (installed with it). ## What it does diff --git a/meta-orchestrator/README.md b/meta-orchestrator/README.md index 37b1268..7d26f25 100644 --- a/meta-orchestrator/README.md +++ b/meta-orchestrator/README.md @@ -2,7 +2,7 @@ *`SKILL.md` is the prompt Claude follows; `SETUP.md` (first-run interview + every option) and `ROTATION.md` (handoff / resume) are loaded only when needed. This file is for you.* -Needs: `consult-plan`, `divide`, `handoff-auto`, `kanban-setup`, `lanes`, `next`, `pair`, `progress-report`, `session-handoff`, `update-progress`, `implementer`, `manager`, `planner`, `verifier` (installed with it). +Needs: `consult-plan`, `divide`, `handoff-auto`, `kanban-setup`, `lanes`, `next`, `pair`, `progress-report`, `session-handoff`, `update-progress`, `implementer`, `manager`, `planner`, `verifier`, the `guard-git` hook (installed with it). ## What it does diff --git a/pair/README.md b/pair/README.md index 8e14cf9..da7b3e4 100644 --- a/pair/README.md +++ b/pair/README.md @@ -2,7 +2,7 @@ *`SKILL.md` is the prompt Claude follows; this file is for you.* -Needs: `handoff-auto`, `kanban-setup`, `next`, `session-handoff`, `implementer`, `manager` (installed with it). +Needs: `handoff-auto`, `kanban-setup`, `next`, `session-handoff`, `implementer`, `manager`, the `guard-git` hook (installed with it). ## What it does diff --git a/scripts/test_site_detail.py b/scripts/test_site_detail.py index 979de8d..bf30b03 100644 --- a/scripts/test_site_detail.py +++ b/scripts/test_site_detail.py @@ -138,7 +138,7 @@ def test_needs_line_in_install_not_body(self): rest = page.replace(install, "") self.assertNotIn("Works on its own.", rest, name) self.assertNotIn("(installed with it).", rest, name) - self.assertIn('

Needs: divide, next (installed with it).

', + self.assertIn('

Needs: divide, next, the guard-git hook (installed with it).

', self.pages["planner"]) def test_pop_needs(self): diff --git a/scripts/workflow_deps.py b/scripts/workflow_deps.py index bd03632..8332b7b 100644 --- a/scripts/workflow_deps.py +++ b/scripts/workflow_deps.py @@ -195,10 +195,12 @@ def listing(g): def needs_line(g, name): """The README line saying what installing `name` alone brings along.""" r = g.resolve(names=[name]) - others = [n for k in ("skill", "agent", "hook") for n in r[k] if n != name] + others = ["`%s`" % n for k in ("skill", "agent", "hook") for n in r[k] if n != name] + if r["agent"]: # any agent install also copies agents/hooks/guard-git.py + others.append("the `guard-git` hook") if not others: return "Works on its own." - return "Needs: %s (installed with it)." % ", ".join("`%s`" % n for n in others) + return "Needs: %s (installed with it)." % ", ".join(others) def name_listing(g): From fec5da8b8ef276b73d60833a115d5c691ad5e5e2 Mon Sep 17 00:00:00 2001 From: KrishP147 Date: Sat, 17 Oct 2026 03:10:43 -0400 Subject: [PATCH 02/16] docs(switch): pre-switch notes don't print artifacts/routines Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01WHwM2TcQBo9oHdCrYCtdMn --- switch/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/switch/README.md b/switch/README.md index 4194393..baade5f 100644 --- a/switch/README.md +++ b/switch/README.md @@ -12,7 +12,7 @@ Runs several Claude Code accounts side by side, each with its own config dir, an - Inside a session, `/switch` closes it and reopens the same conversation on your previous account, `/switch ` on a named one. - `/switch setup` does the one-time setup from inside Claude. - `/switch add|remove|rename|list` manages the accounts; new ones share skills, settings and history with the first. `list` shows who is logged in where and how much usage each account has left. -- Before each switch it prints what stays with the old account (artifacts, routines) and what ends or pauses (Remote Control, running subagents, background commands); it never asks. +- Before each switch it prints what ends or pauses (Remote Control, running subagents, background commands). It never asks. - A statusline shows which account you're on and how much of its session and weekly limits is used, and warns you near the limit with the account that has the most room left. ## When to use @@ -154,7 +154,7 @@ flowchart TD Login, settings and transcripts belong to a config dir; some features belong to the claude.ai account that is logged in there. -Before every switch `/switch` prints a line for what ends or pauses (Remote Control, subagents, background commands); none of it stops the switch. The last two items below are only described here: +Before every switch `/switch` prints a line for what ends or pauses (Remote Control, subagents, background commands). None of it stops the switch. Artifacts, routines and connectors (the last two items below) are not printed: - **Remote Control** ends with the old Claude process. - When it was on, `/switch` says so. From a17398933fe07fe2898e2df5255ce54838132476 Mon Sep 17 00:00:00 2001 From: KrishP147 Date: Sat, 17 Oct 2026 03:10:43 -0400 Subject: [PATCH 03/16] docs(score-loop): example total uses kept fresh median (-47 ms, 11%) Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01WHwM2TcQBo9oHdCrYCtdMn --- score-loop/README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/score-loop/README.md b/score-loop/README.md index 2a157ae..41b7935 100644 --- a/score-loop/README.md +++ b/score-loop/README.md @@ -45,7 +45,7 @@ Pushes one numeric score up (or down) unattended. Claude tries one idea per comm 4. **Loop.** Picks the most promising idea from the Next ideas list, commits one change, runs the harness: - correctness fails → `git revert`, logged `invalid`, doesn't count toward K; - beats the best by more than the margin (a % of the current best) → kept; - - beats it by more than half the margin but not the full margin → **borderline**: reruns the best and the candidate N times each now, interleaved in ABBA order (best, candidate, candidate, best, ...), and keeps the candidate only if its fresh median beats the best's fresh median by more than half the margin, else `git revert`, logged `noise`; the row note logs both fresh medians; + - beats it by more than half the margin but not the full margin → **borderline**. It reruns the best and the candidate N times each, interleaved in ABBA order (best, candidate, candidate, best, ...). It keeps the candidate only if its fresh median beats the best's fresh median by more than half the margin; otherwise `git revert`, logged `noise`. The row note logs both fresh medians; - beats it by half the margin or less → `git revert`, logged `noise`; - worse → `git revert`, logged `revert`. 5. **Stops** @@ -93,7 +93,9 @@ flowchart TD - Seed the Next ideas list yourself; the loop reads it fresh before every experiment, so you can append while it runs. - The margin is a percentage of the best, so a big win late in the run isn't lost as noise once the score has shrunk. - Memoised calls (`lru_cache`) can score ~0: the harness must use fresh inputs or one process per run, and a near-zero score is suspect: invalid unless correctness proves otherwise. -- The margin is measured once, on the baseline. A borderline candidate (more than half the margin, not the full margin) costs N extra runs each of the best and the candidate, interleaved in ABBA order, so a too-wide baseline margin doesn't throw away a real gain, and machine drift (before or during the candidate's run) neither fakes a gain nor hides one: both fresh medians see the same drift. +- The margin is measured once, on the baseline. A borderline candidate (more than half the margin, not the full margin) costs N extra runs each of the best and the candidate, interleaved in ABBA order. + - That way a too-wide baseline margin doesn't throw away a real gain. + - Machine drift (before or during the candidate's run) neither fakes a gain nor hides one, because both fresh medians see the same drift. - A noisy grader means a wide margin and few keeps. Cut the noise at its source (fixed seeds, warm-up runs, an idle machine) rather than lowering the margin. - `parallel` above 1 runs variants in separate worktrees, but graders that share a machine get noisier. Leave it at 1 unless the grader is remote or cheap. - Set the quota to 0 if every official submission should ask you first. @@ -111,7 +113,7 @@ Writes a harness that checks the parser output against fixtures and reports the - Experiment 2 (bigger read buffer) gives 368 ms, within 2.2% of 371 (8 ms), and is reverted as `noise`. - Experiment 3 (skip validation) fails the correctness check and is reverted as `invalid`. - Experiment 4 (lazy token table) gives 364 ms, 1.9% better: borderline (between 1.1% and 2.2%), so it reruns the best and the candidate 5 times each in ABBA order (fresh medians 373 ms and 365 ms), and keeps it, since 365 beats 373 by 2.1%, more than 1.1%. -- After five more experiments without a keep it stops on plateau and appends a summary: two kept commits, -48 ms (12% faster). +- After five more experiments without a keep it stops on plateau and appends a summary: two kept commits, -47 ms (11% faster). ## Related From 8ae143838714c68fb8579bb8a111cfddf35dfd65 Mon Sep 17 00:00:00 2001 From: KrishP147 Date: Sat, 17 Oct 2026 03:10:43 -0400 Subject: [PATCH 04/16] docs(session-bridge,sitrep): match SKILL.md on snapshot and stalled agents Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01WHwM2TcQBo9oHdCrYCtdMn --- session-bridge/README.md | 5 +++-- sitrep/README.md | 8 ++++---- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/session-bridge/README.md b/session-bridge/README.md index 1cfcd11..c0f8cba 100644 --- a/session-bridge/README.md +++ b/session-bridge/README.md @@ -40,7 +40,8 @@ type the slash command. - Otherwise, fall back to that repo's transcripts under `~/.claude/projects//*.jsonl`. - `` is the working directory path with every character other than letters and digits replaced by `-`. - If no target is found, it says so and stops. -2. **Read-only snapshot.** Uses `ListAgents`/`SendMessage` if the session is reachable that way, or reads the other session's transcript with the bundled `scripts/snapshot.py`. It never dumps the raw `.jsonl` file (no `cat`). +2. **Read-only snapshot.** For a transcript, it runs the bundled `scripts/snapshot.py`. It never dumps the raw `.jsonl` file (no `cat`). + - Asking a live session for its status is a message, so that goes through the step 4 gate first. - Extracts only the last user ask, the last N actions, and any branches/PRs/files mentioned. - Also checks `git`, `gh pr`, and that repo's `skilleddocs/` for its handoff/ledger. - Redacts anything that looks like a secret, token, or personal data before repeating it. @@ -49,7 +50,7 @@ type the slash command. 5. **Send.** `SendMessage` if available and the target is reachable that way; otherwise appends to a shared `skilleddocs/bridge.md` as a drop-off, since there's no live channel to that session. 6. **Log.** Every exchange (sent and any reply) appended to `skilleddocs/bridge.md` with local timestamps, not UTC. 7. **Report.** The reply, if one arrives — or "no reply" if not. - - Notes when a session (cloud, Remote-Control, or transcript-only) can't reply by design. + - Notes when a session can't reply by design (cloud, Remote Control, or transcript-only). - Reads its transcript/handoff/PR instead where accessible. Reads: `ListAgents` (if available), transcript files under `~/.claude/projects/`, `git`, `gh`, a repo's `skilleddocs/`. diff --git a/sitrep/README.md b/sitrep/README.md index d865b40..4b30c1c 100644 --- a/sitrep/README.md +++ b/sitrep/README.md @@ -40,11 +40,11 @@ type the slash command. 1. **What's running.** Collects the IDs of background tasks from the conversation, skipping any whose completion notice already arrived. - Sources: `Bash`/`PowerShell` with `run_in_background`, `Monitor` loops, background `Agent` launches. - Reports each one's age and its last output line (read from the task's output file, or `TaskOutput`, now deprecated). - - Checks `ListAgents` (if available) for other agents you can message. + - Checks `ListAgents` (if available) and notes other agents that look stalled. 2. **Git.** For each repo this session ran git in (not only the current one): - `git worktree list`. - - Per worktree, `git status --porcelain` and `git status --porcelain --ignored -- skilleddocs` (handoffs in an excluded `skilleddocs/`, or an `AGENTS.md`-set handoff folder). - - Per worktree, unpushed commits (`git log ..`, `` = the upstream, else `origin/`, else `origin/`; never the local default branch, which hides commits made on it). + - Per worktree, `git status --porcelain` and `git status --porcelain --ignored -- skilleddocs`. The second one finds handoffs in an excluded `skilleddocs/`, or in a handoff folder set in `AGENTS.md`. + - Per worktree, unpushed commits: `git log ..`, where `` is the upstream, else `origin/`, else `origin/`. Never the local default branch, which would hide commits made on it. - No remote ref: unpushed is "unknown", and that blocks SAFE. - A branch with 0 commits and a clean tree has nothing to push; "never pushed" is only for commits with no `origin/`. 3. **PRs + CI.** `gh pr list --author @me` with checks status. @@ -59,7 +59,7 @@ type the slash command. Saved on disk means untracked (the only option on forks) or, in commit mode, a dated handoff left uncommitted on a task branch. That file doesn't count as dirty, and `sitrep` never suggests committing it. - An untracked handoff covers only the work it describes. - The verdict is NOT SAFE when its worktree is a non-main one or was made by pair/meta-orchestrator (it would be removed with the worktree), or when unsure. + It is lost if its worktree is removed, so the verdict is NOT SAFE when that worktree isn't the main one, was made by pair or meta-orchestrator, or when unsure. - Otherwise NOT SAFE, with the specific reasons. 7. **On "close" / "yes, stop them":** lists exactly what will be stopped and what (if anything) would be committed/pushed, and waits for an explicit yes before doing either. - On yes, stops background tasks with `TaskStop` (if available). From 04d5df84ee623de1732fe6213e5d4c50d7ed9078 Mon Sep 17 00:00:00 2001 From: KrishP147 Date: Sat, 17 Oct 2026 03:10:43 -0400 Subject: [PATCH 05/16] docs(skills): plainer wording, fix repo-scrub #update link, spend-gate HOOK.md link Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01WHwM2TcQBo9oHdCrYCtdMn --- pr-watch/README.md | 4 ++-- remind/README.md | 4 ++-- repo-scrub/README.md | 10 +++++----- repo-showcase/README.md | 4 ++-- spend-gate/README.md | 6 +++--- teammate-brief/README.md | 2 +- wayfinder/README.md | 6 +++--- 7 files changed, 18 insertions(+), 18 deletions(-) diff --git a/pr-watch/README.md b/pr-watch/README.md index 9fa9472..2321fb4 100644 --- a/pr-watch/README.md +++ b/pr-watch/README.md @@ -37,7 +37,7 @@ Watches your open pull requests (your own repo, or a fork against its upstream) - Classifies each unresolved one as valid / outdated / disagree / question. - Cites its thread URL. 3. **Read CI** (`gh pr checks`); a fork PR stuck at `action_required` is reported as waiting on maintainer approval, not as failing. -4. **Fix** the valid threads through [`pair`](../pair/) (one call per PR, every valid thread's path/line/body as the task), which reruns the tests. +4. **Fix** the valid threads through [`pair`](../pair/), which reruns the tests. One call per PR, with every valid thread's path, line and body as the task. - Where subagents can't be spawned, or `pair` isn't installed, it fixes inline on the head branch with the same gates. 5. **Gate.** Shows the diff summary and drafted replies, and asks before pushing or replying. - A force push needs its own fresh yes even if the push itself was already approved. @@ -46,7 +46,7 @@ Watches your open pull requests (your own repo, or a fork against its upstream) - Resolves only threads it just fixed or proved outdated by reading the current diff, and only after another explicit yes. - Never resolves a disagree/question thread, which gets a reply and stays open. 7. **Optional bot re-trigger** (`@coderabbitai review`), only on a fresh yes. - - Notes that bots frequently never run on fork PRs at all. + - Bots often never run on fork PRs at all; it says so. 8. **Watches** (`Monitor` or a bounded poll, never a blind sleep) until merged/closed/stopped, re-reading threads and CI every pass. 9. **Logs** every pass to `skilleddocs/pr-watch/-.md` in the repo you're working from, one file per PR repo. - Committed or untracked per [TRACKING.md](../handoff-auto/TRACKING.md) (always untracked on a fork). diff --git a/remind/README.md b/remind/README.md index 2d08f46..1bbf2a9 100644 --- a/remind/README.md +++ b/remind/README.md @@ -49,7 +49,7 @@ The skill turns your words into one `remind.py` command; the script does the res - A corrupt file is moved aside, never overwritten. - The script copies itself there too, so the hook survives skill updates. 4. **Desktop notification** for timed reminders. - - Windows: a one-shot scheduled task (`schtasks /Create /XML`, ISO start time, no locale date formats) showing a toast via PowerShell 5.1, `msg` as fallback. It runs late if the PC slept (within a day), then deletes itself. + - Windows: a one-shot scheduled task (`schtasks /Create /XML` with an ISO start time, so locale date formats don't matter). It shows a toast via PowerShell 5.1, with `msg` as fallback. If the PC slept, it runs late (up to a day), then deletes itself. - macOS/Linux: an `at` job running `osascript` or `notify-send`. No `at` (or no `notify-send`): in-session only, and `add` says so. - "Under N%" has no fixed time: always in-session only. 5. **In-session.** switch's `UserPromptSubmit` hook prints each due reminder once (next to its usage warning) and marks it done. @@ -77,7 +77,7 @@ Most runs pair it with `switch` around a usage limit. A few setups need one extra step. -- **Without switch**, `add` prints the exact hook command for your machine (absolute Python, forward slashes). Add it to `~/.claude/settings.json` only after your first `/remind` (which puts `remind.py` there): a missing script makes Python exit 2, which blocks the prompt. +- **Without switch**, `add` prints the exact hook command for your machine (absolute Python path, forward slashes). Add it to `~/.claude/settings.json` only after your first `/remind`, which puts `remind.py` in place. If the script is missing, Python exits 2, and that blocks the prompt. ```json {"hooks": {"UserPromptSubmit": [{"hooks": [{"type": "command", "command": "python3 ~/.claude-remind/remind.py hook", "timeout": 10}]}]}} diff --git a/repo-scrub/README.md b/repo-scrub/README.md index 6af13e8..54f3291 100644 --- a/repo-scrub/README.md +++ b/repo-scrub/README.md @@ -31,16 +31,16 @@ Defaults to the current repo. Only you can run it (`disable-model-invocation: tr 1. **Prereqs and target** — version-checks each tool (stops with the install command if one is missing), then `gh repo view … --json name,owner,isPrivate,defaultBranchRef` and confirms you accept a history rewrite + force-push. - `` is one `mktemp -d` path, echoed once. - - Lists every other remote in your clone (each is its own copy of the history, scanned, rewritten and pushed to on a yes). - - Lists every submodule (a separate repo to scrub on its own; relative URLs flagged). + - Lists every other remote in your clone. Each holds its own copy of the history, so it is scanned, rewritten and pushed to on a yes. + - Lists every submodule. Each is a separate repo to scrub on its own; relative URLs are flagged. 2. **Git LFS bail-out** — stops with a warning if the root `.gitattributes` shows LFS-tracked paths; `git filter-repo` has no LFS awareness. - The same check runs over all history in step 3 to catch nested files and other branches. 3. **Scan (throwaway clone #1)** - `gitleaks git --log-opts="--all -m"` (or `detect --source` pre-8.19) over all history, merge commits included (a secret added only in a conflict resolution is invisible without `-m`). - Other remotes' branches fetched in, `git filter-repo --analyze`. - [`scripts/summarize_findings.py`](scripts/summarize_findings.py) merges them into `findings.json`, written to a work dir *outside* the clone. - Secrets get IDs `S1…`: deduped by rule + value, or by location when the value is empty; fingerprint only, no raw value on disk. - Large blobs get IDs `L1…`: sized by bytes accumulated across all versions of that path in history. + Secrets get IDs `S1…`, deduped by rule and value (or by location when the value is empty). Only a fingerprint is stored; no raw value goes to disk. + Large blobs get IDs `L1…`, sized by the bytes of every version of that path in history added up. - Personal strings handed over by `repo-showcase` (or named by you) get a `git log --all -m -S''` and `--grep` check each, since gitleaks has no rule for names or emails; hits become `P1…`. - Emails in commit messages and author/committer identities other than yours are found the same way (`git log --all --format=…`). - Signed commits and tags are counted: a rewrite drops every signature. @@ -132,5 +132,5 @@ Defaults to the current repo. Only you can run it (`disable-model-invocation: tr ## Prereqs - `gh` (authenticated), [`gitleaks`](https://github.com/gitleaks/gitleaks), [`git-filter-repo`](https://github.com/newren/git-filter-repo), and Python for the helper scripts. -- Install commands are in the [top README](../README.md#install); the skill also prints the right one if a tool is missing. +- Install commands are in the [top README](../README.md#update); the skill also prints the right one if a tool is missing. - No separate sizing tool: before/after repo size comes from `git count-objects -vH`. diff --git a/repo-showcase/README.md b/repo-showcase/README.md index f29eec0..b7a383a 100644 --- a/repo-showcase/README.md +++ b/repo-showcase/README.md @@ -45,8 +45,8 @@ Defaults to the current repo. Claude also runs it when you say one of the phrase - One-line pitch. - Result. - Demo media placeholder(s) the user fills in themselves (never a fabricated screenshot/GIF/metric). - - Quickstart, actually run from a clean clone. Installs go in a temp prefix or venv, never global, and never by registry name unless that registry entry's repository URL is this repo. - - The quickstart result is reported; a step whose toolchain isn't installed on this machine is reported `not run: missing` and kept, never dropped. + - Quickstart, actually run from a clean clone. Installs go in a temp prefix or venv, never global. It installs by registry name only when that registry entry's repository URL is this repo. + - The quickstart result is reported. A step whose tool isn't installed on this machine is reported as `not run: missing` and kept, never dropped. - Architecture only if the audience needs it. - Credits. 5. **Scan for secrets and private names** diff --git a/spend-gate/README.md b/spend-gate/README.md index 2f7ef1a..a5c71c9 100644 --- a/spend-gate/README.md +++ b/spend-gate/README.md @@ -47,7 +47,7 @@ You can also run it directly: 6. **Run + remind** - run the approved action, then remind about teardown or an auto-stop/idle-timeout for anything left running. 7. **Approval token** - if `hooks/spend-guard.py` blocks the action, write - the approval it expects (see that hook's docs) only after step 4's yes. + the approval it expects (see [HOOK.md](HOOK.md)) only after step 4's yes. ## Design principles @@ -65,8 +65,8 @@ You can also run it directly: - About to provision a GPU pod for a training/eval run. - About to call a paid API in a loop (batch scoring, embeddings) where the per-call cost adds up. -- Reviewing whether a repo's existing spend approvals in `skilleddocs/ - spend.md` still look right before continuing a paused job. +- Reviewing whether a repo's existing spend approvals in + `skilleddocs/spend.md` still look right before continuing a paused job. ## Tips diff --git a/teammate-brief/README.md b/teammate-brief/README.md index 7b412e3..8f3afdc 100644 --- a/teammate-brief/README.md +++ b/teammate-brief/README.md @@ -48,7 +48,7 @@ Claude also runs it when you say one of the phrases above. 5. **Ownership map** — area/path -> who to ask. 6. **Don't-touch list** — what to leave alone and why, per item. 7. **Draft, then write** — shows the full draft before writing. - - Saves to `skilleddocs/briefs/-.md` on confirmation (`teammate` when no name was given). + - On your yes, saves it to `skilleddocs/briefs/-.md`. With no name given, `` is `teammate`. 8. **Gate.** - Commits only when [`TRACKING.md`](../handoff-auto/TRACKING.md) allows it and on yes. - Pushes only on a separate yes. diff --git a/wayfinder/README.md b/wayfinder/README.md index e553d07..4a3f6e7 100644 --- a/wayfinder/README.md +++ b/wayfinder/README.md @@ -29,9 +29,9 @@ User-invoked only (`disable-model-invocation: true`): - Then grills you to name the destination, then grills breadth-first for the open decisions. - Creates the map issue (Destination, Notes, Decisions so far, Not yet specified, Out of scope), creates the tickets it can phrase now as sub-issues, then wires blocking with GitHub's issue-dependencies API (`Blocked by: #n` body lines if that API is unavailable). - Fires one `general-purpose` subagent per research ticket. -2. **Work**: loads the map, picks the first open, unblocked, unassigned ticket (a ticket you name that is claimed by someone else or blocked: it asks first), assigns it to you (the claim), and resolves it by type: - - `wayfinder:research`: a subagent with web search; findings go in the resolution comment (long ones split over several comments, or a committed file if the repo tracks it; a gist only on your yes naming its content and destination; never a link to an untracked file). - - `wayfinder:prototype`: a rough artifact you react to, inline in the comment or a committed file (a gist only on your yes; one needing its own branch: it asks you). +2. **Work**: loads the map and picks the first open, unblocked, unassigned ticket. If you name a ticket that someone else claimed or that is blocked, it asks first. It assigns the ticket to you (the claim) and resolves it by type: + - `wayfinder:research`: a subagent with web search. Findings go in the resolution comment; long ones are split over several comments, or go in a committed file if the repo tracks it. A gist only on your yes naming its content and destination. Never a link to an untracked file. + - `wayfinder:prototype`: a rough artifact you react to, inline in the comment or a committed file. A gist only on your yes; if it needs its own branch, it asks you. - `wayfinder:grilling`: runs `grill-docs`; transcript where `grill-docs` puts it, linked only once committed. - `wayfinder:task`: the manual work a decision waits on. If it needs you, you get a checklist; the ticket stays claimed and open until you report it done. 3. **Record**: From c74adb136b787948eaf1448b421e37a149f5abac Mon Sep 17 00:00:00 2001 From: KrishP147 Date: Sat, 17 Oct 2026 03:10:52 -0400 Subject: [PATCH 06/16] docs(gap-scan,lanes,progress-report): match SKILL.md (lists issues, decrease is -1, watermark timestamp) Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01WHwM2TcQBo9oHdCrYCtdMn --- gap-scan/README.md | 21 ++++++++++----------- lanes/README.md | 4 ++-- progress-report/README.md | 11 ++++++----- 3 files changed, 18 insertions(+), 18 deletions(-) diff --git a/gap-scan/README.md b/gap-scan/README.md index e2347d6..a113844 100644 --- a/gap-scan/README.md +++ b/gap-scan/README.md @@ -21,10 +21,9 @@ and extension ideas. - Starting cold on a repo you (or someone else) haven't touched in a while and want a prioritized starting point instead of reading everything by hand. -- Not for picking the next task off an existing board — that's - [`kanban/next`](../kanban/next/) reading the board this skill's output can - seed. Not for watching an open PR to merge — that's - [`pr-watch`](../pr-watch/). +- Not for picking the next task off an existing board: that's + [`kanban/next`](../kanban/next/). This skill's output can seed that board. + Not for watching an open PR to merge: that's [`pr-watch`](../pr-watch/). ## How to invoke @@ -43,8 +42,8 @@ phrases above work without the slash command. - No upstream or no remote: skip the pull and say so. - Otherwise `git pull --ff-only` (a diverged history is reported the same as dirty, never force-merged). - - A fork also fetches `upstream`, reports how far ahead/behind it is, and - pulls upstream's own `good first issue`-labeled issues. + - A fork also fetches `upstream`, reports how far ahead or behind it is, + and lists upstream's open `good first issue` issues. 2. **Survey.** - README and docs (flagging doc/code drift). - The last ~20 commits (default; `--commits` overrides). @@ -59,9 +58,9 @@ phrases above work without the slash command. a screenshot capability if this session has one; skipped (with a reason) for libraries, CLIs, and backend-only services, or when no such tool is available. -4. **Rank and tag.** Every surviving candidate gets a value/effort - trade-off, an `S`/`L` size tag, and mandatory evidence — no evidence, no - listing. A secret is cited by `file:line` or SHA, never by its value. +4. **Rank and tag.** Each candidate is ranked by value against effort and + tagged `S` or `L` for size. Each needs evidence; without it, it isn't + listed. A secret is cited by `file:line` or SHA, never by its value. 5. **Write.** One file, `skilleddocs/gaps/.md` — the only write this skill makes. Never committed unless asked; `skilleddocs/` is excluded per [`TRACKING.md`](../handoff-auto/TRACKING.md). @@ -80,8 +79,8 @@ skill. Writes: `skilleddocs/gaps/.md` only. - **Evidence or it doesn't exist.** A ranked list that can't be traced back to a line, a commit, or an issue is just opinion; this skill would rather under-report than pad the list. -- **Don't re-litigate the board.** Cross-checking open issues before - ranking means the output adds to a backlog instead of duplicating it. +- **Don't repeat the board.** It checks open issues before ranking, so the + output adds to a backlog instead of duplicating it. - **Report, then stop.** Surveying and proposing is the whole job; turning a proposal into an issue or a PR is a separate, explicitly gated step (or another skill's, via the hand-offs at the end of the report). diff --git a/lanes/README.md b/lanes/README.md index ee8e63f..29aa68a 100644 --- a/lanes/README.md +++ b/lanes/README.md @@ -22,7 +22,7 @@ Sets how many issues a [`meta-orchestrator`](../meta-orchestrator/) run works on ``` - `/lanes 3`: regroup the queue into 3 lanes. -- `/lanes increase` / `decrease`: usually ±1, chosen and explained by the model. +- `/lanes increase`: usually one more lane. `/lanes decrease`: one fewer. Claude picks which lanes change and explains why. Also model-invocable: meta-orchestrator's setup calls it for `parallel:`. @@ -38,7 +38,7 @@ Also model-invocable: meta-orchestrator's setup calls it for `parallel:`. - Issues whose file sets overlap share a lane, in queue order; the groups left are the independent streams. - Lanes get area names (`site`, `hooks`), not numbers. 4. **Picks the count.** - - Asking for more lanes than there are independent streams, or more than 4, gets questions: a best-guess grouping and the options, never a silent cap. + - Ask for more lanes than there are independent streams, or more than 4, and it asks you first: it shows a best-guess grouping and the options. It never caps the count silently. - `increase` usually adds one by splitting the longest lane on file-disjoint issues. - `decrease` merges two colliding lanes, or folds the shortest into the nearest. 5. **Proposes.** diff --git a/progress-report/README.md b/progress-report/README.md index 3fe8e47..5d8c2e2 100644 --- a/progress-report/README.md +++ b/progress-report/README.md @@ -31,9 +31,10 @@ Claude also runs it when you ask for "an update doc". 1. **Find the source.** Reports folder (default the repo's `skilleddocs/reports/`); ledger at `skilleddocs/orchestrator/ledger.md`. - No ledger → reconstructs one from `git log`, merged PRs, issues and the conversation, and says so. -2. **Watermark.** `.last-reported` holds ` `, NNN = last reported ledger entry. - - The new report covers `watermark + 1 … latest` (a restarted ledger, numbered from 001 again, is caught by the timestamp and covered from 001). - - It also covers any commits or merged PRs since the watermark with no ledger entry, marked "not in ledger" (the reporting commits themselves are skipped). +2. **Watermark.** `.last-reported` records where the last report stopped: ` `, where NNN is the last reported ledger entry. + - The new report covers entries `NNN + 1` through the latest. + - If a new run restarted the ledger at 001, the stored timestamp no longer matches, so the report covers the ledger from 001. + - It also covers commits or merged PRs since the watermark that have no ledger entry, marked "not in ledger". The reporting commits themselves are skipped. - Earlier items only reappear under "Revisions to earlier reports" if they changed (revert, reversed decision, broken "done"). 3. **Fixed sections.** Empty → "none". - Header (report number, date, time range in your local zone, ledger range). @@ -55,7 +56,7 @@ Claude also runs it when you ask for "an update doc". - Never overwrites an earlier report. - Reads it back to check. 6. **Advance the watermark.** Updates `.last-reported`, appends a `report` entry to the ledger. - - In commit mode it commits them with the report: on the default branch, or on its docs branch when the default is protected ([`TRACKING.md`](../handoff-auto/TRACKING.md)). + - In commit mode it commits them with the report, on the default branch. If the default branch is protected, it commits on a docs branch instead ([`TRACKING.md`](../handoff-auto/TRACKING.md)). - Prints the path and entry range. Reads: `skilleddocs/orchestrator/ledger.md`, `.last-reported`, git/gh. @@ -91,7 +92,7 @@ Writes: the report, `.last-reported`, a ledger entry. Watermark says 5; ledger is at 22. - Writes `skilleddocs/reports/002-2026-09-23-auth-and-export.md` covering entries 6–22 (Done table with 4 merged PRs, one flaky-CI item under "What didn't", two decisions made on your behalf). -- Sets `.last-reported` to `022 002-2026-09-23-auth-and-export.md`. +- Sets `.last-reported` to `022 002-2026-09-23-auth-and-export.md` plus entry 022's timestamp. - Appends a `report` ledger entry. - Prints the path. From 4ea01b4beab23a1cb3553cd84308a69f10b9f6c7 Mon Sep 17 00:00:00 2001 From: KrishP147 Date: Sat, 17 Oct 2026 03:10:53 -0400 Subject: [PATCH 07/16] docs(skills): split dense bullets, plainer wording Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01WHwM2TcQBo9oHdCrYCtdMn --- find-me-a-skill/README.md | 22 +++++++++++----------- grill-docs/README.md | 6 +++--- handoff-auto/README.md | 6 +++--- handoff/README.md | 4 ++-- meta-orchestrator/README.md | 16 ++++++++-------- pair/README.md | 23 +++++++++++++---------- 6 files changed, 40 insertions(+), 37 deletions(-) diff --git a/find-me-a-skill/README.md b/find-me-a-skill/README.md index bd18fef..aa9c30b 100644 --- a/find-me-a-skill/README.md +++ b/find-me-a-skill/README.md @@ -46,19 +46,19 @@ uses the conversation's goal, then the board. - The primary pick is the best fit from everything installed. - When an entry or workflow from this collection fits and isn't already the pick, it adds that too. - - Any option from the catalog is labelled "from your collection"; one that - isn't in this session's skill list and isn't in - `~/.claude/skills//` or the plugin's install dir (that check is - skipped, and said so, when the plugin isn't installed) is labelled "not - installed" with the install command (user-only skills never show in - that list, installed or not). + - Any option from the catalog is labelled "from your collection". + - A catalog option is labelled "not installed", with the install command, + when it isn't in this session's skill list, in + `~/.claude/skills//` or in the plugin's install dir. With no + plugin installed, that last check is skipped and the reply says so. + User-only skills never show in the session's list, installed or not. - Plugin installs get the `krish:` prefix on commands. - Nothing fits: it says so, names the nearest option and suggests doing the task directly. 4. **Model and effort per step.** - - From `CATALOG.md`'s defaults, adjusted for a large or risky task: effort - goes up first, the model only once effort is at `max`; the reverse for a - small one. + - Starts from `CATALOG.md`'s defaults. For a large or risky task, effort + goes up first, and the model only once effort is at `max`. A small task + works the same way in reverse. - A skill that isn't in the catalog shows its origin (plugin or built-in) and an `estimate` label. 5. **Reply.** Per option: why it fits, the steps with model and effort, @@ -73,8 +73,8 @@ Writes: nothing. - **Suggest, don't run.** It runs on Haiku at low effort, so it must not start heavy work by accident; you start it by pasting the commands. - **One generated catalog.** `CATALOG.md` is generated from the repo - (`python scripts/site_catalog.py`) and a test fails when it drifts, so - the skill works offline in any repo and its defaults match the site's + (`python scripts/site_catalog.py`), and a test fails when it drifts. So + the skill works offline in any repo, and its defaults match the site's "suggested model · effort" chips. - **Broad first, own collection second.** The best tool for the task wins even when it's a plugin or built-in; this collection gets a second slot diff --git a/grill-docs/README.md b/grill-docs/README.md index 86d0be2..c6e917f 100644 --- a/grill-docs/README.md +++ b/grill-docs/README.md @@ -26,9 +26,9 @@ Runs the `grilling` interview on a plan or decision and leaves a paper trail in - a `### Q` block (topic / asked / recommended / answer / why) to the transcript - one `| D | date | decision | why | source |` row to the decisions doc (created with a header if missing) - `Q` counts across the whole session. - - The heading is bare `### Q` so the register's `grills/#q` source resolves on GitHub (anchors are lowercase). + - The heading is just `### Q`, so the register's source link (`grills/#q`) works on GitHub, where anchors are lowercase. - Delegated answers ("go with your recs") are recorded as `(delegated)`. -4. When the frontier is empty and you confirm: sets `Status: settled`, adds `## Summary` and `## Open`, prints both paths. Nothing is committed unless you ask. +4. When no open questions are left and you confirm: sets `Status: settled`, adds `## Summary` and `## Open`, prints both paths. Nothing is committed unless you ask. Writes `skilleddocs/grills/-.md` and the decisions doc: @@ -50,7 +50,7 @@ Writes `skilleddocs/grills/-.md` and the decisions doc: ## Tips -- To control the transcript filename, put a kebab-case slug after a doc path or a quoted subject (`/grill-docs "our caching plan" cache-plan`); otherwise Claude picks 2 to 4 topic words, and a hyphenated last word of a plain sentence (`e-books`) stays in the subject. +- To set the transcript filename, put a kebab-case slug after a doc path or a quoted subject (`/grill-docs "our caching plan" cache-plan`). Otherwise Claude picks 2 to 4 topic words. A hyphenated last word in a plain sentence (`e-books`) stays part of the subject, not the slug. - Register tracked (say `docs/decisions.md`) but `skilleddocs/` not: the transcript goes in `docs/grills/` instead, so the rows' Source links work once you commit both. - "Go with your recs" is fine: delegated answers are recorded as `(delegated) `, so the register stays complete. - Files are left uncommitted unless you ask; commit them yourself if the repo tracks `skilleddocs/`. diff --git a/handoff-auto/README.md b/handoff-auto/README.md index 5d953fb..66e7db3 100644 --- a/handoff-auto/README.md +++ b/handoff-auto/README.md @@ -25,8 +25,8 @@ Claude can call it: another skill uses the Skill tool with `handoff-auto`. The o 1. Summarises the conversation into a document under the repo's **`skilleddocs/handoffs/`** (OS temp dir only when there is no repo). - Committed or left untracked per [`TRACKING.md`](TRACKING.md). - - Commit only if the repo already tracks `skilleddocs/` (or the `AGENTS.md` handoff folder) or opts in, never on a fork. -2. Records the git state and adds a "suggested skills" section. + - Committed only if the repo already tracks `skilleddocs/` (or the handoff folder `AGENTS.md` sets), or its `AGENTS.md`/`CLAUDE.md` opts in. Never on a fork. +2. Adds a "suggested skills" section and records the git state: - Branch. - Base SHA (`git merge-base HEAD`; on the default branch itself, the upstream or the parent of the session's first commit). - Head SHA. @@ -39,7 +39,7 @@ Claude can call it: another skill uses the Skill tool with `handoff-auto`. The o ## Design principles - **An ending a program can read.** The absolute path is always the very last line, so a calling skill or orchestrator never has to guess. -- **Same document as `handoff`.** Only the frontmatter, save location, tracking sentence, a git-state line (branch, base SHA, head SHA) and the final path line differ from the original, so a manual and an unattended handoff read the same. +- **Same document as `handoff`.** Only five things differ from the original: the frontmatter, the save location, the tracking sentence, a git-state line (branch, base SHA, head SHA) and the final path line. So a manual and an unattended handoff read the same. - **Shared tracking rule.** Commit or not comes from [`TRACKING.md`](TRACKING.md), the single source for every file under `skilleddocs/`. ## Use cases diff --git a/handoff/README.md b/handoff/README.md index bf12b97..1b102bf 100644 --- a/handoff/README.md +++ b/handoff/README.md @@ -24,9 +24,9 @@ Turns this conversation into a handoff document. A fresh session can pick up the ## How it works 1. Summarises the conversation into a document saved in the repo under **`skilleddocs/handoffs/-.md`** (OS temp dir only when there is no repo). - - Committed only if the repo already tracks `skilleddocs/` (or the `AGENTS.md` handoff folder) or opts in, never on a fork. + - Committed only if the repo already tracks `skilleddocs/` (or the handoff folder `AGENTS.md` sets), or its `AGENTS.md`/`CLAUDE.md` opts in. Never on a fork. - Otherwise left untracked and git-excluded ([`TRACKING.md`](../handoff-auto/TRACKING.md)). -2. Records the git state and adds a "suggested skills" section naming skills the next session should load. +2. Adds a "suggested skills" section naming skills the next session should load, and records the git state: - Branch. - Base SHA (`git merge-base HEAD`; on the default branch itself, the upstream or the parent of the session's first commit). - Head SHA. diff --git a/meta-orchestrator/README.md b/meta-orchestrator/README.md index 7d26f25..83699a8 100644 --- a/meta-orchestrator/README.md +++ b/meta-orchestrator/README.md @@ -52,13 +52,13 @@ Almost every behaviour is a setting you pick on the first run. - `planner` → kickoff brief with the issue's size (a `size:*` label wins over its rating) and a recommended shape; then by `shape` ([`SKILL.md`](SKILL.md) §2): - `pair` (default) runs a `manager` per issue - `flat` an `implementer` directly - - `swarm` one `haiku` implementer per trivial item, each in its own worktree off one batch branch, one `parallel` slot each, merged into the batch branch, then one opus review at the merge gate and one PR + - `swarm` runs one `haiku` implementer per trivial item. Each item gets its own worktree off one batch branch and takes one `parallel` slot, and is merged into the batch branch. The batch then gets one opus review at the merge gate and one PR - `auto` takes the planner's pick per brief - Implementer model by size: trivial → haiku, small/medium → sonnet, large or risky → opus, unless the brief or `implementer_model` says otherwise. - - `verifier`; mechanical chores go to `general-purpose` on `haiku`, never judgment or the merge gate. + - Then `verifier`. Mechanical chores go to `general-purpose` on `haiku`; judgment calls and the merge gate never do. - Each step is a fresh Agent call. - - Agents run code review inline (nested fan-out stalls). - - An **INTERIM** report is not a result, nor is a manager handback missing its Branch, Tests or Rounds section (asked once, then rerun). + - Agents run code review inline, because agents spawning their own reviewers stall. + - An **INTERIM** report is not a result. Neither is a manager handback missing its Branch, Tests or Rounds section: the orchestrator asks once for the full report, then reruns. 2. **Loop:** `planner → manager | implementer | swarm → merge gate → verifier → repeat`. - Parallel issues each get their own worktree. - With `parallel > 1`, [`lanes`](../lanes/) groups the queue into file-disjoint lanes, each working its issues in order; `/lanes` changes them mid-run. @@ -66,14 +66,14 @@ Almost every behaviour is a setting you pick on the first run. - Tests/CI green for the head SHA. - Diff skimmed for scope creep, secrets, drift and anything on your pause list. - Push, then merge per your `merge` setting. - - Worktree torn down links-first; ledger entry. + - Worktree torn down, unlinking dependency links before removing it; ledger entry. 4. **Autonomy.** - One retry per failure, then split or park, never loop. - - `decisions: assume` lets agents pick their recommendation for calls with no written answer (unlike `interview: answer`, which answers from the written plan) and log an open `A-n` for you to confirm; listed in every handoff and report. - - The `guard-git.py` hook blocks agents from pushing default or merging. + - `decisions: assume` covers calls the written plan doesn't answer. Agents pick their own recommendation and log it as an open `A-n` for you to confirm. Open `A-n` items are listed in every handoff and report. (`interview: answer` is different: it answers only from the written plan.) + - The `guard-git.py` hook blocks agents from pushing to the default branch or merging. 5. **Ledger.** Append-only `skilleddocs/orchestrator/ledger.md`, local timestamps, committed per entry (unless you chose uncommitted docs). 6. **Rotation** ([`ROTATION.md`](ROTATION.md)). - - After `handoff_budget` merges or a smart-zone warning (with lanes, once every in-flight lane has merged or parked): writes `orchestrator-handoff.md`, logs it, optionally runs a progress report, stops. + - After `handoff_budget` merges, or a smart-zone warning that its context is getting full (with lanes, once every in-flight lane has merged or parked): writes `orchestrator-handoff.md`, logs it, optionally runs a progress report, stops. - `resume` picks up from there. 7. **Done** when every in-scope issue is closed or parked with a reason (or `stop` is reached), default is green, every merge has a verify entry. diff --git a/pair/README.md b/pair/README.md index da7b3e4..d28a3e5 100644 --- a/pair/README.md +++ b/pair/README.md @@ -35,20 +35,23 @@ Model-invocable, so "pair on issue 12" also works. 2. **Isolate.** - `git worktree add ../_worktrees/- -b / ` (slug = `issue--`). - Reuses an existing worktree/branch if present. - - A relative `origin` URL (`../origin.git`) is first made absolute with `git remote set-url` (same target), since a worktree resolves it from its own root. - - Deps (`node_modules`/`.venv`) are linked from the main checkout (a `mklink /J` junction on Windows, paths built with `cygpath -wa` and run with `MSYS_NO_PATHCONV=1` from Git Bash, refused unless both paths are absolute; `ln -s` elsewhere), not reinstalled. - - For an issue, your session then marks it started (card → In Progress, or `status:todo` → `status:in-progress`, creating that label first if missing; skipped with no board) and comments "Started on branch …"; a board error is reported, never blocking. + - A relative `origin` URL (`../origin.git`) would break inside a worktree, which resolves it from its own root. So it is first made absolute with `git remote set-url` (same target). + - Deps (`node_modules`/`.venv`) are linked from the main checkout, not reinstalled: `ln -s` on mac/linux, a `mklink /J` junction on Windows. On Windows it refuses unless both paths are absolute; from Git Bash it builds them with `cygpath -wa` and runs with `MSYS_NO_PATHCONV=1`. + - For an issue, your session then marks it started: card → In Progress, or label `status:todo` → `status:in-progress` (creating that label first if missing). It also comments "Started on branch …". No board: skipped. A board error is reported and never blocks the task. 3. **Delegate.** One `Agent(subagent_type="manager")` call with working dir, task + checklist, verified/missing files, rules, implementer model, `max_rounds: 3`, "never push, merge, or open a PR". Not `fork`. 4. **On return.** - - Ignores a report titled **INTERIM** (implementer still running) and waits for the manager's next handback; a handback without its Branch, Tests and Rounds sections (a placeholder) is no result either: it asks once, then reruns. - - Then shows the manager's report verbatim; reruns tests if the report is thin or risky; if `skilleddocs/HANDOFF.md` exists (unfinished), offers another round. - - Before pushing, checks `git diff --name-only ...HEAD` carries no `skilleddocs/HANDOFF.md` and, in commit mode, nothing in the handoff folder (`AGENTS.md`/`CLAUDE.md`'s, else `skilleddocs/handoffs/`; nothing under `skilleddocs/` or that folder when handoffs are untracked, always the case on a fork; see [`TRACKING.md`](../handoff-auto/TRACKING.md)) and removes any hit in a commit. + - A report titled **INTERIM** means the implementer is still running: it waits for the manager's next handback. A handback missing its Branch, Tests or Rounds section (a placeholder) is no result either: it asks once, then reruns. + - Then it shows the manager's report verbatim. It reruns the tests if the report is thin or the change risky. If `skilleddocs/HANDOFF.md` exists (unfinished), it offers another round. + - Before pushing, it checks `git diff --name-only ...HEAD` for files that must not ship, and removes any hit in a commit ([`TRACKING.md`](../handoff-auto/TRACKING.md)): + - `skilleddocs/HANDOFF.md`, always. + - In commit mode, anything in the handoff folder (`AGENTS.md`/`CLAUDE.md`'s, else `skilleddocs/handoffs/`). + - When handoffs are untracked (always the case on a fork), anything under `skilleddocs/` or that folder. - Pushes + `gh pr create … Closes #` on `--push` or your go. Never merges. - PR review feedback later → step 3 again in the same worktree. 5. **Print.** - Branch, worktree path, PR URL (or "not pushed"), test result, rounds used, `skilleddocs/HANDOFF.md` path. - Doesn't clean up the worktree until the PR merges. - - Then it moves the worktree's dated handoffs into the main checkout's handoff folder (where `update-progress` finds them), unlinks `node_modules`/`.venv` (link only, never a recursive delete) and runs `git worktree remove` only after a check confirms neither path is left, dangling links included. + - After the merge, it moves the worktree's dated handoffs into the main checkout's handoff folder, where `update-progress` finds them. It then unlinks `node_modules`/`.venv` (the link only, never a recursive delete). It runs `git worktree remove` only after a check confirms neither link is left, dangling links included. - Never `--force`: if git still refuses, it stops and reports what's left. Writes: a worktree + branch; commits (via agents); `skilleddocs/HANDOFF.md` in the worktree if unfinished (untracked unless the repo tracks `skilleddocs/`; never pushed). @@ -83,10 +86,10 @@ flowchart TD - Set your branch prefix in your `CLAUDE.md`; otherwise branches start with `feat/`. - An **INTERIM** report means the implementer is still running; wait for the real one. -- Decisions register in an untracked `skilleddocs/`: the brief passes main's header so every assumed `A-n` is a row teardown can carry. - - A heading or prose entry stops teardown with the lines listed instead of being lost; turn them into rows and rerun. +- If the decisions register lives in an untracked `skilleddocs/`, the brief passes the main checkout's register header. That way each assumed decision (`A-n`) is written as a row teardown can copy back to main. + - A heading or prose entry stops teardown, which lists those lines instead of losing them. Turn them into rows and rerun. - Leave the worktree alone while the manager runs. -- Tear down only after the PR merges, with the exact commands in `TEARDOWN.md`: move every untracked record in the worktree's doc folders (dated handoffs, `HANDOFF.md` renamed to a dated handoff, decisions register rows) to the main checkout without overwriting, unlink, check that no link and no record is left, then `git worktree remove`. +- Tear down only after the PR merges, with the exact commands in `TEARDOWN.md`. In order: move every untracked record in the worktree's doc folders to the main checkout without overwriting (dated handoffs, `HANDOFF.md` renamed to a dated handoff, decisions register rows); unlink the deps; check that no link and no record is left; then `git worktree remove`. - `git worktree remove` deletes git-excluded files silently, so a record left behind is lost. - Never remove the worktree while a link exists: `git worktree remove` or a recursive delete follows it and empties the main checkout's copy. - Unfinished after 3 rounds? Accept the offer of another round; it restarts from `skilleddocs/HANDOFF.md`. From e3d6adacca2578829f4ad414958727b26402557d Mon Sep 17 00:00:00 2001 From: KrishP147 Date: Sat, 17 Oct 2026 03:10:59 -0400 Subject: [PATCH 08/16] docs(agents): drop D373 id, verifier not guarded, plainer bullets Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01WHwM2TcQBo9oHdCrYCtdMn --- agents/README.md | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/agents/README.md b/agents/README.md index 14af9f5..ea2fd67 100644 --- a/agents/README.md +++ b/agents/README.md @@ -78,7 +78,7 @@ Needs: `handoff-auto`, `kanban-setup`, `next`, `session-handoff`, `implementer`, - Only with no notification path does it return **INTERIM — implementer still running** (callers must not act on it). 4. Reviews every round itself, inline: - Commit scope, `git diff ...HEAD`, reruns tests + lint. - - Checks `git diff --name-only ...HEAD` carries no `skilleddocs/HANDOFF.md` (nothing in the handoff folder, `AGENTS.md`/`CLAUDE.md`'s else `skilleddocs/handoffs/`, in commit mode; nothing under `skilleddocs/` or that folder when untracked). + - Checks that `git diff --name-only ...HEAD` holds no handoff files: never `skilleddocs/HANDOFF.md`. When handoffs are committed, nothing in the handoff folder (the one `AGENTS.md`/`CLAUDE.md` names, else `skilleddocs/handoffs/`). When they are untracked, nothing under `skilleddocs/` or that folder. - Fixes one-liners; larger gaps go to the next round. - Never spawns reviewer subagents. 5. Retries with a **fresh** implementer + `skilleddocs/HANDOFF.md`/findings, up to `max_rounds`; deletes `HANDOFF.md` once picked up (in a commit if tracked). @@ -120,13 +120,13 @@ Needs: `handoff-auto`, `kanban-setup`, `next`, `session-handoff`, the `guard-git - **You pass:** the kickoff brief verbatim + branch prefix + protected branch + `decisions` (from `manager` or the orchestrator). - **How it works:** - Branches off a freshly pulled default (the brief's Branch verbatim, else `/issue--`). - - If it created the branch, lists "card → In Progress + comment "Started on branch …"" as a manual step in its handoff (its `gh` is read-only, so its caller does it). + - If it created the branch, its handoff lists a manual step for the caller: move the card to In Progress and comment "Started on branch …". Its own `gh` is read-only. - Commits small. - Runs the repo's detected test command before claiming done. - Multi-session task or low turns → writes the handoff early. - Stuck or past ~100k tokens: writes `skilleddocs/HANDOFF.md` (done / not done / next step / failed attempts), then stops, so a manager can restart a fresh implementer from it. It commits that file only if [`TRACKING.md`](../handoff-auto/TRACKING.md) says so (never on a fork). - **You get back:** - - Calls `session-handoff` (which wraps `handoff-auto`). + - A handoff written by `session-handoff` (which wraps `handoff-auto`). - Final message ends with the handoff document's absolute path on its own line. - The handoff cites any open `A-n` it assumed. - **Guard:** `guard-git.py` hook (below). @@ -153,7 +153,7 @@ Needs: `consult-plan`, `next`, `update-progress`, the `guard-git` hook (installe - **Role:** verifies an implementation session and closes the loop. - `maxTurns: 120`. - - No guard hook. + - The guard hook doesn't apply to it. - **You pass:** - Handoff path (or saved manager report path). - Whether it may answer interview-style questions on your behalf. @@ -191,8 +191,8 @@ Needs: `consult-plan`, `next`, `update-progress`, the `guard-git` hook (installe **As a plugin.** Claude Code ignores `hooks` frontmatter in plugin agents, so the plugin wires the same command once, plugin-wide, in [`.claude-plugin/plugin.json`](../.claude-plugin/plugin.json), with `--plugin`. -- That hook fires for every session, so with `--plugin` it reads `agent_type` from the hook input and enforces only for `implementer`/`manager` (bare or `:`-prefixed); the main session and other agents pass through (exit 0). -- Without Python 3.8+ the plugin command can't run guard-git, so it greps the hook input for the same `agent_type` match: those two agents are blocked (exit 2), everything else passes (exit 0), so a missing Python never locks your own session's Bash. +- That hook fires in every session. With `--plugin` it reads `agent_type` from the hook input and enforces only for `implementer`/`manager` (bare or `:`-prefixed); the main session and other agents pass through (exit 0). +- Without Python 3.8+ the plugin command can't run guard-git. It then greps the hook input for the same `agent_type` match: those two agents are blocked (exit 2) and everything else passes (exit 0). A missing Python never locks your own session's Bash. **It is a guardrail, not a sandbox.** It stops an agent's honest mistakes and the obvious workarounds. @@ -211,13 +211,16 @@ Needs: `consult-plan`, `next`, `update-progress`, the `guard-git` hook (installe - **Card moves, issue comments and labels belong to the caller** (orchestrator, `pair`, verifier; none is guarded): implementer and manager list them in their handoff. - `gh api` is GET only: a non-GET method, or `-f`/`-F`/`--input` without `-X GET` (they imply POST), blocks; `gh api graphql` allows only a literal read query (no `mutation`). - `curl`/`wget`/`iwr`/`irm` to any `github.com` host (`github.com`, `api.github.com`, `uploads.github.com`) or `/api/v3/`: GET/HEAD only; any URL naming `git-receive-pack` (smart-HTTP push) blocks whatever the method. -- local git (add, commit, branch, merge, rebase, stash, worktree, fetch, pull, checkout/switch, tag, …) stays allowed; `git send-pack`/`http-push` and an unknown git subcommand or `git-*` plugin that names push/merge/sync/delete/ship/land/submit/publish/deploy/traverse/propose (`git subtree push`, `git ship`, `git-ship origin main`) block; commands git runs for you (`rebase -x`, `submodule foreach`, `bisect run`, `-c key=`) are read like any other command. +- local git (add, commit, branch, merge, rebase, stash, worktree, fetch, pull, checkout/switch, tag, …) stays allowed. These block: `git send-pack`/`http-push`, and an unknown git subcommand or `git-*` plugin that names push/merge/sync/delete/ship/land/submit/publish/deploy/traverse/propose (`git subtree push`, `git ship`, `git-ship origin main`). Commands git runs for you (`rebase -x`, `submodule foreach`, `bisect run`, `-c key=`) are read like any other command. - third-party push/merge/PR tools (#202) block their remote writes, reads pass: - `hub push|api|merge|fork|create|pull-request|sync|delete` and `hub pr|issue|release|gist` writes (hub is read as git too), `git town ship|sync|propose`, `gt`/`graphite submit|ss|merge|sync|land`, `ghstack` (bare = submit) `land|submit`, Sapling `sl push|pr|ghstack` (Bash only; PowerShell `sl` is Set-Location), `spr`/`git spr land|update|diff|merge`, `git machete traverse|github|gitlab`, `jj git push`, `arc land|diff`, and `gh-pages` (bin or `npx gh-pages`) on every run. - `hub status`, `gt log`, `sl log`, `git town status`, `git machete status`, `hub pr list` pass. - - Any other program whose arguments pair a push-like verb (push/ship/land/submit/sync/merge/publish/deploy/traverse/propose) with a protected branch, `origin`/`upstream` or a git URL blocks (`mytool ship origin main`; D373); image tools (`docker push`, `helm`, `kubectl`, …) are exempt. + - Any other program whose arguments pair a push-like verb (push/ship/land/submit/sync/merge/publish/deploy/traverse/propose) with a protected branch, `origin`/`upstream` or a git URL blocks (`mytool ship origin main`); image tools (`docker push`, `helm`, `kubectl`, …) are exempt. - unreadable code that could run a push fails closed: Bash `function f { … }` wrappers, a shell running `<(…)`, `script -c`, `xargs` feeding a shell or interpreter, PowerShell `(expr)` arguments (`git push origin ('ma'+'in')`), `[Diagnostics.Process]::Start`/`ProcessStartInfo` naming git/gh, and inline interpreter code (`deno eval`, `node -e`, …) that mentions push/merge next to a process call or a git/gh word. -- backstop for runners it doesn't model: a command whose head isn't git/gh, a shell, an interpreter, an HTTP client, a handled wrapper or a reader (`echo`, `printf`, `grep`, `rg`, `cat`, `ls`, `test`, `Write-Host`, `Select-String`, …), and whose arguments name a push/merge-capable command (`git … push|send-pack|http-push|subtree|receive-pack`, `gh … pr merge|api|alias|repo`, a gh write as classified above, `api.github.com`, `git-receive-pack`), blocks: `parallel git push …`, `awk 'BEGIN{system("git push …")}'`, `sed '1e git push …'`, `lua -e`, `Rscript -e`. +- backstop for runners it doesn't model. A command blocks when both are true: + - its first word isn't git/gh, a shell, an interpreter, an HTTP client, a handled wrapper or a reader (`echo`, `printf`, `grep`, `rg`, `cat`, `ls`, `test`, `Write-Host`, `Select-String`, …); + - its arguments name a push/merge-capable command (`git … push|send-pack|http-push|subtree|receive-pack`, `gh … pr merge|api|alias|repo`, a gh write as classified above, `api.github.com`, `git-receive-pack`). + - Examples: `parallel git push …`, `awk 'BEGIN{system("git push …")}'`, `sed '1e git push …'`, `lua -e`, `Rscript -e`. - `uv run`/`poetry run`/`pipenv run`, `npm exec`/`npx` (incl. `-c '…'`), `flock` (incl. `-c`), `strace`/`ltrace`, `coproc` and `trap '…'` are unwrapped and the inner command read as usual, so `uv run pytest` and `uv run git push origin krish/x` pass. - a shell or `.`/`source` reading its script from `/dev/stdin`, `/dev/fd/N` or `/proc/self/fd/N` is a stdin shell (`bash /dev/stdin <<< 'git push …'`). - write-then-run: a command that writes a file (`>`/`>>`, `tee`, PowerShell `Set-Content`/`Add-Content`/`Out-File`) and runs that same file (`sh x.sh`, `./x.sh`, `. x.sh`, `pwsh -File x.ps1`, `python x.py`) blocks when its text names a push/merge-capable command or a gh write. @@ -351,9 +354,9 @@ Protected branches: `GUARD_PROTECTED_BRANCHES` (comma list), default `main,maste ## Example -One issue through all three steps, as an orchestrator (or you) calls them. -The manager briefs and spawns its own `implementer` inside its turn, so only -its report comes back; you push and merge in between: +One issue through planner, manager and verifier, as an orchestrator (or you) +calls them. The manager briefs and spawns its own `implementer` inside its turn, so only +the manager's report comes back. You push and merge in between: ```transcript ⏺ Agent(subagent_type="planner", prompt="~/code/myrepo; exclusions: label needs-design; order: priority label") From 1ba3f36c26e4140bfe745d87a87ffe4f1b163fbc Mon Sep 17 00:00:00 2001 From: KrishP147 Date: Sat, 17 Oct 2026 03:10:59 -0400 Subject: [PATCH 09/16] docs(hooks): link ROTATION.md, plainer spend-guard lead Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01WHwM2TcQBo9oHdCrYCtdMn --- hooks/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/hooks/README.md b/hooks/README.md index 6abcaf8..57b7391 100644 --- a/hooks/README.md +++ b/hooks/README.md @@ -15,7 +15,7 @@ summary; the build fails if a hook has no section). See [`../site/README.md`](.. `UserPromptSubmit` hook. Prints a one-line warning into the conversation when the live context passes ~75k tokens, so both you and Claude see it and can wrap up: `/divide` the rest, then `/session-handoff` (or, for an orchestrator, -the rotation step in `meta-orchestrator`, see `ROTATION.md`). Heuristic only; +the rotation step in `meta-orchestrator`, see [`ROTATION.md`](../meta-orchestrator/ROTATION.md)). Heuristic only; `/context` is the precise check. How it works: on every prompt you submit, Claude Code passes the hook JSON on stdin; the script reads `transcript_path` and only the tail of that file (never the whole transcript). @@ -26,7 +26,7 @@ How it works: on every prompt you submit, Claude Code passes the hook JSON on st - If the result is at least the threshold it prints the warning (stdout is injected into the conversation). - Below it, or on any error (missing file, malformed lines, bad env), it prints nothing and never blocks. -Threshold: env var `SMARTZONE_TOKENS` (integer tokens), default `75000` (the old 1.5 MB size check at ~20 bytes per token). +Threshold: env var `SMARTZONE_TOKENS` (integer tokens), default `75000` (the same as the hook's earlier 1.5 MB transcript-size check, at ~20 bytes per token). - A bad value falls back to the default. - Set it in the hook `command` or your shell env. @@ -105,9 +105,9 @@ python hooks/smartzone.py --self-test ## `spend-guard.py` — block billable commands without an approval -`PreToolUse` hook for `Bash`, `PowerShell` and MCP tool calls. Enforces the -[`spend-gate`](../spend-gate/) skill's gate at the tool-call level: blocks a -command or MCP call that matches a known billable pattern unless an +`PreToolUse` hook for `Bash`, `PowerShell` and MCP tool calls. It enforces the +[`spend-gate`](../spend-gate/) skill's gate at the tool-call level. A command +or MCP call that matches a known billable pattern is blocked unless an approval already exists, so a billable action can't slip through even if the gate steps get skipped in the prompt. @@ -196,7 +196,7 @@ Approval scheme (either allows the one matched action): - The hook deletes the first file it finds (sorted by name) and allows that single call; the next matching call is blocked again until another approval file appears. - The file is gone after use, so it is no record: the log is `skilleddocs/spend.md`. - A call holding two or more billable commands (` && `) is refused and the file kept: run them as separate calls. -2. **`SPEND_GATE_APPROVED=