@cardor/agent-harness-kit 0.1.0 → 0.3.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.
Files changed (6) hide show
  1. package/README.md +366 -121
  2. package/dist/core/materializer/templates.d.ts +1 -1
  3. package/dist/core/materializer/templates.d.ts.map +1 -1
  4. package/dist/core/materializer/templates.js +1 -0
  5. package/dist/core/materializer/templates.js.map +1 -1
  6. package/package.json +2 -2
package/README.md CHANGED
@@ -1,7 +1,67 @@
1
- # agent-harness-kit
1
+ # @cardor/agent-harness-kit
2
2
 
3
- CLI scaffolding for multi-agent harness systems.
4
- Binary: `ahk` · Works with Claude Code, OpenCode, and any MCP-compatible AI tool.
3
+ **A provider-agnostic scaffolding kit for running structured multi-agent workflows in your codebase.**
4
+
5
+ Instead of letting AI agents roam freely through your project with no memory, no coordination, and no audit trail, agent-harness-kit gives them a shared structure: a task backlog, a defined workflow, a persistent log of every action taken, and a health gate that must be green before any work begins.
6
+
7
+ You stay in control. The agents stay on track.
8
+
9
+ ```bash
10
+ npx ahk init
11
+ ```
12
+
13
+ ---
14
+
15
+ ## Why this exists
16
+
17
+ Most AI coding tools give you a single agent with a chat window. That works for small tasks. It breaks down when:
18
+
19
+ - You want multiple specialized agents working in sequence (plan → explore → build → review)
20
+ - You need to track what changed, what was tried, and what was blocked — across sessions
21
+ - You switch between AI providers (Claude Code today, OpenCode tomorrow) and don't want to re-setup everything
22
+ - You want a health check that agents must pass before touching code
23
+
24
+ agent-harness-kit solves all of this with a thin layer of scaffolding and a local MCP server that any MCP-compatible AI tool can connect to.
25
+
26
+ ---
27
+
28
+ ## How it works
29
+
30
+ ```
31
+ ahk init
32
+ └── creates config, agent definitions, task backlog, health check
33
+
34
+ AI tool opens your project
35
+ └── reads .claude/mcp.json or opencode.json
36
+ └── spawns: npx ahk serve (stdio MCP server)
37
+
38
+ Agent starts working
39
+ └── tasks.get() → picks a task from the backlog
40
+ └── tasks.claim(id) → atomically claims it (no double-work)
41
+ └── actions.start() → registers its action
42
+ └── actions.write() → logs sections: result, files, blockers…
43
+ └── actions.complete() → closes the action
44
+
45
+ Lead → Explorer → Builder → Reviewer
46
+ └── each role has its own agent definition with clear responsibilities
47
+ └── the harness DB records the full history
48
+ ```
49
+
50
+ Everything is stored locally in a SQLite database (`.harness/harness.db`). No cloud, no external services, no API keys required beyond what your AI tool already uses.
51
+
52
+ ---
53
+
54
+ ## Features
55
+
56
+ - **Provider-agnostic** — works with Claude Code, OpenCode, or any MCP-compatible AI tool. Switch providers without losing your task history or reconfiguring your workflow.
57
+ - **Structured 4-agent workflow** — Lead, Explorer, Builder, and Reviewer each have defined responsibilities and can only act within their role.
58
+ - **Atomic task claiming** — agents use `tasks.claim()` which uses a SQLite transaction to prevent two agents from picking up the same task at the same time.
59
+ - **Full audit trail** — every action, file touched, tool used, and section written is stored in SQLite and queryable.
60
+ - **Health gate** — agents must run `health.sh` and get a green exit before starting or closing any task. You define what "healthy" means.
61
+ - **Markdown fallback** — `current.md` is always regenerated so agents can understand the session state even without the MCP server.
62
+ - **Docs search** — agents can call `docs.search(query)` to find relevant content in your project's docs folder before writing code.
63
+ - **Zero native dependencies** — uses `node:sqlite` (Node ≥ 22) or `bun:sqlite` (Bun) built-in. No native compilation, no `node-gyp`.
64
+ - **Incremental scaffold** — `ahk init` and `ahk build` never overwrite files you've customized. Agent definitions you've edited are preserved.
5
65
 
