@futurelastic/colab-handbook 1.12.0-rc.66 → 1.12.0-rc.68

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
@@ -191,6 +191,22 @@ By hand, the same steps (full checklist:
191
191
 
192
192
  Pre-existing branches are **grandfathered**. Do not rename anything.
193
193
 
194
+ ## Customising a skill for your repo
195
+
196
+ Want a skill to behave differently in one repo — Issue comments in Japanese, an
197
+ extra check before wrap? Do not fork the skill: a fork stops receiving handbook
198
+ updates. Write the difference in `.colab/skills/<skill>.md` (for example
199
+ `.colab/skills/code-wrap.md`), in plain prose. Every skill reads that file
200
+ before its own steps, and what it says wins over the skill's text for that repo.
201
+ It never loosens a `colab` gate: a refused claim or merge stays refused.
202
+
203
+ Claude Code loads the file into the skill automatically. Other engines get a
204
+ plain sentence in each skill telling the agent to read the file, which works
205
+ without any engine support. Because the file instructs agents, a change to it
206
+ is never treated as docs-only: it merges on `auto-trunk` or a human's go, like a
207
+ `CLAUDE.md` change. Rule:
208
+ [`CONVENTIONS.md` §8, *Local policy*](CONVENTIONS.md#local-policy--a-repo-refines-a-skill-without-forking-it-520).
209
+
194
210
  ## Optional automation on top
195
211
 
196
212
  Nothing here assumes a dashboard, scheduler or bot exists. An adopter may still
package/README.vi.md CHANGED
@@ -189,6 +189,23 @@ Mấy flag của `colab adopt` nên biết:
189
189
 
190
190
  Nhánh có sẵn từ trước được **giữ nguyên** (grandfathered). Đừng đổi tên gì cả.
191
191
 
192
+ ## Tuỳ biến một skill cho repo của bạn
193
+
194
+ Muốn một skill chạy khác đi ở một repo — comment Issue bằng tiếng Nhật, thêm
195
+ một bước kiểm tra trước wrap? Đừng fork skill: bản fork không còn nhận cập nhật
196
+ từ handbook. Hãy viết phần khác biệt vào `.colab/skills/<skill>.md` (ví dụ
197
+ `.colab/skills/code-wrap.md`), bằng văn xuôi thường. Mỗi skill đọc file đó
198
+ trước các bước của chính nó, và nội dung file thắng phần chữ của skill trong
199
+ repo đó. Nó không bao giờ nới một cổng của `colab`: claim hay merge đã bị từ
200
+ chối thì vẫn bị từ chối.
201
+
202
+ Claude Code tự nạp file vào skill. Các engine khác có một câu thường trong mỗi
203
+ skill bảo agent đọc file, cách này chạy được mà không cần engine hỗ trợ gì.
204
+ Vì file này ra lệnh cho agent, thay đổi trong nó không bao giờ được coi là
205
+ docs-only: nó merge bằng `auto-trunk` hoặc khi có người duyệt, giống một thay đổi
206
+ `CLAUDE.md`. Quy tắc:
207
+ [`CONVENTIONS.md` §8, *Local policy*](CONVENTIONS.md#local-policy--a-repo-refines-a-skill-without-forking-it-520).
208
+
192
209
  ## Tự động hoá tùy chọn, đặt lên trên
193
210
 
194
211
  Không có gì ở đây giả định đã có dashboard, scheduler hay bot. Người adopt vẫn
package/package.json CHANGED
@@ -32,5 +32,5 @@
32
32
  "engines": {
33
33
  "node": ">=18"
34
34
  },
35
- "version": "1.12.0-rc.66"
35
+ "version": "1.12.0-rc.68"
36
36
  }
@@ -21,6 +21,13 @@ const DOCS_DIR = 'docs/';
21
21
  const NEVER_BASENAMES = Object.freeze(['CLAUDE.md', 'CLAUDE.local.md', 'AGENTS.md']);
22
22
  /** Config directories: nothing under them is documentation, at any depth. */
23
23
  const NEVER_DIRS = Object.freeze(['.claude', '.github', '.githooks']);
24
+ /**
25
+ * Agent-instruction directories named by more than one segment (#520): nothing under them is
26
+ * documentation, at any depth. `.colab/skills/<skill>.md` is a skill's local policy — text an agent
27
+ * loads and follows over the skill's own — so one `.md` there changes agent behaviour exactly as a
28
+ * `CLAUDE.md` does. Only this subtree: the rest of `.colab/` is judged by the ordinary rules.
29
+ */
30
+ const NEVER_SUBDIRS = Object.freeze(['.colab/skills']);
24
31
 
25
32
  const MODE_SYMLINK = '120000';
26
33
  const MODE_GITLINK = '160000';
@@ -35,6 +42,13 @@ function pathReason(p) {
35
42
  if (NEVER_BASENAMES.includes(base)) return `${base} is agent rules, not documentation`;
36
43
  const dir = segs.slice(0, -1).find((s) => NEVER_DIRS.includes(s));
37
44
  if (dir) return `under ${dir}/ (config)`;
45
+ const dirs = segs.slice(0, -1);
46
+ for (const sub of NEVER_SUBDIRS) {
47
+ const want = sub.split('/');
48
+ for (let i = 0; i + want.length <= dirs.length; i++) {
49
+ if (want.every((w, j) => dirs[i + j] === w)) return `under ${sub}/ (skill local policy — agent instructions)`;
50
+ }
51
+ }
38
52
  if (String(p).startsWith(DOCS_DIR)) return null;
39
53
  const dot = base.lastIndexOf('.');
40
54
  const ext = dot > 0 ? base.slice(dot) : '';
@@ -151,6 +165,6 @@ function directChanges(git, repo, trunk, since) {
151
165
  }
152
166
 
153
167
  module.exports = {
154
- DOC_EXTENSIONS, DOCS_DIR, NEVER_BASENAMES, NEVER_DIRS,
168
+ DOC_EXTENSIONS, DOCS_DIR, NEVER_BASENAMES, NEVER_DIRS, NEVER_SUBDIRS,
155
169
  pathReason, classify, parseRaw, parseBinary, branchChanges, directChanges,
156
170
  };