create-bk-agent 0.16.1 → 0.17.0

package/README.md

@@ -1,54 +1,118 @@
 # create-bk-agent
 
-Scaffold a new [BackendKit agent](https://github.com/BackendKit-labs/backendkit-agent-framework) project in seconds.
+Scaffold a new [BackendKit agent](https://github.com/BackendKit-labs/backendkit-agent-framework) project in seconds — or add capabilities to an existing one.
 
-## Usage
+## Create a project
 
 ```bash
 npx create-bk-agent my-project
 ```
 
+The CLI asks three questions and generates a production-ready project:
+
 ```
-✨  create-bk-agent  v0.14.0
+✨  create-bk-agent  v0.17.0
 
-? Project name:  my-project
-? Template:      coding — Coding assistant (files, git, code execution)
-? LLM provider:  Anthropic (Claude)
+? Project name:          my-project
+? Architecture:          Multi-agent (orchestrator + specialists)
+? Skill packs:           Node.js / TypeScript
+? How will it be used?   MCP Server (HTTP)
 
-Creating coding agent in ./my-project...
+Creating Multi-agent — MCP Server (HTTP) agent in ./my-project...
 Installing dependencies...
 
-✅  Done!
+✅  Done! Your agent is ready.
+
    cd my-project
-   cp .env.example .env
-   npm run dev
+   cp .env.example .env      # add your API key
+   npm run server            # starts HTTP MCP on port 3001
 ```
 
-## Templates
+## Architectures
+
+| Architecture | What it gives you | Best for |
+|---|---|---|
+| `multi-agent` | Orchestrator + specialists with delegation | Domain agents (DevOps, finance, data, etc.) |
+| `single` | One agent with a tool registry | Simple task automation |
+| `coding` | 10 pre-built agents + all coding tools | Coding assistants, ready out of the box |
+| `autonomous` | Trigger system (cron / webhook / event) | Scheduled or event-driven daemons |
+| `minimal` | Bare engine, no entry point | Library embedding |
 
-### `coding` — complete, ready to run
-10 specialized agents (backend, frontend, QA, security, architecture…) and all
-coding tools (read/write files, run commands, git, search) are already configured.
-Add your API key, describe your project in `AGENT.md`, and it works out of the box.
-**Choose this when you want a coding assistant, not when you want to build one.**
+## Deploy modes
 
-### `domain-agent` — blank multi-agent architecture
-Orchestrator + specialists pattern with no pre-built agents or tools. You define
-the agents and tools for your specific domain (Docker, AWS, databases, APIs, etc.).
-The framework handles orchestration, delegation, and parallel execution.
-**Choose this when you are building a new type of agent from scratch.**
+Available for `multi-agent` and `single` architectures:
 
-| Template | What it gives you | You provide |
-|----------|------------------|-------------|
-| `coding` | 10 agents + all coding tools | API key + `AGENT.md` |
-| `domain-agent` | Orchestration skeleton | Agents + tools for your domain |
-| `autonomous` | Trigger system (cron / webhook / event) | Agent logic |
-| `mcp-server` | MCP server boilerplate | Tools to expose |
-| `minimal` | Bare engine | Everything |
+| Mode | Entry point | Use case |
+|---|---|---|
+| `repl` | `src/index.ts` — readline loop | Local terminal tool |
+| `mcp-http` | `src/server.ts` — HTTP MCP server | Connect to Claude Desktop, Cursor, etc. |
+| `mcp-stdio` | `src/server.ts` — stdio MCP server | Subprocess / pipe-based MCP |
+| `hybrid` | Both `index.ts` + `server.ts` | REPL for dev, server for production |
+| `library` | Only `src/engine.ts` exported | Import the engine in your own app |
 
 ## Providers
 
-Supports Anthropic (Claude), OpenAI, DeepSeek / OpenAI-compatible endpoints, and Ollama (local).
+Anthropic (Claude), OpenAI, DeepSeek / any OpenAI-compatible endpoint, and Ollama (local).
+
+---
+
+## Add capabilities to an existing project
+
+Once a project is created, use `add` to extend it without editing code manually:
+
+```bash
+npx create-bk-agent add <module> [options]
+```
+
+### `add server` — expose the agent as an HTTP MCP server
+
+```bash
+npx create-bk-agent add server
+npx create-bk-agent add server --port 4000 --name my-agent
+```
+
+- Generates `src/server.ts` wired to the existing engine
+- Adds `@backendkit-labs/mcp-server` to `dependencies`
+- Adds `"server"` script to `package.json`
+
+### `add specialist <name>` — add a specialist agent (multi-agent projects)
+
+```bash
+npx create-bk-agent add specialist data-analyst
+npx create-bk-agent add specialist git-expert
+```
+
+- Creates `src/agents/<name>.ts` with an `AgentProfile` stub
+- Patches `src/engine.ts`: adds the import and `agents.register()`
+
+### `add tools <domain>` — add a tool file for a new domain
+
+```bash
+npx create-bk-agent add tools github
+npx create-bk-agent add tools my-database
+```
+
+- Creates `src/tools/<domain>-tools.ts` with two stub tools (action + query)
+- Patches `src/engine.ts`: adds the import and `tools.register()`
+
+### `add mcp-client <url>` — connect to a remote MCP server
+
+```bash
+npx create-bk-agent add mcp-client http://localhost:3001/mcp
+npx create-bk-agent add mcp-client http://billing-agent/mcp --name billing
+```
+
+- Patches `src/engine.ts`: adds the entry to `mcpServers: [...]` inside `AgentEngine`
+- Creates the `mcpServers` array if it doesn't exist yet
+
+All `add` commands are **idempotent** — running the same command twice won't duplicate entries.
+
+---
+
+## Requirements
+
+- Node.js >= 20
+- An API key for your chosen provider (Anthropic, OpenAI, DeepSeek, or Ollama)
 
 ## License
 

package/dist/src/add/detector.js

@@ -0,0 +1,80 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectProject = detectProject;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function detectProject(cwd) {
+    const pkgFile = path.join(cwd, 'package.json');
+    if (!fs.existsSync(pkgFile))
+        return null;
+    let pkg;
+    try {
+        pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    const deps = {
+        ...(pkg.dependencies ?? {}),
+        ...(pkg.devDependencies ?? {}),
+    };
+    if (!deps['@backendkit-labs/agent-core'])
+        return null;
+    const engineFile = path.join(cwd, 'src', 'engine.ts');
+    let architecture = 'unknown';
+    let engineFnName = 'createEngine';
+    if (fs.existsSync(engineFile)) {
+        const content = fs.readFileSync(engineFile, 'utf-8');
+        if (content.includes('ORCHESTRATOR_PROFILE') || content.includes("id: 'orchestrator'")) {
+            architecture = 'multi-agent';
+        }
+        else if (content.includes('export function create')) {
+            architecture = 'single';
+        }
+        const match = content.match(/export function (\w+)\s*\(/);
+        if (match)
+            engineFnName = match[1];
+    }
+    return {
+        cwd,
+        architecture,
+        engineFile,
+        indexFile: path.join(cwd, 'src', 'index.ts'),
+        serverFile: path.join(cwd, 'src', 'server.ts'),
+        pkgFile,
+        engineFnName,
+    };
+}

package/dist/src/add/index.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAdd = runAdd;
+const detector_1 = require("./detector");
+const server_1 = require("./modules/server");
+const specialist_1 = require("./modules/specialist");
+const tools_1 = require("./modules/tools");
+const mcp_client_1 = require("./modules/mcp-client");
+const HELP = `
+Usage: npx create-bk-agent add <module> [options]
+
+Modules:
+  server                Add an HTTP MCP server (src/server.ts)
+    --port <n>            Port to listen on  (default: 3001)
+    --name <s>            MCP server name    (default: project directory name)
+
+  specialist <name>     Add a new specialist agent to a multi-agent project
+                        (creates src/agents/<name>.ts and patches engine.ts)
+
+  tools <domain>        Add a tool file for a new domain
+                        (creates src/tools/<domain>-tools.ts and patches engine.ts)
+
+  mcp-client <url>      Add a remote MCP server to the engine
+    --name <s>            Name for the mcpServers entry (default: last URL segment)
+
+Examples:
+  npx create-bk-agent add server --port 4000
+  npx create-bk-agent add specialist data-analyst
+  npx create-bk-agent add tools github
+  npx create-bk-agent add mcp-client http://localhost:3001/mcp --name billing
+`;
+function runAdd(args, cwd) {
+    const [module, ...rest] = args;
+    if (!module || module === '--help' || module === '-h') {
+        console.log(HELP);
+        process.exit(0);
+    }
+    const info = (0, detector_1.detectProject)(cwd);
+    if (!info) {
+        console.error('\n✗  No bk-agent project detected in the current directory.\n' +
+            '   Make sure you are inside a project created with npx create-bk-agent.\n');
+        process.exit(1);
+    }
+    switch (module) {
+        case 'server':
+            (0, server_1.addServer)(info, rest);
+            break;
+        case 'specialist':
+            if (info.architecture !== 'multi-agent') {
+                console.error(`\n⚠  "add specialist" is designed for multi-agent projects.\n` +
+                    `   Detected architecture: ${info.architecture}.\n` +
+                    `   Proceeding anyway — verify engine.ts manually.\n`);
+            }
+            (0, specialist_1.addSpecialist)(info, rest);
+            break;
+        case 'tools':
+            (0, tools_1.addTools)(info, rest);
+            break;
+        case 'mcp-client':
+            (0, mcp_client_1.addMcpClient)(info, rest);
+            break;
+        default:
+            console.error(`\n✗  Unknown module: "${module}"\n`);
+            console.log(HELP);
+            process.exit(1);
+    }
+}

package/dist/src/add/modules/mcp-client.js

@@ -0,0 +1,65 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addMcpClient = addMcpClient;
+const fs = __importStar(require("fs"));
+const patcher_1 = require("../patcher");
+function addMcpClient(info, args) {
+    const url = args[0];
+    if (!url) {
+        console.error('\n✗  Usage: add mcp-client <url> [--name <name>]\n');
+        process.exit(1);
+    }
+    let name = url.split('/').filter(Boolean).pop() ?? 'remote-agent';
+    for (let i = 1; i < args.length; i++) {
+        if (args[i] === '--name' && args[i + 1]) {
+            name = args[++i];
+            break;
+        }
+    }
+    if (!fs.existsSync(info.engineFile)) {
+        console.error('\n✗  src/engine.ts not found.\n');
+        process.exit(1);
+    }
+    const ok = (0, patcher_1.addMcpServerEntry)(info.engineFile, name, url);
+    if (ok) {
+        console.log(`\n✓  Patched src/engine.ts  (mcpServers: { name: '${name}', url: '${url}' })`);
+        console.log(`\nNext steps:\n   npm run dev\n`);
+    }
+    else {
+        console.error('\n✗  Could not locate AgentEngine constructor to inject mcpServers.\n');
+        process.exit(1);
+    }
+}

package/dist/src/add/modules/server.js

@@ -0,0 +1,100 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addServer = addServer;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const patcher_1 = require("../patcher");
+function parseArgs(args, defaultName) {
+    let port = 3001;
+    let name = defaultName;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--port' && args[i + 1])
+            port = parseInt(args[++i]);
+        if (args[i] === '--name' && args[i + 1])
+            name = args[++i];
+    }
+    return { port, name };
+}
+function generateServerTs(info, opts) {
+    return `import 'dotenv/config';
+import { AgentMCPServer } from '@backendkit-labs/mcp-server';
+import { CallbackTransport } from '@backendkit-labs/agent-core';
+import { z } from 'zod';
+import { ${info.engineFnName} } from './engine';
+
+const server = new AgentMCPServer({
+    name:    '${opts.name}',
+    version: '1.0.0',
+    port:    parseInt(process.env.MCP_PORT ?? '${opts.port}'),
+
+    tools: [
+        {
+            name:        'agent_request',
+            description: 'TODO: describe what requests this agent handles',
+            schema: {
+                request: z.string().describe('Natural-language request for the agent'),
+            },
+            buildPrompt: ({ request }: { request: string }) => request,
+        },
+    ],
+
+    engineFactory: (transport: CallbackTransport) => ${info.engineFnName}(transport),
+});
+
+await server.start();
+`;
+}
+function addServer(info, args) {
+    const opts = parseArgs(args, path.basename(info.cwd));
+    if (fs.existsSync(info.serverFile)) {
+        console.error(`\n✗  src/server.ts already exists. Remove it first to regenerate.\n`);
+        process.exit(1);
+    }
+    fs.writeFileSync(info.serverFile, generateServerTs(info, opts));
+    console.log(`\n✓  Created src/server.ts  (HTTP MCP on port ${opts.port})`);
+    const added = (0, patcher_1.addPackageDependency)(info.pkgFile, '@backendkit-labs/mcp-server', '^0.16.0');
+    (0, patcher_1.addPackageDependency)(info.pkgFile, 'zod', '^3.25.0');
+    (0, patcher_1.addPackageScript)(info.pkgFile, 'server', 'ts-node src/server.ts');
+    if (added) {
+        console.log(`✓  package.json  (@backendkit-labs/mcp-server added)`);
+    }
+    console.log(`✓  package.json  (script "server" added)`);
+    console.log(`
+Next steps:
+   npm install
+   npm run server        # starts HTTP MCP on port ${opts.port}
+`);
+}

package/dist/src/add/modules/specialist.js

@@ -0,0 +1,98 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addSpecialist = addSpecialist;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const patcher_1 = require("../patcher");
+function toConstName(name) {
+    return name.replace(/-/g, '_').toUpperCase() + '_PROFILE';
+}
+function toDisplayName(name) {
+    return name.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+}
+function generateSpecialistTs(name) {
+    const constName = toConstName(name);
+    return `import type { AgentProfile } from '@backendkit-labs/agent-core';
+
+// TODO: Rename this file and export to match your domain
+export const ${constName}: AgentProfile = {
+    id: '${name}',
+    name: '${toDisplayName(name)}',
+    icon: '🔧',
+    description: 'TODO: describe what this specialist does',
+    delegatesTo: [],
+    allowedTools: [
+        // TODO: list the tool names this agent can use
+    ],
+    systemPrompt: \`You are a specialist in TODO: <your domain area>.
+
+Use the available tools to complete the task delegated to you.
+Be precise and report results clearly.\`,
+};
+`;
+}
+function addSpecialist(info, args) {
+    const name = args[0];
+    if (!name) {
+        console.error('\n✗  Usage: add specialist <name>\n');
+        process.exit(1);
+    }
+    const agentFile = path.join(info.cwd, 'src', 'agents', `${name}.ts`);
+    if (fs.existsSync(agentFile)) {
+        console.error(`\n✗  src/agents/${name}.ts already exists.\n`);
+        process.exit(1);
+    }
+    fs.writeFileSync(agentFile, generateSpecialistTs(name));
+    console.log(`\n✓  Created src/agents/${name}.ts`);
+    if (fs.existsSync(info.engineFile)) {
+        const constName = toConstName(name);
+        (0, patcher_1.addImportLine)(info.engineFile, `import { ${constName} } from './agents/${name}';`);
+        // Primary: insert after TODO comment; fallback: after last .register( call
+        const inserted = (0, patcher_1.insertAfterPattern)(info.engineFile, /\/\/ TODO: register more specialists/, `    agents.register(${constName});`) ||
+            (0, patcher_1.insertAfterPattern)(info.engineFile, /agents\.register\(/, `    agents.register(${constName});`);
+        if (inserted) {
+            console.log(`✓  Patched src/engine.ts  (agents.register(${constName}))`);
+        }
+        else {
+            console.log(`⚠  Could not auto-patch engine.ts — add manually: agents.register(${constName})`);
+        }
+        const orchestratorFile = path.join(info.cwd, 'src', 'agents', 'orchestrator.ts');
+        if (fs.existsSync(orchestratorFile)) {
+            console.log(`\n  Reminder: add '${name}' to orchestrator.ts delegatesTo[] and update the systemPrompt.`);
+        }
+    }
+    console.log(`\nNext steps:\n   Implement src/agents/${name}.ts\n   npm run dev\n`);
+}

package/dist/src/add/modules/tools.js

@@ -0,0 +1,102 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addTools = addTools;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const patcher_1 = require("../patcher");
+function toCamelCase(name) {
+    return name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+function generateToolsTs(domain) {
+    const fn = toCamelCase(domain);
+    return `import { defineTool, z } from '@backendkit-labs/agent-core';
+
+// TODO: replace with real ${domain} SDK/API calls
+
+export const ${fn}Action = defineTool({
+    name: '${domain}_action',
+    description: 'TODO: describe what this tool does',
+    input: z.object({
+        target: z.string().describe('Target to act on'),
+        // TODO: add more parameters
+    }),
+    execute: async ({ target }) => {
+        // TODO: implement
+        return \`${domain} action on: \${target}\`;
+    },
+});
+
+export const ${fn}Query = defineTool({
+    name: '${domain}_query',
+    description: 'TODO: describe what this query returns',
+    input: z.object({
+        filter: z.string().optional().describe('Optional filter'),
+    }),
+    execute: async ({ filter }) => {
+        // TODO: implement
+        return JSON.stringify({ results: [], filter });
+    },
+});
+`;
+}
+function addTools(info, args) {
+    const domain = args[0];
+    if (!domain) {
+        console.error('\n✗  Usage: add tools <domain>\n');
+        process.exit(1);
+    }
+    const toolsFile = path.join(info.cwd, 'src', 'tools', `${domain}-tools.ts`);
+    if (fs.existsSync(toolsFile)) {
+        console.error(`\n✗  src/tools/${domain}-tools.ts already exists.\n`);
+        process.exit(1);
+    }
+    fs.mkdirSync(path.dirname(toolsFile), { recursive: true });
+    fs.writeFileSync(toolsFile, generateToolsTs(domain));
+    console.log(`\n✓  Created src/tools/${domain}-tools.ts`);
+    if (fs.existsSync(info.engineFile)) {
+        const fn = toCamelCase(domain);
+        (0, patcher_1.addImportLine)(info.engineFile, `import { ${fn}Action, ${fn}Query } from './tools/${domain}-tools';`);
+        const inserted = (0, patcher_1.insertAfterPattern)(info.engineFile, /\/\/ TODO: register more tools/, `    tools.register(${fn}Action).register(${fn}Query);`) ||
+            (0, patcher_1.insertAfterPattern)(info.engineFile, /tools\.register\(/, `    tools.register(${fn}Action).register(${fn}Query);`);
+        if (inserted) {
+            console.log(`✓  Patched src/engine.ts  (tools.register(${fn}Action, ${fn}Query))`);
+        }
+        else {
+            console.log(`⚠  Could not auto-patch engine.ts — add manually: tools.register(${fn}Action).register(${fn}Query)`);
+        }
+    }
+    console.log(`\nNext steps:\n   Implement src/tools/${domain}-tools.ts\n   npm run dev\n`);
+}

package/dist/src/add/patcher.js

@@ -0,0 +1,168 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addImportLine = addImportLine;
+exports.insertAfterPattern = insertAfterPattern;
+exports.insertBeforePattern = insertBeforePattern;
+exports.addPackageScript = addPackageScript;
+exports.addPackageDependency = addPackageDependency;
+exports.addMcpServerEntry = addMcpServerEntry;
+const fs = __importStar(require("fs"));
+// ── Import block ──────────────────────────────────────────────────────────────
+/** Adds `importLine` after the last import statement. No-op if already present. */
+function addImportLine(file, importLine) {
+    const content = fs.readFileSync(file, 'utf-8');
+    if (content.includes(importLine.trim()))
+        return;
+    const lines = content.split('\n');
+    let lastImportIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (/^import\s/.test(lines[i]))
+            lastImportIdx = i;
+    }
+    if (lastImportIdx === -1) {
+        fs.writeFileSync(file, importLine + '\n' + content);
+    }
+    else {
+        lines.splice(lastImportIdx + 1, 0, importLine);
+        fs.writeFileSync(file, lines.join('\n'));
+    }
+}
+// ── Line insertion ────────────────────────────────────────────────────────────
+/**
+ * Inserts `newLine` after the LAST line that matches `pattern`.
+ * Returns true if the insertion was done, false if the pattern wasn't found.
+ * No-op if `newLine` (trimmed) already exists in the file.
+ */
+function insertAfterPattern(file, pattern, newLine) {
+    const content = fs.readFileSync(file, 'utf-8');
+    if (content.includes(newLine.trim()))
+        return true;
+    const lines = content.split('\n');
+    let lastIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (pattern.test(lines[i]))
+            lastIdx = i;
+    }
+    if (lastIdx === -1)
+        return false;
+    lines.splice(lastIdx + 1, 0, newLine);
+    fs.writeFileSync(file, lines.join('\n'));
+    return true;
+}
+/**
+ * Inserts `newLine` before the FIRST line that matches `pattern`.
+ * Returns true if the insertion was done, false if the pattern wasn't found.
+ * No-op if `newLine` (trimmed) already exists in the file.
+ */
+function insertBeforePattern(file, pattern, newLine) {
+    const content = fs.readFileSync(file, 'utf-8');
+    if (content.includes(newLine.trim()))
+        return true;
+    const lines = content.split('\n');
+    let firstIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (pattern.test(lines[i])) {
+            firstIdx = i;
+            break;
+        }
+    }
+    if (firstIdx === -1)
+        return false;
+    lines.splice(firstIdx, 0, newLine);
+    fs.writeFileSync(file, lines.join('\n'));
+    return true;
+}
+// ── package.json helpers ──────────────────────────────────────────────────────
+function addPackageScript(pkgFile, name, cmd) {
+    const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf-8'));
+    pkg.scripts ??= {};
+    pkg.scripts[name] = cmd;
+    fs.writeFileSync(pkgFile, JSON.stringify(pkg, null, 2) + '\n');
+}
+/** Adds `depName@version` to dependencies if not already present. */
+function addPackageDependency(pkgFile, depName, version) {
+    const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf-8'));
+    pkg.dependencies ??= {};
+    if (pkg.dependencies[depName])
+        return false;
+    pkg.dependencies[depName] = version;
+    fs.writeFileSync(pkgFile, JSON.stringify(pkg, null, 2) + '\n');
+    return true;
+}
+// ── AgentEngine options patcher ───────────────────────────────────────────────
+/**
+ * Adds `mcpServers: [{ name, url }]` to the first AgentEngine constructor call.
+ * If mcpServers already exists, appends a new entry to the existing array.
+ * Returns true on success.
+ */
+function addMcpServerEntry(file, name, url) {
+    const content = fs.readFileSync(file, 'utf-8');
+    const entry = `        { name: '${name}', url: '${url}' },`;
+    if (content.includes(`url: '${url}'`))
+        return true; // already registered
+    if (content.includes('mcpServers:')) {
+        // Append into existing array — insert after 'mcpServers: ['
+        const updated = content.replace(/(mcpServers:\s*\[)/, `$1\n${entry}`);
+        if (updated === content)
+            return false;
+        fs.writeFileSync(file, updated);
+        return true;
+    }
+    // Insert new mcpServers block before the closing of AgentEngine({ ... })
+    const lines = content.split('\n');
+    let depth = 0;
+    let engineStart = -1;
+    let closeIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].includes('new AgentEngine({')) {
+            engineStart = i;
+            depth = 0;
+        }
+        if (engineStart !== -1) {
+            depth += (lines[i].match(/\{/g) ?? []).length;
+            depth -= (lines[i].match(/\}/g) ?? []).length;
+            if (depth === 0 && i > engineStart) {
+                closeIdx = i;
+                break;
+            }
+        }
+    }
+    if (closeIdx === -1)
+        return false;
+    lines.splice(closeIdx, 0, `        mcpServers: [\n${entry}\n        ],`);
+    fs.writeFileSync(file, lines.join('\n'));
+    return true;
+}

package/dist/src/index.js

@@ -38,6 +38,7 @@ const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const prompts_1 = require("./prompts");
 const scaffold_1 = require("./scaffold");
+const index_1 = require("./add/index");
 // Read version from package.json so it always matches the published version
 const FRAMEWORK_VERSION = (() => {
     try {
@@ -48,14 +49,59 @@ const FRAMEWORK_VERSION = (() => {
         return '0.16.0';
     }
 })();
-const NEXT_STEPS = {
-    coding: ['Edit AGENT.md to describe your project', 'npm run dev'],
-    'domain-agent': ['Rename agents/ and tools/ to match your domain', 'Implement tools in src/tools/', 'npm run dev'],
-    autonomous: ['Configure triggers in src/index.ts', 'npm run dev (or npm start in production)'],
-    'mcp-server': ['Register tools in src/server.ts', 'npm run build && npx my-mcp-server'],
-    minimal: ['Implement your LLMProvider in src/index.ts', 'npm run dev'],
-};
+// ── Human-readable label for the scaffold banner ──────────────────────────────
+function describeChoices(choices) {
+    const arch = {
+        'multi-agent': 'Multi-agent',
+        single: 'Single-agent',
+        coding: 'Coding assistant',
+        autonomous: 'Autonomous daemon',
+        minimal: 'Minimal / embedded',
+    };
+    const deploy = {
+        repl: 'Terminal REPL',
+        'mcp-http': 'MCP Server (HTTP)',
+        'mcp-stdio': 'MCP Server (stdio)',
+        hybrid: 'REPL + MCP Server',
+        library: 'Library',
+    };
+    const archLabel = arch[choices.architecture] ?? choices.architecture;
+    if (!choices.deployMode)
+        return archLabel;
+    return `${archLabel} — ${deploy[choices.deployMode] ?? choices.deployMode}`;
+}
+// ── Next steps after scaffold ─────────────────────────────────────────────────
+function buildNextSteps(choices) {
+    const { architecture: arch, deployMode: mode } = choices;
+    // Self-contained architectures
+    if (arch === 'coding')
+        return ['Edit AGENT.md to describe your project', 'npm run dev'];
+    if (arch === 'autonomous')
+        return ['Configure triggers in src/index.ts', 'npm run dev'];
+    if (arch === 'minimal')
+        return ['Implement your LLM provider in src/index.ts', 'npm run dev'];
+    // Layered architectures (multi-agent, single) — vary by deploy mode
+    const domainSteps = arch === 'multi-agent'
+        ? ['Rename agents/ and tools/ to match your domain', 'Implement tools in src/tools/']
+        : ['Implement tools in src/tools/'];
+    if (mode === 'repl')
+        return [...domainSteps, 'npm run dev'];
+    if (mode === 'mcp-http')
+        return [...domainSteps, 'npm run server   # starts HTTP MCP on port 3001'];
+    if (mode === 'mcp-stdio')
+        return [...domainSteps, 'npm run build', 'node dist/server.js'];
+    if (mode === 'hybrid')
+        return [...domainSteps, 'npm run dev', '# in another terminal:', 'npm run server'];
+    if (mode === 'library')
+        return [...domainSteps, '# import { createEngine } from \'./src/engine\' in your app'];
+    return ['npm run dev'];
+}
+// ── Main ──────────────────────────────────────────────────────────────────────
 async function main(argv) {
+    if (argv[2] === 'add') {
+        (0, index_1.runAdd)(argv.slice(3), process.cwd());
+        return;
+    }
     const projectArg = argv[2];
     console.log(`\n✨  create-bk-agent  v${FRAMEWORK_VERSION}\n`);
     const defaultName = projectArg ?? 'my-agent';
@@ -69,7 +115,7 @@ async function main(argv) {
         console.error(`\n✗  Directory already exists: ${targetDir}`);
         process.exit(1);
     }
-    console.log(`\nCreating ${choices.template} agent in ./${choices.projectName} ...`);
+    console.log(`\nCreating ${describeChoices(choices)} agent in ./${choices.projectName} ...`);
     try {
         (0, scaffold_1.scaffold)(choices, targetDir);
     }
@@ -79,7 +125,7 @@ async function main(argv) {
     }
     console.log('Installing dependencies...\n');
     (0, scaffold_1.installDeps)(targetDir);
-    const steps = NEXT_STEPS[choices.template] ?? ['npm run dev'];
+    const steps = buildNextSteps(choices);
     console.log(`
 ✅  Done! Your agent is ready.
 

package/dist/src/prompts.js

@@ -5,21 +5,81 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.askQuestions = askQuestions;
 const prompts_1 = __importDefault(require("prompts"));
-const TEMPLATES = [
-    { title: 'coding', value: 'coding', description: '10 agents + all coding tools included. Ready to run — improve UI and extend' },
-    { title: 'domain-agent', value: 'domain-agent', description: 'Blank multi-agent architecture. You define agents and tools for your domain' },
-    { title: 'autonomous', value: 'autonomous', description: 'Event-driven agent — cron schedules, webhooks, custom events' },
-    { title: 'mcp-server', value: 'mcp-server', description: 'MCP server — expose your tools to Claude Desktop / Cursor / VS Code' },
-    { title: 'minimal', value: 'minimal', description: 'Bare engine — full control, bring your own agents and tools' },
+// ── Option definitions ────────────────────────────────────────────────────────
+const p = (s, n) => s.padEnd(n);
+const ARCHITECTURE_CHOICES = [
+    {
+        title: p('Multi-agent', 22) + 'Orchestrator delegates to specialized sub-agents',
+        value: 'multi-agent',
+        description: 'Best for complex domains (git: commit / branch / merge / recovery)',
+    },
+    {
+        title: p('Single agent', 22) + 'One agent handles all requests with tools',
+        value: 'single',
+        description: 'Best for focused single-domain tasks and quick prototypes',
+    },
+    {
+        title: p('Coding assistant', 22) + '10 pre-built agents for software dev — ready to run',
+        value: 'coding',
+        description: 'Just add your API key and run',
+    },
+    {
+        title: p('Autonomous daemon', 22) + 'Cron / webhook triggers, no human input',
+        value: 'autonomous',
+        description: 'Best for background monitoring, alerts, automated reports',
+    },
+    {
+        title: p('Minimal / embedded', 22) + 'Bare engine factory, full control',
+        value: 'minimal',
+        description: 'Best for embedding in an existing app or custom architecture',
+    },
 ];
-const PROVIDERS = [
-    { title: 'Anthropic (Claude)', value: 'anthropic', description: 'claude-sonnet-4-6 recommended' },
-    { title: 'OpenAI', value: 'openai', description: 'gpt-4o recommended' },
-    { title: 'DeepSeek / OpenAI-compatible', value: 'deepseek', description: 'deepseek-chat or any OpenAI-compatible endpoint' },
-    { title: 'Ollama (local)', value: 'ollama', description: 'llama3.2, codellama, qwen2.5 — no API key needed' },
+const SKILL_PACK_CHOICES = [
+    { title: p('Node.js / TypeScript', 24) + 'npm, jest, tsc, eslint', value: 'node' },
+    { title: p('Python', 24) + 'pytest, ruff, mypy, pip', value: 'python' },
+    { title: p('Go', 24) + 'go test, golangci-lint', value: 'go' },
+    { title: p('Docker / K8s', 24) + 'docker, kubectl, helm', value: 'docker' },
 ];
+const DEPLOY_MODE_CHOICES = [
+    {
+        title: p('Terminal REPL', 28) + 'Humans type requests, agent responds in the terminal',
+        value: 'repl',
+    },
+    {
+        title: p('MCP Server — HTTP', 28) + 'Other agents / tools connect via HTTP protocol',
+        value: 'mcp-http',
+        description: 'e.g. git-agent server that another bk-agent connects to',
+    },
+    {
+        title: p('MCP Server — stdio', 28) + 'Claude Desktop / Cursor / VS Code integration',
+        value: 'mcp-stdio',
+    },
+    {
+        title: p('REPL + MCP Server', 28) + 'Hybrid — humans use it AND other agents connect',
+        value: 'hybrid',
+    },
+    {
+        title: p('Library only', 28) + 'No entry point — imported programmatically',
+        value: 'library',
+    },
+];
+const PROVIDER_CHOICES = [
+    { title: p('Anthropic (Claude)', 32) + 'claude-sonnet-4-6 recommended', value: 'anthropic' },
+    { title: p('OpenAI', 32) + 'gpt-4o recommended', value: 'openai' },
+    { title: p('DeepSeek / OpenAI-compatible', 32) + 'deepseek-chat or any OpenAI-compatible endpoint', value: 'deepseek' },
+    { title: p('Ollama (local)', 32) + 'llama3.2, codellama — no API key needed', value: 'ollama' },
+];
+// ── Conditional question helpers ──────────────────────────────────────────────
+const NEEDS_SKILLS = ['multi-agent', 'single'];
+const NEEDS_DEPLOY = ['multi-agent', 'single', 'coding'];
+// @types/prompts doesn't fully type the function form of `type` — cast at call site.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const whenSkills = (_prev, v) => NEEDS_SKILLS.includes(v.architecture) ? 'multiselect' : null;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const whenDeploy = (_prev, v) => NEEDS_DEPLOY.includes(v.architecture) ? 'select' : null;
+// ── Main question flow ────────────────────────────────────────────────────────
 async function askQuestions(defaultName) {
-    const answers = await (0, prompts_1.default)([
+    const raw = await (0, prompts_1.default)([
         {
             type: 'text',
             name: 'projectName',
@@ -29,26 +89,43 @@ async function askQuestions(defaultName) {
         },
         {
             type: 'select',
-            name: 'template',
-            message: 'Template:',
-            choices: TEMPLATES.map(t => ({
-                title: t.title.padEnd(14) + ' ' + t.description,
-                value: t.value,
-            })),
+            name: 'architecture',
+            message: 'What type of agent are you building?',
+            choices: ARCHITECTURE_CHOICES,
+            initial: 0,
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        {
+            type: whenSkills,
+            name: 'skillPacks',
+            message: 'Include skill packs?  (space to toggle, enter to confirm)',
+            choices: SKILL_PACK_CHOICES,
+            instructions: false,
+            hint: 'Adds domain-specific instructions to your agents. Can be skipped.',
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        {
+            type: whenDeploy,
+            name: 'deployMode',
+            message: 'How will this agent be used?',
+            choices: DEPLOY_MODE_CHOICES,
             initial: 0,
         },
         {
             type: 'select',
             name: 'provider',
             message: 'LLM provider:',
-            choices: PROVIDERS.map(p => ({
-                title: p.title.padEnd(30) + ' ' + p.description,
-                value: p.value,
-            })),
+            choices: PROVIDER_CHOICES,
             initial: 0,
         },
-    ], { onCancel: () => { return false; } });
-    if (!answers.projectName || !answers.template || !answers.provider)
+    ], { onCancel: () => false });
+    if (!raw.projectName || !raw.architecture || !raw.provider)
         return null;
-    return answers;
+    return {
+        projectName: raw.projectName,
+        architecture: raw.architecture,
+        skillPacks: (raw.skillPacks ?? []),
+        deployMode: (raw.deployMode ?? undefined),
+        provider: raw.provider,
+    };
 }

package/dist/src/scaffold.js

@@ -39,6 +39,11 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
 const TEMPLATES_DIR = path.resolve(__dirname, '../../templates');
+const BASE_DIR = path.join(TEMPLATES_DIR, 'base');
+const DEPLOY_DIR = path.join(TEMPLATES_DIR, 'deploy');
+// Only these architectures use the base + deploy layer pattern.
+// The rest (coding, autonomous, minimal) are self-contained in base/.
+const LAYERED = ['multi-agent', 'single'];
 // ── Provider env var hints ────────────────────────────────────────────────────
 const PROVIDER_ENV = {
     anthropic: { varName: 'ANTHROPIC_API_KEY', placeholder: 'sk-ant-...', model: 'claude-sonnet-4-6' },
@@ -46,54 +51,118 @@ const PROVIDER_ENV = {
     deepseek: { varName: 'LLM_API_KEY', placeholder: 'sk-...', model: 'deepseek-chat' },
     ollama: { varName: 'OLLAMA_BASE_URL', placeholder: 'http://localhost:11434', model: 'llama3.2' },
 };
-// ── Copy template ─────────────────────────────────────────────────────────────
+// ── Copy directory (overlay-safe) ─────────────────────────────────────────────
+// dst may already exist from the base layer — files are overwritten, dirs merged.
 function copyDir(src, dst) {
     fs.mkdirSync(dst, { recursive: true });
     for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
         const srcPath = path.join(src, entry.name);
         const dstPath = path.join(dst, entry.name);
-        if (entry.isDirectory()) {
-            copyDir(srcPath, dstPath);
-        }
-        else {
-            fs.copyFileSync(srcPath, dstPath);
-        }
+        entry.isDirectory() ? copyDir(srcPath, dstPath) : fs.copyFileSync(srcPath, dstPath);
     }
 }
-// ── Substitute project name in package.json ───────────────────────────────────
-function patchPackageJson(dir, projectName) {
+// ── Patch package.json — name + scripts ──────────────────────────────────────
+const DEPLOY_SCRIPTS = {
+    repl: (s) => {
+        delete s['server'];
+    },
+    'mcp-http': (s) => {
+        s['dev'] = 'ts-node src/server.ts';
+        s['start'] = 'node dist/server.js';
+        delete s['server'];
+    },
+    'mcp-stdio': (s) => {
+        s['dev'] = 'ts-node src/server.ts';
+        s['start'] = 'node dist/server.js';
+        delete s['server'];
+    },
+    // hybrid: keep both dev (REPL) and server (MCP) — no changes
+    library: (s) => {
+        delete s['dev'];
+        delete s['server'];
+        delete s['start'];
+    },
+};
+function patchPackageJson(dir, projectName, deployMode) {
     const pkgPath = path.join(dir, 'package.json');
     if (!fs.existsSync(pkgPath))
         return;
     const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
     pkg.name = projectName;
+    if (deployMode && DEPLOY_SCRIPTS[deployMode]) {
+        pkg.scripts ??= {};
+        DEPLOY_SCRIPTS[deployMode](pkg.scripts);
+    }
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
 }
-// ── Write .env with provider preset ──────────────────────────────────────────
+// ── Write .env stub ───────────────────────────────────────────────────────────
 function writeEnv(dir, provider) {
     const envExample = path.join(dir, '.env.example');
     const envFile = path.join(dir, '.env');
-    // Only create .env if .env.example exists and .env doesn't
     if (!fs.existsSync(envExample) || fs.existsSync(envFile))
         return;
     const p = PROVIDER_ENV[provider];
-    const content = `# Generated by create-bk-agent\n${p.varName}=${p.placeholder}\nLLM_PROVIDER=${provider}\nLLM_MODEL=${p.model}\n`;
+    const content = [
+        '# Generated by create-bk-agent',
+        `${p.varName}=${p.placeholder}`,
+        `LLM_PROVIDER=${provider}`,
+        `LLM_MODEL=${p.model}`,
+        ...(provider !== 'anthropic' && provider !== 'ollama'
+            ? ['LLM_BASE_URL=https://api.openai.com/v1']
+            : []),
+        '',
+    ].join('\n');
     fs.writeFileSync(envFile, content);
 }
+// ── Inject skill pack hint into engine.ts ─────────────────────────────────────
+// Appends a clearly marked comment block so the developer knows what to wire.
+// Full YAML-based skill injection is handled by `create-bk-agent add skills`.
+const SKILL_HINTS = {
+    node: 'npm, jest, tsc, eslint — Node.js / TypeScript conventions',
+    python: 'pytest, ruff, mypy, pip — Python conventions',
+    go: 'go test, golangci-lint — Go conventions',
+    docker: 'docker, kubectl, helm — Docker / K8s conventions',
+};
+function injectSkillPack(targetDir, pack) {
+    const engineFile = path.join(targetDir, 'src', 'engine.ts');
+    if (!fs.existsSync(engineFile))
+        return;
+    const block = [
+        '',
+        `// ── Skill pack: ${pack} ──────────────────────────────────────────────────────`,
+        `// ${SKILL_HINTS[pack]}`,
+        `// To activate: add YAML skill files in .backendkit-agent/skills/`,
+        `// and wire SkillLoader + SkillActivator into the engine above.`,
+    ].join('\n');
+    fs.appendFileSync(engineFile, block + '\n');
+}
 // ── Main scaffold ─────────────────────────────────────────────────────────────
 function scaffold(choices, targetDir) {
-    const templateDir = path.join(TEMPLATES_DIR, choices.template);
-    if (!fs.existsSync(templateDir)) {
-        throw new Error(`Template not found: ${choices.template} (looked in ${templateDir})`);
-    }
     if (fs.existsSync(targetDir)) {
         throw new Error(`Directory already exists: ${targetDir}`);
     }
-    // 1. Copy template files
-    copyDir(templateDir, targetDir);
-    // 2. Patch package.json name
-    patchPackageJson(targetDir, choices.projectName);
-    // 3. Write .env stub
+    const isLayered = LAYERED.includes(choices.architecture);
+    // 1. Base layer — always copied
+    const baseDir = path.join(BASE_DIR, choices.architecture);
+    if (!fs.existsSync(baseDir)) {
+        throw new Error(`Base template not found: ${choices.architecture} (in ${baseDir})`);
+    }
+    copyDir(baseDir, targetDir);
+    // 2. Deploy layer — overlaid on top of base (layered architectures only)
+    if (isLayered && choices.deployMode && choices.deployMode !== 'library') {
+        const deployDir = path.join(DEPLOY_DIR, choices.deployMode);
+        if (!fs.existsSync(deployDir)) {
+            throw new Error(`Deploy template not found: ${choices.deployMode} (in ${deployDir})`);
+        }
+        copyDir(deployDir, targetDir);
+    }
+    // 3. Skill packs — appended to engine.ts
+    for (const pack of choices.skillPacks) {
+        injectSkillPack(targetDir, pack);
+    }
+    // 4. Patch package.json (name + deploy-mode script adjustments)
+    patchPackageJson(targetDir, choices.projectName, isLayered ? choices.deployMode : undefined);
+    // 5. .env stub
     writeEnv(targetDir, choices.provider);
 }
 function installDeps(targetDir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bk-agent",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Create a new BackendKit agent project",
   "main": "dist/src/index.js",
   "bin": {