@kontourai/flow-agents 0.1.1

package/docs/assets/site.js

@@ -0,0 +1,139 @@
+const storageKey = "flow-agents-docs-theme";
+const root = document.documentElement;
+const prefersDark = window.matchMedia("(prefers-color-scheme: dark)");
+const mermaidApi = window.mermaid;
+
+function currentTheme() {
+  return root.dataset.theme === "dark" ? "dark" : "light";
+}
+
+function updateToggleLabels() {
+  const label = currentTheme() === "dark" ? "Dark" : "Light";
+  for (const element of document.querySelectorAll("[data-theme-label]")) {
+    element.textContent = label;
+  }
+}
+
+function setTheme(theme, persist = true) {
+  root.dataset.theme = theme;
+  if (persist) {
+    localStorage.setItem(storageKey, theme);
+  }
+  updateToggleLabels();
+}
+
+function prepareMermaid() {
+  for (const block of document.querySelectorAll("code.language-mermaid, code.mermaid")) {
+    if (block.closest(".mermaid")) {
+      continue;
+    }
+    const wrapper = document.createElement("div");
+    wrapper.className = "mermaid";
+    wrapper.textContent = block.textContent;
+    const container = block.closest("pre");
+    if (container) {
+      container.replaceWith(wrapper);
+    } else {
+      block.replaceWith(wrapper);
+    }
+  }
+
+  for (const diagram of document.querySelectorAll("div.mermaid, section.mermaid")) {
+    if (!diagram.dataset.source) {
+      diagram.dataset.source = diagram.textContent.trim();
+    }
+  }
+}
+
+async function renderMermaid() {
+  if (!mermaidApi) {
+    return;
+  }
+  const theme = currentTheme() === "dark" ? "dark" : "base";
+  mermaidApi.initialize({
+    startOnLoad: false,
+    securityLevel: "strict",
+    theme,
+    themeVariables: currentTheme() === "dark"
+      ? {
+          background: "#111824",
+          primaryColor: "#16202d",
+          primaryTextColor: "#eef3f8",
+          primaryBorderColor: "#3d566e",
+          lineColor: "#5cc4e0",
+          secondaryColor: "#11303c",
+          tertiaryColor: "#0a0e13",
+          fontFamily: "IBM Plex Mono, monospace"
+        }
+      : {
+          background: "#ffffff",
+          primaryColor: "#ecebe4",
+          primaryTextColor: "#101114",
+          primaryBorderColor: "#9aa6b2",
+          lineColor: "#1f6f88",
+          secondaryColor: "#ddebef",
+          tertiaryColor: "#f5f4ef",
+          fontFamily: "IBM Plex Mono, monospace"
+        }
+  });
+
+  const diagrams = Array.from(document.querySelectorAll(".mermaid")).filter((diagram) => diagram.dataset.source);
+  diagrams.forEach((diagram, index) => {
+    diagram.id = diagram.id || `mermaid-${index}`;
+    diagram.removeAttribute("data-processed");
+    diagram.textContent = diagram.dataset.source;
+  });
+
+  if (diagrams.length) {
+    try {
+      await mermaidApi.run({ nodes: diagrams });
+    } catch (error) {
+      console.error("Mermaid render failed", error);
+      for (const diagram of diagrams) {
+        diagram.textContent = diagram.dataset.source;
+        diagram.classList.add("mermaid--error");
+      }
+    }
+  }
+}
+
+function setupNavDrawer() {
+  const toggle = document.querySelector("[data-nav-toggle]");
+  const rail = document.getElementById("site-rail");
+  const backdrop = document.querySelector("[data-nav-backdrop]");
+  if (!toggle || !rail || !backdrop) {
+    return;
+  }
+  const setOpen = (open) => {
+    toggle.setAttribute("aria-expanded", String(open));
+    rail.classList.toggle("open", open);
+    backdrop.hidden = !open;
+    document.body.classList.toggle("nav-open", open);
+  };
+  toggle.addEventListener("click", () => setOpen(toggle.getAttribute("aria-expanded") !== "true"));
+  backdrop.addEventListener("click", () => setOpen(false));
+  window.matchMedia("(min-width: 861px)").addEventListener("change", () => setOpen(false));
+}
+
+prepareMermaid();
+updateToggleLabels();
+setupNavDrawer();
+
+for (const button of document.querySelectorAll("[data-theme-toggle]")) {
+  button.addEventListener("click", async () => {
+    const next = currentTheme() === "dark" ? "light" : "dark";
+    setTheme(next);
+    await renderMermaid();
+  });
+}
+
+prefersDark.addEventListener("change", async (event) => {
+  if (localStorage.getItem(storageKey)) {
+    return;
+  }
+  root.dataset.theme = event.matches ? "dark" : "light";
+  updateToggleLabels();
+  await renderMermaid();
+});
+
+renderMermaid();

