@futurelastic/colab-handbook 1.12.0-rc.9 → 1.13.0-rc.1

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.
Files changed (76) hide show
  1. package/README.md +244 -212
  2. package/README.vi.md +246 -185
  3. package/audit/audit.mjs +197 -12
  4. package/package.json +6 -1
  5. package/templates/README.md +49 -2
  6. package/templates/ci-laravel.yml +181 -18
  7. package/templates/ci-node.yml +137 -0
  8. package/templates/ci-python.yml +128 -0
  9. package/templates/deploy-adapter-portainer.mjs +206 -0
  10. package/templates/deploy-container-run.mjs +368 -0
  11. package/templates/deploy-container.yml +219 -0
  12. package/templates/dist-refs.yml +6 -0
  13. package/templates/docs-lint.mjs +1 -1
  14. package/templates/npx-launcher.mjs +118 -20
  15. package/templates/npx-service.mjs +828 -0
  16. package/templates/release-auto.yml +364 -35
  17. package/tools/colab +1791 -266
  18. package/tools/lib/adopt.js +373 -14
  19. package/tools/lib/branch-name.js +29 -1
  20. package/tools/lib/ci-cure.js +522 -31
  21. package/tools/lib/ci-grant.js +289 -22
  22. package/tools/lib/ci-wait.js +203 -0
  23. package/tools/lib/claim-comments.js +13 -64
  24. package/tools/lib/claim-identity.js +4 -7
  25. package/tools/lib/codec/claim.d.ts +41 -0
  26. package/tools/lib/codec/claim.js +151 -0
  27. package/tools/lib/codec/decision.d.ts +29 -0
  28. package/tools/lib/codec/decision.js +81 -0
  29. package/tools/lib/codec/grants.d.ts +82 -0
  30. package/tools/lib/codec/grants.js +268 -0
  31. package/tools/lib/codec/hold.d.ts +26 -0
  32. package/tools/lib/codec/hold.js +152 -0
  33. package/tools/lib/codec/index.d.ts +21 -0
  34. package/tools/lib/codec/index.js +32 -0
  35. package/tools/lib/codec/labels.d.ts +65 -0
  36. package/tools/lib/codec/labels.js +716 -0
  37. package/tools/lib/codec/markers.d.ts +35 -0
  38. package/tools/lib/codec/markers.js +138 -0
  39. package/tools/lib/codec/release.d.ts +17 -0
  40. package/tools/lib/codec/release.js +69 -0
  41. package/tools/lib/codec/samples.json +762 -0
  42. package/tools/lib/codeowners.js +68 -4
  43. package/tools/lib/conflict-markers.js +47 -0
  44. package/tools/lib/container-close.js +38 -0
  45. package/tools/lib/cure-diff.js +198 -9
  46. package/tools/lib/decision-record.js +15 -39
  47. package/tools/lib/docs-only.js +15 -1
  48. package/tools/lib/exposure-shape.js +42 -8
  49. package/tools/lib/git.js +303 -42
  50. package/tools/lib/group-labels.js +65 -0
  51. package/tools/lib/hermetic.js +72 -6
  52. package/tools/lib/install-check.js +34 -9
  53. package/tools/lib/install-route.js +139 -0
  54. package/tools/lib/instruction-file.js +1 -0
  55. package/tools/lib/labels.js +22 -647
  56. package/tools/lib/local-adopt.js +8 -4
  57. package/tools/lib/migration-grant.js +206 -104
  58. package/tools/lib/notify-endpoint.js +170 -0
  59. package/tools/lib/place.js +2 -2
  60. package/tools/lib/release-cut.js +199 -25
  61. package/tools/lib/release-finalize.js +160 -32
  62. package/tools/lib/release-policy.js +130 -22
  63. package/tools/lib/release-runner.js +125 -0
  64. package/tools/lib/release-tag.js +3 -1
  65. package/tools/lib/scratch-dirs.js +106 -0
  66. package/tools/lib/ship-batch.js +46 -1
  67. package/tools/lib/stamp.js +7 -0
  68. package/tools/lib/tracker-fake.js +195 -0
  69. package/tools/lib/tracker-github.js +106 -0
  70. package/tools/lib/tracker-scenarios.json +206 -0
  71. package/tools/lib/tracker.js +64 -0
  72. package/tools/lib/tree-green.js +88 -0
  73. package/tools/lib/util.js +17 -1
  74. package/tools/lib/verify-runs.js +104 -0
  75. package/tools/lib/wake.js +8 -90
  76. package/tools/lib/workflow-triggers.js +48 -0
