fdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: fdk — Framework Dev Kit (self-contained)

Skill: fdk — Framework Dev Kit（self-contained）

On-demand: KHÔNG auto-bơm đầu phiên (phần lớn phiên là dev dự án khác). Skill này tự chứa đủ guidance để chạy ở bất kỳ project nào; mục "bản đầy đủ" ở cuối chỉ áp dụng KHI bạn đang ở trong repo framework.

按需模式：不要在会话开始时自动注入（大多数会话都是其他项目的开发工作）。本 skill 自包含足够的指导内容，可在任何项目中运行；末尾的“完整版本”仅适用于当前位于 framework repo 中时。

WHAT

Purpose và context

目的与上下文

Purpose: front-door on-demand, self-contained cho việc sửa CHÍNH framework hoặc distill/author một skill ở bất kỳ project nào: pre-flight trước mọi thay đổi, luật ship/HTML, bản đồ downstream, và gác problem-tree.
Trigger (khi nào dùng):
- Đang sửa CHÍNH framework (skill / rule / validator / hook / wiki), HOẶC
- Đang distill / author một skill trong phiên của project bất kỳ.
Non-goals: KHÔNG dùng cho dev tính năng dự án thường (đó là phần lớn phiên — ADR-004); không auto-fire đầu phiên.

**目的：**用于按需通过 front-door 修改 framework 本身，或在任何项目中 distill/author skill 的自包含入口：所有变更前执行 pre-flight，掌握发布/HTML 规则、downstream 地图，并维护 problem-tree。
触发条件（何时使用）：
- 正在修改 framework 本身（skill / rule / validator / hook / wiki），或者
- 正在任意项目的会话中 distill / author skill。
**非目标：**不要用于常规项目功能开发（这属于大多数会话场景——ADR-004）；不要在会话开始时自动触发。

Tư tưởng mặc định — Donella Meadows: sửa HỆ THỐNG, đừng sửa triệu chứng

默认思维——Donella Meadows：修复系统，而不是症状

Mọi việc framework đi qua lens tư duy hệ thống & vòng phản hồi (systems thinking, Thinking in Systems):

Gặp lỗi/vấn đề → hỏi "cấu trúc nào sinh ra nó?" trước khi vá chỗ đau. Một triệu chứng lặp lại là tín hiệu của vòng phản hồi thiếu hoặc sai — vá tay lần thứ 2 cho cùng một loại lỗi là sai quy trình; đúng là đổi cấu trúc (rule harness, skill, template, hook) để loại lỗi đó không tái sinh. (Đây chính là failure-flywheel và problem-tree đang làm.)
Chọn điểm đòn bẩy (leverage point) cao nhất với chi phí thấp nhất, theo thang Meadows: sửa tham số < thêm vòng phản hồi < đổi luồng thông tin < đổi luật chơi < đổi mục tiêu/paradigm. Trước khi code, tự hỏi: fix này nằm ở bậc nào? Có bậc cao hơn rẻ không? (Vd: thay vì dặn agent nhớ — bậc thấp — thì thêm validator tự cắn — đổi luật chơi.)
Nuôi vòng phản hồi, đừng chỉ bắn một phát: mỗi thay đổi phải có đường tín hiệu quay về (verify tất định, ledger, log, eval) để hệ tự thấy mình lệch. Thay đổi không có feedback loop = thay đổi mù.
Tôn trọng độ trễ (delay): hiệu ứng của rule/skill mới chỉ lộ sau nhiều phiên — đừng kết luận sớm, cũng đừng chồng thêm fix khi fix trước chưa kịp phát tác; ghi ngày vào ledger để đo.

framework 的所有工作都应通过系统思考与反馈循环的视角审视（systems thinking Thinking in Systems）：

遇到错误/问题时，先问“是什么结构产生了它？”，然后再修补痛点。反复出现的症状意味着反馈循环缺失或失效——第二次为同类错误手工打补丁是错误的处理方式；正确做法是改变结构（rule harness、skill、template、hook），避免该错误再次产生。（这正是 failure-flywheel 和 problem-tree 所负责的工作。）
选择成本最低且杠杆最高的位置（leverage point），按照 Meadows 杠杆阶梯：调整参数 < 增加反馈循环 < 改变信息流 > 改变游戏规则 < 改变目标/范式。编码前先问：此修复位于哪一层？是否存在成本更低但层级更高的方案？例如，与其要求 agent 记住规则（低杠杆），不如增加一个会主动拦截问题的 validator（改变游戏规则）。
持续培育反馈循环，而不是只开一枪：每次变更都必须有信号返回路径（确定性 verify、ledger、log、eval），让系统能够察觉自身偏离。没有反馈循环的变更就是盲改。
尊重延迟（delay）：新 rule/skill 的效果往往要经过多个会话才会显现——不要过早下结论，也不要在前一个修复尚未显现时继续叠加修复；将日期记录到 ledger 中以便衡量。

Kim chỉ nam thứ 2 — Hub & trình bày (UX cho user, feedback 2026-07-03)

第二指南针——Hub 与呈现（面向用户的 UX，2026-07-03 反馈）

Cạnh tư duy Meadows, mọi tool/skill/hub framework tuân nguyên tắc dùng-được-và-an-toàn của user:

