@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.8
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/LICENSE +21 -0
- package/README.md +309 -3
- package/README.vi.md +279 -0
- package/audit/audit.mjs +3035 -0
- package/package.json +26 -5
- package/templates/README.md +257 -0
- package/templates/adr-README.md +57 -0
- package/templates/branch-name.yml +51 -0
- package/templates/ci-laravel.yml +540 -0
- package/templates/ci-node.yml +291 -0
- package/templates/ci-python.yml +281 -0
- package/templates/deploy-xserver.yml +531 -0
- package/templates/dist-refs.yml +177 -0
- package/templates/docs-lint.mjs +993 -0
- package/templates/docs-lint.yml +55 -0
- package/templates/gotchas-d-README.md +41 -0
- package/templates/identity-vocabulary.example +58 -0
- package/templates/npx-launcher.mjs +213 -0
- package/templates/pre-commit-dispatch +88 -0
- package/templates/pre-commit-identity +267 -0
- package/templates/pre-push-guard +117 -0
- package/templates/release-auto.yml +470 -0
- package/templates/release-tag.yml +245 -0
- package/templates/repo-CLAUDE-block.md +21 -0
- package/tools/colab +13746 -0
- package/tools/lib/adopt.js +882 -0
- package/tools/lib/axis-authority.js +96 -0
- package/tools/lib/base-ci-verdict.js +93 -0
- package/tools/lib/blocked-by.js +262 -0
- package/tools/lib/branch-name.js +137 -0
- package/tools/lib/checklist.js +143 -0
- package/tools/lib/ci-cure.js +512 -0
- package/tools/lib/ci-grant.js +307 -0
- package/tools/lib/ci-verdict.js +113 -0
- package/tools/lib/claim-comments.js +212 -0
- package/tools/lib/claim-identity.js +195 -0
- package/tools/lib/codeowners.js +208 -0
- package/tools/lib/consumer-evidence.js +74 -0
- package/tools/lib/container-close.js +141 -0
- package/tools/lib/cure-diff.js +267 -0
- package/tools/lib/decision-record.js +335 -0
- package/tools/lib/dirty-owner.js +150 -0
- package/tools/lib/disposition.js +378 -0
- package/tools/lib/docs-only.js +156 -0
- package/tools/lib/exposure-shape.js +207 -0
- package/tools/lib/gate.js +80 -0
- package/tools/lib/git.js +1059 -0
- package/tools/lib/group-labels.js +120 -0
- package/tools/lib/hermetic.js +193 -0
- package/tools/lib/identity.js +187 -0
- package/tools/lib/install-check.js +259 -0
- package/tools/lib/instruction-file.js +302 -0
- package/tools/lib/journal.js +430 -0
- package/tools/lib/labels.js +653 -0
- package/tools/lib/landed.js +230 -0
- package/tools/lib/local-adopt.js +133 -0
- package/tools/lib/lockfile-drift.js +119 -0
- package/tools/lib/machine-trailer.js +83 -0
- package/tools/lib/machine.js +238 -0
- package/tools/lib/migration-grant.js +641 -0
- package/tools/lib/migration-paths.js +135 -0
- package/tools/lib/notify.js +188 -0
- package/tools/lib/npm-publish-guard.js +242 -0
- package/tools/lib/orphan-worktree.js +127 -0
- package/tools/lib/owner-branch.js +182 -0
- package/tools/lib/place.js +782 -0
- package/tools/lib/ports.js +167 -0
- package/tools/lib/procs.js +185 -0
- package/tools/lib/readiness.js +240 -0
- package/tools/lib/records.js +185 -0
- package/tools/lib/refs-brake.js +95 -0
- package/tools/lib/release-cut.js +822 -0
- package/tools/lib/release-finalize.js +481 -0
- package/tools/lib/release-policy.js +358 -0
- package/tools/lib/release-tag.js +225 -0
- package/tools/lib/ship-batch.js +277 -0
- package/tools/lib/ship-roles.js +71 -0
- package/tools/lib/ship-target-sync.js +181 -0
- package/tools/lib/shipguard.js +317 -0
- package/tools/lib/shipped-branch.js +56 -0
- package/tools/lib/solo.js +213 -0
- package/tools/lib/squash.js +515 -0
- package/tools/lib/stale-base.js +70 -0
- package/tools/lib/stamp.js +703 -0
- package/tools/lib/state.js +262 -0
- package/tools/lib/teardown.js +83 -0
- package/tools/lib/trust-humans.js +104 -0
- package/tools/lib/util.js +98 -0
- package/tools/lib/wake.js +188 -0
- package/tools/lib/workflow-triggers.js +273 -0
- package/tools/lib/writes-authority.js +237 -0
- package/tools/lib/yaml.js +101 -0
- package/bin/cli.js +0 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 godx-jp
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,4 +1,310 @@
|
|
|
1
|
-
|
|
1
|
+
***English*** · [Tiếng Việt](README.vi.md)
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
# colab-handbook
|
|
4
|
+
|
|
5
|
+
A small set of conventions and tools for running many repos — many coding
|
|
6
|
+
sessions in parallel, humans and AI agents alike — without stepping on each
|
|
7
|
+
other.
|
|
8
|
+
|
|
9
|
+
**If you are an AI agent, stop here and read [`CLAUDE.md`](CLAUDE.md).**
|
|
10
|
+
This file is for humans.
|
|
11
|
+
|
|
12
|
+
*(The normative document — [`CONVENTIONS.md`](CONVENTIONS.md) — is written in
|
|
13
|
+
English so agents and tooling can read it. This is the English front door; the
|
|
14
|
+
Vietnamese one is [`README.vi.md`](README.vi.md). Both are only gateways, not
|
|
15
|
+
normative — when the two disagree, **both are wrong** until they agree with
|
|
16
|
+
`CONVENTIONS.md` again.)*
|
|
17
|
+
|
|
18
|
+
## What this is
|
|
19
|
+
|
|
20
|
+
A **handbook, not a framework**. It decides **outcomes** — where code merges,
|
|
21
|
+
what a release is, how you announce "I am working on this" — and deliberately
|
|
22
|
+
leaves the **implementation** (your Node version, your test runner, your CI
|
|
23
|
+
file) to each repo.
|
|
24
|
+
|
|
25
|
+
Everything here was distilled from running ~25 real repos, several of them
|
|
26
|
+
production apps maintained almost entirely by AI agents working in parallel
|
|
27
|
+
across many worktrees. The anti-pattern list is not theory: every entry is
|
|
28
|
+
something that actually happened, with the scar to prove it.
|
|
29
|
+
|
|
30
|
+
### The problem it solves
|
|
31
|
+
|
|
32
|
+
One person on one repo needs none of this. The conventions live in their head,
|
|
33
|
+
and their head is the only place they need to be.
|
|
34
|
+
|
|
35
|
+
That stops working somewhere around the third repo, and it collapses entirely
|
|
36
|
+
once sessions run **in parallel** — several at a time, on different machines,
|
|
37
|
+
some of them agents that will not think to ask. Then every unwritten assumption
|
|
38
|
+
becomes a way to lose work:
|
|
39
|
+
|
|
40
|
+
- two sessions claim the same issue, because neither could see the other had
|
|
41
|
+
started;
|
|
42
|
+
- a feature branch is left checked out on the working tree a dev server reads
|
|
43
|
+
from, and the live app quietly serves unmerged code;
|
|
44
|
+
- code merges and the issue stays open, so the next person re-does it;
|
|
45
|
+
- a repo's documentation describes a repo that no longer exists — which is worse
|
|
46
|
+
than no documentation, because someone will act on it.
|
|
47
|
+
|
|
48
|
+
None of those is a hard problem. They are all the *same* problem: **facts about
|
|
49
|
+
a repo that live in someone's memory instead of in the repo.**
|
|
50
|
+
|
|
51
|
+
### What it actually does
|
|
52
|
+
|
|
53
|
+
It makes each repo answer a handful of questions about itself, **once**, in a
|
|
54
|
+
file every session reads before touching anything — is there production today,
|
|
55
|
+
who else works here, what breaks if a merge is wrong, how many units of work run
|
|
56
|
+
at a time, how a commit reaches the thing that runs it.
|
|
57
|
+
|
|
58
|
+
Everything else follows from those answers: which branch to merge into, what a
|
|
59
|
+
release even means here, whether a branch is required at all, how much a session
|
|
60
|
+
must write down before it stops. A session never guesses, and two repos never
|
|
61
|
+
disagree about what a word means.
|
|
62
|
+
|
|
63
|
+
The rest of the repo exists to serve that: a CLI that performs the mechanical
|
|
64
|
+
parts, an audit that reports where reality has drifted from what a repo claims,
|
|
65
|
+
and portable session flows so a coding session opens and closes the same way
|
|
66
|
+
everywhere.
|
|
67
|
+
|
|
68
|
+
### What it is not
|
|
69
|
+
|
|
70
|
+
- **Not a service.** Nothing here is a dependency and nothing phones home. You
|
|
71
|
+
copy what is useful and own the copy — fork it, edit it, delete half of it.
|
|
72
|
+
That is what the licence is for.
|
|
73
|
+
- **Not a CI system, and not an opinion about your stack.** Bring your own
|
|
74
|
+
language, test runner and pipeline. The handbook only asks that the pipeline
|
|
75
|
+
produce two outcomes, and never says how.
|
|
76
|
+
- **Not an enforcement layer**, with one deliberate exception. Conformance is
|
|
77
|
+
advisory, because being wrong about a convention costs a conversation.
|
|
78
|
+
Publication blocks, because history cannot be recalled once anything is
|
|
79
|
+
cloned.
|
|
80
|
+
- **Not a maturity model.** No answer here ranks a repo above another. A repo
|
|
81
|
+
with no production is not a worse repo; it is a repo with fewer gates.
|
|
82
|
+
|
|
83
|
+
If you run one repo alone, read the anti-patterns and take what is useful. If
|
|
84
|
+
you run many — or you work alongside agents that never met the person who set
|
|
85
|
+
the rules — the whole thing is likely to pay for itself faster than it takes to
|
|
86
|
+
read.
|
|
87
|
+
|
|
88
|
+
## The questions
|
|
89
|
+
|
|
90
|
+
Adopting this means answering five questions about your repo, once, into
|
|
91
|
+
`.github/project.yml` — so no session has to guess, and no two repos disagree
|
|
92
|
+
on what a word means:
|
|
93
|
+
|
|
94
|
+
1. **Does a deploy target exist today** — and how is it reached: a tag gates
|
|
95
|
+
production, the promotion itself deploys, a human runs a runbook, or
|
|
96
|
+
nothing is live yet?
|
|
97
|
+
2. **Who else works here** — one person, a team, or the public?
|
|
98
|
+
3. **What would break if you merged something wrong here** — nothing, only
|
|
99
|
+
the people already in the room, users via the next promotion, or users and
|
|
100
|
+
adopters via a released artifact?
|
|
101
|
+
4. **One unit of work in flight at a time, or several at once?**
|
|
102
|
+
5. **By what path does a commit reach the thing that runs it** — a CI
|
|
103
|
+
workflow, a git hook, a documented procedure, a live checkout, a published
|
|
104
|
+
artifact, another system's data, or none of those yet?
|
|
105
|
+
|
|
106
|
+
The answers decide everything that follows: which branch a session merges
|
|
107
|
+
into, what a release is, how much an Issue narrates, what must exist before a
|
|
108
|
+
merge can be undone, whether a branch is even required. Nothing here is asked
|
|
109
|
+
twice, and nothing is asked that the repo already states for itself — its
|
|
110
|
+
default branch, its toolchain, its ports.
|
|
111
|
+
|
|
112
|
+
Issues are **claimed** with an assignee plus the `in-progress` label before
|
|
113
|
+
work starts, so parallel sessions never collide on the same task.
|
|
114
|
+
|
|
115
|
+
The full rules — what each answer resolves to, and why:
|
|
116
|
+
[`CONVENTIONS.md`](CONVENTIONS.md). ~15 minutes to read, and the **single
|
|
117
|
+
normative file** — everything else in the repo serves it.
|
|
118
|
+
|
|
119
|
+
## Repo layout
|
|
120
|
+
|
|
121
|
+
| Path | What it is |
|
|
122
|
+
|---|---|
|
|
123
|
+
| [`CONVENTIONS.md`](CONVENTIONS.md) | The rules. Normative, the single source of truth (EN). |
|
|
124
|
+
| [`CLAUDE.md`](CLAUDE.md) | The entry point for AI agents — the operational distillation (EN). |
|
|
125
|
+
| [`project.schema.md`](project.schema.md) | Field reference for `.github/project.yml`. |
|
|
126
|
+
| [`templates/`](templates/) | **Copy-and-own** starting points: CI, release, git hooks (a secret scan and an identity scan), and the `CLAUDE.md` block for adopting repos. **Nothing is called remotely** — copy it, edit it, own it. Templates, not scaffolding, because scaffolding only reaches repos created after it shipped. |
|
|
127
|
+
| [`tools/`](tools/) | `colab` — a small CLI (optional): adopt a repo, claim issues, allocate ports, manage worktrees, and merge a finished branch to trunk when the repo grants it. JSON state, zero dependencies. Full command reference: [`tools/README.md`](tools/README.md). |
|
|
128
|
+
| [`audit/`](audit/) | An external conformance checker. Reads all your repos — every owner, including local-only ones — and reports drift in a single run. Advisory only, never blocking. `--identity` additionally scans public repository descriptions and topics, which no git hook can see. What each check means: [`audit/README.md`](audit/README.md). |
|
|
129
|
+
| [`skills/`](skills/) | Portable session flow: `code-triage` (pick the next task, flagging hard ones for a plan) → `code-start` (open a session; runs `code-plan` when flagged) → `code-wrap` (distill + gate + hand off) → `code-ship` (grade + merge, human-authorized), plus `code-sweep` (clear out everything ALREADY DONE in one repo — or just a named set of issues or one session — running `code-wrap`+`code-ship` on each) `handbook-sync` (bring ONE repo up to the latest handbook, run from inside it), and `release-rung` (the manual fallback and explainer for the release workflow, which is the driver: walk one repo's release rung from a coordinator session — candidate, test period, `release-hold` veto, final — through `colab release cut`/`finalize`, never by hand), and `migration-review` (for whoever a repo binds to the migration-reviewer role: review a branch's migrations against the deploy engine and end in one verdict — GRANT with a review record, REWORK with a brief, or ESCALATE to a human — with a blind test set to run before binding a new reviewer). Installed as Claude Code skills by [`install.sh`](install.sh) — see *Setting up a machine* below. |
|
|
130
|
+
| [`install.sh`](install.sh) | Sets up **your machine**: skills, the `colab` CLI, the pre-commit hook, the fleet list. Idempotent, and `--dry` shows you everything first. |
|
|
131
|
+
|
|
132
|
+
## Install the CLI from npm
|
|
133
|
+
|
|
134
|
+
The `colab` CLI is also published as a public npm package, **`@futurelastic/colab-handbook`**. The command you type stays `colab`.
|
|
135
|
+
|
|
136
|
+
```sh
|
|
137
|
+
npx @futurelastic/colab-handbook <command> # one-off, nothing installed, no npm account needed
|
|
138
|
+
npm i -g @futurelastic/colab-handbook # then: colab <command>
|
|
139
|
+
npm i -g @futurelastic/colab-handbook@next # release candidates (vX.Y.Z-rc.N) instead of finals
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
The package carries what `colab` reads at runtime — the CLI, its `lib/`, `templates/` and `audit/audit.mjs` — and nothing else; `colab template` and `colab adopt` work from the registry copy and stamp the package's own version. The skills are **not** in it: they install with `./install.sh` from a clone (below), because they must symlink into `~/.claude/skills/`. Every tarball is checked file by file against an allowlist in CI (`scripts/check-pack-allowlist.mjs`).
|
|
143
|
+
|
|
144
|
+
## Setting up a machine
|
|
145
|
+
|
|
146
|
+
Once per machine, before you adopt anything into a repo.
|
|
147
|
+
|
|
148
|
+
**You need:** `git`; `node` ≥ 18 (`.nvmrc` pins 22, which is what CI here runs);
|
|
149
|
+
`gh` **logged in** (`gh auth login`) — claims, the skills and the audit's remote
|
|
150
|
+
targets are all useless without it, and the failure surfaces much later as
|
|
151
|
+
something confusing; and `gitleaks` only if you want the pre-commit hook.
|
|
152
|
+
`install.sh` checks every one of these and reports what is missing before it
|
|
153
|
+
changes anything.
|
|
154
|
+
|
|
155
|
+
**1. Clone it somewhere permanent** — with the rest of your code, not in a
|
|
156
|
+
scratch directory.
|
|
157
|
+
|
|
158
|
+
```sh
|
|
159
|
+
git clone https://github.com/futurelastic/colab-handbook.git ~/code/colab-handbook
|
|
160
|
+
cd ~/code/colab-handbook
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
**This clone is infrastructure, not a download.** The skills install as symlinks
|
|
164
|
+
*into this working tree*: delete the clone and every session on the machine
|
|
165
|
+
loses them, and whichever branch it has checked out is the version of the skills
|
|
166
|
+
every session gets. So keep it on `main` unless you are actively working on the
|
|
167
|
+
handbook itself. `install.sh` warns if it finds itself under `/tmp`,
|
|
168
|
+
`~/Downloads` or `~/Desktop`.
|
|
169
|
+
|
|
170
|
+
**2. Install.**
|
|
171
|
+
|
|
172
|
+
```sh
|
|
173
|
+
./install.sh --all --dry # see exactly what would happen; changes nothing
|
|
174
|
+
./install.sh --all # skills + colab CLI + pre-commit hook + fleet list
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
`--all` is the recommended first run. Everything it does is a symlink or a copy,
|
|
178
|
+
it is idempotent, and it never overwrites anything it did not create — your own
|
|
179
|
+
skill, or an existing `~/.colab/repos.txt`, is left alone with a warning. Bare
|
|
180
|
+
`./install.sh` installs the skills and nothing else, if that is genuinely all
|
|
181
|
+
you want.
|
|
182
|
+
|
|
183
|
+
| Flag | What it does |
|
|
184
|
+
|---|---|
|
|
185
|
+
| *(none)* | Symlink `skills/` into `~/.claude/skills/`, so they are available in every repo you open. |
|
|
186
|
+
| `--tools` | Two installs of one CLI: a **symlink** at `~/.local/bin/colab` for your sessions (checking that directory is really on your `PATH`, and printing the exact line to add if not), plus a stamped **frozen copy** at `~/.colab/bin/colab` for always-on services — see below. |
|
|
187
|
+
| `--hooks` | Point this clone's git at `.githooks/`, whose `pre-commit` runs every check in `pre-commit.d/` — a gitleaks secret scan, and an identity scan that needs a vocabulary you supply by path and keep outside every repo (see [`templates/README.md`](templates/README.md)). `core.hooksPath` lives in `.git/config`, so it is per-clone, per-machine, and never travels with the repo. |
|
|
188
|
+
| `--fleet` | Seed `~/.colab/repos.txt` from `audit/repos.txt`, only if it is absent. The seed is format notes and commented placeholders — it registers **nothing**; `colab register <path>` (step 3) is what fills it. That list stays machine-local on purpose: it names your private repos, and this repo is public. |
|
|
189
|
+
| `--all` | `--tools --hooks --fleet`. |
|
|
190
|
+
| `--dry` | Print what would happen, change nothing. Combines with all of the above. |
|
|
191
|
+
| `--check` | **Read-only** health report on what an earlier install left behind — see *Checking an install* below. Takes no other flag; exit 1 on any ✗ row. |
|
|
192
|
+
|
|
193
|
+
`--tools` also creates an **empty** `~/.colab/state.json` when there is none (it never
|
|
194
|
+
touches an existing one). Without that, the file appeared only on the first
|
|
195
|
+
state-changing `colab` command, and anything reading it on a fresh machine got an
|
|
196
|
+
error where it should have seen an empty fleet.
|
|
197
|
+
|
|
198
|
+
**Always-on services must call `~/.colab/bin/colab`.** The symlinked CLI follows
|
|
199
|
+
whatever branch this clone has checked out — deliberate for a human session, and
|
|
200
|
+
wrong for anything that outlives one. A daemon, a launch agent or a headless
|
|
201
|
+
runner started months ago would silently change behaviour because somebody
|
|
202
|
+
checked out an unrelated branch, and nothing would report it: the process keeps
|
|
203
|
+
working, differently. So `--tools` also writes a **copy** to `~/.colab/bin/`
|
|
204
|
+
(honouring `COLAB_HOME`), stamped with the handbook version it was taken from —
|
|
205
|
+
or, when that tree sits ahead of the last tag, with the commit it was taken from
|
|
206
|
+
(`v1.7.0-2-gc8436c6`) and a warning, because no released version describes those
|
|
207
|
+
bytes. That copy never moves on its own.
|
|
208
|
+
|
|
209
|
+
Refreshing it is therefore an act, never a side effect: re-run `./install.sh
|
|
210
|
+
--tools`. `colab update` tells you when it is due. **`behind` means a released
|
|
211
|
+
CLI change exists that this machine lacks** — the comparison runs to the latest
|
|
212
|
+
tag, so a release that changed no CLI code does not nag you, and unreleased work
|
|
213
|
+
in your own checkout does not either. (That last part is why the bound is the tag
|
|
214
|
+
rather than `HEAD`: measuring to `HEAD` marked every machine stale for the whole
|
|
215
|
+
window between a CLI commit and the next tag, and the advertised remedy copies
|
|
216
|
+
*from* that same working tree — so on a machine developing the handbook it
|
|
217
|
+
advised services to adopt untagged code.) It never rewrites the copy, not even
|
|
218
|
+
with `--apply`: that is the toolchain your running services are executing.
|
|
219
|
+
`colab --version` says which of the two you are talking to. The frozen copy carries
|
|
220
|
+
`tools/` only, so `colab template` refuses there — run it from the working tree.
|
|
221
|
+
|
|
222
|
+
**3. Verify, and register your repos.**
|
|
223
|
+
|
|
224
|
+
```sh
|
|
225
|
+
colab --help # not found? fix your PATH — step 2 prints the exact line
|
|
226
|
+
colab --version # which colab is this: the working tree, or the frozen copy?
|
|
227
|
+
colab register /path/to/repo # once per repo — writes repos.txt AND config.json, so they agree
|
|
228
|
+
node audit/audit.mjs # a conformance report across the whole fleet
|
|
229
|
+
colab update # stamped copies that fell behind — the frozen CLI included
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
`colab register` is the way in; hand-editing `~/.colab/repos.txt` still works for
|
|
233
|
+
the audit, but leaves `config.json` — where the CLI reserves each repo's ports —
|
|
234
|
+
unaware of the repo. A remote-only audit target (`owner/name`, nothing cloned) is
|
|
235
|
+
the one entry you add to `repos.txt` by hand. A repo not yet adopted then needs
|
|
236
|
+
`colab adopt` and `colab labels --ensure` — see *Adopting it into a repo* below.
|
|
237
|
+
|
|
238
|
+
### Checking an install
|
|
239
|
+
|
|
240
|
+
```sh
|
|
241
|
+
./install.sh --check # read-only; exit 1 on any ✗ row
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
A frozen copy never breaks — it gets **old**, and an old complete copy answers
|
|
245
|
+
normally for every command it knows until something asks for one added after it
|
|
246
|
+
was frozen. `--check` is the report nothing else gives: whether the frozen copy is
|
|
247
|
+
behind the latest release, **which commands it does not dispatch**, whether the
|
|
248
|
+
state file exists, whether anything is registered, and whether both pre-commit
|
|
249
|
+
hooklets can actually run (gitleaks, and the identity vocabulary). ✗ means
|
|
250
|
+
something installed here is stale or unusable; ⚠ means something was never set
|
|
251
|
+
up, which may be deliberate. It never refreshes anything — re-freezing stays your
|
|
252
|
+
call: `./install.sh --tools`.
|
|
253
|
+
|
|
254
|
+
Then read [`CONVENTIONS.md`](CONVENTIONS.md): ~15 minutes, and the only
|
|
255
|
+
normative file here.
|
|
256
|
+
|
|
257
|
+
## Adopting it into a repo
|
|
258
|
+
|
|
259
|
+
The short version — the full checklist is
|
|
260
|
+
[`CONVENTIONS.md` §9](CONVENTIONS.md#9-adopting-this):
|
|
261
|
+
|
|
262
|
+
1. Answer question 1 honestly (is there production **today**, not "soon").
|
|
263
|
+
2. Add `.github/project.yml`. `colab adopt` asks the five questions and writes
|
|
264
|
+
the file for you — it stops at the descriptor and prints the rest of this
|
|
265
|
+
list, because the remaining steps are not its to take.
|
|
266
|
+
3. `colab labels --ensure` — the convention labels do not exist by default, and
|
|
267
|
+
there are more than one. A check whose label was never created can never
|
|
268
|
+
fire.
|
|
269
|
+
4. Paste [`templates/repo-CLAUDE-block.md`](templates/repo-CLAUDE-block.md)
|
|
270
|
+
into the repo's `CLAUDE.md` — this is the only way agents discover these
|
|
271
|
+
conventions.
|
|
272
|
+
5. Make sure CI produces the two required outcomes: a secret scan and a build,
|
|
273
|
+
with toolchain versions **resolved from the repo's own manifest** — never
|
|
274
|
+
hardcoded. Copy a template if it helps.
|
|
275
|
+
|
|
276
|
+
Pre-existing branches are **grandfathered**. Do not rename anything.
|
|
277
|
+
|
|
278
|
+
**Working in a repo you don't own?** If committing these files there is not an option,
|
|
279
|
+
`colab adopt --local` keeps everything in your local clone instead, and nothing lands in
|
|
280
|
+
the owner's history — see
|
|
281
|
+
[*Working in a repo you don't own*](CONVENTIONS.md#working-in-a-repo-you-dont-own).
|
|
282
|
+
|
|
283
|
+
## Why so little enforcement
|
|
284
|
+
|
|
285
|
+
Our private repos sit on a GitHub plan without branch protection — pushes to
|
|
286
|
+
`main` cannot be forbidden. So this handbook does not pretend to enforce; it
|
|
287
|
+
makes **compliance cheap and checking cheap**. The audit tool reports drift; the
|
|
288
|
+
conventions explain *why* each rule exists, so you can judge for yourself when
|
|
289
|
+
breaking one is worth it. When you do break one, fix the documentation in the
|
|
290
|
+
same PR — a document describing a repo that does not exist is the worst thing in
|
|
291
|
+
this business.
|
|
292
|
+
|
|
293
|
+
**Two things do block, and the line between them is deliberate.** The git hooks
|
|
294
|
+
refuse: a secret scan, and an identity scan that stops a hostname, a home path
|
|
295
|
+
or a customer's name reaching a public repo. Those guard **publication**, which
|
|
296
|
+
is the one mistake that cannot be undone — history cannot be recalled once
|
|
297
|
+
anything is cloned. Everything about *conformance* stays advisory, because being
|
|
298
|
+
wrong about a convention costs a conversation, and being wrong about publication
|
|
299
|
+
costs forever.
|
|
300
|
+
|
|
301
|
+
## License
|
|
302
|
+
|
|
303
|
+
[MIT License](LICENSE). Copy what is useful — that is what this repo is
|
|
304
|
+
for. The licence is the legal half of "copy-and-own": you may use, modify and
|
|
305
|
+
redistribute anything here, including in closed-source work, provided you keep
|
|
306
|
+
the notice. It also carries an express patent grant, and reserves the project's
|
|
307
|
+
trademarks.
|
|
308
|
+
|
|
309
|
+
Adopting a convention costs you nothing and grants us nothing. Nothing here
|
|
310
|
+
phones home, and there is no obligation to contribute anything back.
|
package/README.vi.md
ADDED
|
@@ -0,0 +1,279 @@
|
|
|
1
|
+
[English](README.md) · ***Tiếng Việt***
|
|
2
|
+
|
|
3
|
+
# colab-handbook
|
|
4
|
+
|
|
5
|
+
Bộ quy ước và công cụ nhỏ để vận hành nhiều repo — nhiều phiên code song song,
|
|
6
|
+
người thật lẫn AI agent — mà không giẫm chân nhau.
|
|
7
|
+
|
|
8
|
+
**Nếu bạn là AI agent, dừng ở đây và đọc [`CLAUDE.md`](CLAUDE.md).**
|
|
9
|
+
File này dành cho con người.
|
|
10
|
+
|
|
11
|
+
*(Tài liệu chuẩn tắc — [`CONVENTIONS.md`](CONVENTIONS.md) — viết bằng tiếng Anh
|
|
12
|
+
để agent và tool đọc được. Bản này là cửa vào tiếng Việt cho anh em dev; bản
|
|
13
|
+
tiếng Anh nằm ở [`README.md`](README.md). Cả hai chỉ là cửa vào, không phải
|
|
14
|
+
tài liệu chuẩn tắc — khi hai bản nói khác nhau thì **cả hai đều sai** cho tới
|
|
15
|
+
khi khớp lại với `CONVENTIONS.md`.)*
|
|
16
|
+
|
|
17
|
+
## Đây là cái gì
|
|
18
|
+
|
|
19
|
+
Một cuốn **handbook, không phải framework**. Nó quyết định **kết quả** — code
|
|
20
|
+
merge vào đâu, release là gì, báo "tôi đang làm việc này" bằng cách nào — và cố
|
|
21
|
+
tình để **cách hiện thực** (phiên bản Node, test runner, file CI của bạn) cho
|
|
22
|
+
từng repo tự quyết.
|
|
23
|
+
|
|
24
|
+
Mọi thứ trong đây được chưng cất từ việc vận hành ~25 repo thật, trong đó có
|
|
25
|
+
nhiều app production được bảo trì gần như hoàn toàn bởi AI agent chạy song song
|
|
26
|
+
trên nhiều worktree. Mục anti-pattern không phải lý thuyết: từng mục là chuyện
|
|
27
|
+
đã xảy ra thật, kèm sẹo để chứng minh.
|
|
28
|
+
|
|
29
|
+
### Nó giải quyết vấn đề gì
|
|
30
|
+
|
|
31
|
+
Một người, một repo thì chẳng cần gì trong đây cả. Quy ước nằm trong đầu người
|
|
32
|
+
đó, và trong đầu là chỗ duy nhất nó cần nằm.
|
|
33
|
+
|
|
34
|
+
Cách đó hết hiệu lực đâu đó quanh cái repo thứ ba, và sụp hẳn khi các phiên bắt
|
|
35
|
+
đầu chạy **song song** — vài phiên một lúc, trên nhiều máy khác nhau, có những
|
|
36
|
+
phiên là agent và chúng sẽ không nghĩ ra chuyện phải hỏi. Lúc đó mọi giả định
|
|
37
|
+
không viết ra đều thành một cách để mất việc:
|
|
38
|
+
|
|
39
|
+
- hai phiên cùng claim một issue, vì chẳng bên nào thấy được bên kia đã bắt đầu;
|
|
40
|
+
- một nhánh feature bị bỏ quên trên chính working tree mà dev server đang đọc,
|
|
41
|
+
thế là app đang chạy lặng lẽ phục vụ code chưa merge;
|
|
42
|
+
- code đã merge mà issue vẫn mở, nên người sau làm lại từ đầu;
|
|
43
|
+
- tài liệu của một repo mô tả một repo không còn tồn tại — thứ này tệ hơn là
|
|
44
|
+
không có tài liệu, vì kiểu gì cũng có người tin theo mà làm.
|
|
45
|
+
|
|
46
|
+
Không cái nào trong đó là vấn đề khó. Chúng đều là **cùng một** vấn đề: **những
|
|
47
|
+
sự thật về một repo lại nằm trong trí nhớ của ai đó thay vì nằm trong repo.**
|
|
48
|
+
|
|
49
|
+
### Thực chất nó làm gì
|
|
50
|
+
|
|
51
|
+
Nó bắt mỗi repo tự trả lời một nhúm câu hỏi về chính mình, **một lần**, vào một
|
|
52
|
+
file mà mọi phiên đều đọc trước khi động vào bất cứ thứ gì — hôm nay đã có
|
|
53
|
+
production chưa, còn ai khác làm ở đây, merge sai thì hỏng cái gì, mỗi lúc chạy
|
|
54
|
+
bao nhiêu đầu việc, và code đi tới chỗ nó chạy bằng đường nào.
|
|
55
|
+
|
|
56
|
+
Mọi thứ còn lại suy ra từ mấy câu trả lời đó: merge vào nhánh nào, ở repo này
|
|
57
|
+
release nghĩa là gì, có bắt buộc phải có nhánh không, một phiên phải ghi lại
|
|
58
|
+
bao nhiêu trước khi dừng. Phiên làm việc không phải đoán, và hai repo không bao
|
|
59
|
+
giờ hiểu khác nhau về cùng một từ.
|
|
60
|
+
|
|
61
|
+
Phần còn lại của repo sinh ra để phục vụ điều đó: một CLI làm giúp phần cơ học,
|
|
62
|
+
một audit báo chỗ nào thực tế đã trôi khỏi thứ repo tự khai, và các luồng phiên
|
|
63
|
+
làm việc mang đi được để phiên code ở đâu cũng mở ra và đóng lại giống nhau.
|
|
64
|
+
|
|
65
|
+
### Nó không phải cái gì
|
|
66
|
+
|
|
67
|
+
- **Không phải một service.** Không có gì ở đây là dependency và không có gì gửi
|
|
68
|
+
dữ liệu về. Bạn copy cái nào thấy dùng được rồi sở hữu bản copy đó — fork,
|
|
69
|
+
sửa, xoá bớt nửa cũng được. Giấy phép sinh ra để làm việc đó.
|
|
70
|
+
- **Không phải hệ thống CI, cũng không có ý kiến gì về stack của bạn.** Ngôn
|
|
71
|
+
ngữ, test runner, pipeline — của bạn cả. Handbook chỉ yêu cầu pipeline cho ra
|
|
72
|
+
hai kết quả, và không bao giờ nói phải làm bằng cách nào.
|
|
73
|
+
- **Không phải lớp ép buộc**, trừ đúng một ngoại lệ cố ý. Chuyện tuân thủ chỉ là
|
|
74
|
+
cảnh báo, vì sai một quy ước thì tốn một cuộc trao đổi. Chuyện phát hành ra
|
|
75
|
+
ngoài thì chặn, vì history không thu hồi lại được một khi đã có người clone.
|
|
76
|
+
- **Không phải thang đo độ trưởng thành.** Không câu trả lời nào ở đây xếp repo
|
|
77
|
+
này trên repo kia. Một repo chưa có production không phải repo tệ hơn; nó là
|
|
78
|
+
repo có ít cổng hơn.
|
|
79
|
+
|
|
80
|
+
Nếu bạn làm một repo một mình, đọc mục anti-pattern rồi lấy cái nào thấy dùng
|
|
81
|
+
được. Còn nếu bạn chạy nhiều repo — hoặc bạn làm việc cùng những agent chưa
|
|
82
|
+
từng gặp người đặt ra luật — thì nhiều khả năng nó hoàn vốn nhanh hơn cả thời
|
|
83
|
+
gian bạn bỏ ra để đọc.
|
|
84
|
+
|
|
85
|
+
## Năm câu hỏi
|
|
86
|
+
|
|
87
|
+
Adopt handbook này nghĩa là trả lời năm câu hỏi về repo của bạn, một lần, ghi
|
|
88
|
+
vào `.github/project.yml` — để không phiên nào phải đoán, và không hai repo
|
|
89
|
+
nào hiểu khác nhau về cùng một từ:
|
|
90
|
+
|
|
91
|
+
1. **Hôm nay đã có đích deploy chưa** — và đến đó bằng đường nào: một tag gác
|
|
92
|
+
cổng production, chính cú promote là deploy, một người chạy runbook bằng
|
|
93
|
+
tay, hay chưa có gì sống cả?
|
|
94
|
+
2. **Còn ai khác làm ở repo này** — một mình, một team, hay có cả người
|
|
95
|
+
ngoài?
|
|
96
|
+
3. **Merge nhầm thì cái gì hỏng** — không gì cả, chỉ những người đang có mặt
|
|
97
|
+
ở đây, người dùng qua lần promote kế tiếp, hay người dùng/người adopt qua
|
|
98
|
+
một artifact đã phát hành?
|
|
99
|
+
4. **Một việc tại một thời điểm, hay nhiều việc chạy song song?**
|
|
100
|
+
5. **Code đi tới chỗ nó chạy bằng đường nào** — một workflow CI, một git
|
|
101
|
+
hook, một quy trình tay có ghi lại, một checkout đang sống sẵn, một
|
|
102
|
+
artifact phát hành, dữ liệu của hệ thống khác, hay chưa có đường nào cả?
|
|
103
|
+
|
|
104
|
+
Trả lời xong năm câu này là quyết định luôn mọi thứ còn lại: merge vào nhánh
|
|
105
|
+
nào, release nghĩa là gì, Issue tường thuật nhiều hay ít, cần gì để undo một
|
|
106
|
+
merge, có bắt buộc phải có branch hay không. Không câu nào bị hỏi hai lần, và
|
|
107
|
+
không câu nào hỏi cái mà repo đã tự nói sẵn rồi — nhánh mặc định, toolchain,
|
|
108
|
+
port của nó.
|
|
109
|
+
|
|
110
|
+
Issue được **claim** bằng assignee + label `in-progress` trước khi bắt tay vào
|
|
111
|
+
làm, nên các phiên song song không bao giờ đụng nhau trên cùng một việc.
|
|
112
|
+
|
|
113
|
+
Toàn bộ luật — mỗi câu trả lời quy về đâu, và vì sao:
|
|
114
|
+
[`CONVENTIONS.md`](CONVENTIONS.md). Đọc mất ~15 phút và là file **chuẩn tắc
|
|
115
|
+
duy nhất** — mọi thứ còn lại trong repo chỉ phục vụ nó.
|
|
116
|
+
|
|
117
|
+
## Cấu trúc repo
|
|
118
|
+
|
|
119
|
+
| Đường dẫn | Là gì |
|
|
120
|
+
|---|---|
|
|
121
|
+
| [`CONVENTIONS.md`](CONVENTIONS.md) | Luật. Chuẩn tắc, nguồn sự thật duy nhất (EN). |
|
|
122
|
+
| [`CLAUDE.md`](CLAUDE.md) | Cửa vào cho AI agent — bản chưng cất vận hành (EN). |
|
|
123
|
+
| [`project.schema.md`](project.schema.md) | Tham chiếu field của `.github/project.yml`. |
|
|
124
|
+
| [`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. Là template chứ không phải scaffold, vì scaffold chỉ tới được những repo tạo ra sau khi nó ra đời. |
|
|
125
|
+
| [`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 đầy đủ các lệnh: [`tools/README.md`](tools/README.md). |
|
|
126
|
+
| [`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, không bao giờ chặn. 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). |
|
|
127
|
+
| [`skills/`](skills/) | Flow phiên làm việc portable: `code-triage` (chọn việc tiếp theo, gắn cờ việc khó cần plan) → `code-start` (mở phiên; chạy `code-plan` khi có cờ) → `code-wrap` (chưng cất + gate + bàn giao) → `code-ship` (chấm điểm + merge, cần người xác nhận), cộng `code-sweep` (dọn sạch mọi việc ĐÃ XONG trong một repo — hoặc chỉ một nhóm issue hay một phiên được chỉ định — chạy `code-wrap`+`code-ship` từng cái) `handbook-sync` (kéo MỘT repo lên bản handbook mới nhất, chạy từ trong repo đó), và `release-rung` (đường dự phòng thủ công và phần giải thích cho release workflow — workflow mới là thứ tự chạy: đi hết nấc release của một repo từ phiên điều phối — candidate, thời gian thử, quyền phủ quyết `release-hold`, bản final — qua `colab release cut`/`finalize`, không bao giờ tag tay), và `migration-review` (cho người/agent mà repo gán vai migration-reviewer: review migration của một nhánh theo engine deploy thật và chốt đúng một verdict — GRANT kèm review record, REWORK kèm brief sửa, hoặc ESCALATE lên người — kèm bộ test mù phải chạy trước khi gán reviewer mới). [`install.sh`](install.sh) cài chúng thành skill Claude Code — xem mục *Cài đặt máy* ngay dưới. |
|
|
128
|
+
| [`install.sh`](install.sh) | Cài đặt cho **máy của bạn**: skills, CLI `colab`, hook pre-commit, danh sách repo cho audit. Idempotent, và `--dry` cho xem trước mọi thứ. |
|
|
129
|
+
|
|
130
|
+
## Cài CLI từ npm
|
|
131
|
+
|
|
132
|
+
CLI `colab` còn được phát hành dạng package npm công khai **`@futurelastic/colab-handbook`**. Lệnh bạn gõ vẫn là `colab`.
|
|
133
|
+
|
|
134
|
+
```sh
|
|
135
|
+
npx @futurelastic/colab-handbook <lệnh> # chạy một lần, không cài gì, không cần tài khoản npm
|
|
136
|
+
npm i -g @futurelastic/colab-handbook # rồi: colab <lệnh>
|
|
137
|
+
npm i -g @futurelastic/colab-handbook@next # bản ứng viên (vX.Y.Z-rc.N) thay vì bản final
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Package chỉ chứa những gì `colab` đọc lúc chạy — CLI, `lib/`, `templates/` và `audit/audit.mjs` — không gì khác; `colab template` và `colab adopt` chạy được từ bản trên registry và đóng dấu đúng version của package. Các skill **không** nằm trong đó: chúng cài bằng `./install.sh` từ một bản clone (xem bên dưới), vì phải symlink vào `~/.claude/skills/`. Mỗi tarball được CI đối chiếu từng file với allowlist (`scripts/check-pack-allowlist.mjs`).
|
|
141
|
+
|
|
142
|
+
## Cài đặt máy
|
|
143
|
+
|
|
144
|
+
Làm một lần cho mỗi máy, trước khi adopt handbook vào repo nào.
|
|
145
|
+
|
|
146
|
+
**Cần có sẵn:** `git`; `node` ≥ 18 (`.nvmrc` ghim 22 — đúng bản CI ở đây chạy);
|
|
147
|
+
`gh` và phải **đăng nhập rồi** (`gh auth login`) — claim issue, các skill và
|
|
148
|
+
phần audit repo remote đều vô dụng nếu thiếu, mà lỗi thì mãi về sau mới hiện ra
|
|
149
|
+
dưới dạng khó hiểu; `gitleaks` chỉ cần nếu bạn muốn bật hook pre-commit.
|
|
150
|
+
`install.sh` kiểm tra hết những thứ này và báo cái nào thiếu *trước khi* đụng
|
|
151
|
+
vào bất cứ gì.
|
|
152
|
+
|
|
153
|
+
**1. Clone vào chỗ ở lâu dài** — để chung với đống code của bạn, đừng để trong
|
|
154
|
+
thư mục tạm.
|
|
155
|
+
|
|
156
|
+
```sh
|
|
157
|
+
git clone https://github.com/futurelastic/colab-handbook.git ~/code/colab-handbook
|
|
158
|
+
cd ~/code/colab-handbook
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
**Bản clone này là hạ tầng, không phải file tải về xem cho biết.** Các skill
|
|
162
|
+
được cài bằng symlink trỏ *thẳng vào working tree này*: xoá clone đi là mọi
|
|
163
|
+
phiên trên máy mất skill, và repo đang checkout nhánh nào thì mọi phiên dùng
|
|
164
|
+
đúng bản skill của nhánh đó. Nên khi không trực tiếp sửa handbook, hãy để nó ở
|
|
165
|
+
`main`. `install.sh` sẽ cảnh báo nếu thấy mình đang nằm trong `/tmp`,
|
|
166
|
+
`~/Downloads` hay `~/Desktop`.
|
|
167
|
+
|
|
168
|
+
**2. Cài.**
|
|
169
|
+
|
|
170
|
+
```sh
|
|
171
|
+
./install.sh --all --dry # xem trước sẽ làm gì; không thay đổi gì cả
|
|
172
|
+
./install.sh --all # skills + CLI colab + hook pre-commit + danh sách repo
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
`--all` là lựa chọn nên dùng cho lần chạy đầu. Mọi thứ nó làm đều là symlink
|
|
176
|
+
hoặc copy, chạy lại bao nhiêu lần cũng được, và không bao giờ ghi đè thứ nó
|
|
177
|
+
không tạo ra — skill của riêng bạn, hay `~/.colab/repos.txt` đã có sẵn, đều được
|
|
178
|
+
giữ nguyên kèm một dòng cảnh báo. Chạy trơn `./install.sh` thì chỉ cài skills,
|
|
179
|
+
nếu bạn thật sự chỉ cần bấy nhiêu.
|
|
180
|
+
|
|
181
|
+
| Flag | Làm gì |
|
|
182
|
+
|---|---|
|
|
183
|
+
| *(không có)* | Symlink `skills/` vào `~/.claude/skills/`, để mở repo nào cũng có. |
|
|
184
|
+
| `--tools` | Cài một CLI theo hai cách: một **symlink** ở `~/.local/bin/colab` cho các phiên làm việc của bạn (có kiểm tra thư mục đó thật sự nằm trong `PATH` không, thiếu thì in ra đúng dòng cần thêm), cộng một **bản đóng băng** có đóng dấu ở `~/.colab/bin/colab` cho các service luôn-bật — xem ngay dưới. |
|
|
185
|
+
| `--hooks` | Trỏ git của clone này vào `.githooks/`, ở đó `pre-commit` chạy lần lượt mọi check trong `pre-commit.d/` — quét secret bằng gitleaks, và quét danh tính (identity) vốn cần một danh sách từ khoá do bạn cấp bằng đường dẫn và giữ NGOÀI mọi repo (xem [`templates/README.md`](templates/README.md)). `core.hooksPath` nằm trong `.git/config` nên là cấu hình per-clone, per-máy, không đi theo repo. |
|
|
186
|
+
| `--fleet` | Tạo `~/.colab/repos.txt` từ `audit/repos.txt`, chỉ khi file chưa tồn tại. Danh sách đó cố tình nằm ngoài repo: nó ghi tên các repo private của bạn, còn repo này thì public. |
|
|
187
|
+
| `--all` | `--tools --hooks --fleet`. |
|
|
188
|
+
| `--dry` | In ra sẽ làm gì, không thay đổi gì. Ghép được với mọi flag trên. |
|
|
189
|
+
|
|
190
|
+
**Service luôn-bật phải gọi `~/.colab/bin/colab`.** Bản CLI symlink chạy theo
|
|
191
|
+
đúng nhánh mà clone này đang checkout — với một phiên làm việc của con người thì
|
|
192
|
+
đó là chủ đích, nhưng với thứ sống lâu hơn một phiên thì đó là sai. Một daemon,
|
|
193
|
+
một launch agent hay một runner headless bật từ mấy tháng trước sẽ âm thầm đổi
|
|
194
|
+
hành vi chỉ vì ai đó checkout một nhánh chẳng liên quan, mà không có gì báo cả:
|
|
195
|
+
tiến trình vẫn chạy, chỉ là chạy khác đi. Nên `--tools` còn ghi thêm một **bản
|
|
196
|
+
copy** vào `~/.colab/bin/` (có tôn trọng `COLAB_HOME`), đóng dấu version handbook
|
|
197
|
+
mà nó được lấy ra — hoặc, khi cây làm việc đó đang đi trước tag gần nhất, đóng dấu
|
|
198
|
+
đúng commit mà nó được lấy ra (`v1.7.0-2-gc8436c6`) kèm một cảnh báo, vì không
|
|
199
|
+
version phát hành nào mô tả đúng đống byte đó. Bản copy đó không bao giờ tự thay đổi.
|
|
200
|
+
|
|
201
|
+
Vì vậy làm mới nó là một hành động chủ ý, không phải hệ quả phụ: chạy lại
|
|
202
|
+
`./install.sh --tools`. `colab update` sẽ cho biết khi nào đến lúc. **`behind`
|
|
203
|
+
nghĩa là đã có một thay đổi CLI ĐÃ PHÁT HÀNH mà máy này chưa có** — phép so sánh
|
|
204
|
+
chạy tới tag gần nhất, nên một bản phát hành không đụng gì tới code CLI sẽ không
|
|
205
|
+
càm ràm bạn, mà công việc chưa phát hành trong chính checkout của bạn cũng vậy.
|
|
206
|
+
(Vế sau chính là lý do mốc trên là tag chứ không phải `HEAD`: đo tới `HEAD` khiến
|
|
207
|
+
mọi máy bị đánh dấu cũ suốt quãng từ lúc commit CLI tới tag kế tiếp, mà cách khắc
|
|
208
|
+
phục được quảng cáo lại copy *từ* chính cây làm việc đó — nên trên máy đang phát
|
|
209
|
+
triển handbook, nó khuyên các service nạp code chưa phát hành.) Nó không bao giờ
|
|
210
|
+
ghi đè bản copy, kể cả với `--apply`: đó là bộ công cụ mà các service đang chạy
|
|
211
|
+
của bạn đang thực thi. `colab --version` cho biết bạn đang nói chuyện với bản nào.
|
|
212
|
+
|
|
213
|
+
**3. Kiểm lại, rồi chỉ cho audit biết phải soi repo nào.**
|
|
214
|
+
|
|
215
|
+
```sh
|
|
216
|
+
colab --help # không thấy lệnh? sửa PATH — bước 2 in sẵn dòng cần thêm
|
|
217
|
+
colab --version # colab nào đây: bản working tree hay bản đóng băng?
|
|
218
|
+
$EDITOR ~/.colab/repos.txt # thay các dòng ví dụ bằng repo của bạn
|
|
219
|
+
node audit/audit.mjs # báo cáo conformance cho toàn bộ fleet
|
|
220
|
+
colab update # các bản copy có đóng dấu đã tụt lại — kể cả CLI đóng băng
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
Xong thì đọc [`CONVENTIONS.md`](CONVENTIONS.md): mất ~15 phút, và là file chuẩn
|
|
224
|
+
tắc duy nhất ở đây.
|
|
225
|
+
|
|
226
|
+
## Adopt vào một repo
|
|
227
|
+
|
|
228
|
+
Bản rút gọn — checklist đầy đủ ở
|
|
229
|
+
[`CONVENTIONS.md` §9](CONVENTIONS.md#9-adopting-this):
|
|
230
|
+
|
|
231
|
+
1. Trả lời câu 1 một cách trung thực (có production **hôm nay** không, chứ
|
|
232
|
+
không phải "sắp có").
|
|
233
|
+
2. Thêm `.github/project.yml`. `colab adopt` hỏi năm câu rồi ghi file giùm bạn —
|
|
234
|
+
nó dừng ở phần descriptor và in ra phần còn lại của danh sách này, vì mấy
|
|
235
|
+
bước sau không phải việc của nó.
|
|
236
|
+
3. `colab labels --ensure` — các label quy ước không có sẵn, và không phải chỉ
|
|
237
|
+
một cái. Một check mà label của nó chưa từng được tạo thì không bao giờ chạy
|
|
238
|
+
được.
|
|
239
|
+
4. Dán [`templates/repo-CLAUDE-block.md`](templates/repo-CLAUDE-block.md) vào
|
|
240
|
+
`CLAUDE.md` của repo — đây là cách duy nhất để agent phát hiện ra bộ quy ước
|
|
241
|
+
này.
|
|
242
|
+
5. Đảm bảo CI đạt hai kết quả bắt buộc: quét secret và build, với phiên bản
|
|
243
|
+
toolchain **resolve từ manifest của chính repo** — không bao giờ hardcode.
|
|
244
|
+
Copy template nếu thấy tiện.
|
|
245
|
+
|
|
246
|
+
Nhánh có sẵn từ trước được **giữ nguyên** (grandfathered). Đừng đổi tên gì cả.
|
|
247
|
+
|
|
248
|
+
**Làm việc trong repo không phải của mình?** Nếu không thể commit các file này vào đó,
|
|
249
|
+
`colab adopt --local` giữ mọi thứ trong bản clone local của bạn, không có gì lọt vào lịch sử
|
|
250
|
+
của chủ repo — xem
|
|
251
|
+
[*Working in a repo you don't own*](CONVENTIONS.md#working-in-a-repo-you-dont-own).
|
|
252
|
+
|
|
253
|
+
## Vì sao ép buộc ít vậy
|
|
254
|
+
|
|
255
|
+
Các repo private của chúng ta nằm trên gói GitHub không có branch protection —
|
|
256
|
+
không thể cấm push vào `main`. Nên handbook này không giả vờ ép buộc; nó làm
|
|
257
|
+
cho việc **tuân thủ rẻ và việc kiểm tra rẻ**. Audit tool báo drift; quy ước
|
|
258
|
+
giải thích *vì sao* từng luật tồn tại để bạn tự phán đoán khi nào đáng phá luật.
|
|
259
|
+
Khi phá, hãy sửa tài liệu trong cùng PR — một tài liệu mô tả một repo không tồn
|
|
260
|
+
tại là thứ tệ nhất trong nghề này.
|
|
261
|
+
|
|
262
|
+
**Có hai thứ thì chặn thật, và ranh giới đó là cố ý.** Git hook thì từ chối:
|
|
263
|
+
một bản quét secret, và một bản quét danh tính chặn không cho tên máy, đường dẫn
|
|
264
|
+
home hay tên khách hàng lọt vào một repo public. Chúng canh phần **phát hành ra
|
|
265
|
+
ngoài** — sai lầm duy nhất không thể sửa được, vì history không thu hồi lại được
|
|
266
|
+
một khi đã có người clone. Mọi thứ thuộc về *conformance* vẫn chỉ là cảnh báo:
|
|
267
|
+
sai một quy ước thì tốn một cuộc trao đổi, còn sai chuyện phát hành thì tốn vĩnh
|
|
268
|
+
viễn.
|
|
269
|
+
|
|
270
|
+
## Giấy phép
|
|
271
|
+
|
|
272
|
+
[MIT License](LICENSE). Cứ copy những gì thấy dùng được — repo này sinh
|
|
273
|
+
ra để làm việc đó. Giấy phép là nửa pháp lý của "copy-and-own": bạn được dùng,
|
|
274
|
+
sửa và phát hành lại mọi thứ ở đây, kể cả trong sản phẩm đóng mã nguồn, miễn là
|
|
275
|
+
giữ lại phần ghi chú bản quyền. Nó cũng kèm một điều khoản cấp quyền sáng chế
|
|
276
|
+
rõ ràng, và giữ lại quyền với thương hiệu của dự án.
|
|
277
|
+
|
|
278
|
+
Việc bạn adopt một quy ước không tốn gì của bạn và cũng không cho chúng tôi
|
|
279
|
+
quyền gì. Không có gì ở đây gửi dữ liệu về, và không có nghĩa vụ đóng góp ngược.
|