package/README.md CHANGED
@@ -9,11 +9,27 @@ 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, from the newest release; --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` ≥ 2.94 logged in (`gh auth login`); distro
27
+ packages often ship an older `gh`, so install it from [cli.github.com](https://cli.github.com).
28
+
29
+ *([`CONVENTIONS.md`](CONVENTIONS.md) is the normative document, written in
30
+ English so agents and tooling can read it. This file and the Vietnamese
31
+ [`README.vi.md`](README.vi.md) are only gateways. When the two disagree, **both
32
+ are wrong** until they agree with `CONVENTIONS.md` again.)*
17
33
 
18
34
  ## What this is
19
35
 
@@ -22,10 +38,10 @@ what a release is, how you announce "I am working on this" — and deliberately
22
38
  leaves the **implementation** (your Node version, your test runner, your CI
23
39
  file) to each repo.
24
40
 
25
- Everything here was distilled from running ~25 real repos, several of them
41
+ It was distilled from running a fleet of real repos, several of them
26
42
  production apps maintained almost entirely by AI agents working in parallel
27
43
  across many worktrees. The anti-pattern list is not theory: every entry is
28
- something that actually happened, with the scar to prove it.
44
+ something that actually happened.
29
45
 
30
46
  ### The problem it solves
31
47
 
@@ -50,20 +66,17 @@ a repo that live in someone's memory instead of in the repo.**
50
66
 
51
67
  ### What it actually does
52
68
 
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.
57
-
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.
69
+ It makes each repo answer five questions about itself, **once**, in a file
70
+ every session reads before touching anything (see [*The five
71
+ questions*](#the-five-questions)). Everything else follows from those answers:
72
+ which branch to merge into, what a release even means here, whether a branch is
73
+ required at all, how much a session must write down before it stops.
62
74
 
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.
75
+ The rest of the repo serves that: a CLI that performs the mechanical parts, an
76
+ audit that reports where reality has drifted from what a repo claims, and
77
+ session flows (skills) so a coding session opens and closes the same way
78
+ everywhere. The skills are plain prose — a person at a terminal can follow them
79
+ with no agent and no other tool.
67
80
 
68
81
  ### What it is not
69
82
 
@@ -73,48 +86,148 @@ everywhere.
73
86
  - **Not a CI system, and not an opinion about your stack.** Bring your own
74
87
  language, test runner and pipeline. The handbook only asks that the pipeline
75
88
  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.
89
+ - **Mostly not an enforcement layer.** Conformance is advisory. The few things
90
+ that block are listed in [*Why so little
91
+ enforcement*](#why-so-little-enforcement).
80
92
  - **Not a maturity model.** No answer here ranks a repo above another. A repo
81
93
  with no production is not a worse repo; it is a repo with fewer gates.
82
94
 
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.
95
+ ## Your first session
96
+
97
+ A unit of work goes round one loop. Each step is a skill, invoked in an agent
98
+ session as a slash command (`/code-start 42`), or followed by hand from
99
+ [`skills/`](skills/).
100
+
101
+ | Step | Skill | Who runs it | What it leaves behind |
102
+ |---|---|---|---|
103
+ | 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 |
104
+ | 2. Open | `/code-start <N>` | implementer | the issue claimed, a branch cut from trunk and pushed, a worktree, a short plan file |
105
+ | 3. Work | — | implementer | commits on the branch |
106
+ | 4. Hand off | `/code-wrap` | implementer | what was learned written onto the Issue, the repo's gate run, the branch pushed — then it **stops** |
107
+ | 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 |
108
+ | 6. Clean up | `/code-sweep` | coordinator | finished work shipped, stale claims and worktrees cleared |
109
+ | 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 |
110
+
111
+ Also in [`skills/`](skills/): `code-plan` (a full plan for a hard issue, run by
112
+ `code-start` when flagged), `handbook-sync` (bring one repo up to the current
113
+ handbook), and `migration-review` (review a branch's migrations, for whoever a
114
+ repo binds to that role).
115
+
116
+ **Words you will meet:**
117
+
118
+ - **Trunk** — the branch sessions merge into (`trunk:` in `project.yml`).
119
+ **Promotion** — merging trunk into `main` where trunk is not `main`; on a
120
+ `live` repo the promotion *is* the deploy.
121
+ - **Claim** — an assignee plus the `in-progress` label, backed by the branch
122
+ pushed to the remote, taken *before* work starts.
123
+ - **Implementer / coordinator** — the session that writes the code / the one
124
+ that picks, merges and cleans up. One person may be both, at different times.
125
+ - **Phase A / Phase B** — `code-wrap` (the implementer's half, ends before any
126
+ merge) / `code-ship` (the coordinator's half: the merge and everything after).
127
+ - **Rung** — how much plan a session writes: 0 none, 1 a five-line stub, 2 a
128
+ full plan from `code-plan`.
129
+
130
+ Newcomers: read [`CONVENTIONS.md` §1](CONVENTIONS.md#1-the-model-in-one-picture)
131
+ (the model) and [§11](CONVENTIONS.md#11-quick-reference) (quick reference)
132
+ first. The rest of `CONVENTIONS.md` is reference — look things up, do not read
133
+ it end to end.
134
+
135
+ ## The five questions
136
+
137
+ Adopting means answering these about your repo into `.github/project.yml`.
138
+ `colab adopt` asks only the two that change a gate (1 and 3), as numbered menus;
139
+ the other three are optional and can be answered any time later:
140
+
141
+ | # | Question | Writes | At adoption |
142
+ |---|---|---|---|
143
+ | 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` | asked |
144
+ | 2 | Who else works here — just you, a team, or the public? | `room` | optional — `colab adopt --axis room` |
145
+ | 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` | asked — a human's answer |
146
+ | 4 | May a human commit straight to trunk alongside worktree sessions — freely, with declared intent, or never? | `writes` | optional — `colab adopt --axis writes` |
147
+ | 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` | optional — `colab adopt --axis channels` |
148
+
149
+ **Answering question 3 is a human's act** when the answer is "nothing" or "only
150
+ people already in the room". An agent can drive everything else; when it gets
151
+ there, `colab adopt` prints, as its first line, the one command the human runs.
152
+
153
+ Nothing is asked that the repo already states — its default branch (`trunk`,
154
+ kept as it is: a `master` default is fine, nothing needs renaming),
155
+ its toolchain, its ports are detected. Gate count, release ritual and whether a
156
+ branch is mandatory are derived from the answers. What each answer resolves to,
157
+ and why: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) and
158
+ [§9](CONVENTIONS.md#9-adopting-this); every field:
159
+ [`project.schema.md`](project.schema.md).
160
+
161
+ ## Adopting it into a repo
162
+
163
+ **The default route: run `/handbook-sync` in an agent session inside the repo.**
164
+ It sees that nothing is adopted yet and drives adoption to the end — the
165
+ descriptor (through `colab adopt`), the labels, the `CLAUDE.md` block, CI from
166
+ the templates, and registration on this machine. Run later, the same skill
167
+ brings an adopted repo up to the current handbook without losing your local
168
+ edits.
169
+
170
+ By hand, the same steps (full checklist:
171
+ [`CONVENTIONS.md` §9](CONVENTIONS.md#9-adopting-this)):
172
+
173
+ 1. `colab adopt` — answers the two gating questions and writes
174
+ `.github/project.yml`. It stops there and prints the remaining steps.
175
+ 2. `colab labels --ensure` — the convention labels do not exist by default. A
176
+ check whose label was never created can never fire.
177
+ 3. Paste [`templates/repo-CLAUDE-block.md`](templates/repo-CLAUDE-block.md)
178
+ into the repo's `CLAUDE.md` — this is how agents discover the conventions.
179
+ 4. Make sure CI produces the two required outcomes: a secret scan and a build,
180
+ with toolchain versions **resolved from the repo's own manifest**, never
181
+ hardcoded. Copy a template from [`templates/`](templates/) if it helps.
182
+ 5. `colab register` — puts the repo on this machine's fleet list, so the audit
183
+ and the port allocator both know it.
184
+
185
+ `colab adopt` flags worth knowing:
186
+
187
+ - `--autonomy auto-trunk` — records the maintainer's grant that lets an agent
188
+ finish the trunk merge through `colab ship` (never a release). Needs a human.
189
+ - `--land` — commits what this run wrote straight to trunk and pushes it, so
190
+ the first feature branch is judged by the new rules. Needs a human
191
+ (`COLAB_HUMAN=1` and `--answered-by`).
192
+ - `--fork` — the repo tracks an upstream you don't own (detected when a remote
193
+ named `upstream` exists); the `CLAUDE.md` block is then appended, never
194
+ restructured, and the upstream's own agent workflow is named.
195
+ - `--local` — you cannot commit to this repo at all; everything stays in your
196
+ clone ([*Working in a repo you don't
197
+ own*](CONVENTIONS.md#working-in-a-repo-you-dont-own)).
198
+
199
+ Pre-existing branches are **grandfathered**. Do not rename anything.
200
+
201
+ ## Customising a skill for your repo
202
+
203
+ Want a skill to behave differently in one repo — Issue comments in Japanese, an
204
+ extra check before wrap? Do not fork the skill: a fork stops receiving handbook
205
+ updates. Write the difference in `.colab/skills/<skill>.md` (for example
206
+ `.colab/skills/code-wrap.md`), in plain prose. Every skill reads that file
207
+ before its own steps, and what it says wins over the skill's text for that repo.
208
+ It never loosens a `colab` gate: a refused claim or merge stays refused. Name
209
+ the step you are refining by its number (`code-ship` B1c, `code-sweep` §3): a
210
+ large skill is a short core plus reference files, and the core keeps every
211
+ step's number.
212
+
213
+ Claude Code loads the file into the skill automatically. Other engines get a
214
+ plain sentence in each skill telling the agent to read the file, which works
215
+ without any engine support. Because the file instructs agents, a change to it
216
+ is never treated as docs-only: it merges on `auto-trunk` or a human's go, like a
217
+ `CLAUDE.md` change. Rule:
218
+ [`CONVENTIONS.md` §8, *Local policy*](CONVENTIONS.md#local-policy--a-repo-refines-a-skill-without-forking-it-520).
219
+
220
+ ## Optional automation on top
221
+
222
+ Nothing here assumes a dashboard, scheduler or bot exists. An adopter may still
223
+ build one: open sessions from a button, run the loop on a schedule, treat a
224
+ human's click on a merge button as the go that `code-ship` waits for, or push
225
+ notifications when work changes state. Such a tool reads the same shared
226
+ artefacts a person does — `.github/project.yml`, the labels, the claims on each
227
+ Issue, the machine-local `~/.colab/state.json` — and can receive `colab`'s
228
+ events at `notifyUrl` ([`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default)).
229
+ It never changes a `colab` gate: the go before a merge and the grant before a
230
+ migration hold with or without it.
118
231
 
119
232
  ## Repo layout
120
233
 
@@ -123,181 +236,100 @@ normative file** — everything else in the repo serves it.
123
236
  | [`CONVENTIONS.md`](CONVENTIONS.md) | The rules. Normative, the single source of truth (EN). |
124
237
  | [`CLAUDE.md`](CLAUDE.md) | The entry point for AI agents — the operational distillation (EN). |
125
238
  | [`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`).
239
+ | [`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. |
240
+ | [`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). |
241
+ | [`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). |
242
+ | [`skills/`](skills/) | The session flow — see [*Your first session*](#your-first-session). Installed as Claude Code skills by `install.sh`. |
243
+ | [`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
244
 
144
245
  ## Setting up a machine
145
246
 
146
- Once per machine, before you adopt anything into a repo.
247
+ Once per machine. Clone somewhere permanent — the skills are symlinks *into
248
+ this working tree*, so whatever it has checked out is the version every session
249
+ gets. `install.sh` checks its prerequisites before it changes anything, never
250
+ overwrites what it did not create, and `--dry` prints the plan first.
147
251
 
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.
252
+ **Which version you get.** `main` runs ahead of the last final release, so the
253
+ first install from a fresh clone checks out the **newest final release tag**
254
+ (`vX.Y.Z`, never a release candidate) and installs from that — the same
255
+ default npm gives you. To follow `main` instead, unreleased work included, run
256
+ the first install with `--trunk`. Every run prints which one you are on.
257
+ Later moves are explicit:
154
258
 
155
- **1. Clone it somewhere permanent** — with the rest of your code, not in a
156
- scratch directory.
259
+ - to a newer release: `./install.sh --release`;
260
+ - from a release back to `main`: `git checkout main && ./install.sh --trunk` (an
261
+ older release's installer does not know `--trunk`, so check out `main` first).
157
262
 
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.
263
+ A clone with uncommitted changes is never moved, and a re-run without either
264
+ flag keeps whatever is checked out.
182
265
 
183
266
  | Flag | What it does |
184
267
  |---|---|
185
268
  | *(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. |
269
+ | `--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. |
270
+ | `--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)). |
271
+ | `--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
272
  | `--all` | `--tools --hooks --fleet`. |
190
- | `--dry` | Print what would happen, change nothing. Combines with all of the above. |
191
- | `--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. |
192
-
193
- `--tools` also creates an **empty** `~/.colab/state.json` when there is none (it never
194
- touches an existing one). Without that, the file appeared only on the first
195
- state-changing `colab` command, and anything reading it on a fresh machine got an
196
- error where it should have seen an empty fleet.
197
-
198
- **Always-on services must call `~/.colab/bin/colab`.** The symlinked CLI follows
199
- whatever branch this clone has checked out — deliberate for a human session, and
200
- wrong for anything that outlives one. A daemon, a launch agent or a headless
201
- runner started months ago would silently change behaviour because somebody
202
- checked out an unrelated branch, and nothing would report it: the process keeps
203
- working, differently. So `--tools` also writes a **copy** to `~/.colab/bin/`
204
- (honouring `COLAB_HOME`), stamped with the handbook version it was taken from —
205
- or, when that tree sits ahead of the last tag, with the commit it was taken from
206
- (`v1.7.0-2-gc8436c6`) and a warning, because no released version describes those
207
- bytes. That copy never moves on its own.
208
-
209
- Refreshing it is therefore an act, never a side effect: re-run `./install.sh
210
- --tools`. `colab update` tells you when it is due. **`behind` means a released
211
- CLI change exists that this machine lacks** — the comparison runs to the latest
212
- tag, so a release that changed no CLI code does not nag you, and unreleased work
213
- in your own checkout does not either. (That last part is why the bound is the tag
214
- rather than `HEAD`: measuring to `HEAD` marked every machine stale for the whole
215
- window between a CLI commit and the next tag, and the advertised remedy copies
216
- *from* that same working tree — so on a machine developing the handbook it
217
- advised services to adopt untagged code.) It never rewrites the copy, not even
218
- with `--apply`: that is the toolchain your running services are executing.
219
- `colab --version` says which of the two you are talking to (or `npm package` for an
220
- `npx`/`npm i` install), and prints that install's version. The frozen copy carries
221
- `tools/` only, so `colab template` refuses there — run it from the working tree.
222
-
223
- **3. Verify, and register your repos.**
224
-
225
- ```sh
226
- colab --help # not found? fix your PATH — step 2 prints the exact line
227
- colab --version # which colab is this — working tree, frozen copy, or npm package — and its version
228
- colab register /path/to/repo # once per repo — writes repos.txt AND config.json, so they agree
229
- node audit/audit.mjs # a conformance report across the whole fleet
230
- colab update # stamped copies that fell behind — the frozen CLI included
231
- ```
232
-
233
- `colab register` is the way in; hand-editing `~/.colab/repos.txt` still works for
234
- the audit, but leaves `config.json` — where the CLI reserves each repo's ports —
235
- unaware of the repo. A remote-only audit target (`owner/name`, nothing cloned) is
236
- the one entry you add to `repos.txt` by hand. A repo not yet adopted then needs
237
- `colab adopt` and `colab labels --ensure` — see *Adopting it into a repo* below.
273
+ | `--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). |
274
+ | `--release` | Check this clone out at the newest final release tag, then install. The default for a first install from a fresh clone. |
275
+ | `--trunk` | Check out `main` and install it, unreleased work included — the clone's `@next`. |
276
+ | `--dry` | Print what would happen, change nothing. Combines with the flags above. |
277
+ | `--check` | **Read-only** health report on an earlier install — see below. Takes no other flag; exit 1 on any ✗ row. |
278
+
279
+ **Always-on services (launch agents, daemons, headless runners) must call
280
+ `~/.colab/bin/colab`, not the symlink**, because the symlink follows whatever
281
+ branch this clone has checked out. The frozen copy never moves on its own:
282
+ `colab update` says when it is behind a released CLI change, and re-running
283
+ `./install.sh --tools` refreshes it. Why it works this way:
284
+ [`tools/README.md`](tools/README.md#install).
285
+
286
+ **The CLI alone, without the skills,** is on npm as
287
+ **`@futurelastic/colab-handbook`**. No final release has been published to npm
288
+ yet, so the default `latest` tag holds only a placeholder; install from
289
+ **`@next`**, the release candidates: `npx @futurelastic/colab-handbook@next
290
+ <command>`, or `npm i -g @futurelastic/colab-handbook@next`. The command is
291
+ still `colab`. The skills are not in the package; they install from a
292
+ clone, because they must symlink into `~/.claude/skills/`.
238
293
 
239
294
  ### Checking an install
240
295
 
241
296
  ```sh
242
- ./install.sh --check # read-only; exit 1 on any ✗ row
297
+ colab --version # which colab answered — working tree, frozen copy or npm package — and its version
298
+ ./install.sh --check # read-only; exit 1 on any ✗ row
299
+ node audit/audit.mjs # a conformance report across every registered repo
300
+ colab update # stamped copies that fell behind, the frozen CLI included
243
301
  ```
244
302
 
245
- A frozen copy never breaks — it gets **old**, and an old complete copy answers
246
- normally for every command it knows until something asks for one added after it
247
- was frozen. `--check` is the report nothing else gives: whether the frozen copy is
248
- behind the latest release, **which commands it does not dispatch**, whether the
249
- state file exists, whether anything is registered, and whether both pre-commit
250
- hooklets can actually run (gitleaks, and the identity vocabulary). ✗ means
251
- something installed here is stale or unusable; ⚠ means something was never set
252
- up, which may be deliberate. It never refreshes anything — re-freezing stays your
253
- call: `./install.sh --tools`.
303
+ `--check` reports whether the frozen copy is behind the latest release and
304
+ which commands it does not dispatch, whether the state file exists, whether
305
+ anything is registered, whether both pre-commit hooklets can run, and whether
306
+ `notifyUrl` is unset while a local observer declared an endpoint. ✗ means
307
+ something installed is stale or unusable; ⚠ means something was never set up,
308
+ which may be deliberate or just not done yet — so a correct fresh install, with
309
+ no repo registered and no identity vocabulary, reports ⚠ rows and exits 0. It
310
+ never refreshes anything. `--check` is not in v1.11.0 or earlier; on such a
311
+ release, follow `main` to get it.
254
312
 
255
- Then read [`CONVENTIONS.md`](CONVENTIONS.md): ~15 minutes, and the only
256
- normative file here.
257
-
258
- ## Adopting it into a repo
259
-
260
- The short version — the full checklist is
261
- [`CONVENTIONS.md` §9](CONVENTIONS.md#9-adopting-this):
262
-
263
- 1. Answer question 1 honestly (is there production **today**, not "soon").
264
- 2. Add `.github/project.yml`. `colab adopt` asks the five questions and writes
265
- the file for you — it stops at the descriptor and prints the rest of this
266
- list, because the remaining steps are not its to take.
267
- 3. `colab labels --ensure` — the convention labels do not exist by default, and
268
- there are more than one. A check whose label was never created can never
269
- fire.
270
- 4. Paste [`templates/repo-CLAUDE-block.md`](templates/repo-CLAUDE-block.md)
271
- into the repo's `CLAUDE.md` — this is the only way agents discover these
272
- conventions.
273
- 5. Make sure CI produces the two required outcomes: a secret scan and a build,
274
- with toolchain versions **resolved from the repo's own manifest** — never
275
- hardcoded. Copy a template if it helps.
313
+ ## Why so little enforcement
276
314
 
277
- Pre-existing branches are **grandfathered**. Do not rename anything.
315
+ Branch protection is not available on every plan and every owner a fleet spans,
316
+ so this handbook does not rely on it. It makes **compliance cheap and checking
317
+ cheap** instead: the audit reports drift, and the conventions explain *why*
318
+ each rule exists, so you can judge when breaking one is worth it. When you do,
319
+ fix the documentation in the same change — a document describing a repo that
320
+ does not exist is the worst thing in this business.
278
321
 
279
- **Working in a repo you don't own?** If committing these files there is not an option,
280
- `colab adopt --local` keeps everything in your local clone instead, and nothing lands in
281
- the owner's history — see
282
- [*Working in a repo you don't own*](CONVENTIONS.md#working-in-a-repo-you-dont-own).
322
+ **A short list does block, deliberately:**
283
323
 
284
- ## Why so little enforcement
324
+ - **Publication.** The git hooks refuse a secret, and an identity scan stops a
325
+ hostname, a home path or a customer's name reaching a public repo. History
326
+ cannot be recalled once anything is cloned.
327
+ - **The gates around a merge**, enforced by `colab`: a human go before a merge
328
+ (unless the repo granted `auto-trunk` or the change is docs-only), a grant
329
+ before a migration ships, and a release never bundled into a merge.
285
330
 
286
- Our private repos sit on a GitHub plan without branch protection — pushes to
287
- `main` cannot be forbidden. So this handbook does not pretend to enforce; it
288
- makes **compliance cheap and checking cheap**. The audit tool reports drift; the
289
- conventions explain *why* each rule exists, so you can judge for yourself when
290
- breaking one is worth it. When you do break one, fix the documentation in the
291
- same PR — a document describing a repo that does not exist is the worst thing in
292
- this business.
293
-
294
- **Two things do block, and the line between them is deliberate.** The git hooks
295
- refuse: a secret scan, and an identity scan that stops a hostname, a home path
296
- or a customer's name reaching a public repo. Those guard **publication**, which
297
- is the one mistake that cannot be undone — history cannot be recalled once
298
- anything is cloned. Everything about *conformance* stays advisory, because being
299
- wrong about a convention costs a conversation, and being wrong about publication
300
- costs forever.
331
+ Everything else is a default — one good way to do it — because being wrong
332
+ about a convention costs a conversation.
301
333
 
302
334
  ## License
303
335