Skip to content

docs: add working-in-turns fleet skill #2556

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lilyshen0722 merged 8 commits into from
Oct 24, 2026
Merged

docs: add working-in-turns fleet skill #2556

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
2ef311f
docs: add working-in-turns fleet skill
lilyshen0722 Oct 23, 2026
103779f
docs: require PR review verdicts
lilyshen0722 Oct 24, 2026
1acd145
docs: link review verdict guidance
lilyshen0722 Oct 24, 2026
ccc7637
docs: clean reviewer gate checkouts
lilyshen0722 Oct 24, 2026
94a3700
docs: make gate verdict format explicit
lilyshen0722 Oct 24, 2026
d825123
chore: sync packaged Commonly skill
lilyshen0722 Oct 24, 2026
d6f96aa
docs: clarify reviewer checkout guidance
lilyshen0722 Oct 24, 2026
8084325
docs: keep public skill generic
lilyshen0722 Oct 24, 2026
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
5 changes: 2 additions & 3 deletions cli/skills/commonly/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,7 @@ live.

| what you produced | where it belongs |
|---|---|
| a review of a pull request | `gh pr review` — approve, or request changes |
| a review of a pull request | review on the pull request, not only in chat |
| a decision with a lasting consequence | an ADR in `docs/adr/` |
| an idea nobody is building yet | the idea register |
| a bug or a piece of work | a GitHub issue |
Expand All @@ -183,8 +183,7 @@ live.
This matters most for reviews. Excellent review reasoning posted as a pod
message does not gate anything and cannot be acted on by someone reading the
pull request — the merge button does not know the conversation happened. If you
reviewed something and it is not ready, **say so on the pull request** with
`gh pr review --request-changes`, not only in chat.
reviewed something, say so on the pull request, not only in chat.

When you approve, say what you verified AND what you could not. An unqualified
approval on something you did not check is worse than a partial one, because it
Expand Down
5 changes: 2 additions & 3 deletions docs/agents/skills/commonly/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,7 @@ live.

| what you produced | where it belongs |
|---|---|
| a review of a pull request | `gh pr review` — approve, or request changes |
| a review of a pull request | review on the pull request, not only in chat |
| a decision with a lasting consequence | an ADR in `docs/adr/` |
| an idea nobody is building yet | the idea register |
| a bug or a piece of work | a GitHub issue |
Expand All @@ -183,8 +183,7 @@ live.
This matters most for reviews. Excellent review reasoning posted as a pod
message does not gate anything and cannot be acted on by someone reading the
pull request — the merge button does not know the conversation happened. If you
reviewed something and it is not ready, **say so on the pull request** with
`gh pr review --request-changes`, not only in chat.
reviewed something, say so on the pull request, not only in chat.

When you approve, say what you verified AND what you could not. An unqualified
approval on something you did not check is worse than a partial one, because it
Expand Down
32 changes: 32 additions & 0 deletions fleet-skills/working-in-turns/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
name: working-in-turns
description: Keep each turn bounded, checkpointed, and reviewable.
user-invocable: false
last_updated: 2026-10-24
---

# Working in Turns

- Size each turn to finish well inside its run timeout. The default is 15 minutes; only adapters that honor `COMMONLY_AGENT_RUN_TIMEOUT_MS` can use a longer value such as `2700000` (45 minutes). If the work is larger, split it and say how in the row.
- Push a checkpoint commit before the final five minutes of the run timeout. A draft PR is enough; a timeout sends SIGTERM and loses uncommitted work.
- Put every gate ask on the PR with the exact head and in the pod.
- Ask reviewers in a pod they actually belong to.
- After a HOLD, fix it, push the new head, and re-ask on the PR.
- File every verdict as described in [review checklist rule 44](../../docs/development/review-checklist.md#what-a-clearance-can-bind) and [rule 51](../../docs/development/review-checklist.md#where-a-verdict-is-readable): the first line must name the exact head and verdict, and the final non-blank line must be the bare `GATE: PASS` or `GATE: HOLD` sentinel.
- After filing a verdict, choose a checkout strategy: inspect and remove/prune a temporary PR checkout only after checking for uncommitted work, or keep one reusable checkout and clean/refetch it for the next review.
- Never use `git worktree remove --force` before checking for uncommitted work.

## Gate ask template

Address the reviewer in a pod they belong to and include the PR number, exact
head SHA, files or properties to check, and the required verdict form:

> Please review PR #<number> at `<full-head-sha>`. Check `<files/properties>`.
> File the verdict as a PR review. Its first line must be `HEAD: <full-head-sha>
> — GATE: PASS` or `HEAD: <full-head-sha> — GATE: HOLD`, and its final
> non-blank line must be exactly `GATE: PASS` or `GATE: HOLD`, per review
> checklist rules 44 and 51. After filing it, inspect a temporary checkout for
> uncommitted work before removing it and pruning; otherwise clean and refetch
> the reusable checkout for the next review.

Use one reusable checkout per seat when appropriate; inspect temporary checkouts before removing them.
Loading