@kontourai/flow-agents 0.1.1

package/schemas/workflow-release.schema.json

@@ -0,0 +1,172 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flow-agents.dev/schemas/workflow-release.schema.json",
+  "title": "Flow Agents Workflow Release Readiness",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "task_slug",
+    "decision",
+    "updated_at",
+    "scope",
+    "evidence_ref",
+    "gates",
+    "rollback_plan",
+    "observability_plan",
+    "post_deploy_checks",
+    "docs"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "task_slug": {
+      "type": "string",
+      "minLength": 1
+    },
+    "repo": {
+      "type": "string",
+      "minLength": 1
+    },
+    "decision": {
+      "type": "string",
+      "enum": ["merge", "release", "deploy", "hold", "rollback_required"]
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "scope": {
+      "type": "string",
+      "minLength": 1
+    },
+    "evidence_ref": {
+      "type": "string",
+      "minLength": 1
+    },
+    "gates": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "status", "summary"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "enum": ["merge", "release", "deploy", "post_deploy", "docs"]
+          },
+          "status": {
+            "type": "string",
+            "enum": ["pass", "hold", "not_required", "not_verified"]
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1
+          },
+          "evidence_refs": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "uniqueItems": true
+          }
+        }
+      }
+    },
+    "rollback_plan": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "summary", "owner"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["ready", "not_required", "missing"]
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "owner": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "observability_plan": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "summary"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["ready", "not_required", "missing"]
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "signals": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true
+        }
+      }
+    },
+    "post_deploy_checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "status", "summary"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "status": {
+            "type": "string",
+            "enum": ["planned", "pass", "fail", "not_required", "not_verified"]
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1
+          },
+          "evidence_refs": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "uniqueItems": true
+          }
+        }
+      }
+    },
+    "docs": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "summary"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["updated", "not_needed", "followup_required", "missing"]
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "refs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true
+        }
+      }
+    }
+  }
+}

