@kontourai/flow-agents 1.1.0 → 1.2.0

package/docs/context-map.md

@@ -65,18 +65,18 @@ Primary tools: `npm run workflow:sidecar`, `npm run workflow:validate-artifacts`
 
 | Skill | Source | When To Load |
 | --- | --- | --- |
-| deliver | skills/deliver/SKILL.md | Delivery workflow — selected work to delivered code. Ensures pull-work + pickup-probe preflight, then chains plan-work → execute-plan → review-work → verify-work → loop on failure without requiring user interaction between cleanly determ... |
-| evidence-gate | skills/evidence-gate/SKILL.md | Evaluate whether completed work is trustworthy enough for human review, merge, or release. Use after implementation, verify-work, provider checks, CI, or remediation to map acceptance criteria to evidence, inspect scope integrity, classi... |
-| execute-plan | skills/execute-plan/SKILL.md | Parallel execution primitive — plan artifact path to implemented code via tool-worker (x4). Reads plan directly. Updates session file between waves. |
-| fix-bug | skills/fix-bug/SKILL.md | Bug fix orchestrator — diagnose → plan-work → execute-plan → review-work → verify-work → loop. Diagnosis phase is unique to bugs, then chains the same primitives. |
-| idea-to-backlog | skills/idea-to-backlog/SKILL.md | Turn raw product or technical ideas into shaped, prioritized, executable GitHub issue backlog. Use for idea intake, ideation, product shaping, spike/prototype decisions, PRD-like feature briefs, prioritization, and backlog creation befor... |
-| learning-review | skills/learning-review/SKILL.md | Capture post-merge, post-deploy, or post-incident learnings and feed them back into backlog, workflow skills, tests, docs, or knowledge. Use after release readiness, post-deploy checks, retrospectives, failed gates, or repeated workflow... |
-| plan-work | skills/plan-work/SKILL.md | Code planning primitive — goal + directory to structured execution plan. Delegates to tool-planner. No resume, no ideation. |
-| pull-work | skills/pull-work/SKILL.md | Select ready GitHub issues from the executable backlog and prepare them for implementation. Use when choosing what to work on next, reviewing a kanban-style issue board, enforcing WIP limits, grouping issues, deciding worktree isolation,... |
-| release-readiness | skills/release-readiness/SKILL.md | Decide whether evidence-backed work is ready to merge, release, deploy, or hold. Use after evidence-gate PASS, before merge/release/deploy, and for post-deploy verification planning. |
-| review-work | skills/review-work/SKILL.md | Review primitive - run report-only code, security, dependency, architecture/standards, and IaC/policy critique before verification; records findings through the critique artifact/sink, currently critique.json locally. |
-| tdd-workflow | skills/tdd-workflow/SKILL.md | Test-driven development — RED → GREEN → REFACTOR with git checkpoints. Wraps plan-work → execute-plan → review-work → verify-work with test-first constraints and coverage gates. |
-| verify-work | skills/verify-work/SKILL.md | Verification primitive — session file path to structured evidence verdict via tool-verifier + tool-playwright. Reads acceptance criteria from plan artifact. |
+| deliver | kits/builder/skills/deliver/SKILL.md | Delivery workflow — selected work to delivered code. Ensures pull-work + pickup-probe preflight, then chains plan-work → execute-plan → review-work → verify-work → loop on failure without requiring user interaction between cleanly determ... |
+| evidence-gate | kits/builder/skills/evidence-gate/SKILL.md | Evaluate whether completed work is trustworthy enough for human review, merge, or release. Use after implementation, verify-work, provider checks, CI, or remediation to map acceptance criteria to evidence, inspect scope integrity, classi... |
+| execute-plan | kits/builder/skills/execute-plan/SKILL.md | Parallel execution primitive — plan artifact path to implemented code via tool-worker (x4). Reads plan directly. Updates session file between waves. |
+| fix-bug | kits/builder/skills/fix-bug/SKILL.md | Bug fix orchestrator — diagnose → plan-work → execute-plan → review-work → verify-work → loop. Diagnosis phase is unique to bugs, then chains the same primitives. |
+| idea-to-backlog | kits/builder/skills/idea-to-backlog/SKILL.md | Turn raw product or technical ideas into shaped, prioritized, executable GitHub issue backlog. Use for idea intake, ideation, product shaping, spike/prototype decisions, PRD-like feature briefs, prioritization, and backlog creation befor... |
+| learning-review | kits/builder/skills/learning-review/SKILL.md | Capture post-merge, post-deploy, or post-incident learnings and feed them back into backlog, workflow skills, tests, docs, or knowledge. Use after release readiness, post-deploy checks, retrospectives, failed gates, or repeated workflow... |
+| plan-work | kits/builder/skills/plan-work/SKILL.md | Code planning primitive — goal + directory to structured execution plan. Delegates to tool-planner. No resume, no ideation. |
+| pull-work | kits/builder/skills/pull-work/SKILL.md | Select ready GitHub issues from the executable backlog and prepare them for implementation. Use when choosing what to work on next, reviewing a kanban-style issue board, enforcing WIP limits, grouping issues, deciding worktree isolation,... |
+| release-readiness | kits/builder/skills/release-readiness/SKILL.md | Decide whether evidence-backed work is ready to merge, release, deploy, or hold. Use after evidence-gate PASS, before merge/release/deploy, and for post-deploy verification planning. |
+| review-work | kits/builder/skills/review-work/SKILL.md | Review primitive - run report-only code, security, dependency, architecture/standards, and IaC/policy critique before verification; records findings through the critique artifact/sink, currently critique.json locally. |
+| tdd-workflow | kits/builder/skills/tdd-workflow/SKILL.md | Test-driven development — RED → GREEN → REFACTOR with git checkpoints. Wraps plan-work → execute-plan → review-work → verify-work with test-first constraints and coverage gates. |
+| verify-work | kits/builder/skills/verify-work/SKILL.md | Verification primitive — session file path to structured evidence verdict via tool-verifier + tool-playwright. Reads acceptance criteria from plan artifact. |
 
 ## Support Skills
 
