@kontourai/flow-agents 0.1.1 → 0.2.0

package/docs/integrations/harness-install.md

@@ -0,0 +1,213 @@
+---
+title: Harness Install
+---
+
+# Harness Install
+
+This page walks through three harness installs: Claude Code (the L2 reference runtime), opencode, and pi. All three follow the same model — `npm run build:bundles` generates the bundle, `flow-agents init` places it — but each runtime expects different files at different paths.
+
+## How harness bundles work
+
+`npm run build:bundles` generates one bundle per runtime under `dist/<runtime>/`. Each bundle contains:
+
+- A host-specific configuration file that maps lifecycle events to shell commands invoking the canonical hook adapter wrapper.
+- A host-specific adapter wrapper (`<runtime>-hook-adapter.js`) that reads stdin JSON from the host, invokes `run-hook.js` with the canonical script path and profile, translates the exit code to the host-native response format, and fails open on errors.
+- A host-specific telemetry wrapper (`<runtime>-telemetry-hook.js`) that maps host event names to canonical telemetry event names and invokes `scripts/telemetry/telemetry.sh`.
+- An `install.sh` that places the generated files at the host-expected paths.
+
+`flow-agents init` (from `npx @kontourai/flow-agents`) calls `install.sh` for the selected runtime.
+
+## Claude Code
+
+Claude Code is the L2 reference implementation. All four policy classes are wired: workflow steering, quality gate, stop-goal-fit, and config protection.
+
+### Install
+
+```bash
+npx @kontourai/flow-agents init --runtime claude-code --dest /path/to/workspace --yes
+```
+
+The install script writes hook wiring into `.claude/settings.json` inside the destination workspace. The hooks object in `settings.json` maps Claude Code lifecycle events (`UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`) to shell commands invoking the adapter:
+
+```bash
+bash -lc 'root="${FLOW_AGENTS_CLAUDE_CODE_ROOT:-$(pwd)}"; \
+  node "$root/scripts/hooks/claude-telemetry-hook.js" UserPromptSubmit dev'
+bash -lc 'root="${FLOW_AGENTS_CLAUDE_CODE_ROOT:-$(pwd)}"; \
+  node "$root/scripts/hooks/claude-hook-adapter.js" UserPromptSubmit \
+    workflow-steering workflow-steering.js default'
+```
+
+Telemetry always fires first and is always non-blocking (timeout: 10 s). Policy hooks fire second and may block on `PreToolUse` (timeout: 30 s). Both fail open on hook runtime errors.
+
+### Dogfood variant (repo-local)
+
+Inside the `flow-agents` source repo itself, the dogfood script writes hook wiring that points at the local `scripts/hooks/` directory rather than a published package:
+
+```bash
+npm run dogfood -- --runtime claude-code
+```
+
+The destination defaults to the repo root. Pass `--dest` to override.
+
+### Scope-collision warning
+
+When `init` detects that an existing `.claude/settings.json` already has hooks entries for the same lifecycle events, it emits a scope-collision warning to stderr:
+
+```
+[flow-agents] WARNING: .claude/settings.json already has hooks for UserPromptSubmit.
+Existing entries will be preserved; Flow Agents hooks will be appended.
+Review .claude/settings.json to confirm hook ordering is correct.
+```
+
+The install appends rather than replaces, so existing hooks are not removed. Review the settings file after install to confirm the ordering is what you want.
+
+### Resulting file layout
+
+```
+<workspace>/
+  .claude/
+    settings.json          ← hook wiring (appended by install)
+  scripts/
+    hooks/
+      claude-hook-adapter.js
+      claude-telemetry-hook.js
+      run-hook.js
+      config-protection.js
+      quality-gate.js
+      stop-goal-fit.js
+      workflow-steering.js
+      …
+  skills/
+    …
+  .flow-agents/            ← runtime workflow artifacts (not committed)
+```
+
+## opencode
+
+opencode is an L1 adapter. It has no native `prompt.submit`-equivalent event, so workflow steering is approximated at `session.created` rather than at each user turn. This is a documented gap: see <a href="../spec/runtime-hook-surface.html">the spec, section 2.1</a>.
+
+### Install
+
+```bash
+npx @kontourai/flow-agents init --runtime opencode --dest /path/to/workspace --yes
+```
+
+### Dogfood variant
+
+```bash
+npm run dogfood -- --runtime opencode
+```
+
+### Resulting file layout
+
+```
+<workspace>/
+  .opencode/
+    plugins/
+      flow-agents.js       ← auto-loaded at opencode startup
+    agents/
+      dev.md               ← agent prompts (opencode markdown format)
+      tool-planner.md
+      tool-worker.md
+      …
+    skills/
+      deliver.md
+      fix-bug.md
+      …
+  opencode.json            ← workspace instructions pointer
+  scripts/
+    hooks/
+      opencode-hook-adapter.js
+      opencode-telemetry-hook.js
+      run-hook.js
+      …
+  skills/
+    …
+```
+
+`opencode.json` at the workspace root is a minimal config file:
+
+```json
+{
+  "instructions": "This workspace uses Flow Agents. See AGENTS.md for conventions, skills, and workflow guidance."
+}
+```
+
+The plugin at `.opencode/plugins/flow-agents.js` is auto-loaded at opencode startup. It exports `FlowAgentsPlugin` and registers handlers for:
+
+| opencode event | What fires |
+| --- | --- |
+| `session.created` | Telemetry + workflow steering (session-start context injection) |
+| `tool.execute.before` | Telemetry + config-protection (blocking via thrown Error) |
+| `tool.execute.after` | Telemetry + quality gate |
+| `session.idle` | Telemetry + stop-goal-fit (warning only — not a true stop event) |
+| `session.error`, `session.compacted`, `permission.asked`, `file.edited` | Telemetry only |
+
+**Accepted gaps**: opencode has no `prompt.submit` hook, so workflow steering fires only on `session.created` — not at each user turn. `session.idle` is the closest event to a stop hook but does not reliably fire on session completion. These gaps are declared in the conformance level (L1) and in the plugin source comments.
+
+**Agents**: opencode receives agent prompts as markdown files in `.opencode/agents/`. The main orchestrator is `dev.md`; specialist tools (planner, worker, reviewer, etc.) are additional markdown files in the same directory.
+
+## pi
+
+pi is an L1 adapter. It has no stop hook, so stop-goal-fit cannot fire at session end. This is a documented gap: see <a href="../spec/runtime-hook-surface.html">the spec, section 2.3</a>.
+
+### Install
+
+```bash
+npx @kontourai/flow-agents init --runtime pi --dest /path/to/workspace --yes
+```
+
+### Dogfood variant
+
+```bash
+npm run dogfood -- --runtime pi
+```
+
+### Resulting file layout
+
+```
+<workspace>/
+  .pi/
+    extensions/
+      flow-agents.ts       ← auto-discovered at startup (needs project trust)
+    skills/
+      deliver.md
+      fix-bug.md
+      …
+  AGENTS.md                ← agent instructions (pi uses AGENTS.md, not a registry)
+  scripts/
+    hooks/
+      pi-hook-adapter.js
+      pi-telemetry-hook.js
+      run-hook.js
+      …
+  skills/
+    …
+```
+
+The extension at `.pi/extensions/flow-agents.ts` is auto-discovered at startup. It registers handlers for:
+
+| pi event | What fires |
+| --- | --- |
+| `session_start` | Telemetry |
+| `before_agent_start` | Telemetry + workflow steering (injects context into system prompt) |
+| `tool_call` | Telemetry + config-protection (blocking via `{ block: true }` return) |
+| `tool_result` | Telemetry + quality gate |
+| `session_shutdown` | Telemetry + stop-goal-fit (warning only — not a true stop event) |
+
+**Accepted gaps**: pi has no stop hook. `session_shutdown` is used as the closest equivalent but does not carry the same semantics as a stop event. This gap is declared in the conformance level (L1) and in the extension source comments.
+
+**Agents**: pi has no named-subagent registry. Agent guidance is delivered through `AGENTS.md` at the workspace root, plus the skills in `.pi/skills/` and the extension. The `flow-agents.ts` extension comment says explicitly: "pi has no named-subagent registry. Agents are not exported for pi."
+
+### Scope-collision warning
+
+Same behavior as Claude Code: if an existing `.pi/extensions/` directory contains a file with conflicting event registrations, `init` warns and appends. Review the extension file after install.
+
+## Related references
+
+- `dist/opencode/` — generated opencode bundle (do not edit by hand)
+- `dist/pi/` — generated pi bundle (do not edit by hand)
+- `dist/claude-code/` — generated Claude Code bundle
+- `scripts/hooks/run-hook.js` — canonical hook runner
+- <a href="../spec/runtime-hook-surface.html">Runtime Hook Surface spec</a> — event taxonomy, policy classes, conformance levels
+- <a href="conformance.html">Conformance</a> — how to self-certify a new adapter

