@agenticprimitives/devkit

Part of Agentic Primitives — the open-source trust substrate for agentic applications: identity that can sign, authority checked at act time, evidence the owner carries. Developer kit · All packages

The Developer Kit core — ap, the CLI that is the packages' own front door (spec 398 §10, spec 399 §3, ADR-0063).

npx ap doctor                          # every rule, this tree, the config it found
npx ap doctor --rule no-private-keys   # one rule; --json for a coding agent
npx ap doctor --rules --write          # project the rules source; pin digests in agentic.lock.json
npx ap upgrade --canary                # newest canary of every @agenticprimitives/* pin, one exact set
npx ap upgrade --pin 1.0.0-alpha.24    # or one named version / dist-tag
npx ap conform a2a https://…           # A2A 1.0 conformance (dispatches to @agenticprimitives/a2a)
npx ap test --live-gates live-gates.json
npx ap create my-product --template product-repo --pin 1.0.0-alpha.24

Doctor rules

Each rule is one file under src/rules/, data plus one pure judgement, parameterised by a config section. The ids are the ones spec 399 §2.3 gives to the root checks they replace:

| Rule | Twin (root check) | Enforces | | --- | --- | --- | | web-no-direct-mcp | check:no-direct-mcp-in-web | ADR-0044 — browser code reaches MCP only via /a2a/* | | no-private-keys | check:no-app-private-keys | no raw key material in app source; allow-list with reasons | | no-hmac-home-bridge | check:no-hmac-home-bridge | spec 341 ratchet — the bridge count only falls | | no-cross-subject-vault-reads | check:no-cross-subject-vault-reads | spec 366 R3 — reads only at the own subject | | fail-open-knobs | check:fail-open-knobs | ADR-0045 — every permissive knob allow-listed by name | | internal-marker-split | check:internal-marker-split | spec 341 §7 — marker ≠ custody secret | | custodian-coverage | check:custodian-coverage | specs 294/295 — provider-neutral custodian | | archetype-catalog | check:archetype-catalog | spec 354 §3 — catalog validates at recorded digests | | capability-vocabulary | check:capability-vocabulary | ADR-0051 — capability / protocol features / playbook | | demo-person-org-distinct | check:demo-person-org-distinct | ADR-0046 — person SA ≠ org SA | | rules-drift | — | 399 §3.4 — projections match the pinned source by digest | | lock-coherent | — | 399 §3.1 — exact, coherent @agenticprimitives/* pins |

Config resolution is one mechanism: ap.config.json#doctor, else agentic.lock.json#doctor, else the built-in reference layout of the agenticprimitives monorepo. A product repo gets its own section from create-app.

Exit codes: 0 clean · 1 findings · 2 usage or config · 3 a rule or dispatch errored. Error codes are stable strings (E_CONFIG, E_RULE_UNKNOWN, E_MODULE_ABSENT, …) so an agent branches on the code.

Rules projection

ap doctor --rules projects one rules source into .cursor/rules/*.mdc (frontmatter from rules/sidecar.json, body byte-for-byte) and into the <!-- ap:rules -->…<!-- /ap:rules --> block of AGENTS.md and CLAUDE.md. A file without the block is left alone. Digests are pinned in agentic.lock.json#rules; rules-drift fails when a projection or a pin no longer matches the source. In this monorepo the source is docs/architecture/agent-rules; a consumer uses the copy bundled in the package.

agentic.lock.json

{ "lockVersion": 1, "packages": { "@agenticprimitives/a2a": "1.0.0-alpha.24" }, "rules": { "skill-terminology": "sha256:…" }, "devkit": "…", "template": { "name": "product-repo", "revision": "…" }, "doctor": { … } }

packages is the coherent set ap upgrade maintains; rules the source digests; doctor the product's rule config (each section replaces the reference section whole).

Pinned definitions — ap upgrade stops for review (398 §10.3)

ap upgrade --pin-definitions <registry> agentic-trust/org-steward,agentic-trust/person-steward records, in agentic.lock.json#definitions, each archetype definition's digest and the authority shape of every tool (risk, action, requirement type, resource and authority args, approval policy, effects, idempotency). Every later ap upgrade reads the registry first: a wording change is a version bump; a change to any of those fields stops the upgrade with the change named per tool (treasury.payment.execute: authorityArg payer → org), and --accept-definitions re-pins once a reviewer has read it. The pin is a reviewer's memory, never a verifier's input.

The Developer MCP (ap mcp)

A coding agent's host spawns ap mcp (stdio JSON-RPC) and gets a read-only server: packages_list, package_exports (the names each entry's .d.ts declares), ontology_term (T-box IRI, label, comment — what a term means and what it is not), contract_deployments (addresses per chain), recipes (the agent rules and each package's spec), doctor (the same report, redacted). Everything is answered from the packages installed beside it. It is the third MCP — not the runtime's private MCP behind admission (ADR-0057), not the Home MCP (spec 397) — and its ap://developer-mcp/doctrine resource says so first: no signing key, no vault, no authority, no production effect (spec 398 §10.4, T23). Claude Code: claude mcp add ap-dev -- npx ap mcp --root .

ap generate client|cli|parity — the fourth and fifth surfaces of one contract (398 §7.2)

ap generate client --registry https://<skills-registry> --definition agentic-trust/person-steward --only web.search,person.memory.remember --out src/lib/agent-client.ts
ap generate cli    --registry … --definition agentic-trust/org-steward --only treasury.payment.execute
ap generate parity --registry … --definition agentic-trust/org-steward --json

Projected FROM the compiled definition (the registry's, or --file <definition.json>) by @agenticprimitives/harness's pure generateCapabilityClient / cliArgumentSchema / generateParityCases — the kit dispatches to the consumer's install (absent ⇒ E_MODULE_ABSENT). The client's every operation posts an intent to the app's /harness/run boundary through an injected port and carries no authority; the parity cases are the positive pair (screen intent vs Ask sentence → the same normalized plan digest) and the negative pair (a forged surface, a changed party after approval). Regenerate after ap upgrade moves a pinned definition.

ap eval — cases as data against a live Home (398 §10 / P1.3)

ap eval evals/faithnet.eval.json --home https://www.faithnet.me --persona alice --report live-gates-reports/eval-faithnet-latest.json
ap eval --from-runs --home https://www.faithnet.me --persona alice --out evals/from-runs.eval.json

A case is { id, incident, persona | (the --session bearer), addressee?, message, plan?, truth?, checks[] }; a check is one of the deterministic judges by name (answered, replyKindIs, neverClaims, claimsRequire, falseEmptiness, emptinessCarriesReason, evidenceFromTool, evidenceCountAgrees, noPlaceholderLeaks, textIncludes, textExcludes, evidenceNoneFrom). An act's correct outcome in a case is authority_required — the twin, as a test; an eval never signs. An unrunnable case is a FAILING case. --from-runs turns an agent's live run records into case skeletons to edit. Exit 1 on any failing case.

What it will not do

Hold a key, read a vault, mint authority, invoke a production effect. A doctor finding is a review checkpoint; no verifier reads it (spec 361 §1).