Hub 1-tên, mô tả-phạm-vi — đừng bắt nhớ nhiều lệnh con. Một hub làm HẾT việc liên quan; user chỉ mô tả phạm vi (all > 1 phần / phần tương đương / mức độ), không phải nhớ subcommand. Tên lệnh phải NGẮN, gõ được bằng cơ-bắp (user quen
```
curl
```
; tên khó nhớ = không bao giờ được gọi → vô dụng). Vd
```
medic
```
(cổng sức khoẻ tổng) thay tên dài.
TL;DR — phần user đọc cô đọng + ĐỦ ý, không dè sẻn. User có thói quen "too long didn't read": ngắn nhưng không cụt, không ki bo giải thích.
Model tư duy minh bạch — user đọc phần think để kiểm hướng đi. Đừng giấu suy luận.
Cuối output: inject recap + dạy dùng thụ động — nhắc lại tinh gọn tool này làm gì + hint use-case tiêu biểu VÀ bất ngờ (user không ngờ cũng dùng được) → user học cách dùng mà không phải hỏi.
Minh bạch = an toàn; usage > performance. Cho user ĐỌC ĐƯỢC cấu trúc thư mục + under-the-hood, không chỉ tối ưu cho query. Đã hiển thị thì transparent → user thấy an toàn khi dùng hệ. Ưu tiên tính-dùng-được hơn tối ưu ngầm.

除 Meadows 思维外，framework 中的所有 tool/skill/hub 都必须遵循“用户可用且安全”的原则：

**Hub 使用单一名称并直接描述范围——不要让用户记住多个子命令。**一个 hub 应完成全部相关工作；用户只需描述范围（全部 > 一部分 / 等价部分 / 程度），不必记忆 subcommand。命令名称必须简短，能够凭肌肉记忆输入（用户熟悉
```
curl
```
；难记的名称永远不会被调用，也就毫无用处）。例如使用
```
medic
```
（统一健康检查入口），而不是冗长名称。
**TL;DR——让用户读到的内容紧凑但信息充分，不能过度精简。**用户有“内容太长不愿读”的习惯：既要简短，又不能省略关键解释。
思维模型透明——让用户阅读 think 部分，以检查思考方向。不要隐藏推理过程。
在输出末尾注入 recap，并以被动方式教会使用——简要提醒该工具的作用，并给出典型及容易出乎意料的使用场景提示，让用户无需询问也能学会使用。
**透明意味着安全；usage > performance。**让用户能够阅读目录结构及 under-the-hood 实现，而不只是针对查询进行优化。已经展示的内容是透明的，用户才会对使用该系统感到安全。优先保证可用性，而不是隐式优化。

Mental model

pre-flight (pull → luật → grep/impact → propose STOP → surgical+verify → layout downstream) → sửa → [distill skill · kit từ dự án khác · bản đầy đủ trong repo] → ci-local + fdk-uat trước ship → cập nhật problem-tree trước khi kết thúc turn

pre-flight（pull → 规则 → grep/impact → propose STOP → surgical+verify → layout downstream）→ 修改 → [distill skill · 从其他项目生成 kit · framework repo 中的完整版本] → ship 前执行 ci-local + fdk-uat → 结束 turn 前更新 problem-tree

。

Input và output contract

输入与输出契约

	Field	Required?	Ý nghĩa
In	việc framework hoặc skill cần distill	có	mô tả của user
In	repo hiện tại (framework hay dự án khác)	có	quyết định dùng bản đầy đủ hay kit
Out	draft propose chờ duyệt, rồi thay đổi surgical đã verify	có	không code thẳng
Out	`llmwiki/html/fdk-problem-tree.html` đã rà/cập nhật	có mỗi lần gọi	trước khi kết thúc turn
Out	PR qua kit	khi dev từ dự án khác	`fdk-kit.sh submit`

	字段	必填？	含义
输入	需要修改的 framework 工作或待 distill 的 skill	是	用户描述
输入	当前 repo（framework 或其他项目）	是	决定使用完整版本还是 kit
输出	等待审批的 draft proposal，随后执行已验证的 surgical 变更	是	不得直接编码
输出	已检查/更新的 `llmwiki/html/fdk-problem-tree.html`	每次调用均必填	结束 turn 前完成
输出	通过 kit 创建的 PR	从其他项目开发时需要	`fdk-kit.sh submit`

Rules và capabilities

规则与能力