package/schemas/workflow-state.schema.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flow-agents.dev/schemas/workflow-state.schema.json",
+  "title": "Flow Agents Workflow State",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "task_slug",
+    "status",
+    "phase",
+    "updated_at",
+    "next_action"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "task_slug": {
+      "type": "string",
+      "minLength": 1
+    },
+    "repo": {
+      "type": "string",
+      "minLength": 1
+    },
+    "status": {
+      "type": "string",
+      "enum": ["new", "planning", "planned", "in_progress", "blocked", "verifying", "verified", "needs_decision", "not_verified", "failed", "delivered", "accepted", "archived"]
+    },
+    "phase": {
+      "type": "string",
+      "enum": ["idea", "backlog", "pickup", "planning", "execution", "verification", "goal_fit", "evidence", "release", "learning", "done"]
+    },
+    "owner": {
+      "type": "string"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "source_request": {
+      "type": "string"
+    },
+    "artifact_paths": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "next_action": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "summary"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["continue", "needs_user", "blocked", "done"]
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "target_phase": {
+          "type": "string",
+          "enum": ["idea", "backlog", "pickup", "planning", "execution", "verification", "goal_fit", "evidence", "release", "learning", "done"]
+        },
+        "target_artifact": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/scripts/README.md

@@ -0,0 +1,111 @@
+# Scripts Directory
+
+`scripts/` is the public compatibility and shell-runtime surface for Flow Agents. Keep command paths stable unless a migration includes wrappers, docs updates, and bundle/install validation.
+
+## Public Wrappers
+
+These files are stable launchers for TypeScript code compiled under `build/src/`:
+
+| Wrapper | Compiled implementation |
+| --- | --- |
+| `build-universal-bundles.js` | `build/src/tools/build-universal-bundles.js` |
+| `filter-installed-packs.js` | `build/src/tools/filter-installed-packs.js` |
+| `generate-context-map.js` | `build/src/tools/generate-context-map.js` |
+| `flow-kit.js` | `build/src/cli/flow-kit.js` |
+| `pull-work-provider.js` | `build/src/cli/pull-work-provider.js` |
+| `effective-backlog-settings.js` | `build/src/cli/effective-backlog-settings.js` |
+| `publish-change-helper.js` | `build/src/cli/publish-change-helper.js` |
+| `promote-workflow-artifact.js` | `build/src/cli/promote-workflow-artifact.js` |
+| `usage-feedback.js` | `build/src/cli/usage-feedback.js` |
+| `validate-hook-influence-cases.js` | `build/src/cli/validate-hook-influence.js` |
+| `validate-source-tree.js` | `build/src/cli.js validate-source` through package command wiring |
+
+If implementation moves, update these wrappers rather than breaking callers.
+`npm run validate:source --` enforces this table: public wrappers must remain
+thin launchers, and implementation logic belongs under `src/cli/` or
+`src/tools/`.
+
+## Package Command Surface
+
+`package.json` exposes command names through npm scripts and package bins.
+Commands that run `node build/src/cli.js <command>` must be registered in
+`src/cli.ts`; bins that point at `build/src/cli.js` must have a matching
+`flow-agents-*` alias in `src/cli.ts`. Direct bins may point at compiled
+single-command entry points such as `build/src/cli/workflow-sidecar.js` when
+callers need a stable executable name without the multiplexer.
+
+`npm run validate:source --` checks this command surface and rejects stale
+migration scaffolding such as pending command registries. Add a real command,
+document a compatibility wrapper, or delete the stale surface.
+
+## Runtime Hooks
+
+`scripts/hooks/` contains runtime hook adapters and policies for Claude Code, Codex, Kiro-style hooks, and repo guardrails. Canonical hook behavior lives here and in TypeScript bundle generation, not in local `.codex/` or `.claude/` installs.
+
+`npm run validate:source --` enforces this inventory. If a hook moves, is
+renamed, or changes category, update the table and the validator together.
+
+| Hook file | Category | Owning checks | Purpose |
+| --- | --- | --- | --- |
+| `claude-hook-adapter.js` | runtime adapter | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_runtime_adapter_activation.sh` | Translates Claude hook events into the shared hook runner contract. |
+| `codex-hook-adapter.js` | runtime adapter | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_runtime_adapter_activation.sh` | Translates Codex hook events into the shared hook runner contract. |
+| `claude-telemetry-hook.js` | telemetry shim | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_telemetry.sh` | Captures Claude hook telemetry and fails open. |
+| `codex-telemetry-hook.js` | telemetry shim | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_telemetry.sh` | Captures Codex hook telemetry and fails open. |
+| `run-hook.js` | hook runner | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_goal_fit_hook.sh`, `evals/integration/test_workflow_steering_hook.sh` | Applies profile/disable flags, traversal checks, and hook execution. |
+| `config-protection.js` | policy hook | `evals/integration/test_hook_category_behaviors.sh` | Blocks unsafe runtime config edits. |
+| `governance-audit.sh` | policy hook | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_telemetry.sh` | Emits governance/Veritas audit context when configured. |
+| `post-edit-accumulator.js` | policy hook | `evals/integration/test_hook_category_behaviors.sh` | Tracks edited files across a turn for later quality hooks. |
+| `quality-gate.js` | policy hook | `evals/integration/test_hook_category_behaviors.sh` | Runs configured quality checks as hook policy. |
+| `report-only-guard.js` | policy hook | `evals/integration/test_hook_category_behaviors.sh` | Protects report-only specialist roles from production edits. |
+| `stop-format-typecheck.js` | policy hook | `evals/integration/test_hook_category_behaviors.sh` | Runs stop-time format/typecheck feedback. |
+| `stop-goal-fit.js` | policy hook | `evals/integration/test_goal_fit_hook.sh` | Warns when a workflow is about to stop short of Goal Fit. |
+| `workflow-steering.js` | policy hook | `evals/integration/test_workflow_steering_hook.sh` | Provides workflow guidance from current artifact state. |
+| `pre-commit-quality.js` | repo guardrail hook | `evals/integration/test_hook_category_behaviors.sh` | Supports repository Git hook checks, not installed runtime hooks. |
+| `desktop-notify.sh` | local notification helper | `evals/integration/test_hook_category_behaviors.sh` | Optional local desktop notification helper. |
+| `lib/audit-transport.sh` | shared hook library | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_telemetry.sh` | Shared audit event transport functions. |
+| `lib/hook-flags.js` | shared hook library | `evals/integration/test_hook_category_behaviors.sh` | Shared profile/disable flag parsing. |
+| `lib/patterns.sh` | shared hook library | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_telemetry.sh` | Shared shell pattern constants. |
+| `lib/resolve-formatter.js` | shared hook library | `evals/integration/test_hook_category_behaviors.sh` | Shared formatter resolution helper. |
+
+## Telemetry
+
+`scripts/telemetry/` contains shell telemetry collection and redaction helpers. Runtime hook wrappers call these scripts; generated bundles copy them for installed runtime use.
+
+Set `CONSOLE_TELEMETRY_URL` or `CONSOLE_URL` to mirror redacted runtime
+telemetry to a Console API. The transport derives `/api/telemetry/records`
+unless `CONSOLE_TELEMETRY_ENDPOINT_URL` is set explicitly. Hosted Console URLs
+must use `https://`; `http://` is accepted only for `localhost` or `127.0.0.1`
+local development. Use `CONSOLE_TELEMETRY_TOKEN` or `CONSOLE_AUTH_TOKEN` for
+bearer auth, and `CONSOLE_TENANT_ID` for hosted tenant routing. Leaving the
+Console URL unset keeps telemetry local-only.
+
+Installers persist telemetry sink choices into the installed
+`scripts/telemetry/telemetry.conf`. `local-files` is the default and requires no
+Console. Add `--telemetry-sink local-kontour-console` for a separately running
+local Console, `--telemetry-sink kontour-hosted-console` for Kontour's hosted
+Console, or `--telemetry-sink user-hosted-console --console-url ...` for a
+self-hosted Console. Legacy `kontour-cloud` and `hosted-kontour-console` names
+remain accepted. `--console-token-file` and `--console-tenant` can be used with
+any Console sink. Prefer `flow-agents init` for a prompted setup; use `--yes`
+with the same flags for CI/headless installs.
+
+Run `flow-agents telemetry-doctor --dest PATH --json --headless` to inspect an
+installed telemetry configuration. It reports active sinks, local JSONL paths,
+Console target settings, and bounded local Console reachability without
+prompting. Add `--allow-network` to probe a non-local HTTPS Console endpoint.
+
+## Install And Repo Utilities
+
+- `install-codex-home.sh`: installs the isolated generated Codex home.
+- `setup-repo-hooks.sh`: configures this clone's Git hook path.
+- `check-content-boundary.cjs`, `detect-tools.sh`, `discover-agents.sh`, `git-status.sh`: repo-local helper commands.
+- `context-budget/` and `statusline/`: specialized support tooling copied into bundles where needed.
+
+## Bundle Policy
+
+`scripts/` is copied into generated bundles intentionally. Do not remove scripts from bundle output only to reduce size unless the corresponding source, generated install behavior, docs, and evals are updated together.
+
+`evals/static/test_universal_bundles.sh` rebuilds bundles and checks the output
+shape. It also verifies reproducibility by building the same source into two
+fresh output directories and diffing the results. A failure means generated
+content is non-deterministic or a bundle build step is carrying stale state.

package/scripts/build-universal-bundles.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Supports FLOW_AGENTS_PACKS through the TypeScript bundle builder.
+import("../build/src/tools/build-universal-bundles.js").then(({ main }) => process.exit(main()));

package/scripts/check-content-boundary.cjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+const { execFileSync } = require("node:child_process");
+const { readFileSync } = require("node:fs");
+
+const SELF = "scripts/check-content-boundary.cjs";
+
+const bannedTerms = [
+  {
+    label: "private vertical product name",
+    pattern: new RegExp(["c", "a", "m", "p", "f", "i", "t"].join(""), "i"),
+  },
+  {
+    label: "private regulated vertical repository name",
+    pattern: new RegExp("\\b" + ["t", "a", "x", "e", "s"].join("") + "\\b", "i"),
+  },
+  {
+    label: "private regulated vertical term",
+    pattern: new RegExp("\\b" + ["t", "a", "x"].join("") + "\\b", "i"),
+  },
+];
+
+const ignoredPathPatterns = [
+  /^node_modules\//,
+  /^dist\//,
+  /^build\//,
+  /^\.git\//,
+  /^\.astro\//,
+  /^test-results\//,
+  /^\.omx\//,
+];
+
+function trackedFiles() {
+  const injected = process.env.FLOW_AGENTS_CONTENT_BOUNDARY_FILES;
+  if (injected) return injected.split(/\r?\n/).filter(Boolean);
+  const output = execFileSync("git", ["ls-files", "-z"], { encoding: "utf8" });
+  return output.split("\0").filter(Boolean);
+}
+
+function isIgnoredPath(filePath) {
+  return filePath === SELF || ignoredPathPatterns.some((pattern) => pattern.test(filePath));
+}
+
+function isWorkflowRuntimeArtifact(filePath) {
+  return filePath.startsWith(".flow-agents/");
+}
+
+function lineNumberFor(content, index) {
+  return content.slice(0, index).split("\n").length;
+}
+
+const findings = [];
+
+for (const filePath of trackedFiles()) {
+  if (isWorkflowRuntimeArtifact(filePath)) {
+    findings.push({
+      filePath,
+      line: 1,
+      label: "Flow Agents runtime artifact must not be tracked in this repo",
+    });
+    continue;
+  }
+
+  if (isIgnoredPath(filePath)) {
+    continue;
+  }
+
+  let content;
+  try {
+    content = readFileSync(filePath, "utf8");
+  } catch {
+    continue;
+  }
+
+  if (content.includes("\0")) {
+    continue;
+  }
+
+  for (const term of bannedTerms) {
+    const match = term.pattern.exec(content);
+    if (match) {
+      findings.push({
+        filePath,
+        line: lineNumberFor(content, match.index),
+        label: term.label,
+      });
+    }
+  }
+}
+
+if (findings.length > 0) {
+  console.error("Content boundary check failed:");
+  for (const finding of findings) {
+    console.error(`- ${finding.filePath}:${finding.line} ${finding.label}`);
+  }
+  process.exit(1);
+}
+
+console.log("Content boundary check passed.");

package/scripts/context-budget/budget-scan.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# budget-scan.sh — Scan Flow Agents bundles for token overhead estimation
+# Usage: bash budget-scan.sh [--verbose]
+set -euo pipefail
+
+BUNDLE_DIR="${FLOW_AGENTS_BUNDLE_DIR:-${HOME}/.flow-agents}"
+VERBOSE=false
+[[ "${1:-}" == "--verbose" ]] && VERBOSE=true
+
+# Handle missing bundle dir gracefully
+if [[ ! -d "$BUNDLE_DIR" ]]; then
+  echo '{"packages":[],"issues":[],"totals":{"context":0,"skills":0,"agents":0,"total":0}}'
+  exit 0
+fi
+
+# Collect all bundle directories (top-level + local/)
+_pkg_dirs=()
+for d in "${BUNDLE_DIR}"/*/; do
+  [[ ! -d "$d" ]] && continue
+  base=$(basename "$d")
+  if [[ "$base" == "local" ]]; then
+    for ld in "${d}"*/; do
+      [[ -d "$ld" ]] && _pkg_dirs+=("$ld")
+    done
+  else
+    _pkg_dirs+=("$d")
+  fi
+done
+
+estimate_tokens() {
+  local file="$1"
+  [[ ! -f "$file" ]] && echo 0 && return
+  local words chars
+  words=$(wc -w < "$file" 2>/dev/null | tr -d ' ')
+  chars=$(wc -c < "$file" 2>/dev/null | tr -d ' ')
+  case "$file" in
+    *.sh|*.json) echo $(( chars / 4 )) ;;
+    *) echo $(( (words * 13 + 9) / 10 )) ;;
+  esac
+}
+
+count_lines() {
+  local file="$1"
+  [[ ! -f "$file" ]] && echo 0 && return
+  wc -l < "$file" 2>/dev/null | tr -d ' '
+}
+
+skill_desc_words() {
+  local file="$1"
+  [[ ! -f "$file" ]] && echo 0 && return
+  sed -n '/^---$/,/^---$/p' "$file" | grep -i 'description' | head -1 | wc -w | tr -d ' '
+}
+
+count_mcp_servers() {
+  local file="$1"
+  jq '[.mcpServers // {} | keys | length] | add // 0' "$file" 2>/dev/null || echo 0
+}
+
+count_tools() {
+  local file="$1"
+  jq '[.tools // [] | length] | add // 0' "$file" 2>/dev/null || echo 0
+}
+
+prompt_lines() {
+  local file="$1"
+  case "$file" in
+    *.json)
+      jq -r '.systemPrompt // .prompt // .developer_instructions // ""' "$file" 2>/dev/null | wc -l | tr -d ' '
+      ;;
+    *.toml)
+      # Codex agent TOML stores instructions as escaped newlines in one string.
+      awk -F' = ' '/^(developer_instructions|instructions|prompt) = / {print $2}' "$file" \
+        | sed 's/^"//; s/"$//' \
+        | perl -pe 's/\\n/\n/g' \
+        | wc -l | tr -d ' '
+      ;;
+    *)
+      echo 0
+      ;;
+  esac
+}
+
+packages_json='[]'
+issues_json='[]'
+
+for pkg_dir in "${_pkg_dirs[@]}"; do
+  [[ ! -d "$pkg_dir" ]] && continue
+  pkg_name=$(basename "$pkg_dir")
+
+  context_tokens=0
+  skill_tokens=0
+  agent_tokens=0
+  files_json='[]'
+
+  # Scan context files
+  while IFS= read -r -d '' f; do
+    tokens=$(estimate_tokens "$f")
+    lines=$(count_lines "$f")
+    context_tokens=$((context_tokens + tokens))
+    rel="${f#"$pkg_dir"}"
+    if $VERBOSE; then
+      files_json=$(echo "$files_json" | jq -c --arg p "$rel" --argjson t "$tokens" --argjson l "$lines" '. + [{path:$p,tokens:$t,lines:$l,type:"context"}]')
+    fi
+    if [[ "$lines" -gt 100 ]]; then
+      issues_json=$(echo "$issues_json" | jq -c --arg p "${pkg_name}/${rel}" --argjson l "$lines" '. + [{type:"context_bloat",path:$p,lines:$l,suggestion:"Consider moving to context/deferred/ or splitting"}]')
+    fi
+  done < <(find "${pkg_dir}context" -name '*.md' -print0 2>/dev/null || true)
+
+  # Scan skills
+  while IFS= read -r -d '' f; do
+    tokens=$(estimate_tokens "$f")
+    desc_words=$(skill_desc_words "$f")
+    skill_tokens=$((skill_tokens + tokens))
+    rel="${f#"$pkg_dir"}"
+    if $VERBOSE; then
+      files_json=$(echo "$files_json" | jq -c --arg p "$rel" --argjson t "$tokens" --argjson dw "$desc_words" '. + [{path:$p,tokens:$t,desc_words:$dw,type:"skill"}]')
+    fi
+    if [[ "$desc_words" -gt 30 ]]; then
+      issues_json=$(echo "$issues_json" | jq -c --arg p "${pkg_name}/${rel}" --argjson w "$desc_words" '. + [{type:"bloated_skill_desc",path:$p,words:$w,suggestion:"Trim description to under 30 words"}]')
+    fi
+  done < <(find "${pkg_dir}skills" -name 'SKILL.md' -print0 2>/dev/null || true)
+
+  # Scan agent specs
+  while IFS= read -r -d '' f; do
+    tokens=$(estimate_tokens "$f")
+    pl=$(prompt_lines "$f")
+    mcp=$(count_mcp_servers "$f")
+    tools=$(count_tools "$f")
+    agent_tokens=$((agent_tokens + tokens))
+    rel="${f#"$pkg_dir"}"
+    if $VERBOSE; then
+      files_json=$(echo "$files_json" | jq -c --arg p "$rel" --argjson t "$tokens" --argjson pl "$pl" --argjson mcp "$mcp" --argjson tools "$tools" '. + [{path:$p,tokens:$t,prompt_lines:$pl,mcp_servers:$mcp,tools:$tools,type:"agent"}]')
+    fi
+    if [[ "$pl" -gt 200 ]]; then
+      issues_json=$(echo "$issues_json" | jq -c --arg p "${pkg_name}/${rel}" --argjson l "$pl" '. + [{type:"heavy_agent_spec",path:$p,prompt_lines:$l,suggestion:"Reduce systemPrompt or move to context file"}]')
+    fi
+    if [[ "$mcp" -gt 10 ]] || [[ "$tools" -gt 50 ]]; then
+      issues_json=$(echo "$issues_json" | jq -c --arg p "${pkg_name}/${rel}" --argjson m "$mcp" --argjson t "$tools" '. + [{type:"mcp_oversubscription",path:$p,mcp_servers:$m,tools:$t,suggestion:"Reduce MCP servers or tools per agent"}]')
+    fi
+  done < <(find "${pkg_dir}agents" \( -name '*agent-spec.json' -o -name '*.json' -o -name '*.toml' \) -print0 2>/dev/null || true)
+
+  total=$((context_tokens + skill_tokens + agent_tokens))
+  pkg_entry=$(jq -nc \
+    --arg name "$pkg_name" \
+    --argjson context "$context_tokens" \
+    --argjson skills "$skill_tokens" \
+    --argjson agents "$agent_tokens" \
+    --argjson total "$total" \
+    --argjson files "$files_json" \
+    '{name:$name,tokens:{context:$context,skills:$skills,agents:$agents,total:$total},files:$files}')
+  packages_json=$(echo "$packages_json" | jq -c --argjson p "$pkg_entry" '. + [$p]')
+done
+
+total_context=$(echo "$packages_json" | jq '[.[].tokens.context] | add // 0')
+total_skills=$(echo "$packages_json" | jq '[.[].tokens.skills] | add // 0')
+total_agents=$(echo "$packages_json" | jq '[.[].tokens.agents] | add // 0')
+total_all=$(echo "$packages_json" | jq '[.[].tokens.total] | add // 0')
+
+jq -nc \
+  --argjson packages "$packages_json" \
+  --argjson issues "$issues_json" \
+  --argjson tc "$total_context" \
+  --argjson ts "$total_skills" \
+  --argjson ta "$total_agents" \
+  --argjson tt "$total_all" \
+  '{packages:$packages,issues:$issues,totals:{context:$tc,skills:$ts,agents:$ta,total:$tt}}'