package/docs/configurable-workflow-routing.md

@@ -0,0 +1,174 @@
+---
+title: Configurable Workflow Routing
+---
+
+# Configurable Workflow Routing
+
+Configurable workflow routing is the design for choosing which provider or profile should handle each Flow Agents workflow slot. It belongs to the workflow and agent/provider-selection layer: it names who should plan, implement, review, or verify, while the workflow contracts still own state, gates, artifacts, and evidence.
+
+This page is a design target. Flow Agents does not yet load a routing config or change runtime behavior from these examples.
+
+## Compatibility
+
+No config means current behavior. If a repo or user has no routing config, the active harness, current agent profile, skills, workflow contracts, and sidecar rules behave exactly as they do today.
+
+The first implementation slices should preserve that rule. Routing config should be opt-in, inspectable, and easy to diagnose before it affects execution.
+
+## Start With One Provider
+
+The simple case is a single default provider. A user should not need to learn adapter internals, consensus backends, or advanced lane policy to say "use this provider for normal Flow Agents work."
+
+Future config may look like this:
+
+```yaml
+providers:
+  codex:
+    cli: codex
+
+profiles:
+  default:
+    default: codex
+```
+
+In this shape, every workflow slot resolves to `codex` unless a later slot override says otherwise. Planning, implementation, review, and verification still follow the same contracts from the Workflow Usage Guide and Shared Workflow Contracts:
+https://github.com/kontourai/flow-agents/blob/main/docs/workflow-usage-guide.md
+https://github.com/kontourai/flow-agents/blob/main/docs/workflow-shared-contracts.md
+
+## Slots
+
+Slots are the workflow moments where provider choice matters. They use Flow Agents workflow vocabulary, not tool-specific command names.
+
+| Slot | Meaning | Typical workflow owner |
+| --- | --- | --- |
+| `plan` | Shape an accepted work item into an implementation plan with acceptance criteria and file ownership. | `plan-work` |
+| `implement` | Make source changes from the approved plan and record progress. | `execute-plan` |
+| `review` | Critique the result for quality, security, correctness, or consensus findings. | critique, evidence, or review agents |
+| `verify` | Run checks, map evidence to acceptance criteria, and report `PASS`, `FAIL`, or `NOT_VERIFIED`. | `verify-work` |
+
+Slot overrides let a profile keep one default provider while choosing stronger or cheaper options for specific phases:
+
+```yaml
+providers:
+  codex:
+    cli: codex
+
+  claude-opus:
+    cli: claude
+    model: opus
+
+profiles:
+  default:
+    default: codex
+    slots:
+      plan: claude-opus
+      implement: codex
+      review: claude-opus
+      verify: codex
+```
+
+This says: use the default provider for ordinary work, ask `claude-opus` to plan and review, and keep implementation and verification on `codex`.
+
+## Consensus Review
+
+`consensus` is a Flow Agents review concept. It means more than one reviewer perspective is used for a read-only critique, and the result is normalized into Flow Agents review, critique, or evidence artifacts.
+
+Users should be able to request consensus without knowing which backend produced it:
+
+```yaml
+providers:
+  codex:
+    cli: codex
+
+  claude-opus:
+    cli: claude
+    model: opus
+
+  consensus-review:
+    mode: consensus
+    reviewers:
+      - claude-opus
+      - codex
+
+profiles:
+  default:
+    default: codex
+    slots:
+      plan: claude-opus
+      implement: codex
+      review: consensus-review
+      verify: codex
+```
+
+A future backend may use native subagents, separate CLI profiles, or optional MCO infrastructure to run the reviewers. That backend is not the first-class API. The user-facing promise is that consensus remains read-only review behavior and produces findings that Flow Agents can map into its normal artifact contracts.
+
+Consensus review is not implementation routing. It should not write production files, bypass verification, or replace evidence gates.
+
+## Advanced Lanes
+
+Lanes are deferred guarded overrides for bounded work. They are not a route named after task size, and this design does not define or enable runtime lane behavior yet.
+
+A lane should eventually answer questions like:
+
+- What kinds of work are allowed in this lane?
+- Which files or directories are in scope?
+- Which provider or profile may implement it?
+- Which guardrails, review, and verification must pass before the work is accepted?
+- What happens when the work exceeds the lane boundary?
+
+Future config might express a guarded lane like this:
+
+```yaml
+lanes:
+  docs_only:
+    description: Documentation changes with no runtime code edits.
+    allow_paths:
+      - docs/**
+    deny_paths:
+      - skills/**
+      - agents/**
+      - schemas/**
+      - scripts/**
+      - dist/**
+    slots:
+      implement: codex
+      review: consensus-review
+      verify: codex
+```
+
+This example documents intent only. Guarded lanes need schema validation, conflict checks, artifact recording, and enforcement before they can safely affect execution.
+
+## Layer Alignment
+
+Routing should stay aligned with Operating Layers:
+https://github.com/kontourai/flow-agents/blob/main/docs/operating-layers.md
+
+- Providers and profiles describe agent/provider selection.
+- Slots connect provider selection to workflow phases.
+- Workflows still own durable state, acceptance criteria, handoffs, and phase transitions.
+- Evidence still owns proof, findings, validation output, and release confidence.
+- Powers may expose optional tools or backend infrastructure, but they do not define Flow Agents workflow meaning.
+
+That split keeps Flow Agents portable across Codex, Claude Code, Kiro, OpenCode, and future runtimes.
+
+## Non-Goals For This Slice
+
+This design slice does not add:
+
+- runtime config loading
+- provider execution
+- schema validation
+- MCO integration
+- consensus result normalization
+- guarded lane enforcement
+- generated bundle changes
+
+Docs and examples here are vocabulary and rollout guidance for later implementation.
+
+## Follow-Up Slices
+
+1. Config schema and validation: define the config file shape, validate examples, and produce clear errors for unknown providers, slots, profiles, and lane policy.
+2. No-op routing resolution: load config and report which provider would handle each slot without changing execution.
+3. Consensus review backend: implement read-only consensus review behind a backend boundary and normalize findings into critique or evidence artifacts.
+4. Guarded lanes: design and enforce bounded policy overrides after guardrails, path scopes, artifact recording, and fallback behavior are explicit.
+
+Each slice should preserve no-config compatibility and report `NOT_VERIFIED` when a selected provider, backend, or guardrail cannot be inspected.

