@kontourai/flow-agents 0.1.1

package/docs/fixture-ownership.md

@@ -0,0 +1,44 @@
+---
+title: Fixture Ownership
+---
+
+# Fixture Ownership
+
+`evals/fixtures/` is canonical eval source, not generic sample data. Keep fixture
+groups only when an owning eval or validator names the behavior they protect.
+When adding, moving, or deleting a fixture directory, update this inventory and
+run `npm run validate:source --` and `npm run fixture:retirement-audit --`.
+
+## Ownership Inventory
+
+| Fixture directory | Classification | Owners | Cleanup rule |
+| --- | --- | --- | --- |
+| `evals/fixtures/backlog-provider-settings` | settings precedence fixtures | `evals/integration/test_effective_backlog_settings.sh` | Keep while backlog provider settings resolution supports global defaults and project overrides. |
+| `evals/fixtures/builder-kit-workflow-state` | Builder Kit workflow-state fixtures | `evals/static/test_workflow_skills.sh` | Keep while Builder Kit state contract and resume behavior are documented in workflow skill contracts. |
+| `evals/fixtures/console-learning-projection` | console learning projection fixtures | `evals/integration/test_console_learning_projection.sh` | Keep while learning projection supports correction and open-route examples. |
+| `evals/fixtures/flow-kit-repository` | Flow Kit repository contract fixtures | `evals/integration/test_flow_kit_repository.sh`, `evals/integration/test_local_flow_kit_install.sh`, `evals/integration/test_runtime_adapter_activation.sh`, `evals/static/test_workflow_skills.sh` | Keep valid and invalid cases paired with the Flow Kit repository contract. |
+| `evals/fixtures/hook-influence` | hook influence behavioral cases | `evals/integration/test_hook_influence_cases.sh`, `evals/static/test_workflow_skills.sh`, `scripts/validate-hook-influence-cases.js` | Keep while hook influence cases define agent guidance behavior. |
+| `evals/fixtures/pull-work-provider` | work item provider normalization fixtures | `evals/integration/test_pull_work_provider.sh` | Keep while provider normalization preserves blockers, artifact refs, board membership, and freshness metadata. |
+| `evals/fixtures/pull-work-wip-shepherding` | WIP shepherding state fixtures | `evals/static/test_workflow_skills.sh` | Keep while pull-work documents personal versus global WIP behavior. |
+| `evals/fixtures/surface-trust` | Surface trust evidence fixtures | `evals/integration/test_workflow_sidecar_writer.sh` | Keep while sidecar writer maps Surface trust evidence into workflow records. |
+| `evals/fixtures/usage-feedback` | usage feedback import/outcome fixtures | `evals/integration/test_usage_feedback_import.sh`, `evals/integration/test_usage_feedback_outcomes.sh`, `evals/integration/test_usage_feedback_report.sh` | Keep while usage feedback import, outcome, and report flows accept JSONL fixture input. |
+| `evals/fixtures/veritas-governance-adapter` | Veritas governance adapter fixtures | `evals/integration/test_veritas_governance_adapter.sh` | Keep while the Veritas adapter supports pass, unconfigured, and secret-failure governance paths. |
+
+## Cleanup Policy
+
+Do not delete a fixture group just because a filename has no obvious direct
+reference. Many fixture directories are consumed as directories by integration
+tests. A fixture deletion is safe only when:
+
+1. The owning eval or validator no longer needs the behavior.
+2. This inventory is updated in the same change.
+3. `npm run validate:source --` and the owning eval pass.
+4. Any contract or docs that described the fixture behavior are updated.
+
+Generated eval output belongs under ignored result directories, not under
+`evals/fixtures/`.
+
+`npm run fixture:retirement-audit --` is a read-only retirement pass. It reports
+fixture groups as kept when they have documented owners and live eval/script
+references. A nonzero retire-candidate count is not permission to delete by
+itself; it is a prompt to update or remove the owning eval and fixture together.

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

