SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsfdk

fdk

General & other

View repository

Updated 10-15 22:33

About this skill

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

On-demand: does NOT auto-inject at session start (most sessions are other project dev). This skill is self-contained enough guidance to run in any project; the "full version" section at the end applies ONLY WHEN you are inside the framework repo.

WHAT

Purpose and context

  • Purpose: front-door on-demand, self-contained for editing the framework ITSELF or distilling/authoring a skill in any project: pre-flight before any change, ship/HTML rules, downstream map, and problem-tree guardrails.
  • Trigger (when to use):
    • Editing the framework ITSELF (skill / rule / validator / hook / wiki), OR
    • Distilling / authoring a skill in any project's session.
  • Non-goals: NOT used for normal project feature dev (that is most sessions — ADR-004); does not auto-fire at session start.

Default mindset — Donella Meadows: fix the SYSTEM, not the symptom

Every framework task goes through the lens of systems thinking & feedback loops (systems thinking, Thinking in Systems):

  • Hit a bug/problem → ask "what structure produces it?" before patching the sore spot. A recurring symptom is a signal of a missing or wrong feedback loop — manually patching the same kind of bug a 2nd time is a process error; the right thing is to change the structure (rule harness, skill, template, hook) so that kind of bug cannot re-emerge. (This is exactly what the failure-flywheel and problem-tree are doing.)
  • Choose the highest leverage point at the lowest cost, per the Meadows ladder: changing parameters < adding feedback loops < changing information flows < changing the rules of the game < changing the goal/paradigm. Before coding, ask yourself: which rung is this fix on? Is there a cheaper higher rung? (E.g.: instead of telling the agent to remember — a low rung — add a self-biting validator — changing the rules of the game.)
  • Nurture feedback loops, don't just fire one shot: every change must have a signal path back (deterministic verify, ledger, log, eval) so the system can see itself drift. A change with no feedback loop = a blind change.
  • Respect delays: the effect of a new rule/skill only shows up after many sessions — don't conclude too early, and don't pile on another fix before the previous one has had time to take effect; date it in the ledger to measure.

2nd guiding principle — Hub & presentation (UX for the user, feedback 2026-07-03)

