FROZEN — immutable history. Superseding/current decisions live in docs/decisions/. Do not edit.

ADR 0008: Kit Operation Boundary

Date: 2026-06-15
Status: Accepted

Context

A kit is the SEAM where Flow and Flow Agents meet: Flow owns the container (manifest + flows), Flow Agents owns the extension (skills, adapters, docs, activation), and a kit fuses both into one package. So “which layer owns an operation on a kit?” is ill-posed whenever the operation touches both halves.

Of the kit operations: validate touches only the container (cleanly Flow); activate touches only a specific agent runtime — codex-local/strands-local (cleanly Flow Agents); install and inspect STRADDLE the seam.

A concrete duplication was found motivating this: flow-agents reimplements Flow’s container contract — src/flow-kit/validate.ts has its own validateCoreContainer (schema_version/id/name/flows), while Flow exposes the authoritative validateKitContainer from its src/index.ts, and flow-agents does not even depend on @kontourai/flow. The two contracts can silently drift.

This ADR records the design decision reached with Brian Anderson on 2026-06-15.

Decision

The Dividing Test

Does the operation need to INTERPRET the agent extension (what a skill or adapter MEANS), or only the container (manifest + flows + the names of declared asset classes)? Container-only → Flow. Extension-interpreting → Flow Agents.

flow kit validate, flow kit install (fetch + validate + place a kit package), flow kit inspect (container validity + flows + declared asset-class NAMES — the K0/structural view). Flow knows NOTHING about what a skill or adapter means.

Flow Agents Owns the Extension Operations

flow-agents kit activate (wire the extension into a runtime), plus the extension-interpreting augmentation of install (place skill/adapter assets) and inspect (interpret asset classes → K1/K2 + runtime targets). Flow Agents COMPOSES on Flow’s primitives; it never reimplements them.

Flow’s kit operations must NEVER interpret extension semantics — fetch, validate, place, report-structure, full stop. Holding this line keeps Flow’s operations genuinely generic even though flow-agents is currently the only consumer; the line between the layers is precisely “does it interpret the extension?”

DRY via Delegation

flow-agents depends on @kontourai/flow, deletes validateCoreContainer, and delegates all container work to Flow’s primitives. The container contract lives ONCE, in Flow.

Flow Agents Is the Reference Consumer

Flow Agents is the worked example for any future producer building on Flow — lean on Flow’s agent-blind primitives, add your own extension layer in your own CLI.

Consequences

CLI Surface

flow kit <validate|install|inspect> (container, agent-blind) and flow-agents kit <install|inspect|activate> (extension-composing). The standalone flow-kit binary and the flat flow validate-kit verb are deprecated with aliases.

Position C Adopted

This adopts position C (generic kit operations live in Flow) over position B (whole-kit lifecycle stays in flow-agents). C was chosen because doing it twice (B now, migrate later) is wasteful, and the agent-blind guardrail removes the premature-abstraction risk that motivated B.

Breaking CLI Change

Breaking CLI change on published 1.x in BOTH repos → deprecation aliases + a coordinated release.

Separate-Product-Ready

Because the primitives live in Flow with flow-agents as a consumer, Flow Kits could later be productized (container + primitives + marketplace) without re-architecture.

Alternatives Considered

Position B (kit lifecycle entirely in flow-agents, defer generic Flow ops)

Rejected. Defensible short-term (flow-agents is the only layer that comprehends a whole kit today) but causes a double-migration; the agent-blind guardrail makes C’s genericity real now, removing B’s main justification.

Position A (container ops = Flow, runtime ops = flow-agents, by category)

Rejected earlier in the discussion — kits are not pure containers, so a category split mislocates install/inspect.

References

ADR 0007: Flow / Skill / Kit / Tool Boundary — the skill/tool boundary; same conversation.
GitHub #62 (Builder Kit skill placement), #50 / #79 (marketplace / trust layer), #52 / #60 (agentless gate-eval proving Flow Definitions are agentless-capable).
kontourai/flow container spec (flow PR #67) — establishes Flow owns the container contract + validateKitContainer.