@kontourai/flow-agents 1.0.1 → 1.2.0

package/build/src/tools/build-universal-bundles.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { loadJson, readText, root, walkFiles, writeText } from "./common.js";
 const dist = process.env.FLOW_AGENTS_DIST_DIR ? path.resolve(process.env.FLOW_AGENTS_DIST_DIR) : path.join(root, "dist");
@@ -8,6 +9,61 @@ const packs = loadJson(path.join(root, "packaging/packs.json"));
 const textExtensions = new Set([".css", ".html", ".js", ".json", ".md", ".sh", ".toml", ".txt", ".yaml", ".yml", ".ts"]);
 const dropDiagnostics = [];
 const printDiagnostics = !["0", "false", "no"].includes(String(process.env.FLOW_AGENTS_EXPORT_DIAGNOSTICS ?? "1").toLowerCase());
+/**
+ * Collect all skill source paths across skills/ and kit-owned skills.
+ * Returns an array of {name, src} pairs where name is the install name
+ * (same as the directory name) and src is the absolute SKILL.md path.
+ * Kit-owned skills are discovered by reading kit.json `skills` arrays;
+ * each entry's `path` is resolved relative to the kit directory.
+ */
+function collectAllSkills() {
+    const results = [];
+    const seen = new Set();
+    // 1. Top-level skills/ directory (tools pending reclassification).
+    const skillsDir = path.join(root, "skills");
+    if (fs.existsSync(skillsDir)) {
+        for (const skill of fs.readdirSync(skillsDir).sort()) {
+            const skillPath = path.join(skillsDir, skill, "SKILL.md");
+            if (fs.existsSync(skillPath) && !seen.has(skill)) {
+                seen.add(skill);
+                results.push({ name: skill, src: skillPath });
+            }
+        }
+    }
+    // 2. Kit-owned skills declared in kits/<kit>/kit.json `skills` arrays.
+    const kitsDir = path.join(root, "kits");
+    if (fs.existsSync(kitsDir)) {
+        for (const kitName of fs.readdirSync(kitsDir).sort()) {
+            const kitJson = path.join(kitsDir, kitName, "kit.json");
+            if (!fs.existsSync(kitJson))
+                continue;
+            let kitManifest;
+            try {
+                kitManifest = loadJson(kitJson);
+            }
+            catch {
+                continue;
+            }
+            const skills = Array.isArray(kitManifest["skills"]) ? kitManifest["skills"] : [];
+            for (const entry of skills) {
+                if (typeof entry !== "object" || entry === null)
+                    continue;
+                const skillEntry = entry;
+                const relPath = typeof skillEntry["path"] === "string" ? skillEntry["path"] : null;
+                if (!relPath)
+                    continue;
+                // Derive install name from the directory containing SKILL.md (one level up).
+                const absPath = path.resolve(path.join(kitsDir, kitName), relPath);
+                const skillName = path.basename(path.dirname(absPath));
+                if (fs.existsSync(absPath) && !seen.has(skillName)) {
+                    seen.add(skillName);
+                    results.push({ name: skillName, src: absPath });
+                }
+            }
+        }
+    }
+    return results.sort((a, b) => a.name.localeCompare(b.name));
+}
 function resetDir(dir) {
     fs.rmSync(dir, { recursive: true, force: true });
     fs.mkdirSync(dir, { recursive: true });
@@ -326,10 +382,8 @@ function buildClaudeCode(agents) {
     writeText(path.join(bundle, manifest.claude_code.task_dir, ".gitkeep"), "");
     for (const spec of agents)
         writeText(path.join(bundle, ".claude/agents", `${spec.name}.md`), exportClaudeAgent(spec));
-    for (const skill of fs.readdirSync(path.join(root, "skills"))) {
-        const skillPath = path.join(root, "skills", skill, "SKILL.md");
-        if (fs.existsSync(skillPath))
-            writeText(path.join(bundle, ".claude/skills", skill, "SKILL.md"), sanitizeText(readText(skillPath), "claude-code", "<bundle-root>"));
+    for (const { name, src } of collectAllSkills()) {
+        writeText(path.join(bundle, ".claude/skills", name, "SKILL.md"), sanitizeText(readText(src), "claude-code", "<bundle-root>"));
     }
     writeText(path.join(bundle, ".claude/settings.json"), exportClaudeSettings());
     writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("Claude Code", agents, manifest.claude_code.task_dir));
@@ -351,10 +405,8 @@ function buildCodex(agents) {
     writeText(path.join(bundle, ".codex/hooks.json"), exportCodexHooks());
     for (const spec of targetAgents)
         writeText(path.join(bundle, ".codex/agents", `${spec.name}.toml`), exportCodexAgent(spec));
-    for (const skill of fs.readdirSync(path.join(root, "skills"))) {
-        const skillPath = path.join(root, "skills", skill, "SKILL.md");
-        if (fs.existsSync(skillPath))
-            writeText(path.join(bundle, ".codex/skills", skill, "SKILL.md"), sanitizeText(readText(skillPath), "codex", "<bundle-root>"));
+    for (const { name, src } of collectAllSkills()) {
+        writeText(path.join(bundle, ".codex/skills", name, "SKILL.md"), sanitizeText(readText(src), "codex", "<bundle-root>"));
     }
     writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("Codex", targetAgents, manifest.codex.task_dir));
     writeText(path.join(bundle, "README.md"), exportTargetReadme("Codex", "bash install.sh /path/to/workspace"));
@@ -518,10 +570,8 @@ function buildOpencode(agents) {
     for (const spec of agents) {
         writeText(path.join(bundle, ".opencode/agents", `${spec.name}.md`), exportOpencodeAgent(spec));
     }
-    for (const skill of fs.readdirSync(path.join(root, "skills"))) {
-        const skillPath = path.join(root, "skills", skill, "SKILL.md");
-        if (fs.existsSync(skillPath))
-            writeText(path.join(bundle, ".opencode/skills", skill, "SKILL.md"), sanitizeText(readText(skillPath), "opencode", "<bundle-root>"));
+    for (const { name, src } of collectAllSkills()) {
+        writeText(path.join(bundle, ".opencode/skills", name, "SKILL.md"), sanitizeText(readText(src), "opencode", "<bundle-root>"));
     }
     writeText(path.join(bundle, ".opencode/plugins/flow-agents.js"), exportOpencodePlugin());
     writeText(path.join(bundle, "opencode.json"), exportOpencodeConfig());
@@ -631,10 +681,8 @@ function buildPi(agents) {
     writeText(path.join(bundle, manifest.pi.task_dir, ".gitkeep"), "");
     // pi has no named-subagent registry; agents are left canonical/unexported.
     // Skills are exported to .pi/skills/ (direct .md files supported in that dir).
-    for (const skill of fs.readdirSync(path.join(root, "skills"))) {
-        const skillPath = path.join(root, "skills", skill, "SKILL.md");
-        if (fs.existsSync(skillPath))
-            writeText(path.join(bundle, ".pi/skills", skill, "SKILL.md"), sanitizeText(readText(skillPath), "pi", "<bundle-root>"));
+    for (const { name, src } of collectAllSkills()) {
+        writeText(path.join(bundle, ".pi/skills", name, "SKILL.md"), sanitizeText(readText(src), "pi", "<bundle-root>"));
     }
     writeText(path.join(bundle, ".pi/extensions/flow-agents.ts"), exportPiExtension());
     writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("pi", agents, manifest.pi.task_dir));
@@ -647,7 +695,7 @@ function buildCatalog(agents) {
     return {
         source_root: ".",
         agents: agents.slice().sort((a, b) => a.name.localeCompare(b.name)).map((spec) => spec.name),
-        skills: fs.readdirSync(path.join(root, "skills")).filter((name) => fs.existsSync(path.join(root, "skills", name, "SKILL.md"))).sort(),
+        skills: collectAllSkills().map(({ name }) => name),
         powers: fs.readdirSync(path.join(root, "powers")).filter((name) => fs.existsSync(path.join(root, "powers", name, "mcp.json"))).sort(),
         packs: packs.packs ?? [],
         kits: fs.existsSync(kitsCatalog) ? loadJson(kitsCatalog).kits ?? [] : [],
@@ -678,5 +726,21 @@ export function main() {
     }
     return 0;
 }
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = main();
+}

package/build/src/tools/generate-context-map.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { exists, loadJson, markdownTable, oneLine, readText, rel, root, writeText } from "./common.js";
 const defaultOutput = path.join(root, "docs/context-map.md");
@@ -74,16 +75,58 @@ function repoShape(manifest) {
     rows.push([".flow-agents", "runtime", "Cross-session workflow artifacts and sidecars. Not committed by default."]);
     return rows;
 }
+/** Collect all skill {name, absPath} pairs from skills/ and kit-owned skills. */
+function allSkillPaths() {
+    const results = [];
+    const seen = new Set();
+    const skillsDir = path.join(root, "skills");
+    if (exists(skillsDir)) {
+        for (const name of fs.readdirSync(skillsDir).sort()) {
+            const absPath = path.join(skillsDir, name, "SKILL.md");
+            if (exists(absPath) && !seen.has(name)) {
+                seen.add(name);
+                results.push({ name, absPath });
+            }
+        }
+    }
+    const kitsDir = path.join(root, "kits");
+    if (exists(kitsDir)) {
+        for (const kitName of fs.readdirSync(kitsDir).sort()) {
+            const kitJson = path.join(kitsDir, kitName, "kit.json");
+            if (!exists(kitJson))
+                continue;
+            let kitManifest;
+            try {
+                kitManifest = loadJson(kitJson);
+            }
+            catch {
+                continue;
+            }
+            const skills = Array.isArray(kitManifest["skills"]) ? kitManifest["skills"] : [];
+            for (const entry of skills) {
+                if (typeof entry !== "object" || entry === null)
+                    continue;
+                const skillEntry = entry;
+                const relPath = typeof skillEntry["path"] === "string" ? skillEntry["path"] : null;
+                if (!relPath)
+                    continue;
+                const absPath = path.resolve(path.join(kitsDir, kitName), relPath);
+                const skillName = path.basename(path.dirname(absPath));
+                if (exists(absPath) && !seen.has(skillName)) {
+                    seen.add(skillName);
+                    results.push({ name: skillName, absPath });
+                }
+            }
+        }
+    }
+    return results.sort((a, b) => a.name.localeCompare(b.name));
+}
 function listSkillRows() {
     const workflowRows = [];
     const supportRows = [];
-    const skillsDir = path.join(root, "skills");
-    for (const name of fs.readdirSync(skillsDir).sort()) {
-        const skillPath = path.join(skillsDir, name, "SKILL.md");
-        if (!exists(skillPath))
-            continue;
-        const meta = frontmatter(readText(skillPath));
-        const row = [meta.name ?? name, rel(skillPath), oneLine(meta.description ?? "")];
+    for (const { name, absPath } of allSkillPaths()) {
+        const meta = frontmatter(readText(absPath));
+        const row = [meta.name ?? name, rel(absPath), oneLine(meta.description ?? "")];
         if (workflowSkills.has(row[0]))
             workflowRows.push(row);
         else
@@ -194,5 +237,21 @@ export function main(argv = process.argv.slice(2)) {
     console.log(`Wrote ${rel(output)}`);
     return 0;
 }
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = main();
+}

package/build/src/tools/validate-package.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import path from "node:path";
 export function main(argv = process.argv.slice(2)) {
     const [prefixArg, localFlag] = argv;
@@ -60,5 +61,21 @@ export function main(argv = process.argv.slice(2)) {
     console.log(errors === 0 ? "Result: PASS" : `Result: FAIL (${errors} error(s))`);
     return errors === 0 ? 0 : 1;
 }
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = main();
+}

package/build/src/tools/validate-source-tree.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { loadJson, readText, rel, root, walkFiles } from "./common.js";
@@ -36,7 +37,7 @@ const publicScriptWrappers = new Map([
             ] }],
     ["scripts/filter-installed-packs.js", { target: "../build/src/tools/filter-installed-packs.js", significantLines: ['import("../build/src/tools/filter-installed-packs.js").then(({ main }) => process.exit(main(process.argv.slice(2))));'] }],
     ["scripts/generate-context-map.js", { target: "../build/src/tools/generate-context-map.js", significantLines: ['import("../build/src/tools/generate-context-map.js").then(({ main }) => process.exit(main(process.argv.slice(2))));'] }],
-    ["scripts/flow-kit.js", { target: "../build/src/cli/flow-kit.js", significantLines: ['import("../build/src/cli/flow-kit.js").then(({ main }) => process.exit(main()));'] }],
+    ["scripts/kit.js", { target: "../build/src/cli/kit.js", significantLines: ['import("../build/src/cli/kit.js").then(({ main }) => main().then((code) => process.exit(code)));'] }],
     ["scripts/pull-work-provider.js", { target: "../build/src/cli/pull-work-provider.js", significantLines: ['import("../build/src/cli/pull-work-provider.js").then(({ main }) => process.exit(main()));'] }],
     ["scripts/effective-backlog-settings.js", { target: "../build/src/cli/effective-backlog-settings.js", significantLines: ['import("../build/src/cli/effective-backlog-settings.js").then(({ main }) => process.exit(main()));'] }],
     ["scripts/publish-change-helper.js", { target: "../build/src/cli/publish-change-helper.js", significantLines: ['import("../build/src/cli/publish-change-helper.js").then(({ main }) => process.exit(main()));'] }],
@@ -390,6 +391,32 @@ function validateAgentPaths(reporter, manifest) {
     }
 }
 function validateLegacyRefs(reporter) {
+    // Collect all kit-owned asset relative paths so legacy-ref scanning can skip matches
+    // that are subpaths of kit-owned assets. E.g. legacyRefRe matches "skills/plan-work/SKILL.md"
+    // within "kits/builder/skills/plan-work/SKILL.md"; the kit declares and validates these.
+    const kitOwnedSubPaths = new Set();
+    const kitsDir = path.join(root, "kits");
+    if (fs.existsSync(kitsDir)) {
+        for (const kitName of fs.readdirSync(kitsDir)) {
+            const kitJson = path.join(kitsDir, kitName, "kit.json");
+            if (!fs.existsSync(kitJson))
+                continue;
+            try {
+                const kitManifest = loadJson(kitJson);
+                for (const section of ["skills", "docs", "adapters", "evals", "assets"]) {
+                    const entries = Array.isArray(kitManifest[section]) ? kitManifest[section] : [];
+                    for (const entry of entries) {
+                        if (typeof entry !== "object" || entry === null)
+                            continue;
+                        const relPath = entry["path"];
+                        if (typeof relPath === "string" && relPath)
+                            kitOwnedSubPaths.add(relPath);
+                    }
+                }
+            }
+            catch { /* skip invalid kit.json */ }
+        }
+    }
     for (const file of walkFiles(path.join(root, "evals")).sort()) {
         if (!textRefExtensions.has(path.extname(file)))
             continue;
@@ -403,6 +430,11 @@ function validateLegacyRefs(reporter) {
                 continue;
             if (ref.split(/[\\/]/).includes("node_modules"))
                 continue;
+            // Skip refs that are declared kit-owned asset paths or their parent directories
+            // (e.g. "skills/plan-work/SKILL.md" or "skills/plan-work" matched inside
+            // "kits/builder/skills/plan-work/SKILL.md" in eval files).
+            if (kitOwnedSubPaths.has(ref) || [...kitOwnedSubPaths].some((p) => p.startsWith(ref + "/")))
+                continue;
             const candidates = [path.join(root, ref), ...(ref.startsWith("evals/") ? [] : [path.join(root, "evals", ref)])];
             if (!candidates.some(fs.existsSync))
                 reporter.fail(`${rel(file)}: references missing source path: ${ref}`);
@@ -624,5 +656,21 @@ export function main(argv = process.argv.slice(2)) {
     console.log("Source tree validation passed.");
     return 0;
 }
-if (import.meta.url === `file://${process.argv[1]}`)
-    process.exit(main());
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = main();
+}

package/context/scripts/telemetry/console-presets.sh

@@ -6,7 +6,7 @@ flow_agents_local_kontour_console_url() {
 }
 
 flow_agents_kontour_cloud_console_url() {
-  printf '%s\n' "${FLOW_AGENTS_KONTOUR_CLOUD_CONSOLE_URL:-https://console.kontourai.com}"
+  printf '%s\n' "${FLOW_AGENTS_KONTOUR_CLOUD_CONSOLE_URL:-https://console.kontourai.io}"
 }
 
 flow_agents_kontour_hosted_console_url() {

package/docs/adr/0007-flow-skill-kit-tool-boundary.md

@@ -0,0 +1,169 @@
+---
+title: "ADR 0007: Flow / Skill / Kit / Tool Boundary"
+---
+
+# ADR 0007: Flow / Skill / Kit / Tool Boundary
+
+**Date:** 2026-06-15  
+**Status:** Accepted
+
+---
+
+## Context
+
+Flow Agents has accumulated ~26 skills. When kits were first introduced, the word "skill" was used loosely for anything the agent knew how to do — from kit-specific workflow procedures to general capabilities (search, browser, dependency scanning) to cross-cutting concerns (agentic engineering principles, context budgeting). That blurred three genuinely different things: the agent's *procedural methods for flow steps*, the *raw capabilities it wields*, and the *containers that package flows with their implementations*.
+
+The boundary became sharper when the Flow Definition container moved to `kontourai/flow` (ADR 0001). Once Flow owns the process contract and Flow Agents owns the agent-facing implementation, a natural question emerges: where does each skill belong, and what is a skill in the first place?
+
+A related accumulation was an informal "general capability skill tier" — skills like `agentic-engineering`, `search-first`, `github-cli`, and `eval-rebuild` that described how the agent uses runtime capabilities, not how it implements a specific flow step. That tier was never designed; it accreted as the skill list grew. It is not a peer design concept alongside Kit-skills; it is an artifact of undifferentiated naming.
+
+This ADR records the conceptual model that was agreed in a design conversation with Brian Anderson on 2026-06-15 and makes it the authoritative reference for future skill placement, kit authoring, and orphan triage.
+
+---
+
+## Decision
+
+### The Four Definitions
+
+#### 1. Flow Definition = the WHAT
+
+A Flow Definition is a process contract: steps, gates, expected evidence, and definition-of-done. It is the container for *what* a workflow accomplishes, not *how* the agent does it.
+
+- Flow Definitions are owned and validated by `kontourai/flow`.
+- They are agentless-capable: a CI job or a human can satisfy a flow without an agent, as proven by the agentless gate-eval work (issues #52 and #60).
+- Flow Agents *consumes* Flow Definitions; it does not own them (ADR 0001).
+
+#### 2. Skill = the HOW = the *do* of a specific flow step
+
+A skill is the agent's procedural method for accomplishing one step or gate of a flow. Brian's framing: *"skills are the do part of the flow definition."*
+
+Consequences of this definition:
+
+- There is exactly **one kind of skill** in the intended design.
+- Every skill is bound to a flow step: it implements the agent's side of that step.
+- Every skill belongs to the kit that owns that flow.
+- A skill with no flow step behind it is not a skill in this model — it is either a tool, an orphan, or evidence of a missing flow.
+
+The earlier informal "general capability skill tier" was an accreted artifact, not a designed concept. It is not a peer category to Kit-skills. Skills in that tier are reclassified as tools, orphans, or — where a missing flow is strongly implied — candidates for a future kit.
+
+#### 3. Tool = a raw capability the agent wields
+
+A tool is something the agent *uses* to do the work: run bash, read/write files, drive a browser, call `gh`, look up packages, search the web. Tools are:
+
+- Provided by the runtime or harness, not tied to any flow.
+- The agent's *hands*, not its *method*.
+- Distinct from a skill even when the agent wraps a tool call in a named skill file — if the "skill" is just "here is how to invoke this capability," it is a tool description, not a flow-step method.
+
+A skill that only describes how to use a tool (e.g., `github-cli`, `browser-test`, `eval-rebuild`) belongs in harness documentation or an agent system prompt, not in the `skills/` directory as a first-class skill.
+
+#### 4. Kit = packages a flow with its skills
+
+A kit:
+
+- Owns one or more Flow Definitions.
+- Provides the agent-side skills that implement those flows' steps.
+- May include store adapters, evals, and docs.
+
+A kit's skills are the agent-side implementation of that kit's flows, in a one-to-one relationship between skills and flow steps (or a small cluster of closely related steps).
+
+### Core Rule
+
+> **A skill that has no flow step behind it is not a Kit-skill.** It is either:
+> - (a) a **TOOL** mislabeled as a skill — it describes a raw capability and should live in harness docs or an agent system prompt, or
+> - (b) an **ORPHAN** — it is procedural and agent-driven but the flow that would own its step has not been defined yet; it signals a missing or implicit flow, or
+> - (c) **scope drift** — it does not belong in this repo's skill layer at all.
+
+### Cross-Kit Skill Sharing: DEFERRED
+
+A question arose during this discussion: can a skill be shared across kits? For example, `knowledge-capture` is implemented as a Knowledge Kit skill (`knowledge.ingest:capture`) but is used as a support step inside Builder Kit flows (e.g., `learning-review` calls `knowledge-capture`).
+
+The sharing model under active consideration is an npm-dependency model: Kit B declares a peer dependency on Kit A and invokes Kit A's skills as a consumer, without absorbing them into Kit B's skill list.
+
+**This alternative is not adopted now.** The cross-kit sharing question is deferred. Until it is resolved:
+
+- Each skill belongs to exactly one kit.
+- When a skill is consumed across kits, the consumer kit calls the skill by reference; it does not duplicate or re-own it.
+- The audit table in the companion document (`0007-skill-audit.md`) reflects the intended single-kit ownership for each skill.
+
+---
+
+## Consequences
+
+### Immediate Structural Clarity
+
+- The `skills/` directory contains a mix of Kit-skills, tools, and orphans. The audit table in `docs/adr/0007-skill-audit.md` maps each skill to one of those three classifications.
+- Skills that are tools (`agentic-engineering`, `browser-test`, `dependency-update`, `eval-rebuild`, `github-cli`, `search-first`) should eventually migrate to agent system prompts, harness context, or be removed from `skills/` entirely. No move is made in this ADR.
+- Orphans (`context-budget`, `explore`, `feedback-loop`, `frontend-design`) each implied either a missing flow or a reclassification. All four were ruled on 2026-06-15 (see "Orphan Rulings — 2026-06-15" below); all are REMOVED, with preserved intents recorded.
+
+### Builder Kit Fix (Issue #62) Becomes Mechanical
+
+With this model, the Builder Kit fix discussed in issue #62 is straightforward: every skill in `skills/` that maps to `builder.build` or `builder.shape` steps belongs in the Builder Kit. The audit table provides the exact step-to-skill mapping. The fix is to move those skills into `kits/builder/` — but that move is explicitly out of scope for this ADR. This ADR provides the analysis that makes the move mechanical.
+
+### Tools Are Flow-Agnostic
+
+Runtime-provided tools (`gh`, Playwright, bash, file read/write, package registries) are not skills. They do not belong to flows. The agent wields them as hands while executing flow steps. Packaging them as skills creates false parallelism with Kit-skills and inflates the skill list.
+
+### Orphan Triage Protocol
+
+For each orphan, one of these outcomes is required:
+
+1. **Define the missing flow.** If the orphan describes a coherent procedural method that deserves a kit, define the flow, create the kit, and move the skill.
+2. **Reclassify as a tool.** If the orphan is really a description of how to use a raw capability, remove it from `skills/` and fold its content into agent context or harness docs.
+3. **Accept scope drift.** If the orphan does not belong in this repo's skill layer, remove it.
+
+No orphan should remain permanently in `skills/` without a documented triage outcome.
+
+### Orphan Rulings — 2026-06-15
+
+Brian ruled on all four orphans on 2026-06-15. All four are **REMOVED** for now; preserved intents are recorded below so the rationale is not lost.
+
+| Orphan Skill | Ruling | Preserved Intent |
+| --- | --- | --- |
+| `explore` | **REMOVED** — reclassified as a tool: parallel codebase-reading capability. | The original aim was multi-angle codebase capture (dependencies, security, runnability/testability, business logic, patterns). This preserved intent is the seed of a possible future `codebase-onboarding` flow if that capability is ever wanted as a first-class kit flow. |
+| `feedback-loop` | **REMOVED** — subsumed. Its "did the change work locally" concern is now handled by `verify-work` plus the flow route-back capability. | No separate preserved intent; the concern is covered. |
+| `context-budget` | **REMOVED** — agent self-maintenance; relates conceptually to `learning-review`. Not a flow-step skill. | Conceptually adjacent to `learning-review`; could inform a future self-maintenance flow, but is not a flow-step skill under the current model. |
+| `frontend-design` | **REMOVED** for now. | "Plan-work but for UI" — the seed of a possible future UI/Frontend Kit with design + visual-verify steps. Revisit if a UI kit is ever built. |
+
+These rulings do not change this ADR's status. The ADR remains **Proposed** pending Brian's separate confirmation of the whole document.
+
+### Knowledge Kit Boundary
+
+`knowledge-capture` is the one skill in `skills/` that belongs to the Knowledge Kit rather than the Builder Kit. Its canonical flow is `knowledge.ingest:capture`. Its presence in the top-level `skills/` directory (rather than in `kits/knowledge/`) is itself a consequence of the pre-ADR undifferentiated structure. Future kit authoring should place kit skills inside their kit directory.
+
+### Audit Table as Evidence
+
+The companion document `docs/adr/0007-skill-audit.md` is the authoritative mapping of every skill in `skills/` to this model. It provides the evidence base for Builder Kit issue #62 and any future kit migrations.
+
+---
+
+## Alternatives Considered
+
+### Keep the "General Capability Skill Tier" as a Peer Category
+
+Rejected. The general capability tier was never designed — it accreted. Treating it as a first-class category alongside Kit-skills would institutionalize an accident. The model is simpler with exactly one kind of skill.
+
+### Allow Skills to Be Defined Without Flow Binding
+
+Rejected. The whole value of the model is that a skill's purpose, ownership, and location are derivable from its flow step. A skill with no flow binding is undefined in the model — it either needs a flow or needs to be reclassified.
+
+### Cross-Kit Skill Sharing via npm Dependency (DEFERRED)
+
+Not rejected but not adopted now. The npm-dependency model for cross-kit sharing is the most likely future path if skills need to be consumed across kits. It is deferred until a concrete cross-kit case requires it. See "Cross-Kit Skill Sharing: DEFERRED" above.
+
+### Move All Tool-like Skills to Agent System Prompts Immediately
+
+Deferred. The tool-like skills in `skills/` have runtime users. Moving them without updating agent specs and evals would break existing behavior. This ADR records the intended direction; the migrations should be sequenced through backlog issues.
+
+---
+
+## References
+
+- [ADR 0001: Flow Agents Consumes Flow For Workflow Enforcement](./0001-flow-agents-consumes-flow.md) — establishes that Flow owns Flow Definitions and Flow Agents consumes them.
+- [ADR 0002: Flow Kits as Extension Unit](./0002-flow-kits-as-extension-unit.md) — establishes the kit as the packaging unit.
+- [ADR 0003: Flow Agents Coordinates Kits and Adapters](./0003-flow-agents-coordinates-kits-and-adapters.md) — establishes how Flow Agents relates to kits.
+- [docs/adr/0007-skill-audit.md](./0007-skill-audit.md) — companion skill audit table.
+- `kits/builder/flows/build.flow.json` — Builder Kit build flow step IDs.
+- `kits/builder/flows/shape.flow.json` — Builder Kit shape flow step IDs.
+- `kits/knowledge/flows/ingest.flow.json` — Knowledge Kit ingest flow step IDs.
+- GitHub issue #62 — Builder Kit skill placement fix (becomes mechanical given this model).
+- GitHub issues #52 and #60 — agentless gate-eval work proving Flow Definitions are agentless-capable.