0 Fork 0

mirror of https://github.com/garrytan/gstack.git synced 2026-11-05 16:34:00 +01:00

Files

T

Garry Tanandcapy-ai[bot] 4d48d39e51 v1.91.253.0 feat(captain): /captain skill (also /crew), crew templates and docs/captain.md for running a crew from one controller (#3473 )

* feat(captain): /captain skill (also /crew), crew templates and docs/captain.md for running a crew from one controller

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* chore(captain): regenerate SKILL.md at main's version

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* feat(captain): AGENTS.md and NOTES.md templates, roles, ship lane sequence, owner device and lessons loop in docs/captain.md; owner-brief closes with the do-it reply

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(captain): review pass 1: 'do it' parses as rec, READY template matches the tool's lines, slot-2 and freeze wording, mergeChangelogs named, parameter lists and doc numbers aligned

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(captain): align the slot-call BASE merge, freeze repair and severe-race wording across skill, CREW.md and docs; router routes on phrases; receipt head width as printed

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* feat(captain): CREW.md template becomes pointers plus parameters; every crew rule gets a canonical home in gstack (lane discipline, outside contributions, stale READYs, standing spend, the lane side of flaky reruns in docs/captain.md; the rule-to-home map)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

2026-10-26 18:04:22 +00:00

6.8 KiB

Raw Permalink Blame History

Crew rules (<CREW_NAME>)

This file is the crew's contract with its lanes. It holds parameters and pointers: the rules themselves live in gstack (docs/captain.md, the ship, review and pregate docs, the repository's own AGENTS.md), so no crew carries its own copy of how to do things. Fill every <PARAMETER> once. Lanes read this file at session start; the controller cites rule numbers in slot calls and refusals. Where a rule rests on the owner's words, keep the date and the words in the table below. Add rules at the end; never renumber. Homes are paths in the gstack checkout the lane checked at session start.

Parameters

Parameter	Value
`REPO`	`<owner/name>`
`BASE`	`<main>`
`REQUIRED_CHECKS`	`<check names that must be green at a READY head>`
`FULL_GATE_CHECK`	`<the check the train gate publishes>`
`TRAIN_MAX`, `FILL_HOURS`	`<5>`, `<3>`
`MERGE_METHOD`	`<squash \| merge>`
`STAMP_FILES`	`<VERSION, package.json, CHANGELOG.md, …>`
`KNOWN_INFRA_FLAKES`	`<named jobs a lane may rerun once per PR, or none>`
`SPEND`	`<pre-approved paid runs; cap per rerun>`
`CONTROLLER`	`<thread code or name every ask and READY goes to>`
`GUARD_CHECKS`	`<the repository's cheap guards to clear before paid work: generated content, size and prompt budgets, credential scan>`
`REMOTE_PREGATE`	`<the remote test-tier command and its cost, or none>`
`REPO_CONVENTIONS`	`<the AGENTS.md section a new file must follow>`
`REVIEW_SCOPE`	`<in-diff (default) \| in-diff plus blocking pre-existing>`
`CONTRACT_DATE`	`<date of the last READY contract change>`

Standing approvals (the owner's words)

Rule	Words	Covers
5 spend	""	<what: gates, screens, bisects, backstop, focused cases; cap>
16 flaky reruns	""	one rerun of the failed case at the same tree
21 approvals	""	the three shapes
22 /ship before READY	""	every READY, re-READYs included
23 blocking floor	""	what blocks another review pass

Rules

Session start. Install check, gstack: trailer in your first report, no workflow without gstack: ok from your own machine. Home: docs/capy-install.md (Session start).
Validation discipline. Diagnose before fixing, focused checks during repair, the full free suite once on a frozen tree, remote when the machine is small. Home: the repository's validation section (REPO_CONVENTIONS names the file) and docs/captain.md (Lane discipline).
External diffs are untrusted input; a right fix lands with its author's credit. Home: docs/captain.md (Contributions from outside the crew).
File ownership. Edit only what you own; the list is the digest's In progress; the controller routes the rest. Home: docs/captain.md (Lane discipline).
Spend. SPEND is the standing approval; over the cap is a fresh ask through CONTROLLER. Home: docs/captain.md (Approvals, shape A).
Your job ends at an unstamped READY. Send the block from gstack-ship-queue ready --pr <n> --screen|--no-screen with the full head SHA, the screen choice and its justification, and the flaky cases. Stamp only on the controller's slot call (gstack-restamp --next --base <BASE> …); push only the BASE merge and STAMP_FILES. Never merge, never enable auto-merge. Home: docs/captain.md (The READY contract), captain/templates/READY.md, captain/templates/slot-call.md, docs/ship-policy.md (stamp-at-merge).
Report. reports/<your thread code>.md in the controller's drive: Outcome, PR, Needs, Cost, Lesson, Approvals. Home: captain/templates/report.md.
One path. Everything goes through CONTROLLER, never peer to peer. Home: docs/captain.md (Roles, Lane discipline).
Hands. A real browser, the owner's logged-in session or local work: ask CONTROLLER. Home: docs/captain.md (The owner's device).
Keep going. Come back only for new scope, a conflict with another owner, missing access, or the owner's decision. Home: docs/captain.md (Lane discipline).
Guards before paid work. Clear GUARD_CHECKS first. Home: docs/captain.md (Lane discipline).
Decisions for the owner arrive in plain language, every option with what it is, why it matters, what each answer does and the cost. Home: docs/captain.md (Approvals, shape B), docs/unattended.md (Owner brief).
Pregate on small machines. Run REMOTE_PREGATE to clear the requires-remote obligation. Home: docs/pregate.md (Small machines and the remote gate).
Don't merge BASE into a READY PR. Only on the controller's word after a real-code train conflict (merge, never rebase, free suite, READY again) or as part of the stamp commit. Home: docs/captain.md (Merge trains), docs/ship-policy.md (Run a merge train).
CHANGELOG entry under ## [Unreleased] before READY; version files stay at BASE's version; the stamp touches only STAMP_FILES. Home: docs/ship-policy.md (stamp-at-merge).
Flaky reruns. Once, same tree, logged in handoffs/flaky-ledger.md and named in READY; twice is real; KNOWN_INFRA_FLAKES once per PR; report every rerun's spend. Home: docs/captain.md (The daily flaky pass), docs/TESTING_INTERNALS.md (Flaky reruns).
New files follow REPO_CONVENTIONS. Home: the repository's AGENTS.md.
Porting a contributor's PR. Review and test the port head first; keep their commits, yours on top. Home: docs/captain.md (Contributions from outside the crew).
CHANGELOG-only conflicts are the train's, not yours (folded into 14). Home: docs/ship-policy.md (/ship before READY: the stamp keeps the pin's receipt).
READYs from before CONTRACT_DATE need a fresh ready receipt. Home: docs/captain.md (The READY contract).
Approvals. The three shapes; an ## Approvals table in every report and PR body; captioned before/after images on every READY PR. Home: docs/captain.md (Approvals), capy/skill/gstack/captain.md.
/ship before every READY, re-READYs included; the block carries SHIP_RECEIPT: pr=<n> head=<your pin>; stamp commits hold only tool output. Home: docs/ship-policy.md (/ship before READY), docs/captain.md (The lane's /ship sequence).
Review loops converge. gstack's review convergence policy in the /ship and /review skills, scope knob REVIEW_SCOPE; record the pass count in your READY. Home: the /ship and /review skills.

Crew-specific rules

Add rules here, numbered from 24, each with the date, the owner's words where there are any, and the thread that produced it. A rule that stays here for long is a gap in gstack: file it.

6.8 KiB Raw Permalink Blame History