@@ -0,0 +1,180 @@
+---
+title: Flow Kit Repository Contract
+---
+
+# Flow Kit Repository Contract
+
+A Flow Kit repository is a local folder with a root `kit.json`. Flow Agents validates the repository shape, declared paths, declared assets, fixture behavior, and diagnostics. Flow validates Flow Definition semantics.
+
+Use this command before adding a kit to a catalog or sharing it with another maintainer:
+
+```bash
+npm run validate:source -- --kit path/to/local-kit
+```
+
+The full source-tree command validates the built-in Kit Catalog and Builder Kit through the same repository contract:
+
+```bash
+npm run validate:source --
+```
+
+## Local Install
+
+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
+```
+
+`--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.
+
+Install always runs the same repository validation used by `npm run validate:source -- --kit` before it creates or updates local install state. A validation failure exits nonzero and leaves the destination registry and copied kits unchanged.
+
+Local installs are runtime overlay state. The command writes registry metadata to:
+
+```text
+<dest>/kits/local/installed-kits.json
+```
+
+and copies validated repositories under:
+
+```text
+<dest>/kits/local/repositories/<kit-id>/
+```
+
+It does not edit the source Kit Catalog at `kits/catalog.json`.
+
+Each registry entry records:
+
+- `id`: kit id from `kit.json`.
+- `source`: absolute local source path used for the install.
+- `hash`: `sha256:` content hash of the source repository.
+- `version`: optional manifest version when a future contract permits one.
+- `installed_at`: UTC ISO timestamp.
+- `installed_path`: copied kit path under the destination.
+- `state`: install state reported by status commands.
+
+Reinstalling the same kit id from the same source with the same content is idempotent and leaves the registry unchanged. Installing a different source with an existing kit id fails with a conflict unless `--update` is passed. `--update` replaces the copied kit and registry entry after the new source validates. `--force` re-copies an existing same-source install after validation.
+
+`list` and `status` are read-only. `list` prints one summary line per installed local kit. `status` prints JSON provenance and reports copied kit state as `installed` or `missing`.
+
+## Runtime Activation
+
+`activate` reads the built-in Kit Catalog and local install overlay, selects a runtime adapter, and writes generated runtime-local files into the destination workspace. When `--adapter` is omitted, Flow Agents selects the only implemented adapter:
+
+```text
+codex-local
+```
+
+Unknown adapter ids fail with JSON diagnostics that include the available adapters. No Claude, Kiro, framework, API, npm module extraction, or remote install adapters are implemented by this activation surface.
+
+The `codex-local` adapter supports only Flow Definition assets declared in `flows`. It activates the built-in Builder Kit Flow Definitions, including `builder.shape` and `builder.build`, plus Flow Definitions from locally installed kit copies under:
+
+```text
+<dest>/kits/local/repositories/<kit-id>/
+```
+
+Activation reuses the installed local kit registry at `<dest>/kits/local/installed-kits.json`; it does not duplicate installed kit state and does not edit `kits/catalog.json`.
+
+Generated files are written under:
+
+```text
+<dest>/.flow-agents/runtime/codex/
+```
+
+Flow Definition copies are placed under `flows/<kit-id>/<flow-id>.flow.json`, and activation writes an `activation.json` manifest in the same runtime-local area.
+
+The stable activation diagnostics include:
+
+- `selected_adapter`: selected adapter id, currently `codex-local`.
+- `supported_asset_classes`: asset classes the selected adapter activates, currently `["flows"]`.
+- `generated_runtime_files`: generated runtime-local files with asset class, path, kit id, asset id, and source path.
+- `skipped_assets`: unsupported declared assets with asset class, path, kit id, asset id when present, and reason.
+- `warnings`: recoverable catalog, registry, or asset discovery problems.
+- `errors`: blocking discovery or activation problems.
+
+Declared `skills`, `docs`, `adapters`, `evals`, and generic `assets` are diagnostic-only for this adapter. They are skipped with explicit `skipped_assets` entries; they are not copied, installed, invoked, or treated as active runtime behavior.
+
+## Root Manifest
+
+`kit.json` must be valid JSON at the repository root.
+
+```json
+{
+  "schema_version": "1.0",
+  "id": "example-kit",
+  "name": "Example Kit",
+  "product_name": "Example Kit",
+  "description": "A local kit used to validate the repository contract.",
+  "flows": [
+    {
+      "id": "example.review",
+      "path": "flows/review.flow.json",
+      "description": "Review a small change."
+    }
+  ],
+  "docs": [
+    {
+      "id": "example.readme",
+      "path": "docs/README.md"
+    }
+  ]
+}
+```
+
+Required fields:
+
+- `schema_version`: must be `"1.0"`.
+- `id`: stable kebab-case kit id, such as `builder` or `example-kit`.
+- `name`: non-empty display name.
+- `flows`: non-empty list of Flow Definition entries. Each entry must be an object with `id` and `path`.
+
+Optional fields:
+
+- `product_name`: non-empty display name when the product name differs from `name`.
+- `description`: non-empty summary.
+- `skills`, `docs`, `adapters`, `evals`, `assets`: lists of relative asset paths or objects with `id`, `path`, and optional `description`.
+
+## Path Rules
+
+All declared paths are local to the kit directory. A path must be relative, must not contain `..`, and must point at an existing file or folder. Absolute paths are rejected because a kit must be portable between worktrees and machines.
+
+Valid:
+
+```json
+{ "id": "example.review", "path": "flows/review.flow.json" }
+```
+
+Invalid:
+
+```json
+{ "id": "example.review", "path": "../flow/review.flow.json" }
+```
+
+Diagnostic:
+
+```text
+kit.json: flows[0].path must stay inside the kit directory; '..' path traversal is not allowed
+```
+
+## Flow Boundary
+
+Flow Agents checks that a declared Flow Definition path is present and delegates Flow Definition validation to Flow with `flow validate-definition <path> --json` or the local Flow CLI fallback when available. If the Flow validation surface is unavailable, the source validator keeps only the existing minimal shape fallback and verification must record that gap as `NOT_VERIFIED`.
+
+Flow Agents must not duplicate Flow gate semantics, trusted-producer rules, route-back behavior, or claim validation. Those belong to Flow.
+
+## Scope
+
+This contract and install surface are local repository validation, local runtime bookkeeping, and Codex-local Flow Definition activation only. Remote install is a non-goal: Flow Agents does not install remote kits, fetch git repositories, split npm packages, select adapter packages, invoke the full Builder Kit provider graph, or implement Claude, Kiro, framework, API, or provider adapters.
+
+## Common Failures
+
+- `kit.json: .schema_version must be "1.0"`: update the manifest schema version.
+- `kit.json: .id must be a stable kebab-case string`: use a lowercase id such as `review-kit`.
+- `kit.json: .flows must be a non-empty list`: declare at least one Flow Definition.
+- `kit.json: flows[0].path points at missing Flow Definition`: add the file or fix the relative path.
+- `kit.json: docs[0].path points at missing asset`: add the asset or remove the entry.

