agent-tools

Use when deciding whether to dispatch a runner or a worker for a subtask. Describes the decision boundary, the failure mode when runner is used where worker is intended, and the safe composition pattern.

When a repo has no GitHub remote (or is not yet a git repo) -- use this to route survey, sweep, and dispatch off the GitHub-centric path. Detect with `git remote` empty; treat blank GitHub columns as expected, not an error; route work to commits + CLAUDE.md instead of issues + PRs; degrade a maintenance sweep to the local-only axes.

When the directive is "status check," "what's new across my projects," or "sweep maintenance" -- run a per-project, read-mostly, non-PR sweep. For each project under the owner-prefixed layout, gather stars/forks, open issues/PRs split into mine vs community vs bots, package downloads, release-due (unreleased conventional commits), a test run, a stale-CLAUDE.md flag, and branch-cleanup candidates. Emit a fresh per-project report every sweep; NEVER cache status back into a workspace/manager CLAUDE.md.

Before making any non-trivial code, docs, or config change -- create a feature branch first, then open a PR. Never commit directly to main. Apply by default before any edit; this is the baseline branch discipline that all other git skills build on.

When the issue or PR queue has open unlabeled items -- run a read-only triage pass that labels each one by component, category, priority, and size, flags duplicates, closes noise, and reports the p1 queue before runners are dispatched.

When writing any issue, PR, or commit message, use this for the authoring standard. Covers structure (headings, lists, tables, fenced blocks, the bug block, the before/after) and voice (factual, no emdashes, no editorializing labels, conventional-commit prefixes, no commit trailers).

The canonical owner-prefixed workspace layout. Every repo lives at ~/Code/<host>/<owner>/<repo> -- no active/ or language segment. Enumerate with `ls ~/Code/github.com/*/*`; resolve siblings by path arithmetic. The manager (workspace-root) CLAUDE.md is a map of where things are and how to read them, never a cache of per-project inventory or status. Load this whenever a session reasons about where a repo lives, walks the workspace, or resolves one project from another.

When the dispatcher needs a workspace map -- at the start of any multi-project or scope-scoping invocation. Enumerate repos under the owner-prefixed layout with `ls ~/Code/github.com/*/*`, load each project's positioning and live GitHub state (open/draft PRs, issues, CI), and RECONSTITUTE a tight activity report. Re-survey on every invocation; never cache per-project status back into any workspace CLAUDE.md, and never rely on prior-session memory.

When the dispatcher is about to fire a runner -- use this template to write the prompt and wrap the PR lifecycle. Apply before every dispatch: the prompt section covers setup, context, task, tool-call discipline, and steps; the PR-lifecycle pattern covers draft-PR-first through CI-watch and merge.

At the start of a dispatched lifecycle (runner or bare dispatch), verify the tools you need are in the sandbox allowlist. Fail LOUD on a blocked tool -- do NOT produce a "run this yourself" artifact (the silent-degradation trap). For a known-safe set of common dev tools, auto-heal by adding to .claude/settings.local.json. Anything else: ask the user.

When reviewing a PR in agent-tools -- reads the diff and issue, checks conventions, approves+merges, approves+notes ordering, or requests changes+converts to draft.

When the runner is about to return -- hold the invocation open until the full PR lifecycle is done (push, mark ready, CI watch, merge). Returning early orphans the work.

When choosing how to dispatch a subagent -- consult this before firing any dispatch. Covers the two primary mechanisms (Task tool / Bash + claude -p) and when each fits: default to Task tool for in-project work, reach for Bash + claude -p when you need a different cwd, process boundary, or long-running dispatch.

When piping markdown into `gh issue create --body "$(cat <<'EOF' ... EOF)"` (or any single-quoted heredoc), use literal backticks. Do NOT escape them -- escapes survive into the output and break the markdown.

