Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
509 changes: 509 additions & 0 deletions .agents/skills/backlog-burndown/SKILL.md

Large diffs are not rendered by default.

31 changes: 28 additions & 3 deletions .agents/skills/drive-pr/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ description: >-
develop and, when asked, on to a mergeable develop -> main promotion PR, applying the
pr-review-conduct disposition to every reviewer finding along the way: fix it, decline it with
evidence, defer it behind a filed issue, or put the call to the maintainer and wait for an
explicit answer in the same turn. Use this whenever asked to drive, land, take, chase, or push
explicit answer in the same turn, escalating to whoever dispatched the drive instead where the
maintainer cannot be reached from that seat. Use this whenever asked to drive, land, take, chase, or push
a PR toward develop or main, or to run the review loop hands off instead of narrating each
round. When the request does not say how far ("drive this PR", "land it"), ask once whether the
target is develop or a mergeable main promotion PR, rather than guessing. Triggers even when
Expand Down Expand Up @@ -37,14 +38,35 @@ promotion PR once the fix lands, is the early exit this skill exists to prevent.
before the first push: develop only, or all the way to a mergeable main promotion PR. Recommend
"all the way to main" as the default, a promotion PR left to go stale once develop is ready is
the more common regret than driving one step too far.
- A drive dispatched as part of a larger run takes its target from the brief and asks no one,
since a subagent stopping to ask stalls a run designed to keep moving without one, and the seat
that dispatched it is the seat that holds the maintainer's answer. `backlog-burndown` is such a
run, and it briefs develop only, driving the develop -> main promotion pull request in its own
seat under "The Drive Loop"'s promotion steps. A brief naming no target at all is one to stop
and ask its dispatcher about, and asking the dispatcher is the whole of what a dispatched drive
does about an authorization question. A dispatched drive is not the seat that can verify a
grant, so it does not try: the responsibility for having the maintainer's go-ahead sits with the
dispatcher, and a worker inventing a check it cannot perform would only launder that
responsibility rather than discharge it.
- **A brief is never itself the authorization**, which binds the dispatching seat. What authorizes
a merge is what the maintainer said, recorded where the skill that carries the grant states its
scope, the way `backlog-burndown`'s own "What Invoking This Skill Authorizes" does. Writing an
approval into a brief creates none, since an agent cannot widen its own permission by writing
itself one, and a merge is the outward-facing act this skill's own "What Invoking This Skill
Authorizes" keeps tied to something the maintainer actually said.
- A repo on the operational workflow model (registry `workflowModel: operational`) has no
standing promotion PR expectation, confirm whether a promotion PR is even wanted before opening
one, per operational-vs-release-workflow's "Operational repositories" delta.
one, per operational-vs-release-workflow's "Operational repositories (the complete delta)"
section.

## What Invoking This Skill Authorizes

- Naming this skill, and answering its how-far question, is the maintainer's explicit, current
go-ahead for every feature -> develop squash merge the drive performs to reach that target.
- A dispatched drive answers no such question, so what stands in its place is the go-ahead the
dispatching seat holds, per "How Far to Drive" above, and the drive performs the same merges on
it. Reading this bullet list is not how such a drive establishes that, since a worker cannot
verify a grant made in a seat it has no access to.
- It is never authorization to merge the develop -> main promotion PR, or to dispatch a release.
Those stay in merge-and-release, invoked on its own so the maintainer keeps a checkpoint before
the harder-to-reverse step.
Expand Down Expand Up @@ -125,7 +147,10 @@ pr-review-conduct's five outcomes are the actual rule, this is the mapping to us
- Real, fixable, but a value call rather than a scope boundary, or the agent genuinely does not
know which of the above applies, so ask the maintainer directly, whatever the runtime's own
interactive-question mechanism is, and get an explicit answer in the same turn, a plan to ask
later is resolution by silence (outcome 3).
later is resolution by silence (outcome 3). A drive that cannot reach the
maintainer directly, a dispatched one being the ordinary case, escalates to whoever dispatched
it and stops that unit of work there instead, per `pr-review-conduct`, which owns what the
receiving seat then does and how far the escalation travels.
- The same finding keeps recurring against correct code, fix the class, sharpen a name, add a
comment, or take the rule itself to the maintainer, rather than re-arguing the instance every
round (outcome 5).
Expand Down
4 changes: 3 additions & 1 deletion .agents/skills/local-strict-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,8 @@ Bounds: read-only. No edit, no stage, no commit, no push, no PR-hosted write of

**Model tier:** the strongest tier this session can reach, per `AGENTS.md` "Match the model tier to the judgment" and "Never tier down the seat holding the judgment", applied here to the reviewer rather than the author. Run the pass on the same tier that authored the change when only one tier is reachable, a second, adversarially-prompted look still catches what the authoring pass's own "looks ready" judgment did not.

"This session can reach" means the tier this session can name when it dispatches the reviewer, rather than the tier this session is itself running on. A session deliberately tiered down for execution work, a worker dispatched by an orchestrator being the ordinary case, names a stronger tier for the reviewer where its harness lets it, since tiering down the author is the reason the reviewer must not follow it down. What a given harness and account actually permit varies, so treat this as the tier to ask for rather than one to assume. Where a dispatch reaches several tiers but exposes no way to name one, take what it gives and run the pass, on the same reasoning as the single-reachable-tier sentence above. A seat that cannot dispatch a subagent at all cannot perform this pass. Instead of pushing, it reports that it could not run the pass, to whoever dispatched it, or to the maintainer where nobody did. Either way it is a push that does not happen rather than a pass quietly skipped. The headless `run --backend` route under "Recording the Pass" is not the substitute: it runs a vendor CLI against its own review, which never carries the brief above, so it satisfies the rule this section states only where that separate route is what a capture point asked for.