RULE-01 (MUST): TRƯỚC KHI ship push/PR — chạy
python3 fdk/tools/ci-local.py
(trọn mọi step
```
run:
```
của mọi workflow GitHub tại local, L4). L2 (pre-commit/medic) KHÔNG bằng L4 (CI fresh-clone): có gate CHỈ chạy trên CI, hoặc auto-fix ở Stop-hook nên commit-rồi-push-ngay lọt L2 mà CI đỏ (đã cháy: R3 index-sync 2026-07; search-index + skill-provenance 2026-09-08). Xanh hết mới push; rồi
```
/fdk-uat
```
(canary + main-URL smoke) trước khi báo xong. Xem
```
[[harness-enforcement-floor]]
```
.
RULE-02 (MUST): KHÔNG ghi công AI — commit message / PR / code / wiki KHÔNG được chèn
```
Co-Authored-By: Claude…
```
,
```
Generated with Claude Code
```
,
```
🤖
```
, hay bất kỳ credit/attribution nào cho AI. Author & committer chỉ là danh tính người dùng. Nếu template/tool sinh sẵn trailer ghi công thì cắt bỏ trước khi commit.
RULE-03 (MUST): On-demand only — không đăng ký hook auto-fire đầu phiên (ADR-004).
RULE-04 (MUST): Self-contained — phần trên (pre-flight + distill + inventory) đủ chạy ở project khác; mục "bản đầy đủ" chỉ áp dụng KHI các file đó tồn tại. Không bao giờ giả định file repo-local có mặt.
RULE-05 (MUST): Đếm số luôn LIVE; không hardcode (anti-drift).
RULE-06 (MUST): HTML cho NGƯỜI đọc phải giải nghĩa thuật ngữ — nội dung hiển thị trong report/visualization (title, mô tả node, chú thích) viết tiếng Việt thường; thuật ngữ chuyên ngành bắt buộc kèm giải nghĩa ngắn trong ngoặc ngay lần xuất hiện đầu (vd: "flush (xả sổ — tự ghi trước khi thoát)", "untracked (file git chưa theo dõi)"). Không viết tắt jargon trần cho người xem — jargon trần chỉ được phép trong file máy đọc.
RULE-07 (MUST): HTML cho người xem phải có TOGGLE sáng/tối (feedback 2026-07-06 — nhắc lần 2, không tái phạm) — mọi file HTML sinh ra để NGƯỜI xem (report, cây, dashboard, docs, proposal render…) phải có nút chuyển dark/light:
```
prefers-color-scheme
```
chỉ là mặc định ban đầu, user bấm toggle thì override qua
```
html[data-theme]
```
+ lưu
```
localStorage
```
(kèm script chống FOUC trong head). KHÔNG ép cứng một mode. Dạng bắt buộc: NÚT GẠT (switch) có nhãn, hàng footer dính đáy sidebar/nav — KHÔNG chip icon rải góc. Snippet chuẩn: skill
```
docs-site-macos
```
§ "Theme Toggle sáng/tối"; generator tham khảo
```
_DARK_RULES
```
trong
```
fdk/tools/build-overstack-docs.py
```
(một nguồn emit 2 khối, chống drift).
RULE-08 (MUST): Chuyển mode PHẢI qua circle-reveal, không phải flip tức thời (feedback 160926, task
T-260916-01
) — nút gạt bấm xong mở một overlay tròn màu nền = MODE ĐÍCH, tỏa từ đúng toạ độ nút, lan chậm rồi nhanh-dứt-khoát phủ kín viewport, ĐÓ mới là lúc
```
data-theme
```
/
```
localStorage
```
đổi giá trị, rồi overlay fade. Tôn trọng
```
prefers-reduced-motion: reduce
```
(fallback về crossfade ≤150ms, không phải 0 motion). Snippet chuẩn: skill
```
docs-site-macos
```
§ "Theme Toggle sáng/tối" mục 4; nghiệm thu bằng
```
node skills/docs-site-macos/scripts/verify-theme-motion.mjs <file.html>
```
(Playwright thật, không phải model tự bảo đảm).
RULE-09 (MUST): HTML cho người xem: THANG CỠ CHỮ COMPACT cho màn 13″ (feedback 2026-07-06) — GIẢM size chứ không tăng: body ~13.5px, nav 12px, list/bảng 12.5px, nhãn 10–10.5px; tăng cỡ chữ làm màn 13″ tệ hơn (ít nội dung, wrap chật). Dễ đọc = line-height/contrast, không phải font to. Chi tiết: docs-site-macos § Best Practices.
RULE-10 (MUST): HTML report/visualization phải SHOW FULL PATH — mọi file HTML sinh ra để xem (report, cây, dashboard, proposal render…) phải hiển thị đường dẫn tuyệt đối của chính nó ngay trên trang (footer hoặc titlebar, dạng
```
<code>
```
copy được), để người xem biết file nằm đâu mà mở lại/sửa. Sinh file xong phải điền path thật, không placeholder.
Capabilities: đọc/ghi repo framework hoặc sandbox kit; chạy gate/test cục bộ; tạo PR qua CLI đã auth.

RULE-01（MUST）：在 push/PR 发布前运行
python3 fdk/tools/ci-local.py
（在本地执行所有 GitHub workflow 的全部
```
run:
```
步骤，属于 L4）。L2（pre-commit/medic）不能替代 L4（CI fresh-clone）；如果某个 gate 只在 CI 上运行，或 Stop-hook 中的 auto-fix 导致 commit 后立即 push，就可能通过 L2 却留下红色 CI（已发生：R3 index-sync 2026-07；search-index + skill-provenance 2026-09-08）。必须全部通过后才能 push；然后运行
```
/fdk-uat
```
（canary + main URL 冒烟测试），再报告完成。参见
```
[[harness-enforcement-floor]]
```
。
RULE-02（MUST）：不得标注 AI 贡献——commit message、PR、代码或 wiki 中不得插入
```
Co-Authored-By: Claude…
```
、
```
Generated with Claude Code
```
、
```
🤖
```
或任何形式的 AI credit/attribution。Author 与 committer 只能是用户身份。如果 template/tool 自动生成带署名的 trailer，必须在 commit 前删除。
RULE-03（MUST）：仅按需使用——不要注册会在会话开始时自动触发的 hook（ADR-004）。
RULE-04（MUST）：自包含——上述部分（pre-flight + distill + inventory）应足以在其他项目中运行；“完整版本”仅在相关文件实际存在时适用。绝不能假设 repo-local 文件一定存在。
RULE-05（MUST）：数量始终进行 LIVE 统计；不得硬编码（anti-drift）。
RULE-06（MUST）：面向人类阅读的 HTML 必须解释术语——report/visualization 中展示的内容（标题、节点描述、注释）应使用日常中文；专业术语首次出现时必须附有简短括号解释，例如“flush（冲刷——退出前自动写入）”“untracked（Git 尚未跟踪的文件）”。不要向人类阅读者直接使用未经解释的 jargon；纯 jargon 只允许出现在供机器读取的文件中。
RULE-07（MUST）：面向人类阅读的 HTML 必须提供明暗模式 TOGGLE（2026-07-06 反馈——再次提醒，不得重犯）——所有供人类查看的 HTML 文件（report、树、dashboard、文档、proposal render 等）都必须提供 dark/light 切换按钮：
```
prefers-color-scheme
```
仅作为初始默认值，用户点击 toggle 后应通过
```
html[data-theme]
```
覆盖，并保存到
```
localStorage
```
（同时在 head 中放置防止 FOUC 的脚本）。不得硬性固定一种模式。强制形式：带标签的开关（switch），以固定行形式置于 sidebar/nav 底部——不得使用散落在角落的 icon chip。标准 snippet：skill
```
docs-site-macos
```
§“Theme Toggle sáng/tối”；参考 generator
```
_DARK_RULES
```
，位于
```
fdk/tools/build-overstack-docs.py
```
（由单一来源 emit 两个代码块，防止 drift）。
RULE-08（MUST）：模式切换必须通过 circle-reveal，而非即时翻转（160926 反馈，任务
```
T-260916-01
```
）——点击开关后，应从开关的准确坐标展开一个采用目标模式背景色的圆形 overlay，缓慢扩散后快速、果断地覆盖整个 viewport；只有在此时才切换
```
data-theme
```
/
```
localStorage
```
的值，随后让 overlay 淡出。必须尊重
```
prefers-reduced-motion: reduce
```
（回退为不超过 150ms 的 crossfade，而不是完全无动效）。标准 snippet：skill
```
docs-site-macos
```
§“Theme Toggle sáng/tối”第 4 项；使用
```
node skills/docs-site-macos/scripts/verify-theme-motion.mjs <file.html>
```
验收（使用真实 Playwright，而不是依赖模型自我声明）。
RULE-09（MUST）：面向人类阅读的 HTML：针对 13 英寸屏幕使用紧凑字号阶梯（2026-07-06 反馈）——应减小而非增大字号：body 约 13.5px，nav 12px，list/table 12.5px，标签 10–10.5px；增大字号会让 13 英寸屏幕体验更差（可见内容更少、换行更拥挤）。易读性来自 line-height/contrast，而不是大字体。详情参见 docs-site-macos § Best Practices。
RULE-10（MUST）：HTML report/visualization 必须显示完整路径——所有供人类查看的 HTML 文件（report、树、dashboard、proposal render 等）都必须在页面中显示自身绝对路径（位于 footer 或 titlebar，使用可复制的
```
<code>
```
），让查看者知道文件位置并可重新打开或编辑。生成文件后必须填写真实路径，不得使用 placeholder。
能力：读取/写入 framework repo 或 sandbox kit；运行本地 gate/test；通过已完成认证的 CLI 创建 PR。

