Kontour Flow

Proof, not promises. Flow shows why work was allowed to move forward.

Documentation · Getting Started · Use Cases · CLI Reference

AI agents move faster than humans can inspect. They skip steps, accept weak evidence, declare work complete after partial verification, and lose the thread after context compaction. The work looks done — until you ask why it was allowed to advance, and nobody can answer.

Flow is the missing record in the middle: the required path, the evidence each gate expected, the evidence that was actually collected, and the exceptions a human explicitly accepted. It does not run your agents and it does not replace CI. It explains — durably, locally, in plain files — why the work was allowed to advance.

flow run: agent-dev-flow / feature-search-filters
current step: implement

PASS  plan gate: Acceptance criteria are ready for implementation. satisfied
WAIT  implementation gate: implementation gate waiting
WAIT  verify gate: verify gate waiting

next action: attach evidence for implementation gate
continuation: resume from implement, not chat memory
report: .flow/runs/dev-1847/report.md

Why teams adopt Flow

• Evidence-gated transitions. A step is not complete because an agent says so. Gates declare typed expectations, and runs advance only when evidence satisfies them — or when a human accepts an explicit, attributable exception.
• Survives context loss. Every run lives in plain files under .flow/runs/<run-id>/. A new agent session, a teammate, or a CI job can flow resume and continue from recorded state, not chat memory.
• Deterministic route-back. Failed evidence routes work back to the right step (implementation_defect → implement, plan_gap → plan) with attempt budgets, so agents cannot loop silently forever.
• Audit-ready reports. Every run regenerates a human-readable report.md and machine-readable report.json that explain what passed, what blocked, what was excepted, and what happens next.
• Local-first, zero lock-in. v0.1 is a file-backed CLI and TypeScript library. No hosted service, no account, no telemetry. Your evidence stays in your repo.

See it

Thirty seconds, four commands — and a gate an agent cannot talk its way past:

The bundled local Flow Console (flow console) renders any run from its local files — the process graph, gate outcomes, evidence, route-backs, and the next action:

Quickstart

npm install -D @kontourai/flow

# Scaffold .flow/ with a sample agent-dev definition
npx flow init

# Start a run for a concrete piece of work
npx flow start .flow/definitions/agent-dev-flow.json \
  --run-id dev-1847 --params subject=feature-search-filters

# Attach evidence to the current gate, then evaluate
npx flow attach-evidence dev-1847 --gate plan-gate \
  --file ./acceptance-claim.json --trust-artifact
npx flow evaluate dev-1847

# See where the run stands — from any session, any time
npx flow status dev-1847
npx flow resume dev-1847

In a hurry? npx flow init --demo scaffolds a ready-made run named demo so flow status demo and flow console --run demo have something real to show immediately.

The Getting Started guide walks this path end to end with real output, including what evidence files look like and how a blocked gate routes work back.

Where Flow fits

Flow is the process-transparency layer of the Kontour product line: Kontour shows the work behind AI.

| Product | Owns | | --- | --- | | Survey | Producer evidence: source → extraction → candidate → review → claim | | Surface | Portable trust state: claims, evidence, policies, trust snapshots | | Flow | Process transparency: steps, gates, transitions, runs, exceptions, reports | | Veritas | Code/change transparency: repo standards, merge readiness | | Flow Agents | Agent-facing distribution: kits, runtime adapters, hooks |

Flow stands alone — you need none of the other products to use it. When they are present, Veritas can supply repo-readiness evidence to Flow gates, and Flow Agents can enforce Flow gates from inside Claude Code, Codex, Kiro, or GitHub Actions.

Real teams use Flow for agentic development gates, regulated release decisions, platform golden paths, adversarial review loops, and audit-ready change evidence. Use Cases walks through each with definitions you can copy.

How it works