6
66
  ---
7
67
 
@@ -12,207 +72,392 @@ Binary: `ahk` · Works with Claude Code, OpenCode, and any MCP-compatible AI too
12
72
 
13
73
  ---
14
74
 
15
- ## Local development setup
16
-
17
- ### 1. Clone and install dependencies
75
+ ## Installation
18
76
 
19
77
  ```bash
20
- git clone <repo-url>
21
- cd agent-harness-kit
22
- npm install
78
+ # Install in your project as a dev dependency
79
+ npm install --save-dev @cardor/agent-harness-kit
80
+
81
+ # Or globally
82
+ npm install -g @cardor/agent-harness-kit
23
83
  ```
24
84
 
25
- ### 2. Build the TypeScript source
85
+ Then run the interactive setup inside your project:
26
86
 
27
87
  ```bash
28
- npm run build
88
+ npx ahk init
89
+ # or, if installed globally:
90
+ ahk init
29
91
  ```
30
92
 
31
- This compiles `src/` → `dist/`. You must re-run this every time you change source files.
93
+ ---
94
+
95
+ ## Commands
32
96
 
33
- > Tip: run `npm run dev` in a separate terminal to watch for changes and rebuild automatically.
97
+ ### `ahk init`
34
98
 
35
- ### 3. Link the binary globally
99
+ Interactive scaffold. Asks for your project name, description, AI provider, docs path, and an optional first task. Creates all harness files in the current directory.
36
100
 
37
101
  ```bash
38
- npm link
102
+ ahk init
39
103
  ```
40
104
 
41
- This registers `ahk` as a global command on your machine by symlinking `bin/ahk.js` into your global `node_modules/.bin/`.
105
+ Run this once per project. Safe to re-run — it will not overwrite files you've customized.
106
+
107
+ ---
108
+
109
+ ### `ahk build`
42
110
 
43
- Verify it worked:
111
+ Regenerates `AGENTS.md` and provider-specific files from your `agent-harness-kit.config.ts`. Use this after changing config values.
44
112
 
45
113
  ```bash
46
- ahk --version
47
- # 0.1.0
114
+ ahk build
115
+ ahk build --watch # watch mode: rebuilds automatically on config changes
48
116
  ```
49
117
 
50
118
  ---
51
119
 
52
- ## Testing from an external project folder
120
+ ### `ahk status`
53
121
 
54
- Once linked, you can use `ahk` from **any directory** — no need to be inside `agent-harness-kit/`.
122
+ Shows the current task table and any active agent actions.
55
123
 
56
124
  ```bash
57
- # Create a test project folder anywhere
58
- mkdir ~/projects/my-test-app
59
- cd ~/projects/my-test-app
60
-
61
- # Run the interactive scaffold
62
- ahk init
125
+ ahk status
126
+ ahk status --json # machine-readable output
63
127
  ```
64
128
 
65
- Follow the prompts. After init, your folder will contain:
129
+ ---
130
+
131
+ ### `ahk health`
66
132
 
133
+ Runs `health.sh` and reports the result. Exit 0 = healthy, exit 1 = something is wrong.
134
+
135
+ ```bash
136
+ ahk health
67
137
  ```
68
- my-test-app/
69
- ├── agent-harness-kit.config.ts ← your harness config
70
- ├── AGENTS.md ← navigation map for agents
71
- ├── health.sh ← implement your health checks here
72
- ├── .harness/
73
- │ ├── harness.db ← SQLite source of truth
74
- │ ├── current.md ← auto-generated session snapshot
75
- │ └── feature_list.json ← human-editable task list
76
- └── .claude/
77
- ├── agents/
78
- │ ├── lead.md
79
- │ ├── explorer.md
80
- │ ├── builder.md
81
- │ └── reviewer.md
82
- └── mcp.json ← Claude Code picks this up automatically
138
+
139
+ ---
140
+
141
+ ### `ahk sync`
142
+
143
+ Syncs `.harness/feature_list.json` into the SQLite database. Tasks already in the DB are skipped (by slug). Use this to seed the backlog from the JSON file without duplicating existing tasks.
144
+
145
+ ```bash
146
+ ahk sync
147
+ ahk sync --dry-run # preview changes without applying them
83
148
  ```
