@futurelastic/colab-handbook 1.16.0-rc.2 → 1.16.0-rc.21
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 +20 -18
- package/README.vi.md +22 -20
- package/package.json +1 -1
- package/templates/README.md +38 -4
- package/templates/publish-downloads.mjs +659 -0
- package/templates/publish-downloads.yml +184 -0
- package/tools/colab +66 -20
- package/tools/lib/ci-verdict.js +98 -7
- package/tools/lib/git.js +68 -12
- package/tools/lib/install-check.js +1 -1
- package/tools/lib/ship-handoff.js +34 -5
package/README.md
CHANGED
|
@@ -21,7 +21,7 @@ colab register # adds the repo to this machine's fleet list
|
|
|
21
21
|
```
|
|
22
22
|
|
|
23
23
|
Then, in an agent session in that repo, run the `code-start` skill with an issue
|
|
24
|
-
number — each
|
|
24
|
+
number — each agent runtime has its own way to invoke a skill, see [*Choose your agent runtime*](#choose-your-agent-runtime).
|
|
25
25
|
With an agent at hand, the `handbook-sync` skill replaces the last three commands and also does
|
|
26
26
|
the rest of adoption (see [*Adopting it into a repo*](#adopting-it-into-a-repo)).
|
|
27
27
|
You need `git`, `node` ≥ 18 and `gh` ≥ 2.94 logged in (`gh auth login`); distro
|
|
@@ -115,7 +115,7 @@ with a pointer to [#604](https://github.com/futurelastic/colab-handbook/issues/6
|
|
|
115
115
|
## Your first session
|
|
116
116
|
|
|
117
117
|
A unit of work goes round one loop. Each step is a skill, invoked by name in an
|
|
118
|
-
agent session (the syntax is the
|
|
118
|
+
agent session (the syntax is the agent runtime's — [*Choose your agent runtime*](#choose-your-agent-runtime)),
|
|
119
119
|
or followed by hand from [`skills/`](skills/).
|
|
120
120
|
|
|
121
121
|
| Step | Skill | Who runs it | What it leaves behind |
|
|
@@ -153,7 +153,7 @@ shell its own `COLAB_SESSION=<any stable id>` so their holds stay apart.
|
|
|
153
153
|
full plan from `code-plan`.
|
|
154
154
|
|
|
155
155
|
Newcomers: read [`CONVENTIONS.md` §1](CONVENTIONS.md#1-the-model-in-one-picture)
|
|
156
|
-
(the model) and [
|
|
156
|
+
(the model) and the [quick reference](tools/docs/quick-reference.md)
|
|
157
157
|
first. The rest of `CONVENTIONS.md` is reference — look things up, do not read
|
|
158
158
|
it end to end.
|
|
159
159
|
|
|
@@ -193,7 +193,8 @@ brings an adopted repo up to the current handbook without losing your local
|
|
|
193
193
|
edits.
|
|
194
194
|
|
|
195
195
|
By hand, the same steps (full checklist:
|
|
196
|
-
[`
|
|
196
|
+
[`skills/handbook-sync/2-adoption-procedure.md`](skills/handbook-sync/2-adoption-procedure.md);
|
|
197
|
+
the rules it serves: [`CONVENTIONS.md` §9](CONVENTIONS.md#9-adopting-this)):
|
|
197
198
|
|
|
198
199
|
1. `colab adopt` — answers the two gating questions and writes
|
|
199
200
|
`.github/project.yml`. It stops there and prints the remaining steps.
|
|
@@ -235,9 +236,9 @@ the step you are refining by its number (`code-ship` B1c, `code-sweep` §3): a
|
|
|
235
236
|
large skill is a short core plus reference files, and the core keeps every
|
|
236
237
|
step's number.
|
|
237
238
|
|
|
238
|
-
Claude Code loads the file into the skill automatically. Other
|
|
239
|
+
Claude Code loads the file into the skill automatically. Other agent runtimes get a
|
|
239
240
|
plain sentence in each skill telling the agent to read the file, which works
|
|
240
|
-
without any
|
|
241
|
+
without any runtime support. Because the file instructs agents, a change to it
|
|
241
242
|
is never treated as docs-only: it merges on `auto-trunk` or a human's go, like a
|
|
242
243
|
`CLAUDE.md` change. Rule:
|
|
243
244
|
[`CONVENTIONS.md` §8, *Local policy*](CONVENTIONS.md#local-policy--a-repo-refines-a-skill-without-forking-it-520).
|
|
@@ -261,11 +262,12 @@ migration hold with or without it.
|
|
|
261
262
|
| [`CONVENTIONS.md`](CONVENTIONS.md) | The rules. Normative, the single source of truth (EN). |
|
|
262
263
|
| [`AGENTS.md`](AGENTS.md) | The entry point for AI agents — the operational distillation (EN). |
|
|
263
264
|
| [`project.schema.md`](project.schema.md) | Field reference for `.github/project.yml`. |
|
|
264
|
-
| [`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.
|
|
265
|
+
| [`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. Optional — the handbook ships no enforcement; each file's home is the tool that runs it ([`templates/README.md`](templates/README.md#where-each-file-lives--the-handbook-ships-no-enforcement-643)). Copy it, edit it, own it; one caller, `instruction-files.yml`, is kept for compatibility. |
|
|
265
266
|
| [`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). |
|
|
266
|
-
| [`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. `--batch-history` shows each repo's measured batch landing picture, flagged only against thresholds the repo declares. What each check means: [`audit/README.md`](audit/README.md). |
|
|
267
|
+
| [`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. `--batch-history` shows each repo's measured batch landing picture, flagged only against thresholds the repo declares. The text checks stay here; the multi-repo sweep is adopter tooling and leaves once its replacement ships. What each check means: [`audit/README.md`](audit/README.md). |
|
|
267
268
|
| [`skills/`](skills/) | The session flow — see [*Your first session*](#your-first-session). Plain `SKILL.md` folders; `install.sh` links them into each coding agent you choose. |
|
|
268
|
-
| [`
|
|
269
|
+
| [`guides/`](guides/) | The role guides — author, reviewer, coordinator, cure, by hand — each written as the files that role leaves for the next. The judgement only; the skills keep their names and point to their guide. |
|
|
270
|
+
| [`engines/`](engines/) | One small data file per agent runtime: where its user-level skills go, how a skill is invoked, what it supports. Adding an agent runtime is adding a file — [`engines/README.md`](engines/README.md). |
|
|
269
271
|
| [`install.sh`](install.sh) | Sets up **your machine**: skills, the `colab` CLI, the pre-commit hook, the fleet list. Idempotent; `--dry` shows everything first. |
|
|
270
272
|
|
|
271
273
|
## Setting up a machine
|
|
@@ -289,12 +291,12 @@ Later moves are explicit:
|
|
|
289
291
|
A clone with uncommitted changes is never moved, and a re-run without either
|
|
290
292
|
flag keeps whatever is checked out.
|
|
291
293
|
|
|
292
|
-
### Choose your
|
|
294
|
+
### Choose your agent runtime
|
|
293
295
|
|
|
294
296
|
The skills are plain `SKILL.md` folders that call `git`, `gh` and `colab`; any
|
|
295
297
|
coding agent that reads skills can run them. What differs is **where each
|
|
296
298
|
agent looks for them**, so the install asks. At a terminal, `./install.sh`
|
|
297
|
-
lists the
|
|
299
|
+
lists the agent runtimes it knows and lets you pick one or more, with *other: give a
|
|
298
300
|
path* last. Unattended, say it with a flag:
|
|
299
301
|
|
|
300
302
|
```sh
|
|
@@ -303,21 +305,21 @@ path* last. Unattended, say it with a flag:
|
|
|
303
305
|
./install.sh --skills-dir ~/my-agent/skills # any other agent: you give its folder
|
|
304
306
|
```
|
|
305
307
|
|
|
306
|
-
|
|
|
308
|
+
| Agent runtime | Skills folder | Invoke | Before the skills work there |
|
|
307
309
|
|---|---|---|---|
|
|
308
310
|
| Claude Code (`claude`) | `~/.claude/skills` | `/code-start` | Nothing. This user-level install **wins** over a repo's own `.claude/skills/<name>` of the same name (precedence is enterprise > personal > project), so rename a repo variant you want used. |
|
|
309
311
|
| OpenAI Codex (`codex`) | `~/.agents/skills` | `$code-start` | Its default sandbox has no network, so `gh` fails: set `[sandbox_workspace_write] network_access = true` in `~/.codex/config.toml`. Values from Codex's docs; not yet verified by a clean-machine run. |
|
|
310
312
|
| anything else | `--skills-dir <path>` | the agent's own way | The agent's shell needs network access for `gh`. The folder is remembered in `~/.colab/skills-dirs`. |
|
|
311
313
|
|
|
312
|
-
A re-run with no flag and no terminal keeps every
|
|
314
|
+
A re-run with no flag and no terminal keeps every agent runtime it finds already
|
|
313
315
|
linked, so an existing machine changes nothing. Finding none, it installs for
|
|
314
|
-
Claude Code and says so. The per-
|
|
316
|
+
Claude Code and says so. The per-runtime facts live in [`engines/`](engines/),
|
|
315
317
|
one file each — that folder is the source for the table above.
|
|
316
318
|
|
|
317
319
|
| Flag | What it does |
|
|
318
320
|
|---|---|
|
|
319
|
-
| *(none)* | Symlink `skills/` into each chosen
|
|
320
|
-
| `--engine <id>[,<id>]` | Install for these
|
|
321
|
+
| *(none)* | Symlink `skills/` into each chosen agent runtime's user-level folder, so they are available in every repo you open. Asks at a terminal; otherwise keeps what is linked (see [*Choose your agent runtime*](#choose-your-agent-runtime)). |
|
|
322
|
+
| `--engine <id>[,<id>]` | Install for these agent runtimes (`claude`, `codex` — the files in `engines/`), no question asked. |
|
|
321
323
|
| `--skills-dir <path>` | Also install into this folder, for an agent `engines/` does not know. |
|
|
322
324
|
| `--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. |
|
|
323
325
|
| `--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)). |
|
|
@@ -353,8 +355,8 @@ node audit/audit.mjs # a conformance report across every registered repo
|
|
|
353
355
|
colab update # stamped copies that fell behind, the frozen CLI included
|
|
354
356
|
```
|
|
355
357
|
|
|
356
|
-
`--check` reports, per
|
|
357
|
-
plus that
|
|
358
|
+
`--check` reports, per agent runtime, how many skills are linked, missing or broken,
|
|
359
|
+
plus that runtime's own caveats (Codex's sandbox network, for instance). It also reports whether the frozen copy is behind the latest release and
|
|
358
360
|
which commands it does not dispatch, whether the state file exists, whether
|
|
359
361
|
anything is registered, whether both pre-commit hooklets can run, and whether
|
|
360
362
|
`notifyUrl` is unset, or lacks a URL, while a local observer declared one. ✗ means
|
package/README.vi.md
CHANGED
|
@@ -20,7 +20,7 @@ colab register # đưa repo vào danh sách fleet của máy này
|
|
|
20
20
|
```
|
|
21
21
|
|
|
22
22
|
Sau đó, trong một phiên agent ở repo đó, chạy skill `code-start` kèm số issue —
|
|
23
|
-
mỗi
|
|
23
|
+
mỗi agent runtime có cách gọi skill riêng, xem [*Chọn agent runtime*](#chọn-agent-runtime). Có agent
|
|
24
24
|
trong tay thì skill `handbook-sync` thay được ba lệnh cuối và làm nốt phần adopt còn
|
|
25
25
|
lại (xem [*Adopt vào một repo*](#adopt-vào-một-repo)). Cần có `git`, `node` ≥ 18
|
|
26
26
|
và `gh` ≥ 2.94 đã đăng nhập (`gh auth login`); gói `gh` của các distro thường cũ
|
|
@@ -114,7 +114,7 @@ production đủ 7 ngày. Thông báo nằm ở đầu
|
|
|
114
114
|
## Phiên làm việc đầu tiên
|
|
115
115
|
|
|
116
116
|
Mỗi đầu việc đi qua một vòng. Mỗi bước là một skill, gọi theo tên trong phiên
|
|
117
|
-
agent (cú pháp gọi là của
|
|
117
|
+
agent (cú pháp gọi là của agent runtime — [*Chọn agent runtime*](#chọn-agent-runtime)), hoặc tự làm
|
|
118
118
|
theo bằng tay từ [`skills/`](skills/).
|
|
119
119
|
|
|
120
120
|
| Bước | Skill | Ai chạy | Để lại gì |
|
|
@@ -153,7 +153,7 @@ vào nhau.
|
|
|
153
153
|
dòng, 2 plan đầy đủ từ `code-plan`.
|
|
154
154
|
|
|
155
155
|
Người mới: đọc [`CONVENTIONS.md` §1](CONVENTIONS.md#1-the-model-in-one-picture)
|
|
156
|
-
(mô hình) và [
|
|
156
|
+
(mô hình) và [bảng tra nhanh](tools/docs/quick-reference.md) trước. Phần
|
|
157
157
|
còn lại của `CONVENTIONS.md` là tài liệu tra cứu — cần gì tra nấy, đừng đọc từ
|
|
158
158
|
đầu tới cuối.
|
|
159
159
|
|
|
@@ -192,7 +192,8 @@ này. Chạy lại về sau, chính skill đó kéo một repo đã adopt lên b
|
|
|
192
192
|
nhất mà không làm mất phần bạn đã sửa.
|
|
193
193
|
|
|
194
194
|
Làm bằng tay thì cũng đúng các bước đó (checklist đầy đủ:
|
|
195
|
-
[`
|
|
195
|
+
[`skills/handbook-sync/2-adoption-procedure.md`](skills/handbook-sync/2-adoption-procedure.md);
|
|
196
|
+
các quy tắc nó phục vụ: [`CONVENTIONS.md` §9](CONVENTIONS.md#9-adopting-this)):
|
|
196
197
|
|
|
197
198
|
1. `colab adopt` — trả lời hai câu hỏi về cổng và ghi `.github/project.yml`. Nó dừng ở
|
|
198
199
|
đó và in ra các bước còn lại.
|
|
@@ -234,8 +235,8 @@ chối thì vẫn bị từ chối. Hãy gọi bước bạn muốn chỉnh theo
|
|
|
234
235
|
B1c, `code-sweep` §3): một skill lớn gồm một phần lõi ngắn cộng các file tham
|
|
235
236
|
chiếu, và phần lõi giữ số của mọi bước.
|
|
236
237
|
|
|
237
|
-
Claude Code tự nạp file vào skill. Các
|
|
238
|
-
skill bảo agent đọc file, cách này chạy được mà không cần
|
|
238
|
+
Claude Code tự nạp file vào skill. Các agent runtime khác có một câu thường trong mỗi
|
|
239
|
+
skill bảo agent đọc file, cách này chạy được mà không cần runtime hỗ trợ gì.
|
|
239
240
|
Vì file này ra lệnh cho agent, thay đổi trong nó không bao giờ được coi là
|
|
240
241
|
docs-only: nó merge bằng `auto-trunk` hoặc khi có người duyệt, giống một thay đổi
|
|
241
242
|
`CLAUDE.md`. Quy tắc:
|
|
@@ -260,11 +261,12 @@ quyền cấp trước khi chạy migration vẫn đứng vững dù có nó hay
|
|
|
260
261
|
| [`CONVENTIONS.md`](CONVENTIONS.md) | Luật. Chuẩn tắc, nguồn sự thật duy nhất (EN). |
|
|
261
262
|
| [`AGENTS.md`](AGENTS.md) | Cửa vào cho AI agent — bản chưng cất vận hành (EN). |
|
|
262
263
|
| [`project.schema.md`](project.schema.md) | Tham chiếu field của `.github/project.yml`. |
|
|
263
|
-
| [`templates/`](templates/) | Điểm khởi đầu **copy-về-là-của-bạn**: CI, release, git hook (một bản quét secret và một bản quét danh tính), và block `CLAUDE.md` cho repo adopt.
|
|
264
|
+
| [`templates/`](templates/) | Điểm khởi đầu **copy-về-là-của-bạn**: CI, release, git hook (một bản quét secret và một bản quét danh tính), và block `CLAUDE.md` cho repo adopt. Tuỳ chọn — handbook không kèm cơ chế cưỡng chế nào; nhà của mỗi file là công cụ chạy nó ([`templates/README.md`](templates/README.md#where-each-file-lives--the-handbook-ships-no-enforcement-643)). Copy, sửa, sở hữu; riêng một caller, `instruction-files.yml`, được giữ để tương thích. |
|
|
264
265
|
| [`tools/`](tools/) | `colab` — một CLI nhỏ (tùy chọn): adopt một repo, claim issue, cấp port, quản lý worktree, và merge nhánh đã xong vào trunk khi repo cho phép. State JSON, không dependency. Tham chiếu các lệnh: [`tools/README.md`](tools/README.md). |
|
|
265
|
-
| [`audit/`](audit/) | Trình kiểm tra conformance từ bên ngoài. Đọc mọi repo của bạn — mọi owner, kể cả repo local-only — và báo drift trong một lần chạy. Chỉ cảnh báo. Thêm `--identity` thì quét cả description và topic của repo public — thứ mà không git hook nào nhìn thấy được. Thêm `--batch-history` thì hiện số liệu batch landing đo được của từng repo, chỉ cảnh báo theo ngưỡng repo tự khai báo. Ý nghĩa từng check: [`audit/README.md`](audit/README.md). |
|
|
266
|
+
| [`audit/`](audit/) | Trình kiểm tra conformance từ bên ngoài. Đọc mọi repo của bạn — mọi owner, kể cả repo local-only — và báo drift trong một lần chạy. Chỉ cảnh báo. Thêm `--identity` thì quét cả description và topic của repo public — thứ mà không git hook nào nhìn thấy được. Thêm `--batch-history` thì hiện số liệu batch landing đo được của từng repo, chỉ cảnh báo theo ngưỡng repo tự khai báo. Các check văn bản ở lại đây; phần quét nhiều repo là công cụ của bên adopt và sẽ rời đi khi bản thay thế ra mắt. Ý nghĩa từng check: [`audit/README.md`](audit/README.md). |
|
|
266
267
|
| [`skills/`](skills/) | Luồng phiên làm việc — xem [*Phiên làm việc đầu tiên*](#phiên-làm-việc-đầu-tiên). Là các thư mục `SKILL.md` thuần; `install.sh` link chúng vào từng coding agent bạn chọn. |
|
|
267
|
-
| [`
|
|
268
|
+
| [`guides/`](guides/) | Các hướng dẫn theo vai trò — author, reviewer, coordinator, cure, by hand — mỗi bản viết dưới dạng các file vai trò đó để lại cho bước sau. Chỉ phần phán đoán; các skill giữ nguyên tên và trỏ tới hướng dẫn của mình. |
|
|
269
|
+
| [`engines/`](engines/) | Mỗi agent runtime một file dữ liệu nhỏ: skill cấp user đặt ở đâu, gọi skill thế nào, agent hỗ trợ gì. Thêm agent runtime là thêm một file — [`engines/README.md`](engines/README.md). |
|
|
268
270
|
| [`install.sh`](install.sh) | Cài đặt cho **máy của bạn**: skills, CLI `colab`, hook pre-commit, danh sách fleet. Idempotent; `--dry` cho xem trước mọi thứ. |
|
|
269
271
|
|
|
270
272
|
## Cài đặt máy
|
|
@@ -288,12 +290,12 @@ sau đều phải chủ động:
|
|
|
288
290
|
Clone đang có thay đổi chưa commit thì không bao giờ bị chuyển, và chạy lại
|
|
289
291
|
không kèm flag nào thì giữ nguyên thứ đang checkout.
|
|
290
292
|
|
|
291
|
-
### Chọn
|
|
293
|
+
### Chọn agent runtime
|
|
292
294
|
|
|
293
295
|
Các skill là thư mục `SKILL.md` thuần, chỉ gọi `git`, `gh` và `colab`; coding
|
|
294
296
|
agent nào đọc được skill thì chạy được chúng. Khác nhau là **mỗi agent tìm
|
|
295
297
|
skill ở đâu**, nên bản cài sẽ hỏi. Ở terminal, `./install.sh` liệt kê các
|
|
296
|
-
|
|
298
|
+
agent runtime nó biết và cho bạn chọn một hoặc nhiều, lựa chọn cuối là *other: give a
|
|
297
299
|
path*. Chạy không người trông thì nói bằng flag:
|
|
298
300
|
|
|
299
301
|
```sh
|
|
@@ -302,21 +304,21 @@ path*. Chạy không người trông thì nói bằng flag:
|
|
|
302
304
|
./install.sh --skills-dir ~/my-agent/skills # agent khác: bạn đưa thư mục của nó
|
|
303
305
|
```
|
|
304
306
|
|
|
305
|
-
|
|
|
307
|
+
| Agent runtime | Thư mục skill | Gọi | Cần làm gì để skill chạy được |
|
|
306
308
|
|---|---|---|---|
|
|
307
309
|
| Claude Code (`claude`) | `~/.claude/skills` | `/code-start` | Không cần gì. Bản cài cấp user này **thắng** `.claude/skills/<name>` cùng tên của repo (thứ tự ưu tiên là enterprise > personal > project), nên muốn dùng bản của repo thì đổi tên nó. |
|
|
308
310
|
| OpenAI Codex (`codex`) | `~/.agents/skills` | `$code-start` | Sandbox mặc định không có mạng nên `gh` lỗi: đặt `[sandbox_workspace_write] network_access = true` trong `~/.codex/config.toml`. Số liệu lấy từ tài liệu của Codex; chưa được xác minh bằng một lần chạy trên máy sạch. |
|
|
309
311
|
| agent khác | `--skills-dir <path>` | theo cách của agent | Shell của agent cần có mạng cho `gh`. Thư mục được ghi nhớ trong `~/.colab/skills-dirs`. |
|
|
310
312
|
|
|
311
|
-
Chạy lại không flag và không có terminal thì giữ mọi
|
|
312
|
-
sẵn, nên máy đã cài không thay đổi gì. Không thấy
|
|
313
|
-
Code và nói rõ điều đó. Thông tin từng
|
|
314
|
-
mỗi
|
|
313
|
+
Chạy lại không flag và không có terminal thì giữ mọi agent runtime đã thấy được link
|
|
314
|
+
sẵn, nên máy đã cài không thay đổi gì. Không thấy agent runtime nào thì cài cho Claude
|
|
315
|
+
Code và nói rõ điều đó. Thông tin từng agent runtime nằm trong [`engines/`](engines/),
|
|
316
|
+
mỗi agent runtime một file — thư mục đó là nguồn của bảng trên.
|
|
315
317
|
|
|
316
318
|
| Flag | Làm gì |
|
|
317
319
|
|---|---|
|
|
318
|
-
| *(không có)* | Symlink `skills/` vào thư mục cấp user của từng
|
|
319
|
-
| `--engine <id>[,<id>]` | Cài cho các
|
|
320
|
+
| *(không có)* | Symlink `skills/` vào thư mục cấp user của từng agent runtime đã chọn, để mở repo nào cũng có. Ở terminal thì hỏi; không thì giữ những gì đã link (xem [*Chọn agent runtime*](#chọn-agent-runtime)). |
|
|
321
|
+
| `--engine <id>[,<id>]` | Cài cho các agent runtime này (`claude`, `codex` — các file trong `engines/`), không hỏi. |
|
|
320
322
|
| `--skills-dir <path>` | Cài thêm vào thư mục này, cho agent mà `engines/` chưa biết. |
|
|
321
323
|
| `--tools` | CLI `colab` cài hai lần: một **symlink** ở `~/.local/bin/colab` cho các phiên làm việc của bạn (in sẵn dòng `PATH` nếu cần), và một **bản đóng băng** có đóng dấu ở `~/.colab/bin/colab` cho các service luôn-bật. Đồng thời tạo `~/.colab/state.json` rỗng nếu chưa có. |
|
|
322
324
|
| `--hooks` | Trỏ git của clone này vào `.githooks/`: quét secret bằng gitleaks, và quét danh tính với danh sách từ khoá do bạn giữ NGOÀI mọi repo (xem [`templates/README.md`](templates/README.md)). |
|
|
@@ -351,8 +353,8 @@ node audit/audit.mjs # báo cáo conformance cho mọi repo đã đăng ký
|
|
|
351
353
|
colab update # các bản copy có đóng dấu đã tụt lại, kể cả CLI đóng băng
|
|
352
354
|
```
|
|
353
355
|
|
|
354
|
-
`--check` báo theo từng
|
|
355
|
-
các lưu ý riêng của
|
|
356
|
+
`--check` báo theo từng agent runtime: bao nhiêu skill đã link, thiếu hay hỏng, kèm
|
|
357
|
+
các lưu ý riêng của runtime đó (ví dụ mạng trong sandbox của Codex). Nó cũng báo bản đóng băng có tụt sau bản phát hành mới nhất không và lệnh nào
|
|
356
358
|
nó không chạy được, file state có tồn tại không, đã đăng ký repo nào chưa, cả
|
|
357
359
|
hai hooklet pre-commit có chạy được không, và `notifyUrl` có đang trống (hoặc
|
|
358
360
|
thiếu một URL) trong khi một observer trên máy đã khai endpoint không. ✗ nghĩa là thứ đã cài đang cũ
|
package/package.json
CHANGED
package/templates/README.md
CHANGED
|
@@ -2,11 +2,13 @@
|
|
|
2
2
|
|
|
3
3
|
Starting points you **copy into your own repo**. That is the entire model.
|
|
4
4
|
|
|
5
|
-
> **These are NOT called remotely.**
|
|
6
|
-
>
|
|
5
|
+
> **These are NOT called remotely — with one exception.** `instruction-files.yml` is a caller:
|
|
6
|
+
> its one job `uses:` this handbook's reusable `.github/workflows/instruction-files.yml` (#588,
|
|
7
|
+
> kept for compatibility — see *Where each file lives* below). Every other file here is copied,
|
|
8
|
+
> not called. (`dist-refs.yml` is a
|
|
7
9
|
> `workflow_call` workflow, but its caller is your own release workflow, in the same repo, via
|
|
8
10
|
> `uses: ./.github/workflows/dist-refs.yml` — the file still lives, in full, where it runs.) An earlier version of this
|
|
9
|
-
> handbook told repos to call shared workflows; that was reversed. Every workflow now
|
|
11
|
+
> handbook told repos to call shared workflows; that was reversed. Every other workflow now
|
|
10
12
|
> lives, in full, inside the repo that runs it. You copy the file, you edit it, **you
|
|
11
13
|
> own it.** Divergence between your copy and this template is expected — a shared
|
|
12
14
|
> workflow that silently changes under a hundred repos is the failure mode we are
|
|
@@ -70,6 +72,31 @@ Named it something other than `ci-heavy.yml`? Say so with `heavy-workflow:` in `
|
|
|
70
72
|
light templates show a commented `paths-ignore` for docs as an option; the old in-workflow
|
|
71
73
|
docs-only guard is gone.
|
|
72
74
|
|
|
75
|
+
## Where each file lives — the handbook ships no enforcement (#643)
|
|
76
|
+
|
|
77
|
+
Every file in this folder is an **optional starting file**: copy it if it helps, change it as
|
|
78
|
+
you like, or write your own. The handbook states rules; the tool that runs a file is what
|
|
79
|
+
enforces anything, and that tool is the file's home. Where the runner is still a `colab`
|
|
80
|
+
command in this repo, the file stays here until that command's replacement ships — code moves
|
|
81
|
+
only after its replacement exists (epic #631), and a file that moves keeps its path here with a
|
|
82
|
+
header naming its new home ([`docs/compat-surfaces.md`](../docs/compat-surfaces.md)).
|
|
83
|
+
|
|
84
|
+
| File | Runs it today | Home |
|
|
85
|
+
|---|---|---|
|
|
86
|
+
| `ci-node.yml`, `ci-python.yml`, `ci-laravel.yml` (with the #625 `Migration round-trip` job), `ci-*-heavy.yml` | your forge's CI; `colab ship` / `promote` read or dispatch the runs; `colab template --roundtrip` writes the round-trip job | the adopter's CI layer; until it ships (#608), an optional starting file here |
|
|
87
|
+
| `release-tag.yml`, `release-auto.yml` | your forge's CI; `release-auto.yml` runs `colab release cut` / `finalize --auto` | the release commands' new home (#608); an optional starting file here until then |
|
|
88
|
+
| `dist-refs.yml`, `npx-launcher.mjs`, `npx-service.mjs` | your own release workflow and package `bin` | stays here, as an optional starting file |
|
|
89
|
+
| `publish-downloads.yml`, `publish-downloads.mjs` | your own release workflow, as its last job | stays here, as an optional starting file |
|
|
90
|
+
| `deploy-xserver.yml`, `deploy-container.yml`, `deploy-container-run.mjs`, `deploy-adapter-portainer.mjs` | your repo's deploy workflow | the adopter's deploy tooling; here as an optional starting file |
|
|
91
|
+
| `pre-push-guard` | git, honouring `COLAB_SHIP=1` from `colab ship` | the tool that lands branches (#608); an optional starting file here until then |
|
|
92
|
+
| `pre-commit-dispatch`, `pre-commit-identity`, `identity-vocabulary.example` | git (this repo's own `.githooks/` run them in place) | stays here, as an optional starting file |
|
|
93
|
+
| `pre-commit-instruction-files`, `instruction-files.yml` | `colab instruction-files`; the reusable workflow in this repo | the `colab instruction-files` command; the reusable workflow is the one remote call this folder keeps, for compatibility |
|
|
94
|
+
| `docs-lint.mjs`, `docs-lint.yml`, `branch-name.yml` | your CI (advisory or opt-in); `code-wrap`'s docs step | stays here, as an optional starting file |
|
|
95
|
+
| `repo-CLAUDE-block.md`, `gotchas-d-README.md`, `adr-README.md` | nothing — text you paste or copy (`colab adopt` pastes the block) | stays here |
|
|
96
|
+
|
|
97
|
+
Nothing in this table changes what a copied file does. A stamp, a drift report or a `colab`
|
|
98
|
+
check that reads one of these files is that tool's behaviour, documented with the tool.
|
|
99
|
+
|
|
73
100
|
## What each template is for
|
|
74
101
|
|
|
75
102
|
| File | Copy to | For | Notes |
|
|
@@ -83,6 +110,8 @@ Named it something other than `ci-heavy.yml`? Say so with `heavy-workflow:` in `
|
|
|
83
110
|
| `dist-refs.yml` | `.github/workflows/dist-refs.yml` | A **private** repo shipping a **compiled** tool, installed as `npx github:<org>/<repo>#vX.Y.Z` ([CONVENTIONS §6, *Distribution*](../CONVENTIONS.md#distribution--one-install-surface-npx-442)) | `workflow_call`, called from the same run that cut the release tag (a tag pushed with `GITHUB_TOKEN` triggers nothing else). Takes one build artifact per `<os>-<arch>` and pushes each as an orphan commit at `refs/tags/dist/vX.Y.Z/<os>-<arch>` with a `SHA256SUMS`. Refuses a public or unreadable repository (a public compiled tool ships npm platform packages instead), a version that is not an existing tag, and a missing platform — before pushing any. Never moves a dist ref that exists. |
|
|
84
111
|
| `npx-launcher.mjs` | anywhere in-repo (e.g. `bin/launch.mjs`), named by the root `package.json`'s `bin` | Pairs with `dist-refs.yml` | Node ≥ 18, zero dependencies, needs `git`. Reads the `#vX.Y.Z` npx installed, fetches that one dist ref with the same URL and credentials npx cloned with, verifies `SHA256SUMS`, installs to a stable per-user path (`$XDG_DATA_HOME`/`%LOCALAPPDATA%`), and execs it; `--print-path` prints that path. A **channel** committish (`#stable`, `#next`, #465) is resolved to the release tag on the commit npx installed, then installed as that version; any other branch is refused. Also the library `npx-service.mjs` imports. `*.mjs`, so `colab template npx-launcher.mjs --dest <path>` copies it stamped, `--dest` required. One edit point: `BIN` (defaults to the package name without its scope). |
|
|
85
112
|
| `npx-service.mjs` | the same directory as your `npx-launcher.mjs` copy (e.g. `bin/service.mjs`), named by the root `package.json`'s `bin` | A tool that runs as a **per-machine service** (a dashboard, a daemon, a JS app a launch agent serves), installed with npx ([CONVENTIONS §6, *Services over npx*](../CONVENTIONS.md#services-over-npx--init-update-rollback-465)) | `npx github:<org>/<repo>#vX.Y.Z init [--auto-update 6h \| --no-auto-update]`, then `<tool> update [--check] [--version vX.Y.Z] [--channel next\|stable]`, `<tool> rollback`, `<tool> status`, `<tool> uninstall [--purge]` (#472: unit, timer, shim and every version go; config and state stay unless `--purge`); anything else runs the current version's payload. Versions side by side under `$XDG_DATA_HOME/<tool>/` with `current`/`previous` links the unit and the `~/.local/bin` shim go through; update installs beside, switches, restarts, health-checks, and **switches back** on failure. Config/secrets under `$XDG_CONFIG_HOME/<tool>/`, state and logs under `$XDG_STATE_HOME/<tool>/` — the unit carries their locations, never a value. launchd agent on macOS, systemd user unit on Linux, Windows refused; `<TOOL>_SERVICE_MANAGER=none` skips the manager. `--auto-update` (#471) adds a timer (launchd `StartInterval` agent / systemd user `.timer`) that runs the same `update`. Node ≥ 18, zero dependencies; needs `git`, `npm` for `update`, `tar` for `dist`. **Imports `./npx-launcher.mjs`** — copy both, or edit the import. Edit points: `KIND` (`binary` = a compiled tool from dist refs, `package` = a JS app run with node, `dist` = a prebuilt JS app unpacked from one verified tarball in the `dist/vX.Y.Z/any` ref, #470), `LABEL`, `SERVICE_ARGS`, `ENTRY`, `DIST_FILE`, `HEALTH_URL`, `KEEP`, `AUTO_UPDATE`, `VERBS`. The package's `files` must include both copies (and a `package` app's built output). `colab template npx-service.mjs --dest <path>`, `--dest` required. |
|
|
113
|
+
| `publish-downloads.yml` | `.github/workflows/publish-downloads.yml` | A repo whose **finals** carry files people install on their own machines, published to a **self-hosted downloads site** ([CONVENTIONS §6, *Downloads*](../CONVENTIONS.md#downloads--finals-to-a-self-hosted-site-648); contract in [`docs/downloads.md`](../docs/downloads.md)) | `workflow_call` from your release workflow's last job (a tag or Release made with `GITHUB_TOKEN` triggers nothing else), and `workflow_dispatch` with a tag to retry, finish a partial run, or `dry_run`. Finals only. Downloads the Release's files the `downloads:` block in `project.yml` names and runs the script below. Inputs: `runs-on` — a runner that can **reach the site** (a private-network site is unreachable from a GitHub-hosted runner; an unresolvable name fails the run before anything is sent) — and `reserved`, names the site keeps for itself. Secrets `DOWNLOADS_SSH_KEY` / `_SSH_HOST` / `_SSH_PORT` / `_SSH_USER` / `_SSH_KNOWN_HOSTS` (the older `DOWNLOADS_KNOWN_HOSTS` is still read as a fallback), variable `DOWNLOADS_URL` (the site root). Edit point: `PUBLISH_SCRIPT`. |
|
|
114
|
+
| `publish-downloads.mjs` | `.github/downloads/publish-downloads.mjs` (the workflow's `PUBLISH_SCRIPT`) | Pairs with `publish-downloads.yml` | `check` · `names vX.Y.Z` · `publish vX.Y.Z <dir> [--dry-run]`. rsync over SSH in a fixed order — the version folder, each file read back over HTTPS against its checksum, `SHA256SUMS`, installers (`@DOWNLOADS_URL@` stamped), `manifest.json`, `latest.json` **last** (never moved back to an older final) — then reads it all back. Never replaces a published file; a different `SHA256SUMS` for a published version refuses; a re-run sends nothing. Validates the manifest the portal lists. Node ≥ 18, zero dependencies. `colab template publish-downloads.mjs --dest <path>`, `--dest` required. |
|
|
86
115
|
| `deploy-xserver.yml` | `.github/workflows/deploy-xserver.yml` | PHP-framework + Vite apps shipped to **shared hosting over SSH** (no root, no Docker): build on a runner, rsync, migrate on the server | Derived from three independently-written copies. Resolves Node the same way the CI templates do — all three hardcoded it, and one shipped on a different major than its CI built on. Migrates **production**; keeps a **mandatory** smoke test. Does **not** change your tier. |
|
|
87
116
|
| `deploy-container.yml` | `.github/workflows/deploy-container.yml` | A **container** app on a host whose platform has an API (Portainer today), `deploy: tag` ([CONVENTIONS §6, *A container deploy*](../CONVENTIONS.md#6-releases), #452) | One contract on every host: build each listed image **once** per final tag (`vX.Y.Z` + commit sha), run the pre-deploy hook, have the platform run exactly that tag (all images, one call), green only on a **verified running version** (stack settled, commit and container images checked, then `release.health-url` reporting `X.Y.Z`), roll back to the previous final on a failure after the platform accepted. **Two jobs (#460):** `publish` builds and pushes on **every** final, ungated — so a repo not yet cut over still gets each final's image in the registry; `deploy` `needs:` it, never builds (a missing image fails before the platform is touched), and is the one job you gate on "is the platform switched on". Images and build args sit in the workflow-level `env`, written once for both jobs. Triggers: a final tag push (route `deploy-tag`), `workflow_dispatch` with a tag (a manual deploy or rollback), and `workflow_call` — route `deploy-tag-fast` reaches it from `release-auto.yml`'s commented `deploy` job, like `dist-refs.yml` from its release run. Needs its two scripts below. One required secret: `PORTAINER_API_KEY`, a non-admin key owning only this app's stack; optional `HEALTH_AUTH_HEADER` (`Name: value`) or `HEALTH_BASIC_AUTH` (`user:password`) when the version URL sits behind auth — masked, never printed. **Every redeploy recreates the containers.** Does **not** change your exposure. |
|
|
88
117
|
| `deploy-container-run.mjs` | `.github/deploy/deploy-container-run.mjs` | Pairs with `deploy-container.yml` | The driver: builds, runs the hook, calls the adapter, verifies, rolls back, records. `--publish-only` = build and push only (no platform config, no version URL needed); `--deploy-only` = everything after, refusing a tag whose image is not in the registry. **Build args:** `DEPLOY_BUILD_ARGS`, one per line — `KEY=VALUE` for every image or `<image-ref> KEY=VALUE` for one; `${TAG}` (`vX.Y.Z`), `${VERSION}` (`X.Y.Z`) and `${SHA}` are filled in by the driver, so a static site can bake public config and its version into a served file. They end up in the image — public values only, never a secret. Node ≥ 18, zero dependencies; shells out to `git`, `docker`, `gh`. `colab template deploy-container-run.mjs --dest <path>`, `--dest` required, stamped on line 2. |
|
|
@@ -175,7 +204,7 @@ colab template ci-python --dest .github/workflows/ci.yml --roundtrip --roundtrip
|
|
|
175
204
|
|
|
176
205
|
### Migration round-trip — what the Laravel job proves, and what it cannot
|
|
177
206
|
|
|
178
|
-
`ci-laravel.yml`'s `migrations` job runs every migration **twice per engine**: once from
|
|
207
|
+
`ci-laravel.yml`'s `migrations` job runs every migration **twice per database engine**: once from
|
|
179
208
|
zero, then — after rolling back the migrations the change adds and seeding rows at the
|
|
180
209
|
schema *before* the change — once more, the way a deploy lands new migrations on data
|
|
181
210
|
that predates them. The schema after both passes must match. Two things to know before
|
|
@@ -246,6 +275,8 @@ directory into ~45 repos and was wrong — fixed 2026-08-20.
|
|
|
246
275
|
colab template deploy-container --dest .github/workflows/deploy-container.yml
|
|
247
276
|
colab template deploy-container-run.mjs --dest .github/deploy/deploy-container-run.mjs
|
|
248
277
|
colab template deploy-adapter-portainer.mjs --dest .github/deploy/deploy-adapter-portainer.mjs
|
|
278
|
+
colab template publish-downloads --dest .github/workflows/publish-downloads.yml
|
|
279
|
+
colab template publish-downloads.mjs --dest .github/downloads/publish-downloads.mjs
|
|
249
280
|
colab template docs-lint.mjs --dest tools/docs-lint.mjs # --dest is required for this one
|
|
250
281
|
```
|
|
251
282
|
|
|
@@ -376,6 +407,9 @@ drift is only ever a suggestion (#607), so the trailer is moot there. Full contr
|
|
|
376
407
|
is missing or incoherent, when a declared toolchain disagrees with what CI actually
|
|
377
408
|
pins, when branch names drift, and when a stamped copy has fallen behind its template.
|
|
378
409
|
It is advisory — run it locally or on a schedule. It is **not** wired into any repo's CI.
|
|
410
|
+
That multi-repo sweep is adopter tooling: it runs from here, unchanged, until its replacement
|
|
411
|
+
ships, and then leaves; only the text checks stay
|
|
412
|
+
([`audit/README.md`, *What stays and what leaves*](../audit/README.md#what-stays-and-what-leaves-643)).
|
|
379
413
|
|
|
380
414
|
## Runner policy
|
|
381
415
|
|