@futurelastic/colab-handbook 1.13.0-rc.12 → 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
@@ -20,9 +20,9 @@ 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>` (Claude
24
- Code; in Codex, `$code-start` — see [*Choose your engine*](#choose-your-engine)). With an
25
- 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
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
28
28
  packages often ship an older `gh`, so install it from [cli.github.com](https://cli.github.com).
@@ -95,19 +95,19 @@ with no agent and no other tool.
95
95
 
96
96
  ## Your first session
97
97
 
98
- A unit of work goes round one loop. Each step is a skill, invoked in an agent
99
- session as a slash command (`/code-start 42`), or followed by hand from
100
- [`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/).
101
101
 
102
102
  | Step | Skill | Who runs it | What it leaves behind |
103
103
  |---|---|---|---|
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 |
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 |
106
106
  | 3. Work | — | implementer | commits on the branch |
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 |
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 |
111
111
 
112
112
  Also in [`skills/`](skills/): `code-plan` (a full plan for a hard issue, run by
113
113
  `code-start` when flagged), `handbook-sync` (bring one repo up to the current
@@ -166,7 +166,7 @@ and why: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) and
166
166
 
167
167
  ## Adopting it into a repo
168
168
 
169
- **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.**
170
170
  It sees that nothing is adopted yet and drives adoption to the end — the
171
171
  descriptor (through `colab adopt`), the labels, the `CLAUDE.md` block, CI from
172
172
  the templates, and registration on this machine. Run later, the same skill
package/README.vi.md CHANGED
@@ -19,9 +19,9 @@ 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>` (Claude
23
- Code; trong Codex là `$code-start` — xem [*Chọn engine*](#chọn-engine)). Có agent
24
- 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
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ũ
27
27
  hơn, nên hãy cài từ [cli.github.com](https://cli.github.com).
@@ -94,19 +94,19 @@ khác.
94
94
 
95
95
  ## Phiên làm việc đầu tiên
96
96
 
97
- 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
98
- slash command (`/code-start 42`), hoặc tự làm theo bằng tay từ
99
- [`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/).
100
100
 
101
101
  | Bước | Skill | Ai chạy | Để lại gì |
102
102
  |---|---|---|---|
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 |
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 |
105
105
  | 3. Làm | — | thợ | commit trên nhánh |
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 |
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 |
110
110
 
111
111
  Cũng trong [`skills/`](skills/): `code-plan` (plan đầy đủ cho issue khó, do
112
112
  `code-start` gọi khi có cờ), `handbook-sync` (kéo một repo lên bản handbook mới
@@ -166,8 +166,8 @@ sao: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) và
166
166
 
167
167
  ## Adopt vào một repo
168
168
 
169
- **Đường mặc định: chạy `/handbook-sync` trong một phiên agent ngay trong repo
170
- đó.** 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
171
171
  `colab adopt`), label, block `CLAUDE.md`, CI từ template, và đăng ký trên máy
172
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
173
173
  nhất mà không làm mất phần bạn đã sửa.
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.13.0-rc.12"
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
  /**