2 added, 2 removed. Audit A to A.
<!-- lang:en -->
# CLAUDE.md — xeno-skills (T4 agent-primary repo)
> Agent operating manual. **Read fully at session start.** The `using-t4` entry map below is a
> **standing default**, not a pointer to read once: re-route at every phase boundary. This repo is
> the T4 standard-shipper — the rules here are the ones it ships.
## North-star
Ship agent skills and workflow-enforcement hooks that make agent-primary repos (like this one)
correct, verifiable, and self-consistent. This repo documents a standard it must itself follow:
every rule, figure, or contract it ships is tested by `tests/`, and a documented-but-unenforced
claim is a defect (see the composition audits in `docs/research/2026-08-04-*`).
## Repo layout
- `skills/` — the skills: `multi-agent/` (clink delegation), `t4/` (the T4 standard incl. this
- bootstrap), `design/` (web/UI), `karpathy-guidelines/` (coding guardrails).
+ bootstrap), `design/` (web/UI), `qwen38/` (skills a small local model will follow), `karpathy-guidelines/` (coding guardrails).
- `hooks/` — **canonical** workflow-enforcement hook scripts (the plugin's path-B copies).
- `.claude-plugin/` — plugin manifest.
- `tests/` — the bash contract suite (hooks, gate, guards, skills). CI job `tests` runs it.
- `docs/` — `adr/`, `research/` (empirical data that calibrated the skills), `plans/`, `agents/`.
- Memory: `docs/OPEN-WORK-LEDGER.md`, `DONE.md`, `Obsidian-xeno-skills/Home.md`.
## Commands
- **Test / verify (fast prefix of CI):** `bash tests/hooks/run-all.sh` — runs every `test-*.sh`.
This is the `.claude/t4.json` `"verify"`; the gate runs it before `gh pr merge`.
- **E2E / skill discovery (CI only):** `npx --yes skills@1 add . --list` — asserts every
`SKILL.md` is discoverable by the real installer (installer stops descending at a dir's own
`SKILL.md`, #45). Run locally when a skill's directory structure changes.
- **Git-bash on Windows:** `C:\Program Files\Git\bin\bash.exe` (hooks resolve it via `run-hook.cmd`).
## Session-start read protocol
1. `Obsidian-xeno-skills/Home.md` (vault index) — open only the notes the task touches.
2. `docs/OPEN-WORK-LEDGER.md` — current open work, tracked and untracked.
3. The GitHub issue you're picking up — `gh issue view <n> --comments`.
4. `DONE.md` / `docs/research/` only if the task needs history or provenance.
## Session-end protocol — report what actually happened
Before the session ends, **report every rule that did not hold** as a `skill-feedback` issue on
`xenodeve/xeno-skills`. The tracker is the record: it does not depend on the branch checked out,
does not depend on the repo the session ran in, and survives a session that ends by crashing.
**One issue per rule, not per session** — a rule that fails five times is one issue with five
comments, and the comment count is the frequency.
```sh
gh issue list --repo xenodeve/xeno-skills --state all --search "<skill> <rule>" # --state all
gh issue comment <n> --repo xenodeve/xeno-skills --body-file <file> # found one
gh issue create --repo xenodeve/xeno-skills --label skill-feedback ... # none
```
`--repo` is not optional; `gh` defaults to the repo you are standing in. Include closed issues — a
closed one often holds the analysis already, or records that the behaviour is deliberate.
**In this repo also write the local note**, `Obsidian-xeno-skills/skill-usage/<YYYY-MM-DD>-<slug>.md`,
so the findings sit next to the code being changed. Sessions in other repos file the issue only.
Rules and skeleton: `t4-agent-memory`.
**Report the skips, especially the embarrassing ones** — a record of only the memorable sessions is a
failure-selected sample. **No hook produces any of this**
(`docs/adr/0001-hook-based-workflow-enforcement.md`); a missing report means a missing report, not a
session in which nothing went wrong.
## using-t4 — standing default (invoke at every phase boundary)
This repo follows the T4 operating standard. **Re-route at every phase boundary:** a check at task
start does **not** discharge a later trigger. After writing code → `simplify`; before merge →
`code-review` + `scrutinize`; touched auth/secrets → `security-review`; done → `verify`. When a task
matches a `t4-*` skill or a companion-ecosystem skill (superpowers, mattpocock, 9arm), invoke it
before acting — don't work from memory; skills evolve. The non-negotiable rules (evidence before
verdict, root cause before fix, proof before skipping, PRD → issues → PR, TDD, bilingual tracker)
are carried by `using-t4` — load it at session start and follow it through the session.
**clink-masteragent wiring:** wired, and the choice this paragraph asked for is **invoke before any
`clink` call** — not loaded at session start. `clink` is reachable here as `mcp__pal__clink`, carrying
`antigravity`, `claude`, `claude-9arm`, `codex`, `cursor` (verified 2026-08-14 by six successful calls
across three of them). It is used in a minority of sessions, so paying ~19 KB of every session for a
tier most of them never reach is the worse trade. **Load `using-clink` first, then the instrument
skill, then `clink-masteragent` before the call that spends a lane.**
## Dev notification
Notify the developer (toast via `scripts/notify.ps1` if present, else the push tool) on: a
TDD cycle / long task complete, needing a confirm (before closing issues / merging), or an AFK
batch done — not routine sub-progress.
## Writing conventions (bilingual)
- **GitHub tracker** (issue/PRD/PR bodies): English + a **full Thai mirror**, same depth — never a
summary. Identifiers stay English. See `docs/agents/issue-tracker.md`.
- **Governed docs** (`CONTEXT.md`, `UBIQUITOUS_LANGUAGE.md`, `PRODUCT.md`, `docs/agents/*`):
`<!-- lang:en -->` … `<!-- lang:end -->` / `<!-- lang:th -->` … `<!-- lang:end -->` full mirror.
- **Chat, reports, status updates:** single-language (Thai).
- **Code, commit messages, inline comments:** English.
## Agents docs pointers
- Workflow & auto-triggered skills → `docs/agents/workflow.md`
- Issue tracker & bilingual bodies → `docs/agents/issue-tracker.md`
- Triage labels (canonical roles + T4 delta) → `docs/agents/triage-labels.md`
- Domain doc consumption rules → `docs/agents/domain.md`
- Domain glossary → `CONTEXT.md` (canonical: `UBIQUITOUS_LANGUAGE.md`)
## Self-consistency rules (this repo only)
- Editing a root `hooks/` script ⇒ re-copy it to `skills/t4/t4-project-bootstrap/references/hooks/`
in the same change (`test-bootstrap-sync.sh` byte-compares).
- Editing hook wiring ⇒ update both `hooks/hooks.json` (plugin) and the bootstrap
`references/hooks/settings.json` (`test-wiring-parity.sh`).
- A new rule/claim in a skill ⇒ a `tests/skills/test-*.sh` asserting it. Documented ≠ enforced.
<!-- lang:th -->
# CLAUDE.md — xeno-skills (T4 repo แบบ agent-primary)
> คู่มือการทำงานของ agent **อ่านให้ครบตอนเริ่ม session** entry map `using-t4` ด้านล่างเป็น **ค่า
> เริ่มต้นถาวร** ไม่ใช่ pointer ที่อ่านครั้งเดียว — ต้อง re-route ทุกครั้งที่ข้าม phase repo นี้เป็น
> **ตัว ship มาตรฐาน T4** — กฎที่เขียนที่นี่คือกฎที่ repo นี้เป็นคนแจกจ่าย
## เป้าหมาย (North-star)
Ship agent skills และ workflow-enforcement hooks ที่ทำให้ repo แบบ agent-primary (รวมทั้ง repo นี้)
ถูกต้อง ตรวจสอบได้ และ self-consistent — repo นี้เป็นมาตรฐานที่ตัวเองต้องปฏิบัติตาม: ทุกกฎ/ตัวเลข/
contract ที่ ship ออกไปต้องมี `tests/` คอยยืนยัน และการอ้างว่ามีแต่ไม่ได้บังคับจริงคือ defect
(ดู composition audits ใน `docs/research/2026-08-04-*`)
## โครงสร้าง repo
- `skills/` — ตัว skills: `multi-agent/` (clink delegation), `t4/` (มาตรฐาน T4 รวม bootstrap นี้),
- `design/` (web/UI), `karpathy-guidelines/` (guardrails การเขียนโค้ด)
+ `design/` (web/UI), `qwen38/` (skill ที่โมเดลเล็กในเครื่องทำตามได้), `karpathy-guidelines/` (guardrails การเขียนโค้ด)
- `hooks/` — **ต้นฉบับ** ของ workflow-enforcement hooks (path-B ของ plugin)
- `.claude-plugin/` — plugin manifest
- `tests/` — ชุดเทสต์ bash (hooks, gate, guards, skills) — CI job `tests` รันชุดนี้
- `docs/` — `adr/`, `research/` (ข้อมูลเชิงประจักษ์ที่ปรับเทียบ skills), `plans/`, `agents/`
- Memory: `docs/OPEN-WORK-LEDGER.md`, `DONE.md`, `Obsidian-xeno-skills/Home.md`
## คำสั่ง
- **Test / verify (fast prefix ของ CI):** `bash tests/hooks/run-all.sh` — รันทุก `test-*.sh`
นี่คือค่า `"verify"` ใน `.claude/t4.json`; gate จะรันก่อน `gh pr merge`
- **E2E / skill discovery (เฉพาะ CI):** `npx --yes skills@1 add . --list` — ยืนยันว่าทุก
`SKILL.md` ถูกค้นพบโดย installer จริง (installer หยุดไล่ directory ที่มี `SKILL.md` ของตัวเอง, #45)
— รันเองเมื่อโครงสร้าง directory ของ skill เปลี่ยน
- **Git-bash บน Windows:** `C:\Program Files\Git\bin\bash.exe` (hooks ค้นผ่าน `run-hook.cmd`)
## วิธีอ่านตอนเริ่ม session
1. `Obsidian-xeno-skills/Home.md` (vault index) — เปิดเฉพาะ note ที่งานแตะถึง
2. `docs/OPEN-WORK-LEDGER.md` — งานที่ค้างอยู่ ทั้งที่มีและไม่มี issue
3. ตัว issue ที่กำลังหยิบ — `gh issue view <n> --comments`
4. `DONE.md` / `docs/research/` เฉพาะเมื่องานต้องการ history หรือ provenance
## using-t4 — ค่าเริ่มต้นถาวร (invoke ทุกขอบ phase)
repo นี้ใช้มาตรฐานการทำงาน T4 **Re-route ทุกขอบ phase:** การตรวจตอนเริ่ม task **ไม่ได้** ตัดสิทธิ์
trigger ที่จะเกิดทีหลัง เขียนโค้ดเสร็จ → `simplify`; ก่อน merge → `code-review` + `scrutinize`;
แตะ auth/secrets → `security-review`; เสร็จ → `verify` เมื่อ task ตรงกับ skill `t4-*` หรือ
companion ecosystem (superpowers, mattpocock, 9arm) ให้ invoke ก่อนลงมือ — อย่าทำจากความจำ
เพราะ skills มีการพัฒนา กฎที่ไม่ negotiable (หลักฐานก่อน verdict, root cause ก่อน fix, proof ก่อน
skip, PRD → issues → PR, TDD, bilingual tracker) อยู่ใน `using-t4` — โหลดตอนเริ่ม session และทำตามทั้ง session
**clink-masteragent wiring:** wired แล้ว และคำตอบของคำถามที่ย่อหน้านี้ตั้งไว้คือ **invoke ก่อนทุก
`clink` call** ไม่ใช่โหลดตอนเริ่ม session · `clink` เรียกได้ในชื่อ `mcp__pal__clink` มี `antigravity`,
`claude`, `claude-9arm`, `codex`, `cursor` (ยืนยัน 2026-08-14 ด้วยการเรียกสำเร็จหกครั้งบนสามตัว) ·
มีไม่กี่ session ที่ใช้มัน การจ่าย ~19 KB ทุก session ให้ tier ที่ส่วนใหญ่ไม่ได้แตะจึงเป็นการแลกที่แย่กว่า ·
**โหลด `using-clink` ก่อน แล้วค่อย skill ของเครื่องมือ แล้วค่อย `clink-masteragent` ก่อน call ที่จะจ่ายโควตา**
## การแจ้งเตือน developer
แจ้ง (toast ผ่าน `scripts/notify.ps1` ถ้ามี หรือ push tool) เมื่อ: TDD cycle / งานยาวเสร็จ,
ต้องให้คนยืนยัน (ก่อนปิด issue / merge), หรือ AFK batch จบ — ไม่ใช่ทุกความคืบหน้าเล็กๆ
## ข้อตกลงการเขียน (bilingual)
- **GitHub tracker** (issue/PRD/PR body): อังกฤษ + **ไทยที่ mirror เต็ม** ความลึกเท่ากัน — ห้ามสรุป
identifiers ต้องเป็นอังกฤษ ดู `docs/agents/issue-tracker.md`
- **Governed docs** (`CONTEXT.md`, `UBIQUITOUS_LANGUAGE.md`, `PRODUCT.md`, `docs/agents/*`):
`<!-- lang:en -->` … `<!-- lang:end -->` / `<!-- lang:th -->` … `<!-- lang:end -->` mirror เต็ม
- **Chat, reports, status updates:** ภาษาเดียว (ไทย)
- **โค้ด, commit message, inline comment:** อังกฤษ
## ตัวชี้ docs/agents
- Workflow และ auto-triggered skills → `docs/agents/workflow.md`
- Issue tracker และ bilingual bodies → `docs/agents/issue-tracker.md`
- Triage labels (roles มาตรฐาน + T4 delta) → `docs/agents/triage-labels.md`
- กฎการอ่าน domain docs → `docs/agents/domain.md`
- Domain glossary → `CONTEXT.md` (canonical: `UBIQUITOUS_LANGUAGE.md`)
## กฎ self-consistency (เฉพาะ repo นี้)
- แก้ script ใน `hooks/` root ⇒ ต้องคัดลอกไป `skills/t4/t4-project-bootstrap/references/hooks/`
ในคอมมิทเดียวกัน (`test-bootstrap-sync.sh` เทียบ byte)
- แก้ hook wiring ⇒ ต้องแก้ทั้ง `hooks/hooks.json` (plugin) และ bootstrap
`references/hooks/settings.json` (`test-wiring-parity.sh`)
- กฎ/คำอ้างใหม่ใน skill ⇒ ต้องมี `tests/skills/test-*.sh` ยืนยัน — "เขียนไว้" ≠ "บังคับจริง"
<!-- lang:end -->