@keel_flow/adopt 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jglasskatz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @keel_flow/adopt
+
+LLM-driven adoption: given a workspace knowledge base and a prompt, emits a typed `ArchitectureMap`, agent stubs, and a rationale string via `emit_architecture` structured tool_use output through the Keel `ModelProvider` abstraction.
+
+Part of the [Keel](https://github.com/jglasskatz/keel) framework.
+
+## Install
+
+```
+npm install @keel_flow/adopt
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import type { KnowledgeBase } from "@keel_flow/core";
+import type { ArchitectureMap } from "@keel_flow/schema";
+import type { ModelProvider } from "@keel_flow/runtime";
+export interface AgentStub {
+    id: string;
+    description: string;
+    context: string;
+    tools: string[];
+}
+export interface AdoptResult {
+    architecture: ArchitectureMap;
+    agents: AgentStub[];
+    rationale: string;
+}
+export declare function adopt({ prompt, kb, provider, }: {
+    prompt: string;
+    kb: KnowledgeBase;
+    provider: ModelProvider;
+}): Promise<AdoptResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGxD,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,eAAe,CAAC;IAC9B,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAyDD,wBAAsB,KAAK,CAAC,EAC1B,MAAM,EACN,EAAE,EACF,QAAQ,GACT,EAAE;IACD,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,aAAa,CAAC;IAClB,QAAQ,EAAE,aAAa,CAAC;CACzB,GAAG,OAAO,CAAC,WAAW,CAAC,CAuDvB"}

package/dist/index.js

@@ -0,0 +1,103 @@
+import { ArchitectureMapSchema } from "@keel_flow/schema";
+import { z } from "zod";
+const AgentStubSchema = z.object({
+    id: z.string(),
+    description: z.string(),
+    context: z.string(),
+    tools: z.array(z.string()),
+});
+const AdoptOutputSchema = z.object({
+    architecture: ArchitectureMapSchema,
+    agents: z.array(AgentStubSchema),
+    rationale: z.string(),
+});
+const adoptToolSchema = {
+    name: "emit_architecture",
+    description: "Emit the architecture map, agent stubs, and rationale for the Keel project",
+    inputSchema: {
+        type: "object",
+        properties: {
+            architecture: {
+                type: "object",
+                description: "The ArchitectureMap matching the Keel schema",
+                properties: {
+                    schemaVersion: { type: "string" },
+                    layers: { type: "array", items: { type: "object" } },
+                    nodes: { type: "array", items: { type: "object" } },
+                    connections: { type: "array", items: { type: "object" } },
+                    contexts: { type: "array", items: { type: "object" } },
+                },
+                required: ["schemaVersion", "layers", "nodes", "connections", "contexts"],
+            },
+            agents: {
+                type: "array",
+                description: "Agent stubs for the project",
+                items: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string" },
+                        description: { type: "string" },
+                        context: { type: "string" },
+                        tools: { type: "array", items: { type: "string" } },
+                    },
+                    required: ["id", "description", "context", "tools"],
+                },
+            },
+            rationale: {
+                type: "string",
+                description: "Why this architecture was chosen",
+            },
+        },
+        required: ["architecture", "agents", "rationale"],
+    },
+};
+export async function adopt({ prompt, kb, provider, }) {
+    const chunks = await kb.retrieve(prompt, 10);
+    const kbContext = chunks.length > 0
+        ? chunks.map((c, i) => `[${i + 1}] (source: ${c.source})\n${c.content}`).join("\n\n")
+        : "No KB documents available.";
+    const systemPrompt = `You are an expert software architect adopting the Keel framework for a new project.
+
+Keel is an opinionated framework for integrating AI into software systems. Every Keel project has:
+- architecture/data.ts: a typed graph of all system nodes (agents, tools, services, datastores)
+- principles/index.ts: a registry of engineering principles checked on every PR
+- A verify gate (keel verify) that runs on every PR as a GitHub Action
+
+Keel architecture conventions:
+- Layers: framework, cli, apps, principles, infra, agents, tools, data, ui
+- Nodes: each has id, label, layer, tech, description, keyFiles, keyFunctionality, principles
+- Connections: from/to node ids, type (uses|calls|reads|http|query|tool-call|grounds-on), label
+- Contexts: bounded contexts grouping related nodes by domain
+
+A real example from the Keel framework itself:
+- Layer "framework" contains @keel_flow/core and @keel_flow/schema
+- Layer "cli" contains @keel_flow/cli
+- Context "framework-core" groups @keel_flow/core and @keel_flow/schema
+- Connections wire @keel_flow/cli → @keel_flow/core via "uses"
+
+You must emit a complete, valid ArchitectureMap using the emit_architecture tool.
+The architecture must be appropriate to the user's domain and informed by their KB content.
+Include at least one thin-slice agent node and at least one tool node.
+Include a "thin-slice" bounded context with the primary agent.`;
+    const userMessage = `Project prompt: ${prompt}
+
+KB context (top-10 chunks):
+${kbContext}
+
+Design a Keel architecture for this project. Emit structured output using the emit_architecture tool.`;
+    const response = await provider.generate({
+        model: provider.defaultModel,
+        system: systemPrompt,
+        messages: [{ role: "user", content: [{ type: "text", text: userMessage }] }],
+        tools: [adoptToolSchema],
+        toolChoice: "any",
+        maxTokens: 4096,
+    });
+    const toolUse = response.content.find((b) => b.type === "tool_use");
+    if (!toolUse || toolUse.type !== "tool_use") {
+        throw new Error("Model did not return structured output via tool_use");
+    }
+    const parsed = AdoptOutputSchema.parse(toolUse.input);
+    return parsed;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@keel_flow/adopt",
+  "version": "0.2.0",
+  "private": false,
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "zod": "^3.23.0",
+    "@keel_flow/core": "0.2.0",
+    "@keel_flow/runtime": "0.2.0",
+    "@keel_flow/schema": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src"
+  }
+}