@kontourai/flow-agents 0.1.1

package/install.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat >&2 <<'EOF'
+usage: bash install.sh /path/to/workspace [options]
+
+Options:
+  --telemetry-sink NAME   local-files, local-kontour-console,
+                          kontour-hosted-console, user-hosted-console,
+                          or legacy aliases. May be repeated.
+  --console-url URL       Persist Console telemetry base URL.
+  --console-endpoint URL  Persist full Console telemetry records endpoint URL.
+  --console-token-file PATH
+                          Read Console telemetry bearer token from a file.
+  --console-tenant ID     Persist Console tenant identifier.
+EOF
+}
+
+DEST=""
+CONSOLE_CONFIG_ARGS=()
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --telemetry-sink|--telemetry-sinks|--console-url|--console-endpoint|--console-endpoint-url|--console-token-file|--console-tenant|--console-tenant-id)
+      [[ $# -ge 2 ]] || { echo "install.sh: $1 requires a value" >&2; exit 2; }
+      CONSOLE_CONFIG_ARGS+=("$1" "$2")
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    -*)
+      echo "install.sh: unknown option: $1" >&2
+      usage
+      exit 2
+      ;;
+    *)
+      if [[ -n "$DEST" ]]; then
+        echo "install.sh: unexpected argument: $1" >&2
+        usage
+        exit 2
+      fi
+      DEST="$1"
+      shift
+      ;;
+  esac
+done
+[[ -n "$DEST" ]] || { usage; exit 2; }
+SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+mkdir -p "$DEST"
+rsync -a "$SRC"/ "$DEST"/
+if [[ -n "${FLOW_AGENTS_PACKS:-}" ]]; then
+  FILTER_SCRIPT="$DEST/scripts/filter-installed-packs.mjs"
+  if [[ ! -f "$FILTER_SCRIPT" ]]; then
+    FILTER_SCRIPT="$DEST/scripts/filter-installed-packs.js"
+  fi
+  node "$FILTER_SCRIPT" "$DEST" --packs "$FLOW_AGENTS_PACKS"
+fi
+if [[ ${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "${FLOW_AGENTS_TELEMETRY_SINK:-}" || -n "${FLOW_AGENTS_TELEMETRY_SINKS:-}" || -n "${FLOW_AGENTS_CONSOLE_URL:-}" || -n "${CONSOLE_TELEMETRY_URL:-}" || -n "${CONSOLE_URL:-}" || -n "${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-}" || -n "${CONSOLE_TELEMETRY_TOKEN_FILE:-}" ]]; then
+  bash "$DEST/scripts/telemetry/install-console-config.sh" "$DEST/scripts/telemetry/telemetry.conf" "${CONSOLE_CONFIG_ARGS[@]}"
+fi
+echo "Installed Flow Agents bundle into $DEST"

package/integrations/veritas/flow-agents.adapter.json

@@ -0,0 +1,138 @@
+{
+  "name": "flow-agents",
+  "kind": "repo-adapter",
+  "policy": {
+    "defaultFalsePositiveReview": "unknown",
+    "defaultPromotionCandidate": false,
+    "defaultOverrideOrBypass": false
+  },
+  "graph": {
+    "version": 1,
+    "defaultResolution": {
+      "phase": "Flow Agents north star",
+      "workstream": "Portable agent workflow reliability",
+      "matchedArtifacts": [
+        "docs/north-star-roadmap.md"
+      ]
+    },
+    "nonSliceableInvariants": [
+      "Portable bundle exports stay installable across Codex, Claude Code, and Kiro",
+      "Workflow contract changes include validation coverage",
+      "Hook and sidecar behavior stays evidence-backed"
+    ],
+    "resolverPrecedence": [
+      "active workflow sidecar under .flow-agents",
+      "north-star roadmap workstream",
+      "repo surface fallback"
+    ],
+    "nodes": [
+      {
+        "id": "flow-agents.workflow",
+        "kind": "governance-surface",
+        "label": "workflow contracts and sidecars",
+        "patterns": [
+          "context/contracts/",
+          "schemas/",
+          "src/cli/workflow-sidecar.ts",
+          "src/cli/validate-workflow-artifacts.ts"
+        ],
+        "boundary": "advisory",
+        "owners": [
+          "flow-agents-core"
+        ]
+      },
+      {
+        "id": "flow-agents.hooks",
+        "kind": "tooling-surface",
+        "label": "runtime hooks",
+        "patterns": [
+          "scripts/hooks/"
+        ],
+        "boundary": "advisory",
+        "owners": [
+          "flow-agents-runtime"
+        ]
+      },
+      {
+        "id": "flow-agents.docs",
+        "kind": "product-surface",
+        "label": "docs and guidebook",
+        "patterns": [
+          "docs/"
+        ],
+        "boundary": "advisory",
+        "owners": [
+          "flow-agents-docs"
+        ]
+      },
+      {
+        "id": "flow-agents.skills",
+        "kind": "product-surface",
+        "label": "skills and powers",
+        "patterns": [
+          "skills/",
+          "powers/"
+        ],
+        "boundary": "advisory",
+        "owners": [
+          "flow-agents-core"
+        ]
+      },
+      {
+        "id": "flow-agents.evals",
+        "kind": "verification-surface",
+        "label": "evals",
+        "patterns": [
+          "evals/"
+        ],
+        "boundary": "advisory",
+        "owners": [
+          "flow-agents-quality"
+        ]
+      },
+      {
+        "id": "flow-agents.packaging",
+        "kind": "delivery-surface",
+        "label": "bundle packaging",
+        "patterns": [
+          "packaging/",
+          "src/tools/build-universal-bundles.ts",
+          "src/tools/filter-installed-packs.ts"
+        ],
+        "boundary": "advisory",
+        "owners": [
+          "flow-agents-release"
+        ]
+      },
+      {
+        "id": "flow-agents.instructions",
+        "kind": "governance-surface",
+        "label": "agent instructions",
+        "patterns": [
+          "AGENTS.md",
+          "README.md"
+        ],
+        "boundary": "advisory",
+        "owners": [
+          "flow-agents-core"
+        ]
+      }
+    ]
+  },
+  "evidence": {
+    "artifactDir": ".veritas/evidence/flow-agents-readiness",
+    "reportTransport": "artifact",
+    "evidenceChecks": [
+      {
+        "id": "source-tree",
+        "command": "npm run validate:source",
+        "method": "validation",
+        "summary": "Validates Flow Agents canonical source tree invariants."
+      }
+    ],
+    "requiredEvidenceCheckIds": [
+      "source-tree"
+    ],
+    "uncoveredPathPolicy": "warn"
+  }
+}

package/integrations/veritas/flow-agents.authority-settings.json

@@ -0,0 +1,26 @@
+{
+  "version": 1,
+  "id": "flow-agents",
+  "name": "Flow Agents Authority Settings",
+  "description": "Conservative local authority settings for recording Veritas as optional Flow Agents evidence before any release.",
+  "defaults": {
+    "mode": "advisory",
+    "new_rule_stage": "recommend"
+  },
+  "review_preferences": {
+    "human_signoff_required_for_stage_promotion": true,
+    "reviewer_confidence_scale": [
+      "low",
+      "medium",
+      "high"
+    ],
+    "major_rewrite_definition": "A change counts as a major rewrite when the reviewer replaces the main workflow, contract, or hook structure instead of making local edits."
+  },
+  "promotion_preferences": {
+    "evidence_checks_required_before_block": [
+      "npm run validate:source"
+    ],
+    "warnings_block_in_ci": false,
+    "require_consistent_eval_before_promotion": true
+  }
+}

package/integrations/veritas/flow-agents.repo-standards.json

@@ -0,0 +1,82 @@
+{
+  "version": 1,
+  "name": "flow-agents-governance",
+  "description": "Local Veritas repo standards for Flow Agents development. This stays optional and adapter-boundary scoped.",
+  "rules": [
+    {
+      "id": "agent-instructions-remain-flow-agents-source",
+      "kind": "required-pattern",
+      "classification": "hard-invariant",
+      "stage": "warn",
+      "message": "Flow Agents source instructions must keep the canonical source-of-truth framing.",
+      "owner": "flow-agents-core",
+      "rollback_switch": null,
+      "match": {
+        "files": [
+          "AGENTS.md"
+        ],
+        "pattern": "Flow Agents Source"
+      },
+      "explain": {
+        "summary": "Agent instruction files are governance surface. They must continue to identify this repo as the canonical Flow Agents source.",
+        "mustDo": [
+          "Keep AGENTS.md present and scoped to Flow Agents source behavior.",
+          "Route instruction changes through normal workflow evidence."
+        ],
+        "mustNotDo": [
+          "Replace source-of-truth guidance with generated bundle instructions."
+        ],
+        "contextLinks": [
+          "docs/operating-layers.md",
+          "context/contracts/governance-adapter-contract.md"
+        ]
+      }
+    },
+    {
+      "id": "workflow-contract-changes-require-evals",
+      "kind": "diff-required",
+      "classification": "promotable-policy",
+      "stage": "warn",
+      "message": "Workflow contract or sidecar schema changes should include eval coverage.",
+      "owner": "flow-agents-quality",
+      "rollback_switch": null,
+      "match": {
+        "if-changed": "{context/contracts/,schemas/,src/cli/workflow-sidecar.ts,src/cli/validate-workflow-artifacts.ts}",
+        "then-require": "evals/"
+      },
+      "explain": {
+        "summary": "Workflow state is a reliability boundary. Contract, schema, and sidecar writer changes need executable coverage.",
+        "mustDo": [
+          "Add or update static/integration evals when workflow contracts or sidecar schemas change.",
+          "Record eval evidence in Flow Agents evidence sidecars."
+        ],
+        "contextLinks": [
+          "docs/workflow-usage-guide.md"
+        ]
+      }
+    },
+    {
+      "id": "hook-changes-require-hook-evals",
+      "kind": "diff-required",
+      "classification": "promotable-policy",
+      "stage": "warn",
+      "message": "Runtime hook changes should include hook influence or steering eval updates.",
+      "owner": "flow-agents-runtime",
+      "rollback_switch": null,
+      "match": {
+        "if-changed": "scripts/hooks/",
+        "then-require": "evals/"
+      },
+      "explain": {
+        "summary": "Hook behavior is a just-in-time guidance boundary. Hook changes need eval evidence that guidance still reaches agents or fails honestly.",
+        "mustDo": [
+          "Update hook integration or hook-influence cases when runtime hook behavior changes.",
+          "Document runtime gaps instead of implying live influence."
+        ],
+        "contextLinks": [
+          "evals/fixtures/hook-influence/cases.json"
+        ]
+      }
+    }
+  ]
+}

package/kits/builder/flows/build.flow.json

@@ -0,0 +1,218 @@
+{
+  "id": "builder.build",
+  "version": "1.0",
+  "steps": [
+    { "id": "pull-work", "next": "design-probe" },
+    { "id": "design-probe", "next": "plan" },
+    { "id": "plan", "next": "execute" },
+    { "id": "execute", "next": "verify" },
+    { "id": "verify", "next": "merge-ready" },
+    { "id": "merge-ready", "next": "pr-open" },
+    { "id": "pr-open", "next": "merge-ready-ci" },
+    { "id": "merge-ready-ci", "next": "learn" },
+    { "id": "learn", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "pull-work-gate": {
+      "step": "pull-work",
+      "expects": [
+        {
+          "id": "selected-work",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "A ready work item is selected with scope and acceptance context.",
+          "claim": {
+            "type": "builder.pull-work.selected",
+            "subject": "work-item",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "design-probe-gate": {
+      "step": "design-probe",
+      "expects": [
+        {
+          "id": "pickup-probe-readiness",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Pickup Probe evidence is recorded before planning: goal fit and scope, blockers and dependencies, dependency freshness, acceptance criteria quality, provider state, risk, stop-short risks, planning readiness, decisions, unresolved questions, accepted gaps, probe_status, probe_artifact_ref, grouping decision, expected modified files, and conflict risks.",
+          "claim": {
+            "type": "builder.design-probe.pickup-readiness",
+            "subject": "work-item",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        },
+        {
+          "id": "probe-decisions-or-accepted-gaps",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Planning is blocked until pickup Probe decisions are captured in the pull-work or plan handoff artifact, or unresolved questions are explicitly recorded as accepted gaps. Stale broad continuation language after a merge is not sufficient for planning newly selected work.",
+          "claim": {
+            "type": "builder.design-probe.decisions",
+            "subject": "decision",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "plan-gate": {
+      "step": "plan",
+      "expects": [
+        {
+          "id": "implementation-plan",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "The implementation plan names files, changes, acceptance evidence, and sequencing.",
+          "claim": {
+            "type": "builder.plan.implementation",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "execute-gate": {
+      "step": "execute",
+      "expects": [
+        {
+          "id": "implementation-scope",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "The implementation scope records changed files and excludes unrelated work.",
+          "claim": {
+            "type": "builder.execute.scope",
+            "subject": "change",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "verify-gate": {
+      "step": "verify",
+      "on_route_back": {
+        "missing_evidence": "verify",
+        "implementation_defect": "execute",
+        "plan_gap": "plan",
+        "decision_gap": "design-probe",
+        "default": "verify"
+      },
+      "route_back_policy": {
+        "max_attempts": 3,
+        "on_exceeded": "block"
+      },
+      "expects": [
+        {
+          "id": "tests-evidence",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Relevant tests or checks have evidence tied to the implemented change.",
+          "claim": {
+            "type": "builder.verify.tests",
+            "subject": "flow-step",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        },
+        {
+          "id": "policy-compliance",
+          "kind": "surface.claim",
+          "required": false,
+          "description": "Policy compliance evidence is attached when policy gates apply.",
+          "explore_hint": "Use as advisory evidence for scope, security, privacy, release, or repository policy checks.",
+          "claim": {
+            "type": "builder.verify.policy-compliance",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted", "advisory"]
+          }
+        }
+      ]
+    },
+    "merge-ready-gate": {
+      "step": "merge-ready",
+      "on_route_back": {
+        "missing_evidence": "verify",
+        "implementation_defect": "execute",
+        "plan_gap": "plan",
+        "decision_gap": "design-probe",
+        "default": "verify"
+      },
+      "route_back_policy": {
+        "max_attempts": 3,
+        "on_exceeded": "block"
+      },
+      "expects": [
+        {
+          "id": "merge-readiness",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "The change is ready for merge review based on scope, evidence, and unresolved risks.",
+          "claim": {
+            "type": "builder.merge-ready.readiness",
+            "subject": "change",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "pr-open-gate": {
+      "step": "pr-open",
+      "expects": [
+        {
+          "id": "pull-request-opened",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "A pull request exists with linked work, implementation summary, and verification evidence.",
+          "claim": {
+            "type": "builder.pr-open.pull-request",
+            "subject": "pull-request",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "merge-ready-ci-gate": {
+      "step": "merge-ready-ci",
+      "expects": [
+        {
+          "id": "ci-merge-readiness",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "CI and review status support a merge-ready decision.",
+          "claim": {
+            "type": "builder.merge-ready-ci.readiness",
+            "subject": "pull-request",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "learn-gate": {
+      "step": "learn",
+      "expects": [
+        {
+          "id": "decision-evidence",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Durable decision evidence from the build is recorded.",
+          "claim": {
+            "type": "builder.learn.decisions",
+            "subject": "decision",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        },
+        {
+          "id": "learning-evidence",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Learning evidence from delivery is recorded for future work.",
+          "claim": {
+            "type": "builder.learn.evidence",
+            "subject": "release",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/kits/builder/flows/shape.flow.json

@@ -0,0 +1,127 @@
+{
+  "id": "builder.shape",
+  "version": "1.0",
+  "steps": [
+    { "id": "shape", "next": "breakdown" },
+    { "id": "breakdown", "next": "file-issues" },
+    { "id": "file-issues", "next": "shape-done" },
+    { "id": "shape-done", "next": null }
+  ],
+  "gates": {
+    "shape-gate": {
+      "step": "shape",
+      "expects": [
+        {
+          "id": "shaped-problem",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "The problem is stated in terms a builder can act on.",
+          "claim": {
+            "type": "builder.shape.problem",
+            "subject": "decision",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        },
+        {
+          "id": "shaped-outcome",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "The intended outcome is explicit enough to evaluate later.",
+          "claim": {
+            "type": "builder.shape.outcome",
+            "subject": "flow-run",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        },
+        {
+          "id": "shaped-constraints",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Constraints that affect implementation are captured.",
+          "claim": {
+            "type": "builder.shape.constraints",
+            "subject": "decision",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        },
+        {
+          "id": "shaped-non-goals",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Non-goals are named so the build stays scoped.",
+          "claim": {
+            "type": "builder.shape.non-goals",
+            "subject": "decision",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        },
+        {
+          "id": "shaped-success",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Success criteria are concrete enough for verification.",
+          "claim": {
+            "type": "builder.shape.success",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        },
+        {
+          "id": "shaped-risk",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Material delivery risks are recorded before breakdown.",
+          "claim": {
+            "type": "builder.shape.risk",
+            "subject": "decision",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        },
+        {
+          "id": "open-decisions",
+          "kind": "surface.claim",
+          "required": false,
+          "description": "Open decisions are recorded when the shape is not fully settled.",
+          "explore_hint": "Attach when unresolved choices could affect slices or issue boundaries.",
+          "claim": {
+            "type": "builder.shape.open-decisions",
+            "subject": "decision",
+            "accepted_statuses": ["trusted", "accepted", "advisory"]
+          }
+        }
+      ]
+    },
+    "breakdown-gate": {
+      "step": "breakdown",
+      "expects": [
+        {
+          "id": "slices-defined",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "The shaped work is split into independently useful slices.",
+          "claim": {
+            "type": "builder.breakdown.slices",
+            "subject": "work-item",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "file-issues-gate": {
+      "step": "file-issues",
+      "expects": [
+        {
+          "id": "work-items-filed",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Work items are filed or otherwise recorded with enough context to pull later.",
+          "claim": {
+            "type": "builder.file-issues.work-items",
+            "subject": "work-item",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/kits/builder/kit.json

@@ -0,0 +1,19 @@
+{
+  "schema_version": "1.0",
+  "id": "builder",
+  "name": "Builder Kit",
+  "product_name": "Builder Kit",
+  "description": "A Flow Kit for shaping work, breaking it down, building changes, verifying evidence, preparing pull requests, checking merge readiness, and recording learning.",
+  "flows": [
+    {
+      "id": "builder.shape",
+      "path": "flows/shape.flow.json",
+      "description": "Shape a problem into slices and fileable work items."
+    },
+    {
+      "id": "builder.build",
+      "path": "flows/build.flow.json",
+      "description": "Pull ready work through design probing, planning, implementation, verification, pull request readiness, merge readiness, and learning."
+    }
+  ]
+}