0 Fork 0

mirror of https://github.com/garrytan/gstack.git synced 2026-11-02 15:04:37 +01:00

Files

T

Garry Tanandcapy-ai[bot] 737e5a239e v1.91.285.0 docs(captain): plan before build — a sized /autoplan is a building lane's first act, the owner's word gates the build (#3521 )

* docs(captain): plan before build — a sized /autoplan is a building lane's first act, the owner's word gates the build (GSTA-130)

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

* docs(capy skill): Plan, approve, ship — the Capy-wide short form (autoplan sized to the work, ELI5 with rec and do it, APPROVED before the build, /ship at the final head, no merge without the owner's word) (GSTA-130)

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

* fix(changelog): restore the full history; the Unreleased block had been written over a truncated read (GSTA-130)

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

* docs(capy skill): tighten Plan, approve, ship to one-line bullets so the Capy skill stays under its 4120-token eager ceiling (GSTA-130)

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

* fix: pre-landing review fixes — import --by takes the owner alone, the controller checks the row against its relay, brief.md spells the full answer command and carries the run dir, first act after the install check (GSTA-130)

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

* docs(captain): name the lane brief in the template lists; fix two template command lines

docs/skills.md and docs/PROJECT_STRUCTURE.md enumerate captain/templates/ and
omitted brief.md (document-release audit gsta130-docs-1). brief.md's restore
line now names the checkpoint dir that resume --from takes, and plan-ask.md's
answer line carries --rec-hash like brief.md (ship review pass 2).

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-27 23:56:53 +00:00

7.7 KiB

Raw 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
24 plan before build	""	a sized /autoplan first, the owner's word before the build

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.
Plan before build. If you build something, a /autoplan run on your brief, sized to the work, is your first act after the session-start check; send CONTROLLER the plan and its gate in plain language with the recommended reply named; build only after the owner's word is answered into the run and it reports APPROVED; record it with gstack-approvals import --autoplan. New scope taken on part-way gets the same. Exempt: read-only lanes, the daily flaky pass's repairs, slot stamps, CHANGELOG-only resolves, cap re-pins under a written grant. Home: docs/captain.md (Plan before build), captain/templates/brief.md.

Crew-specific rules

Add rules here, numbered from 25, each with the date, the owner's words where there are any, and the thread that produced it. A crew whose own rules already took 24 before rule 24 shipped keeps its numbering and cites docs/captain.md (Plan before build) by section name. A rule that stays here for long is a gap in gstack: file it.

7.7 KiB Raw Blame History