issues
GitHub-issue marathon - triage open issues, then run agent-ready ones to merge with Agent Teams
bjcoombs · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add bjcoombs/ai-native-toolkit --skill issues技能说明
name: issues disable-model-invocation: true description: GitHub-issue marathon - triage open issues, then run agent-ready ones to merge with Agent Teams argument-hint: "[scope-label] (optional - narrows which open issues are considered; default: all open issues)"
GitHub Issue Marathon
Thin orchestrator. Triages open issues, then delegates execution of
agent-readyissues to the marathon skill (same engine as/tm).
Configuration
Read the repo's CLAUDE.md ## Marathon Configuration (GitHub Issues subsection) for label
names, with defaults:
- Agent-ready label:
agent-ready - Needs-triage label:
needs-triage - In-progress label:
in-progress - Issue exclude labels: (none)
Also read base branch, required approvals, and bot-reviewer rules (shared with /tm).
Phase 0: Capability Detection
echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS # set $TEAMS_AVAILABLE (true if "1")
Routing
ORG=$(gh repo view --json owner --jq '.owner.login')
REPO=$(gh repo view --json name --jq '.name')
# Optional scope filter from $ARGUMENTS — narrows the issue universe; routing still applies within it.
SCOPE_LABEL="$ARGUMENTS" # empty = all open issues
FILTER=(); [ -n "$SCOPE_LABEL" ] && FILTER=(--label "$SCOPE_LABEL")
READY=$(gh issue list --label "agent-ready" "${FILTER[@]}" --state open --json number --jq 'length')
READY > 0→ Marathon mode. Work ONLY theagent-readyissues. Do NOT assess or modify untagged issues — the human has curated the queue by tagging.READY == 0→ Triage mode (below).
Triage Mode (no agent-ready issues exist)
Enumerate open issues minus the exclude labels:
gh issue list "${FILTER[@]}" --state open --json number,title,body,labels | \
jq '[.[] | select((.labels[].name) as $l | ($l | IN("<exclude-labels>")) | not)]'
If $ARGUMENTS (a scope label) was given, only issues carrying it are considered; routing still applies within that subset.
Triage is a planning pass, not a labeling pass. It runs once over the whole issue set, in this order, and every write it makes shows up in the report the human approves:
- Promote on Confirmation - fold in answers the human gave since the last run.
- Research Pass - resolve what the repository can answer before asking anything.
- Overlap Sweep - hold back issues that collide with open PRs; record issue-to-issue collisions as edges or hot-file notes.
- Size by Judgment - decide one PR or several, and propose any decomposition.
- Dependency Authoring - write the ordering as native
blocked_byedges. - Triage Report - apply every label write at once, then render labels, decomposition tree, execution order, overlaps; STOP.
An issue is agent-ready only when it survives all of steps 2 to 4: clear after research,
no unresolved overlap, and sized to one PR (or approved as a decomposed parent). Everything
else stays or becomes needs-triage. Research and sizing read widely, so fan them out with
subagents (the Agent tool); never teammates.
Steps 1 to 4 decide the label of each issue that exists at the start of the pass but do not
write it: the verdict needs all four inputs, so every agent-ready / needs-triage label change
on those issues happens in one write at the Triage Report step. Creating an approved
decomposition is a separate phase after approval that labels its own children and parent (see
Size by Judgment). An interrupted pass therefore never leaves an issue agent-ready while it overlaps an open
PR. Comments, body edits and dependency edges are written where they are decided.
Promote on Confirmation
Start with issues already labeled needs-triage that carry a triage comment with a
recommended reading, or a decomposition proposal comment (marker
<!-- triage:decomposition-proposal -->, see Size by Judgment). A human reply approving that
proposal on the issue counts as approval of the decomposition and triggers its creation phase. If a human reply after that comment confirms or corrects it ("yes,
reading A" is enough), fold the confirmed answers into the issue body (append a
Clarified scope section with the confirmed scope and acceptance criteria) or, when the body
is the author's to keep, into a marker-tagged issue comment: a new comment whose first line is the
HTML-comment marker <!-- triage:clarified-scope -->. The marker, not any UI pinning, is what
makes it durable: the implementing teammate and every later
run find the clarified contract by grepping for it, never by re-interpreting the thread. The
issue's verdict becomes agent-ready (label swapped from needs-triage at the Triage Report
step) unless the same pass's Overlap Sweep or Size by Judgment holds it back:
gh issue edit <N> --body-file <body-plus-clarified-scope.md> # issue body route
gh issue comment <N> --body-file <clarified-scope.md> # marker comment route; first line is the marker
A correction that opens a new question is not a confirmation: run the Research Pass on the
new question and keep needs-triage. No reply means no change.
Research Pass
Before any question reaches a human, research it. For each issue whose scope, acceptance
criteria, or intent is unclear, run an understand-style pass over what the ambiguity
touches: the code and tests, open and merged PRs (gh pr list --state all --search "<terms>"), and the issue history (linked, referenced, and closed issues). The primitive is
the /understand skill (skills/understand/SKILL.md, relative to the plugin root): define the
terms, separate the explicit need from the implicit one, and bound the scope, grounded in
what the repository shows. Spawn one research subagent per ambiguous issue (or per subsystem
for a wide one) so the pass runs in parallel.
Any question the repository answers is answered, not asked. What the code does now, whether a constraint is real, which reading matches existing behav
阅读完整来源 ↗