@kontourai/flow-agents 0.1.1

package/.githooks/pre-push

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(git rev-parse --show-toplevel)"
+cd "$ROOT_DIR"
+
+echo "flow-agents pre-push: validating repo Git hook setup"
+npm run validate:repo-hooks --silent
+
+echo "flow-agents pre-push: validating source tree"
+npm run validate:source --silent

package/.github/workflows/ci.yml

@@ -0,0 +1,210 @@
+name: Flow Agents CI
+
+on:
+  pull_request:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: flow-agents-ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  source-and-static:
+    name: Source and Static
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      FLOW_AGENTS_CI_LANE: source-and-static
+      FLOW_AGENTS_CI_RESULTS_DIR: evals/results/ci-baseline/source-and-static
+      FLOW_CLI_ROOT: ${{ github.workspace }}/.flow-cli/node_modules/@kontourai/flow
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "22"
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Install Flow CLI for definition validation
+        run: |
+          mkdir -p .flow-cli
+          cd .flow-cli
+          printf '{"name":"flow-cli-host","private":true}\n' > package.json
+          npm install --no-save @kontourai/flow
+
+      - name: Install shell tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y jq ripgrep
+
+      - name: Initialize CI evidence
+        run: bash evals/ci/run-baseline.sh --init
+
+      - name: Content boundary
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check content-boundary
+
+      - name: Source tree validation
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check source-tree-validation
+
+      - name: Context map drift
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check context-map-drift
+
+      - name: Static eval suite
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check static-eval-suite
+
+      - name: Finalize CI evidence
+        if: always()
+        run: bash evals/ci/run-baseline.sh --finalize
+
+      - name: Upload CI evidence artifacts
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: flow-agents-ci-source-and-static
+          path: evals/results/ci-baseline/source-and-static/
+          if-no-files-found: warn
+          retention-days: 14
+
+  workflow-contracts:
+    name: Workflow Contracts
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      FLOW_AGENTS_CI_LANE: workflow-contracts
+      FLOW_AGENTS_CI_RESULTS_DIR: evals/results/ci-baseline/workflow-contracts
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "22"
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Install shell tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y jq ripgrep
+
+      - name: Initialize CI evidence
+        run: bash evals/ci/run-baseline.sh --init
+
+      - name: Workflow artifact integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check workflow-artifact-integration
+
+      - name: Workflow artifact cleanup audit integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check workflow-artifact-cleanup-audit-integration
+
+      - name: Fixture retirement audit integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check fixture-retirement-audit-integration
+
+      - name: Publish-change helper integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check publish-change-helper-integration
+
+      - name: Workflow sidecar writer integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check workflow-sidecar-writer-integration
+
+      - name: Finalize CI evidence
+        if: always()
+        run: bash evals/ci/run-baseline.sh --finalize
+
+      - name: Upload CI evidence artifacts
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: flow-agents-ci-workflow-contracts
+          path: evals/results/ci-baseline/workflow-contracts/
+          if-no-files-found: warn
+          retention-days: 14
+
+  runtime-and-kit:
+    name: Runtime and Kit
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      FLOW_AGENTS_CI_LANE: runtime-and-kit
+      FLOW_AGENTS_CI_RESULTS_DIR: evals/results/ci-baseline/runtime-and-kit
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "22"
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Install shell tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y jq ripgrep
+
+      - name: Initialize CI evidence
+        run: bash evals/ci/run-baseline.sh --init
+
+      - name: Goal Fit hook integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check goal-fit-hook-integration
+
+      - name: Hook category behavior integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check hook-category-behavior-integration
+
+      - name: Workflow steering hook integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check workflow-steering-hook-integration
+
+      - name: Hook influence contract integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check hook-influence-contract-integration
+
+      - name: Flow Kit repository integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check flow-kit-repository-integration
+
+      - name: Runtime adapter activation integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check runtime-adapter-activation-integration
+
+      - name: Bundle install integration
+        continue-on-error: true
+        run: bash evals/ci/run-baseline.sh --check bundle-install-integration
+
+      - name: Finalize CI evidence
+        if: always()
+        run: bash evals/ci/run-baseline.sh --finalize
+
+      - name: Upload CI evidence artifacts
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: flow-agents-ci-runtime-and-kit
+          path: evals/results/ci-baseline/runtime-and-kit/
+          if-no-files-found: warn
+          retention-days: 14