When authoring a new skill or updating an existing one -- reference this for the two advanced frontmatter capabilities: dynamic context injection via `!`command`` syntax and `allowed-tools` for pre-approving tool use. Apply selectively; both features add overhead and should only appear where they genuinely help.

Use when dispatching an auditor or implementing an audit pass: defines the rubric format the auditor expects and the five-phase execution contract (Orient, Evaluate, Triage, File, Report) the auditor follows.

When the dispatcher has audit findings filed as GitHub issues and needs to decide how to fire per-finding runners -- use this to read the labeled finding-issues, apply the in-progress label before dispatch, and choose parallel vs sequential runner execution.

How to coordinate with background tasks (dispatched sessions, CI watches, sub-agent dispatches) without polling or sleep-looping. Use Monitor for live streaming output; use run_in_background for fire-and-forget final-result cases. Wait for the harness notification, peek at in-flight output deliberately, surface stalled runs after a reasonable clock budget.

Before starting any dispatched or non-trivial work that will become a PR -- open the draft PR first, with the plan as the body. The PR body is the plan, the commit stream is the work, and the PR exists as a visible, resumable work unit from minute zero. Use this whenever the work crosses the "deserve a PR" threshold.

When a dispatch-time issue surfaces -- wrapper bug, sandbox gap, missing skill, unexpected behavior -- file a structured GitHub issue to close the build-use-feedback loop.

When any agent session starts, compacts, or ends -- use this to know what state survives and what you must externalize before the session closes. Covers the persistence hierarchy, the MEMORY.md trap, externalization discipline, the cold-restart corollary, and dispatcher-specific compaction survival.

When a PR is open and needs a fix, push to the same branch or wait for merge before branching. Never branch off the open PR's branch directly -- squash-merge will leave you with a phantom conflict.

When the dispatcher is scoping a unit of work or deciding how to execute it -- use this to define what the unit is and pick the right execution shape (single runner / parallel / sequential / chained / audit + remediate). Default to single runner; reach for other shapes only when the unit justifies the coordination cost.

When the dispatcher has N tasks to execute -- use this before fanning out to decide whether to run in parallel or sequentially. Default is sequential; parallelize only when all three conditions hold (different file surface, independent semantics, predictable pattern). Different repos is the canonical parallel case; same-repo parallel needs worktrees.

When the task involves release-readiness, release-audit, version analysis, or "is this ready to ship" -- apply before any analysis. Anchor on origin/main (not the working branch tip), surface branch divergence in the first paragraph, and cross-check published versions against external sources. Without this, a stale branch produces false blocking findings.

When dispatched with an issue number, the runner's authoritative source for what to do is `gh issue view <N>`, NOT the dispatcher's paraphrase. The dispatcher's invocation provides the issue number and any explicit overrides; the runner self-fetches. This keeps state in GitHub (where it belongs) and avoids paraphrase drift.

When deciding between the Workflow tool and the Task tool for large-scale orchestration (50+ agents) -- use this. Covers what the Workflow tool is, its critical no-direct-I/O constraint, the fan-out + synthesize and chained design->impl->review shapes it fits, and when the simpler Task tool wins instead.

Before dispatching any agent after a batch of merged PRs, verify that ~/.claude/agents/ and ~/.claude/skills/ are in sync with the repo. Stale installed definitions cause dispatched agents to reintroduce behaviors explicitly removed in recent PRs.

When you notice something wrong or suboptimal in a skill or agent definition -- file a GitHub issue on joshrotenberg/agent-tools rather than silently proceeding.

When a dispatched run produces text or findings rather than a PR -- use this to pick the right output destination (stdout, CLAUDE.md entry, issue comment, findings file), apply the spawn-issue handback pattern, and hold the synchronous discipline for non-PR runs.

When a dispatched session hangs, produces no output, or seems stuck. Read the dispatched session's transcript directly -- it's the source of truth. Echo-flush spirals usually trace to one failed parallel tool call cascading cancellation errors to siblings.