package/docs/integrations/index.md

@@ -0,0 +1,54 @@
+---
+title: Integration Examples
+---
+
+# Integration Examples
+
+Flow Agents reaches host runtimes and agent frameworks through two distinct distribution models. This section provides worked examples for each model and a guide to the conformance kit for third-party adapter authors.
+
+## Distribution models at a glance
+
+**Harness runtimes** ship as self-contained bundles under `dist/<runtime>/`. The `npm run build:bundles` command generates each bundle from the canonical manifest and policy scripts. `flow-agents init` (or the dogfood variant) places the generated files at the host-expected paths inside a target workspace. Claude Code, Codex, Kiro, opencode, and pi are harness adapters.
+
+**Framework adapters** live in `integrations/<name>/` as language-native packages. They register Flow Agents callbacks with the framework's lifecycle system using the framework's native registration API. `integrations/strands/` is the reference implementation: `flow-agents-strands` is a Python `HookProvider` that wires into AWS Strands Agents without requiring the Strands SDK at import time.
+
+**Third-party adapters** self-certify by running the conformance kit in `packaging/conformance/`. The kit provides golden fixtures and a runner that pipes each fixture through the adapter command and reports per-level verdict.
+
+## Conformance levels
+
+| Level | What is required |
+| --- | --- |
+| L0 | Telemetry only — at least `agentSpawn` fires on session start |
+| L1 | L0 plus workflow steering and stop-goal-fit in warning mode |
+| L2 | L1 plus config protection (blocking) and quality gate — the reference level |
+
+Claude Code and Codex are L2 reference implementations. opencode is L1 (no prompt-submit hook). pi is L1 (no stop hook). The Strands adapter is L0 plus config protection via `BeforeToolCallEvent` cancellation.
+
+The <a href="../spec/runtime-hook-surface.html">Runtime Hook Surface spec</a> defines the canonical event taxonomy, policy classes, conformance levels, and engine contract in full.
+
+## Pages in this section
+
+<div class="doc-grid">
+  <a class="doc-card" href="harness-install.html">
+    <strong>Harness Install</strong>
+    <span>Worked example installing into a Claude Code project, and the two newest runtimes: opencode and pi. Includes the dogfood variant and scope-collision warning behavior.</span>
+  </a>
+  <a class="doc-card" href="framework-adapter.html">
+    <strong>Framework Adapter</strong>
+    <span>Worked example based on <code>integrations/strands/</code>: constructing FlowAgentsHooks, telemetry emitted, the engine-contract binding for policy, and documented limitations.</span>
+  </a>
+  <a class="doc-card" href="conformance.html">
+    <strong>Conformance</strong>
+    <span>How a third-party adapter self-certifies: the engine contract 1.0, running the conformance runner, what each level requires, and how to declare gaps.</span>
+  </a>
+  <a class="doc-card" href="../spec/runtime-hook-surface.html">
+    <strong>Runtime Hook Surface Spec</strong>
+    <span>Canonical event taxonomy, four policy classes, conformance levels L0/L1/L2, mapping tables, and the engine contract for adapter authors.</span>
+  </a>
+</div>
+
+---
+
+## TypeScript native-import adapter
+
+`integrations/strands-ts/` (`@kontourai/flow-agents-strands`) is the first native-import consumer of the policy engine contract. It binds the `config-protection.js` `run()` function directly — no subprocess on the hot path. Achieves **L2** conformance. See `integrations/strands-ts/README.md` and the [Framework Adapter](framework-adapter.html) page for the full comparison with the Python adapter.

