@kontourai/flow-agents 1.0.1 → 1.2.0

package/docs/adr/0007-skill-audit.md

@@ -0,0 +1,112 @@
+---
+title: "Skill Audit 2026-06-15: Flow / Skill / Kit / Tool Boundary"
+---
+
+# Skill Audit: Flow / Skill / Kit / Tool Boundary
+
+**Date:** 2026-06-15  
+**Companion to:** [ADR 0007](./0007-flow-skill-kit-tool-boundary.md)  
+**Scope:** All 26 skills in `skills/` — no skills declared inside kit directories were found separate from those already listed here.
+
+---
+
+## Classification Key
+
+| Label | Meaning |
+| --- | --- |
+| **KIT-SKILL** | The agent's procedural method for one step of a kit-owned flow. Belongs in the kit that owns that flow. |
+| **TOOL** | A raw capability the agent wields. Not tied to any flow step. Should be provided by the runtime or harness, not packaged as a "skill." |
+| **ORPHAN** | Procedural but no flow step can be cited as the home. Either implies a missing/implicit flow, or signals scope drift. |
+
+Flow step IDs used below are from:
+
+- `kits/builder/flows/build.flow.json` — steps: `pull-work`, `design-probe`, `plan`, `execute`, `verify`, `merge-ready`, `pr-open`, `merge-ready-ci`, `learn`, `done`
+- `kits/builder/flows/shape.flow.json` — steps: `shape`, `breakdown`, `file-issues`, `shape-done`
+- `kits/knowledge/flows/ingest.flow.json` — steps: `capture`, `classify`, `route`
+- `kits/knowledge/flows/compile.flow.json` — steps: `select-raws`, `compile`, `link`
+- `kits/knowledge/flows/synthesize.flow.json` — steps: `detect-cluster`, `propose`, `evidence-gate`, `apply-or-reject`
+- `kits/knowledge/flows/consolidate.flow.json` — steps: `related-event`, `propose`, `evidence-gate`, `apply-or-reject`
+- `kits/knowledge/flows/retire.flow.json` — steps: `identify`, `propose-retirement`, `evidence-gate`, `apply-or-reject`
+- `kits/knowledge/flows/store-contract.flow.json` — steps: `verify-contract`
+
+---
+
+## Full Audit Table
+
+| Skill | What It Does | Classification | Kit + Flow Step (if KIT-SKILL) / Rationale (if TOOL or ORPHAN) |
+| --- | --- | --- | --- |
+| `agentic-engineering` | Principles for eval-first loops, task decomposition (15-minute units), model routing (Haiku/Sonnet/Opus), and session strategy. | TOOL | Documents how to use the agent's cognitive capabilities and model-selection judgment. It is guidance the agent *applies* while using tools, not a method for a specific flow step. It is not tied to any flow or kit. |
+| `browser-test` | Delegates browser automation tasks — screenshots, accessibility checks, form filling, UI testing, DOM inspection — to `tool-playwright`. | TOOL | Wraps raw access to a browser automation capability (`tool-playwright`). No flow step backs it; it is a harness/runtime capability the agent directs. Equivalent to "how to run Playwright." |
+| `builder-shape` | User-facing entry into the Builder Kit shape flow — invokes `idea-to-backlog` as a primitive and links `kits/builder/flows/shape.flow.json`; stops at the backlog gate unless issue sync is requested. | KIT-SKILL | **Kit:** builder. **Flow:** `builder.shape`. **Step:** `shape` (and through it, `breakdown` and `file-issues` via `idea-to-backlog` delegation). `builder-shape` is the agent's procedural method for satisfying the `builder.shape` flow's entry step. |
+| `context-budget` | Audits token overhead across installed Flow Agents bundles; scans components and produces a budget report with per-component breakdown and optimization suggestions. | ORPHAN | Procedural and agent-driven, but there is no flow in any kit that has a step for "audit the agent's own context budget." **Implies missing flow:** an implicit "context-health" or "self-maintenance" flow. Until that flow exists and is owned by a kit, this skill is unanchored. |
+| `deliver` | Orchestrates the full plan → execute → review → verify loop, including preflight (pull-work, pickup-probe), looping on failures, and delivery confirmation. | KIT-SKILL | **Kit:** builder. **Flow:** `builder.build`. **Steps:** orchestrates across `pull-work`, `design-probe`, `plan`, `execute`, `verify`, `merge-ready` in sequence. `deliver` is the agent's top-level orchestration method for the builder build flow. It subsumes multiple build-flow steps and is the primary orchestrator skill for that flow. |
+| `dependency-update` | Analyzes and upgrades project dependencies — delegates registry/advisory lookups to `tool-dependencies-updater`, then presents a plan and applies approved updates. | TOOL | Orchestrating a dependency scanner subagent (`tool-dependencies-updater`) is a raw capability use. There is no kit-owned flow with a "dependency-update" step. |
+| `design-probe` | Generic one-question-at-a-time alignment interview — turns unclear goals, designs, or workflow states into shared understanding before planning or execution. | KIT-SKILL | **Kit:** builder. **Flow:** `builder.build`. **Step:** `design-probe`. The skill's own SKILL.md names the Builder Kit `design-probe` step explicitly. It also applies outside Builder Kit, but the canonical flow binding is `builder.build:design-probe`. |
+| `eval-rebuild` | Defines project-specific rebuild/reinstall steps for the eval feedback loop so the `eval-builder` agent knows how to rebuild after editing a prompt or skill. | TOOL | This is harness/tooling guidance for how to run evals — a raw capability instruction with no flow step home. It is not a method for any kit-owned step; it is instructions about how the agent's own evaluation tooling works. |
+| `evidence-gate` | Evaluates whether completed work has enough trustworthy evidence, scope integrity, and provider/runtime signal to publish, continue fixing, or request a human decision. | KIT-SKILL | **Kit:** builder. **Flow:** `builder.build`. **Step:** `verify` (the gate evaluation that determines whether the verify step's evidence satisfies the gate claim `builder.verify.tests`). Also maps to `merge-ready` evidence checks. The skill explicitly separates from release-readiness and handles the `verify`-step gate logic. |
+| `execute-plan` | Parallel execution primitive — reads a plan artifact, fans out to `tool-worker` subagents in waves, and updates the session artifact between waves. | KIT-SKILL | **Kit:** builder. **Flow:** `builder.build`. **Step:** `execute`. The skill is the agent's procedural method for the `execute` step of the builder build flow. |
+| `explore` | Fans out parallel subagents to map codebase structure, entry points, dependencies, architectural patterns, config, tests, and documentation accuracy in one pass. | ORPHAN | Procedural and multi-wave but there is no kit-owned flow step for "explore a codebase." It is used as a support skill during discovery/shaping and debugging but is not anchored to a specific flow step. **Implies missing flow:** a "codebase-onboarding" or "repository-exploration" flow with an `explore` step, or it belongs as a tool-like capability rather than a flow step skill. |
+| `feedback-loop` | Verifies that completed implementation actually works by classifying the change (visual vs. integration) and delegating to the appropriate verification method (Playwright or direct command execution). | ORPHAN | There is no kit-owned flow step called "feedback-loop." It overlaps with the `verify` step of the builder build flow, but its scope is narrower (per-implementation-task confirmation) and it is used as a support skill during `execute-plan`, not as the canonical agent method for the `verify` step. **Implies missing flow:** or this is a tool-like capability (a "quick verify" affordance) that could be subsumed into `verify-work`. |
+| `fix-bug` | Bug-fix orchestrator — adds a diagnosis phase (reproduce + root-cause via `tool-planner`), then chains plan → execute → review → verify identical to `deliver`. | KIT-SKILL | **Kit:** builder. **Flow:** `builder.build`. **Steps:** `design-probe` (root-cause/diagnosis maps to alignment before planning), `plan`, `execute`, `verify`. `fix-bug` is an alternative entry into the builder build flow for defect work; it adds a diagnosis front-end and otherwise implements the same flow steps as `deliver`. |
+| `frontend-design` | Delegates frontend implementation to `tool-worker` with curated design guidelines (typography, color, motion, spatial composition, anti-patterns); requires Playwright visual verification after implementation. | ORPHAN | There is no kit-owned flow with a "frontend-design" step. This skill injects design taste into the `execute` step of the builder build flow but is not the canonical method for that step — it is used as a support layer inside `execute-plan`/`deliver`. **Implies missing flow:** a "frontend" or "UI-design" flow with dedicated design and verify steps, or this is more accurately a library of guidelines that the `execute` step (via `execute-plan`) consumes. |
+| `github-cli` | Uses the `gh` CLI to interact with GitHub — PRs, issues, repos, releases, Actions, gists, search, and arbitrary API calls. | TOOL | `gh` is a raw capability — a command-line tool the agent wields. The skill is a how-to for operating that tool, not a method for a kit-owned flow step. Used as support across many flow steps without being bound to one. |
+| `idea-to-backlog` | Turns raw product or technical ideas into shaped, prioritized, executable GitHub issue backlog through intake, separation, opportunity review, shaping, prioritization, and issue creation. | KIT-SKILL | **Kit:** builder. **Flow:** `builder.shape`. **Steps:** `shape` (idea intake → shaped problem/outcome/constraints/non-goals/success/risk), `breakdown` (slices and thinnest meaningful slices), `file-issues` (creating GitHub issues with provider-neutral metadata). `idea-to-backlog` is the primary agent method that implements all three active steps of `builder.shape`. |
+| `knowledge-capture` | Saves durable knowledge, pointers, decisions, lessons, corrections, and source references into the knowledge base using pointer or curated-knowledge modes. | KIT-SKILL | **Kit:** knowledge. **Flow:** `knowledge.ingest`. **Step:** `capture` (the first step of `knowledge.ingest`: capture raw text → produce a raw record). This skill is the agent's method for the `capture` step of the knowledge ingest flow. |
+| `learning-review` | Captures post-merge/post-deploy/post-incident learnings and routes them back to backlog, workflow skills, tests, docs, or knowledge; includes correction telemetry and a verdict. | KIT-SKILL | **Kit:** builder. **Flow:** `builder.build`. **Step:** `learn`. The skill is the agent's method for the `learn` step of the builder build flow: turn delivery outcomes into durable learning and follow-up routing. |
+| `pickup-probe` | Builder Kit specialization of the `design-probe` flow step — records scope, provider state, WIP/conflict scan, revision freshness, decisions, unresolved questions, accepted gaps, and planning readiness for selected backlog work. | KIT-SKILL | **Kit:** builder. **Flow:** `builder.build`. **Step:** `design-probe` (the `pickup-probe` skill is explicitly described in its SKILL.md as "the Builder Kit pickup specialization of the `design-probe` flow step"). It implements the `design-probe` step for the productized pickup path. |
+| `plan-work` | Planning primitive — delegates codebase analysis and execution plan creation to `tool-planner`; produces a plan artifact, `acceptance.json`, and `handoff.json`. | KIT-SKILL | **Kit:** builder. **Flow:** `builder.build`. **Step:** `plan`. The skill is the agent's method for the `plan` step of the builder build flow. |
+| `pull-work` | Selects ready GitHub issues from the backlog, enforces WIP limits, checks dependencies, determines worktree isolation, and hands selected work to planning. | KIT-SKILL | **Kit:** builder. **Flow:** `builder.build`. **Step:** `pull-work`. The skill is the agent's method for the `pull-work` step of the builder build flow. |
+| `release-readiness` | Decides whether evidence-backed work is ready to merge, release, deploy, or hold — checks committed/pushed state, provider change record, CI/checks, rollback plan, observability, and docs; produces a structured release decision. | KIT-SKILL | **Kit:** builder. **Flow:** `builder.build`. **Steps:** `merge-ready` and `merge-ready-ci`. The skill implements the agent-facing logic for both merge readiness gates: it consumes evidence-gate output, checks operational and CI state, and produces a merge/release/deploy/hold decision. |
+| `review-work` | Report-only critique primitive — delegates to `tool-code-reviewer`, `tool-security-reviewer`, and optionally `tool-dependencies-updater`; records findings through the `critique.json` artifact/sink. | KIT-SKILL | **Kit:** builder. **Flow:** `builder.build`. **Step:** `verify` (review is part of the verify gate's quality checks) or more precisely as an intermediate step between `execute` and the formal `verify` gate. The SKILL.md describes it as a gate that must be satisfied before verification. Mapped to: between `execute` and `verify` in `builder.build`. |
+| `search-first` | Research-before-coding workflow — searches the codebase, package registries, GitHub, and web in parallel; evaluates candidates; and decides to adopt, extend, or build before writing code. | TOOL | This is a research/lookup methodology, not the agent's method for a specific flow step. It is used as a support behavior across multiple steps (shaping, planning, execution) without being anchored to one. It could be seen as a harness capability (web + registry search). |
+| `tdd-workflow` | TDD orchestrator — wraps plan → execute → review → verify with test-first constraints, git checkpoints (RED/GREEN/REFACTOR), and a coverage gate (>= 80%). | KIT-SKILL | **Kit:** builder. **Flow:** `builder.build`. **Steps:** `plan`, `execute`, `verify`. `tdd-workflow` is an alternative parameterization of the builder build flow that enforces test-first discipline across those three steps. |
+| `verify-work` | Verification primitive — delegates to `tool-verifier` and `tool-playwright`; maps evidence to acceptance criteria; updates `evidence.json` and `acceptance.json`. | KIT-SKILL | **Kit:** builder. **Flow:** `builder.build`. **Step:** `verify`. The skill is the canonical agent method for the `verify` step. |
+
+---
+
+## Summary Counts
+
+| Category | Count | Notes |
+| --- | --- | --- |
+| **KIT-SKILL (builder kit)** | 17 | `builder-shape`, `deliver`, `design-probe`, `evidence-gate`, `execute-plan`, `fix-bug`, `idea-to-backlog`, `learning-review`, `pickup-probe`, `plan-work`, `pull-work`, `release-readiness`, `review-work`, `tdd-workflow`, `verify-work`, `knowledge-capture` (builder-side consumer), `fix-bug` (builder alt-entry) |
+| **KIT-SKILL (knowledge kit)** | 1 | `knowledge-capture` implements `knowledge.ingest:capture` |
+| **TOOL** | 6 | `agentic-engineering`, `browser-test`, `dependency-update`, `eval-rebuild`, `github-cli`, `search-first` |
+| **ORPHAN** | 4 | `context-budget`, `explore`, `feedback-loop`, `frontend-design` |
+
+Note: `knowledge-capture` appears in both the builder-kit count above and the knowledge-kit count. The canonical home is the Knowledge Kit (`knowledge.ingest:capture`); its use inside builder flows is as a support dependency.
+
+Corrected final count:
+
+- **KIT-SKILL:** 17 total — 16 belonging to the builder kit (across `builder.build` and `builder.shape` flows), 1 belonging to the knowledge kit (`knowledge.ingest:capture`)
+- **TOOL:** 6
+- **ORPHAN:** 4
+
+---
+
+## Orphans With "Implies Missing Flow" Detail
+
+| Orphan Skill | Implication | Disposition |
+| --- | --- | --- |
+| `context-budget` | Implies missing flow: a "context-health" or "agent-self-audit" flow. No kit currently owns context-budget management as a named flow. This could eventually become a `builder.context-audit` or standalone kit flow. Alternatively, if the repo decides context budgeting is always a harness concern, this should be reclassified as a TOOL and the skill dissolved or folded into harness documentation. | **REMOVED** (2026-06-15). Agent self-maintenance; not a flow-step skill. Conceptually adjacent to `learning-review`; preserved intent noted in ADR 0007. |
+| `explore` | Implies missing flow: a "codebase-onboarding" or "repository-exploration" flow with discrete steps (structure, entry points, dependencies, patterns, docs accuracy). Alternatively, `explore` is a multi-step capability the agent uses across many flow phases — in which case it is more accurately a TOOL (raw codebase-reading capability orchestrated across subagents) than a flow-step skill. | **REMOVED** (2026-06-15). Reclassified as a tool (parallel codebase-reading capability). Preserved intent: seed of a possible future `codebase-onboarding` flow — see ADR 0007. |
+| `feedback-loop` | Implies missing flow: or more precisely, it overlaps with the `verify` step of `builder.build` without being the canonical method for it. The skill is used as a lightweight per-task verification inside `execute-plan`. If the builder build flow added a sub-step or explicit "local-verify" step between `execute` and the formal `verify` gate, `feedback-loop` would map there. Otherwise, it should be subsumed into `verify-work` or reclassified as support tooling. | **REMOVED** (2026-06-15). Subsumed: concern now handled by `verify-work` plus flow route-back. |
+| `frontend-design` | Implies missing flow: a "frontend" or "UI-kit" flow with steps for design direction, implementation, and visual verification. Alternatively, the design guidelines could be packaged as a context resource injected into `execute-plan`/`tool-worker` rather than as a separate "skill." If it stays a skill, it belongs in a hypothetical UI Kit that owns a `frontend.build` flow with design and verify steps. | **REMOVED** (2026-06-15). Preserved intent: "plan-work but for UI" — seed of a possible future UI/Frontend Kit with design + visual-verify steps. Revisit if a UI kit is built. |
+
+---
+
+## Implementation Record (Issue #62, 2026-06-15)
+
+The dispositions in this audit table were implemented in PR #62:
+
+- **16 KIT-SKILLS moved to Builder Kit:** `builder-shape`, `deliver`, `design-probe`, `evidence-gate`, `execute-plan`, `fix-bug`, `idea-to-backlog`, `learning-review`, `pickup-probe`, `plan-work`, `pull-work`, `release-readiness`, `review-work`, `tdd-workflow`, `verify-work` — moved from `skills/<name>/` to `kits/builder/skills/<name>/` and declared in `kits/builder/kit.json` `skills` array.
+- **1 KIT-SKILL moved to Knowledge Kit:** `knowledge-capture` — moved to `kits/knowledge/skills/knowledge-capture/` and declared in `kits/knowledge/kit.json` `skills` array.
+- **4 ORPHANS deleted:** `context-budget`, `explore`, `feedback-loop`, `frontend-design` — removed per Brian's 2026-06-15 ruling above.
+- **6 TOOLs left in place:** `agentic-engineering`, `browser-test`, `dependency-update`, `eval-rebuild`, `github-cli`, `search-first` — remain in `skills/` pending separate reclassification. See `skills/README.md`.
+
+**Structural changes:**
+- `src/tools/build-universal-bundles.ts`: `collectAllSkills()` function added; bundle builders now collect skills from both `skills/` (tool-skills) and kit-declared `skills` arrays. Runtime bundles (`.claude/skills/`, `.codex/skills/`, etc.) include all kit-owned skills unchanged.
+- `src/tools/generate-context-map.ts`: `allSkillPaths()` function added; context map generation now includes kit-owned skills.
+- `src/tools/validate-source-tree.ts`: `validateLegacyRefs()` updated to skip legacy-ref matches that resolve as declared kit-owned asset subpaths.
+- `packaging/packs.json`: Skill entries limited to the 6 remaining tool-skills in `skills/`. Kit-owned skills are no longer listed in packs (they're always included in the bundle as kit assets).
+- `flow-agents kit inspect kits/builder` now reports `k1: true` (skills present).
+- `flow-agents kit inspect kits/knowledge` now reports `k1: true` (skills present).

package/docs/adr/0008-kit-operation-boundary.md

@@ -0,0 +1,88 @@
+---
+title: "ADR 0008: Kit Operation Boundary"
+---
+
+# 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 Owns the Agent-Blind Kit Operations
+
+`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.
+
+### The Agent-Blind Guardrail
+
+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](./0007-flow-skill-kit-tool-boundary.md) — 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`.

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>