package/docs/index.md

@@ -0,0 +1,129 @@
+---
+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>
+
+<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>
+  </section>
+  <section>
+    <strong>Survive context loss</strong>
+    <span>Durable sidecar state under <code>.flow-agents/</code> records acceptance criteria, evidence, critique, and handoff, so any session resumes from recorded state instead of chat memory.</span>
+  </section>
+  <section>
+    <strong>Evidence over confidence</strong>
+    <span>Hooks catch stop-short behavior, and important work ends with tests, browser checks, CI results, review findings, or an explicit <code>NOT_VERIFIED</code> gap — never just a confident summary.</span>
+  </section>
+</div>
+
+## How it works
+
+```mermaid
+flowchart LR
+  Idea[Idea]
+  Backlog[Backlog]
+  Plan[Plan]
+  Build[Build]
+  Review[Review]
+  Verify[Verify]
+  Evidence[Evidence]
+  Release[Release readiness]
+  Learn[Learning]
+
+  Idea --> Backlog --> Plan --> Build --> Review --> Verify --> Evidence --> Release --> Learn
+  Review -->|finding| Build
+  Verify -->|gap| Build
+  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.
+
+## Quick Start
+
+```bash
+npx @kontourai/flow-agents init --dest /path/to/workspace
+```
+
+Until the first npm release lands, the same command works from a checkout: clone the repo, `npm install && npm run build`, then `node build/src/cli.js init --dest /path/to/workspace`.
+
+Then ask for the workflow you want, in plain language:
+
+```text
+Use deliver for this GitHub issue. Plan it, implement it, review it, verify it, and stop if evidence is missing.
+```
+
+For bugs:
+
+```text
+Use fix-bug. Reproduce the problem, diagnose root cause, implement the fix, and verify the regression path.
+```
+
+## Explore the docs
+
+<div class="doc-grid">
+  <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>
+  </a>
+  <a class="doc-card" href="agent-system-guidebook.html">
+    <strong>System Guidebook</strong>
+    <span>The plain-language map of how Flow Agents is assembled and how it should feel to use.</span>
+  </a>
+  <a class="doc-card" href="skills-map.html">
+    <strong>Workflow Map</strong>
+    <span>See the core skills, gates, artifacts, and route-back behavior.</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>
+  </a>
+  <a class="doc-card" href="developer-architecture.html">
+    <strong>Developer Architecture</strong>
+    <span>Flow Agents' coordination role, product boundaries, artifact flow, and cross-product vocabulary.</span>
+  </a>
+  <a class="doc-card" href="sandbox-policy.html">
+    <strong>Safer Execution</strong>
+    <span>Choose local, worktree, container, cloud, or privileged execution boundaries deliberately.</span>
+  </a>
+  <a class="doc-card" href="veritas-integration.html">
+    <strong>Governance Evidence</strong>
+    <span>Attach optional Veritas readiness reports without making governance tooling mandatory.</span>
+  </a>
+  <a class="doc-card" href="workflow-eval-strategy.html">
+    <strong>Eval Strategy</strong>
+    <span>How static, integration, behavioral, and artifact evals validate the bundle.</span>
+  </a>
+  <a class="doc-card" href="workflow-artifact-lifecycle.html">
+    <strong>Artifact Lifecycle</strong>
+    <span>Check in reviewable change work while promoting completed behavior into durable docs before merge.</span>
+  </a>
+  <a class="doc-card" href="work-item-adapters.html">
+    <strong>Provider Adapters</strong>
+    <span>Map provider-neutral work items, boards, published changes, checks, and evidence to GitHub-first adapters.</span>
+  </a>
+  <a class="doc-card" href="repository-structure.html">
+    <strong>Repository Structure</strong>
+    <span>The canonical source, generated output, runtime state, package, docs, eval, and cleanup boundaries.</span>
+  </a>
+  <a class="doc-card" href="kontour-resource-contract.html">
+    <strong>Resource Contracts</strong>
+    <span>The shared resource shape for durable workflow state and sidecars.</span>
+  </a>
+  <a class="doc-card" href="context-map.html">
+    <strong>Developer Reference</strong>
+    <span>The generated repo map: commands, agents, skills, scripts, and contracts.</span>
+  </a>
+</div>
+
+## The Kontour family
+
+Kontour AI shows the work behind AI. <a href="https://kontourai.github.io/flow/">Flow</a> proves why a process was allowed to advance. Veritas makes AI-authored code changes inspectable. Flow Agents packages those foundations into the agent tools you already use — so trustworthy autonomy doesn't require a perfect prompt, perfect memory, or a new runtime.
+
+## Why it matters
+
+Long-running agent work fails when the model loses context, skips verification, or calls partial work done. Flow Agents makes the process explicit without making the user write a perfect prompt every time. The agent gets a workflow; the developer gets artifacts they can inspect.