@kontourai/flow-agents 0.1.2 → 0.2.0

package/build/src/cli/utterance-check.js

@@ -15,6 +15,9 @@ function usage() {
         "  --utterance TEXT      Utterance text to check (required unless --not-configured).",
         "  --bundle-path FILE    Trust bundle JSON file. Omit for an empty bundle (all unsupported).",
         "  --agent-id ID         Agent identifier for provenance (default: flow-agents-utterance-check).",
+        "  --extractor NAME      Extractor to use: 'reference' (default, pattern-based) or 'anthropic'",
+        "                        (model-backed, requires ANTHROPIC_API_KEY and @kontourai/survey/anthropic).",
+        "  --model MODEL         Model for the anthropic extractor (e.g. claude-haiku-4-5).",
         "  --not-configured      Skip survey call; output not_configured without error.",
         "  --strict              Exit non-zero when any badge is disputed, rejected, or unsupported.",
         "  --help                Show this help.",
@@ -51,6 +54,43 @@ async function loadSurvey() {
         return undefined;
     }
 }
+/**
+ * Dynamically import @kontourai/survey/anthropic and create the Anthropic extractor.
+ * Fails open with a clear not_configured message when the key or peer dep is missing.
+ */
+async function loadAnthropicExtractor(model) {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+        return {
+            notConfigured: true,
+            reason: "anthropic extractor requires ANTHROPIC_API_KEY to be set. " +
+                "Set the environment variable or switch extractor to 'reference'.",
+        };
+    }
+    try {
+        const pkg = "@kontourai/survey/anthropic";
+        const mod = await Function("m", "return import(m)")(pkg);
+        if (typeof mod.createAnthropicUtteranceExtractor !== "function") {
+            return {
+                notConfigured: true,
+                reason: "@kontourai/survey/anthropic does not export createAnthropicUtteranceExtractor. " +
+                    "Update @kontourai/survey to a version that supports the anthropic extractor.",
+            };
+        }
+        const opts = { apiKey };
+        if (model)
+            opts.model = model;
+        return mod.createAnthropicUtteranceExtractor(opts);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            notConfigured: true,
+            reason: `@kontourai/survey/anthropic is not available: ${msg}. ` +
+                "Install @kontourai/survey with the anthropic subpath export, or switch extractor to 'reference'.",
+        };
+    }
+}
 // ---------------------------------------------------------------------------
 // Core check logic
 // ---------------------------------------------------------------------------