Alongside the Meadows mindset, every framework tool/skill/hub follows the user's usable-and-safe principle:

  • Hub with 1 name, scope-described — don't force memorizing many subcommands. One hub does ALL related work; the user just describes scope (all > 1 part / equivalent part / level), not have to remember subcommand. Command names must be SHORT, typeable by muscle memory (user is used to curl; hard-to-remember names = never get called → useless). Eg medic (overall health gate) instead of long names.
  • TL;DR — the part the user reads concisely + with ENOUGH meaning, not stingy. Users have the "too long didn't read" habit: short but not cut off, not skimping on explanation.
  • Transparent thinking model — the user reads the think part to check the direction. Don't hide reasoning.
  • End of output: inject recap + teach passive usage — concisely restate what this tool does + hint at typical AND surprising use-cases (ones the user didn't expect to be usable) → the user learns how to use it without having to ask.
  • Transparency = safety; usage > performance. Let the user READ the folder structure + under-the-hood, not just optimize for the query. If it's displayed, it's transparent → the user feels safe using the system. Prioritize usability over hidden optimization.

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 and output contract

Field Required? Meaning
In the framework or skill that needs distilling yes the user's description
In current repo (framework or another project) yes decide whether to use the full version or the kit
Out draft proposal awaiting approval, then verified surgical changes yes no coding directly
Out llmwiki/html/fdk-problem-tree.html reviewed/updated yes on every call before ending the turn
Out PR via the kit when dev from another project fdk-kit.sh submit

Rules and capabilities

  • RULE-01 (MUST): BEFORE shipping push/PR — run python3 fdk/tools/ci-local.py (all steps run: of every GitHub workflow locally, L4). L2 (pre-commit/medic) is NOT equal to L4 (CI fresh-clone): there are gates that ONLY run on CI, or auto-fix in the Stop hook, so commit-then-push-immediately passes L2 while CI goes red (already burned: R3 index-sync 2026-07; search-index + skill-provenance 2026-09-08). Only push when everything is green; then /fdk-uat (canary + main-URL smoke) before reporting done. See [[harness-enforcement-floor]].
  • RULE-02 (MUST): DO NOT write AI credit — commit message / PR / code / wiki must NOT insert Co-Authored-By: Claude…, Generated with Claude Code, 🤖, or any credit/attribution to AI. Author & committer are only the user's identity. If the template/tool generates a credit trailer, remove it before committing.
  • RULE-03 (MUST): On-demand only — do not register an auto-fire hook at the start of the session (ADR-004).
  • RULE-04 (MUST): Self-contained — the part above (pre-flight + distill + inventory) is enough to run in another project; the "full version" section only applies WHEN those files exist. Never assume a repo-local file is present.
  • RULE-05 (MUST): Counts are always LIVE; no hardcoding (anti-drift).
  • RULE-06 (MUST): HTML for HUMAN readers must explain terminology — content displayed in report/visualization (title, node descriptions, captions) is written in plain Vietnamese; specialized terminology must come with a short explanation in parentheses at its first occurrence (e.g.: "flush (xả sổ — tự ghi trước khi thoát)", "untracked (file git chưa theo dõi)"). Do not use bare jargon for viewers — bare jargon is only allowed in machine-read files.
  • RULE-07 (MUST): HTML for viewers must have a light/dark TOGGLE (feedback 2026-07-06 — second reminder, do not repeat) — every HTML file generated for HUMAN viewing (report, tree, dashboard, docs, proposal render…) must have a dark/light toggle button: prefers-color-scheme is only the initial default, when the user clicks the toggle it overrides via html[data-theme] + saves localStorage (with an anti-FOUC script in head). Do NOT force a single mode. Mandatory form: a labeled SWITCH, in a footer row pinned to the bottom of the sidebar/nav — NOT icon chips scattered in corners. Standard snippet: skill docs-site-macos § "Theme Toggle sáng/tối"; reference generator _DARK_RULES in fdk/tools/build-overstack-docs.py (a single source emits 2 blocks, anti-drift).
  • RULE-08 (MUST): Mode switching MUST go through circle-reveal, not an instant flip (feedback 160926, task T-260916-01) — after clicking the switch, a circular overlay opens with background color = TARGET MODE, radiating from the exact coordinates of the button, spreading slowly then fast-and-decisive to cover the viewport, THAT is when data-theme/localStorage changes value, then the overlay fades. Respect prefers-reduced-motion: reduce (fallback to crossfade ≤150ms, not 0 motion). Standard snippet: skill docs-site-macos § "Theme Toggle sáng/tối" section 4; acceptance via node skills/docs-site-macos/scripts/verify-theme-motion.mjs <file.html> (real Playwright, not the model self-attesting).
  • RULE-09 (MUST): HTML for viewers: COMPACT FONT SCALE for 13″ screens (feedback 2026-07-06) — DECREASE sizes rather than increase: body ~13.5px, nav 12px, list/table 12.5px, labels 10–10.5px; increasing font size makes 13″ screens worse (less content, tight wrapping). Readability = line-height/contrast, not big fonts. Details: docs-site-macos § Best Practices.
  • RULE-10 (MUST): HTML report/visualization must SHOW FULL PATH — every HTML file generated for viewing (report, tree, dashboard, proposal render…) must display its own absolute path right on the page (footer or titlebar, in the form <code> copyable), so viewers know where the file is to reopen/edit it. After generating the file, the real path must be filled in, not a placeholder.
  • Capabilities: read/write framework repo or sandbox kit; run local gate/test; create PR via authenticated CLI.

Failure boundaries

  • No approval for draft → blocked at pre-flight #4, no code.
  • ci-local.py red → no push (RULE-01).
  • Repo-local file not present (currently in another project) → drop the "full version" item, do not assume (RULE-04).
  • fdk-kit.sh check not enough 15 steps → do not submit.

HOW

Main workflow

Step Type Inputs Action Outputs/exit Failure/next
W01 effect base remote Pull before editing latest version —
W02 deterministic harness Know the rules (rule-registry / policy.yaml) rule list no harness → universal rules
W03 deterministic module name Grep the name; shared code → impact-check then safe-change no duplicate duplicate → edit the old module
W04 judgment change Propose draft, STOP and wait for approval approved not approved → blocked
W05 effect approved draft Surgical → verify → record trace (B01–B03 by work type) change + green tests red → fix, loop
W06 deterministic touched path Check the downstream map before touching a hook/engine/installer/CI path path passes overstack_paths.py bare_path_lint red → fix
W07 effect issue in session Review + update problem-tree before ending the turn tree updated not present → create from template

Details for each step (source of truth for W01–W06, Pre-flight):

  1. Pull before editing — sync the base, don't work on an old version.
  2. Know the rules — if the repo has a harness: see rule-registry / policy.yaml. Universal rules always hold: wiki files must have ## Origin; do not record raw/; wiki files must be in the correct subfolder (concepts/entities/sources/draft/…); proposals must have the full pair .md+.html.
  3. Don't step on old modules — before creating a new skill/validator/script/hook, grep the name to see if it already exists; when editing shared code, map callers first (impact-check) then safe-change.
  4. Propose first — every change → draft plan, STOP and wait for approval; do not code directly.
  5. Surgical → verify → record trace — only touch what must be touched; run tests/drift-tests; update registry/log. For commit, explicit pathspec stage, not git add -A/./commit -a: multiple sessions share the same tree, staging in bulk sweeps up another session's work in progress (rule P1 no-bulk-stage blocks in framework repos).
  6. Client machine layout ≠ repo layout — before touching a path in a hook/engine/installer/CI: read the "Downstream map" section below; bare paths llmwiki/ harness/ are ONLY correct in this repo.

Branches

ID Kind Guard Behavior Skip / failure Rejoin
B01 conditional_required the task is to distill/author a skill per the "Distill / author a skill" section — W06
B02 conditional_required developing from another project, without fdk/tools kit: pull → distill in kit → check → submit PR inside the overstack repo → skip the pull step W07
B03 capability_optional currently INSIDE the framework repo (full-version file is present) read the full version; after editing SKILL.md → sync-skill.sh file absent → skip W06
B04 conditional_required about to ship push/PR ci-local.py then /fdk-uat (RULE-01) red → do not push W07

Validation and stopping

Deterministic checks: tests/drift-tests, swh-lint.py for skills, ci-local.py, fdk-kit.sh check, verify-theme-motion for HTML. Human approval needed: draft propose at W04. End the turn only after reviewing the problem-tree (W07).

Examples

  • Positive: "/fdk add a new probe for medic" in the framework repo → pull, grep medic.py (do not spawn ad-hoc tools), draft awaiting approval → surgical edit + test → ci-local.py green before push → add problem-tree node status: solved, scope: ["harness"] shows "solved 1/3 pillars" in orange.
  • Boundary/failure: currently in another project, wants to push a just-distilled skill into overstack but types python3 fdk/tools/new-skill.py → file does not exist (ADR-004) → switch to B02: pull the kit into .overstack-kit/, distill in the kit, fdk-kit.sh check then submit.

Reference — Downstream map — what you are seeing is NOT what runs on the client machine

Framework repo (currently open) Client machine after curl bootstrap.sh Note
llmwiki/ .llmwiki/ wiki · raw · html · .harness-stamp
harness/ .harness/ only poc-vendor-neutral/ + foundation.yaml + metrics/; there is NO scripts/ validators/
harness/scripts · harness/validators · fdk/tools · llmwiki/.claude/hooks ~/.claude/harness/ (global) shared engine; hooks fire from ~/.claude/settings.json
fdk/wiki/ none framework_only
skills/*/SKILL.md ~/.claude/skills/ via npx, not located in the project repo
none CAPABILITIES.md · .overstack.yaml · root .claude/settings.json only present downstream

Machine-readable source: harness/downstream-contract.yaml → layout_map. Rule: a path that touches downstream goes through harness/scripts/overstack_paths.py (engine) or hooklib.overstack_dir/harness_dir/stamp_path (hook); bare_path_lint red if hardcoded. Real behavior test: bash harness/tests/dot-layout-runtime-test.sh . (dot fixture, isolated HOME). Remember: rg/Grep skips dot directories — use --hidden when inspecting a downstream project.

Distill / author a skill (usable in any project)

  • Native skill per the solid-what-how/1 (SWH)standard: frontmatter name + description + metadata.design-standard: "solid-what-how/1", then ## WHAT (purpose/trigger/non-goals · mental model · input/output contract · rules with IDs · failure boundaries) and ## HOW (main workflow table W01… with exit/next · branches or explicitly state "no sub-branches" · validation/stopping · positive + boundary examples). Full skeleton: concept solid-what-how (framework repo) or generate with new-skill.py.
  • description must have enough trigger — state clearly WHEN to call it (keywords, situations); this is what the router uses to select the skill.
  • Find a template before writing (SWH v1.1 Reuse Layer) if a catalog exists: python3 fdk/tools/skill-reuse.py search --desc "<việc>" → if the contract matches, new-skill.py <tên> --from <asset_id> --params p.json (render typed template + pin sha256); if not, scratch with --reason. Every skill creation leaves behind reuse_decision; reuse does not exempt any gate.
  • Check the shape if a tool exists: python3 fdk/tools/swh-lint.py --skills <tên> --ci (structure only; behavior must still be tested with sample sentences). A skill pulled from upstream lives in skills/external/, not rewritten per SWH.
  • Keep self-contained: do not point to a file that exists in only 1 repo; if needed, write "if file X is present then…".
  • After writing: try 1–2 sample sentences to see whether the skill is triggered correctly.

Reference — Inventory — don't trust remembered numbers, count LIVE (path depends on repo layout)

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 — the SHARED problem log of the whole framework (not just /fdk)

llmwiki/html/fdk-problem-tree.html is the single ledger for ALL framework problems — any skill/session that touches framework work (propose, harness-update, orca-workflow…) and finds or solves a problem must update it; /fdk is the gatekeeper: every time /fdk is called, BEFORE ending the turn it must review and update the tree (create from template if absent; if not in the framework repo but the project has llmwiki/ then use the project-local path with the same name):

  • Form: single-file HTML styled /docs-site-macos (liquid-glass). Content = problem tree — each node is a problem encountered in a session; nodes connect parent→child with SVG connectors drawn automatically by JS (measure getBoundingClientRect, redraw on resize) — no hardcoded coordinates.
  • Data separated from markup: the entire node lives in one block <script type="application/json" id="tree-data">; each update only adds/edits JSON, does not touch markup. Each node: {id, parent, title, desc, status: solved|partial|open, scope: "full" | ["harness"|"skills"|"llmwiki"...], date, solvedBy?, session?}.
  • Scope is a variable fixed by 3 pillars: "full" = solving all 3 pillars (harness + skills + llmwiki); otherwise list the pillars covered (e.g. ["skills"] = only solved at the skill layer). status: solved but scope is not full, the tree must clearly show "solved x/3 pillars" — it must not be misread as fully solved.
  • Append-only for history: do not delete old nodes; when a problem is solved, change status + record solvedBy (solved by which skill/rule/commit).
  • Color by COVERAGE, not by status: green ONLY when all 3/3 pillars are solved; severity scale descending: 0/3 (nothing yet — most severe) = red #ef4444 → 1/3 = orange #f97316 → 2/3 = yellow #eab308 → 3/3 = green #22c55e. Badge also shows x/3. Never color green something that is only partially solved.

Adapt into overstack remote — when developing FROM another project

In the middle of another project but want to distill a skill and push it into overstack? fdk-gate + fdk/tools is NOT present in that project (intentional — ADR-004), so pull kit to a sandbox and submit via PR — do not edit by hand randomly:

  1. Pull kit (first time — run directly from remote, no local file needed): 
    bash <(curl -fsSL https://raw.githubusercontent.com/Rheinmir/setup/orca/fdk/tools/fdk-kit.sh) pull
    → clone overstack into .overstack-kit/ (automatically adds to .gitignore, does NOT touch your project).
  2. Distill skill IN the kit: cd .overstack-kit && python3 fdk/tools/new-skill.py <tên> → write SKILL.md → register (mirror + LOOP_MAP + AGENT/CLAUDE table + CAPABILITIES — pre-flight #3 + checklist).
  3. Check: bash .overstack-kit/fdk/tools/fdk-kit.sh check — fdk-gate all 15 steps must be complete to be valid.
  4. Submit (OPEN the PR yourself): bash .overstack-kit/fdk/tools/fdk-kit.sh submit skill/<tên> "<mô tả>" → gate green → push branch → gh pr create into orca.

If you are INSIDE the overstack repo, skip the pull step — fdk-kit check / submit runs directly on the repo.

If you are INSIDE the framework repo (Rheinmir/setup) — full version

The files below exist ONLY in the framework repo, are NOT distributed to other projects (intentional — ADR-004). When present, read them for the detailed version:

  • fdk/wiki/concepts/fdk.md — full front-door (pre-flight + module map by type).
  • fdk/docs/CONTRIBUTING.md — runbook for adding/editing rule harness (content-check / hook-event / process-gate; next number R13).
  • fdk/README.md + fdk/tools/ — kit folder (e.g. build-cheatsheet.py).
  • After editing SKILL.md → bash fdk/tools/sync-skill.sh <tên> — sync canonical → llmwiki mirror + installed copy ~/.claude in 1 command, auto-verifies parity. Do NOT cp each copy by hand (source of drift — eval 020726).
  • llmwiki/html/*-fdk-docs.html — HTML reading version.