package/docs/north-star.md

@@ -152,9 +152,9 @@ The goal is not to add ceremony. The goal is to make agents more reliable while
 | [x] | Standards register | Supported standards and Flow Agents-owned formats are documented with adoption rules. |
 | [ ] | Structured workflow state | Draft schemas, contracts, validation, explicit current-session identity, delegation-safe agent event logs, sidecar writer commands, and direct workflow-skill writer instructions exist for state, acceptance, evidence, handoff, critique, release, and learning; automatic enforcement remains partial. |
 | [ ] | Context map | Generated repo/context map exists; workflow steering and core planner/worker/verifier agents now use it, but broader agent coverage remains. |
-| [ ] | JIT guidance | Stop hook checks sidecars; workflow steering reads `state.json`, `critique.json`, context-map availability, and high-risk state after non-subagent tools; broader file/task-aware guidance remains. |
+| [ ] | JIT guidance | Stop hook checks sidecars; workflow steering reads `state.json`, `critique.json`, context-map availability, and high-risk state after non-subagent tools; the opt-in utterance evidence-check hook (ADR 0003 §9) badges unsupported agent statements via Survey; broader file/task-aware guidance remains. |
 | [x] | Sandbox policy | `context/contracts/sandbox-policy.md` and https://github.com/kontourai/flow-agents/blob/main/docs/sandbox-policy.md classify local read-only, local edit, worktree, container, cloud sandbox, and privileged integration modes. |