@@ -84,17 +84,13 @@ Primary tools: `npm run workflow:sidecar`, `npm run workflow:validate-artifacts`
 | --- | --- | --- |
 | agentic-engineering | skills/agentic-engineering/SKILL.md | Eval-first execution, task decomposition, and cost-aware model routing for AI-driven development workflows. |
 | browser-test | skills/browser-test/SKILL.md | Headless browser automation via Playwright — screenshots, accessibility checks, form filling, UI testing, DOM inspection. |
-| builder-shape | skills/builder-shape/SKILL.md | Invoke Builder Kit shape from a raw idea or the current conversation context without requiring the user to name idea-to-backlog. Delegates shaping to idea-to-backlog, records the Builder Kit Flow Definition link, and stops at the backlog... |
-| context-budget | skills/context-budget/SKILL.md | Audit token overhead across Flow Agents bundles — agent specs, skills, context files, MCP servers. Produces budget report with per-component breakdown and optimization suggestions. |
+| builder-shape | kits/builder/skills/builder-shape/SKILL.md | Invoke Builder Kit shape from a raw idea or the current conversation context without requiring the user to name idea-to-backlog. Delegates shaping to idea-to-backlog, records the Builder Kit Flow Definition link, and stops at the backlog... |
 | dependency-update | skills/dependency-update/SKILL.md | Analyze and upgrade project dependencies — latest versions, security vulnerabilities, actionable update plan across all package managers. |
-| design-probe | skills/design-probe/SKILL.md | Generic one-question-at-a-time design probing interview for turning unclear goals, designs, or workflow states into shared understanding before planning or execution. |
+| design-probe | kits/builder/skills/design-probe/SKILL.md | Generic one-question-at-a-time design probing interview for turning unclear goals, designs, or workflow states into shared understanding before planning or execution. |
 | eval-rebuild | skills/eval-rebuild/SKILL.md | Project-specific build and install commands for the eval feedback loop. Injected into eval-builder agent. Replace this skill for different build systems. |
-| explore | skills/explore/SKILL.md | Parallel codebase exploration — fans out subagents to map structure, entry points, dependencies, patterns, config, and tests in one pass. |
-| feedback-loop | skills/feedback-loop/SKILL.md | Verify implementation actually works. Visual changes → Playwright; integration changes → commands/tests. Run after completing builds. |
-| frontend-design | skills/frontend-design/SKILL.md | Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics. |
 | github-cli | skills/github-cli/SKILL.md | Interact with GitHub via gh CLI — PRs, issues, repos, releases, workflows, gists. |
-| knowledge-capture | skills/knowledge-capture/SKILL.md | Save durable knowledge, lightweight pointers, user corrections, decisions, lessons, relationship context, or source references into the knowledge base. Use when the user says save, remember, capture, file this, bookmark context, or when... |
-| pickup-probe | skills/pickup-probe/SKILL.md | Builder Kit work-item/docs/provider-grounded Probe specialization used at the design-probe flow step before plan-work. |
+| knowledge-capture | kits/knowledge/skills/knowledge-capture/SKILL.md | Save durable knowledge, lightweight pointers, user corrections, decisions, lessons, relationship context, or source references into the knowledge base. Use when the user says save, remember, capture, file this, bookmark context, or when... |
+| pickup-probe | kits/builder/skills/pickup-probe/SKILL.md | Builder Kit work-item/docs/provider-grounded Probe specialization used at the design-probe flow step before plan-work. |
 | search-first | skills/search-first/SKILL.md | Research-before-coding workflow. Search for existing tools, libraries, and patterns before writing custom code. |
 
 ## Agents
@@ -129,8 +125,8 @@ Pack composition is defined in `packaging/packs.json`. The current builder expor
 
 | Pack | Default | Skills | Agents | Powers | Purpose |
 | --- | --- | --- | --- | --- | --- |
-| core | yes | 9 | 5 | 1 | Small default surface for reliable coding and workflow execution. |
-| development | no | 17 | 9 | 1 | Development workflow depth for backlog, release, dependency, GitHub, TDD, and frontend work. |
+| core | yes | 2 | 5 | 1 | Small default surface for reliable coding and workflow execution. |
+| development | no | 4 | 9 | 1 | Development workflow depth for backlog, release, dependency, GitHub, TDD, and frontend work. |
 
 ## Current Workflow State
 