84
149
 
85
150
  ---
86
151
 
87
- ## Development loop
152
+ ### `ahk serve`
88
153
 
154
+ Starts the MCP server on stdio. **You never need to call this manually.** After `ahk init`, the generated `.claude/mcp.json` (Claude Code) or `opencode.json` (OpenCode) tells the AI tool to spawn it automatically when you open the project.
155
+
156
+ ```bash
157
+ ahk serve
158
+ ahk serve --port 3456 # default port (used only for config reference)
89
159
  ```
90
- # Terminal 1 — watch and rebuild on save
91
- cd agent-harness-kit
92
- npm run dev
93
160
 
94
- # Terminal 2 — test commands from your external project
95
- cd ~/projects/my-test-app
96
- ahk status
161
+ ---
162
+
163
+ ### `ahk task add`
164
+
165
+ Interactively adds a new task to the backlog (SQLite + `feature_list.json`).
166
+
167
+ ```bash
97
168
  ahk task add
98
- ahk health
99
169
  ```
100
170
 
101
- Because `npm link` creates a symlink (not a copy), every rebuild in terminal 1 is immediately available in terminal 2 — no re-linking needed.
171
+ ---
172
+
173
+ ### `ahk task list`
174
+
175
+ Lists all tasks. Optionally filter by status.
176
+
177
+ ```bash
178
+ ahk task list
179
+ ahk task list --status pending
180
+ ahk task list --status in_progress
181
+ ahk task list --status done
182
+ ahk task list --status blocked
183
+ ```
102
184
 
103
185
  ---
104
186
 
105
- ## Available commands
187
+ ### `ahk task done <id|slug>`
188
+
189
+ Marks a task as done. Runs the health check first — if health fails, the task is not closed.
106
190
 
191
+ ```bash
192
+ ahk task done 3
193
+ ahk task done add-auth-flow
107
194
  ```
108
- ahk init Interactive harness scaffold
109
- ahk build Regenerate AGENTS.md + provider files from config
110
- ahk build --watch Rebuild on config file changes
111
- ahk health Run health.sh and report result
112
- ahk status Show task table and active actions
113
- ahk status --json Same, as JSON
114
- ahk sync Sync feature_list.json ↔ SQLite
115
- ahk sync --dry-run Preview changes without applying
116
- ahk serve Start MCP server on stdio (used by Claude Code)
117
- ahk task add Add a task interactively
118
- ahk task list List all tasks
119
- ahk task list --status pending|in_progress|done|blocked
120
- ahk task done <id|slug> Mark a task as done (runs health check first)
121
- ahk migrate --to <provider> Move provider files to claude-code or opencode
122
- ahk export --json Export tasks + actions as JSON
195
+
196
+ ---
197
+
198
+ ### `ahk migrate`
199
+
200
+ Migrates provider-specific files from one provider to another. Useful when switching from Claude Code to OpenCode or vice versa.
201
+
202
+ ```bash
203
+ ahk migrate --to opencode
204
+ ahk migrate --to claude-code
123
205
  ```
124
206
 
125
207
  ---
126
208
 
127
- ## Remove the global link
209
+ ### `ahk export`
128
210
 
129
- When you no longer need the local link:
211
+ Exports the full database (tasks, actions, sections) as JSON. Useful for backups or external reporting.
130
212
 
131
213
  ```bash
132
- npm unlink -g agent-harness-kit
214
+ ahk export --json
215
+ ahk export --json > snapshot.json
133
216
  ```
134
217
 
135
218
  ---
136
219
 
137
- ## MCP server
220
+ ## Files created by `ahk init`
138
221
 