package/docs/context-map.md

@@ -0,0 +1,145 @@
+---
+title: Context Map
+---
+
+# Context Map
+
+Generated by `npm run context-map`. Regenerate after changing agents, skills, schemas, workflow contracts, or core commands.
+
+## How To Use This
+
+- Start here when a session is long, resumed, or context-constrained.
+- Load only the specific skill, contract, schema, or doc that matches the task.
+- Treat `.flow-agents` as runtime state and `dist/` as generated output.
+
+## Repository Shape
+
+| Path | Role | Purpose |
+| --- | --- | --- |
+| agent-cards | canonical copy | Install/discovery cards that point at canonical agents. |
+| agents | source | Canonical agent specs and routing prompts. |
+| context | canonical copy | Shared contracts, routing notes, templates, and reusable guidance. |
+| docs | canonical copy | Long-lived project documentation and GitHub Pages content. |
+| evals | canonical copy | Static, integration, install, and behavioral eval fixtures. |
+| kits | canonical copy | Project directory. |
+| packaging | canonical copy | Project directory. |
+| powers | canonical copy | Optional MCP/tool integration packs. |
+| prompts | canonical copy | Reusable prompt entry points. |
+| schemas | canonical copy | JSON Schema contracts for machine-readable workflow artifacts. |
+| scripts | canonical copy | Build, validation, hook, telemetry, workflow, and import/export utilities. |
+| skills | canonical copy | On-demand capability instructions and workflow primitives. |
+| dist | generated | Generated bundle exports. Do not edit by hand. |
+| .flow-agents | runtime | Cross-session workflow artifacts and sidecars. Not committed by default. |
+
+## Core Commands
+
+| Use | Command |
+| --- | --- |
+| Source tree | npm run validate:source |
+| Static suite | bash evals/run.sh static |
+| Integration suite | bash evals/run.sh integration |
+| Workflow artifacts | npm run workflow:validate-artifacts -- --require-sidecars --require-critique .flow-agents/<slug> |
+| Workflow sidecars | npm run workflow:sidecar -- --help |
+| Context map drift | npm run context-map:check |
+| Bundle build | npm run build:bundles |
+
+## Workflow Sidecars
+
+Machine-readable workflow state lives beside Markdown artifacts in `.flow-agents/<slug>/`.
+
+| Schema | Title | ID |
+| --- | --- | --- |
+| backlog-provider-settings.schema.json | Flow Agents Backlog Provider Settings | https://flow-agents.dev/schemas/backlog-provider-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 |
+| workflow-handoff.schema.json | Flow Agents Workflow Handoff | https://flow-agents.dev/schemas/workflow-handoff.schema.json |
+| workflow-learning.schema.json | Flow Agents Workflow Learning | https://flow-agents.dev/schemas/workflow-learning.schema.json |
+| workflow-release.schema.json | Flow Agents Workflow Release Readiness | https://flow-agents.dev/schemas/workflow-release.schema.json |
+| workflow-state.schema.json | Flow Agents Workflow State | https://flow-agents.dev/schemas/workflow-state.schema.json |
+
+Primary tools: `npm run workflow:sidecar`, `npm run workflow:validate-artifacts`, `scripts/hooks/stop-goal-fit.js`, and `scripts/hooks/workflow-steering.js`.
+
+## Workflow Skills
+
+| 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. |
+
+## Support Skills
+
+| Skill | Source | When To Load |
+| --- | --- | --- |
+| 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. |
+| 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. |
+| 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. |
+| search-first | skills/search-first/SKILL.md | Research-before-coding workflow. Search for existing tools, libraries, and patterns before writing custom code. |
+
+## Agents
+
+| Agent | Model | Tools | Role |
+| --- | --- | --- | --- |
+| dev | claude-opus-4.6-1m | 1 | Development agent for coding tasks. Writes, modifies, and validates code following existing patterns. Delegates to specialists for domain-specific research when available. |
+| tool-code-reviewer | claude-sonnet-4.6-1m | 8 | Delegate to me for code quality review. Analyzes readability, maintainability, patterns, DRY compliance, and produces structured review with severity levels. Separate from verification (build/test/lint). |
+| tool-dependencies-updater | agi-nova-beta-1m | 8 | Delegate to me for updating your project dependencies - checks latest versions, identifies outdated packages, and finds security advisories across npm, PyPI, Cargo, Maven/Gradle, Go, NuGet, Ruby, PHP, Swift, Dart, Docker, Helm, Terraform... |
+| tool-explore-config | kimi-k2.5 | 6 | Delegate to me for project configuration inspection - finds and summarizes configuration files and environment variables within a project |
+| tool-explore-deps | kimi-k2.5 | 6 | Delegate to me for Dependency analysis - parses package manifests to identify tech stack and dependencies |
+| tool-explore-entry | kimi-k2.5 | 6 | Delegate to me to find the Entry point of a project - locates main files, CLI commands, API routes, and exports |
+| tool-explore-patterns | kimi-k2.5 | 6 | Delegate to me for Pattern detection - identifies architectural patterns, frameworks, and coding conventions |
+| tool-explore-structure | kimi-k2.5 | 6 | Delegate to me to scout out the project structure - maps directory layout and identifies key folders in a codebase |
+| tool-explore-tests | kimi-k2.5 | 6 | Delegate to me to find and understand testing strategies - locates test files and understands testing strategy |
+| tool-planner | claude-sonnet-4.6-1m | 7 | Delegate to me for codebase analysis and execution planning. Explores code, identifies patterns and dependencies, and writes plan/sidecar artifacts under .flow-agents. No production file modifications. |
+| tool-playwright | claude-sonnet-4.6-1m | 25 | Delegate to me for browser automation, testing, and debugging - loading real pages, testing navigation, checking accessibility via structured snapshots, evaluating scripts, and visual verification. Anything that would otherwise require a... |
+| tool-security-reviewer | claude-sonnet-4.6-1m | 7 | Delegate to me for security analysis. Checks OWASP Top 10, secrets detection, input validation, injection vulnerabilities, auth/authz, and rate limiting. Read-only analysis with shell for scanning tools. |
+| tool-verifier | claude-sonnet-4.6-1m | 8 | Delegate to me for implementation verification. Read-only + shell for source code; writes review/evidence artifacts under .flow-agents. Verifies acceptance criteria and produces PASS/FAIL/NOT_VERIFIED verdicts with evidence. No productio... |
+| tool-worker | claude-sonnet-4.6-1m | 1 | Delegate to me for writing and developing source code for a project. Works best when a detailed plan can be provided. NO access to web tools. Can be used in parallel for any coding tasks that require trusted access to the write and shell... |
+
+## Optional Powers
+
+| Power | Source |
+| --- | --- |
+| dependency-checker | powers/dependency-checker/POWER.md |
+| playwright | powers/playwright/POWER.md |
+
+## Packs
+
+Pack composition is defined in `packaging/packs.json`. The current builder exports pack metadata in bundle catalogs, and generated install scripts support opt-in `FLOW_AGENTS_PACKS` filtering while leaving all packs installed by default.
+
+| 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. |
+
+## Current Workflow State
+
+Runtime workflow state is excluded from the committed map.
+Regenerate locally with `npm run context-map -- --include-runtime` to include recent `.flow-agents` state.
+
+## Context Loading Rules
+
+- For delivery work, load `deliver`, then the specific primitive skill for the current phase.
+- For planning, verification, release, learning, or artifact validation, load `context/contracts/artifact-contract.md` plus the phase contract.
+- For unknown external APIs or libraries, use `search-first` before implementation.
+- For large or noisy sessions, prefer sidecars and this map over rereading broad docs.
+- For generated exports, edit source files and rebuild instead of editing `dist/`.

package/docs/developer-architecture.md

@@ -0,0 +1,145 @@
+---
+title: Developer Architecture
+---
+
+# Developer Architecture
+
+This guide is the local starting point for Flow Agents maintainers who need to understand how this repository coordinates with Flow, Surface, Veritas, and Builder Kit. It describes the architecture from the Flow Agents side only; product-specific runtime details remain in their owning products.
+
+## Orientation
+
+Flow Agents is the agent-facing operating layer. It turns a user's intent into workflow skills, local artifacts, sidecars, checks, and handoffs that a human or another agent can inspect later.
+
+**Current state:** Flow Agents owns the portable agent bundle, skills, contracts, local workflow artifacts, runtime-specific exports, provider wiring, and validation scripts in this repository.
+
+**Future direction:** Flow, Surface, Veritas, Builder Kit, and other Kontour products should continue converging on shared resource shapes and gate vocabulary without making this repository the owner of every product's runtime semantics.
+
+Use these local references when you need more detail:
+
+- [Context glossary](../CONTEXT.md) defines Flow Agents vocabulary.
+- [Repository Structure](repository-structure.md) is the canonical map for source, generated output, runtime state, packaging, eval, and cleanup boundaries.
+- [ADR 0003](adr/0003-flow-agents-coordinates-kits-and-adapters.md) records the kit and adapter boundary.
+- [ADR 0005](adr/0005-kubernetes-inspired-resource-contracts.md) records the Kontour Resource Contract direction.
+- [Kontour Resource Contract](kontour-resource-contract.md) documents the shared durable record shape.
+- [Flow Kit Repository Contract](flow-kit-repository-contract.md) documents local kit validation and activation boundaries.
+- [Veritas Integration Boundary](veritas-integration.md) documents optional governance evidence.
+
+## Coordination Map
+
+```mermaid
+flowchart LR
+  User[User intent]
+  Runtime[Agent runtime<br/>Codex, Claude Code, Kiro, CI]
+  Skills[Flow Agents skills]
+  Sidecars[Workflow artifacts<br/>and sidecars]
+  RuntimeAdapters[Runtime adapters<br/>and export]
+  ProviderAdapters[Provider adapters<br/>GitHub, local files, future providers]
+  Flow[Flow<br/>workflow semantics]
+  Builder[Builder Kit<br/>build workflows]
+  Veritas[Veritas<br/>governance evidence]
+  Surface[Surface<br/>portable trust state]
+
+  User --> Runtime --> Skills --> Sidecars
+  Skills --> RuntimeAdapters
+  Skills --> ProviderAdapters
+  RuntimeAdapters --> Runtime
+  Sidecars --> ProviderAdapters
+  Skills -. delegates workflow semantics .-> Flow
+  Skills -. activates Flow Kit assets .-> Builder
+  Skills -. records optional evidence .-> Veritas
+  Skills -. references trust claims .-> Surface
+  Veritas -. may produce .-> Surface
+  Builder -. uses Flow definitions .-> Flow
+```
+
+**Current state:** Flow Agents coordinates local agent workflows with Markdown session artifacts, JSON sidecars, scripts, evals, and local docs. It validates Flow Kit repository shape and activates supported local Flow Definition assets for the implemented `codex-local` adapter.
+
+**Future direction:** Flow should own authoritative workflow semantics, route decisions, gate enforcement, and Flow Definition validation. Flow Agents should stay the projection layer that makes those workflows usable inside agent runtimes and provider-backed workspaces.
+
+## Ownership Boundaries
+
+| Product | Owns | Flow Agents boundary |
+| --- | --- | --- |
+| Flow Agents | Agent-facing workflow bundles, skills, sidecars, artifact contracts, evals, runtime export, provider wiring, and local-first docs. | Does not become the core workflow engine for all Kontour products and should not copy product-native rule models into this repo. |
+| Flow | Generic workflow semantics, Flow Definitions, gate transitions, attempts, route-back behavior, Flow Runs, and Flow Reports. | Flow Agents may consume or project Flow concepts, but Flow owns enforcement semantics once the Flow surface is available. |
+| Builder Kit | The first Kontour-authored Flow Kit for build work: shaping, pickup probes, planning, execution, review, verification, publication, release readiness, and learning workflows. | Flow Agents validates, installs, activates, and routes Builder Kit assets; it does not make every Builder Kit specialization a core Flow Agents concept. |
+| Veritas | Repo-local standards, authority settings, policy/rule checks, and native governance reports. | Flow Agents records compact Veritas evidence references when configured; Veritas is optional and not a mandatory dependency for every workflow. |
+| Surface | Portable trust state, claims, TrustReports, Trust Snapshots, and user-facing trust surfaces. | Flow Agents can reference Surface-shaped claims for gates, but Surface owns claim models and trust presentation. |
+
+**Current state:** Builder Kit is the first proof point for extracting out-of-the-box behavior into normal Flow Kits. Veritas integration is documented as optional and adapter-driven. Surface references appear as a trust-state boundary in local Veritas and Builder Kit evidence docs.
+
+**Future direction:** Flow Agents should support more runtime adapters, provider adapters, and Flow Kits without forcing all users to install Builder Kit, Veritas, Surface, or a specific hosted provider.
+
+## Artifact And Evidence Flow
+
+```mermaid
+flowchart TB
+  Idea[Idea or request]
+  Backlog[Backlog / Work Item]
+  Probe[Alignment / Pickup Probe]
+  Plan[Run Plan or Execution Plan]
+  Execute[Execution]
+  Review[Review]
+  Verify[Verification]
+  Evidence[Evidence Gate]
+  Release[Release Gate]
+  Learn[Learning]
+
+  Artifacts[(Markdown artifacts)]
+  Sidecars[(JSON sidecars)]
+  Providers[(Provider records)]
+  Governance[(Optional governance evidence)]
+  Trust[(Optional Surface trust claim)]
+
+  Idea --> Backlog --> Probe --> Plan --> Execute --> Review --> Verify --> Evidence --> Release --> Learn
+  Plan --> Artifacts
+  Execute --> Artifacts
+  Review --> Sidecars
+  Verify --> Sidecars
+  Evidence --> Sidecars
+  Release --> Providers
+  Evidence --> Governance
+  Governance --> Trust
+  Trust --> Evidence
+  Review -->|finding| Execute
+  Verify -->|gap| Execute
+  Evidence -->|missing evidence| Plan
+```
+
+**Current state:** The durable handoff surface is a pair of human-readable Markdown artifacts and machine-readable JSON sidecars under `.flow-agents/<slug>/`. Verification, critique, release, and learning records are explicit artifacts rather than hidden chat memory.
+
+**Future direction:** Durable workflow state should converge toward Kontour Resource Contracts with versioned identity, desired state, observed status, and condition summaries. That convergence should preserve local files and provider-backed records as first-class surfaces.
+
+## Local Workflow Roles
+
+Flow Agents workflows separate selection, planning, execution, critique, verification, evidence, release, and learning so each stage leaves inspectable state.
+
+**Current state:**
+
+- `pull-work` selects work, checks WIP and dependency context, and records the pickup decision.
+- `plan-work` produces an execution plan with acceptance criteria, scope, risks, and verification expectations.
+- `execute-plan` implements the approved plan and records modified files.
+- `review-work` and `verify-work` produce report-only critique and evidence.
+- `evidence-gate`, `release-readiness`, and `learning-review` decide whether the work is trustworthy, acceptable, and worth feeding back into the system.
+
+**Future direction:** Flow-owned runs and gates should be able to supply the same structure to local agents, CI agents, and hosted control planes without depending on a particular chat runtime.
+
+## Resource Contract Alignment
+
+Kontour Resource Contracts provide the shared shape for durable records that cross product or adapter boundaries.
+
+**Current state:** Flow Agents already uses local workflow artifacts and sidecars as the operational handoff surface. New shared contracts should prefer the Kontour Resource Contract shape unless a product records a specific exception.
+
+**Future direction:** Active Workflow Runs, Selected Scope, Gate status, provider evidence, Surface claims, and Veritas report pointers should become easier to compare because they use compatible identity, metadata, desired intent, observed status, and condition-style summaries.
+
+## Reading Order For Contributors
+
+Start here, then follow the local docs in this order:
+
+1. [Workflow Usage Guide](workflow-usage-guide.md) for the user-facing delivery path.
+2. [Repository Structure](repository-structure.md) for where changes belong and what is generated or runtime-only.
+3. [Skills Map](skills-map.md) for workflow phase composition.
+4. [Workflow Artifact Lifecycle](workflow-artifact-lifecycle.md) for what stays local, what gets promoted, and what must not be merged.
+5. [Flow Kit Repository Contract](flow-kit-repository-contract.md) for kit repository validation and activation behavior.
+6. [Veritas Integration Boundary](veritas-integration.md) for optional governance evidence.
+7. [Developer Reference](context-map.md) for generated repository structure, commands, agents, skills, scripts, and contracts.