package/docs/flow-kit-repository-contract.md

@@ -23,11 +23,11 @@ npm run validate:source --
 Installed Flow Agents bundles include a local-only install command for Flow Kit repositories that already exist on disk:
 
 ```bash
-npm run flow-kit -- install-local path/to/local-kit --dest /path/to/installed-flow-agents
-npm run flow-kit -- list --dest /path/to/installed-flow-agents
-npm run flow-kit -- status --dest /path/to/installed-flow-agents
-npm run flow-kit -- status example-kit --dest /path/to/installed-flow-agents
-npm run flow-kit -- activate --dest /path/to/installed-flow-agents --format json
+npm run kit -- install path/to/local-kit --dest /path/to/installed-flow-agents
+npm run kit -- list --dest /path/to/installed-flow-agents
+npm run kit -- status --dest /path/to/installed-flow-agents
+npm run kit -- status example-kit --dest /path/to/installed-flow-agents
+npm run kit -- activate --dest /path/to/installed-flow-agents --format json
 ```
 
 `--dest` is the installed bundle or workspace root. When omitted, the command uses the current working directory. Tests and automation should pass a temp destination; the command does not need to write to a user home directory.

package/docs/getting-started.md

@@ -0,0 +1,177 @@
+---
+title: Builder Kit Quick Start
+---
+
+# Builder Kit Quick Start
+
+This guide takes you from nothing to a running, gated build flow in about two minutes. By the end you will have Flow Agents installed in your coding agent's workspace and understand how the Builder Kit's two flows — `builder.shape` and `builder.build` — turn a raw idea into a merged change with evidence.
+
+## 1. Install
+
+Run this from any workspace you want to add discipline to:
+
+```bash
+npx @kontourai/flow-agents init --runtime <your-agent> --dest .
+```
+
+Where `--runtime` is one of `claude-code`, `codex`, `kiro`, `opencode`, or `pi`. For a fully unattended install:
+
+```bash
+npx @kontourai/flow-agents init --runtime claude-code --dest . --yes
+npx @kontourai/flow-agents init --runtime codex       --dest . --yes
+npx @kontourai/flow-agents init --runtime opencode    --dest . --yes
+```
+
+The installer copies agents, skills, context contracts, hook scripts, Kit assets, and the Flow Agents telemetry descriptor into the workspace. The Builder Kit installs automatically. Your agent reads those files at startup; no plugin registry required.
+
+**What lands in the workspace:**
+
+- `agents/`, `skills/`, `context/` — skill definitions and shared contracts the agent follows
+- `scripts/hooks/` — four canonical policy scripts (steering, quality gate, stop-goal-fit, config protection) wired to the host's native hook surface
+- `kits/builder/` — Builder Kit flows and skills
+- `console.telemetry.json` — telemetry descriptor (writes locally by default)
+
+At L2 conformance (Claude Code, Codex, Kiro) all four hooks are active and the stop hook blocks early exits that lack evidence. At L1 (opencode, pi) steering and stop-goal-fit run but without blocking capability; see the [Runtime Hook Surface spec](spec/runtime-hook-surface.html) for the gaps.
+
+## 2. What the Builder Kit gives you
+
+The Builder Kit installs two flows:
+
+| Flow | ID | What it does |
+|---|---|---|
+| Shape | `builder.shape` | Turns a raw idea into slices and executable work items |
+| Build | `builder.build` | Takes a ready work item through design probe → plan → execute → verify → PR → merge readiness → learn |
+
+These are not freeform chat sessions. Each flow has **evidence gates** — named checkpoints that expect specific claims before the next step starts. The agent cannot silently skip a gate; it either satisfies the expectation or the transition is blocked (at L2) or flagged (at L1).
+
+**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](https://kontourai.github.io/flow/); Flow Agents compiles them to whatever hook surface your agent exposes.
+
+## 3. A two-minute first run
+
+### Step 1 — Shape an idea
+
+In your coding agent, paste this:
+
+```text
+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 agent will 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. stops at the `breakdown-gate` and waits for you to confirm before creating GitHub issues
+
+You will see the agent write a local artifact at `.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:
+
+```text
+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
+
+```text
+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** — fans out to up to four `tool-worker` subagents in parallel waves (`execute-gate`)
+5. **review-work** — code and optional security review (`critique.json` sidecar)
+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. **release-readiness** — scope, evidence, and risk assessment (`merge-ready-gate`)
+8. **pull-request** — PR with linked work item and verification evidence (`pr-open-gate`)
+
+You can also invoke each skill individually if you want explicit control:
+
+```text
+Use pull-work to select issue #42.
+```
+
+```text
+Use plan-work on the session artifact from the pull-work step.
+```
+
+```text
+Use verify-work on the current branch and report what evidence is present.
+```
+
+### What you observe
+
+- **Between each step**, the agent writes a local session sidecar under `.flow-agents/<slug>/` — `state.json`, `acceptance.json`, `evidence.json`, and `handoff.json`. These survive compaction, tab close, or a new session. A future session resumes from recorded state.
+- **At each gate**, the agent either presents the evidence and moves forward, or blocks and explains what is missing. It does not make up a confident summary and proceed.
+- **The stop-goal-fit hook** (at L2) prevents the agent from stopping when evidence is still incomplete — you see a warning or block rather than "all done!" on partial work.
+- **If verify fails**, the verify-gate routes back to execution (or plan, or design-probe, depending on the failure class) and tries again — up to three times before hard-blocking.
+
+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:
+
+```bash
+node build/src/cli.js kit inspect kits/builder
+```
+
+(Or, from a global install: `flow-agents kit inspect kits/builder`)
+
+This prints the kit id, name, declared flows, skills, and conformance level (K0/K1). It does not require a running agent or active session.
+
+To see the raw flow definitions with their gate expectations:
+
+```bash
+cat kits/builder/flows/shape.flow.json
+cat kits/builder/flows/build.flow.json
+```
+
+## 5. Verify your setup
+
+After installing, run the source validation to confirm the workspace is coherent:
+
+```bash
+npm run validate:source
+```
+
+For a full static eval pass (docs layout, legacy-term checks, bundle assertions):
+
+```bash
+npm run eval:static
+```
+
+## What to read next
+
+- [Workflow Usage Guide](workflow-usage-guide.html) — example prompts and expected behavior for every skill and stage
+- [Agent System Guidebook](agent-system-guidebook.html) — how the pieces fit together conceptually
+- [Kit Authoring Guide](kit-authoring-guide.html) — author your own Flow Kit from scratch
+- [Runtime Hook Surface spec](spec/runtime-hook-surface.html) — hook events, conformance levels, and host gaps
+- [Workflow Artifact Lifecycle](workflow-artifact-lifecycle.html) — when to promote local artifacts to durable docs

package/docs/index.md

@@ -71,24 +71,31 @@ The same canonical policies wire into agent frameworks as in-process language-na
 
 ## Quick Start
 
+Install into your workspace in one command:
+
 ```bash
-npx @kontourai/flow-agents init --dest /path/to/workspace
+npx @kontourai/flow-agents init --runtime <your-agent> --dest .
 ```
 
-Runtime-specific installs:
+Where `--runtime` is `claude-code`, `codex`, `kiro`, `opencode`, or `pi`. The Builder Kit installs automatically and gives your agent two gated flows: `builder.shape` (idea → slices → filed work items) and `builder.build` (selected work item → design probe → plan → execute → verify → PR → learn).
 
-```bash
-npx @kontourai/flow-agents init --runtime claude-code --dest /path/to/workspace --yes
-npx @kontourai/flow-agents init --runtime opencode --dest /path/to/workspace --yes
-npx @kontourai/flow-agents init --runtime pi --dest /path/to/workspace --yes
+Ask your agent to shape an idea:
+
+```text
+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. Shape this into an executable
+work item and stop at the backlog gate.
 ```
 
-Then ask for the workflow you want, in plain language:
+Then build it:
 
 ```text
-Use deliver for this GitHub issue. Plan it, implement it, review it, verify it, and stop if evidence is missing.
+Use deliver for the issue you just filed. Pull it, probe the design, plan it,
+implement it, verify it, and stop if any evidence is missing.
 ```
 
+Each step has an evidence gate. The agent cannot proceed past a gate without the expected evidence — it either presents it or blocks and explains what is missing. See the <a href="getting-started.html">Builder Kit Quick Start</a> for a full two-minute walkthrough with worked examples and an explanation of what you observe at each gate.
+
 For bugs:
 
 ```text
@@ -98,6 +105,10 @@ Use fix-bug. Reproduce the problem, diagnose root cause, implement the fix, and
 ## Explore the docs
 
 <div class="doc-grid">
+  <a class="doc-card" href="getting-started.html">
+    <strong>Builder Kit Quick Start</strong>
+    <span>Zero to a running, gated build flow in two minutes: install, shape an idea into a work item, build it through the builder.shape and builder.build flows, and see what the evidence gates do.</span>
+  </a>
   <a class="doc-card" href="workflow-usage-guide.html">
     <strong>Workflow Usage Guide</strong>
     <span>Every stage from shaping ideas to learning review, with example prompts and expected behavior.</span>

package/docs/kit-authoring-guide.md

@@ -112,7 +112,7 @@ npm run validate:source --
 Once validation passes, install the kit into a target workspace:
 
 ```bash
-npx @kontourai/flow-agents flow-kit install-local path/to/my-kit --dest /path/to/workspace
+npx @kontourai/flow-agents kit install path/to/my-kit --dest /path/to/workspace
 ```
 
 `--dest` is the installed Flow Agents bundle root. When omitted the command uses the current directory. From a contributor checkout of this repository, the equivalent form is `npm run flow-kit -- <command>`.
@@ -120,8 +120,8 @@ npx @kontourai/flow-agents flow-kit install-local path/to/my-kit --dest /path/to
 Confirm the install:
 
 ```bash
-npx @kontourai/flow-agents flow-kit list --dest /path/to/workspace
-npx @kontourai/flow-agents flow-kit status my-kit --dest /path/to/workspace
+npx @kontourai/flow-agents kit list --dest /path/to/workspace
+npx @kontourai/flow-agents kit status my-kit --dest /path/to/workspace
 ```
 
 `list` prints one summary line per installed kit. `status` prints JSON provenance including the SHA256 content hash and `installed` or `missing` state.
@@ -129,7 +129,7 @@ npx @kontourai/flow-agents flow-kit status my-kit --dest /path/to/workspace
 To replace an existing install after you update the kit source:
 
 ```bash
-npx @kontourai/flow-agents flow-kit install-local path/to/my-kit --dest /path/to/workspace --update
+npx @kontourai/flow-agents kit install path/to/my-kit --dest /path/to/workspace --update
 ```
 
 ## Activate
@@ -137,7 +137,7 @@ npx @kontourai/flow-agents flow-kit install-local path/to/my-kit --dest /path/to
 After installing, run activate to write runtime-local files into the workspace:
 
 ```bash
-npx @kontourai/flow-agents flow-kit activate --dest /path/to/workspace --format json
+npx @kontourai/flow-agents kit activate --dest /path/to/workspace --format json
 ```
 
 The `codex-local` adapter is selected automatically. To activate for Strands, pass `--adapter strands-local`.
@@ -194,7 +194,7 @@ The **container contract** is owned by [Kontour Flow](https://kontourai.github.i
 - Path rules: all declared paths must be relative, must not contain `..`, and must resolve inside the kit directory.
 - The **extension model**: unknown top-level fields are consumer extensions; core validation ignores-but-permits them.
 
-Container validation is surfaced in Flow's CLI as `flow validate-kit <kit-dir>`. Flow Agents delegates container validation to Flow when `FLOW_CLI_ROOT` is configured; without it, Flow Agents applies the same rules internally.
+Container validation is surfaced in Flow's CLI as `flow kit validate <kit-dir>`. Flow Agents delegates core container validation to `@kontourai/flow`'s `validateKitContainer` library function; the contract lives once, in Flow.
 
 For the authoritative container spec and JSON Schema, see [kontourai/flow#67](https://github.com/kontourai/flow/pull/67) (the spec PR) and the published `schemas/flow-kit-container.schema.json` in the `@kontourai/flow` package.
 
@@ -284,7 +284,7 @@ Layering summary:
 Use the `inspect` subcommand to derive a kit's conformance level and consumer targets:
 
 ```bash
-npm run flow-kit -- inspect path/to/my-kit
+npm run kit -- inspect path/to/my-kit
 ```
 
 Output is stable JSON:
@@ -310,3 +310,22 @@ The `inspect` command is read-only and safe to run before install.
 ## Direction
 
 Flow Kits are designed to be shareable workflow units — authored once, carried across teams and workspaces. The intended growth path is distribution from git remotes and a curated Kontour kit catalog of Kontour-authored kits covering work modes beyond software delivery. Today install is local-path only; remote fetch is explicitly a non-goal in this version.
+
+## Migration: flow-kit → flow-agents kit
+
+The standalone `flow-kit` binary was removed in this release. The `flow-agents kit` subcommand is the replacement.
+
+| Old command | New command |
+|---|---|
+| `flow-kit install-local <path>` | `flow-agents kit install <path>` |
+| `flow-kit install-git <url>` | `flow-agents kit install <url>` |
+| `flow-kit activate` | `flow-agents kit activate` |
+| `flow-kit inspect <dir>` | `flow-agents kit inspect <dir>` |
+| `flow-kit list` | `flow-agents kit list` |
+| `flow-kit status <id>` | `flow-agents kit status <id>` |
+| `npx @kontourai/flow-agents flow-kit ...` | `npx @kontourai/flow-agents kit ...` |
+| `npm run flow-kit -- ...` | `npm run kit -- ...` |
+
+`install-local` and `install-git` are unified into a single `install` command. The source argument auto-detects whether it is a local path or a git URL (http://, https://, git+, ssh://, file://).
+
+Running the old `flow-kit` command will produce a "command not found" error from your shell — there is no alias or shim. Update any scripts or CI configurations that call `flow-kit` to use `flow-agents kit`.

package/docs/knowledge-kit.md

@@ -4,7 +4,7 @@ title: Knowledge Kit
 
 # Knowledge Kit
 
-The Knowledge Kit is a Flow Kit for durable, gated knowledge storage. It packages a store contract, five pipeline flows, pluggable store adapters, and a parameterized contract test suite — all validated and installed through the standard `flow-kit` path.
+The Knowledge Kit is a Flow Kit for durable, gated knowledge storage. It packages a store contract, five pipeline flows, pluggable store adapters, and a parameterized contract test suite — all validated and installed through the `flow-agents kit` path.
 
 ## What it ships
 
@@ -44,7 +44,7 @@ The vector detector is fail-closed: infrastructure failures throw `EMBED_FAILURE
 
 ```bash
 # Install the kit into a workspace
-npx @kontourai/flow-agents flow-kit install-local kits/knowledge --dest /path/to/workspace
+npx @kontourai/flow-agents kit install kits/knowledge --dest /path/to/workspace
 
 # Run the contract suite against the default adapter
 node --test kits/knowledge/evals/contract-suite/suite.test.js

package/docs/spec/runtime-hook-surface.md

@@ -490,7 +490,7 @@ Kit flow activation for Strands workspaces is implemented as a new runtime adapt
 The CLI command is:
 
 ```bash
-flow-kit activate --adapter strands-local [--dest DIR] [--source-root DIR]
+flow-agents kit activate --adapter strands-local [--dest DIR] [--source-root DIR]
 ```
 
 This writes activated flow files to `.flow-agents/runtime/strands/flows/<kit-id>/<asset-id>.flow.json` and produces a parity-diagnostic `activation.json` (same schema as codex-local: `schema_version`, `adapter`, `supported_asset_classes`, `generated_runtime_files`, `skipped_assets`, `warnings`, `errors`).

package/docs/vision.md

@@ -20,7 +20,7 @@ One official framework adapter spike exists: `integrations/strands/` is a Python
 
 ### What ships today
 
-Kit authoring is shipped. The `kit.json` contract at schema version 1.0 is validated by the `flow-kit` CLI before any install. The [Kit Authoring Guide](kit-authoring-guide.html) walks from an empty directory to a validated, locally installed kit. Two reference kits ship in `kits/`:
+Kit authoring is shipped. The `kit.json` contract at schema version 1.0 is validated by the `flow-agents kit` CLI before any install. The [Kit Authoring Guide](kit-authoring-guide.html) walks from an empty directory to a validated, locally installed kit. Two reference kits ship in `kits/`:
 
 **Builder Kit** packages the full `idea → backlog → plan → build → review → verify → evidence → release → learning` pipeline as two flows (`builder.shape`, `builder.build`). It installs automatically.
 

package/docs/workflow-usage-guide.md

@@ -43,7 +43,7 @@ Separate these into distinct ideas, use Probe/alignment questions if the outcome
 
 Expected behavior:
 
-- delegate shaping to `skills/idea-to-backlog/SKILL.md`
+- delegate shaping to `kits/builder/skills/idea-to-backlog/SKILL.md`
 - link the artifact to the Builder Kit Flow Definition at `kits/builder/flows/shape.flow.json`
 - inventory each distinct idea separately
 - classify each idea

package/evals/fixtures/builder-kit-workflow-state/happy-path.json

@@ -49,8 +49,8 @@
     "planning_readiness": "ready",
     "expected_modified_files": [
       "context/contracts/builder-kit-workflow-state-contract.md",
-      "skills/design-probe/SKILL.md",
-      "skills/pickup-probe/SKILL.md"
+      "kits/builder/skills/design-probe/SKILL.md",
+      "kits/builder/skills/pickup-probe/SKILL.md"
     ],
     "conflict_risks": [
       "workflow guidance shared with downstream Builder Kit automation"

package/evals/fixtures/builder-kit-workflow-state/mid-work-resume.json

@@ -54,8 +54,8 @@
     "planning_readiness": "completed",
     "expected_modified_files": [
       "context/contracts/builder-kit-workflow-state-contract.md",
-      "skills/design-probe/SKILL.md",
-      "skills/pickup-probe/SKILL.md",
+      "kits/builder/skills/design-probe/SKILL.md",
+      "kits/builder/skills/pickup-probe/SKILL.md",
       "evals/fixtures/builder-kit-workflow-state/happy-path.json",
       "evals/fixtures/builder-kit-workflow-state/mid-work-resume.json"
     ],

package/evals/fixtures/console-learning-projection/artifacts/console-learning-correction/learning.json

@@ -28,7 +28,7 @@
           "target": "skill",
           "action": "Update workflow learning guidance after release.",
           "status": "deferred",
-          "ref": "skills/learning-review/SKILL.md"
+          "ref": "kits/builder/skills/learning-review/SKILL.md"
         }
       ],
       "correction": {

package/evals/fixtures/pull-work-provider/github-issues.json

@@ -73,7 +73,7 @@
     "number": 97,
     "title": "Emit source revision metadata and structured blockers",
     "state": "OPEN",
-    "body": "## Problem\nDownstream pickup needs durable source revision and blocker metadata.\n\n## Scope\n- Emit provider-neutral work-item metadata.\n- Preserve human-readable blocker prose.\n\n## Acceptance criteria\n- Source revision fields normalize.\n- Structured blockers preserve provider refs and text blockers.\n\n## Dependencies / Blockers\nRequires kontourai/flow#2.\nBlocked by product decision on rollout scope.\n\n## Source artifact\n`.flow-agents/idea-to-backlog-source-revision-structured-blockers/idea-to-backlog-source-revision-structured-blockers--plan.md`\n\n<!-- flow-agents:work-item-metadata\n{\n  \"schema_version\": \"1.0\",\n  \"source_revisions\": [\n    {\n      \"repo\": \"kontourai/flow-agents\",\n      \"planned_base_ref\": \"main\",\n      \"planned_base_sha\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\n      \"planned_at\": \"2026-06-03T03:23:14Z\",\n      \"planning_artifact_ref\": \".flow-agents/idea-to-backlog-source-revision-structured-blockers/idea-to-backlog-source-revision-structured-blockers--plan.md\",\n      \"planning_scope_refs\": [\n        \"skills/idea-to-backlog/SKILL.md\",\n        \"context/contracts/work-item-contract.md\"\n      ]\n    },\n    {\n      \"repo\": \"kontourai/flow\",\n      \"planned_base_ref\": \"main\",\n      \"planned_base_sha\": \"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\n      \"planned_at\": \"2026-06-03T03:23:14Z\",\n      \"planning_artifact_ref\": \".flow-agents/idea-to-backlog-source-revision-structured-blockers/idea-to-backlog-source-revision-structured-blockers--plan.md\",\n      \"planning_scope_refs\": [\"context/contracts/work-item-contract.md\"]\n    }\n  ],\n  \"blockers\": [\n    {\n      \"type\": \"work_item\",\n      \"ref\": \"kontourai/flow#2\",\n      \"status\": \"blocked\",\n      \"summary\": \"Requires Flow contract issue first.\"\n    },\n    {\n      \"type\": \"text\",\n      \"status\": \"blocked\",\n      \"summary\": \"Product decision on rollout scope.\"\n    }\n  ]\n}\n-->",
+    "body": "## Problem\nDownstream pickup needs durable source revision and blocker metadata.\n\n## Scope\n- Emit provider-neutral work-item metadata.\n- Preserve human-readable blocker prose.\n\n## Acceptance criteria\n- Source revision fields normalize.\n- Structured blockers preserve provider refs and text blockers.\n\n## Dependencies / Blockers\nRequires kontourai/flow#2.\nBlocked by product decision on rollout scope.\n\n## Source artifact\n`.flow-agents/idea-to-backlog-source-revision-structured-blockers/idea-to-backlog-source-revision-structured-blockers--plan.md`\n\n<!-- flow-agents:work-item-metadata\n{\n  \"schema_version\": \"1.0\",\n  \"source_revisions\": [\n    {\n      \"repo\": \"kontourai/flow-agents\",\n      \"planned_base_ref\": \"main\",\n      \"planned_base_sha\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\n      \"planned_at\": \"2026-06-03T03:23:14Z\",\n      \"planning_artifact_ref\": \".flow-agents/idea-to-backlog-source-revision-structured-blockers/idea-to-backlog-source-revision-structured-blockers--plan.md\",\n      \"planning_scope_refs\": [\n        \"kits/builder/skills/idea-to-backlog/SKILL.md\",\n        \"context/contracts/work-item-contract.md\"\n      ]\n    },\n    {\n      \"repo\": \"kontourai/flow\",\n      \"planned_base_ref\": \"main\",\n      \"planned_base_sha\": \"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\n      \"planned_at\": \"2026-06-03T03:23:14Z\",\n      \"planning_artifact_ref\": \".flow-agents/idea-to-backlog-source-revision-structured-blockers/idea-to-backlog-source-revision-structured-blockers--plan.md\",\n      \"planning_scope_refs\": [\"context/contracts/work-item-contract.md\"]\n    }\n  ],\n  \"blockers\": [\n    {\n      \"type\": \"work_item\",\n      \"ref\": \"kontourai/flow#2\",\n      \"status\": \"blocked\",\n      \"summary\": \"Requires Flow contract issue first.\"\n    },\n    {\n      \"type\": \"text\",\n      \"status\": \"blocked\",\n      \"summary\": \"Product decision on rollout scope.\"\n    }\n  ]\n}\n-->",
     "labels": [],
     "assignees": [],
     "milestone": null,
@@ -101,7 +101,7 @@
     "number": 110,
     "title": "Fresh planned item",
     "state": "OPEN",
-    "body": "## Scope\nUse fresh source revision metadata.\n\n## Acceptance criteria\nFreshness is verified.\n\n<!-- flow-agents:work-item-metadata\n{\n  \"schema_version\": \"1.0\",\n  \"planned_base_ref\": \"main\",\n  \"planned_base_sha\": \"cccccccccccccccccccccccccccccccccccccccc\",\n  \"planned_at\": \"2026-06-02T00:00:00Z\",\n  \"planning_artifact_ref\": \".flow-agents/fresh/fresh--plan.md\",\n  \"planning_scope_refs\": [\"skills/pull-work/SKILL.md\"]\n}\n-->",
+    "body": "## Scope\nUse fresh source revision metadata.\n\n## Acceptance criteria\nFreshness is verified.\n\n<!-- flow-agents:work-item-metadata\n{\n  \"schema_version\": \"1.0\",\n  \"planned_base_ref\": \"main\",\n  \"planned_base_sha\": \"cccccccccccccccccccccccccccccccccccccccc\",\n  \"planned_at\": \"2026-06-02T00:00:00Z\",\n  \"planning_artifact_ref\": \".flow-agents/fresh/fresh--plan.md\",\n  \"planning_scope_refs\": [\"kits/builder/skills/pull-work/SKILL.md\"]\n}\n-->",
     "labels": [],
     "assignees": [],
     "milestone": null,
@@ -115,7 +115,7 @@
     "number": 111,
     "title": "Drifted planned item",
     "state": "OPEN",
-    "body": "## Scope\nUse drifted source revision metadata.\n\n## Acceptance criteria\nFreshness reports benign drift.\n\n<!-- flow-agents:work-item-metadata\n{\n  \"schema_version\": \"1.0\",\n  \"planned_base_ref\": \"main\",\n  \"planned_base_sha\": \"dddddddddddddddddddddddddddddddddddddddd\",\n  \"planned_at\": \"2026-06-01T00:00:00Z\",\n  \"planning_artifact_ref\": \".flow-agents/drifted/drifted--plan.md\",\n  \"planning_scope_refs\": [\"skills/pickup-probe/SKILL.md\"]\n}\n-->",
+    "body": "## Scope\nUse drifted source revision metadata.\n\n## Acceptance criteria\nFreshness reports benign drift.\n\n<!-- flow-agents:work-item-metadata\n{\n  \"schema_version\": \"1.0\",\n  \"planned_base_ref\": \"main\",\n  \"planned_base_sha\": \"dddddddddddddddddddddddddddddddddddddddd\",\n  \"planned_at\": \"2026-06-01T00:00:00Z\",\n  \"planning_artifact_ref\": \".flow-agents/drifted/drifted--plan.md\",\n  \"planning_scope_refs\": [\"kits/builder/skills/pickup-probe/SKILL.md\"]\n}\n-->",
     "labels": [],
     "assignees": [],
     "milestone": null,
@@ -129,7 +129,7 @@
     "number": 112,
     "title": "Stale planned item",
     "state": "OPEN",
-    "body": "## Scope\nUse stale source revision metadata.\n\n## Acceptance criteria\nFreshness routes stale work.\n\n<!-- flow-agents:work-item-metadata\n{\n  \"schema_version\": \"1.0\",\n  \"planned_base_ref\": \"main\",\n  \"planned_base_sha\": \"eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\",\n  \"planned_at\": \"2026-04-01T00:00:00Z\",\n  \"planning_artifact_ref\": \".flow-agents/stale/stale--plan.md\",\n  \"planning_scope_refs\": [\"context/contracts/work-item-contract.md\", \"skills/pull-work/SKILL.md\"]\n}\n-->",
+    "body": "## Scope\nUse stale source revision metadata.\n\n## Acceptance criteria\nFreshness routes stale work.\n\n<!-- flow-agents:work-item-metadata\n{\n  \"schema_version\": \"1.0\",\n  \"planned_base_ref\": \"main\",\n  \"planned_base_sha\": \"eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\",\n  \"planned_at\": \"2026-04-01T00:00:00Z\",\n  \"planning_artifact_ref\": \".flow-agents/stale/stale--plan.md\",\n  \"planning_scope_refs\": [\"context/contracts/work-item-contract.md\", \"kits/builder/skills/pull-work/SKILL.md\"]\n}\n-->",
     "labels": [],
     "assignees": [],
     "milestone": null,
@@ -143,7 +143,7 @@
     "number": 113,
     "title": "Legacy item missing planned base",
     "state": "OPEN",
-    "body": "## Scope\nPreserve legacy gap for missing planned_base_sha.\n\n## Acceptance criteria\nFreshness is not verified.\n\n<!-- flow-agents:work-item-metadata\n{\n  \"schema_version\": \"1.0\",\n  \"planned_base_ref\": \"main\",\n  \"planned_at\": \"2026-06-01T00:00:00Z\",\n  \"planning_artifact_ref\": \".flow-agents/legacy/legacy--plan.md\",\n  \"planning_scope_refs\": [\"skills/pull-work/SKILL.md\"]\n}\n-->",
+    "body": "## Scope\nPreserve legacy gap for missing planned_base_sha.\n\n## Acceptance criteria\nFreshness is not verified.\n\n<!-- flow-agents:work-item-metadata\n{\n  \"schema_version\": \"1.0\",\n  \"planned_base_ref\": \"main\",\n  \"planned_at\": \"2026-06-01T00:00:00Z\",\n  \"planning_artifact_ref\": \".flow-agents/legacy/legacy--plan.md\",\n  \"planning_scope_refs\": [\"kits/builder/skills/pull-work/SKILL.md\"]\n}\n-->",
     "labels": [],
     "assignees": [],
     "milestone": null,

package/evals/integration/test_activate_npx_context.sh

@@ -14,7 +14,7 @@ trap 'rm -rf "$TMP_DIR"' EXIT
 pass() { echo "  ✓ $1"; }
 fail() { echo "  ✗ $1"; errors=$((errors + 1)); }
 
-CLI="$ROOT/scripts/flow-kit.js"
+CLI="$ROOT/scripts/kit.js"
 MIXED_SRC="$ROOT/evals/fixtures/flow-kit-repository/mixed-runtime-kit"
 
 echo "=== activate npx-context Checks (Issue #57) ==="
@@ -27,7 +27,7 @@ mkdir -p "$DEST"
 
 # Install a kit into the destination workspace first.
 install_out="$TMP_DIR/install.out"
-if flow_agents_node "$CLI" install-local "$MIXED_SRC" --dest "$DEST" >"$install_out" 2>&1; then
+if flow_agents_node "$CLI" install "$MIXED_SRC" --dest "$DEST" >"$install_out" 2>&1; then
   pass "mixed-runtime-kit installs into workspace"
 else
   fail "install failed (prerequisite step)"