package/.github/workflows/docs-pages.yml

@@ -0,0 +1,52 @@
+name: Publish Docs
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs-pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Configure Pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+        with:
+          enablement: true
+
+      - name: Build Jekyll site
+        uses: actions/jekyll-build-pages@44a6e6beabd48582f863aeeb6cb2151cc1716697 # v1.0.13
+        with:
+          source: ./docs
+          destination: ./_site
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: ./_site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

package/.github/workflows/publish-npm.yml

@@ -0,0 +1,104 @@
+name: Publish NPM
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "22"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci --no-fund --no-audit
+
+      - name: Install shell tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y jq ripgrep
+
+      - name: Validate source tree
+        run: npm run validate:source --
+
+      - name: Run static eval suite
+        run: bash evals/run.sh static
+
+      - name: Pack dry run
+        run: npm pack --dry-run
+
+  publish:
+    needs: verify
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: npm ci --no-fund --no-audit
+
+      - name: Install shell tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y jq ripgrep
+
+      - name: Build bundle
+        run: npm run build --silent
+
+      - name: Verify tag matches package version
+        run: |
+          PACKAGE_VERSION=$(node -p "JSON.parse(require('node:fs').readFileSync('package.json', 'utf8')).version")
+          if [ "v${PACKAGE_VERSION}" != "${GITHUB_REF_NAME}" ]; then
+            echo "Tag ${GITHUB_REF_NAME} does not match package.json version v${PACKAGE_VERSION}" >&2
+            exit 1
+          fi
+
+      - name: Verify tagged commit is on main
+        run: |
+          git fetch origin main
+          if ! git merge-base --is-ancestor "${GITHUB_SHA}" "FETCH_HEAD"; then
+            echo "Tagged commit ${GITHUB_SHA} is not reachable from the fetched origin/main tip" >&2
+            exit 1
+          fi
+
+      - name: Check published version
+        id: published
+        run: |
+          PACKAGE_NAME=$(node -p "JSON.parse(require('node:fs').readFileSync('package.json', 'utf8')).name")
+          PACKAGE_VERSION=$(node -p "JSON.parse(require('node:fs').readFileSync('package.json', 'utf8')).version")
+          if npm view "${PACKAGE_NAME}@${PACKAGE_VERSION}" version >/dev/null 2>&1; then
+            echo "published=true" >> "${GITHUB_OUTPUT}"
+            echo "${PACKAGE_NAME}@${PACKAGE_VERSION} is already published; skipping npm publish."
+          else
+            echo "published=false" >> "${GITHUB_OUTPUT}"
+          fi
+
+      - name: Publish public package
+        if: steps.published.outputs.published != 'true'
+        run: npm publish --access public

package/AGENTS.md