package/scripts/detect-tools.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Detect optional CLI tools. Output is injected into agent context at spawn.
+

package/scripts/discover-agents.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+# Spawn hook: discover agent cards from the repo, installed bundle, or legacy root file.
+echo "=== Agent Card Discovery ==="
+FOUND=0
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+shopt -s nullglob
+cards=(
+  "$ROOT_DIR"/agent-cards/*.json
+  "$HOME"/.flow-agents/agent-cards/*.json
+  "$HOME"/.flow-agents/agent-card.json
+)
+for card in "${cards[@]}"; do
+  [ -f "$card" ] || continue
+  FOUND=$((FOUND + 1))
+  name=$(node -e "const d=require(process.argv[1]); process.stdout.write(d.name||'?')" "$card" 2>/dev/null)
+  agent=$(node -e "const d=require(process.argv[1]); process.stdout.write(d.agent||'?')" "$card" 2>/dev/null)
+  desc=$(node -e "const d=require(process.argv[1]); process.stdout.write(d.description||'')" "$card" 2>/dev/null)
+  echo ""
+  echo "📋 $name (agent: $agent)"
+  echo "   $desc"
+done
+if [ "$FOUND" -eq 0 ]; then
+  echo "No agent cards found."
+else
+  echo ""
+  echo "Discovered $FOUND orchestrator(s)."
+fi

package/scripts/effective-backlog-settings.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("../build/src/cli/effective-backlog-settings.js").then(({ main }) => process.exit(main()));

package/scripts/filter-installed-packs.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("../build/src/tools/filter-installed-packs.js").then(({ main }) => process.exit(main(process.argv.slice(2))));