-| [ ] | Evidence integration | Evidence sidecars now carry `standard_refs` for SARIF, OpenTelemetry, JUnit/TAP, Veritas, and custom proof; a local Veritas readiness wrapper can record native Veritas reports as optional Flow Agents evidence. |
+| [ ] | Evidence integration | Evidence sidecars now carry `standard_refs` for SARIF, OpenTelemetry, JUnit/TAP, Veritas, and custom proof; a local Veritas readiness wrapper records native Veritas reports as optional evidence; utterance trust reports from `@kontourai/survey` cover agent statements. |
 | [ ] | Feedback loop | Runtime telemetry, outcomes, evals, and recurring corrections feed back into docs, skills, rules, or backlog. |
 | [ ] | Export validation | Codex, Claude Code, and Kiro exports preserve the same operating layers and now install telemetry, Goal Fit, and workflow steering hook wiring; adapter output, installed-command coverage, Claude live hook influence, and Kiro live strict-stop coverage exist. |
 
@@ -180,7 +180,7 @@ Tasks:
 
 - Document the public layers: rules, skills, powers, agents, workflows, knowledge, and evidence. **Done:** see https://github.com/kontourai/flow-agents/blob/main/docs/operating-layers.md.
 - Mark which directories are canonical source, generated exports, runtime state, and optional integrations.
-- Decide which workflow skills are part of the core pack and which are optional domain packs. **Started:** `packaging/packs.json` defines core, development, knowledge, AWS, and experimental packs.
+- Decide which workflow skills are part of the core pack and which are optional domain packs. **Started:** `packaging/packs.json` defines core and development packs.
 - Add a standards register that lists each external standard, how Flow Agents uses it, and what Flow Agents-owned schemas still exist. **Done:** see https://github.com/kontourai/flow-agents/blob/main/docs/standards-register.md.
 - Add a "do not invent without checking standards" rule to contributor docs.
 

package/docs/repository-structure.md

@@ -96,7 +96,7 @@ specific row that matches the change.
 | Bundle/export shape | `packaging/`, `src/tools/build-universal-bundles.ts`, and source directories copied into bundles | `bash evals/static/test_universal_bundles.sh` |
 | Installer or local runtime setup behavior | `scripts/install-*.sh`, package bins, and generated bundle install scripts | `bash evals/integration/test_bundle_install.sh` |
 | Workflow artifact, sidecar, or provider contract | `context/contracts/`, `schemas/`, `src/cli/workflow-*`, and matching eval fixtures | `npm run workflow:validate-artifacts --` and workflow integration evals |
-| Flow Kit catalog or bundled kit content | `kits/`, Flow Definition files, and kit repository fixtures | `npm run flow-kit -- validate` or `bash evals/integration/test_flow_kit_repository.sh` |
+| Flow Kit catalog or bundled kit content | `kits/`, Flow Definition files, and kit repository fixtures | `npm run validate:source -- --kit <path>` or `bash evals/integration/test_flow_kit_repository.sh` |
 | Durable developer guidance | `docs/`; regenerate/check the context map when navigation or durable contracts change | `npm run context-map:check --` |
 | Eval scenario or fixture | `evals/static/`, `evals/integration/`, `evals/fixtures/`, or `evals/cases/` | The owning eval plus `bash evals/run.sh static` when contracts are touched |
 | Optional external integration configuration | `integrations/` or `veritas.claims.json`; keep local run output ignored | The integration-specific eval or documented dry run |

package/docs/skills-map.md

