Getting Started#

Start by saving and reading back one local note through the Knowledge Kit's store API. This uses the published 9.1.1 package, Node.js 22 or newer, npm, and a writable directory. It needs no model credentials or provider calls. A coding agent is needed later to use the installed Claude Code hooks; this first task runs directly in Node and does not qualify live host enforcement.

Save your first note#

Create a new disposable directory and install the Claude Code workspace bundle with the Knowledge Kit selected:

mkdir flow-agents-first-note
cd flow-agents-first-note
flow_agents() (
  tool_root=$(mktemp -d) || exit 1
  trap 'rm -rf "$tool_root"' EXIT HUP INT TERM
  npm exec --yes --prefix "$tool_root" \
    --package=@kontourai/flow-agents@9.1.1 -- flow-agents "$@"
)
flow_agents init --runtime claude-code --dest . \
  --activate-kit knowledge --telemetry-sink local-files --yes

The isolated npm prefix keeps a repository-local package from intercepting this versioned command. The installer prints the selected runtime, destination and local-files telemetry pin. Explicit --telemetry-sink local-files ignores operator Console configs; TELEMETRY_CONFIG_FILE can still override it, and a separately enabled OTLP bridge is outside this pin. See the full telemetry resolution rules. This is not a network-isolation setting. Source changes newer than 9.1.1 validate telemetry configuration for every install; that additional validation is not claimed for this pinned release.

Save a note using the installed store API:

node --input-type=module <<'JS'
import DefaultKnowledgeStore from './kits/knowledge/adapters/default-store/index.js';
const store = new DefaultKnowledgeStore({ storeRoot: './knowledge-demo' });
const id = await store.create({
  type: 'raw',
  title: 'Upgrade reminder',
  body: 'Read the release notes before upgrading.',
  category: 'quickstart',
  provenance: { agent: 'quickstart-cli', note: 'Local text entered in this example.' }
});
const saved = await store.get(id);
console.log(JSON.stringify({ id, type: saved.type, body: saved.body,
  agent: saved.provenance.agent }, null, 2));
JS

Expect a generated id, type: "raw", the same body, and agent: "quickstart-cli". The record is saved at knowledge-demo/records/<id>.md; its graph index is in knowledge-demo/graph-index.json. The agent label identifies this example's calling process; it is supplied by the caller and is not authenticated identity or independent review. Saving the note records text and provenance, not its truth. Each execution creates a new record. Keep the returned id to read it again with get(id) rather than creating a duplicate.

Recovery: if create refuses with MISSING_EVIDENCE for a missing provenance.agent, it has not created that record. Supply the actual calling process label and retry the rejected input. Do not remove provenance enforcement or edit a stored record to bypass it. For a missing adapter file, confirm the install above completed in this directory before running Node.

This completes a local capture and read-back, not a gated software delivery. For a small code change, use your repository's normal implementation, meaningful checks and separate review; report unresolved gaps. To add a stateful delivery workflow, select the optional Builder Kit below. builder.build-lean is an ablation experiment, not a small-task shortcut.

flow_agents init --runtime codex --global --activate-kit builder --yes

flow_agents init --runtime opencode --global --activate-kit builder --yes

bash scripts/install-codex-home.sh /tmp/codex-home --skills-dir /tmp/agents/skills

2. What the Builder Kit gives you#

Builder is optional. Activate it in an existing workspace with flow_agents init --runtime claude-code --dest . --activate-kit builder --telemetry-sink local-files --yes. The current manifest declares the following catalog; builder.shape and builder.build are the starter pair, not the complete list:

These are not freeform chat sessions. Each flow has evidence gates — named checkpoints that expect specific claims before the next step starts. Flow evaluates those expectations when a transition is requested. Whether the host can also prevent the agent from ending its turn depends on the completion-check wiring and configuration above.

Shape flow gates (builder.shape):

• shape-gate — problem, outcome, constraints, non-goals, success criteria, and risk are stated
• breakdown-gate — work is split into independently useful slices
• file-issues-gate — each slice becomes a filed work item with enough context to pull later

Build flow gates (builder.build):

• pull-work-gate — a ready work item is selected with scope and acceptance context
• design-probe-gate — goal fit, blockers, dependencies, and planning readiness are recorded before a plan is written
• plan-gate — the plan names files, changes, acceptance evidence, and sequencing
• execute-gate — changed files are recorded and unrelated work is excluded
• verify-gate — tests or checks have evidence tied to the implementation (up to 3 route-back attempts before blocking)
• merge-ready-gate — scope, evidence, and residual risks support a merge-ready decision
• pr-open-gate — a pull request exists with linked work and verification evidence
• merge-ready-ci-gate — CI and review status support merge
• learn-gate — decisions and delivery learnings are recorded for future work

The gate semantics live in Kontour Flow; Flow Agents compiles them to whatever hook surface your agent exposes.

3. Optional Builder walkthrough#

Step 1 — Shape an idea#

In your coding agent, paste this:

Use Builder Kit shape. I want to add a progress indicator to the CLI output so
users can see what step the installer is on. Keep it simple — just a step count
like "[2/5] Copying agents". Shape this into an executable work item and stop
at the backlog gate.

The prompt asks the agent to run the builder-shape / idea-to-backlog skill, which:

1. inventories the idea and classifies it
2. proposes the thinnest meaningful slice (the step counter) and names what is out of scope
3. drafts a shaped work item with a stated outcome, non-goals, acceptance criteria, and a verification expectation
4. presents the breakdown for confirmation before creating provider-backed work items

You will see the agent write a local artifact at .kontourai/flow-agents/<slug>/<slug>--idea-to-backlog.md. That artifact is the machine-readable input to the next stage — not a summary in the chat window.

To continue and file the GitHub issue:

That looks right. File the GitHub issue and stop.

The agent runs the file-issues step, checks the file-issues-gate, and stops. You now have a shaped, filed work item that the build flow can pull.

Step 2 — Build that work item#

Use deliver for the issue you just filed. Pull it, probe the design, plan it,
implement it, review it, verify it, and stop if any evidence is missing.

The deliver skill orchestrates the full builder.build flow:

1. pull-work — selects the issue, confirms scope and acceptance criteria (pull-work-gate)
2. design-probe — checks goal fit, identifies blockers and dependencies, and records planning readiness before touching a file (design-probe-gate)
3. plan-work — delegates to tool-planner, which writes a structured plan artifact naming files, changes, sequencing, and acceptance evidence (plan-gate)
4. execute-plan — delegates plan-scoped work to tool-worker subagents, running independent tasks concurrently when file ownership and dependencies permit; there is no fixed worker count (execute-gate)
5. review-work — code and optional security review recorded in the trust.bundle critique slice
6. verify-work — tests and checks with evidence tied to the change; if evidence is missing the verify-gate triggers a route-back (verify-gate)
7. evidence-gate — scope, evidence, and risk assessment (merge-ready-gate)
8. publish-change operation — create or update the provider change record with linked work and verification evidence (pr-open-gate); this step uses an operation, not a pull-request skill
9. release-readiness — assess provider/CI merge readiness for that change (merge-ready-ci-gate)
10. learning and workspace closeout — route durable follow-up, retain open changes for review, and reclaim only clean linked worktrees whose exact head is freshly confirmed merged

You can also invoke each skill individually if you want explicit control:

Use pull-work to select issue #42.

Use plan-work on the session artifact from the pull-work step.

Use verify-work on the current branch and report what evidence is present.

What you observe#

• Inspect the session records under .kontourai/flow-agents/<slug>/: state.json tracks workflow control, acceptance.json holds the acceptance definition, and handoff.json carries continuation context. Review and verification records belong in trust.bundle slices, including critique, acceptance-criteria, tests-evidence, and policy-compliance. The active step's public operations update the relevant records; every file is not rewritten at every step. Retained records support later resumption. Legacy critique.json and evidence.json are retired sidecars, not the current evidence outputs.
• At each requested transition, Flow evaluates the recorded evidence expectations and reports missing evidence or a route-back. This does not establish the truth of the supplied evidence.
• The stop-goal-fit hook, when loaded and configured to block on a host that supports it, can refuse completion for qualifying evidence gaps. Check the runtime table above; warning-only and shutdown callbacks do not provide the same completion control.
• If verify fails, verify-gate routes missing evidence and the default failure class back to verify, implementation defects to execute, plan gaps to plan, and decision gaps to design-probe. The route-back budget is three attempts; exceeding it blocks the run.

This is guided, not fully automated. The agent handles the mechanics; you make product decisions. Gates are explicit handoff points, not invisible checkboxes.

4. Inspect what you installed#

After installing, you can inspect the Builder Kit's declared contents:

flow_agents kit inspect kits/builder --json

This prints a JSON object with the kit id, name, conformance levels (k0/k1/k2), declared targets, and any third-party extensions — for example:

{
  "kit_id": "builder",
  "kit_name": "Builder Kit",
  "conformance": { "k0": true, "k1": true, "k2": false },
  "targets": ["flow", "flow-agents"],
  "third_party_extensions": [],
  "trust": "unverified"
}

It does not require a running agent or active session.

To see the raw flow definitions with their gate expectations:

cat kits/builder/flows/shape.flow.json
cat kits/builder/flows/build.flow.json

5. Verify your setup#

The note read-back above checks that the installed store API works locally. For the kit's own adapter contract checks, run its existing suite from the installed workspace (no build or project dependency installation is needed):

node --test kits/knowledge/evals/contract-suite/suite.test.js

For contributors in the Flow Agents source checkout, npm run validate:source and npm run eval:static validate source and generated bundles. They are not consumer-workspace setup commands and do not prove a host loaded its hooks.

What to read next#

• Workflow Usage Guide — example prompts and expected behavior for every skill and stage
• Agent System Guidebook — how the pieces fit together conceptually
• Kit Authoring Guide — author your own Flow Kit from scratch
• Runtime Hook Surface spec — hook events, conformance levels, and host gaps
• Workflow Artifact Lifecycle — when to promote local artifacts to durable docs