1. Author a Flow Definition — JSON describing steps, gates, typed evidence expectations, and route-back policy. Validate it with flow validate-definition.
2. Start a Flow Run — flow start snapshots the definition and creates authoritative run state under .flow/runs/<run-id>/.
3. Attach evidence — test output, CI results, trust reports, human attestations. Files are copied into the run; nothing is synthesized.
4. Evaluate gates — flow evaluate passes, blocks, routes back, or waits. Accepted exceptions are first-class, recorded with reason and authority.
5. Report and resume — report.md / report.json explain the run; flow resume gives the next agent everything it needs without chat memory.

.flow/runs/dev-1847/
├── definition.json        # normalized definition snapshot from run start
├── state.json             # authoritative run state (continuation authority)
├── evidence/
│   ├── manifest.json      # evidence index
│   └── ev.<id>.<ext>     # copied evidence artifacts (original extension preserved)
├── report.md              # regenerated human-readable report
└── report.json            # regenerated machine-readable report

CLI

flow init                          scaffold .flow/ with config and a sample definition
flow validate-definition <path>    validate a Flow Definition, with --json diagnostics
flow start <definition>            start a run from a definition
flow status <run-id>               summary, json, or markdown run status
flow attach-evidence <run-id>      copy an evidence file onto a gate
flow evaluate <run-id>             evaluate gates and advance, block, or route back
flow accept-exception <run-id>     pass a gate by explicit, attributed exception
flow resume <run-id>               print continuation state for the next agent
flow report <run-id>               regenerated run report in summary, markdown, or json
flow list                          list local runs
flow console --run <run-id>        loopback-only local console for a run
flow config preview|apply <file>   preview and apply project config proposals
flow validate-transition <file>    validate a proposed transition against run state
flow version-release-report <file> project a versioned release report

Every command accepts --cwd <path> to scope local Flow files. Full flags, formats, and exit behavior: CLI Reference.

Library

The same primitives the CLI uses are exported from the package root, fully typed:

import {
  startRun,
  attachEvidence,
  evaluateRun,
  loadRun,
  validateDefinitionWithDiagnostics,
  validateRunTransition,
  projectFlowRunFromFiles
} from "@kontourai/flow";

const result = validateDefinitionWithDiagnostics(definition);
if (!result.valid) console.error(result.diagnostics);

const projection = await projectFlowRunFromFiles("dev-1847", { cwd: process.cwd() });
console.log(projection.current_step, projection.gates);

Public usage is limited to the package root and the flow CLI; dist/ subpaths are not part of the npm API. The Library guide covers run lifecycle, projections, release readiness evaluation, and config merge helpers.

Documentation

| Guide | What it covers | | --- | --- | | Getting Started | install → first run → evidence → route-back → resume, with real output | | Use Cases | realistic team scenarios with copyable definitions | | Evidence | evidence kinds, surface.claim expectations, trust artifacts, diagnostics | | Gates & Route-Back | gate evaluation rules, transitions, route-back policy, exceptions | | Agent Hooks | enforcing gates from Claude Code hooks, GitHub Actions, Git hooks | | Project Config | trusted producers, gate overrides, config merge preview/apply | | Release Readiness | release lanes, hold/proceed decisions, version release reports | | CLI Reference | every command, flag, format, and exit code | | Library | typed API for embedding Flow | | Developer Architecture | lifecycle and enforcement internals, ownership boundaries |

The docs map lives at docs/README.md. Contributor setup lives in docs/contributing.md. Release history lives in CHANGELOG.md.

Schemas

Flow's contracts are public JSON Schemas under schemas/: Flow Definitions, Flow Runs, gate evidence, reports, transition validation, release readiness, and version release reports. npm test fails if the runtime drifts from the published schemas.

Boundaries

Flow is deliberately small. It is not an agent runtime, multi-agent orchestrator, task board, repo standards engine, hosted service, or hosted web UI. Surface owns portable trust state, Veritas owns repo readiness semantics, and Flow Agents owns agent-facing workflow distribution. Flow owns one thing: the evidence-backed record of why a required path was allowed to advance.

License

Apache-2.0 © Kontour AI