DEC-0004 — Claude-primitives-first

Reversibility: one-way door — sets the core architecture (the primitive-to-layer map below). Client data stays sovereign/portable via OKF even if the runtime changes.

Context

We want to be agent-native and move fast, taking full advantage of everything Anthropic ships as of June 2026 rather than reinventing orchestration.

Options considered

1. Build a bespoke agent framework + orchestration from scratch.
2. Glue together third-party agent frameworks.
3. Build on Claude's native primitives and package as Claude Code plugin(s).

Decision

Adopt Claude-primitives-first. Map every layer to a primitive:

• Subagents → the expert/principal team.
• Agent Skills → repeatable procedures (ingest, author-okf, scaffold-vertical, verify-kb).
• Hooks → trace capture + governance gates (Establish the learning-loop & audit architecture).
• MCP server → expose each client's OKF KB to downstream agents (the agentic foundation).
• Claude Agent SDK (TS) → the ingestion→extraction→OKF runtime (structured outputs, prompt caching, memory tool, context editing).
• Claude Code plugin(s) → packaging & distribution to agencies (via marketplace).
• Private evals (API) → "is the loop improving against business outcomes?"

Rationale

• Speed + DX + reliability; no orchestration to maintain.
• Recursive moat — we build with the same primitives we ship; improvements compound on both sides.
• Custom build tooling stays on VoidZero/Vite + TypeScript.

Consequences

• Defines the roster of subagents + skills and the plugin packaging shape.
• Couples us to Anthropic's platform — accepted; OKF keeps client data sovereign and portable even if the runtime changes.

Review

Revisit if a primitive proves limiting at multi-tenant scale (esp. MCP isolation and per-tenant eval/RL).