Failure boundaries

失败边界

Chưa có duyệt cho draft → blocked ở pre-flight #4, không code.
```
ci-local.py
```
đỏ → không push (RULE-01).
File repo-local không có mặt (đang ở dự án khác) → bỏ mục "bản đầy đủ", không giả định (RULE-04).
```
fdk-kit.sh check
```
chưa đủ 15 bước → không submit.

draft 尚未获批 → 在 pre-flight 第 4 步 blocked，不得编码。
```
ci-local.py
```
失败 → 不得 push（RULE-01）。
repo-local 文件不存在（当前位于其他项目）→ 省略“完整版本”，不得假设其存在（RULE-04）。
```
fdk-kit.sh check
```
未完成全部 15 个步骤 → 不得 submit。

HOW

Main workflow

主工作流

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	effect	base remote	Pull trước khi sửa	bản mới nhất	—
W02	deterministic	harness	Biết luật ( `rule-registry` / `policy.yaml` )	danh sách luật	không có harness → luật phổ quát
W03	deterministic	tên module	Grep tên; code dùng chung → impact-check rồi safe-change	không trùng	trùng → sửa module cũ
W04	judgment	thay đổi	Propose draft, STOP chờ duyệt	duyệt	chưa duyệt → blocked
W05	effect	draft đã duyệt	Surgical → verify → ghi vết (B01–B03 theo loại việc)	thay đổi + test xanh	đỏ → sửa, lặp
W06	deterministic	path chạm	Soi Bản đồ downstream trước khi chạm path hook/engine/installer/CI	path qua `overstack_paths.py`	`bare_path_lint` đỏ → sửa
W07	effect	vấn đề trong phiên	Rà + cập nhật problem-tree trước khi kết thúc turn	cây đã cập nhật	chưa có → tạo từ template

Chi tiết từng bước (nguồn chân lý cho W01–W06, Pre-flight):

Pull trước khi sửa — đồng bộ base, đừng làm trên bản cũ.
Biết luật — nếu repo có harness: xem
```
rule-registry
```
/
```
policy.yaml
```
. Luật phổ quát luôn đúng: file wiki phải có
```
## Origin
```
; không ghi
```
raw/
```
; file wiki đúng subfolder (concepts/entities/sources/draft/…); proposal phải đủ cặp
```
.md
```
+
```
.html
```
.
Đừng dẫm module cũ — trước khi tạo skill/validator/script/hook mới, grep tên xem đã tồn tại chưa; sửa code dùng-chung thì map caller trước (impact-check) rồi safe-change.
Propose trước — mọi thay đổi → draft kế hoạch, STOP chờ duyệt; đừng code thẳng.
Surgical → verify → ghi vết — chỉ chạm cái buộc phải chạm; chạy test/drift-test; cập nhật registry/log. Commit thì stage pathspec tường minh, không
```
git add -A
```
/
```
.
```
/
```
commit -a
```
: nhiều phiên dùng chung cây, stage hàng loạt cuốn việc dở của phiên khác (rule P1
```
no-bulk-stage
```
chặn ở repo framework).
Layout máy khách ≠ layout repo — trước khi chạm path trong hook/engine/installer/CI: đọc mục "Bản đồ downstream" bên dưới; đường trần
```
llmwiki/
```
```
harness/
```
CHỈ đúng trong repo này.