139
- `ahk serve` starts the MCP server on stdio. You never need to call it manually — after `ahk init`, the generated `.claude/mcp.json` (Claude Code) or `opencode.json` (OpenCode) tells the AI tool to spawn it automatically when you open the project.
222
+ ```
223
+ your-project/
224
+ ├── agent-harness-kit.config.ts ← main config (edit freely)
225
+ ├── AGENTS.md ← navigation map regenerated from config
226
+ ├── health.sh ← implement your health checks here
227
+ ├── .harness/
228
+ │ ├── harness.db ← SQLite source of truth (gitignored)
229
+ │ ├── current.md ← auto-generated session snapshot (gitignored)
230
+ │ └── feature_list.json ← human-editable task backlog (commit this)
231
+ └── .claude/ ← or .opencode/ depending on your provider
232
+ ├── agents/
233
+ │ ├── lead.md
234
+ │ ├── explorer.md
235
+ │ ├── builder.md
236
+ │ └── reviewer.md
237
+ └── mcp.json ← tells Claude Code to spawn ahk serve
238
+ ```
140
239
 
141
- **Tools exposed to agents:**
240
+ ### What each file does
142
241
 
143
- | Tool | Description |
144
- |------|-------------|
145
- | `actions.start(taskId, agent)` | Start an action, returns `actionId` |
146
- | `actions.write(actionId, section, content)` | Record a section (result, tools\_used, …) |
147
- | `actions.complete(actionId, summary)` | Close the action |
148
- | `actions.get(taskId)` | Full action history for a task |
149
- | `tasks.get([status])` | List tasks, optionally filtered |
150
- | `tasks.claim(id, agent)` | Atomically claim a pending task |
151
- | `tasks.update(id, status)` | Change task status |
152
- | `docs.search(query)` | Search the project docs folder |
242
+ | File | Purpose | Edit it? |
243
+ |------|---------|----------|
244
+ | `agent-harness-kit.config.ts` | Defines project metadata, provider, storage paths, MCP port | Yes — it's yours |
245
+ | `AGENTS.md` | Navigation map agents read first. Regenerated by `ahk build` | No — changes will be overwritten |
246
+ | `health.sh` | Shell script agents run before starting work. Must exit 0 | **Yes — implement your checks here** |
247
+ | `.harness/feature_list.json` | Task backlog in JSON. Humans edit this, `ahk sync` loads it into SQLite | Yes — add tasks here |
248
+ | `.harness/harness.db` | SQLite database. Source of truth for tasks, actions, sections | No — managed by the harness |
249
+ | `.harness/current.md` | Auto-generated session snapshot for agents without MCP access | No — regenerated automatically |
250
+ | `.claude/agents/*.md` | Agent role definitions. Created once, never overwritten | **Yes — customize agent behavior** |
251
+ | `.claude/mcp.json` | MCP server config. Merged (not overwritten) by `ahk build` | Yes, carefully — don't remove the `agent-harness-kit` entry |
153
252
 
154
253
  ---
155
254
 
156
- ## Runtime compatibility
255
+ ## What you can customize
256
+
257
+ ### `agent-harness-kit.config.ts`
258
+
259
+ Everything in the config file is yours to change:
260
+
261
+ ```ts
262
+ import { defineHarness } from '@cardor/agent-harness-kit'
263
+
264
+ export default defineHarness({
265
+ project: {
266
+ name: 'My App',
267
+ description: 'What this project does',
268
+ docsPath: './docs', // where agents search for documentation
269
+ },
270
+
271
+ provider: 'claude-code', // 'claude-code' | 'opencode'
272
+
273
+ agents: {
274
+ lead: { instructionsPath: null },
275
+ explorer: { instructionsPath: null, allowedPaths: ['./docs', './src'] },
276
+ builder: { instructionsPath: null, writablePaths: ['./src', './tests'] },
277
+ reviewer: { instructionsPath: null },
278
+ custom: [], // define extra agents here
279
+ },
280
+
281
+ storage: {
282
+ dir: '.harness',
283
+ dbPath: '.harness/harness.db',
284
+ tasks: { adapter: 'local' },
285
+ sections: {
286
+ toolsUsed: true, // log which tools agents used
287
+ filesModified: true, // log which files were touched
288
+ result: true, // log action results
289
+ blockers: true, // log blockers agents hit
290
+ nextSteps: false, // optional next steps field
291
+ },
292
+ markdownFallback: { enabled: true, path: '.harness/current.md' },
293
+ },
294
+
295
+ health: {
296
+ scriptPath: './health.sh',
297
+ required: true, // set to false to skip health checks
298
+ },
299
+
300
+ tools: {
301
+ mcp: { enabled: true, port: 3456 },
302
+ scripts: { enabled: true, outputDir: './.harness/scripts' },
303
+ },
304
+ })
305
+ ```
157
306
 
158
- | Runtime | Support |
159
- |---------|---------|
160
- | Node.js ≥ 22 | ✅ uses `node:sqlite` built-in |
161
- | Bun (any) | ✅ uses `bun:sqlite` built-in |
162
- | Node.js < 22 | ❌ `node:sqlite` not available |
307
+ ### `health.sh`
308
+
309
+ This is the most important file to implement. Agents will not start or close tasks until this script exits 0. Examples:
310
+
311
+ ```bash
312
+ #!/usr/bin/env bash
313
+
314
+ # Check the dev server is up
315
+ curl -sf http://localhost:3000/health > /dev/null || exit 1
316
+
317
+ # Run unit tests
318
+ npm test || exit 1
319
+
320
+ # Check DB connection
321
+ psql "$DATABASE_URL" -c "SELECT 1" > /dev/null 2>&1 || exit 1
322
+
323
+ echo "All checks passed."
324
+ ```
325
+
326
+ ### Agent definition files (`.claude/agents/*.md` or `.opencode/agents/*.md`)
327
+
328
+ These are Markdown files with a YAML frontmatter and free-form instructions. They are created once and **never overwritten** by `ahk build` — so any edits you make are permanent.
163
329
 
330
+ You can:
331
+ - Add domain-specific context (e.g. "this project uses hexagonal architecture")
332
+ - Restrict what the agent is allowed to do
333
+ - Add project-specific conventions the agent must follow
334
+ - Reference specific files or docs the agent should read first
335
+
336
+ ```markdown
337
+ ---
338
+ description: Builder agent — implements the plan produced by explorer and lead
164
339
  ---
165
340
 
166
- ## Running tests
341
+ # Builder Agent
167
342
 
168
- Tests use the Node.js built-in test runner — no extra dependencies needed.
343
+ You are the builder agent for MyApp. Follow these rules:
169
344
 
170
- ```bash
171
- npm run build
172
- npm test
345
+ - All API endpoints must be defined in `src/routes/`
346
+ - Never modify `src/core/` without lead approval
347
+ - Run `npm test` after every change and fix failures before completing
348
+ - Use the existing error handling pattern from `src/lib/errors.ts`
349
+ ```
350
+
351
+ ### `.harness/feature_list.json`
352
+
353
+ The human-editable task backlog. Add tasks here, then run `ahk sync` to load them into SQLite.
354
+
355
+ ```json
356
+ [
357
+ {
358
+ "slug": "add-auth-flow",
359
+ "title": "Add JWT authentication flow",
360
+ "description": "Implement login, refresh token, and logout endpoints",
361
+ "acceptance": [
362
+ "POST /auth/login returns a signed JWT",
363
+ "POST /auth/refresh validates and rotates the token",
364
+ "All protected routes return 401 without a valid token",
365
+ "Tests cover happy path and token expiry"
366
+ ]
367
+ }
368
+ ]
173
369
  ```
174
370
 
371
+ Good acceptance criteria make the difference — the reviewer agent uses them to decide whether to approve or block a task.
372
+
175
373
  ---
176
374
 
177
- ## Publishing to npm
375
+ ## MCP tools (for agents)
178
376
 
179
- The package is published under the `@cardor` scope as `@cardor/agent-harness-kit`.
377
+ The harness exposes these tools via MCP. Agents use them instead of reading files directly.
180
378
 
181
- ### Prerequisites
379
+ | Tool | Parameters | Description |
380
+ |------|-----------|-------------|
381
+ | `tasks.get` | `status?` | List tasks, optionally filtered by `pending \| in_progress \| done \| blocked` |
382
+ | `tasks.claim` | `id, agent` | Atomically claim a pending task. Returns `task_already_claimed` if another agent got it first |
383
+ | `tasks.update` | `id, status` | Change task status |
384
+ | `actions.start` | `taskId, agent` | Start a new action, returns `actionId` |
385
+ | `actions.write` | `actionId, sectionType, content` | Record a section: `result \| tools_used \| files_modified \| blockers \| next_steps` |
386
+ | `actions.complete` | `actionId, summary` | Close an action with a one-line summary |
387
+ | `actions.get` | `taskId` | Full action history for a task (all agents, all sections) |
388
+ | `docs.search` | `query` | Search the `docsPath` folder for content matching the query |
182
389
 
183
- 1. Be a member of the `@cardor` npm organization (or have publish access).
184
- 2. Be logged in to npm:
390
+ ---
185
391
 
186
- ```bash
187
- npm login
188
- ```
392
+ ## Agent roles
189
393
 
190
- ### Manual publish
394
+ | Role | Responsibility |
395
+ |------|---------------|
396
+ | **lead** | Decomposes the task into a plan, assigns sub-agents. Does not write code or read source files. |
397
+ | **explorer** | Reads and maps the codebase. Never writes files. Records every file read. |
398
+ | **builder** | Implements the plan. Only writes to `writablePaths`. Records every file modified. |
399
+ | **reviewer** | Verifies all acceptance criteria are met. Approves or blocks. Runs health check before approving. |
191
400
 
192
- ```bash
193
- # 1. Bump the version (patch | minor | major)
194
- npm version patch
401
+ ---
195
402
 
