fdk

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.

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.

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

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.

Kim chỉ nam thứ 2 — Hub & trình bày (UX cho user, feedback 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.

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.

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

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.

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.

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):

1. Pull trước khi sửa — đồng bộ base, đừng làm trên bản cũ.
2. 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.
3. Đừ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.
4. Propose trước — mọi thay đổi → draft kế hoạch, STOP chờ duyệt; đừng code thẳng.
5. 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).
6. 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.

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

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).

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.

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

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.

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

• 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.

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

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)

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.

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

Đ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:

1. Pull kit (lần đầu — chạy thẳng từ remote, không cần file local):

   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).
2. 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).
3. Check: bash .overstack-kit/fdk/tools/fdk-kit.sh check — fdk-gate đủ 15 bước mới hợp lệ.
4. 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.

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

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.