步骤	类型	输入	操作	输出/退出状态	失败/下一步
W01	effect	base remote	修改前执行 pull	最新版本	—
W02	deterministic	harness	了解规则（ `rule-registry` / `policy.yaml` ）	规则列表	无 harness → 使用通用规则
W03	deterministic	模块名称	Grep 名称；若属于共享代码，先做 impact-check，再执行 safe-change	无重复	重复 → 修改现有模块
W04	judgment	变更内容	提出 draft proposal，STOP 等待审批	获批	未获批 → blocked
W05	effect	已批准的 draft	Surgical → verify → 记录轨迹（按工作类型采用 B01–B03）	变更 + 测试通过	失败 → 修复并重试
W06	deterministic	涉及路径	触碰 hook/engine/installer/CI 路径前检查 downstream 地图	路径经过 `overstack_paths.py`	`bare_path_lint` 失败 → 修复
W07	effect	会话中发现的问题	结束 turn 前检查并更新 problem-tree	已更新的树	不存在 → 根据 template 创建

各步骤详情如下（W01–W06、Pre-flight 的事实来源）：

修改前先 pull——同步 base，不要在旧版本上工作。
了解规则——如果 repo 中有 harness，请查看
```
rule-registry
```
/
```
policy.yaml
```
。通用规则始终有效：wiki 文件必须包含
```
## Origin
```
；不得写入
```
raw/
```
；wiki 文件必须位于正确的 subfolder（concepts/entities/sources/draft/…）；proposal 必须同时提供
```
.md
```
和
```
.html
```
。
不要与旧模块重叠——创建新 skill/validator/script/hook 前，先 grep 名称确认是否已存在；如果要修改共享代码，先映射 caller（impact-check），再执行 safe-change。
先提出 proposal——所有变更都要先起草计划，STOP 等待审批；不要直接编码。
Surgical → verify → 记录轨迹——只修改必须修改的部分；运行 test/drift-test；更新 registry/log。 Commit 时必须使用显式 pathspec 进行 stage，不得使用
```
git add -A
```
/
```
.
```
/
```
commit -a
```
：多个会话共享同一工作树，批量 stage 会把其他会话的未完成工作一并提交（framework repo 中的 rule P1
```
no-bulk-stage
```
会阻止此操作）。
客户端 layout ≠ repo layout——触碰 hook/engine/installer/CI 路径前，先阅读下方“downstream 地图”；顶层路径
```
llmwiki/
```
、
```
harness/
```
仅在本 repo 中有效。

Branches

分支

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	conditional_required	việc là distill/author một skill	theo mục "Distill / author một skill"	—	W06
B02	conditional_required	đang dev từ dự án khác, không có `fdk/tools`	kit: pull → distill trong kit → check → submit PR	ở trong repo overstack → bỏ bước pull	W07
B03	capability_optional	đang TRONG repo framework (file bản đầy đủ có mặt)	đọc bản đầy đủ; sửa SKILL.md xong → `sync-skill.sh`	file không có → bỏ qua	W06
B04	conditional_required	sắp ship push/PR	`ci-local.py` rồi `/fdk-uat` (RULE-01)	đỏ → không push	W07

ID	类型	守卫条件	行为	跳过/失败	汇合点
B01	conditional_required	工作内容是 distill/author skill	按“Distill / author 一个 skill”章节执行	—	W06
B02	conditional_required	从其他项目开发，且不存在 `fdk/tools`	kit：pull → 在 kit 中 distill → check → submit PR	位于 overstack repo 内 → 跳过 pull	W07
B03	capability_optional	当前位于 framework repo 内，且完整版本文件存在	阅读完整版本；修改 SKILL.md 后执行 `sync-skill.sh`	文件不存在 → 跳过	W06
B04	conditional_required	准备 push/PR 发布	执行 `ci-local.py` ，然后执行 `/fdk-uat` （RULE-01）	失败 → 不得 push	W07

Validation và stopping

验证与停止条件

Kiểm tất định: test/drift-test,

swh-lint.py

cho skill,

ci-local.py

fdk-kit.sh check

, verify-theme-motion cho HTML. Cần duyệt người: draft propose ở W04. Dừng turn chỉ sau khi đã rà problem-tree (W07).

确定性验证：test/drift-test、针对 skill 的

swh-lint.py

、

ci-local.py

、

fdk-kit.sh check

、针对 HTML 的 verify-theme-motion。人工审批：W04 的 draft proposal。只有检查完 problem-tree 后才能结束 turn（W07）。

Examples

示例

Positive: "/fdk thêm probe mới cho medic" trong repo framework → pull, grep
```
medic.py
```
(không đẻ tool lẻ), draft chờ duyệt → sửa surgical + test →
```
ci-local.py
```
xanh trước push → thêm node problem-tree
```
status: solved
```
,
```
scope: ["harness"]
```
hiện "solved 1/3 trụ" màu cam.
Boundary/failure: đang ở dự án khác, muốn đẩy skill vừa distill vào overstack nhưng gõ
```
python3 fdk/tools/new-skill.py
```
→ file không tồn tại (ADR-004) → chuyển B02: pull kit về
```
.overstack-kit/
```
, distill trong kit,
```
fdk-kit.sh check
```
rồi
```
submit
```
.

**正向示例：**在 framework repo 中执行“/fdk 为 medic 添加新 probe”→ pull，grep
```
medic.py
```
（不要生成孤立工具），起草 proposal 并等待审批 → surgical 修改并测试 → push 前确保
```
ci-local.py
```
通过 → 在 problem-tree 中添加
```
status: solved
```
、
```
scope: ["harness"]
```
的节点，显示“已解决 1/3 个支柱”并使用橙色。
**边界/失败示例：**位于其他项目，希望将刚 distill 的 skill 推送到 overstack，却执行
```
python3 fdk/tools/new-skill.py
```
→ 文件不存在（ADR-004）→ 切换到 B02：将 kit pull 到
```
.overstack-kit/
```
，在 kit 中 distill，运行
```
fdk-kit.sh check
```
，然后执行
```
submit
```
。

