@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.
- package/README.md +244 -212
- package/README.vi.md +246 -185
- package/audit/audit.mjs +197 -12
- package/package.json +6 -1
- package/templates/README.md +49 -2
- package/templates/ci-laravel.yml +181 -18
- package/templates/ci-node.yml +137 -0
- package/templates/ci-python.yml +128 -0
- package/templates/deploy-adapter-portainer.mjs +206 -0
- package/templates/deploy-container-run.mjs +368 -0
- package/templates/deploy-container.yml +219 -0
- package/templates/dist-refs.yml +6 -0
- package/templates/docs-lint.mjs +1 -1
- package/templates/npx-launcher.mjs +118 -20
- package/templates/npx-service.mjs +828 -0
- package/templates/release-auto.yml +364 -35
- package/tools/colab +1791 -266
- package/tools/lib/adopt.js +373 -14
- package/tools/lib/branch-name.js +29 -1
- package/tools/lib/ci-cure.js +522 -31
- package/tools/lib/ci-grant.js +289 -22
- package/tools/lib/ci-wait.js +203 -0
- package/tools/lib/claim-comments.js +13 -64
- package/tools/lib/claim-identity.js +4 -7
- package/tools/lib/codec/claim.d.ts +41 -0
- package/tools/lib/codec/claim.js +151 -0
- package/tools/lib/codec/decision.d.ts +29 -0
- package/tools/lib/codec/decision.js +81 -0
- package/tools/lib/codec/grants.d.ts +82 -0
- package/tools/lib/codec/grants.js +268 -0
- package/tools/lib/codec/hold.d.ts +26 -0
- package/tools/lib/codec/hold.js +152 -0
- package/tools/lib/codec/index.d.ts +21 -0
- package/tools/lib/codec/index.js +32 -0
- package/tools/lib/codec/labels.d.ts +65 -0
- package/tools/lib/codec/labels.js +716 -0
- package/tools/lib/codec/markers.d.ts +35 -0
- package/tools/lib/codec/markers.js +138 -0
- package/tools/lib/codec/release.d.ts +17 -0
- package/tools/lib/codec/release.js +69 -0
- package/tools/lib/codec/samples.json +762 -0
- package/tools/lib/codeowners.js +68 -4
- package/tools/lib/conflict-markers.js +47 -0
- package/tools/lib/container-close.js +38 -0
- package/tools/lib/cure-diff.js +198 -9
- package/tools/lib/decision-record.js +15 -39
- package/tools/lib/docs-only.js +15 -1
- package/tools/lib/exposure-shape.js +42 -8
- package/tools/lib/git.js +303 -42
- package/tools/lib/group-labels.js +65 -0
- package/tools/lib/hermetic.js +72 -6
- package/tools/lib/install-check.js +34 -9
- package/tools/lib/install-route.js +139 -0
- package/tools/lib/instruction-file.js +1 -0
- package/tools/lib/labels.js +22 -647
- package/tools/lib/local-adopt.js +8 -4
- package/tools/lib/migration-grant.js +206 -104
- package/tools/lib/notify-endpoint.js +170 -0
- package/tools/lib/place.js +2 -2
- package/tools/lib/release-cut.js +199 -25
- package/tools/lib/release-finalize.js +160 -32
- package/tools/lib/release-policy.js +130 -22
- package/tools/lib/release-runner.js +125 -0
- package/tools/lib/release-tag.js +3 -1
- package/tools/lib/scratch-dirs.js +106 -0
- package/tools/lib/ship-batch.js +46 -1
- package/tools/lib/stamp.js +7 -0
- package/tools/lib/tracker-fake.js +195 -0
- package/tools/lib/tracker-github.js +106 -0
- package/tools/lib/tracker-scenarios.json +206 -0
- package/tools/lib/tracker.js +64 -0
- package/tools/lib/tree-green.js +88 -0
- package/tools/lib/util.js +17 -1
- package/tools/lib/verify-runs.js +104 -0
- package/tools/lib/wake.js +8 -90
- 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
|
-
|
|
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, 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
|
-
|
|
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
|
|
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
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
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
|
|
64
|
-
|
|
65
|
-
|
|
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
|
-
- **
|
|
77
|
-
|
|
78
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
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`).
|
|
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
|
|
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
|
-
**
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
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
|
-
|
|
156
|
-
|
|
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
|
-
|
|
159
|
-
|
|
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` |
|
|
187
|
-
| `--hooks` | Point this clone's git at `.githooks
|
|
188
|
-
| `--fleet` | Seed `~/.colab/repos.txt`
|
|
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
|
-
| `--
|
|
191
|
-
| `--
|
|
192
|
-
|
|
193
|
-
`--
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
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
|
-
|
|
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
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
**
|
|
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
|
-
|
|
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
|
-
|
|
287
|
-
|
|
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
|
|