@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 +200 -216
- package/README.vi.md +203 -188
- package/package.json +1 -1
- package/tools/colab +89 -6
- package/tools/lib/ci-cure.js +192 -41
- package/tools/lib/ci-wait.js +2 -0
- package/tools/lib/git.js +5 -2
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
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
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
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
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
|
-
- **
|
|
77
|
-
|
|
78
|
-
|
|
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
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
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.
|
|
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.
|
|
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
|
|
129
|
-
| [`skills/`](skills/) |
|
|
130
|
-
| [`install.sh`](install.sh) | Sets up **your machine**: skills, the `colab` CLI, the pre-commit hook, the fleet list. Idempotent
|
|
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
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
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` |
|
|
187
|
-
| `--hooks` | Point this clone's git at `.githooks
|
|
188
|
-
| `--fleet` | Seed `~/.colab/repos.txt`
|
|
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
|
|
191
|
-
| `--dry` | Print what would happen, change nothing. Combines with
|
|
192
|
-
| `--check` | **Read-only** health report on
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
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
|
-
|
|
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
|
-
|
|
247
|
-
|
|
248
|
-
|
|
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
|
|
254
|
-
|
|
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
|
-
##
|
|
267
|
+
## Why so little enforcement
|
|
261
268
|
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
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
|
-
|
|
276
|
+
**A short list does block, deliberately:**
|
|
280
277
|
|
|
281
|
-
**
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
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
|
-
|
|
289
|
-
|
|
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
|
|