Reference — Bản đồ downstream — cái bạn đang thấy KHÔNG phải cái chạy ở máy khách

参考——downstream 地图——你看到的内容并不是客户端实际运行的内容

Repo framework (đang mở)	Máy khách sau `curl bootstrap.sh`	Ghi chú
`llmwiki/`	`.llmwiki/`	wiki · raw · html · `.harness-stamp`
`harness/`	`.harness/`	chỉ `poc-vendor-neutral/` + `foundation.yaml` + `metrics/` ; KHÔNG có `scripts/` `validators/`
`harness/scripts` · `harness/validators` · `fdk/tools` · `llmwiki/.claude/hooks`	`~/.claude/harness/` (global)	engine dùng chung; hook fire từ `~/.claude/settings.json`
`fdk/wiki/`	không có	framework_only
`skills/*/SKILL.md`	`~/.claude/skills/`	qua npx, không nằm trong repo dự án
không có	`CAPABILITIES.md` · `.overstack.yaml` · root `.claude/settings.json`	chỉ có ở downstream

Nguồn máy-đọc:

harness/downstream-contract.yaml

→

layout_map

. Luật: path chạm downstream đi qua

harness/scripts/overstack_paths.py

(engine) hoặc

hooklib.overstack_dir/harness_dir/stamp_path

(hook);

bare_path_lint

đỏ nếu ghi cứng. Test hành vi thật:

bash harness/tests/dot-layout-runtime-test.sh .

(fixture dot, HOME cô lập). Nhớ:

rg

/Grep bỏ qua thư mục dấu chấm — dùng

--hidden

khi soi dự án downstream.

当前打开的 framework repo	执行 `curl bootstrap.sh` 后的客户端	备注
`llmwiki/`	`.llmwiki/`	wiki · raw · html · `.harness-stamp`
`harness/`	`.harness/`	仅包含 `poc-vendor-neutral/` + `foundation.yaml` + `metrics/` ；不包含 `scripts/` 、 `validators/`
`harness/scripts` · `harness/validators` · `fdk/tools` · `llmwiki/.claude/hooks`	`~/.claude/harness/` （全局）	共享 engine；hook 从 `~/.claude/settings.json` 触发
`fdk/wiki/`	无	framework_only
`skills/*/SKILL.md`	`~/.claude/skills/`	通过 npx 安装，不位于项目 repo 中
无	`CAPABILITIES.md` · `.overstack.yaml` · 根目录 `.claude/settings.json`	仅存在于 downstream

供机器读取的来源：

harness/downstream-contract.yaml

→

layout_map

。规则：涉及 downstream 的路径必须通过

harness/scripts/overstack_paths.py

（engine）或

hooklib.overstack_dir/harness_dir/stamp_path

（hook）处理；如果硬编码路径，

bare_path_lint

将失败。真实行为测试：

bash harness/tests/dot-layout-runtime-test.sh .

（使用 dot fixture 和隔离的 HOME）。注意：

rg

/Grep 会忽略点号开头的目录——检查 downstream 项目时应使用

--hidden

。

Distill / author một skill (dùng ở project bất kỳ)

Distill / author 一个 skill（可用于任意项目）

Skill native theo chuẩn solid-what-how/1 (SWH): frontmatter
```
name
```
+
```
description
```
+
```
metadata.design-standard: "solid-what-how/1"
```
, rồi ## WHAT
(purpose/trigger/non-goals · mental model · input/output contract · rules có ID · failure boundaries) và ## HOW
(bảng main workflow W01… có exit/next · branches hoặc ghi rõ "không có nhánh phụ" · validation/stopping · ví dụ positive + boundary). Khung đầy đủ: concept
```
solid-what-how
```
(repo framework) hoặc sinh bằng
```
new-skill.py
```
.
```
description
```
phải đủ trigger — nêu rõ KHI NÀO gọi (từ khoá, tình huống); đây là thứ router dùng để chọn skill.
Tìm mẫu trước khi viết (Reuse Layer SWH v1.1) nếu có catalog:
```
python3 fdk/tools/skill-reuse.py search --desc "<việc>"
```
→ khớp contract thì
```
new-skill.py <tên> --from <asset_id> --params p.json
```
(render template typed + pin sha256); không khớp thì scratch kèm
```
--reason
```
. Mỗi lần tạo skill đều để lại
```
reuse_decision
```
; reuse không miễn cổng nào.
Kiểm hình dạng nếu có tool:
```
python3 fdk/tools/swh-lint.py --skills <tên> --ci
```
(cấu trúc thôi; hành vi vẫn phải thử bằng câu mẫu). Skill kéo từ upstream nằm ở
```
skills/external/
```
, không viết lại theo SWH.
Giữ self-contained: đừng trỏ tới file chỉ có ở 1 repo; nếu cần thì ghi "nếu file X có mặt thì…".
Sau khi viết: thử 1–2 câu mẫu xem skill có được trigger đúng không.