@@ -45,6 +45,9 @@ flowchart LR
   Learn -->|new work| Shape
 ```
 
+> `publish-change` is a CLI-driven workflow step, not a loadable skill.
+> `goal-fit` is a hook-enforced check, not a loadable skill.
+
 ## Current Shape
 
 The operating model now has first-class coverage from idea intake through trusted delivery:
@@ -76,7 +79,7 @@ This view shows how each phase is composed. The left rail is the durable phase s
     <div class="phase-step"><span>01</span><strong>Discovery & shaping</strong></div>
     <div class="phase-lanes">
       <section class="phase-lane phase-lane--primary"><h3>Primary</h3><p><code>builder-shape</code> <code>idea-to-backlog</code></p></section>
-      <section class="phase-lane"><h3>Support</h3><p><code>knowledge-search</code> <code>search-first</code> <code>explore</code> <code>crowdsource</code> <code>frontend-design</code> <code>github-cli</code> <code>knowledge-capture</code></p></section>
+      <section class="phase-lane"><h3>Support</h3><p><code>search-first</code> <code>explore</code> <code>frontend-design</code> <code>github-cli</code> <code>knowledge-capture</code></p></section>
       <section class="phase-lane"><h3>Nested sections / future primitives</h3><p>intake/dedupe, separate ideas, thinnest meaningful slice, opportunity review, explore options, <code>shape-work</code>, prioritize work, sync executable backlog</p></section>
       <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Idea, slice, shape, and backlog gates. Writes shaped briefs and GitHub issue links in <code>.flow-agents/&lt;slug&gt;/</code>.</p></section>
     </div>
@@ -112,7 +115,7 @@ This view shows how each phase is composed. The left rail is the durable phase s
     <div class="phase-step"><span>05</span><strong>Learning & improvement</strong></div>
     <div class="phase-lanes">
       <section class="phase-lane phase-lane--primary"><h3>Primary</h3><p><code>learning-review</code></p></section>
-      <section class="phase-lane"><h3>Support</h3><p><code>knowledge-capture</code> <code>observe</code> <code>idea-to-backlog</code> <code>eval-rebuild</code></p></section>
+      <section class="phase-lane"><h3>Support</h3><p><code>knowledge-capture</code> <code>idea-to-backlog</code> <code>eval-rebuild</code></p></section>
       <section class="phase-lane"><h3>Nested sections / future primitives</h3><p>facts vs interpretation, follow-up routing, docs promotion review, knowledge updates, eval updates, skill/backlog improvements</p></section>
       <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Learning gate. Writes outcomes, gaps, docs promotion state, follow-ups, knowledge updates, and verdict.</p></section>
     </div>
@@ -121,11 +124,11 @@ This view shows how each phase is composed. The left rail is the durable phase s
 
 | Phase | Primary workflow skill | Supporting skills | Nested sections / future primitive candidates |
 | --- | --- | --- | --- |
-| Idea discovery and shaping | `builder-shape`, `idea-to-backlog` | `knowledge-search`, `search-first`, `explore`, `crowdsource`, `frontend-design`, `github-cli`, `knowledge-capture` | intake/dedupe, separate ideas, thinnest meaningful slice, opportunity review, explore options, shape work, prioritize work, sync executable backlog |
+| Idea discovery and shaping | `builder-shape`, `idea-to-backlog` | `search-first`, `explore`, `frontend-design`, `github-cli`, `knowledge-capture` | intake/dedupe, separate ideas, thinnest meaningful slice, opportunity review, explore options, shape work, prioritize work, sync executable backlog |
 | Backlog pickup | `pull-work` | `github-cli` | board snapshot, WIP check, grouping/dependency check, Probe decision, worktree decision, handoff |
 | Execution planning and build | `design-probe`, `pickup-probe`, `plan-work`, `execute-plan`, `review-work`, `verify-work` | `feedback-loop`, `browser-test`, `deliver`, `fix-bug`, `tdd-workflow` | Probe notes, Builder Kit Probe record, Definition Of Done, execution plan, parallel waves, implementation session state, critique report, verification report, Goal Fit Gate |
 | Evidence and release confidence | `evidence-gate`, `release-readiness` | `github-cli`, `eval-rebuild` | criteria-to-evidence map, CI confidence, scope/integrity check, publish-change, rollback review, observability review, final acceptance docs, post-deploy plan |
-| Learning and improvement | `learning-review` | `knowledge-capture`, `observe`, `idea-to-backlog`, `eval-rebuild` | facts vs interpretation, docs promotion review, follow-up routing, knowledge updates, eval/skill/backlog improvements |
+| Learning and improvement | `learning-review` | `knowledge-capture`, `idea-to-backlog`, `eval-rebuild` | facts vs interpretation, docs promotion review, follow-up routing, knowledge updates, eval/skill/backlog improvements |
 
 The highest-leverage future extractions are likely `shape-work`, `test-map`, `scope-and-integrity-check`, and `remediate-ci`. They are still nested because their behavior is present, but not yet large enough to need separate activation contracts.
 
@@ -190,6 +193,9 @@ flowchart LR
   Learning -->|systemic change| Eval[eval-rebuild / backlog / skill update]
 ```
 
+> `publish-change` is a CLI-driven workflow step, not a loadable skill.
+> `goal-fit` is a hook-enforced check, not a loadable skill.
+
 ## Eval Coverage
 
 Workflow evals are layered to match this map: