@backendkit-labs/agent-coding 0.27.2 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,480 +1,496 @@
1
- # @backendkit-labs/agent-coding
2
-
3
- A production-ready coding agent engine built on `@backendkit-labs/agent-core`. Bundles 10 specialized agents, filesystem tools, multi-provider support (DeepSeek, OpenAI, Anthropic, Ollama, Kimi, Grok), automatic stack detection, persistent memory, QA review, reflection, and an orchestration pipeline — all in a single `createCodingEngine()` call.
4
-
5
- [![npm](https://img.shields.io/npm/v/@backendkit-labs/agent-coding)](https://www.npmjs.com/package/@backendkit-labs/agent-coding)
6
-
7
- > **Status: `stable`** — Maintained and production-ready. No new features during the pilot phase.
8
-
9
- ## Table of contents
10
-
11
- - [Installation](#installation)
12
- - [Quick start](#quick-start)
13
- - [createCodingEngine](#createcodingengine)
14
- - [createCodingEngineFromConfig](#createcodingenginefromconfig)
15
- - [Providers](#providers)
16
- - [Built-in agents](#built-in-agents)
17
- - [Built-in tools](#built-in-tools)
18
- - [Skill packs](#skill-packs)
19
- - [Orchestration pipeline](#orchestration-pipeline)
20
- - [Reflection engine](#reflection-engine)
21
- - [MCP server integration](#mcp-server-integration)
22
- - [Multi-agent examples](#multi-agent-examples)
23
- - [Config file](#config-file)
24
-
25
- ---
26
-
27
- ## Installation
28
-
29
- ```bash
30
- npm install @backendkit-labs/agent-coding
31
- ```
32
-
33
- All provider adapters are bundled — no separate packages needed.
34
-
35
- ---
36
-
37
- ## Quick start
38
-
39
- ```typescript
40
- import { createCodingEngine } from '@backendkit-labs/agent-coding';
41
-
42
- const engine = createCodingEngine({
43
- providers: { deepseek: { apiKey: process.env.DEEPSEEK_API_KEY! } },
44
- defaultProvider: 'deepseek',
45
- });
46
-
47
- await engine.run('List all TypeScript files in src/ and tell me which ones have no tests');
48
- ```
49
-
50
- That single call gives you: 10 specialized agents, filesystem tools (read/write/edit/search), persistent project memory, skill loading, and stack auto-detection.
51
-
52
- ---
53
-
54
- ## createCodingEngine
55
-
56
- The primary factory. Returns a fully configured `AgentEngine`.
57
-
58
- ### Options reference
59
-
60
- ```typescript
61
- interface CodingEngineOptions {
62
- // Required
63
- providers: ProvidersConfig;
64
- defaultProvider: string;
65
-
66
- // Agents and engine
67
- defaultAgent?: string; // default: 'general'
68
- workingDir?: string; // default: process.cwd()
69
- maxIterations?: number; // default: 100
70
- maxParallelAgents?: number; // default: 6
71
-
72
- // I/O
73
- transport?: Transport; // default: StdoutTransport
74
-
75
- // App identity
76
- appName?: string; // default: 'bk-agent' — used for ~/.{appName}/
77
-
78
- // Persistence
79
- disablePersistence?: boolean; // skip ProjectStore (useful for testing)
80
-
81
- // MCP servers
82
- mcpServers?: MCPServerConfig[];
83
-
84
- // Context sharing
85
- subAgentContextMessages?: number; // messages visible to sub-agents (recommend 10-20)
86
-
87
- // Iteration control
88
- onToolApproval?: (toolName, agentId, argsPreview) => Promise<ToolApprovalDecision>;
89
- onIterationLimit?: (stats: IterationStats) => Promise<boolean>;
90
- onStep?: (stats: IterationStats) => Promise<boolean>;
91
-
92
- // Orchestration
93
- orchestration?: boolean | OrchestrationOptions;
94
- }
95
- ```
96
-
97
- ### Minimal setup
98
-
99
- ```typescript
100
- const engine = createCodingEngine({
101
- providers: { deepseek: { apiKey: 'sk-...' } },
102
- defaultProvider: 'deepseek',
103
- });
104
- ```
105
-
106
- ### Multiple providers
107
-
108
- ```typescript
109
- const engine = createCodingEngine({
110
- providers: {
111
- deepseek: { apiKey: process.env.DEEPSEEK_API_KEY! },
112
- anthropic: { apiKey: process.env.ANTHROPIC_API_KEY!, model: 'claude-opus-4-8' },
113
- ollama: { host: 'http://localhost:11434', model: 'llama3.2' },
114
- },
115
- defaultProvider: 'deepseek',
116
- // Each agent profile can specify a provider override
117
- });
118
- ```
119
-
120
- ### With full orchestration
121
-
122
- ```typescript
123
- const engine = createCodingEngine({
124
- providers: { deepseek: { apiKey: '...' } },
125
- defaultProvider: 'deepseek',
126
- orchestration: true,
127
- // Enables:
128
- // intent detection → domain detection → risk scoring
129
- // policy engine → agent routing → QA auto-review → reflection
130
- });
131
- ```
132
-
133
- ### With MCP servers
134
-
135
- ```typescript
136
- const engine = createCodingEngine({
137
- providers: { openai: { apiKey: '...' } },
138
- defaultProvider: 'openai',
139
- mcpServers: [
140
- { name: 'github', command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'], env: { GITHUB_TOKEN: '...' } },
141
- { name: 'postgres', command: 'npx', args: ['-y', '@modelcontextprotocol/server-postgres'], env: { DATABASE_URL: '...' } },
142
- ],
143
- subAgentContextMessages: 15,
144
- });
145
- ```
146
-
147
- ### With manual tool approval
148
-
149
- ```typescript
150
- const engine = createCodingEngine({
151
- providers: { deepseek: { apiKey: '...' } },
152
- defaultProvider: 'deepseek',
153
- onToolApproval: async (toolName, agentId, argsPreview) => {
154
- const write = ['write_file', 'edit_file', 'run_command'];
155
- if (!write.includes(toolName)) return 'approve';
156
- console.log(`\n⚠ [${agentId}] ${toolName}:\n${argsPreview}\n`);
157
- const a = await prompt('Approve? (y/n/all): ');
158
- if (a === 'y') return 'approve';
159
- if (a === 'all') return 'approve_all';
160
- return 'reject';
161
- },
162
- });
163
- ```
164
-
165
- ---
166
-
167
- ## createCodingEngineFromConfig
168
-
169
- Reads credentials from `~/.{appName}/config.json`. No code changes needed to switch providers:
170
-
171
- ```typescript
172
- import { createCodingEngineFromConfig } from '@backendkit-labs/agent-coding';
173
-
174
- const engine = createCodingEngineFromConfig();
175
-
176
- // With overrides
177
- const engine = createCodingEngineFromConfig({
178
- workingDir: '/my-project',
179
- orchestration: true,
180
- });
181
- ```
182
-
183
- ---
184
-
185
- ## Providers
186
-
187
- ### DeepSeek
188
-
189
- ```typescript
190
- providers: {
191
- deepseek: {
192
- apiKey: process.env.DEEPSEEK_API_KEY!,
193
- model?: 'deepseek-chat', // default
194
- maxTokens?: 8192,
195
- temperature?: 0.7,
196
- }
197
- }
198
- ```
199
-
200
- ### OpenAI
201
-
202
- ```typescript
203
- providers: {
204
- openai: {
205
- apiKey: process.env.OPENAI_API_KEY!,
206
- model?: 'gpt-4o',
207
- baseUrl?: 'https://api.openai.com/v1',
208
- }
209
- }
210
- ```
211
-
212
- ### Anthropic (Claude)
213
-
214
- ```typescript
215
- providers: {
216
- anthropic: {
217
- apiKey: process.env.ANTHROPIC_API_KEY!,
218
- model?: 'claude-sonnet-4-6', // default
219
- }
220
- }
221
- ```
222
-
223
- ### Ollama (local — no API key)
224
-
225
- ```bash
226
- # Prerequisites
227
- ollama serve
228
- ollama pull llama3.2
229
- ```
230
-
231
- ```typescript
232
- providers: {
233
- ollama: {
234
- host?: 'http://localhost:11434',
235
- model?: 'llama3.2',
236
- }
237
- }
238
- ```
239
-
240
- ### OpenAI-compatible (Kimi, Grok, any endpoint)
241
-
242
- ```typescript
243
- providers: {
244
- kimi: { apiKey: process.env.KIMI_API_KEY!, model: 'moonshot-v1-8k' },
245
- grok: { apiKey: process.env.GROK_API_KEY!, model: 'grok-3' },
246
- // Any OpenAI-compatible endpoint
247
- vllm: { apiKey: 'local', baseUrl: 'http://localhost:8080/v1', model: 'my-model' },
248
- }
249
- ```
250
-
251
- ---
252
-
253
- ## Built-in agents
254
-
255
- Ten specialist agents are bundled. Orchestration routes tasks automatically; you can also select explicitly.
256
-
257
- | Agent ID | Specialty |
258
- |----------|-----------|
259
- | `general` | General-purpose — default starting point |
260
- | `architect` | System design, ADRs, architecture decisions |
261
- | `backend-agent` | APIs, server logic, databases |
262
- | `frontend-agent` | React, CSS, accessibility, UX |
263
- | `devops-agent` | CI/CD, Docker, Kubernetes, infra |
264
- | `database-agent` | SQL, indexes, migrations, query tuning |
265
- | `security-reviewer` | Security audits, OWASP, threat modeling |
266
- | `qa-engineer` | Test strategy, edge cases, QA reviews |
267
- | `documentation-agent` | Docs, READMEs, API docs, changelogs |
268
- | `refactoring-agent` | Code cleanup, technical debt, design patterns |
269
-
270
- ### Selecting an agent
271
-
272
- ```typescript
273
- await engine.run('Audit src/ for SQL injection risks', { agentId: 'security-reviewer' });
274
- ```
275
-
276
- ### Adding custom agents
277
-
278
- Create `~/.bk-agent/agents/my-agent.json`:
279
-
280
- ```json
281
- {
282
- "id": "my-agent",
283
- "name": "My Custom Agent",
284
- "systemPrompt": "You are specialized in ...",
285
- "tools": ["read_file", "run_command"],
286
- "provider": "anthropic"
287
- }
288
- ```
289
-
290
- Loaded automatically — no code changes needed.
291
-
292
- ---
293
-
294
- ## Built-in tools
295
-
296
- All agents have access to these tools via `CODING_TOOLS`:
297
-
298
- | Tool | Description |
299
- |------|-------------|
300
- | `read_file` | Read a file by path |
301
- | `write_file` | Create or overwrite a file |
302
- | `edit_file` | Apply a targeted patch to a file |
303
- | `list_directory` | List files in a directory |
304
- | `run_command` | Execute a shell command |
305
- | `search_files` | Recursive content search |
306
- | `save_context` | Write to `session.md` (persisted notes) |
307
- | `save_learning` | Append to `lecciones-aprendidas.md` |
308
- | `save_audit` | Write a structured audit entry |
309
- | `get_latest_audit` | Read the latest audit |
310
- | `list_audits` | List audit entries |
311
- | `save_user_preference` | Persist user preferences |
312
- | `update_session` | Update the in-progress session note |
313
-
314
- ---
315
-
316
- ## Skill packs
317
-
318
- Built-in packs activate based on detected project stack:
319
-
320
- | Pack | Activates for |
321
- |------|---------------|
322
- | `GLOBAL_BUILTIN_SKILLS` | All projects |
323
- | `NODE_PACK_SKILLS` | Node.js / TypeScript (`package.json`) |
324
- | `GO_PACK_SKILLS` | Go (`go.mod`) |
325
- | `JAVA_PACK_SKILLS` | Java (`pom.xml`, `build.gradle`) |
326
- | `KOTLIN_PACK_SKILLS` | Kotlin / Android |
327
- | `PYTHON_PACK_SKILLS` | Python (`requirements.txt`, `pyproject.toml`) |
328
-
329
- ---
330
-
331
- ## Orchestration pipeline
332
-
333
- When `orchestration: true`, an intelligent routing layer runs before each LLM call:
334
-
335
- ```
336
- Input
337
- → Intent Detection (feature? bug? refactor? question?)
338
- → Domain Detection (backend? frontend? security? ops?)
339
- → Risk Scoring (reads only? writes files? runs commands?)
340
- → Policy Engine (enforce domain-level rules)
341
- → Agent Selection (best agent for detected domain + risk)
342
- → LLM Call
343
- → QA Review (auto-review code-heavy responses)
344
- ```
345
-
346
- ### Custom orchestration
347
-
348
- ```typescript
349
- orchestration: {
350
- capabilityMatrix: {
351
- 'my-specialist': {
352
- owns: ['payments', 'billing'],
353
- skills: ['typescript', 'stripe'],
354
- baseWeight: 0.95,
355
- },
356
- },
357
- customRules: [
358
- {
359
- if: { domain: 'security' },
360
- then: { mustInclude: ['security-reviewer'] },
361
- },
362
- ],
363
- enableQA: true,
364
- noQA: false,
365
- onQAReview: (review) => logger.info('[QA]', review),
366
- }
367
- ```
368
-
369
- ---
370
-
371
- ## Reflection engine
372
-
373
- Observes failures across runs, promotes recurring patterns into policy rules:
374
-
375
- ```typescript
376
- orchestration: {
377
- reflection: true,
378
- // After each sprint:
379
- // 1. Failures logged to FailureCatalog
380
- // 2. Patterns with ≥3 occurrences promoted to PolicyRules
381
- // 3. lecciones-aprendidas.md updated
382
- }
383
- ```
384
-
385
- ---
386
-
387
- ## MCP server integration
388
-
389
- ```typescript
390
- mcpServers: [
391
- {
392
- name: 'code-intelligence',
393
- command: 'bk-mcp', // @backendkit-labs/mcp-server
394
- args: [],
395
- env: { BK_APP_NAME: 'bk-agent', BK_CWD: process.cwd() },
396
- },
397
- {
398
- name: 'github',
399
- command: 'npx',
400
- args: ['-y', '@modelcontextprotocol/server-github'],
401
- env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! },
402
- },
403
- ],
404
- subAgentContextMessages: 20,
405
- ```
406
-
407
- ---
408
-
409
- ## Multi-agent examples
410
-
411
- ### Feature implementation
412
-
413
- ```typescript
414
- await engine.run(`
415
- Implement JWT authentication middleware for Express:
416
- - Validate Bearer token in Authorization header
417
- - Attach decoded user to req.user
418
- - Return 401 with clear error messages
419
- - Include unit tests with valid/expired/malformed token cases
420
- `);
421
- // architect plans → backend-agent implements → qa-engineer writes tests
422
- ```
423
-
424
- ### Security audit
425
-
426
- ```typescript
427
- await engine.run(`
428
- Audit all routes in src/routes/ for:
429
- 1. Missing auth middleware
430
- 2. SQL injection vulnerabilities
431
- 3. Exposed sensitive data
432
- Output a prioritized fix list.
433
- `, { agentId: 'security-reviewer' });
434
- ```
435
-
436
- ### Database migration
437
-
438
- ```typescript
439
- await engine.run(`
440
- Write a zero-downtime migration: add NOT NULL column
441
- 'last_login_at TIMESTAMP DEFAULT NOW()' to the users table (50M rows).
442
- Include rollback script and backfill strategy.
443
- `, { agentId: 'database-agent' });
444
- ```
445
-
446
- ### Full stack refactor
447
-
448
- ```typescript
449
- await engine.run(`
450
- Refactor auth from session cookies to JWT.
451
- Update both Express middleware and React login flow.
452
- Keep backward compatibility for 2 more sprints.
453
- `);
454
- // backend-agent + frontend-agent + security-reviewer
455
- ```
456
-
457
- ---
458
-
459
- ## Config file
460
-
461
- `~/.bk-agent/config.json`:
462
-
463
- ```json
464
- {
465
- "defaultProvider": "deepseek",
466
- "providers": {
467
- "deepseek": { "apiKey": "sk-xxxx", "model": "deepseek-chat" },
468
- "anthropic": { "apiKey": "sk-ant-xxxx", "model": "claude-sonnet-4-6" },
469
- "ollama": { "host": "http://localhost:11434", "model": "llama3.2" }
470
- },
471
- "mcpServers": [
472
- {
473
- "name": "github",
474
- "command": "npx",
475
- "args": ["-y", "@modelcontextprotocol/server-github"],
476
- "env": { "GITHUB_TOKEN": "ghp_xxxx" }
477
- }
478
- ]
479
- }
480
- ```
1
+ # @backendkit-labs/agent-coding
2
+
3
+ A production-ready coding agent engine built on `@backendkit-labs/agent-core`. Bundles 10 specialized agents, filesystem tools, multi-provider support (DeepSeek, OpenAI, Anthropic, Ollama, Kimi, Grok), automatic stack detection, persistent memory, QA review, reflection, and an orchestration pipeline — all in a single `createCodingEngine()` call.
4
+
5
+ [![npm](https://img.shields.io/npm/v/@backendkit-labs/agent-coding)](https://www.npmjs.com/package/@backendkit-labs/agent-coding)
6
+
7
+ > **Status: `stable`** — Maintained and production-ready. No new features during the pilot phase.
8
+
9
+ ## Table of contents
10
+
11
+ - [Installation](#installation)
12
+ - [Quick start](#quick-start)
13
+ - [createCodingEngine](#createcodingengine)
14
+ - [createCodingEngineFromConfig](#createcodingenginefromconfig)
15
+ - [Providers](#providers)
16
+ - [Built-in agents](#built-in-agents)
17
+ - [Built-in tools](#built-in-tools)
18
+ - [Skill packs](#skill-packs)
19
+ - [Orchestration pipeline](#orchestration-pipeline)
20
+ - [Reflection engine](#reflection-engine)
21
+ - [MCP server integration](#mcp-server-integration)
22
+ - [Multi-agent examples](#multi-agent-examples)
23
+ - [Config file](#config-file)
24
+
25
+ ---
26
+
27
+ ## Installation
28
+
29
+ ```bash
30
+ npm install @backendkit-labs/agent-coding
31
+ ```
32
+
33
+ All provider adapters are bundled — no separate packages needed.
34
+
35
+ ---
36
+
37
+ ## Quick start
38
+
39
+ ```typescript
40
+ import { createCodingEngine } from '@backendkit-labs/agent-coding';
41
+
42
+ const engine = createCodingEngine({
43
+ providers: { deepseek: { apiKey: process.env.DEEPSEEK_API_KEY! } },
44
+ defaultProvider: 'deepseek',
45
+ });
46
+
47
+ await engine.run('List all TypeScript files in src/ and tell me which ones have no tests');
48
+ ```
49
+
50
+ That single call gives you: 10 specialized agents, filesystem tools (read/write/edit/search), persistent project memory, skill loading, and stack auto-detection.
51
+
52
+ ---
53
+
54
+ ## createCodingEngine
55
+
56
+ The primary factory. Returns a fully configured `AgentEngine`.
57
+
58
+ ### Options reference
59
+
60
+ ```typescript
61
+ interface CodingEngineOptions {
62
+ // Required
63
+ providers: ProvidersConfig;
64
+ defaultProvider: string;
65
+
66
+ // Agents and engine
67
+ defaultAgent?: string; // default: 'general'
68
+ workingDir?: string; // default: process.cwd()
69
+ maxIterations?: number; // default: 100
70
+ maxParallelAgents?: number; // default: 6
71
+
72
+ // I/O
73
+ transport?: Transport; // default: StdoutTransport
74
+
75
+ // App identity
76
+ appName?: string; // default: 'bk-agent' — used for ~/.{appName}/
77
+
78
+ // Persistence
79
+ disablePersistence?: boolean; // skip ProjectStore (useful for testing)
80
+
81
+ // MCP servers
82
+ mcpServers?: MCPServerConfig[];
83
+
84
+ // Context sharing
85
+ subAgentContextMessages?: number; // messages visible to sub-agents (recommend 10-20)
86
+
87
+ // Iteration control
88
+ onToolApproval?: (toolName, agentId, argsPreview) => Promise<ToolApprovalDecision>;
89
+ onIterationLimit?: (stats: IterationStats) => Promise<boolean>;
90
+ onStep?: (stats: IterationStats) => Promise<boolean>;
91
+
92
+ // Orchestration
93
+ orchestration?: boolean | OrchestrationOptions;
94
+ }
95
+ ```
96
+
97
+ ### Minimal setup
98
+
99
+ ```typescript
100
+ const engine = createCodingEngine({
101
+ providers: { deepseek: { apiKey: 'sk-...' } },
102
+ defaultProvider: 'deepseek',
103
+ });
104
+ ```
105
+
106
+ ### Multiple providers
107
+
108
+ ```typescript
109
+ const engine = createCodingEngine({
110
+ providers: {
111
+ deepseek: { apiKey: process.env.DEEPSEEK_API_KEY! },
112
+ anthropic: { apiKey: process.env.ANTHROPIC_API_KEY!, model: 'claude-opus-4-8' },
113
+ ollama: { host: 'http://localhost:11434', model: 'llama3.2' },
114
+ },
115
+ defaultProvider: 'deepseek',
116
+ // Each agent profile can specify a provider override
117
+ });
118
+ ```
119
+
120
+ ### With full orchestration
121
+
122
+ ```typescript
123
+ const engine = createCodingEngine({
124
+ providers: { deepseek: { apiKey: '...' } },
125
+ defaultProvider: 'deepseek',
126
+ orchestration: true,
127
+ // Enables:
128
+ // intent detection → domain detection → risk scoring
129
+ // policy engine → agent routing → QA auto-review → reflection
130
+ });
131
+ ```
132
+
133
+ ### With MCP servers
134
+
135
+ ```typescript
136
+ const engine = createCodingEngine({
137
+ providers: { openai: { apiKey: '...' } },
138
+ defaultProvider: 'openai',
139
+ mcpServers: [
140
+ { name: 'github', command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'], env: { GITHUB_TOKEN: '...' } },
141
+ { name: 'postgres', command: 'npx', args: ['-y', '@modelcontextprotocol/server-postgres'], env: { DATABASE_URL: '...' } },
142
+ ],
143
+ subAgentContextMessages: 15,
144
+ });
145
+ ```
146
+
147
+ ### With manual tool approval
148
+
149
+ ```typescript
150
+ const engine = createCodingEngine({
151
+ providers: { deepseek: { apiKey: '...' } },
152
+ defaultProvider: 'deepseek',
153
+ onToolApproval: async (toolName, agentId, argsPreview) => {
154
+ const write = ['write_file', 'edit_file', 'run_command'];
155
+ if (!write.includes(toolName)) return 'approve';
156
+ console.log(`\n⚠ [${agentId}] ${toolName}:\n${argsPreview}\n`);
157
+ const a = await prompt('Approve? (y/n/all): ');
158
+ if (a === 'y') return 'approve';
159
+ if (a === 'all') return 'approve_all';
160
+ return 'reject';
161
+ },
162
+ });
163
+ ```
164
+
165
+ ---
166
+
167
+ ## createCodingEngineFromConfig
168
+
169
+ Reads credentials from `~/.{appName}/config.json`. No code changes needed to switch providers:
170
+
171
+ ```typescript
172
+ import { createCodingEngineFromConfig } from '@backendkit-labs/agent-coding';
173
+
174
+ const engine = createCodingEngineFromConfig();
175
+
176
+ // With overrides
177
+ const engine = createCodingEngineFromConfig({
178
+ workingDir: '/my-project',
179
+ orchestration: true,
180
+ });
181
+ ```
182
+
183
+ ---
184
+
185
+ ## Providers
186
+
187
+ ### DeepSeek
188
+
189
+ ```typescript
190
+ providers: {
191
+ deepseek: {
192
+ apiKey: process.env.DEEPSEEK_API_KEY!,
193
+ model?: 'deepseek-chat', // default
194
+ maxTokens?: 8192,
195
+ temperature?: 0.7,
196
+ }
197
+ }
198
+ ```
199
+
200
+ ### OpenAI
201
+
202
+ ```typescript
203
+ providers: {
204
+ openai: {
205
+ apiKey: process.env.OPENAI_API_KEY!,
206
+ model?: 'gpt-4o',
207
+ baseUrl?: 'https://api.openai.com/v1',
208
+ }
209
+ }
210
+ ```
211
+
212
+ ### Anthropic (Claude)
213
+
214
+ ```typescript
215
+ providers: {
216
+ anthropic: {
217
+ apiKey: process.env.ANTHROPIC_API_KEY!,
218
+ model?: 'claude-sonnet-4-6', // default
219
+ }
220
+ }
221
+ ```
222
+
223
+ ### Ollama (local — no API key)
224
+
225
+ ```bash
226
+ # Prerequisites
227
+ ollama serve
228
+ ollama pull llama3.2
229
+ ```
230
+
231
+ ```typescript
232
+ providers: {
233
+ ollama: {
234
+ host?: 'http://localhost:11434',
235
+ model?: 'llama3.2',
236
+ }
237
+ }
238
+ ```
239
+
240
+ ### OpenAI-compatible (Kimi, Grok, any endpoint)
241
+
242
+ ```typescript
243
+ providers: {
244
+ kimi: { apiKey: process.env.KIMI_API_KEY!, model: 'moonshot-v1-8k' },
245
+ grok: { apiKey: process.env.GROK_API_KEY!, model: 'grok-3' },
246
+ // Any OpenAI-compatible endpoint
247
+ vllm: { apiKey: 'local', baseUrl: 'http://localhost:8080/v1', model: 'my-model' },
248
+ }
249
+ ```
250
+
251
+ ---
252
+
253
+ ## Built-in agents
254
+
255
+ Ten specialist agents are bundled. Orchestration routes tasks automatically; you can also select explicitly.
256
+
257
+ | Agent ID | Specialty |
258
+ |----------|-----------|
259
+ | `general` | General-purpose — default starting point |
260
+ | `architect` | System design, ADRs, architecture decisions |
261
+ | `backend-agent` | APIs, server logic, databases |
262
+ | `frontend-agent` | React, CSS, accessibility, UX |
263
+ | `devops-agent` | CI/CD, Docker, Kubernetes, infra |
264
+ | `database-agent` | SQL, indexes, migrations, query tuning |
265
+ | `security-reviewer` | Security audits, OWASP, threat modeling |
266
+ | `qa-engineer` | Test strategy, edge cases, QA reviews |
267
+ | `documentation-agent` | Docs, READMEs, API docs, changelogs |
268
+ | `refactoring-agent` | Code cleanup, technical debt, design patterns |
269
+
270
+ ### Selecting an agent
271
+
272
+ ```typescript
273
+ await engine.run('Audit src/ for SQL injection risks', { agentId: 'security-reviewer' });
274
+ ```
275
+
276
+ ### Adding custom agents
277
+
278
+ Create `~/.bk-agent/agents/my-agent.json`:
279
+
280
+ ```json
281
+ {
282
+ "id": "my-agent",
283
+ "name": "My Custom Agent",
284
+ "systemPrompt": "You are specialized in ...",
285
+ "tools": ["read_file", "run_command"],
286
+ "provider": "anthropic"
287
+ }
288
+ ```
289
+
290
+ Loaded automatically — no code changes needed.
291
+
292
+ ### Project agents and skills need a trusted project
293
+
294
+ Agents in `{project}/.bk-agent/agents/` and skills in `{project}/.bk-agent/skills/` are the **repository's** content, not yours: a cloned repo could ship an agent that replaces the built-in orchestrator with its own prompt and tools. So they load only for a project you trusted. Your own agents and skills under `~/.bk-agent/` always load.
295
+
296
+ ```text
297
+ /trust # is this project trusted, and what would its project layer load
298
+ /trust add # trust it (records the real path in ~/.bk-agent/trusted-projects.json)
299
+ /trust remove # stop trusting it
300
+ /trust list
301
+ ```
302
+
303
+ - Trust is by **exact path**: trusting `~/code` does not trust a repository cloned inside it.
304
+ - For a project that is not trusted, the engine emits a warning naming what was left out. Skills load right after `/trust add`; agents the next time the agent starts.
305
+ - `BK_TRUST_PROJECT=1` trusts every path (CI, containers). A host that decides by itself can pass `trustedProject: true | false` to `createCodingEngine`.
306
+ - A missing or damaged trust file means nobody is trusted.
307
+
308
+ ---
309
+
310
+ ## Built-in tools
311
+
312
+ All agents have access to these tools via `CODING_TOOLS`:
313
+
314
+ | Tool | Description |
315
+ |------|-------------|
316
+ | `read_file` | Read a file by path |
317
+ | `write_file` | Create or overwrite a file |
318
+ | `edit_file` | Apply a targeted patch to a file |
319
+ | `list_directory` | List files in a directory |
320
+ | `run_command` | Execute a shell command |
321
+ | `search_files` | Recursive content search |
322
+ | `save_context` | Write to `session.md` (persisted notes) |
323
+ | `save_learning` | Append to `lecciones-aprendidas.md` |
324
+ | `save_audit` | Write a structured audit entry |
325
+ | `get_latest_audit` | Read the latest audit |
326
+ | `list_audits` | List audit entries |
327
+ | `save_user_preference` | Persist user preferences |
328
+ | `update_session` | Update the in-progress session note |
329
+
330
+ ---
331
+
332
+ ## Skill packs
333
+
334
+ Built-in packs activate based on detected project stack:
335
+
336
+ | Pack | Activates for |
337
+ |------|---------------|
338
+ | `GLOBAL_BUILTIN_SKILLS` | All projects |
339
+ | `NODE_PACK_SKILLS` | Node.js / TypeScript (`package.json`) |
340
+ | `GO_PACK_SKILLS` | Go (`go.mod`) |
341
+ | `JAVA_PACK_SKILLS` | Java (`pom.xml`, `build.gradle`) |
342
+ | `KOTLIN_PACK_SKILLS` | Kotlin / Android |
343
+ | `PYTHON_PACK_SKILLS` | Python (`requirements.txt`, `pyproject.toml`) |
344
+
345
+ ---
346
+
347
+ ## Orchestration pipeline
348
+
349
+ When `orchestration: true`, an intelligent routing layer runs before each LLM call:
350
+
351
+ ```
352
+ Input
353
+ → Intent Detection (feature? bug? refactor? question?)
354
+ → Domain Detection (backend? frontend? security? ops?)
355
+ → Risk Scoring (reads only? writes files? runs commands?)
356
+ → Policy Engine (enforce domain-level rules)
357
+ → Agent Selection (best agent for detected domain + risk)
358
+ → LLM Call
359
+ → QA Review (auto-review code-heavy responses)
360
+ ```
361
+
362
+ ### Custom orchestration
363
+
364
+ ```typescript
365
+ orchestration: {
366
+ capabilityMatrix: {
367
+ 'my-specialist': {
368
+ owns: ['payments', 'billing'],
369
+ skills: ['typescript', 'stripe'],
370
+ baseWeight: 0.95,
371
+ },
372
+ },
373
+ customRules: [
374
+ {
375
+ if: { domain: 'security' },
376
+ then: { mustInclude: ['security-reviewer'] },
377
+ },
378
+ ],
379
+ enableQA: true,
380
+ noQA: false,
381
+ onQAReview: (review) => logger.info('[QA]', review),
382
+ }
383
+ ```
384
+
385
+ ---
386
+
387
+ ## Reflection engine
388
+
389
+ Observes failures across runs, promotes recurring patterns into policy rules:
390
+
391
+ ```typescript
392
+ orchestration: {
393
+ reflection: true,
394
+ // After each sprint:
395
+ // 1. Failures logged to FailureCatalog
396
+ // 2. Patterns with ≥3 occurrences promoted to PolicyRules
397
+ // 3. lecciones-aprendidas.md updated
398
+ }
399
+ ```
400
+
401
+ ---
402
+
403
+ ## MCP server integration
404
+
405
+ ```typescript
406
+ mcpServers: [
407
+ {
408
+ name: 'code-intelligence',
409
+ command: 'bk-mcp', // @backendkit-labs/mcp-server
410
+ args: [],
411
+ env: { BK_APP_NAME: 'bk-agent', BK_CWD: process.cwd() },
412
+ },
413
+ {
414
+ name: 'github',
415
+ command: 'npx',
416
+ args: ['-y', '@modelcontextprotocol/server-github'],
417
+ env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! },
418
+ },
419
+ ],
420
+ subAgentContextMessages: 20,
421
+ ```
422
+
423
+ ---
424
+
425
+ ## Multi-agent examples
426
+
427
+ ### Feature implementation
428
+
429
+ ```typescript
430
+ await engine.run(`
431
+ Implement JWT authentication middleware for Express:
432
+ - Validate Bearer token in Authorization header
433
+ - Attach decoded user to req.user
434
+ - Return 401 with clear error messages
435
+ - Include unit tests with valid/expired/malformed token cases
436
+ `);
437
+ // architect plans → backend-agent implements → qa-engineer writes tests
438
+ ```
439
+
440
+ ### Security audit
441
+
442
+ ```typescript
443
+ await engine.run(`
444
+ Audit all routes in src/routes/ for:
445
+ 1. Missing auth middleware
446
+ 2. SQL injection vulnerabilities
447
+ 3. Exposed sensitive data
448
+ Output a prioritized fix list.
449
+ `, { agentId: 'security-reviewer' });
450
+ ```
451
+
452
+ ### Database migration
453
+
454
+ ```typescript
455
+ await engine.run(`
456
+ Write a zero-downtime migration: add NOT NULL column
457
+ 'last_login_at TIMESTAMP DEFAULT NOW()' to the users table (50M rows).
458
+ Include rollback script and backfill strategy.
459
+ `, { agentId: 'database-agent' });
460
+ ```
461
+
462
+ ### Full stack refactor
463
+
464
+ ```typescript
465
+ await engine.run(`
466
+ Refactor auth from session cookies to JWT.
467
+ Update both Express middleware and React login flow.
468
+ Keep backward compatibility for 2 more sprints.
469
+ `);
470
+ // backend-agent + frontend-agent + security-reviewer
471
+ ```
472
+
473
+ ---
474
+
475
+ ## Config file
476
+
477
+ `~/.bk-agent/config.json`:
478
+
479
+ ```json
480
+ {
481
+ "defaultProvider": "deepseek",
482
+ "providers": {
483
+ "deepseek": { "apiKey": "sk-xxxx", "model": "deepseek-chat" },
484
+ "anthropic": { "apiKey": "sk-ant-xxxx", "model": "claude-sonnet-4-6" },
485
+ "ollama": { "host": "http://localhost:11434", "model": "llama3.2" }
486
+ },
487
+ "mcpServers": [
488
+ {
489
+ "name": "github",
490
+ "command": "npx",
491
+ "args": ["-y", "@modelcontextprotocol/server-github"],
492
+ "env": { "GITHUB_TOKEN": "ghp_xxxx" }
493
+ }
494
+ ]
495
+ }
496
+ ```