create-bk-agent 0.21.0 → 0.21.2

package/README.md

@@ -1,210 +1,270 @@
 # create-bk-agent
 
-**Status: stable** — works and is maintained; will not be expanded during the pilot phase.
+CLI scaffolding tool for the BackendKit Labs agent framework. Generates a fully configured TypeScript agent project in seconds — choose your architecture, deployment mode, and LLM provider, and get a working project with all dependencies wired.
 
-Scaffold a new [BackendKit agent](https://github.com/BackendKit-labs/backendkit-agent-framework) project in seconds — or add capabilities to an existing one.
-
-## Create a project
+## Usage
 
 ```bash
-npx create-bk-agent my-project
-```
-
-The CLI asks three questions and generates a production-ready project:
+npm create bk-agent@latest my-agent
+cd my-agent && npm install && npm run dev
 
+# Or with npx:
+npx create-bk-agent my-agent
 ```
-✨  create-bk-agent  v0.20.0
 
-? Project name:          my-project
-? Architecture:          Multi-agent (orchestrator + specialists)
-? Skill packs:           Node.js / TypeScript
-? How will it be used?   MCP Server (HTTP)
+---
 
-Creating Multi-agent — MCP Server (HTTP) agent in ./my-project...
-Installing dependencies...
+## Interactive setup
 
-✅  Done! Your agent is ready.
+The CLI asks three questions:
 
-   cd my-project
-   cp .env.example .env      # add your API key
-   npm run server            # starts HTTP MCP on port 3001
-```
+1. **Architecture** — what kind of agent?
+2. **Deploy mode** — how will it be used?
+3. **Provider** — which LLM API?
+
+---
 
 ## 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 |
+### `multi-agent` — Multi-agent orchestrator
 
-## Deploy modes
+A routing orchestrator that delegates tasks to specialized sub-agents. Best for complex domains with distinct request types.
 
-Available for `multi-agent` and `single` architectures:
+```
+src/
+├── agents/         ← agent profiles (JSON)
+├── tools/          ← typed tool definitions
+├── orchestrator.ts ← routes requests to sub-agents
+└── index.ts
+```
 
-| 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 |
+**Use case:** A customer platform with separate agents for billing, support, and account management.
 
-## Providers
+### `single` — Single-agent assistant
 
-Anthropic (Claude), OpenAI, DeepSeek / any OpenAI-compatible endpoint, and Ollama (local).
+One agent with a custom system prompt and your tools.
 
-## Model configuration
+```
+src/
+├── tools/
+├── agent.ts
+└── index.ts
+```
 
-Generated projects read three env vars for model selection:
+### `coding` — Coding assistant
 
-| Variable | Default | Description |
-|---|---|---|
-| `LLM_MODEL` | `gpt-4o` | Base model — used by all agents unless overridden |
-| `LLM_MODEL_FAST` | `LLM_MODEL` | Execution agents (specialists, tool-calling loops) |
-| `LLM_MODEL_SMART` | `LLM_MODEL` | Routing agents (orchestrator, reasoning-heavy tasks) |
+Pre-configured with 10 coding agents, filesystem tools, persistent memory, and stack detection. Ready to use immediately.
 
-If `LLM_MODEL_FAST` and `LLM_MODEL_SMART` are not set, all agents use `LLM_MODEL` — fully backwards compatible.
+```
+src/
+└── index.ts    ← createCodingEngine() + readline REPL
+AGENT.md        ← project context injected into every LLM call
+```
 
-Example `.env` for DeepSeek with smart/fast split:
+**Use case:** A project-specific coding assistant with your team's conventions in `AGENT.md`.
 
-```env
-LLM_API_KEY=sk-...
-LLM_BASE_URL=https://api.deepseek.com/v1
-LLM_MODEL=deepseek-chat
-LLM_MODEL_FAST=deepseek-chat
-LLM_MODEL_SMART=deepseek-reasoner
-```
+### `autonomous` — Autonomous daemon
 
-The split is wired in `src/engine.ts` — specialists get `llmModelFast`, orchestrator gets `llmModelSmart`. To assign a model directly on a profile instead of via env vars, uncomment the `model:` field in the agent file:
+Runs on a schedule without user interaction. Pre-wired with `createAutonomousAgent` + cron trigger.
 
-```ts
-// src/agents/orchestrator.ts
-export const ORCHESTRATOR_PROFILE: AgentProfile = {
-  id: 'orchestrator',
-  model: 'deepseek-reasoner',  // uncomment and set explicitly
-  ...
-};
+```
+src/
+├── triggers/
+├── tools/
+└── index.ts    ← cron + event loop
 ```
 
----
+**Use case:** Nightly reports, daily standups, automated monitoring.
 
-## Add capabilities to an existing project
+### `minimal` — Minimal / embedded
 
-Once a project is created, use `add` to extend it without editing code manually:
+Bare-bones template — just `AgentEngine`, one tool, one agent. Use when embedding an agent into an existing application or building a library.
 
-```bash
-npx create-bk-agent add <module> [options]
+```
+src/
+└── index.ts    ← AgentEngine, bare minimum
 ```
 
-### `add server` — expose the agent as an HTTP MCP server
+### `enterprise` — Enterprise (local LLM + RAG)
+
+Full enterprise setup: Ollama LLM, Obsidian vault as knowledge base, six department agents (General, Support, HR, Sales, Finance, Ops), VaultWriter, and optionally an `AgentServer` web server.
 
-```bash
-npx create-bk-agent add server
-npx create-bk-agent add server --port 4000 --name my-agent
 ```
+src/
+├── server.ts       ← createEnterpriseSetup() + AgentServer
+└── agents/         ← 6 department profiles
+.env.example        ← VAULT_PATH, JWT_SECRET, PORT, OLLAMA_HOST
+```
+
+---
 
-- Generates `src/server.ts` wired to the existing engine
-- Adds `@backendkit-labs/mcp-server` to `dependencies`
-- Adds `"server"` script to `package.json`
+## Deploy modes
 
-### `add specialist <name>` — add a specialist agent (multi-agent projects)
+| Mode | Description |
+|------|-------------|
+| `repl` | Terminal REPL — stdin/stdout |
+| `mcp-stdio` | MCP server over stdio (for Claude Desktop, agent-core) |
+| `mcp-http` | MCP server over HTTP (`npm run server`) |
+| `hybrid` | REPL + MCP server side-by-side |
+| `library` | Exports an engine factory, no I/O |
+| `web` | Fastify web server — chat + kanban (enterprise only) |
 
-```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()`
+## Provider options
 
-### `add tools <domain>` — add a tool file for a new domain
+| Provider | Required env var |
+|----------|-----------------|
+| DeepSeek | `DEEPSEEK_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| Anthropic | `ANTHROPIC_API_KEY` |
+| Ollama (local) | *(none — requires `ollama serve`)* |
 
-```bash
-npx create-bk-agent add tools github
-npx create-bk-agent add tools my-database
-```
+The scaffolded `.env.example` lists all required variables.
 
-- 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
+## Scaffolded project structure
 
-```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
-```
+### Coding assistant (simplest)
 
-- Patches `src/engine.ts`: adds the entry to `mcpServers: [...]` inside `AgentEngine`
-- Creates the `mcpServers` array if it doesn't exist yet
+```
+my-agent/
+├── src/
+│   └── index.ts      ← createCodingEngine() + readline REPL
+├── AGENT.md          ← project context (edit this!)
+├── package.json
+├── tsconfig.json
+└── .env.example
+```
 
-All `add` commands are **idempotent** — running the same command twice won't duplicate entries.
+**`AGENT.md`** is injected into every LLM call. Describe your project, stack, and conventions:
 
----
+```markdown
+# My Project
 
-## Multi-project workspaces
+## Tech stack
+Node.js 20, TypeScript 5, Express 4, PostgreSQL 15
 
-Group related projects (e.g. microservices) into a workspace so the agent can navigate all of them from a single shared root — no more switching context manually.
+## Conventions
+- All functions must have JSDoc
+- Tests use Jest + Supertest
+- Never use `any` — use `unknown`
 
-### Setup
+## Architecture
+REST API with repository pattern. DB access only via src/repositories/.
+```
 
-Use the built-in `/workspace` slash commands from inside the running agent:
+### Enterprise web server (most complete)
 
 ```
-/workspace create my-system
-/workspace add my-system ~/dev/my-system/auth-service
-/workspace add my-system ~/dev/my-system/api-gateway
-/workspace add my-system ~/dev/my-system/user-service
+my-agent/
+├── src/
+│   ├── server.ts         ← createEnterpriseSetup() + AgentServer
+│   └── agents/           ← 6 department profiles
+├── .env.example          ← VAULT_PATH, OLLAMA_HOST, JWT_SECRET, PORT
+├── package.json          ← agent-enterprise + agent-web
+└── tsconfig.json
 ```
 
-When a second project is added, a **common root** is auto-detected (`~/dev/my-system/`). The next `/workspace switch` sets that directory as the agent's working directory, giving it access to all services at once.
+---
 
-### Commands
+## Examples
 
-| Command | Description |
-|---|---|
-| `/workspace create <name>` | Create a workspace |
-| `/workspace add <ws> <cwd> [name]` | Add a project |
-| `/workspace import <cwd> [ws] [name]` | Add project (auto-creates workspace) |
-| `/workspace switch <ws> [project]` | Switch to workspace (uses shared root if configured) |
-| `/workspace set-root <ws> [path]` | Set shared root manually (auto-detected if no path) |
-| `/workspace remove <ws> <project>` | Remove a project |
-| `/workspace delete <name>` | Delete workspace |
-| `/workspace list` | List all workspaces |
+### Coding assistant
 
-### Shared root (microservices)
+```bash
+npx create-bk-agent my-dev-assistant
+# → coding → repl → deepseek
 
-For a system with multiple services under a common parent:
+cd my-dev-assistant
+cp .env.example .env
+# Edit .env: add DEEPSEEK_API_KEY
 
-```
-~/dev/my-system/          ← shared root (agent workingDir)
-  ├── auth-service/
-  ├── api-gateway/
-  └── user-service/
+# Describe your project
+nano AGENT.md
+
+npm install && npm run dev
+# > What can I help with?
 ```
 
-The agent can read and edit files across all services using relative paths:
+### Enterprise on-premises assistant
 
+```bash
+npx create-bk-agent company-assistant
+# → enterprise → web → ollama
+
+cd company-assistant
+cp .env.example .env
+# Edit .env: VAULT_PATH=/path/to/obsidian-vault
+
+ollama serve
+ollama pull llama3.2
+ollama pull nomic-embed-text
+
+npm install && npm run dev
+# → Indexing vault...
+# → Server running on :4001
+# Chat:    http://localhost:4001/
+# Kanban:  http://localhost:4001/#kanban
 ```
-auth-service/src/middleware.ts
-api-gateway/src/routes/auth.ts
+
+### Autonomous cron agent
+
+```bash
+npx create-bk-agent standup-bot
+# → autonomous → repl → deepseek
+
+cd standup-bot
+# Edit src/triggers/index.ts: schedule, prompt, output
+npm install && npm run dev
 ```
 
-To override the auto-detected root:
+### MCP server exposing your tools
+
+```bash
+npx create-bk-agent my-tools-server
+# → single → mcp-http → openai
 
+cd my-tools-server
+# Add tools to src/tools/
+# Add agent to src/agents/
+npm install && npm run server   # MCP server on :3000
 ```
-/workspace set-root my-system ~/dev/my-system
+
+Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "my-tools": {
+      "command": "npx",
+      "args": ["-y", "my-tools-server"]
+    }
+  }
+}
 ```
 
 ---
 
-## Requirements
+## `bk add` command
+
+After scaffolding, add new components to your project:
+
+```bash
+bk add tool lookup-order      # creates src/tools/lookup-order.ts
+bk add agent billing          # creates src/agents/billing.json
+bk add trigger daily-report   # adds a cron trigger
+```
 
-- Node.js >= 20
-- An API key for your chosen provider (Anthropic, OpenAI, DeepSeek, or Ollama)
+---
 
-## License
+## Scripts in scaffolded projects
 
-MIT © [BackendKit Labs](https://github.com/BackendKit-labs)
+| Script | Description |
+|--------|-------------|
+| `npm run dev` | Development with tsx / ts-node |
+| `npm run build` | Compile TypeScript |
+| `npm run start` | Run compiled output |
+| `npm run server` | Start MCP or web server |
+| `npm run typecheck` | TypeScript type-check only |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bk-agent",
-  "version": "0.21.0",
+  "version": "0.21.2",
   "description": "Create a new BackendKit agent project",
   "main": "dist/src/index.js",
   "bin": {
@@ -22,6 +22,12 @@
     "prepack": "node scripts/copy-templates.js && npm run build",
     "typecheck": "tsc --noEmit"
   },
+  "peerDependencies": {
+    "@backendkit-labs/agent-core": "^0.22.0"
+  },
+  "peerDependenciesMeta": {
+    "@backendkit-labs/agent-core": { "optional": true }
+  },
   "dependencies": {
     "prompts": "^2.4.2"
   },