Kungfu UNGFU™Developer Platform

Back to libkungfu.devKung Fu Decisions

KFD — Kung Fu Decisions

Start here · 10-minute model

The agent is not the center of truth.

What must remain continuous when the agent, session, repository, authority, or execution path changes—but the work continues?

  • running != authorized
  • retry != same attempt
  • same output != same result
  • success != admitted Fact

One real delivery broke all four equivalences. Following it from healthy action through authority loss, rejected recovery, a valid successor, and settlement reveals why KFD separates Fact, Episode, Atlas, Pursuit, and Warrant—and why the agent is a participant in the work, not its center of truth.

See the real failure that forces this model → Read the foundation model

KFD is an open, evidence-governed engineering standard for preserving facts, boundaries, perspective, and responsibility when the path is not known in advance.

KFD is independent of Kungfu. Kungfu is its founding implementation, not a required dependency.

Implement and verify KFD independently

See the contract succeed. Then implement your own Hub.

Implement KFD without Kungfu — scaffold an adapter in Python, Rust, Node.js, or C++, then verify it offline. The paths differ: a generated starter is not conforming.

Read every result on three axes

Behavior, evidence, and authority answer different questions.

behavior

Does the adapter implement the fixed Hub semantics?

Starter
0/20
Reference
20/20

evidence

Can the report, roots, outcomes, and adapter bytes be recomputed offline?

Starter
valid
Reference
valid

authority

Does this result grant qualification or certification?

Starter
qualifying=false; certification=false
Reference
qualifying=false; certification=false

An implementation can fail while that failure remains independently verifiable. Neither valid evidence nor 20/20 grants authority.

Path 1 · start here

Two-minute understanding path

Run the packaged non-product reference adapter so the complete evidence loop is visible before you write code.

npx --yes --package @kungfu-tech/kfd@1.0.0-alpha.67 kfd demo agent-hub --output agent-hub-demo-report.json

Expected: exit 0 · 20/20 · evidence valid

Behavior: 20/20 (conforming)
Evidence: valid (adapter bytes checked)
Authority: qualifying=false; certification=false
Need the complete machine result?

Add --json; the human command above stays concise by default.

npx --yes --package @kungfu-tech/kfd@1.0.0-alpha.67 kfd demo agent-hub --output agent-hub-demo-report.json --json

One failure that explains the model

callSucceeded: true does not imply completion.

Hub 20 expects rejected / completion-unproved / rejected, because a successful call is not evidence that the Pursuit completed.

Boundary: The packaged reference adapter demonstrates the contract. It is non-product code and is not adopter evidence or certification.

Path 2 · build yours

Implement your own adapter

  • Python
  • Rust
  • Node.js
  • C++

  1. Scaffold

    Generate a deterministic fail-closed starter. No Hub semantics are implemented yet.

    npx --yes --package @kungfu-tech/kfd@1.0.0-alpha.67 kfd scaffold agent-hub --language python --output my-agent-hub-adapter

    Expected: exit 0 · new directory created

  2. Run starter smoke

    Check only the jsonl-stdio/v1 request and response envelope.

    python3 my-agent-hub-adapter/smoke.py

    Expected: exit 0 · envelope pass

  3. Understand the Hub model

    Read what the eight semantic categories protect before writing product decisions.

  4. Implement Hub semantics

    Replace evaluate() with product-owned behavior for the fixed scenarios. KFD cannot supply your product decisions.

    my-agent-hub-adapter/adapter.py → evaluate()

    Target before claiming conformance: 20/20

  5. Test Hub 20

    Run the fixed suite against your adapter bytes. The unmodified starter deliberately returns scenario-not-implemented.

    npx --yes --package @kungfu-tech/kfd@1.0.0-alpha.67 kfd test agent-hub --adapter ./my-agent-hub-adapter/adapter.py --output agent-hub-report.json

    Untouched starter: exit 1 · 0/20 · report.valid=false

  6. Verify report offline

    Recompute the retained report and root closure, optionally including adapter bytes. This does not rerun the adapter or certify production fitness.

    npx --yes --package @kungfu-tech/kfd@1.0.0-alpha.67 kfd verify agent-hub-report agent-hub-report.json --adapter ./my-agent-hub-adapter/adapter.py

    Expected: exit 0 · verification.valid=true · adapter bytes checked