196
- # 2. Build, run tests, and publish (prepublishOnly does build + test automatically)
197
- npm publish --access public
198
- ```
403
+ ## What to commit
404
+
405
+ | File | Commit? |
406
+ |------|---------|
407
+ | `agent-harness-kit.config.ts` | Yes |
408
+ | `AGENTS.md` | Yes |
409
+ | `health.sh` | Yes |
410
+ | `.harness/feature_list.json` | Yes |
411
+ | `.claude/agents/*.md` | Yes |
412
+ | `.claude/mcp.json` / `opencode.json` | Yes |
413
+ | `.harness/harness.db` | **No** (gitignored) |
414
+ | `.harness/current.md` | **No** (gitignored) |
415
+
416
+ The rule: commit inputs (config, task definitions, agent instructions). Ignore outputs (DB, auto-generated snapshots).
417
+
418
+ ---
419
+
420
+ ## Runtime compatibility
199
421
 
200
- > `--access public` is required for scoped packages on the free npm plan.
422
+ | Runtime | Support |
423
+ |---------|---------|
424
+ | Node.js ≥ 22 | ✅ uses `node:sqlite` built-in |
425
+ | Bun (any recent) | ✅ uses `bun:sqlite` built-in |
426
+ | Node.js < 22 | ❌ `node:sqlite` not available |
201
427
 
202
- ### Check what will be packed before publishing
428
+ ---
429
+
430
+ ## Contributing & local development
203
431
 
204
432
  ```bash
205
- npm pack --dry-run
433
+ git clone <repo-url>
434
+ cd agent-harness-kit
435
+ npm install
436
+ npm run build # compile src/ → dist/
437
+ npm run dev # watch mode
438
+ npm test # run tests
439
+ npm link # register ahk globally from local source
206
440
  ```
207
441
 
208
- This lists every file that would be included in the tarball without actually uploading anything. Make sure `dist/` and `bin/` are listed, and that `src/`, `node_modules/`, and `.harness/` are **not**.
209
-
210
- ### Patch release checklist
442
+ Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) with a required scope:
211
443
 
212
444
  ```
213
- [ ] git pull --rebase origin main
214
- [ ] npm run build && npm test # must be green
215
- [ ] npm version patch # bumps package.json + creates git tag
216
- [ ] git push && git push --tags # CI will publish automatically (see below)
217
- [ ] npm publish --access public # only if publishing manually
445
+ feat(cli): add export command
446
+ fix(db): prevent race condition in claimTask
447
+ chore(ci): update Node version to 22
218
448
  ```
449
+
450
+ Types: `feat fix chore refactor docs test perf style build ci revert`
451
+
452
+ ---
453
+
454
+ ## Roadmap
455
+
456
+ These are planned features, not yet released:
457
+
458
+ - **Remote MCP adapter** — connect to a hosted MCP server instead of a local SQLite file. Enables shared task state across machines and team members without syncing a DB file.
459
+ - **Shared action log** — a web interface (or CLI dashboard) to view the full history of what every agent did, across all sessions, for a given project. Useful for team retrospectives and debugging agent behavior.
460
+ - **Jira / Linear task adapter** — pull tasks directly from your existing issue tracker instead of maintaining `feature_list.json` manually. The `tasks.adapter` config key is already wired for this.
461
+ - **Agent telemetry** — per-session statistics on tool usage, files touched, and time spent per role. Exported as JSON or pushed to a remote endpoint.
462
+ - **Multi-project harness** — a single MCP server managing multiple projects, with project-scoped task isolation.
463
+ - **Custom agent roles** — the config already has a `custom: []` field. The roadmap item is full CLI support for generating, registering, and routing tasks to custom-named agents beyond the default four.
package/dist/core/materializer/templates.d.ts CHANGED
@@ -21,5 +21,5 @@ export declare function featureListJson(tasks: {
21
21
  }[]): string;
22
22
  export declare function mergeClaudeMcpJson(filePath: string, port: number): void;
23
23
  export declare function mergeOpencodeJson(filePath: string, port: number): void;
24
- export declare const GITIGNORE_ENTRIES = "\n# agent-harness-kit\n.harness/harness.db\n.harness/harness.db-shm\n.harness/harness.db-wal\n";
24
+ export declare const GITIGNORE_ENTRIES = "\n# agent-harness-kit\n.harness/harness.db\n.harness/harness.db-shm\n.harness/harness.db-wal\n.harness/current.md\n";
25
25
  //# sourceMappingURL=templates.d.ts.map
package/dist/core/materializer/templates.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/core/materializer/templates.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAInD,eAAO,MAAM,SAAS,uoBAmBrB,CAAA;AAID,wBAAgB,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CA8EtD;AAID,wBAAgB,QAAQ,CAAC,MAAM,EAAE;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;CACb,GAAG,MAAM,CA6CT;AAID,eAAO,MAAM,UAAU,4hCA0BtB,CAAA;AAED,eAAO,MAAM,cAAc,24BAsB1B,CAAA;AAED,eAAO,MAAM,aAAa,g9BAwBzB,CAAA;AAED,eAAO,MAAM,cAAc,kjCA2B1B,CAAA;AAID,wBAAgB,eAAe,CAC7B,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,EAAE,GACpF,MAAM,CAER;AAQD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAwBvE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CA6BtE;AAID,eAAO,MAAM,iBAAiB,mGAK7B,CAAA"}
1
+ {"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/core/materializer/templates.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAInD,eAAO,MAAM,SAAS,uoBAmBrB,CAAA;AAID,wBAAgB,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CA8EtD;AAID,wBAAgB,QAAQ,CAAC,MAAM,EAAE;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;CACb,GAAG,MAAM,CA6CT;AAID,eAAO,MAAM,UAAU,4hCA0BtB,CAAA;AAED,eAAO,MAAM,cAAc,24BAsB1B,CAAA;AAED,eAAO,MAAM,aAAa,g9BAwBzB,CAAA;AAED,eAAO,MAAM,cAAc,kjCA2B1B,CAAA;AAID,wBAAgB,eAAe,CAC7B,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,EAAE,GACpF,MAAM,CAER;AAQD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAwBvE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CA6BtE;AAID,eAAO,MAAM,iBAAiB,wHAM7B,CAAA"}
package/dist/core/materializer/templates.js CHANGED
@@ -315,5 +315,6 @@ export const GITIGNORE_ENTRIES = `
315
315
  .harness/harness.db
316
316
  .harness/harness.db-shm
317
317
  .harness/harness.db-wal
318
+ .harness/current.md
318
319
  `;
319
320
  //# sourceMappingURL=templates.js.map
package/dist/core/materializer/templates.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"templates.js","sourceRoot":"","sources":["../../../src/core/materializer/templates.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"templates.js","sourceRoot":"","sources":["../../../src/core/materializer/templates.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cardor/agent-harness-kit",
3
- "version": "0.1.0",
3
+ "version": "0.3.0",
4
4
  "description": "CLI scaffolding for multi-agent harness systems",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -53,4 +53,4 @@
53
53
  "engines": {
54
54
  "node": ">=20.0.0"
55
55
  }
56
- }
56
+ }