package/docs/developer-hook-setup.md

@@ -0,0 +1,61 @@
+---
+title: Developer Git Hook Setup
+---
+
+# Developer Git Hook Setup
+
+Flow Agents has a repo-owned Git pre-push lane for contributors who want local checks before pushing this repository.
+
+Enable it per clone:
+
+```bash
+npm run setup:repo-hooks
+```
+
+That command is idempotent and only writes repo-local Git config:
+
+```bash
+git config --local core.hooksPath .githooks
+```
+
+Verify the setting:
+
+```bash
+git config --local --get core.hooksPath
+```
+
+The expected value is `.githooks`.
+
+## Pre-Push Lane
+
+The tracked `.githooks/pre-push` hook runs bounded local checks:
+
+```bash
+npm run validate:repo-hooks --silent
+npm run validate:source --silent
+```
+
+These checks do not perform network access. They validate the repo hook setup and the source tree from the repository root. Use normal Git bypass mechanics, such as `git push --no-verify`, only when you have a reason to skip local developer checks.
+
+## Product Boundary
+
+This Git hook lane is developer workstation safety tooling for the Flow Agents repository. It is not a Flow Agents runtime hook and does not participate in runtime adapter activation, hook influence tiers, Flow Definition gate semantics, trusted producer config, or exported agent hook configuration.
+
+Runtime hooks remain under `scripts/hooks/` and are evaluated through the runtime hook docs and hook-influence checks. The repo Git hook only runs local package checks before a push; it must not change runtime hook behavior.
+
+## Runtime Hook Boundary
+
+Runtime-specific hook configuration is generated or installed output:
+
+- `dist/codex/.codex/hooks.json` and related files are generated bundle output.
+- A repo-local or home-local `.codex/` directory is installed runtime state and is ignored by Git.
+- `.claude/` is installed Claude Code runtime state and is ignored by Git.
+- Canonical hook behavior belongs in `scripts/hooks/`, `context/`, packaging metadata, installer scripts, and the TypeScript bundle builder.
+
+If local runtime hooks drift, regenerate the bundles or reinstall the runtime config instead of patching `.codex/` or `.claude/` as source. The stale local `.codex/hooks.json` incident followed exactly that failure mode: an installed runtime file still pointed at Claude-style hook behavior after the canonical Codex hook export had changed. Durable fixes must update the canonical builder, installer, hook script, or docs source, then verify with:
+
+```bash
+npm run build:bundles --
+npm run validate:repo-hooks --
+npm run validate:hook-influence --
+```