Why 0/20 is expected: the untouched scaffold returns scenario-not-implemented for all fixed scenarios. It fails closed so transport success cannot be mistaken for Hub semantics.

Behavior: 0/20 (not conforming)
Evidence: valid (adapter bytes checked)
Authority: qualifying=false; certification=false
Inspect the complete verifier JSON

Add --json to the verify command after the concise human result makes the three axes clear.

npx --yes --package @kungfu-tech/kfd@1.0.0-alpha.67 kfd verify agent-hub-report agent-hub-report.json --adapter ./my-agent-hub-adapter/adapter.py --json

What “Hub semantics” means

Eight responsibilities, exercised by 20 fixed scenarios.

The adapter must make product-owned decisions for these boundaries. KFD supplies the shared questions and expected distinctions; it does not supply your Hub’s storage, policy, or business behavior.

Explore the eight responsibility categories

Negotiation 3 vectors

Both Hubs agree on the exact profile, required features, and semantic root before exchange.

Delivery 5 vectors

Delivery stays separate from admission, while duplicates, idempotency conflicts, and delays remain explicit.

Authority 3 vectors

Delegation can narrow but cannot silently amplify or outlive a revoked Warrant.

Conflict 2 vectors

Concurrent disagreement stays visible instead of disappearing behind last-write-wins.

Knowledge 3 vectors

Partial, intentionally withheld, and unavailable knowledge remain different states.

Completion 1 vector

A successful call cannot be promoted into proof that the Pursuit completed.

Recovery 1 vector

Offline divergence is surfaced when Hubs reconnect instead of being overwritten.

Portability 2 vectors

Export and import preserve semantic roots and reject meaning-changing drift.

See all 20 scenarios and expected outcomes Open the adapter contract

What you gain: A bounded, artifact-linked answer to whether two independently owned Hubs preserve meaning when Work crosses their boundary.

Install the native offline verifierOptional evidence tooling · no coding required

experimental · governed self-change

How KFD changes itself

How should a reader connect KFD's live governance gate with its reconstructed history without granting either lane authority it does not have?

Live gate

Prospective governance

Official Candidate genesis, qualification, numbering, status, Foundation Revision, and release-packaging transitions under the live Profile.

Gate: The applicable live Self-Conformance gate must pass before an official lifecycle transition proceeds.

Edit boundary: Ordinary repository edits do not silently become lifecycle transitions.

Historical replay

Retrospective structural conformance

Starts at v1.0.0-alpha.28 and converges additively with kfd-alpha-55-pre-profile.

retrospective: true · profileAvailableAtEvent: false

Historical boundary: This later structural replay does not project the Profile into historical events or retroactively approve, authorize, activate, certify, or change them.

Authority boundary: The verifier is necessary but not sufficient; accountable human approval remains required. It does not establish semantic truth, retroactive approval or authority, number allocation or status change, activation or certification, adoption or production fitness, publication or release authority.

Evidence and source details Expand evidenceCollapse evidence
Profile
kfd-self-conformance@1.0.0-alpha.1
Candidate
merged · non-normative · no allocated number
Case
closed · no-new-primitive
Open evidence Closed live case Live Self-Conformance Profile Historical lineage guide Historical lineage report Live Profile manifest

experimental adopter profile

Verify Agent Hub in the installed Kungfu product

kungfu agent hub qualify --output-dir <new-directory>

kungfu agent hub verify --qualification-dir <directory>

Understand and run the qualification

draft-interfaces machine interfaces

KFD-11–13 activation interfaces

The numbered KFD-11 through KFD-13 decisions remain authoritative and remain draft until a later explicit activation decision.

Inspect manifest Read schemas