## Recording the Pass

`scripts/local_review.py` is what makes this rule checkable rather than something each session has to remember. For the pass above, the engine only records that it happened, keyed on the content the reviewer actually saw, and its `run --backend <name>` subcommand is the separate case where a headless backend performs the review and records its own count. That receipt is what a capture point reads, the hub's own `.husky/pre-push` hook being the only one today, and a repository having none unless it adds one, since no manifest entry carries it.
Expand Down Expand Up @@ -123,7 +125,7 @@ The digest is bound to the read for the same reason `--expect-digest` is above:

## Disposing of Findings

Every finding maps to one of `pr-review-conduct`'s five outcomes, at whichever moment this pass ran: fixed (1), evidence-disproven (2), escalated to the maintainer for an explicit call (3), filed as a deferred issue (4), or, if it keeps recurring, taken as a signal to fix the class (5). Outcome 2 is the agent's own on its own evidence, covering a finding that is not real and one that is structurally out of scope. A finding judged real and left unfixed is never the agent's alone, so outcome 3 needs the maintainer's explicit answer in the same turn, reached only once outcome 2 is ruled out, and outcomes 4 and 5 reach the maintainer too, for the deferral and for the rule itself. Running this pass is required before every push toward a pull request, per `agent-conduct`. Two claims sit next to each other here and they point opposite ways, so they are stated apart rather than in one sentence. **The pass is mandatory**, and where a capture point enforces it, a push carrying content no recorded pass covers is refused. That refusal is the gate working rather than a fault to route around. **The findings stay advisory**, and the count a pass raises gates nothing at all, since a pass records that a review ran and never that the content is clean. The disposition above is what closes each finding, the same posture local lint holds today. It posts nothing to GitHub, it only reports to the session driving the work. A finding raised here and not fixed is not thereby resolved: the same finding shape reaching a PR-hosted reviewer later still gets its own fresh disposition, per `pr-review-conduct`'s "a disposition decided on one PR does not carry to the next."
Every finding maps to one of `pr-review-conduct`'s five outcomes, at whichever moment this pass ran: fixed (1), evidence-disproven (2), escalated to the maintainer for an explicit call (3), filed as a deferred issue (4), or, if it keeps recurring, taken as a signal to fix the class (5). Outcome 2 is the agent's own on its own evidence, covering a finding that is not real and one that is structurally out of scope. A finding judged real and left unfixed is never the agent's alone, so outcome 3 needs the maintainer's explicit answer in the same turn, reached only once outcome 2 is ruled out, or, where this pass ran in a seat that cannot reach the maintainer, an escalation to whoever dispatched it that stops the work there, which stops the push this pass runs before, and outcomes 4 and 5 reach the maintainer too, for the deferral and for the rule itself. Running this pass is required before every push toward a pull request, per `agent-conduct`. Two claims sit next to each other here and they point opposite ways, so they are stated apart rather than in one sentence. **The pass is mandatory**, and where a capture point enforces it, a push carrying content no recorded pass covers is refused. That refusal is the gate working rather than a fault to route around. **The findings stay advisory**, and the count a pass raises gates nothing at all, since a pass records that a review ran and never that the content is clean. The disposition above is what closes each finding, the same posture local lint holds today. It posts nothing to GitHub, it only reports to the session driving the work. A finding raised here and not fixed is not thereby resolved: the same finding shape reaching a PR-hosted reviewer later still gets its own fresh disposition, per `pr-review-conduct`'s "a disposition decided on one PR does not carry to the next."

## When to Run It

Expand Down
10 changes: 10 additions & 0 deletions .agents/skills/pr-review-conduct/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -172,6 +172,16 @@ from a hub checkout. Do not use a provider connector or reconstruct the GitHub m
- A finding is judged real but should not be fixed. That decision is never the agent's alone.
- An architectural redesign is proposed rather than a bug fix.

An agent that cannot reach the maintainer directly, a dispatched subagent being the ordinary case,
escalates to whoever dispatched it and stops that unit of work there. It never substitutes its own
judgment for the escalation because asking is inconvenient from where it sits, and it never resolves
the thread to keep moving. A dispatcher receiving one puts it to the maintainer at the point that
work stopped, per `GOVERNANCE.md` "Communicating with the User", and deciding it instead so the
dispatcher's own work keeps moving is the same resolution by silence this skill's own
ask-the-maintainer outcome forbids, one seat further from the maintainer. The escalation may travel through several seats, and what stays stopped is the
escalated unit of work, in whichever seat holds it, until the answer arrives. A dispatcher's other
work is not stopped by it.

## Mechanics Live Elsewhere

This skill is the provider-agnostic contract. Use `scripts/pr_review.py` from a hub checkout for
Expand Down
1 change: 1 addition & 0 deletions .claude-plugin/fleet-skills/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
"./skills/add-host-tool",
"./skills/agent-conduct",
"./skills/audit-a-repo",
"./skills/backlog-burndown",
"./skills/carried-instruction-file-guard",
"./skills/code-review",
"./skills/comment-and-doc-style",
Expand Down
2 changes: 1 addition & 1 deletion .claude-plugin/fleet-skills/.source-digest
Original file line number Diff line number Diff line change
@@ -1 +1 @@
9e9025addf504948
ecfc716438f27a07
Loading