@@ -63,6 +103,8 @@ async function runCheck(argv) {
     const agentId = flagString(flags, "agent-id") ?? "flow-agents-utterance-check";
     const notConfigured = flagBool(flags, "not-configured");
     const strict = flagBool(flags, "strict");
+    const extractorName = flagString(flags, "extractor") ?? "reference";
+    const model = flagString(flags, "model");
     if (notConfigured) {
         const report = {
             status: "not_configured",
@@ -106,9 +148,31 @@ async function runCheck(argv) {
         return 1;
     }
     const { surveyAgentUtterance, referenceUtteranceExtractor } = survey;
+    // Resolve which extractor to use.
+    let extractor;
+    if (extractorName === "anthropic") {
+        const anthropicResult = await loadAnthropicExtractor(model);
+        if ("notConfigured" in anthropicResult) {
+            // Fail open: emit not_configured with a clear reason rather than erroring.
+            const report = {
+                status: "not_configured",
+                agent_id: agentId,
+                utterance_excerpt: excerptText(utterance),
+                statements: [],
+                summary: anthropicResult.reason,
+            };
+            process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+            process.stderr.write(`[UtteranceCheck] not_configured: ${anthropicResult.reason}\n`);
+            return 0;
+        }
+        extractor = anthropicResult;
+    }
+    else {
+        extractor = referenceUtteranceExtractor;
+    }
     let trustReport;
     try {
-        trustReport = await surveyAgentUtterance(utterance, referenceUtteranceExtractor, {
+        trustReport = await surveyAgentUtterance(utterance, extractor, {
             bundle,
             agentId,
         });

package/build/src/tools/build-universal-bundles.js

@@ -361,6 +361,270 @@ function buildCodex(agents) {
     writeText(path.join(bundle, "install.sh"), installScript("Codex", "/path/to/workspace"));
     fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
 }
+function exportOpencodeAgent(spec) {
+    // Determine agent mode: orchestrator-like agents -> primary, others -> subagent
+    const primaryAgents = new Set(["dev"]);
+    const mode = primaryAgents.has(spec.name) ? "primary" : "subagent";
+    const prompt = appendExportNote(sanitizeText(spec.prompt, "opencode", "<bundle-root>"), "Kiro hook wiring and JSON-only runtime fields were omitted. If this agent mentions Kiro-specific scheduler or hook behavior, treat that as optional operational guidance rather than a hard dependency.");
+    const lines = ["---"];
+    lines.push(`description: ${String(spec.description ?? "").trim()}`);
+    lines.push(`mode: ${mode}`);
+    lines.push(`model: ${mapped("claude_model_map", spec.model)}`);
+    lines.push("---");
+    lines.push("");
+    lines.push(prompt);
+    return lines.join("\n");
+}
+function exportOpencodePlugin() {
+    // Generate the Flow Agents opencode plugin.
+    // opencode plugins are auto-loaded from .opencode/plugins/*.js at startup.
+    //
+    // NOTE: opencode has no direct user-prompt-submit hook. For prompt-submit
+    // workflow steering, we wire the steering command behind session.created
+    // (for session-start steering context) and tool.execute.before (for
+    // policy). This is the closest reasonable approximation — documented here
+    // as an honest gap matching the codex live-hook-influence caveat pattern.
+    return `/**
+ * Flow Agents opencode plugin.
+ *
+ * Auto-loaded from .opencode/plugins/flow-agents.js at opencode startup.
+ * Delegates policy and telemetry decisions to shared scripts in scripts/hooks/
+ * using the same payload contract as the claude/codex adapters.
+ *
+ * EVENT MAPPING NOTE: opencode has no direct user-prompt-submit hook.
+ * Workflow steering (workflow-steering.js) is wired to session.created
+ * (session-start context) and tool.execute.before (per-tool policy).
+ * This approximates the UserPromptSubmit behavior in other runtimes but
+ * cannot intercept mid-session user messages before they are processed.
+ * This is an accepted gap documented here analogously to the codex
+ * live-hook-influence caveat.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { join, basename } from 'node:path';
+
+// opencode runs plugins inside its own compiled (Bun-based) binary, so
+// process.execPath points at opencode itself — spawning it with a script
+// path silently does nothing (caught by live acceptance smoke 2026-06-11).
+// Resolve a real node binary instead; fall back to PATH lookup.
+const NODE_BIN = basename(process.execPath).startsWith('node') ? process.execPath : 'node';
+
+export const FlowAgentsPlugin = async ({ project, client, $, directory, worktree }) => {
+  const root = directory || process.cwd();
+
+  // The hook scripts read the event payload from stdin; an empty stdin makes
+  // the telemetry pipeline silently skip the emit (fail-open), so every spawn
+  // must pass a payload (caught by live acceptance smoke 2026-06-11).
+  function hookPayload(eventName, detail) {
+    return JSON.stringify({ hook_event_name: eventName, cwd: root, ...(detail || {}) });
+  }
+
+  function runAdapter(adapterScript, eventName, detail, ...args) {
+    const adapterPath = join(root, 'scripts', 'hooks', adapterScript);
+    const result = spawnSync(NODE_BIN, [adapterPath, eventName, ...args], {
+      input: hookPayload(eventName, detail),
+      encoding: 'utf8',
+      cwd: root,
+      env: { ...process.env, FLOW_AGENTS_HOOK_RUNTIME: 'opencode' },
+      timeout: 30000,
+    });
+    try {
+      return JSON.parse(result.stdout || '{}');
+    } catch {
+      return { allow: true };
+    }
+  }
+
+  function runTelemetry(eventName, detail) {
+    const telemetryPath = join(root, 'scripts', 'hooks', 'opencode-telemetry-hook.js');
+    spawnSync(NODE_BIN, [telemetryPath, eventName, 'dev'], {
+      input: hookPayload(eventName, detail),
+      encoding: 'utf8',
+      cwd: root,
+      env: { ...process.env, FLOW_AGENTS_TELEMETRY_RUNTIME: 'opencode' },
+      timeout: 10000,
+    });
+  }
+
+  return {
+    'session.created': async (_input, _output) => {
+      runTelemetry('session.created');
+      // Wire workflow steering on session start for context injection
+      runAdapter('opencode-hook-adapter.js', 'session.created', null, 'workflow-steering', 'workflow-steering.js', 'default');
+    },
+    'tool.execute.before': async (input, output) => {
+      const detail = { tool: input && input.tool, args: output && output.args };
+      runTelemetry('tool.execute.before', detail);
+      const policyResult = runAdapter('opencode-hook-adapter.js', 'tool.execute.before', detail, 'config-protection', 'config-protection.js', 'default');
+      if (policyResult && policyResult.allow === false) {
+        throw new Error(policyResult.reason || 'Blocked by Flow Agents hook policy.');
+      }
+    },
+    'tool.execute.after': async (input, output) => {
+      const detail = { tool: input && input.tool };
+      runTelemetry('tool.execute.after', detail);
+      runAdapter('opencode-hook-adapter.js', 'tool.execute.after', detail, 'quality-gate', 'quality-gate.js', 'default');
+    },
+    'session.idle': async (_input, _output) => {
+      runTelemetry('session.idle');
+      runAdapter('opencode-hook-adapter.js', 'session.idle', null, 'stop-goal-fit', 'stop-goal-fit.js', 'default');
+    },
+    'session.error': async (_input, _output) => {
+      runTelemetry('session.error');
+    },
+    'session.compacted': async (_input, _output) => {
+      runTelemetry('session.compacted');
+    },
+    'permission.asked': async (_input, _output) => {
+      runTelemetry('permission.asked');
+    },
+    'file.edited': async (_input, _output) => {
+      runTelemetry('file.edited');
+    },
+  };
+};
+`;
+}
+function exportOpencodeConfig() {
+    // opencode's config schema requires `instructions` to be an ARRAY of
+    // instruction file paths/globs (a bare string fails validation and aborts
+    // startup). AGENTS.md is loaded natively by opencode, so the config stays
+    // minimal rather than double-including it.
+    return `${JSON.stringify({
+        $schema: "https://opencode.ai/config.json",
+    }, null, 2)}\n`;
+}
+function buildOpencode(agents) {
+    const bundle = path.join(dist, "opencode");
+    resetDir(bundle);
+    copySharedContent(bundle, "opencode", "<bundle-root>");
+    writeText(path.join(bundle, manifest.opencode.task_dir, ".gitkeep"), "");
+    for (const spec of agents) {
+        writeText(path.join(bundle, ".opencode/agents", `${spec.name}.md`), exportOpencodeAgent(spec));
+    }
+    for (const skill of fs.readdirSync(path.join(root, "skills"))) {
+        const skillPath = path.join(root, "skills", skill, "SKILL.md");
+        if (fs.existsSync(skillPath))
+            writeText(path.join(bundle, ".opencode/skills", skill, "SKILL.md"), sanitizeText(readText(skillPath), "opencode", "<bundle-root>"));
+    }
+    writeText(path.join(bundle, ".opencode/plugins/flow-agents.js"), exportOpencodePlugin());
+    writeText(path.join(bundle, "opencode.json"), exportOpencodeConfig());
+    writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("opencode", agents, manifest.opencode.task_dir));
+    writeText(path.join(bundle, "README.md"), exportTargetReadme("opencode", "bash install.sh /path/to/workspace"));
+    writeText(path.join(bundle, "install.sh"), installScript("opencode", "/path/to/workspace"));
+    fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
+}
+function exportPiExtension() {
+    // Generate the Flow Agents pi extension.
+    // pi extensions are auto-discovered from .pi/extensions/*.ts (needs project trust).
+    // pi has no named-subagent registry; agents are not exported. The extension
+    // provides workflow steering (via before_agent_start context injection),
+    // tool-call policy (via tool_call event), and telemetry delegation to shared scripts.
+    return `/**
+ * Flow Agents pi extension.
+ *
+ * Auto-discovered from .pi/extensions/flow-agents.ts at startup (needs project trust).
+ * Delegates policy and telemetry to shared scripts/hooks/ using spawnSync,
+ * mirroring the payload contract used by the claude/codex adapters.
+ *
+ * NOTE: pi has no named-subagent registry. Agents are not exported for pi.
+ * Rely on AGENTS.md + skills + this extension for workflow guidance.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { spawnSync } from "node:child_process";
+import { join, basename } from "node:path";
+
+// pi may run extensions under a non-node runtime (Bun), where process.execPath
+// is not a node binary and spawning it with a script path silently fails.
+// Same failure class the opencode live smoke caught on 2026-06-11.
+const NODE_BIN = basename(process.execPath).startsWith("node") ? process.execPath : "node";
+
+export default function (pi: ExtensionAPI) {
+  const root = process.cwd();
+
+  function runAdapter(adapterScript: string, eventName: string, hookId: string, relScript: string): { allow: boolean; context?: string; reason?: string } {
+    const adapterPath = join(root, "scripts", "hooks", adapterScript);
+    const payload = JSON.stringify({ hook_event_name: eventName, cwd: root });
+    const result = spawnSync(NODE_BIN, [adapterPath, eventName, hookId, relScript, "default"], {
+      input: payload,
+      encoding: "utf8",
+      cwd: root,
+      env: { ...process.env, FLOW_AGENTS_HOOK_RUNTIME: "pi" },
+      timeout: 30000,
+    });
+    try {
+      return JSON.parse(result.stdout || "{}") as { allow: boolean; context?: string; reason?: string };
+    } catch {
+      return { allow: true };
+    }
+  }
+
+  function runTelemetry(eventName: string): void {
+    const telemetryPath = join(root, "scripts", "hooks", "pi-telemetry-hook.js");
+    const payload = JSON.stringify({ hook_event_name: eventName, cwd: root });
+    spawnSync(NODE_BIN, [telemetryPath, eventName, "dev"], {
+      input: payload,
+      encoding: "utf8",
+      cwd: root,
+      env: { ...process.env, FLOW_AGENTS_TELEMETRY_RUNTIME: "pi" },
+      timeout: 10000,
+    });
+  }
+
+  pi.on("session_start", async (_event, _ctx) => {
+    runTelemetry("session_start");
+  });
+
+  pi.on("before_agent_start", async (event, _ctx) => {
+    runTelemetry("before_agent_start");
+    // Inject workflow steering context at agent start
+    const result = runAdapter("pi-hook-adapter.js", "before_agent_start", "workflow-steering", "workflow-steering.js");
+    if (result.context) {
+      return {
+        systemPrompt: event.systemPrompt + "\\n\\n" + result.context,
+      };
+    }
+  });
+
+  pi.on("tool_call", async (event, _ctx) => {
+    runTelemetry("tool_call");
+    const result = runAdapter("pi-hook-adapter.js", "tool_call", "config-protection", "config-protection.js");
+    if (result && result.allow === false) {
+      return { block: true, reason: result.reason || "Blocked by Flow Agents hook policy." };
+    }
+  });
+
+  pi.on("tool_result", async (_event, _ctx) => {
+    runTelemetry("tool_result");
+    runAdapter("pi-hook-adapter.js", "tool_result", "quality-gate", "quality-gate.js");
+  });
+
+  pi.on("session_shutdown", async (_event, _ctx) => {
+    runTelemetry("session_shutdown");
+    runAdapter("pi-hook-adapter.js", "session_shutdown", "stop-goal-fit", "stop-goal-fit.js");
+  });
+}
+`;
+}
+function buildPi(agents) {
+    const bundle = path.join(dist, "pi");
+    resetDir(bundle);
+    copySharedContent(bundle, "pi", "<bundle-root>");
+    writeText(path.join(bundle, manifest.pi.task_dir, ".gitkeep"), "");
+    // pi has no named-subagent registry; agents are left canonical/unexported.
+    // Skills are exported to .pi/skills/ (direct .md files supported in that dir).
+    for (const skill of fs.readdirSync(path.join(root, "skills"))) {
+        const skillPath = path.join(root, "skills", skill, "SKILL.md");
+        if (fs.existsSync(skillPath))
+            writeText(path.join(bundle, ".pi/skills", skill, "SKILL.md"), sanitizeText(readText(skillPath), "pi", "<bundle-root>"));
+    }
+    writeText(path.join(bundle, ".pi/extensions/flow-agents.ts"), exportPiExtension());
+    writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("pi", agents, manifest.pi.task_dir));
+    writeText(path.join(bundle, "README.md"), exportTargetReadme("pi", "bash install.sh /path/to/workspace"));
+    writeText(path.join(bundle, "install.sh"), installScript("pi", "/path/to/workspace"));
+    fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
+}
 function buildCatalog(agents) {
     const kitsCatalog = path.join(root, "kits/catalog.json");
     return {
@@ -379,6 +643,8 @@ export function main() {
     buildKiro(agents);
     buildClaudeCode(agents);
     buildCodex(agents);
+    buildOpencode(agents);
+    buildPi(agents);
     writeText(path.join(dist, "catalog.json"), `${JSON.stringify(buildCatalog(agents), null, 2)}\n`);
     writeText(path.join(dist, "README.md"), "# Universal Bundles\n\nRun `npm run build:bundles` from the repo root to regenerate these bundles.\n");
     console.log("Built bundles:");
@@ -386,6 +652,8 @@ export function main() {
     console.log(" - dist/kiro");
     console.log(" - dist/claude-code");
     console.log(" - dist/codex");
+    console.log(" - dist/opencode");
+    console.log(" - dist/pi");
     if (printDiagnostics && dropDiagnostics.length) {
         console.error("Export sanitization diagnostics:");
         for (const item of dropDiagnostics)

package/build/src/tools/filter-installed-packs.js

@@ -108,10 +108,13 @@ export function main(argv = process.argv.slice(2)) {
     removed += pruneNamedDirs(rootDir, "skills", allPackMembers(packs, "skills"), selected.skills, dryRun);
     removed += pruneNamedDirs(rootDir, ".claude/skills", allPackMembers(packs, "skills"), selected.skills, dryRun);
     removed += pruneNamedDirs(rootDir, ".codex/skills", allPackMembers(packs, "skills"), selected.skills, dryRun);
+    removed += pruneNamedDirs(rootDir, ".opencode/skills", allPackMembers(packs, "skills"), selected.skills, dryRun);
+    removed += pruneNamedDirs(rootDir, ".pi/skills", allPackMembers(packs, "skills"), selected.skills, dryRun);
     removed += pruneNamedDirs(rootDir, "powers", allPackMembers(packs, "powers"), selected.powers, dryRun);
     removed += pruneAgentFiles(rootDir, "agents", ".json", allPackMembers(packs, "agents"), selected.agents, dryRun);
     removed += pruneAgentFiles(rootDir, ".claude/agents", ".md", allPackMembers(packs, "agents"), selected.agents, dryRun);
     removed += pruneAgentFiles(rootDir, ".codex/agents", ".toml", allPackMembers(packs, "agents"), selected.agents, dryRun);
+    removed += pruneAgentFiles(rootDir, ".opencode/agents", ".md", allPackMembers(packs, "agents"), selected.agents, dryRun);
     const summary = {
         selected_packs: [...selectedNames].sort(),
         removed_entries: removed,

package/build/src/tools/validate-source-tree.js

@@ -62,6 +62,10 @@ const hookFilePolicies = new Map([
     ["scripts/hooks/run-hook.js", { category: "hook runner", requiredNeedles: ["isHookEnabled", "Path traversal rejected"] }],
     ["scripts/hooks/config-protection.js", { category: "policy hook", requiredNeedles: ["Config Protection Hook"] }],
     ["scripts/hooks/governance-audit.sh", { category: "policy hook", requiredNeedles: ["governance-audit.sh", "audit_emit"] }],
+    ["scripts/hooks/opencode-hook-adapter.js", { category: "runtime adapter", requiredNeedles: ["opencode", "run-hook.js"] }],
+    ["scripts/hooks/opencode-telemetry-hook.js", { category: "telemetry shim", requiredNeedles: ["opencode", "telemetry"] }],
+    ["scripts/hooks/pi-hook-adapter.js", { category: "runtime adapter", requiredNeedles: ["pi", "run-hook.js"] }],
+    ["scripts/hooks/pi-telemetry-hook.js", { category: "telemetry shim", requiredNeedles: ["pi", "telemetry"] }],
     ["scripts/hooks/post-edit-accumulator.js", { category: "policy hook", requiredNeedles: ["Post-Edit"] }],
     ["scripts/hooks/pre-commit-quality.js", { category: "repo guardrail hook", requiredNeedles: ["staged"] }],
     ["scripts/hooks/quality-gate.js", { category: "policy hook", requiredNeedles: ["Quality"] }],
@@ -95,7 +99,7 @@ const requiredUsageFeedbackFiles = [
 const fixtureOwnershipSelfAuditRefs = new Set([
     "evals/integration/test_fixture_retirement_audit.sh",
 ]);
-const pythonInventoryExcludes = new Set([".git", ".flow-agents", "node_modules", ".venv", "dist", "__pycache__", ".pytest_cache", ".cache", "build"]);
+const pythonInventoryExcludes = new Set([".git", ".flow-agents", "node_modules", ".venv", "dist", "__pycache__", ".pytest_cache", ".cache", "build", "integrations"]);
 const pythonCommandScanRoots = ["README.md", "docs", "context", "skills", "prompts", "agents", "evals", "scripts", "packaging", "package.json"];
 const allowedPythonCommandFiles = [
     /^agents\/tool-explore-deps\.json$/,

package/context/scripts/telemetry/lib/config.sh

@@ -6,7 +6,11 @@ TELEMETRY_CONFIG_FILE="${TELEMETRY_CONFIG_FILE:-${TELEMETRY_DIR}/telemetry.conf}
 
 # Defaults
 TELEMETRY_ENABLED="${TELEMETRY_ENABLED:-true}"
-TELEMETRY_DATA_DIR="${TELEMETRY_DATA_DIR:-$(cd "${TELEMETRY_DIR}/../../.." && pwd)/.telemetry}"
+# TELEMETRY_DIR is <workspace>/scripts/telemetry, so the workspace root is
+# two levels up. Three levels escaped into the workspace's PARENT directory
+# (caught by live acceptance smoke 2026-06-11: events landed in /tmp/.telemetry
+# instead of the installed workspace).
+TELEMETRY_DATA_DIR="${TELEMETRY_DATA_DIR:-$(cd "${TELEMETRY_DIR}/../.." && pwd)/.telemetry}"
 TELEMETRY_SESSION_DIR="${TELEMETRY_SESSION_DIR:-${TELEMETRY_DATA_DIR}/sessions}"
 TELEMETRY_ENRICH_SYSTEM="${TELEMETRY_ENRICH_SYSTEM:-true}"
 TELEMETRY_ENRICH_WORKSPACE="${TELEMETRY_ENRICH_WORKSPACE:-true}"

package/context/settings/flow-agents-settings.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../schemas/flow-agents-settings.schema.json",
+  "schema_version": "1.0",
+  "utteranceCheck": {
+    "enabled": false
+  }
+}

package/docs/context-map.md

@@ -50,6 +50,7 @@ Machine-readable workflow state lives beside Markdown artifacts in `.flow-agents
 | Schema | Title | ID |
 | --- | --- | --- |
 | backlog-provider-settings.schema.json | Flow Agents Backlog Provider Settings | https://flow-agents.dev/schemas/backlog-provider-settings.schema.json |
+| flow-agents-settings.schema.json | Flow Agents Settings | https://flow-agents.dev/schemas/flow-agents-settings.schema.json |
 | workflow-acceptance.schema.json | Flow Agents Workflow Acceptance | https://flow-agents.dev/schemas/workflow-acceptance.schema.json |
 | workflow-critique.schema.json | Flow Agents Workflow Critique | https://flow-agents.dev/schemas/workflow-critique.schema.json |
 | workflow-evidence.schema.json | Flow Agents Workflow Evidence | https://flow-agents.dev/schemas/workflow-evidence.schema.json |

package/docs/index.md

@@ -4,12 +4,12 @@ title: Kontour Flow Agents
 
 # Flow Agents
 
-<p class="home-lede">Coding agents are powerful and forgetful. Flow Agents wraps Codex, Claude Code, Kiro, and CI agents in an operating layer that keeps long-running work inspectable — from idea to release readiness — so you ask for outcomes and the system supplies the path, the state, the checks, and the proof.</p>
+<p class="home-lede">A portable process-discipline layer for agentic work: canonical policies, evidence, and telemetry that compile to whatever hook surface a host exposes — coding-agent harnesses today, agent frameworks next. Flow Agents keeps work inspectable from idea to release readiness so you ask for outcomes and the system supplies the path, the state, the checks, and the proof.</p>
 
 <div class="value-grid">
   <section>
-    <strong>Stay on the path</strong>
-    <span>Turn loose requests into shaped work, plans, implementation waves, review, verification, evidence, and release decisions — the same workflow in every supported runtime.</span>
+    <strong>Four canonical policies</strong>
+    <span>Workflow steering, quality gate, stop-goal-fit, and config protection — each a canonical script under <code>scripts/hooks/</code> that compiles to the host's native hook format. Claude Code and Codex are the L2 reference implementations.</span>
   </section>
   <section>
     <strong>Survive context loss</strong>
@@ -41,7 +41,29 @@ flowchart LR
   Evidence -->|not verified| Plan
 ```
 
-Flow Agents adds the operating layer around the model: skills choose the right workflow, sidecars preserve state, hooks catch stop-short behavior, and evals keep the bundle honest as it changes. The gate semantics underneath — definitions, runs, evidence, route-back — belong to <a href="https://kontourai.github.io/flow/">Kontour Flow</a>; Flow Agents makes that enforcement native inside agent harnesses.
+Flow Agents adds the operating layer around the model: skills choose the right workflow, sidecars preserve state, hooks enforce the four canonical policies, and evals keep the bundle honest as it changes. The gate semantics underneath — definitions, runs, evidence, route-back — belong to <a href="https://kontourai.github.io/flow/">Kontour Flow</a>; Flow Agents compiles those policies to whatever hook surface a host exposes.
+
+## Process-discipline layer
+
+The four canonical policy classes are defined in the <a href="spec/runtime-hook-surface.html">Runtime Hook Surface spec</a> using a runtime-neutral vocabulary. Adapters translate them to the host's native hook format at three conformance levels: <strong>L0</strong> (telemetry only), <strong>L1</strong> (steering + stop-goal-fit warning), and <strong>L2</strong> (all four policies with blocking capability).
+
+### Runtime and support matrix
+
+| Tier | Runtime | Ships | Conformance |
+| --- | --- | --- | --- |
+| Core harness | Claude Code | install + hooks + bundle | L2 — reference implementation |
+| Core harness | Codex | install + hooks + bundle | L2 — reference implementation |
+| Core harness | Kiro | install + hooks + bundle | L2 |
+| Core harness | opencode | agents, skills, plugin, opencode.json | L1 — no prompt-submit hook |
+| Core harness | pi | extension, skills, AGENTS.md | L1 — no stop hook |
+| Official framework adapter | AWS Strands (Python) | `integrations/strands/` spike/preview | L0 + config protection via cancellation |
+| Conformance-certified | Community / third-party | Self-certify | Conformance kit in development |
+
+Documented gaps: opencode has no native `prompt.submit`-equivalent event; pi has no stop hook; Codex live hook influence on model context is limited. The <a href="spec/runtime-hook-surface.html">Runtime Hook Surface spec</a> names every gap explicitly using the canonical event taxonomy.
+
+## Framework adapters
+
+The same canonical policies wire into agent frameworks as in-process language-native packages. `integrations/strands/` contains `flow-agents-strands`, a Python `HookProvider` that emits the canonical telemetry taxonomy and enforces config protection via `BeforeToolCallEvent` cancellation — 50 unit tests, no Strands SDK required. This is a spike/preview. See <a href="spec/runtime-hook-surface.html">the spec</a> for the full framework adapter mapping and minimum viable adapter pseudocode.
 
 ## Quick Start
 
@@ -49,6 +71,13 @@ Flow Agents adds the operating layer around the model: skills choose the right w
 npx @kontourai/flow-agents init --dest /path/to/workspace
 ```
 
+Runtime-specific installs:
+
+```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
+```
 
 Then ask for the workflow you want, in plain language:
 
@@ -77,6 +106,14 @@ Use fix-bug. Reproduce the problem, diagnose root cause, implement the fix, and
     <strong>Workflow Map</strong>
     <span>See the core skills, gates, artifacts, and route-back behavior.</span>
   </a>
+  <a class="doc-card" href="spec/runtime-hook-surface.html">
+    <strong>Runtime Hook Surface</strong>
+    <span>Canonical event taxonomy, four policy classes, conformance levels L0/L1/L2, and host mapping tables for adapter authors.</span>
+  </a>
+  <a class="doc-card" href="vision.html">
+    <strong>Vision and Direction</strong>
+    <span>Where Flow Agents is going: kits beyond coding, TypeScript framework adapters, and Kontour Console as the unifying telemetry surface.</span>
+  </a>
   <a class="doc-card" href="north-star.html">
     <strong>North Star</strong>
     <span>The product promise, design principles, operating layers, and roadmap.</span>
@@ -117,6 +154,10 @@ Use fix-bug. Reproduce the problem, diagnose root cause, implement the fix, and
     <strong>Developer Reference</strong>
     <span>The generated repo map: commands, agents, skills, scripts, and contracts.</span>
   </a>
+  <a class="doc-card" href="integrations/index.html">
+    <strong>Integration Examples</strong>
+    <span>Worked examples for harness runtimes (Claude Code, opencode, pi), framework adapters (AWS Strands), and third-party self-certification with the conformance kit.</span>
+  </a>
 </div>
 
 ## The Kontour family