Skill 必须原生遵循 **solid-what-how/1（SWH）**标准：frontmatter 包含
```
name
```
+
```
description
```
+
```
metadata.design-standard: "solid-what-how/1"
```
，然后是 ## WHAT
（purpose/trigger/non-goals · mental model · input/output contract · 带 ID 的 rules · failure boundaries）以及 ## HOW
（包含 exit/next 的 main workflow W01… 表 · branches 或明确说明“无分支” · validation/stopping · positive + boundary 示例）。完整框架：framework repo 中的 concept
```
solid-what-how
```
，或使用
```
new-skill.py
```
生成。
```
description
```
必须包含充分的触发信息——明确说明何时调用（关键词、场景）；router 会使用该信息选择 skill。
编写前先查找可复用内容（Reuse Layer SWH v1.1）；如果存在 catalog：
```
python3 fdk/tools/skill-reuse.py search --desc "<việc>"
```
→ 如果 contract 匹配，则执行
```
new-skill.py <tên> --from <asset_id> --params p.json
```
（render 类型化 template 并固定 sha256）；如果不匹配，则使用 scratch 并附带
```
--reason
```
。每次创建 skill 都必须留下
```
reuse_decision
```
；reuse 不适用任何豁免。
如果存在相应工具，检查结构：
```
python3 fdk/tools/swh-lint.py --skills <tên> --ci
```
（这里只检查结构；行为仍必须使用示例输入测试）。从 upstream 引入的 skill 位于
```
skills/external/
```
，不要按照 SWH 重写。
保持自包含：不要引用只存在于某一个 repo 的文件；如果确有需要，请写成“如果文件 X 存在，则……”。
编写完成后：使用 1–2 条示例输入测试 skill 是否能被正确触发。

Reference — Inventory — đừng tin số nhớ, đếm LIVE (path tuỳ layout repo)

参考——Inventory——不要相信记忆中的数字，始终进行 LIVE 统计（路径取决于 repo layout）

bash

