@futurelastic/colab-handbook 1.12.0-rc.65 → 1.12.0-rc.66

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -9,11 +9,26 @@ other.
9
9
  **If you are an AI agent, stop here and read [`CLAUDE.md`](CLAUDE.md).**
10
10
  This file is for humans.
11
11
 
12
- *(The normative document — [`CONVENTIONS.md`](CONVENTIONS.md) — is written in
13
- English so agents and tooling can read it. This is the English front door; the
14
- Vietnamese one is [`README.vi.md`](README.vi.md). Both are only gateways, not
15
- normative — when the two disagree, **both are wrong** until they agree with
16
- `CONVENTIONS.md` again.)*
12
+ ## Quick start
13
+
14
+ ```sh
15
+ git clone https://github.com/futurelastic/colab-handbook.git ~/code/colab-handbook
16
+ cd ~/code/colab-handbook && ./install.sh --all # skills + colab CLI + hooks; --dry shows it first
17
+ cd /path/to/your-repo
18
+ colab adopt # asks only what it cannot detect, writes .github/project.yml
19
+ colab labels --ensure # creates the convention labels
20
+ colab register # adds the repo to this machine's fleet list
21
+ ```
22
+
23
+ Then, in an agent session in that repo, run `/code-start <issue-number>`. With an
24
+ agent at hand, `/handbook-sync` replaces the last three commands and also does
25
+ the rest of adoption (see [*Adopting it into a repo*](#adopting-it-into-a-repo)).
26
+ You need `git`, `node` ≥ 18 and `gh` logged in (`gh auth login`).
27
+
28
+ *([`CONVENTIONS.md`](CONVENTIONS.md) is the normative document, written in
29
+ English so agents and tooling can read it. This file and the Vietnamese
30
+ [`README.vi.md`](README.vi.md) are only gateways. When the two disagree, **both
31
+ are wrong** until they agree with `CONVENTIONS.md` again.)*
17
32
 
18
33
  ## What this is
19
34
 
@@ -22,10 +37,10 @@ what a release is, how you announce "I am working on this" — and deliberately
22
37
  leaves the **implementation** (your Node version, your test runner, your CI
23
38
  file) to each repo.
24
39
 
25
- Everything here was distilled from running ~25 real repos, several of them
40
+ It was distilled from running a fleet of real repos, several of them
26
41
  production apps maintained almost entirely by AI agents working in parallel
27
42
  across many worktrees. The anti-pattern list is not theory: every entry is
28
- something that actually happened, with the scar to prove it.
43
+ something that actually happened.
29
44
 
30
45
  ### The problem it solves
31
46
 
@@ -50,20 +65,17 @@ a repo that live in someone's memory instead of in the repo.**
50
65
 
51
66
  ### What it actually does
52
67
 
53
- It makes each repo answer a handful of questions about itself, **once**, in a
54
- file every session reads before touching anything — is there production today,
55
- who else works here, what breaks if a merge is wrong, how many units of work run
56
- at a time, how a commit reaches the thing that runs it.
68
+ It makes each repo answer five questions about itself, **once**, in a file
69
+ every session reads before touching anything (see [*The five
70
+ questions*](#the-five-questions)). Everything else follows from those answers:
71
+ which branch to merge into, what a release even means here, whether a branch is
72
+ required at all, how much a session must write down before it stops.
57
73
 
58
- Everything else follows from those answers: which branch to merge into, what a
59
- release even means here, whether a branch is required at all, how much a session
60
- must write down before it stops. A session never guesses, and two repos never
61
- disagree about what a word means.
62
-
63
- The rest of the repo exists to serve that: a CLI that performs the mechanical
64
- parts, an audit that reports where reality has drifted from what a repo claims,
65
- and portable session flows so a coding session opens and closes the same way
66
- everywhere.
74
+ The rest of the repo serves that: a CLI that performs the mechanical parts, an
75
+ audit that reports where reality has drifted from what a repo claims, and
76
+ session flows (skills) so a coding session opens and closes the same way
77
+ everywhere. The skills are plain prose — a person at a terminal can follow them
78
+ with no agent and no other tool.
67
79
 
68
80
  ### What it is not
69
81
 
@@ -73,48 +85,123 @@ everywhere.
73
85
  - **Not a CI system, and not an opinion about your stack.** Bring your own
74
86
  language, test runner and pipeline. The handbook only asks that the pipeline
75
87
  produce two outcomes, and never says how.
76
- - **Not an enforcement layer**, with one deliberate exception. Conformance is
77
- advisory, because being wrong about a convention costs a conversation.
78
- Publication blocks, because history cannot be recalled once anything is
79
- cloned.
88
+ - **Mostly not an enforcement layer.** Conformance is advisory. The few things
89
+ that block are listed in [*Why so little
90
+ enforcement*](#why-so-little-enforcement).
80
91
  - **Not a maturity model.** No answer here ranks a repo above another. A repo
81
92
  with no production is not a worse repo; it is a repo with fewer gates.
82
93
 
83
- If you run one repo alone, read the anti-patterns and take what is useful. If
84
- you run many — or you work alongside agents that never met the person who set
85
- the rules — the whole thing is likely to pay for itself faster than it takes to
86
- read.
87
-
88
- ## The questions
89
-
90
- Adopting this means answering five questions about your repo, once, into
91
- `.github/project.yml` — so no session has to guess, and no two repos disagree
92
- on what a word means:
93
-
94
- 1. **Does a deploy target exist today** — and how is it reached: a tag gates
95
- production, the promotion itself deploys, a human runs a runbook, or
96
- nothing is live yet?
97
- 2. **Who else works here** — one person, a team, or the public?
98
- 3. **What would break if you merged something wrong here** — nothing, only
99
- the people already in the room, users via the next promotion, or users and
100
- adopters via a released artifact?
101
- 4. **One unit of work in flight at a time, or several at once?**
102
- 5. **By what path does a commit reach the thing that runs it** — a CI
103
- workflow, a git hook, a documented procedure, a live checkout, a published
104
- artifact, another system's data, or none of those yet?
105
-
106
- The answers decide everything that follows: which branch a session merges
107
- into, what a release is, how much an Issue narrates, what must exist before a
108
- merge can be undone, whether a branch is even required. Nothing here is asked
109
- twice, and nothing is asked that the repo already states for itself — its
110
- default branch, its toolchain, its ports.
111
-
112
- Issues are **claimed** with an assignee plus the `in-progress` label before
113
- work starts, so parallel sessions never collide on the same task.
114
-
115
- The full rules — what each answer resolves to, and why:
116
- [`CONVENTIONS.md`](CONVENTIONS.md). ~15 minutes to read, and the **single
117
- normative file** — everything else in the repo serves it.
94
+ ## Your first session
95
+
96
+ A unit of work goes round one loop. Each step is a skill, invoked in an agent
97
+ session as a slash command (`/code-start 42`), or followed by hand from
98
+ [`skills/`](skills/).
99
+
100
+ | Step | Skill | Who runs it | What it leaves behind |
101
+ |---|---|---|---|
102
+ | 1. Pick | `/code-triage` | coordinator | the ready work in order, `group:` labels on issues that must share a branch, `needs-plan` on hard ones, the start commands |
103
+ | 2. Open | `/code-start <N>` | implementer | the issue claimed, a branch cut from trunk and pushed, a worktree, a short plan file |
104
+ | 3. Work | — | implementer | commits on the branch |
105
+ | 4. Hand off | `/code-wrap` | implementer | what was learned written onto the Issue, the repo's gate run, the branch pushed — then it **stops** |
106
+ | 5. Merge | `/code-ship` | coordinator, after a human go | one squash commit on trunk with `Closes #N`, evidence on each issue, claims released, the worktree removed |
107
+ | 6. Clean up | `/code-sweep` | coordinator | finished work shipped, stale claims and worktrees cleared |
108
+ | 7. Release | release workflow, or `/release-rung` | automatic, or a human where a tag deploys | a candidate tag, then the final after a test period — only where the repo's `exposure` has releases |
109
+
110
+ Also in [`skills/`](skills/): `code-plan` (a full plan for a hard issue, run by
111
+ `code-start` when flagged), `handbook-sync` (bring one repo up to the current
112
+ handbook), and `migration-review` (review a branch's migrations, for whoever a
113
+ repo binds to that role).
114
+
115
+ **Words you will meet:**
116
+
117
+ - **Trunk** — the branch sessions merge into (`trunk:` in `project.yml`).
118
+ **Promotion** — merging trunk into `main` where trunk is not `main`; on a
119
+ `live` repo the promotion *is* the deploy.
120
+ - **Claim** — an assignee plus the `in-progress` label, backed by the branch
121
+ pushed to the remote, taken *before* work starts.
122
+ - **Implementer / coordinator** — the session that writes the code / the one
123
+ that picks, merges and cleans up. One person may be both, at different times.
124
+ - **Phase A / Phase B** — `code-wrap` (the implementer's half, ends before any
125
+ merge) / `code-ship` (the coordinator's half: the merge and everything after).
126
+ - **Rung** — how much plan a session writes: 0 none, 1 a five-line stub, 2 a
127
+ full plan from `code-plan`.
128
+
129
+ Newcomers: read [`CONVENTIONS.md` §1](CONVENTIONS.md#1-the-model-in-one-picture)
130
+ (the model) and [§11](CONVENTIONS.md#11-quick-reference) (quick reference)
131
+ first. The rest of `CONVENTIONS.md` is reference — look things up, do not read
132
+ it end to end.
133
+
134
+ ## The five questions
135
+
136
+ Adopting means answering these about your repo, once, into
137
+ `.github/project.yml`. `colab adopt` asks them as numbered menus:
138
+
139
+ | # | Question | Writes |
140
+ |---|---|---|
141
+ | 1 | Does a deploy target exist **today** (not "soon"), and how is it reached — a tag, the promotion itself, a human running a runbook, or nothing yet? | `production` + `deploy` |
142
+ | 2 | Who else works here — just you, a team, or the public? | `room` |
143
+ | 3 | What would break if you merged something wrong here — nothing, only people already in the room, users via the next promotion, or users and adopters via a released artifact? | `exposure` |
144
+ | 4 | May a human commit straight to trunk alongside worktree sessions — freely, with declared intent, or never? | `writes` |
145
+ | 5 | By what path does a commit reach the thing that runs it — a CI workflow, a git hook, a documented procedure, a live checkout, a published artifact, another system's data, or none yet? | `channels` |
146
+
147
+ Nothing is asked that the repo already states — its default branch (`trunk`),
148
+ its toolchain, its ports are detected. Gate count, release ritual and whether a
149
+ branch is mandatory are derived from the answers. What each answer resolves to,
150
+ and why: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) and
151
+ [§9](CONVENTIONS.md#9-adopting-this); every field:
152
+ [`project.schema.md`](project.schema.md).
153
+
154
+ ## Adopting it into a repo
155
+
156
+ **The default route: run `/handbook-sync` in an agent session inside the repo.**
157
+ It sees that nothing is adopted yet and drives adoption to the end — the
158
+ descriptor (through `colab adopt`), the labels, the `CLAUDE.md` block, CI from
159
+ the templates, and registration on this machine. Run later, the same skill
160
+ brings an adopted repo up to the current handbook without losing your local
161
+ edits.
162
+
163
+ By hand, the same steps (full checklist:
164
+ [`CONVENTIONS.md` §9](CONVENTIONS.md#9-adopting-this)):
165
+
166
+ 1. `colab adopt` — answers the five questions and writes
167
+ `.github/project.yml`. It stops there and prints the remaining steps.
168
+ 2. `colab labels --ensure` — the convention labels do not exist by default. A
169
+ check whose label was never created can never fire.
170
+ 3. Paste [`templates/repo-CLAUDE-block.md`](templates/repo-CLAUDE-block.md)
171
+ into the repo's `CLAUDE.md` — this is how agents discover the conventions.
172
+ 4. Make sure CI produces the two required outcomes: a secret scan and a build,
173
+ with toolchain versions **resolved from the repo's own manifest**, never
174
+ hardcoded. Copy a template from [`templates/`](templates/) if it helps.
175
+ 5. `colab register` — puts the repo on this machine's fleet list, so the audit
176
+ and the port allocator both know it.
177
+
178
+ `colab adopt` flags worth knowing:
179
+
180
+ - `--autonomy auto-trunk` — records the maintainer's grant that lets an agent
181
+ finish the trunk merge through `colab ship` (never a release). Needs a human.
182
+ - `--land` — commits what this run wrote straight to trunk and pushes it, so
183
+ the first feature branch is judged by the new rules. Needs a human
184
+ (`COLAB_HUMAN=1` and `--answered-by`).
185
+ - `--fork` — the repo tracks an upstream you don't own (detected when a remote
186
+ named `upstream` exists); the `CLAUDE.md` block is then appended, never
187
+ restructured, and the upstream's own agent workflow is named.
188
+ - `--local` — you cannot commit to this repo at all; everything stays in your
189
+ clone ([*Working in a repo you don't
190
+ own*](CONVENTIONS.md#working-in-a-repo-you-dont-own)).
191
+
192
+ Pre-existing branches are **grandfathered**. Do not rename anything.
193
+
194
+ ## Optional automation on top
195
+
196
+ Nothing here assumes a dashboard, scheduler or bot exists. An adopter may still
197
+ build one: open sessions from a button, run the loop on a schedule, treat a
198
+ human's click on a merge button as the go that `code-ship` waits for, or push
199
+ notifications when work changes state. Such a tool reads the same shared
200
+ artefacts a person does — `.github/project.yml`, the labels, the claims on each
201
+ Issue, the machine-local `~/.colab/state.json` — and can receive `colab`'s
202
+ events at `notifyUrl` ([`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default)).
203
+ It never changes a `colab` gate: the go before a merge and the grant before a
204
+ migration hold with or without it.
118
205
 
119
206
  ## Repo layout
120
207
 
@@ -123,183 +210,80 @@ normative file** — everything else in the repo serves it.
123
210
  | [`CONVENTIONS.md`](CONVENTIONS.md) | The rules. Normative, the single source of truth (EN). |
124
211
  | [`CLAUDE.md`](CLAUDE.md) | The entry point for AI agents — the operational distillation (EN). |
125
212
  | [`project.schema.md`](project.schema.md) | Field reference for `.github/project.yml`. |
126
- | [`templates/`](templates/) | **Copy-and-own** starting points: CI, release, git hooks (a secret scan and an identity scan), and the `CLAUDE.md` block for adopting repos. **Nothing is called remotely** — copy it, edit it, own it. Templates, not scaffolding, because scaffolding only reaches repos created after it shipped. |
127
- | [`tools/`](tools/) | `colab` — a small CLI (optional): adopt a repo, claim issues, allocate ports, manage worktrees, and merge a finished branch to trunk when the repo grants it. JSON state, zero dependencies. Full command reference: [`tools/README.md`](tools/README.md). |
128
- | [`audit/`](audit/) | An external conformance checker. Reads all your repos — every owner, including local-only ones — and reports drift in a single run. Advisory only, never blocking. `--identity` additionally scans public repository descriptions and topics, which no git hook can see. What each check means: [`audit/README.md`](audit/README.md). |
129
- | [`skills/`](skills/) | Portable session flow: `code-triage` (pick the next task, flagging hard ones for a plan) → `code-start` (open a session; runs `code-plan` when flagged) → `code-wrap` (distill + gate + hand off) → `code-ship` (grade + merge, human-authorized), plus `code-sweep` (clear out everything ALREADY DONE in one repo — or just a named set of issues or one session — running `code-wrap`+`code-ship` on each) `handbook-sync` (bring ONE repo up to the latest handbook, run from inside it), and `release-rung` (the manual fallback and explainer for the release workflow, which is the driver: walk one repo's release rung from a coordinator session — candidate, test period, `release-hold` veto, final — through `colab release cut`/`finalize`, never by hand), and `migration-review` (for whoever a repo binds to the migration-reviewer role: review a branch's migrations against the deploy engine and end in one verdict — GRANT with a review record, REWORK with a brief, or ESCALATE to a human — with a blind test set to run before binding a new reviewer). Installed as Claude Code skills by [`install.sh`](install.sh) — see *Setting up a machine* below. |
130
- | [`install.sh`](install.sh) | Sets up **your machine**: skills, the `colab` CLI, the pre-commit hook, the fleet list. Idempotent, and `--dry` shows you everything first. |
131
-
132
- ## Install the CLI from npm
133
-
134
- The `colab` CLI is also published as a public npm package, **`@futurelastic/colab-handbook`**. The command you type stays `colab`.
135
-
136
- ```sh
137
- npx @futurelastic/colab-handbook <command> # one-off, nothing installed, no npm account needed
138
- npm i -g @futurelastic/colab-handbook # then: colab <command>
139
- npm i -g @futurelastic/colab-handbook@next # release candidates (vX.Y.Z-rc.N) instead of finals
140
- ```
141
-
142
- The package carries what `colab` reads at runtime — the CLI, its `lib/`, `templates/` and `audit/audit.mjs` — and nothing else; `colab template` and `colab adopt` work from the registry copy and stamp the package's own version. The skills are **not** in it: they install with `./install.sh` from a clone (below), because they must symlink into `~/.claude/skills/`. Every tarball is checked file by file against an allowlist in CI (`scripts/check-pack-allowlist.mjs`).
213
+ | [`templates/`](templates/) | **Copy-and-own** starting points: CI, release, git hooks (a secret scan and an identity scan), and the `CLAUDE.md` block for adopting repos. Nothing is called remotely — copy it, edit it, own it. |
214
+ | [`tools/`](tools/) | `colab` — a small CLI (optional): adopt a repo, claim issues, allocate ports, manage worktrees, and merge a finished branch to trunk when the repo grants it. JSON state, zero dependencies. Command reference: [`tools/README.md`](tools/README.md). |
215
+ | [`audit/`](audit/) | An external conformance checker. Reads all your repos — every owner, including local-only ones — and reports drift in a single run. Advisory only. `--identity` also scans public repository descriptions and topics, which no git hook can see. What each check means: [`audit/README.md`](audit/README.md). |
216
+ | [`skills/`](skills/) | The session flow — see [*Your first session*](#your-first-session). Installed as Claude Code skills by `install.sh`. |
217
+ | [`install.sh`](install.sh) | Sets up **your machine**: skills, the `colab` CLI, the pre-commit hook, the fleet list. Idempotent; `--dry` shows everything first. |
143
218
 
144
219
  ## Setting up a machine
145
220
 
146
- Once per machine, before you adopt anything into a repo.
147
-
148
- **You need:** `git`; `node` ≥ 18 (`.nvmrc` pins 22, which is what CI here runs);
149
- `gh` **logged in** (`gh auth login`) — claims, the skills and the audit's remote
150
- targets are all useless without it, and the failure surfaces much later as
151
- something confusing; and `gitleaks` only if you want the pre-commit hook.
152
- `install.sh` checks every one of these and reports what is missing before it
153
- changes anything.
154
-
155
- **1. Clone it somewhere permanent** — with the rest of your code, not in a
156
- scratch directory.
157
-
158
- ```sh
159
- git clone https://github.com/futurelastic/colab-handbook.git ~/code/colab-handbook
160
- cd ~/code/colab-handbook
161
- ```
162
-
163
- **This clone is infrastructure, not a download.** The skills install as symlinks
164
- *into this working tree*: delete the clone and every session on the machine
165
- loses them, and whichever branch it has checked out is the version of the skills
166
- every session gets. So keep it on `main` unless you are actively working on the
167
- handbook itself. `install.sh` warns if it finds itself under `/tmp`,
168
- `~/Downloads` or `~/Desktop`.
169
-
170
- **2. Install.**
171
-
172
- ```sh
173
- ./install.sh --all --dry # see exactly what would happen; changes nothing
174
- ./install.sh --all # skills + colab CLI + pre-commit hook + fleet list
175
- ```
176
-
177
- `--all` is the recommended first run. Everything it does is a symlink or a copy,
178
- it is idempotent, and it never overwrites anything it did not create — your own
179
- skill, or an existing `~/.colab/repos.txt`, is left alone with a warning. Bare
180
- `./install.sh` installs the skills and nothing else, if that is genuinely all
181
- you want.
221
+ Once per machine. Clone somewhere permanent — the skills are symlinks *into
222
+ this working tree*, so whichever branch it has checked out is the version every
223
+ session gets; keep it on `main`. `install.sh` checks its prerequisites before it
224
+ changes anything, never overwrites what it did not create, and `--dry` prints
225
+ the plan first.
182
226
 
183
227
  | Flag | What it does |
184
228
  |---|---|
185
229
  | *(none)* | Symlink `skills/` into `~/.claude/skills/`, so they are available in every repo you open. |
186
- | `--tools` | Two installs of one CLI: a **symlink** at `~/.local/bin/colab` for your sessions (checking that directory is really on your `PATH`, and printing the exact line to add if not), plus a stamped **frozen copy** at `~/.colab/bin/colab` for always-on services — see below. |
187
- | `--hooks` | Point this clone's git at `.githooks/`, whose `pre-commit` runs every check in `pre-commit.d/` — a gitleaks secret scan, and an identity scan that needs a vocabulary you supply by path and keep outside every repo (see [`templates/README.md`](templates/README.md)). `core.hooksPath` lives in `.git/config`, so it is per-clone, per-machine, and never travels with the repo. |
188
- | `--fleet` | Seed `~/.colab/repos.txt` from `audit/repos.txt`, only if it is absent. The seed is format notes and commented placeholders — it registers **nothing**; `colab register <path>` (step 3) is what fills it. That list stays machine-local on purpose: it names your private repos, and this repo is public. |
230
+ | `--tools` | The `colab` CLI twice: a **symlink** at `~/.local/bin/colab` for your sessions (it prints the `PATH` line if needed), and a stamped **frozen copy** at `~/.colab/bin/colab` for always-on services. Also creates an empty `~/.colab/state.json` if there is none. |
231
+ | `--hooks` | Point this clone's git at `.githooks/`: a gitleaks secret scan and an identity scan whose vocabulary you keep outside every repo (see [`templates/README.md`](templates/README.md)). |
232
+ | `--fleet` | Seed `~/.colab/repos.txt` with format notes only, if absent. It stays machine-local because it names your private repos; `colab register` fills it. |
189
233
  | `--all` | `--tools --hooks --fleet`. |
190
- | `--notify-url <url>` | Seed `notifyUrl` in `~/.colab/config.json` with a local observer's events URL, only when the key is absent — an existing value is never overwritten. Without the flag, `--tools` seeds it from `~/.colab/notify-endpoint` when a local observer declared its URL there, and otherwise prints that `notifyUrl` is unset and which events that drops. See [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
191
- | `--dry` | Print what would happen, change nothing. Combines with all of the above. |
192
- | `--check` | **Read-only** health report on what an earlier install left behind — see *Checking an install* below. Takes no other flag; exit 1 on any ✗ row. |
193
-
194
- `--tools` also creates an **empty** `~/.colab/state.json` when there is none (it never
195
- touches an existing one). Without that, the file appeared only on the first
196
- state-changing `colab` command, and anything reading it on a fresh machine got an
197
- error where it should have seen an empty fleet.
198
-
199
- **Always-on services must call `~/.colab/bin/colab`.** The symlinked CLI follows
200
- whatever branch this clone has checked out — deliberate for a human session, and
201
- wrong for anything that outlives one. A daemon, a launch agent or a headless
202
- runner started months ago would silently change behaviour because somebody
203
- checked out an unrelated branch, and nothing would report it: the process keeps
204
- working, differently. So `--tools` also writes a **copy** to `~/.colab/bin/`
205
- (honouring `COLAB_HOME`), stamped with the handbook version it was taken from —
206
- or, when that tree sits ahead of the last tag, with the commit it was taken from
207
- (`v1.7.0-2-gc8436c6`) and a warning, because no released version describes those
208
- bytes. That copy never moves on its own.
209
-
210
- Refreshing it is therefore an act, never a side effect: re-run `./install.sh
211
- --tools`. `colab update` tells you when it is due. **`behind` means a released
212
- CLI change exists that this machine lacks** — the comparison runs to the latest
213
- tag, so a release that changed no CLI code does not nag you, and unreleased work
214
- in your own checkout does not either. (That last part is why the bound is the tag
215
- rather than `HEAD`: measuring to `HEAD` marked every machine stale for the whole
216
- window between a CLI commit and the next tag, and the advertised remedy copies
217
- *from* that same working tree — so on a machine developing the handbook it
218
- advised services to adopt untagged code.) It never rewrites the copy, not even
219
- with `--apply`: that is the toolchain your running services are executing.
220
- `colab --version` says which of the two you are talking to (or `npm package` for an
221
- `npx`/`npm i` install), and prints that install's version. The frozen copy carries
222
- `tools/` only, so `colab template` refuses there — run it from the working tree.
223
-
224
- **3. Verify, and register your repos.**
225
-
226
- ```sh
227
- colab --help # not found? fix your PATH — step 2 prints the exact line
228
- colab --version # which colab is this — working tree, frozen copy, or npm package — and its version
229
- colab register /path/to/repo # once per repo — writes repos.txt AND config.json, so they agree
230
- node audit/audit.mjs # a conformance report across the whole fleet
231
- colab update # stamped copies that fell behind — the frozen CLI included
232
- ```
233
-
234
- `colab register` is the way in; hand-editing `~/.colab/repos.txt` still works for
235
- the audit, but leaves `config.json` — where the CLI reserves each repo's ports —
236
- unaware of the repo. A remote-only audit target (`owner/name`, nothing cloned) is
237
- the one entry you add to `repos.txt` by hand. A repo not yet adopted then needs
238
- `colab adopt` and `colab labels --ensure` — see *Adopting it into a repo* below.
234
+ | `--notify-url <url>` | Seed `notifyUrl` in `~/.colab/config.json`, only if the key is absent. See [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
235
+ | `--dry` | Print what would happen, change nothing. Combines with the flags above. |
236
+ | `--check` | **Read-only** health report on an earlier install — see below. Takes no other flag; exit 1 on any ✗ row. |
237
+
238
+ **Always-on services (launch agents, daemons, headless runners) must call
239
+ `~/.colab/bin/colab`, not the symlink**, because the symlink follows whatever
240
+ branch this clone has checked out. The frozen copy never moves on its own:
241
+ `colab update` says when it is behind a released CLI change, and re-running
242
+ `./install.sh --tools` refreshes it. Why it works this way:
243
+ [`tools/README.md`](tools/README.md#install).
244
+
245
+ **The CLI alone, without the skills,** is on npm as
246
+ **`@futurelastic/colab-handbook`** — `npx @futurelastic/colab-handbook <command>`,
247
+ or `npm i -g @futurelastic/colab-handbook` (`@next` for release candidates). The
248
+ command is still `colab`. The skills are not in the package; they install from a
249
+ clone, because they must symlink into `~/.claude/skills/`.
239
250
 
240
251
  ### Checking an install
241
252
 
242
253
  ```sh
243
- ./install.sh --check # read-only; exit 1 on any ✗ row
254
+ colab --version # which colab answered — working tree, frozen copy or npm package — and its version
255
+ ./install.sh --check # read-only; exit 1 on any ✗ row
256
+ node audit/audit.mjs # a conformance report across every registered repo
257
+ colab update # stamped copies that fell behind, the frozen CLI included
244
258
  ```
245
259
 
246
- A frozen copy never breaks — it gets **old**, and an old complete copy answers
247
- normally for every command it knows until something asks for one added after it
248
- was frozen. `--check` is the report nothing else gives: whether the frozen copy is
249
- behind the latest release, **which commands it does not dispatch**, whether the
250
- state file exists, whether anything is registered, whether both pre-commit
251
- hooklets can actually run (gitleaks, and the identity vocabulary), and whether
260
+ `--check` reports whether the frozen copy is behind the latest release and
261
+ which commands it does not dispatch, whether the state file exists, whether
262
+ anything is registered, whether both pre-commit hooklets can run, and whether
252
263
  `notifyUrl` is unset while a local observer declared an endpoint. ✗ means
253
- something installed here is stale or unusable; ⚠ means something was never set
254
- up, which may be deliberate. It never refreshes anything — re-freezing stays your
255
- call: `./install.sh --tools`.
256
-
257
- Then read [`CONVENTIONS.md`](CONVENTIONS.md): ~15 minutes, and the only
258
- normative file here.
264
+ something installed is stale or unusable; ⚠ means something was never set up,
265
+ which may be deliberate. It never refreshes anything.
259
266
 
260
- ## Adopting it into a repo
267
+ ## Why so little enforcement
261
268
 
262
- The short version — the full checklist is
263
- [`CONVENTIONS.md` §9](CONVENTIONS.md#9-adopting-this):
264
-
265
- 1. Answer question 1 honestly (is there production **today**, not "soon").
266
- 2. Add `.github/project.yml`. `colab adopt` asks the five questions and writes
267
- the file for you — it stops at the descriptor and prints the rest of this
268
- list, because the remaining steps are not its to take.
269
- 3. `colab labels --ensure` — the convention labels do not exist by default, and
270
- there are more than one. A check whose label was never created can never
271
- fire.
272
- 4. Paste [`templates/repo-CLAUDE-block.md`](templates/repo-CLAUDE-block.md)
273
- into the repo's `CLAUDE.md` — this is the only way agents discover these
274
- conventions.
275
- 5. Make sure CI produces the two required outcomes: a secret scan and a build,
276
- with toolchain versions **resolved from the repo's own manifest** — never
277
- hardcoded. Copy a template if it helps.
269
+ Branch protection is not available on every plan and every owner a fleet spans,
270
+ so this handbook does not rely on it. It makes **compliance cheap and checking
271
+ cheap** instead: the audit reports drift, and the conventions explain *why*
272
+ each rule exists, so you can judge when breaking one is worth it. When you do,
273
+ fix the documentation in the same change — a document describing a repo that
274
+ does not exist is the worst thing in this business.
278
275
 
279
- Pre-existing branches are **grandfathered**. Do not rename anything.
276
+ **A short list does block, deliberately:**
280
277
 
281
- **Working in a repo you don't own?** If committing these files there is not an option,
282
- `colab adopt --local` keeps everything in your local clone instead, and nothing lands in
283
- the owner's history — see
284
- [*Working in a repo you don't own*](CONVENTIONS.md#working-in-a-repo-you-dont-own).
285
-
286
- ## Why so little enforcement
278
+ - **Publication.** The git hooks refuse a secret, and an identity scan stops a
279
+ hostname, a home path or a customer's name reaching a public repo. History
280
+ cannot be recalled once anything is cloned.
281
+ - **The gates around a merge**, enforced by `colab`: a human go before a merge
282
+ (unless the repo granted `auto-trunk` or the change is docs-only), a grant
283
+ before a migration ships, and a release never bundled into a merge.
287
284
 
288
- Our private repos sit on a GitHub plan without branch protection — pushes to
289
- `main` cannot be forbidden. So this handbook does not pretend to enforce; it
290
- makes **compliance cheap and checking cheap**. The audit tool reports drift; the
291
- conventions explain *why* each rule exists, so you can judge for yourself when
292
- breaking one is worth it. When you do break one, fix the documentation in the
293
- same PR — a document describing a repo that does not exist is the worst thing in
294
- this business.
295
-
296
- **Two things do block, and the line between them is deliberate.** The git hooks
297
- refuse: a secret scan, and an identity scan that stops a hostname, a home path
298
- or a customer's name reaching a public repo. Those guard **publication**, which
299
- is the one mistake that cannot be undone — history cannot be recalled once
300
- anything is cloned. Everything about *conformance* stays advisory, because being
301
- wrong about a convention costs a conversation, and being wrong about publication
302
- costs forever.
285
+ Everything else is a default — one good way to do it — because being wrong
286
+ about a convention costs a conversation.
303
287
 
304
288
  ## License
305
289