@futurelastic/colab-handbook 1.13.0-rc.11 → 1.13.0-rc.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -13,15 +13,16 @@ This file is for humans.
13
13
 
14
14
  ```sh
15
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
16
+ cd ~/code/colab-handbook && ./install.sh --all # asks which coding agent gets the skills; + colab CLI + hooks, from the newest release; --dry shows it first
17
17
  cd /path/to/your-repo
18
18
  colab adopt # asks only what it cannot detect, writes .github/project.yml
19
19
  colab labels --ensure # creates the convention labels
20
20
  colab register # adds the repo to this machine's fleet list
21
21
  ```
22
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
23
+ Then, in an agent session in that repo, run the `code-start` skill with an issue
24
+ number — each engine has its own way to invoke a skill, see [*Choose your engine*](#choose-your-engine).
25
+ With an agent at hand, the `handbook-sync` skill replaces the last three commands and also does
25
26
  the rest of adoption (see [*Adopting it into a repo*](#adopting-it-into-a-repo)).
26
27
  You need `git`, `node` ≥ 18 and `gh` ≥ 2.94 logged in (`gh auth login`); distro
27
28
  packages often ship an older `gh`, so install it from [cli.github.com](https://cli.github.com).
@@ -94,19 +95,19 @@ with no agent and no other tool.
94
95
 
95
96
  ## Your first session
96
97
 
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/).
98
+ A unit of work goes round one loop. Each step is a skill, invoked by name in an
99
+ agent session (the syntax is the engine's — [*Choose your engine*](#choose-your-engine)),
100
+ or followed by hand from [`skills/`](skills/).
100
101
 
101
102
  | Step | Skill | Who runs it | What it leaves behind |
102
103
  |---|---|---|---|
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 |
104
+ | 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 |
105
+ | 2. Open | `code-start <N>` | implementer | the issue claimed, a branch cut from trunk and pushed, a worktree, a short plan file |
105
106
  | 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 |
107
+ | 4. Hand off | `code-wrap` | implementer | what was learned written onto the Issue, the repo's gate run, the branch pushed — then it **stops** |
108
+ | 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 |
109
+ | 6. Clean up | `code-sweep` | coordinator | finished work shipped, stale claims and worktrees cleared |
110
+ | 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
 
111
112
  Also in [`skills/`](skills/): `code-plan` (a full plan for a hard issue, run by
112
113
  `code-start` when flagged), `handbook-sync` (bring one repo up to the current
@@ -165,7 +166,7 @@ and why: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) and
165
166
 
166
167
  ## Adopting it into a repo
167
168
 
168
- **The default route: run `/handbook-sync` in an agent session inside the repo.**
169
+ **The default route: run the `handbook-sync` skill in an agent session inside the repo.**
169
170
  It sees that nothing is adopted yet and drives adoption to the end — the
170
171
  descriptor (through `colab adopt`), the labels, the `CLAUDE.md` block, CI from
171
172
  the templates, and registration on this machine. Run later, the same skill
@@ -244,7 +245,8 @@ migration hold with or without it.
244
245
  | [`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. |
245
246
  | [`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). |
246
247
  | [`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). |
247
- | [`skills/`](skills/) | The session flow — see [*Your first session*](#your-first-session). Installed as Claude Code skills by `install.sh`. |
248
+ | [`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. |
249
+ | [`engines/`](engines/) | One small data file per coding agent: where its user-level skills go, how a skill is invoked, what it supports. Adding an engine is adding a file — [`engines/README.md`](engines/README.md). |
248
250
  | [`install.sh`](install.sh) | Sets up **your machine**: skills, the `colab` CLI, the pre-commit hook, the fleet list. Idempotent; `--dry` shows everything first. |
249
251
 
250
252
  ## Setting up a machine
@@ -268,9 +270,36 @@ Later moves are explicit:
268
270
  A clone with uncommitted changes is never moved, and a re-run without either
269
271
  flag keeps whatever is checked out.
270
272
 
273
+ ### Choose your engine
274
+
275
+ The skills are plain `SKILL.md` folders that call `git`, `gh` and `colab`; any
276
+ coding agent that reads skills can run them. What differs is **where each
277
+ agent looks for them**, so the install asks. At a terminal, `./install.sh`
278
+ lists the engines it knows and lets you pick one or more, with *other: give a
279
+ path* last. Unattended, say it with a flag:
280
+
281
+ ```sh
282
+ ./install.sh --engine claude # Claude Code → ~/.claude/skills
283
+ ./install.sh --engine claude,codex # both
284
+ ./install.sh --skills-dir ~/my-agent/skills # any other agent: you give its folder
285
+ ```
286
+
287
+ | Engine | Skills folder | Invoke | Before the skills work there |
288
+ |---|---|---|---|
289
+ | 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. |
290
+ | 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. |
291
+ | 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`. |
292
+
293
+ A re-run with no flag and no terminal keeps every engine it finds already
294
+ linked, so an existing machine changes nothing. Finding none, it installs for
295
+ Claude Code and says so. The per-engine facts live in [`engines/`](engines/),
296
+ one file each — that folder is the source for the table above.
297
+
271
298
  | Flag | What it does |
272
299
  |---|---|
273
- | *(none)* | Symlink `skills/` into `~/.claude/skills/`, so they are available in every repo you open. |
300
+ | *(none)* | Symlink `skills/` into each chosen engine'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 engine*](#choose-your-engine)). |
301
+ | `--engine <id>[,<id>]` | Install for these engines (`claude`, `codex` — the files in `engines/`), no question asked. |
302
+ | `--skills-dir <path>` | Also install into this folder, for an agent `engines/` does not know. |
274
303
  | `--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. |
275
304
  | `--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)). |
276
305
  | `--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. |
@@ -294,7 +323,7 @@ yet, so the default `latest` tag holds only a placeholder; install from
294
323
  **`@next`**, the release candidates: `npx @futurelastic/colab-handbook@next
295
324
  <command>`, or `npm i -g @futurelastic/colab-handbook@next`. The command is
296
325
  still `colab`. The skills are not in the package; they install from a
297
- clone, because they must symlink into `~/.claude/skills/`.
326
+ clone, because they are symlinks into its working tree.
298
327
 
299
328
  ### Checking an install
300
329
 
@@ -305,7 +334,8 @@ node audit/audit.mjs # a conformance report across every registered repo
305
334
  colab update # stamped copies that fell behind, the frozen CLI included
306
335
  ```
307
336
 
308
- `--check` reports whether the frozen copy is behind the latest release and
337
+ `--check` reports, per engine, how many skills are linked, missing or broken,
338
+ plus that engine's own caveats (Codex's sandbox network, for instance). It also reports whether the frozen copy is behind the latest release and
309
339
  which commands it does not dispatch, whether the state file exists, whether
310
340
  anything is registered, whether both pre-commit hooklets can run, and whether
311
341
  `notifyUrl` is unset while a local observer declared an endpoint. ✗ means
package/README.vi.md CHANGED
@@ -12,15 +12,16 @@ File này dành cho con người.
12
12
 
13
13
  ```sh
14
14
  git clone https://github.com/futurelastic/colab-handbook.git ~/code/colab-handbook
15
- cd ~/code/colab-handbook && ./install.sh --all # skills + CLI colab + hook, từ bản phát hành mới nhất; --dry để xem trước
15
+ cd ~/code/colab-handbook && ./install.sh --all # hỏi agent nào nhận skill; + CLI colab + hook, từ bản phát hành mới nhất; --dry để xem trước
16
16
  cd /duong-dan/toi/repo-cua-ban
17
17
  colab adopt # chỉ hỏi những gì không tự dò ra được, rồi ghi .github/project.yml
18
18
  colab labels --ensure # tạo các label quy ước
19
19
  colab register # đưa repo vào danh sách fleet của máy này
20
20
  ```
21
21
 
22
- Sau đó, trong một phiên agent ở repo đó, chạy `/code-start <số-issue>`. Có agent
23
- trong tay thì `/handbook-sync` thay được ba lệnh cuối và làm nốt phần adopt còn
22
+ Sau đó, trong một phiên agent ở repo đó, chạy skill `code-start` kèm số issue —
23
+ mỗi engine có cách gọi skill riêng, xem [*Chọn engine*](#chọn-engine). Có agent
24
+ trong tay thì skill `handbook-sync` thay được ba lệnh cuối và làm nốt phần adopt còn
24
25
  lại (xem [*Adopt vào một repo*](#adopt-vào-một-repo)). Cần có `git`, `node` ≥ 18
25
26
  và `gh` ≥ 2.94 đã đăng nhập (`gh auth login`); gói `gh` của các distro thường cũ
26
27
  hơn, nên hãy cài từ [cli.github.com](https://cli.github.com).
@@ -93,19 +94,19 @@ khác.
93
94
 
94
95
  ## Phiên làm việc đầu tiên
95
96
 
96
- Mỗi đầu việc đi qua một vòng. Mỗi bước là một skill, gọi trong phiên agent bằng
97
- slash command (`/code-start 42`), hoặc tự làm theo bằng tay từ
98
- [`skills/`](skills/).
97
+ 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
98
+ agent (cú pháp gọi là của engine — [*Chọn engine*](#chọn-engine)), hoặc tự làm
99
+ theo bằng tay từ [`skills/`](skills/).
99
100
 
100
101
  | Bước | Skill | Ai chạy | Để lại gì |
101
102
  |---|---|---|---|
102
- | 1. Chọn | `/code-triage` | điều phối | việc sẵn sàng theo thứ tự, label `group:` trên các issue phải chung một nhánh, `needs-plan` trên việc khó, lệnh để bắt đầu |
103
- | 2. Mở | `/code-start <N>` | thợ | issue đã claim, nhánh cắt từ trunk và đã push, một worktree, một file plan ngắn |
103
+ | 1. Chọn | `code-triage` | điều phối | việc sẵn sàng theo thứ tự, label `group:` trên các issue phải chung một nhánh, `needs-plan` trên việc khó, lệnh để bắt đầu |
104
+ | 2. Mở | `code-start <N>` | thợ | issue đã claim, nhánh cắt từ trunk và đã push, một worktree, một file plan ngắn |
104
105
  | 3. Làm | — | thợ | commit trên nhánh |
105
- | 4. Bàn giao | `/code-wrap` | thợ | điều học được ghi lên Issue, gate của repo đã chạy, nhánh đã push — rồi **dừng** |
106
- | 5. Merge | `/code-ship` | điều phối, sau khi người đồng ý | một squash commit trên trunk kèm `Closes #N`, bằng chứng trên từng issue, claim đã nhả, worktree đã gỡ |
107
- | 6. Dọn | `/code-sweep` | điều phối | việc đã xong được ship, claim và worktree cũ được dọn |
108
- | 7. Release | release workflow, hoặc `/release-rung` | tự động, hoặc người khi tag là thứ deploy | một tag ứng viên, rồi bản final sau thời gian thử — chỉ khi `exposure` của repo có release |
106
+ | 4. Bàn giao | `code-wrap` | thợ | điều học được ghi lên Issue, gate của repo đã chạy, nhánh đã push — rồi **dừng** |
107
+ | 5. Merge | `code-ship` | điều phối, sau khi người đồng ý | một squash commit trên trunk kèm `Closes #N`, bằng chứng trên từng issue, claim đã nhả, worktree đã gỡ |
108
+ | 6. Dọn | `code-sweep` | điều phối | việc đã xong được ship, claim và worktree cũ được dọn |
109
+ | 7. Release | release workflow, hoặc `release-rung` | tự động, hoặc người khi tag là thứ deploy | một tag ứng viên, rồi bản final sau thời gian thử — chỉ khi `exposure` của repo có release |
109
110
 
110
111
  Cũng trong [`skills/`](skills/): `code-plan` (plan đầy đủ cho issue khó, do
111
112
  `code-start` gọi khi có cờ), `handbook-sync` (kéo một repo lên bản handbook mới
@@ -165,8 +166,8 @@ sao: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) và
165
166
 
166
167
  ## Adopt vào một repo
167
168
 
168
- **Đường mặc định: chạy `/handbook-sync` trong một phiên agent ngay trong repo
169
- đó.** Nó nhận ra repo chưa adopt gì và đi hết đường adopt — descriptor (qua
169
+ **Đường mặc định: chạy skill `handbook-sync` trong một phiên agent ngay trong
170
+ repo đó.** Nó nhận ra repo chưa adopt gì và đi hết đường adopt — descriptor (qua
170
171
  `colab adopt`), label, block `CLAUDE.md`, CI từ template, và đăng ký trên máy
171
172
  này. Chạy lại về sau, chính skill đó kéo một repo đã adopt lên bản handbook mới
172
173
  nhất mà không làm mất phần bạn đã sửa.
@@ -243,7 +244,8 @@ quyền cấp trước khi chạy migration vẫn đứng vững dù có nó hay
243
244
  | [`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. Không có gì được gọi từ xa — copy, sửa, sở hữu. |
244
245
  | [`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). |
245
246
  | [`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. Ý nghĩa từng check: [`audit/README.md`](audit/README.md). |
246
- | [`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). `install.sh` cài chúng thành skill Claude Code. |
247
+ | [`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. |
248
+ | [`engines/`](engines/) | Mỗi coding agent 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 engine là thêm một file — [`engines/README.md`](engines/README.md). |
247
249
  | [`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ứ. |
248
250
 
249
251
  ## Cài đặt máy
@@ -267,9 +269,36 @@ sau đều phải chủ động:
267
269
  Clone đang có thay đổi chưa commit thì không bao giờ bị chuyển, và chạy lại
268
270
  không kèm flag nào thì giữ nguyên thứ đang checkout.
269
271
 
272
+ ### Chọn engine
273
+
274
+ Các skill là thư mục `SKILL.md` thuần, chỉ gọi `git`, `gh` và `colab`; coding
275
+ agent nào đọc được skill thì chạy được chúng. Khác nhau là **mỗi agent tìm
276
+ skill ở đâu**, nên bản cài sẽ hỏi. Ở terminal, `./install.sh` liệt kê các
277
+ engine 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
278
+ path*. Chạy không người trông thì nói bằng flag:
279
+
280
+ ```sh
281
+ ./install.sh --engine claude # Claude Code → ~/.claude/skills
282
+ ./install.sh --engine claude,codex # cả hai
283
+ ./install.sh --skills-dir ~/my-agent/skills # agent khác: bạn đưa thư mục của nó
284
+ ```
285
+
286
+ | Engine | Thư mục skill | Gọi | Cần làm gì để skill chạy được |
287
+ |---|---|---|---|
288
+ | 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ó. |
289
+ | 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. |
290
+ | 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`. |
291
+
292
+ Chạy lại không flag và không có terminal thì giữ mọi engine đã thấy được link
293
+ sẵn, nên máy đã cài không thay đổi gì. Không thấy engine nào thì cài cho Claude
294
+ Code và nói rõ điều đó. Thông tin từng engine nằm trong [`engines/`](engines/),
295
+ mỗi engine một file — thư mục đó là nguồn của bảng trên.
296
+
270
297
  | Flag | Làm gì |
271
298
  |---|---|
272
- | *(không có)* | Symlink `skills/` vào `~/.claude/skills/`, để mở repo nào cũng có. |
299
+ | *(không có)* | Symlink `skills/` vào thư mục cấp user của từng engine đã chọn, để mở repo nào cũng có. Ở terminal thì hỏi; không thì giữ những gì đã link (xem [*Chọn engine*](#chọn-engine)). |
300
+ | `--engine <id>[,<id>]` | Cài cho các engine này (`claude`, `codex` — các file trong `engines/`), không hỏi. |
301
+ | `--skills-dir <path>` | Cài thêm vào thư mục này, cho agent mà `engines/` chưa biết. |
273
302
  | `--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ó. |
274
303
  | `--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)). |
275
304
  | `--fleet` | Tạo `~/.colab/repos.txt` chỉ chứa ghi chú định dạng, nếu chưa có. Nó cố tình nằm trên máy vì nó ghi tên các repo private của bạn; `colab register` mới là thứ điền vào. |
@@ -291,8 +320,8 @@ báo khi nó tụt sau một thay đổi CLI đã phát hành, và chạy lại
291
320
  Chưa có bản phát hành chính thức nào lên npm, nên tag mặc định `latest` chỉ là
292
321
  bản giữ chỗ; hãy cài từ **`@next`**, các bản ứng viên: `npx
293
322
  @futurelastic/colab-handbook@next <lệnh>`, hoặc `npm i -g
294
- @futurelastic/colab-handbook@next`. Lệnh gõ vẫn là `colab`. Skill không nằm trong package; chúng cài từ một bản clone, vì phải
295
- symlink vào `~/.claude/skills/`.
323
+ @futurelastic/colab-handbook@next`. Lệnh gõ vẫn là `colab`. Skill không nằm trong package; chúng cài từ một bản clone, vì chúng là
324
+ symlink trỏ vào working tree của bản clone đó.
296
325
 
297
326
  ### Kiểm tra bản cài
298
327
 
@@ -303,7 +332,8 @@ node audit/audit.mjs # báo cáo conformance cho mọi repo đã đăng ký
303
332
  colab update # các bản copy có đóng dấu đã tụt lại, kể cả CLI đóng băng
304
333
  ```
305
334
 
306
- `--check` 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
335
+ `--check` báo theo từng engine: bao nhiêu skill đã link, thiếu hay hỏng, kèm
336
+ các lưu ý riêng của engine đó (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
307
337
  nó không chạy được, file state có tồn tại không, đã đăng ký repo nào chưa, cả
308
338
  hai hooklet pre-commit có chạy được không, và `notifyUrl` có đang trống trong
309
339
  khi một observer trên máy đã khai endpoint không. ✗ nghĩa là thứ đã cài đang cũ
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.13.0-rc.11"
36
+ "version": "1.13.0-rc.13"
37
37
  }
package/tools/colab CHANGED
@@ -283,8 +283,9 @@ function commentHost(repoAbs) {
283
283
  function myMachineId() { return machine.localMachine().id || null; }
284
284
 
285
285
  /**
286
- * Resolve the Claude session URL for this invocation: --session flag > COLAB_SESSION env >
287
- * a DERIVED person identity (#528) > '' (absent, never an error). Free-form — typically a session URL.
286
+ * Resolve the session id for this invocation: --session flag > COLAB_SESSION env >
287
+ * a DERIVED person identity (#528) > '' (absent, never an error). Free-form — any stable id for
288
+ * the session (a URL, a uuid…).
288
289
  *
289
290
  * The derived step exists for a person at a plain terminal, who has no session runtime and so no
290
291
  * id to pass: without it their first trunk `colab claim` refused (#242's gate), `worktree new`
@@ -390,7 +391,7 @@ function warnWeakIdentity(session, sessionName, what, ref) {
390
391
  warn(`no --session or --session-name given — this ${what} will carry NO holder identity.`);
391
392
  warn(` A live hold's refusal can then only point at its process id, and this acquire will`);
392
393
  warn(` not be recognized as your own on a later re-acquire without one.`);
393
- if (ref) warn(` Repair once you have an identity: colab worktree tag ${ref} --session <url>`);
394
+ if (ref) warn(` Repair once you have an identity: colab worktree tag ${ref} --session <id>`);
394
395
  return;
395
396
  }
396
397
  // #326: a planner intent id is a deliberate, documented non-URL value — not a mistyped name.
@@ -401,16 +402,16 @@ function warnWeakIdentity(session, sessionName, what, ref) {
401
402
  // refused the caller's own hold when they later presented their REAL url. Warn, never
402
403
  // refuse: `requirePlaceIdentity` promises `<url-or-any-stable-id>`, so a bare stable id is
403
404
  // a blessed value and rejecting it would break that contract and every adopter using one.
404
- warn(`--session "${session}" does not look like a session URL or a session_… id — this ${what}`);
405
+ warn(`--session "${session}" does not look like a session id (a URL, a uuid, a session_… token) — this ${what}`);
405
406
  warn(` will record it verbatim. That is allowed (any stable id works), but if this is your`);
406
407
  warn(` session NAME you probably meant --session-name: a later 'colab place release'`);
407
- warn(` presenting your real URL will NOT match this value and will be refused (#306).`);
408
+ warn(` presenting your real id will NOT match this value and will be refused (#306).`);
408
409
  return;
409
410
  }
410
411
  if (!sessionName || session) return;
411
- warn(`session name "${sessionName}" recorded with NO session URL — this ${what} will read as owned`);
412
- warn(` but cannot be traced to a session. The name is display text; the URL is the join key.`);
413
- if (ref) warn(` Repair once you have it: colab worktree tag ${ref} --session <url>`);
412
+ warn(`session name "${sessionName}" recorded with NO session id — this ${what} will read as owned`);
413
+ warn(` but cannot be traced to a session. The name is display text; the id is the join key.`);
414
+ if (ref) warn(` Repair once you have it: colab worktree tag ${ref} --session <id>`);
414
415
  }
415
416
 
416
417
  /**
@@ -469,8 +470,8 @@ function identityCell(sessionName, session) {
469
470
  /** Print the `(!)` legend under a table, only when at least one row carries a half-identity. */
470
471
  function identityLegend(entries) {
471
472
  if (!entries.some((e) => e && e.sessionName && !e.session)) return;
472
- print(' (!) session NAME with no session URL — reads as owned, links to nothing.');
473
- print(' Repair: colab worktree tag <worktree> --session <url>');
473
+ print(' (!) session NAME with no session id — reads as owned, links to nothing.');
474
+ print(' Repair: colab worktree tag <worktree> --session <id>');
474
475
  }
475
476
 
476
477
  /**
@@ -918,7 +919,8 @@ Options:
918
919
  --branch <name> branch these claims are worked on. Default: none (null) — a claim held on
919
920
  the trunk checkout has no branch. Never the word "trunk": that is a role,
920
921
  and a record holding it resolves to no ref (refused, exit 1)
921
- --session <url> Claude session URL recorded on the claim + comment (default: COLAB_SESSION env).
922
+ --session <id> any stable id for this session (a URL, a uuid…), recorded on the claim + comment
923
+ (default: COLAB_SESSION env).
922
924
  MANDATORY when no --worktree is given (#242): a claim with no worktree takes
923
925
  the trunk-checkout place-claim, and a blank session can never be recognized
924
926
  as its own later re-acquire — refused (exit 1) before anything is read/written.
@@ -2798,7 +2800,7 @@ function cmdGateHermetic(argv) {
2798
2800
  // neither, so there is nothing else in state.json a second solo attempt could collide with.
2799
2801
  // ---------------------------------------------------------------------------
2800
2802
 
2801
- const HELP_SOLO = `colab solo [--repo <path>] [--force] [--session <url>] [--session-name <name>]
2803
+ const HELP_SOLO = `colab solo [--repo <path>] [--force] [--session <id>] [--session-name <name>]
2802
2804
  colab solo --done [--repo <path>]
2803
2805
 
2804
2806
  Entry gate for solo flow (CONVENTIONS.md, Solo flow) — requires BOTH: this repo does not declare
@@ -3073,7 +3075,7 @@ function cmdSoloDone(repoAbs, doc) {
3073
3075
  // exactly `writes: isolated` — see writes-authority.js's `trunkDirectVetoed`)
3074
3076
  // ---------------------------------------------------------------------------
3075
3077
 
3076
- const HELP_PLACE = `colab place <acquire|check|release> <path> [--repo P] [--session URL] [--session-name N] [--force]
3078
+ const HELP_PLACE = `colab place <acquire|check|release> <path> [--repo P] [--session ID] [--session-name N] [--force]
3077
3079
 
3078
3080
  Path-scoped, machine-local hold on ONE checkout (CONVENTIONS.md, Place-claims) — what a shared
3079
3081
  trunk checkout needs on any repo that does not declare \`writes: isolated\` (the veto), and a
@@ -5235,7 +5237,8 @@ dependency symlinking, dev-server restarts) live in OPTIONAL repo hooks, not her
5235
5237
  <type>/, prefix or not; else the branch after its first '/')
5236
5238
  --trunk <name> override trunk branch
5237
5239
  --repo <path> repo root (default: git root of cwd)
5238
- --session <url> Claude session URL recorded on the worktree + its claims (env COLAB_SESSION)
5240
+ --session <id> any stable id for this session (a URL, a uuid…), recorded on the worktree +
5241
+ its claims (env COLAB_SESSION)
5239
5242
  --session-name <s> short human label for tables/messages (env COLAB_SESSION_NAME)
5240
5243
  --pid <n|none> the new worktree's place-claim liveness anchor (#288) — same meaning as
5241
5244
  \`colab claim\`'s --pid; default: auto-detect (env COLAB_PLACE_PID too)
@@ -5262,7 +5265,7 @@ dependency symlinking, dev-server restarts) live in OPTIONAL repo hooks, not her
5262
5265
  and state record in place for a retry, unless --force. Refuses if there are
5263
5266
  uncommitted TRACKED changes unless --force.
5264
5267
 
5265
- colab worktree tag <name> --session <url> [--session-name <s>] [--branch <b>]
5268
+ colab worktree tag <name> --session <id> [--session-name <s>] [--branch <b>]
5266
5269
  REPAIR session identity, and/or the recorded branch, on a worktree that already
5267
5270
  exists — and on every claim attached to it (claims hold their own copy of each
5268
5271
  field, and claims are what \`doctor\` reports and what \`ship\` unions by). Pass any
@@ -5886,7 +5889,7 @@ function cmdWorktreeRm(argv) {
5886
5889
  }
5887
5890
 
5888
5891
  /**
5889
- * `colab worktree tag <name> --session <url> [--session-name <s>] [--branch <b>]` — repair
5892
+ * `colab worktree tag <name> --session <id> [--session-name <s>] [--branch <b>]` — repair
5890
5893
  * session identity, and/or the recorded branch, on an ALREADY-created worktree. Before this, the
5891
5894
  * only fix was hand-editing ~/.colab/state.json.
5892
5895
  *
@@ -5920,7 +5923,7 @@ function cmdWorktreeTag(argv) {
5920
5923
  const sessionName = String(opts.sessionName || '').trim();
5921
5924
  const branch = String(opts.branch || '').trim();
5922
5925
  if (!session && !sessionName && !branch) {
5923
- throw new UserError('Nothing to tag — pass --session <url>, --session-name <s>, and/or --branch <b>');
5926
+ throw new UserError('Nothing to tag — pass --session <id>, --session-name <s>, and/or --branch <b>');
5924
5927
  }
5925
5928
  if (!state.loadState().worktrees[name]) {
5926
5929
  throw new UserError(`No worktree "${name}" in state (list them with: colab worktrees)`);
@@ -35,15 +35,18 @@ const MACHINE_RE = /· machine `(m:[0-9a-f]{12})`/;
35
35
  const YIELD_RE = /^✅ Released \(yielded — earlier claim by (.+?) wins\)/;
36
36
 
37
37
  /**
38
- * Does `v` look like a session URL / `session_…` id rather than a display name? A SHAPE heuristic
39
- * (#306), not a gate — claim-identity.js re-exports this one copy of it.
38
+ * Does `v` look like a session id — a URL, a `session_…` token, a bare uuid — rather than a display
39
+ * name? A SHAPE heuristic (#306), not a gate — claim-identity.js re-exports this one copy of it.
40
+ * The uuid shape is #531: `--session` takes any stable id, and an engine whose session id is a bare
41
+ * uuid must not have it read back from a claim comment as a session NAME.
40
42
  */
41
43
  function looksLikeSessionId(v) {
42
44
  const s = String(v == null ? '' : v).trim();
43
45
  if (!s) return false;
44
46
  // #528: a derived person identity (`claim-identity.js` `derivePersonSession`) is a session id
45
47
  // too — a stable join key, not a display name — so it reads back as one from a claim comment.
46
- return /^https?:\/\//.test(s) || /session_[\w-]+/.test(s) || /^person:\S+$/.test(s);
48
+ return /^https?:\/\//.test(s) || /session_[\w-]+/.test(s) || /^person:\S+$/.test(s)
49
+ || /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s);
47
50
  }
48
51
 
49
52
  /**
@@ -0,0 +1,52 @@
1
+ 'use strict';
2
+ /**
3
+ * engines/<id>.conf — one data file per coding agent the skills can be installed for (#530).
4
+ *
5
+ * The format is deliberately trivial (`key: value` lines, `#` comments, `note:`/`caveat:`
6
+ * repeatable) so install.sh can read it with sed, without node — a skills-only install must not
7
+ * need the CLI's runtime. This module is the JS reader for `install.sh --check`; the two readers
8
+ * must agree, and install-sh.test.js holds them to it. engines/README.md is the format's doc.
9
+ */
10
+
11
+ const fs = require('fs');
12
+ const path = require('path');
13
+
14
+ const REPEATABLE = new Set(['note', 'caveat']);
15
+
16
+ /** Parse one conf file's text. First occurrence of a single-valued key wins, as `sed …;q` does. */
17
+ function parseConf(text) {
18
+ const out = { note: [], caveat: [] };
19
+ for (const raw of String(text).split(/\r?\n/)) {
20
+ if (/^\s*#/.test(raw)) continue;
21
+ const m = /^([a-z_]+):[ \t]*(.*)$/.exec(raw);
22
+ if (!m) continue;
23
+ const [, key, value] = m;
24
+ if (REPEATABLE.has(key)) out[key].push(value);
25
+ else if (!(key in out)) out[key] = value;
26
+ }
27
+ return out;
28
+ }
29
+
30
+ /** `~/x` → <home>/x. Same rule as install.sh's expand_home for the values a conf file can hold. */
31
+ function expandHome(p, home) {
32
+ if (p === '~') return home;
33
+ if (p.startsWith('~/')) return path.join(home, p.slice(2));
34
+ return p;
35
+ }
36
+
37
+ /** Every engine in <root>/engines, in file order (the order install.sh's prompt numbers them). */
38
+ function listEngines(root) {
39
+ const dir = path.join(root, 'engines');
40
+ let files = [];
41
+ try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.conf')).sort(); } catch (_) { return []; }
42
+ return files.map((f) => ({ id: f.slice(0, -'.conf'.length), ...parseConf(fs.readFileSync(path.join(dir, f), 'utf8')) }));
43
+ }
44
+
45
+ /** Folders given with --skills-dir on an earlier install, one per line in <COLAB_HOME>/skills-dirs. */
46
+ function rememberedDirs(colabHome) {
47
+ let text = '';
48
+ try { text = fs.readFileSync(path.join(colabHome, 'skills-dirs'), 'utf8'); } catch (_) { return []; }
49
+ return text.split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
50
+ }
51
+
52
+ module.exports = { parseConf, expandHome, listEngines, rememberedDirs };
@@ -27,6 +27,7 @@ const path = require('path');
27
27
  const { execFileSync } = require('child_process');
28
28
  const stamp = require('./stamp');
29
29
  const notifyEndpoint = require('./notify-endpoint');
30
+ const engines = require('./engines');
30
31
 
31
32
  const OK = 'ok';
32
33
  const WARN = 'warn';
@@ -141,6 +142,75 @@ function checkFrozen({ root, colabHome }) {
141
142
  return rows;
142
143
  }
143
144
 
145
+ /**
146
+ * The skills, per engine (#530). For every engine in engines/ with a folder of its own, plus every
147
+ * folder an earlier --skills-dir remembered: how many of this clone's skills are linked there, which
148
+ * are missing (a skill added since the install — re-run it), which links are broken (they point into
149
+ * this clone's skills/ at a folder that no longer exists — ✗, installed and now unusable), and which
150
+ * names something else holds (⚠, possibly a deliberate local variant; install.sh never clobbers it).
151
+ *
152
+ * An engine with nothing linked is "not installed for it" — one ✓ line naming them, because a
153
+ * Claude-only machine is a correct machine. Only when NO engine has the skills is that a ⚠.
154
+ * The engine's own `caveat:` lines become ⚠ rows while it is installed: they are what the user must
155
+ * do there for the skills to work (a sandbox with no network, say), and they stay true until done.
156
+ */
157
+ function checkSkills({ root, home, colabHome }) {
158
+ const src = path.join(root, 'skills');
159
+ let skills = [];
160
+ try { skills = fs.readdirSync(src, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort(); } catch (_) { /* none */ }
161
+ const all = engines.listEngines(root);
162
+ const byId = Object.fromEntries(all.map((e) => [e.id, e]));
163
+ const targets = all.filter((e) => e.skills_dir).map((e) => ({ e, dir: engines.expandHome(e.skills_dir, home) }));
164
+ for (const dir of engines.rememberedDirs(colabHome)) {
165
+ if (!targets.some((t) => t.dir === dir)) targets.push({ e: byId.generic || { id: 'generic', label: 'another engine', note: [], caveat: [] }, dir });
166
+ }
167
+
168
+ const rows = [];
169
+ const notInstalled = [];
170
+ for (const { e, dir } of targets) {
171
+ const linked = []; const missing = []; const broken = []; const foreign = [];
172
+ for (const name of skills) {
173
+ const dest = path.join(dir, name);
174
+ let st;
175
+ try { st = fs.lstatSync(dest); } catch (_) { missing.push(name); continue; }
176
+ if (!st.isSymbolicLink()) { foreign.push(name); continue; }
177
+ const to = path.resolve(dir, fs.readlinkSync(dest));
178
+ if (to === path.join(src, name)) linked.push(name);
179
+ else foreign.push(name);
180
+ }
181
+ // Links into this clone's skills/ whose target is gone: a skill removed or renamed upstream.
182
+ let entries = [];
183
+ try { entries = fs.readdirSync(dir); } catch (_) { /* folder absent */ }
184
+ for (const n of entries) {
185
+ const p = path.join(dir, n);
186
+ try {
187
+ if (!fs.lstatSync(p).isSymbolicLink()) continue;
188
+ const to = path.resolve(dir, fs.readlinkSync(p));
189
+ if (to.startsWith(src + path.sep) && !fs.existsSync(to)) broken.push(n);
190
+ } catch (_) { /* unreadable entry — not ours to judge */ }
191
+ }
192
+ const who = `${e.id} (${e.label || e.id}) ${dir}`;
193
+ if (!linked.length && !broken.length) { notInstalled.push(e.id === 'generic' ? dir : `${e.id} (${e.label || e.id})`); continue; }
194
+ const parts = [`${linked.length}/${skills.length} linked`];
195
+ if (missing.length) parts.push(`missing ${missing.join(', ')} — re-run ./install.sh${e.id === 'generic' ? '' : ` --engine ${e.id}`}`);
196
+ if (foreign.length) parts.push(`held by something else (left as is): ${foreign.join(', ')}`);
197
+ if (broken.length) parts.push(`BROKEN links to skills that no longer exist: ${broken.join(', ')} — remove them: ${broken.map((b) => `rm '${path.join(dir, b)}'`).join('; ')}`);
198
+ rows.push({
199
+ area: 'skills',
200
+ severity: broken.length ? FAIL : (missing.length || foreign.length) ? WARN : OK,
201
+ text: `${who}: ${parts.join('; ')}`,
202
+ });
203
+ for (const c of e.caveat || []) rows.push({ area: 'skills', severity: WARN, text: `${e.id}: ${c}` });
204
+ if (e.verified && /^no\b/.test(e.verified)) rows.push({ area: 'skills', severity: WARN, text: `${e.id}: engine file not verified by a run yet — ${e.verified.replace(/^no\s*[—-]?\s*/, '')}` });
205
+ }
206
+ if (!rows.length) {
207
+ rows.push({ area: 'skills', severity: WARN, text: `not linked for any engine — ./install.sh asks which (or --engine <id> / --skills-dir <path>)` });
208
+ } else if (notInstalled.length) {
209
+ rows.push({ area: 'skills', severity: OK, text: `not installed for: ${notInstalled.join(', ')} — fine if deliberate; ./install.sh --engine <id> adds one` });
210
+ }
211
+ return rows;
212
+ }
213
+
144
214
  /** The state file. The CLI creates it lazily, so a consumer reading it early saw an error, not an empty fleet. */
145
215
  function checkState({ root, colabHome, home }) {
146
216
  const file = path.join(colabHome, 'state.json');
@@ -245,6 +315,7 @@ function checkNotify({ colabHome }) {
245
315
  function runChecks(opts) {
246
316
  const o = { env: process.env, ...opts };
247
317
  return [
318
+ ...checkSkills(o),
248
319
  checkLink(o),
249
320
  ...checkFrozen(o),
250
321
  checkState(o),
@@ -280,5 +351,5 @@ if (require.main === module) {
280
351
 
281
352
  module.exports = {
282
353
  OK, WARN, FAIL,
283
- dispatchedCommands, checkLink, checkFrozen, checkState, checkFleet, checkHooks, checkNotify, runChecks, render,
354
+ dispatchedCommands, checkSkills, checkLink, checkFrozen, checkState, checkFleet, checkHooks, checkNotify, runChecks, render,
284
355
  };