ls -d skills/*/ 2>/dev/null | wc -l                                   # số skill
ls harness/validators/*.py 2>/dev/null | wc -l                        # số validator
grep -cE 'id: R' harness/poc-vendor-neutral/policy.yaml 2>/dev/null   # số rule

bash

ls -d skills/*/ 2>/dev/null | wc -l                                   # số skill
ls harness/validators/*.py 2>/dev/null | wc -l                        # số validator
grep -cE 'id: R' harness/poc-vendor-neutral/policy.yaml 2>/dev/null   # số rule

Reference — Problem-tree — sổ vấn đề CHUNG của cả framework (không riêng /fdk)

参考——Problem-tree——整个 framework 的问题总账（不是仅供 /fdk 使用）

llmwiki/html/fdk-problem-tree.html

là ledger duy nhất cho MỌI vấn đề framework — bất kỳ skill/phiên nào chạm việc framework (propose, harness-update, orca-workflow…) phát hiện hay giải một vấn đề đều phải cập nhật nó; /fdk là người gác: mỗi lần /fdk được gọi, TRƯỚC KHI kết thúc turn phải rà và cập nhật cây (tạo từ template nếu chưa có; không ở repo framework nhưng project có

llmwiki/

thì dùng path project-local cùng tên):

Dạng: single-file HTML style /docs-site-macos (liquid-glass). Nội dung = cây vấn đề — mỗi node là một bài toán gặp trong session; node nối cha→con bằng SVG connector do JS tự vẽ (đo
```
getBoundingClientRect
```
, vẽ lại khi resize) — không hardcode toạ độ.

Data tách khỏi markup: toàn bộ node nằm trong một block

<script type="application/json" id="tree-data">

; mỗi lần update chỉ thêm/sửa JSON, không đụng markup. Mỗi node:

{id, parent, title, desc, status: solved|partial|open, scope: "full" | ["harness"|"skills"|"llmwiki"...], date, solvedBy?, session?}

Scope là biến cố định theo 3 trụ:
```
"full"
```
= giải trọn cả 3 trụ (harness + skills + llmwiki); còn không thì liệt kê danh sách trụ đã phủ (vd
```
["skills"]
```
= mới giải ở tầng skill).
```
status: solved
```
mà
```
scope
```
chưa full thì cây phải hiện rõ "solved x/3 trụ" — không được đọc nhầm thành giải trọn.
Append-only về lịch sử: không xoá node cũ; vấn đề được giải thì đổi
```
status
```
+ ghi
```
solvedBy
```
(giải bằng skill/rule/commit nào).
Màu theo ĐỘ PHỦ, không theo status: xanh lá CHỈ khi giải trọn 3/3 trụ; thang nghiêm-trọng-giảm-dần: 0/3 (chưa có gì — nghiêm trọng nhất) = đỏ
```
#ef4444
```
→ 1/3 = cam
```
#f97316
```
→ 2/3 = vàng
```
#eab308
```
→ 3/3 = xanh lá
```
#22c55e
```
. Badge ghi kèm x/3. Không bao giờ tô xanh lá cho thứ mới giải một phần.

llmwiki/html/fdk-problem-tree.html

是所有 framework 问题的唯一 ledger——任何触及 framework 工作的 skill/会话（propose、harness-update、orca-workflow 等），无论发现还是解决问题，都必须更新它；/fdk 负责维护：每次调用 /fdk 时，在结束 turn 前必须检查并更新该树（如果不存在，则根据 template 创建；如果当前不在 framework repo，但项目包含

llmwiki/

，则使用项目内具有相同名称的 project-local 路径）：

形式：采用 /docs-site-macos 风格的单文件 HTML（liquid-glass）。内容为问题树——每个 node 代表会话中遇到的一个问题；node 通过由 JS 自动绘制的 SVG connector 连接父节点与子节点（测量
```
getBoundingClientRect
```
，在 resize 时重新绘制）——不得硬编码坐标。

**数据与 markup 分离：**所有 node 都放在一个

<script type="application/json" id="tree-data">

块中；每次更新只添加/修改 JSON，不触碰 markup。每个 node：

{id, parent, title, desc, status: solved|partial|open, scope: "full" | ["harness"|"skills"|"llmwiki"...], date, solvedBy?, session?}

。

Scope 是固定的三支柱变量：
```
"full"
```
表示完整解决三个支柱（harness + skills + llmwiki）；否则必须列出已覆盖的支柱，例如
```
["skills"]
```
表示目前只在 skill 层解决。如果
```
status: solved
```
但 scope 尚未覆盖全部支柱，树必须明确显示“已解决 x/3 个支柱”，不得被误读为已完整解决。
**历史采用 append-only 方式：**不得删除旧 node；问题解决后，更新
```
status
```
并记录
```
solvedBy
```
（说明通过哪个 skill/rule/commit 解决）。
**颜色反映覆盖程度，而不是 status：**只有完整覆盖 3/3 个支柱时才能使用绿色；严重程度按覆盖程度递减：0/3（尚未解决任何部分——最严重）= 红色
```
#ef4444
```
→ 1/3 = 橙色
```
#f97316
```
→ 2/3 = 黄色
```
#eab308
```
→ 3/3 = 绿色
```
#22c55e
```
。Badge 同时标注 x/3。对于只解决部分问题的新增节点，绝不能涂成绿色。

Adapt vào overstack remote — khi đang dev TỪ một dự án khác

适配 overstack remote——从其他项目进行开发时

Đang dở dự án khác mà muốn chưng cất một skill rồi đẩy vào overstack?

fdk-gate

fdk/tools

KHÔNG có ở dự án đó (cố ý — ADR-004), nên kéo kit về sandbox rồi submit bằng PR — đừng sửa tay lung tung:

Pull kit (lần đầu — chạy thẳng từ remote, không cần file local):
bash
```
bash <(curl -fsSL https://raw.githubusercontent.com/Rheinmir/setup/orca/fdk/tools/fdk-kit.sh) pull
```
→ clone overstack vào
```
.overstack-kit/
```
(tự thêm vào
```
.gitignore
```
, KHÔNG đụng dự án của bạn).
Distill skill TRONG kit:
```
cd .overstack-kit && python3 fdk/tools/new-skill.py <tên>
```
→ viết
```
SKILL.md
```
→ register (mirror + LOOP_MAP + bảng AGENT/CLAUDE + CAPABILITIES — pre-flight #3 + checklist).

Check:

bash .overstack-kit/fdk/tools/fdk-kit.sh check

—

fdk-gate

đủ 15 bước mới hợp lệ.

Submit (TỰ mở PR):

bash .overstack-kit/fdk/tools/fdk-kit.sh submit skill/<tên> "<mô tả>"

→ gate xanh → push branch →

gh pr create

vào

orca

Đang Ở TRONG repo overstack thì bỏ qua bước pull —

fdk-kit check

submit

chạy thẳng trên repo.

正在开发其他项目，希望沉淀一个 skill 并推送到 overstack？该项目中故意不提供

fdk-gate

fdk/tools

（ADR-004），因此应将 kit 拉取到 sandbox，再通过 PR 提交——不要直接随意修改：

Pull kit（首次操作——直接通过 remote 运行，不需要本地文件）：
bash
```
bash <(curl -fsSL https://raw.githubusercontent.com/Rheinmir/setup/orca/fdk/tools/fdk-kit.sh) pull
```
→ 将 overstack clone 到
```
.overstack-kit/
```
（自动添加到
```
.gitignore
```
，不会影响你的项目）。
在 kit 中 distill skill：
```
cd .overstack-kit && python3 fdk/tools/new-skill.py <tên>
```
→ 编写
```
SKILL.md
```
→ 注册（mirror + LOOP_MAP + AGENT/CLAUDE 表 + CAPABILITIES——pre-flight 第 3 步 + checklist）。

Check：

bash .overstack-kit/fdk/tools/fdk-kit.sh check

——

fdk-gate

完成全部 15 个步骤后才有效。

Submit（自动创建 PR）：

bash .overstack-kit/fdk/tools/fdk-kit.sh submit skill/<tên> "<mô tả>"

→ gate 通过 → push branch → 使用

gh pr create

向

orca

创建 PR。

如果当前位于 overstack repo 内，则跳过 pull 步骤——直接运行

fdk-kit check

submit

。

Nếu đang TRONG repo framework (Rheinmir/setup) — bản đầy đủ

如果当前位于 framework repo（Rheinmir/setup）内——完整版本

Các file dưới đây CHỈ có trong repo framework, KHÔNG distribute xuống project khác (cố ý — ADR-004). Khi có mặt thì đọc để lấy bản chi tiết:

```
fdk/wiki/concepts/fdk.md
```
— front-door đầy đủ (pre-flight + module map theo loại).
```
fdk/docs/CONTRIBUTING.md
```
— runbook thêm/sửa rule harness (content-check / hook-event / process-gate; số kế tiếp R13).

fdk/README.md

fdk/tools/

— kit folder (vd

build-cheatsheet.py

Sửa SKILL.md xong →
bash fdk/tools/sync-skill.sh <tên>
— đồng bộ canonical → mirror llmwiki + bản cài
```
~/.claude
```
trong 1 lệnh, tự verify parity. ĐỪNG cp tay từng bản (nguồn drift — eval 020726).
```
llmwiki/html/*-fdk-docs.html
```
— bản đọc HTML.

以下文件仅存在于 framework repo，不会分发到其他项目（这是有意设计，ADR-004）。文件存在时，应阅读并获取更多细节：

```
fdk/wiki/concepts/fdk.md
```
——完整 front-door（pre-flight + 按类型划分的 module map）。
```
fdk/docs/CONTRIBUTING.md
```
——添加/修改 rule harness 的补充 runbook（content-check / hook-event / process-gate；下一个编号为 R13）。

fdk/README.md

fdk/tools/

——kit 目录（例如

build-cheatsheet.py

）。

修改 SKILL.md 后执行
bash fdk/tools/sync-skill.sh <tên>
——通过一条命令将 canonical 版本同步到 llmwiki mirror 和安装到
```
~/.claude
```
的版本，并自动验证 parity。不要逐个手工 cp（这会成为 drift 来源——eval 020726）。
```
llmwiki/html/*-fdk-docs.html
```
——HTML 阅读版本。