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
2 changes: 1 addition & 1 deletion .agents/skills/using-devkit/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ devkit command.
| The work is **not ready for review** — you want a visible PR running CI, but no reviewers pinged yet | `devkit ship <branch> "<title>" --draft -- <paths>` | ship opens a **ready-for-review** PR by default, which requests review the moment it lands; `--draft` opens a draft instead. The bit is recorded with the invocation, so a gate-blocked draft ship still opens a draft under `--resume`. To make **every guard-suggested** ship in a repo a draft, set `.devkit/config.json` → `{ "ship": { "command": "devkit ship", "extraArgs": ["--draft"] } }` — the `command` key is required or `extraArgs` is ignored, and the guard drops `--draft` from its `--pr` suggestions, where it cannot apply |
| You are shipping a **layer on top of another open PR** (stacked PRs) | `devkit ship <branch> "<title>" --base <lower-pr-branch> -- <paths>` — nothing else | ship joins the new PR to the lower PR's **GitHub native stack** by default: it creates the stack when the lower PR targets the default branch, appends when it tops one, and prints `ship: stacked #N on #M`. No `gh stack link` and no extension needed. It never fails the ship: a mid-stack base, a lower PR on another non-default base, or a refusal from GitHub prints why plus the command to run by hand. Stacked PRs merge bottom-up, and merging one also merges those below it, so pass `--no-stack` (recorded for `--resume`) for a PR you want to merge on its own |
| A **draft** PR is finished and you are pushing the final commit | `devkit ship <branch> "<title>" --pr --ready -- <paths>` | one command instead of a re-push followed by a hand-run `gh pr ready`. The flip runs **last**, so a gh failure never costs the pushed commit — it names the exact `gh pr ready` to re-run. `--ready` requires `--pr` (a new ship is ready already); to go the other way, `gh pr ready --undo <branch>` |
| You need the PR's **CI verdict**, not just its URL — an end-to-end status before handing off | `devkit ship <branch> "<title>" --wait-ci -- <paths>` (add `--wait-ci-timeout <60..7200>`, default 3600) | ship otherwise returns while the checks are still pending. The wait runs **last**, after every artifact is durable, so it cannot cost the ship: it prints progress only when the tally changes plus a liveness line each minute, then one verdict line on stderr — `ship: ci-outcome=<passed\|failed\|cancelled\|no-checks\|timed-out\|unavailable\|not-run> pr=<n> …` (`not-run` when the wait was requested but could not run — a failed `--ready` flip, an unresolvable PR number, `SHIP_DRY_RUN`, or a signal that ended the wait (`reason=interrupted`, still exit 0); it always carries a `reason=`). On `failed` it adds `attribution=<inherited-only\|new\|unknown> inherited=<n> new=<m> new-failing=<files> new-steps=<job › step> base-run=<id> base-ci=<red\|green>`: which failures the base the PR was merged onto already had, read from CI's per-file test summaries, never from logs. `new` means not failing on that base run; `unknown` names a `reason=` or an `unsure=` count. Only `inherited-only` says none of the red is yours. A still-running Actions job whose step has already failed counts as red, so the wait ends about 40s after that step rather than at job end; it adds `failed-steps=<job › step>`. A green set also needs the head's own Actions runs, since a review bot can report green on a head CI never ran on: a queued run holds the wait, a run that failed before reporting any check (`startup_failure`) is red, a conflicting PR whose head has no `pull_request` run ends `unavailable reason=merge-conflict` at once (GitHub starts no `pull_request` run on a conflicting PR; a run made before the conflict still decides), every check the base branch requires must have reported, and a head without a `pull_request` run that ran jobs passes only when the PR is mergeable, is not stacked on another open PR, and has no workflow run at all; a fully skipped run or another event's run (e.g. `push`) is not the PR's run but still holds the wait, so it stays pending and ends `timed-out`. Any red that ends the wait while a check is still running, a step-level one included, reports `attribution=unknown reason=run-in-progress`: the per-file summary is not uploaded yet, and the unfinished run may still add new failures. Grep that line; by default the verdict **never** reaches the exit code, so a red PR is not a failed ship and must not be retried with `--resume`. To branch on it in a script, add `--wait-ci-strict`: ship then exits **5** for any verdict but `passed` (`not-run` and a crashed wait included; a signal that ends the wait exits its own 129–143) — the PR is open, so 5 is never a cue to `--resume`; an exit 1 still wins. On `timed-out` the next line names the `gh pr checks` one-shot. Run a `--wait-ci` ship in the background with a tool timeout covering the gates plus the wait. Valid with `--pr` too. **Not** replayed by `--resume` — re-pass it on a retry. For a PR that is already open, use `devkit ci-verdict` (next row) rather than re-shipping; `devkit baseline-status --pr <n> [--json]` reads an open PR's checks once, without waiting, and prints the same `attribution=` fields (a pending or empty check set is `unknown`, nothing failing is `attribution=none`); for a one-off check without waiting, `gh pr checks <n> --json bucket,name,state,link` is the quiet one-shot (`gh run watch` needs a run id and redraws) |
| You need the PR's **CI verdict**, not just its URL — an end-to-end status before handing off | `devkit ship <branch> "<title>" --wait-ci -- <paths>` (add `--wait-ci-timeout <60..7200>`, default 3600) | ship otherwise returns while the checks are still pending. The wait runs **last**, after every artifact is durable, so it cannot cost the ship: it prints progress only when the tally changes plus a liveness line each minute, then one verdict line on stderr — `ship: ci-outcome=<passed\|failed\|cancelled\|no-checks\|timed-out\|unavailable\|not-run> pr=<n> …` (`not-run` when the wait was requested but could not run — a failed `--ready` flip, an unresolvable PR number, `SHIP_DRY_RUN`, or a signal that ended the wait (`reason=interrupted`, still exit 0); it always carries a `reason=`). An `unavailable` line ends with `detail=<why>` (one line, secrets redacted, at most 200 chars): gh's own error for a gh failure, naming the call that failed, or devkit's reason (e.g. the merge conflict). On `failed` it adds `attribution=<inherited-only\|new\|unknown> inherited=<n> new=<m> new-failing=<files> new-steps=<job › step> base-run=<id> base-ci=<red\|green>`: which failures the base the PR was merged onto already had, read from CI's per-file test summaries, never from logs. `new` means not failing on that base run; `unknown` names a `reason=` or an `unsure=` count. Only `inherited-only` says none of the red is yours. A still-running Actions job whose step has already failed counts as red, so the wait ends about 40s after that step rather than at job end; it adds `failed-steps=<job › step>`. A green set also needs the head's own Actions runs, since a review bot can report green on a head CI never ran on: a queued run holds the wait, a run that failed before reporting any check (`startup_failure`) is red, a conflicting PR whose head has no `pull_request` run ends `unavailable reason=merge-conflict` at once (GitHub starts no `pull_request` run on a conflicting PR; a run made before the conflict still decides), every check the base branch requires must have reported, and a head without a `pull_request` run that ran jobs passes only when the PR is mergeable, is not stacked on another open PR, and has no workflow run at all; a fully skipped run or another event's run (e.g. `push`) is not the PR's run but still holds the wait, so it stays pending and ends `timed-out`. Any red that ends the wait while a check is still running, a step-level one included, reports `attribution=unknown reason=run-in-progress`: the per-file summary is not uploaded yet, and the unfinished run may still add new failures. Grep that line; by default the verdict **never** reaches the exit code, so a red PR is not a failed ship and must not be retried with `--resume`. To branch on it in a script, add `--wait-ci-strict`: ship then exits **5** for any verdict but `passed` (`not-run` and a crashed wait included; a signal that ends the wait exits its own 129–143) — the PR is open, so 5 is never a cue to `--resume`; an exit 1 still wins. On `timed-out` the next line names the `gh pr checks` one-shot. Run a `--wait-ci` ship in the background with a tool timeout covering the gates plus the wait. Valid with `--pr` too. **Not** replayed by `--resume` — re-pass it on a retry. For a PR that is already open, use `devkit ci-verdict` (next row) rather than re-shipping; `devkit baseline-status --pr <n> [--json]` reads an open PR's checks once, without waiting, and prints the same `attribution=` fields (a pending or empty check set is `unknown`, nothing failing is `attribution=none`); for a one-off check without waiting, `gh pr checks <n> --json bucket,name,state,link` is the quiet one-shot (`gh run watch` needs a run id and redraws) |
| A PR is **already open** and its check is **red** — is the red yours or inherited from the base it merges onto? | `devkit ci-verdict <pr-number\|branch>` (add `--timeout <60..7200>`, default 900) | prints the same `ship: ci-outcome=… attribution=<inherited-only\|new\|unknown> … base-run=<id>` line `--wait-ci` does, on stdout, without pushing or taking a ship slot — `ship --pr --wait-ci` with nothing to push only says `not-run`. It compares CI's per-file test summaries of the PR run and the base run; hand-diffing `gh run view --log-failed` output compares grepped names instead. Exit 2 means no verdict (no gh, no such PR, or `reason=merge-conflict`); a red or timed-out verdict exits 0. Checks still running: run it in the background with a `--timeout` that outlasts them, since a killed wait prints nothing |
| Another ship may be **running on this machine** (parallel agents, a second session) | just run `devkit ship …`; see who is running and who is next with `devkit ship --queue` | every ship waits for a machine-wide slot, first come first served, before its first gate, and prints its queue position once. There is one slot by default; the machine owner may allow more with `~/.devkit/ship-queue/config.json` `{"slots": N}` (1..4) — never change it yourself, since too many concurrent ships exhaust memory. Do not wrap ship in a `pgrep` wait loop: it has no order, can wait on a shell that merely mentions ship, and can double-start. The slot frees itself when the ship and its process group are gone, and is handed on before `--wait-ci` polls. There is no way to skip the queue: the old `DEVKIT_SHIP_NO_QUEUE` and `DEVKIT_SHIP_QUEUE_DIR` are ignored. If a running ship looks stuck, `devkit ship --queue` names it with the `ps` command that inspects it; stop it yourself once you have checked — never delete the slot by hand while its ship lives. Every attempt prints one `attempt <id> <branch>: queued Ns · setup Ns · gates Ns · <start> → <end> · outcome=<pass or the blocked gate> · log <path>` line just above its gate digest, so queue wait never reads as gate time; find a past attempt with `grep -h '^attempt ' ~/.devkit/telemetry/logs/*.log | grep <branch>` |
| An existing PR conflicts after its base moved, and you have **already resolved it locally** | First rebase/merge the actual PR base, then `devkit ship <branch> "<title>" --pr --base <actual-pr-base> -- <paths...>` | Brief every path you changed and every old-PR path the base does not already hold identically: paths a squash-merged parent PR already landed may be omitted. devkit gates one replacement commit and rewrites only under an exact head-OID lease. It publishes the caller-prepared resolution; it does not perform the rebase or merge. The local rebase/merge is all it needs: **no** raw `git push` to the PR branch and **no** `gh pr update-branch` first — GitHub's PR base OID is a stale snapshot and is not checked. A base that moves on during gates is fine; a rewound one is refused. |
Expand Down
Loading