@@ -0,0 +1,26 @@
+# Universal Agent Bundle (Claude Code)
+
+This bundle was generated from the canonical source in this repo. Treat the repo root as the source of truth and regenerate the bundle instead of editing exported agent files by hand.
+
+## Shared Conventions
+
+- `skills/`, `context/`, `powers/`, `prompts/`, `scripts/`, and `evals/` were copied from the canonical source.
+- Cross-session task artifacts should live under `.flow-agents`.
+- Kiro-only hook wiring was stripped from exported non-Kiro agents to keep the package portable.
+
+## Exported Agents
+
+- `dev` — 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` — 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` — 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, and GitHub Actions
+- `tool-explore-config` — Delegate to me for project configuration inspection - finds and summarizes configuration files and environment variables within a project
+- `tool-explore-deps` — Delegate to me for Dependency analysis - parses package manifests to identify tech stack and dependencies
+- `tool-explore-entry` — Delegate to me to find the Entry point of a project - locates main files, CLI commands, API routes, and exports
+- `tool-explore-patterns` — Delegate to me for Pattern detection - identifies architectural patterns, frameworks, and coding conventions
+- `tool-explore-structure` — Delegate to me to scout out the project structure - maps directory layout and identifies key folders in a codebase
+- `tool-explore-tests` — Delegate to me to find and understand testing strategies - locates test files and understands testing strategy
+- `tool-planner` — 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` — 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 browser. Do NOT use for general web search or fetching content
+- `tool-security-reviewer` — 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` — 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 production file modifications.
+- `tool-worker` — 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 tools. WARNING: May spawn a `git worktree`

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+## 0.1.1
+
+### Documentation And Site
+
+- Rewrote the README and GitHub Pages home with a verified install path
+  (checkout-based; npm publishing is on the roadmap), the Kontour product-line
+  story, and cross-links to the Kontour Flow documentation.
+- Rebranded the docs site to the shared Kontour design tokens: Fraunces,
+  Hanken Grotesk, and IBM Plex Mono, the Flow teal accent, light/dark themes,
+  a version badge, OG/social meta tags, and a favicon.
+- Fixed mobile navigation: the rail is now an accessible slide-over drawer
+  instead of disappearing below 860px.
+- Added frontmatter to fourteen docs (including the workflow usage guide,
+  skills map, and all ADRs) so Jekyll renders them as pages instead of copying
+  raw Markdown, and enabled the github-pages default plugins locally for
+  build parity.
+- Merged the evidence reference migration note into `docs/migrations.md`,
+  merged the roadmap into `docs/north-star.md`, and retired
+  `docs/release-notes.md` in favor of this changelog.
+
+### Packaging And Cross-Product Validation
+
+- Made the package publishable: removed the `private` flag, added the license
+  and public `publishConfig`, a `prepack` validation lane, and a tag-triggered
+  `Publish NPM` workflow using npm trusted publishing, mirroring the Flow
+  release pipeline.
+- Fixed Flow CLI integration in source validation: `FLOW_CLI_ROOT` now resolves
+  the compiled `dist/cli.js` (with a `src/cli.js` fallback), and the
+  source-and-static CI lane installs `@kontourai/flow` so kit Flow Definitions
+  are validated by the real Flow CLI in CI.
+- Removed the broken `build-docs-preview` tool and its wrapper, bin, and script
+  entries; local docs preview is now documented in CONTRIBUTING.md using the
+  same Jekyll setup as the Pages workflow.
+
+### Repository Cleanup
+
+- Consolidated TypeScript tooling source under `src/tools/` and kept
+  `scripts/` as the public wrapper/runtime surface.
+- Documented repository structure, generated-output boundaries, runtime hook
+  boundaries, and safe cleanup rules.
+- Removed stale local runtime artifacts and corrected package metadata drift.
+
+### Codex Runtime Hooks
+
+- Reinstalled Codex into an isolated Flow Agents home and fixed generated
+  Codex hook commands to prefer `CODEX_HOME`.
+- Documented the stale repo-local `.codex/hooks.json` failure mode that caused
+  Codex `PostToolUse` to reject Claude-only `suppressOutput` output.
+
+### CI And Release Readiness
+
+- Enabled permanent TypeScript unused-code enforcement with `noUnusedLocals`
+  and `noUnusedParameters`.
+- Made the Node runtime policy explicit: package metadata requires Node `>=22`,
+  CI runs Node 22, and `@types/node` stays on the Node 22 major line until
+  runtime policy changes.
+- SHA-pinned GitHub Actions with version comments, including dereferencing the
+  annotated `actions/checkout@v6.0.3` tag to its commit SHA.
+- Split Flow Agents CI into independent source/static, workflow-contract, and
+  runtime/kit lanes with separate evidence artifacts.
+- Preserved fail-closed CI evidence finalization: failed, missing, duplicate,
+  or invalid check rows fail the corresponding CI lane.
+- Verified the npm lockfile with a clean audit and updated `promptfoo` to
+  `0.121.15`.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,25 @@
+# Code Of Conduct
+
+## Our Standard
+
+We want this project to be a professional, respectful place to collaborate.
+
+Examples of expected behavior:
+
+- assume good faith and stay specific about technical concerns
+- give actionable feedback instead of personal criticism
+- keep discussion focused on the work and the evidence
+- respect different experience levels and backgrounds
+
+Examples of unacceptable behavior:
+
+- harassment, intimidation, or discrimination
+- personal attacks or insulting language
+- deliberate disruption of review, issue, or discussion threads
+- publishing private information without permission
+
+## Enforcement
+
+Project maintainers may remove comments, close threads, or restrict participation when conduct makes collaboration unsafe or unproductive.
+
+Report conduct issues to `conduct@kontourai.com`.