opencode-agent-harness 0.0.0-stage → 0.2.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/CHANGELOG.md +23 -0
- package/LICENSE +21 -0
- package/README.md +590 -2
- package/bin/agent-harness.js +3059 -0
- package/contrib/global-plugins/README.md +49 -0
- package/contrib/global-plugins/harness-freshness.ts +355 -0
- package/package.json +48 -4
- package/templates/.agents/AGENTS.md +204 -0
- package/templates/.agents/features/INDEX.md +10 -0
- package/templates/.agents/handoffs/README.md +87 -0
- package/templates/.agents/memory/dev-loop.md +59 -0
- package/templates/.agents/memory/domain-map.md +29 -0
- package/templates/.agents/memory/environments.md +35 -0
- package/templates/.agents/memory/flow-map.md +23 -0
- package/templates/.agents/memory/history.md +7 -0
- package/templates/.agents/memory/locations.md +14 -0
- package/templates/.agents/memory/model-routing.md +261 -0
- package/templates/.agents/memory/orchestration.md +183 -0
- package/templates/.agents/memory/owned-files.md +19 -0
- package/templates/.agents/memory/product-principles.md +37 -0
- package/templates/.agents/memory/quality-parameters.md +37 -0
- package/templates/.agents/memory/stack-versions.md +35 -0
- package/templates/.agents/memory/test-design-parameters.md +36 -0
- package/templates/.agents/nightly.json +17 -0
- package/templates/.agents/qa-plans/README.md +70 -0
- package/templates/.agents/qa-runs/README.md +21 -0
- package/templates/.agents/reviews/README.md +47 -0
- package/templates/.agents/rules/00-operating.md +199 -0
- package/templates/.agents/skills/data-engineer/SKILL.md +31 -0
- package/templates/.agents/skills/devops-engineer/SKILL.md +50 -0
- package/templates/.agents/skills/diagnostics-expert/SKILL.md +44 -0
- package/templates/.agents/skills/docs/SKILL.md +140 -0
- package/templates/.agents/skills/features/SKILL.md +187 -0
- package/templates/.agents/skills/frontend-engineer/SKILL.md +81 -0
- package/templates/.agents/skills/handoff/SKILL.md +85 -0
- package/templates/.agents/skills/mobile-engineer/SKILL.md +101 -0
- package/templates/.agents/skills/planner/SKILL.md +112 -0
- package/templates/.agents/skills/product-manager/SKILL.md +115 -0
- package/templates/.agents/skills/qa-architect/SKILL.md +224 -0
- package/templates/.agents/skills/qa-runner/SKILL.md +64 -0
- package/templates/.agents/skills/security-engineer/SKILL.md +53 -0
- package/templates/.agents/skills/system-architect/SKILL.md +42 -0
- package/templates/.agents/skills/ui-designer/SKILL.md +71 -0
- package/templates/.github/workflows/ci.yml +148 -0
- package/templates/.github/workflows/deploy-uat.yml +95 -0
- package/templates/.github/workflows/nightly.yml +83 -0
- package/templates/.github/workflows/uat-health.yml +41 -0
- package/templates/.husky/pre-push +23 -0
- package/templates/.ignore +28 -0
- package/templates/.opencode/agents/data-engineer.md +37 -0
- package/templates/.opencode/agents/devops-engineer.md +37 -0
- package/templates/.opencode/agents/diagnostics-expert.md +37 -0
- package/templates/.opencode/agents/docs.md +37 -0
- package/templates/.opencode/agents/features.md +21 -0
- package/templates/.opencode/agents/frontend-engineer.md +37 -0
- package/templates/.opencode/agents/handoff.md +21 -0
- package/templates/.opencode/agents/mobile-engineer.md +37 -0
- package/templates/.opencode/agents/planner.md +34 -0
- package/templates/.opencode/agents/product-manager.md +29 -0
- package/templates/.opencode/agents/qa-architect.md +27 -0
- package/templates/.opencode/agents/qa-runner.md +17 -0
- package/templates/.opencode/agents/security-engineer.md +37 -0
- package/templates/.opencode/agents/system-architect.md +37 -0
- package/templates/.opencode/agents/ui-designer.md +37 -0
- package/templates/.opencode/commands/board.md +15 -0
- package/templates/.opencode/commands/checkpoint.md +25 -0
- package/templates/.opencode/commands/feature.md +56 -0
- package/templates/.opencode/commands/finish.md +36 -0
- package/templates/.opencode/commands/next.md +49 -0
- package/templates/.opencode/commands/report.md +55 -0
- package/templates/.opencode/commands/resume.md +39 -0
- package/templates/.opencode/commands/switch-model.md +34 -0
- package/templates/.opencode/commands/tidy.md +49 -0
- package/templates/.opencode/plugins/backlog-notify.ts +57 -0
- package/templates/.opencode/plugins/backlog.ts +272 -0
- package/templates/.opencode/plugins/checkpoint.ts +160 -0
- package/templates/.opencode/plugins/context-guard.ts +1164 -0
- package/templates/.opencode/plugins/diff.ts +85 -0
- package/templates/.opencode/plugins/gates.ts +71 -0
- package/templates/.opencode/plugins/job-notify.ts +241 -0
- package/templates/.opencode/plugins/orient.ts +67 -0
- package/templates/.opencode/plugins/session.ts +89 -0
- package/templates/.opencode/plugins/wait.ts +101 -0
- package/templates/.opencode/plugins/where.ts +70 -0
- package/templates/.opencode/skills/bounded-explore/SKILL.md +38 -0
- package/templates/.opencode/skills/dev-loop/SKILL.md +87 -0
- package/templates/.vercelignore +16 -0
- package/templates/AGENTS.md +27 -0
- package/templates/BACKLOG.md +95 -0
- package/templates/docs/ci-cd-pipeline.md +81 -0
- package/templates/docs/gates.md +128 -0
- package/templates/docs/mcp-integrations.md +97 -0
- package/templates/docs/mobile-testing.md +555 -0
- package/templates/docs/nightly-testing.md +106 -0
- package/templates/docs/wsl-optimizations.md +290 -0
- package/templates/opencode.json +188 -0
- package/templates/scripts/agent-report.js +541 -0
- package/templates/scripts/agent-search.sh +117 -0
- package/templates/scripts/backlog.js +1864 -0
- package/templates/scripts/board-service.sh +207 -0
- package/templates/scripts/checkpoint.js +290 -0
- package/templates/scripts/finalize.js +277 -0
- package/templates/scripts/nightly.js +913 -0
- package/templates/scripts/orient.js +514 -0
- package/templates/scripts/qa/board-client.js +260 -0
- package/templates/scripts/qa/board-lib.js +96 -0
- package/templates/scripts/qa/board-sync.js +469 -0
- package/templates/scripts/qa/capacity-lib.js +916 -0
- package/templates/scripts/qa/check-backlog.js +427 -0
- package/templates/scripts/qa/check-capacity.js +85 -0
- package/templates/scripts/qa/check-ci-policy.js +164 -0
- package/templates/scripts/qa/check-concurrency.js +344 -0
- package/templates/scripts/qa/check-dispatch-config.js +296 -0
- package/templates/scripts/qa/check-docs.js +284 -0
- package/templates/scripts/qa/check-integrate.js +98 -0
- package/templates/scripts/qa/check-linger.js +160 -0
- package/templates/scripts/qa/check-prefix-stability.js +183 -0
- package/templates/scripts/qa/check-product.js +177 -0
- package/templates/scripts/qa/check-qa-plan.js +378 -0
- package/templates/scripts/qa/check-qa-scripts.js +85 -0
- package/templates/scripts/qa/check-quality.js +249 -0
- package/templates/scripts/qa/check-test-wiring.js +253 -0
- package/templates/scripts/qa/ci-triage.js +346 -0
- package/templates/scripts/qa/ci-usage-lib.js +185 -0
- package/templates/scripts/qa/ci-wait-lib.js +294 -0
- package/templates/scripts/qa/command-classifier.js +552 -0
- package/templates/scripts/qa/context-guard-core.js +1618 -0
- package/templates/scripts/qa/diff.js +174 -0
- package/templates/scripts/qa/feature-scaffold.js +224 -0
- package/templates/scripts/qa/fixtures/backlog.md +104 -0
- package/templates/scripts/qa/governance.js +174 -0
- package/templates/scripts/qa/hash-file.js +32 -0
- package/templates/scripts/qa/lease-lib.js +263 -0
- package/templates/scripts/qa/merge-backlog.js +324 -0
- package/templates/scripts/qa/mobile-e2e/analyze-timings.js +300 -0
- package/templates/scripts/qa/mobile-e2e/apk-cache.js +420 -0
- package/templates/scripts/qa/mobile-e2e/backend-build-cache.js +203 -0
- package/templates/scripts/qa/mobile-e2e/boot-emulator.sh +432 -0
- package/templates/scripts/qa/mobile-e2e/build-apk.sh +210 -0
- package/templates/scripts/qa/mobile-e2e/check-flows.js +453 -0
- package/templates/scripts/qa/mobile-e2e/config.yaml +18 -0
- package/templates/scripts/qa/mobile-e2e/device-down.sh +88 -0
- package/templates/scripts/qa/mobile-e2e/device-up.sh +258 -0
- package/templates/scripts/qa/mobile-e2e/ios-simulator-down.sh +72 -0
- package/templates/scripts/qa/mobile-e2e/ios-simulator-up.sh +153 -0
- package/templates/scripts/qa/mobile-e2e/job-events.js +181 -0
- package/templates/scripts/qa/mobile-e2e/prewarm.sh +56 -0
- package/templates/scripts/qa/mobile-e2e/run-detached.sh +222 -0
- package/templates/scripts/qa/mobile-e2e/run-maestro.js +1543 -0
- package/templates/scripts/qa/mobile-e2e/ui-dump.js +327 -0
- package/templates/scripts/qa/models.allowlist.txt +32 -0
- package/templates/scripts/qa/provider-stats.js +878 -0
- package/templates/scripts/qa/run-clean.js +83 -0
- package/templates/scripts/qa/run-gates.js +212 -0
- package/templates/scripts/qa/run-loop.js +220 -0
- package/templates/scripts/qa/session-recon.js +512 -0
- package/templates/scripts/qa/store-lib.js +324 -0
- package/templates/scripts/qa/tool-lib.js +134 -0
- package/templates/scripts/qa/where.js +214 -0
- package/templates/scripts/qa/wslconfig-merge.js +157 -0
- package/templates/scripts/serve.js +1328 -0
- package/templates/scripts/setup-nightly.sh +185 -0
- package/templates/scripts/setup-tmpfs.sh +374 -0
- package/templates/scripts/ship.js +586 -0
- package/templates/scripts/switch-reasoning-model.ps1 +101 -0
- package/templates/scripts/switch-reasoning-model.sh +104 -0
- package/templates/scripts/wait-for.js +342 -0
- package/templates/scripts/wsl-gpu.sh +180 -0
- package/templates/scripts/wsl-tune.sh +261 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.2.0 — 2026-11-16
|
|
4
|
+
|
|
5
|
+
First public release under the `opencode-agent-harness` name.
|
|
6
|
+
|
|
7
|
+
- Renamed the package from `@dombaras/agent-harness` to `opencode-agent-harness`
|
|
8
|
+
(the CLI binary remains `agent-harness`).
|
|
9
|
+
- `init` no longer commits or pushes by default; pass `--commit` / `--push`.
|
|
10
|
+
`update` keeps its auto-commit behaviour.
|
|
11
|
+
- `init` refuses to overwrite a pre-existing `AGENTS.md` it did not create;
|
|
12
|
+
`--accept-harness` overwrites deliberately after backing the file up under
|
|
13
|
+
`.harness-backup/`. Pre-existing untracked harness files are backed up before
|
|
14
|
+
any overwrite.
|
|
15
|
+
- Added `repository`, `homepage`, `bugs`, `author`, and public-package keywords;
|
|
16
|
+
Node engine raised to `>=20`.
|
|
17
|
+
- Added a packed-tarball smoke test (`npm run test:pack`), a `prepublishOnly`
|
|
18
|
+
gate, and a tag-driven release workflow.
|
|
19
|
+
- Default model routing is unchanged (`opencode-go/*`).
|
|
20
|
+
|
|
21
|
+
## 0.1.21 — 2026-09-04
|
|
22
|
+
|
|
23
|
+
Last release under the previous name, `@dombaras/agent-harness`.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 opencode-agent-harness contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,591 @@
|
|
|
1
|
-
#
|
|
1
|
+
# opencode-agent-harness
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A reusable multi-agent harness for AI-assisted development. Ships a persona
|
|
4
|
+
fleet (planner, engine engineer, mobile, QA architect/runner, security,
|
|
5
|
+
architecture, product, data, devops, handoff, docs), operating rules, model routing,
|
|
6
|
+
and QA gates — then deploys them into any project.
|
|
7
|
+
|
|
8
|
+
> Extracted from a production project so the "agents / subagents / guardrails /
|
|
9
|
+
> personas" layer is **not** an inherent part of the app codebase. It lives in its
|
|
10
|
+
> own repo and is installed via `npx opencode-agent-harness init`.
|
|
11
|
+
|
|
12
|
+
> **OpenCode V2 (2.0.29+), V2-native.** The harness ships the V2 plugin API
|
|
13
|
+
> (`@opencode/plugin`; plugins default-export `{ id, setup }` and register tools
|
|
14
|
+
> via `ctx.tool.transform` and behavior via `ctx.tool`/`ctx.session`/`ctx.shell`/
|
|
15
|
+
> `ctx.permission`/`ctx.event` hooks) — V1 plugin implementations do **not** run in
|
|
16
|
+
> V2. Configuration is native V2 (`permissions`, `agents`, `mcp.servers`, no
|
|
17
|
+
> `small_model`), commands live in `.opencode/commands/`, and the always-loaded
|
|
18
|
+
> project instructions are `AGENTS.md` (V2 ignores the `instructions` config key).
|
|
19
|
+
|
|
20
|
+
## Prerequisites
|
|
21
|
+
|
|
22
|
+
- **OpenCode V2** (`opencode --version` >= 2.0.29). The harness ships V2 plugins
|
|
23
|
+
and does not run on V1.
|
|
24
|
+
- **Node.js >= 20** and **git**.
|
|
25
|
+
- The default model routing targets the `opencode-go` provider. If you use a
|
|
26
|
+
different provider, edit the `model:` lines in `.opencode/agents/*.md` and
|
|
27
|
+
`opencode.json` after `init`; the routing policy is documented in
|
|
28
|
+
`.agents/memory/model-routing.md`.
|
|
29
|
+
|
|
30
|
+
`init` writes into the target directory and does **not** commit or push by
|
|
31
|
+
default. Preview first with `--dry-run`.
|
|
32
|
+
|
|
33
|
+
## Why
|
|
34
|
+
|
|
35
|
+
- The agent harness is tooling, not application code. Its source lives in the
|
|
36
|
+
npm package — you deploy it with `init`/`update` rather than hand-copying it
|
|
37
|
+
into every repo.
|
|
38
|
+
- One canonical, versioned source of truth for personas/rules/QA tiers, deployed
|
|
39
|
+
on demand and updatable via `npx opencode-agent-harness update`.
|
|
40
|
+
|
|
41
|
+
## Install & initialize
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
# from anywhere (uses a target dir or defaults to cwd)
|
|
45
|
+
npx opencode-agent-harness init --target /path/to/project --name "MyApp" --domain "a widget catalog"
|
|
46
|
+
|
|
47
|
+
# non-interactive
|
|
48
|
+
npx opencode-agent-harness init --target . --yes
|
|
49
|
+
|
|
50
|
+
# preview what would change, without writing anything
|
|
51
|
+
npx opencode-agent-harness init --target . --dry-run
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
`init` writes:
|
|
55
|
+
|
|
56
|
+
| Path | Content | Ownership |
|
|
57
|
+
|---|---|---|
|
|
58
|
+
| `AGENTS.md` | always-loaded project instructions (OpenCode V2 reads `AGENTS.md`; the V1 `instructions` key is ignored) | harness (overwrite) |
|
|
59
|
+
| `BACKLOG.md` | canonical task list (Open / In progress / Frozen / Archive / Not tracking) | **project** (create-if-missing) |
|
|
60
|
+
| `.opencode/agents/*.md` | 15 persona subagent defs (native V2 frontmatter: `model: provider/model#variant`, `permissions`, `steps`, `hidden`) | harness (overwrite) |
|
|
61
|
+
| `.agents/AGENTS.md` | full canonical operating rulebook (V2 auto-discovers it as you work under `.agents/`) | harness (overwrite) |
|
|
62
|
+
| `.agents/rules/00-operating.md` | expanded operating rules (referenced from `AGENTS.md`; V2 ignores the `instructions` config key) | harness (overwrite) |
|
|
63
|
+
| `.agents/skills/*/SKILL.md` | persona instruction skills (V2 also discovers `.agents/skills/` as skills) | harness (overwrite) |
|
|
64
|
+
| `.agents/features/INDEX.md` | pointer to `BACKLOG.md` (per-feature doc tree root) | **project** (create-if-missing) |
|
|
65
|
+
| `opencode.json` | main model + `agents` defaults (small-model on `title`, opportunistic `explore`) + the `permissions` baseline | harness (**merged**, see below) |
|
|
66
|
+
| `scripts/qa/*` | `test:dispatch` / `test:governance` / `test:qa-plan` / `test:prefix` gates + QA-script wiring check | harness (overwrite) |
|
|
67
|
+
| `scripts/backlog.js` | deterministic `BACKLOG.md` editor (list/add/take/archive/freeze) | harness (overwrite) |
|
|
68
|
+
| `.opencode/plugins/backlog.ts` | `backlog_*` custom tools the LLM calls (V2 plugin registering the tools; shells out to the CLI) | harness (overwrite) |
|
|
69
|
+
| `.opencode/plugins/backlog-notify.ts` | structured log whenever an agent mutates the board | harness (overwrite) |
|
|
70
|
+
| `.opencode/plugins/context-guard.ts` | mid-session checkpoint/loop nudges read from `orchestration.md` (core: `scripts/qa/context-guard-core.js`) | harness (overwrite) |
|
|
71
|
+
| `.opencode/plugins/session.ts` | `session_info` tool — reports the primary orchestrator session id (the handoff `session:` join key) + observed cost/tokens/turns | harness (overwrite) |
|
|
72
|
+
| `.opencode/plugins/checkpoint.ts` | `checkpoint_write` / `checkpoint_resume` tools (shell out to `scripts/checkpoint.js`) | harness (overwrite) |
|
|
73
|
+
| `.opencode/commands/checkpoint.md`, `.opencode/commands/resume.md` | mid-session checkpoint + bounded resume-from-checkpoint commands | harness (overwrite) |
|
|
74
|
+
| `scripts/checkpoint.js` | deterministic checkpoint write/replace/read for one session handoff (no timestamps, `unknown` for absent state) | harness (overwrite) |
|
|
75
|
+
| `scripts/ship.js` | deterministic branch lander (`npm run ship`): rebase on `origin/main`, branch gates, direct fast-forward push of `HEAD:main`, then wait for green CI on the landed SHA | harness (overwrite) |
|
|
76
|
+
| `scripts/qa/check-prefix-stability.js` | `test:prefix` gate — fails a volatile value (clock timestamp, machine path, session id) in the always-loaded prompt prefix | harness (overwrite) |
|
|
77
|
+
| `.github/workflows/{ci,deploy-uat,uat-health}.yml` | CI gate, CI-triggered artifact deploy, health probe — the self-contained release cycle `ship` drives | **project** (create-if-missing) |
|
|
78
|
+
| `.husky/pre-push` | pre-push battery (harness process gates + project test gates) | **project** (create-if-missing) |
|
|
79
|
+
| `.vercelignore` | keeps worktree symlinks (`node_modules`, `prisma/generated`) out of the remote build | **project** (create-if-missing) |
|
|
80
|
+
| `docs/ci-cd-pipeline.md` | the pipeline reference (setup, secrets/variables, rollback) | **project** (create-if-missing) |
|
|
81
|
+
| `scripts/agent-report.js` | deterministic dispatch report (`--cost` joins observed provider telemetry; `--json` schema `agent-report/1`) | harness (overwrite) |
|
|
82
|
+
| `scripts/qa/provider-stats.js` | observed cost/token/turn telemetry from the local opencode store (no sqlite dependency) | harness (overwrite) |
|
|
83
|
+
| `scripts/qa/session-recon.js` | tool-habit / context-hygiene recon (shell tool-choice, `cd`-chaining, whole-file + repeated reads, guessed paths, dumps, polling, dispatch sizes; `report:recon`) | harness (overwrite) |
|
|
84
|
+
| `.agents/memory/*` | project data (domain-map, stack-versions, locations, model-routing, orchestration, history, flow-map, product-principles, quality-parameters, test-design-parameters) | **project** (create-if-missing) |
|
|
85
|
+
| `.agents/reviews/*` | project data (durable review/audit deliverables — REPORT.md + scans, tagged by quality-parameters) | **project** (create-if-missing) |
|
|
86
|
+
| `.agents/handoffs/*` | project data (one session handoff file per session — sharded so concurrent sessions never collide) | **project** (create-if-missing) |
|
|
87
|
+
| `.agents/qa-plans/*` | project data (one QA plan file per change — sharded so concurrent sessions never collide) | **project** (create-if-missing) |
|
|
88
|
+
| `.harness.json` | deployed version + project profile + per-file checksums | harness |
|
|
89
|
+
| `.gitignore` | **project-owned** — deployment never reads or rewrites it; harness local-only artifact patterns go to the clone-local `.git/info/exclude` | project |
|
|
90
|
+
| `.gitattributes` | harness-managed section (`BACKLOG.md merge=backlog` — the row-aware merge driver) merged in, project entries preserved | harness (merged) |
|
|
91
|
+
|
|
92
|
+
### `opencode.json` is merged, not clobbered
|
|
93
|
+
|
|
94
|
+
The harness owns only `$schema`, `model`, its `agents` defaults
|
|
95
|
+
(`title`/`build`/`explore` — the V2 small-model pin lives on `agents.title.model`)
|
|
96
|
+
and the `permissions` baseline. Every other key your project adds — extra
|
|
97
|
+
`permissions`, `mcp.servers`, `plugins`, custom `agents`, etc. — is preserved
|
|
98
|
+
across `init`/`update` (the `permissions` array is unioned and `agents` is
|
|
99
|
+
add-only per agent). This is the **native V2 shape**: there is no V1
|
|
100
|
+
`small_model`, singular `agent`, keyed `permission`, or `instructions` key.
|
|
101
|
+
|
|
102
|
+
## Placeholders
|
|
103
|
+
|
|
104
|
+
Templates use `{{PROJECT_NAME}}` and `{{PROJECT_DOMAIN}}`; `init` substitutes
|
|
105
|
+
them from `--name` / `--domain` (or prompts, or `.harness.json`). Domain facts
|
|
106
|
+
that are genuinely project-specific (entity model, external sources, visibility
|
|
107
|
+
tiers, trust tiers) live in `.agents/memory/domain-map.md`, which `init`
|
|
108
|
+
scaffolds for you to fill in — the skills and rules reference memory instead of
|
|
109
|
+
hardcoding domain assumptions.
|
|
110
|
+
|
|
111
|
+
**Features (`.agents/features/`)** — the durable, feature-centric plan of record. A
|
|
112
|
+
found item is captured as one light row in the canonical `BACKLOG.md` (repo root; the
|
|
113
|
+
single write-path for all open work: what's known, priority, evidence). When a feature
|
|
114
|
+
is picked up, the `features` persona authors the per-feature doc chain
|
|
115
|
+
(`.agents/features/<slug>/`), each layer routed to its author persona — `intent.md`
|
|
116
|
+
(product-manager) → `scope.md` (system-architect, HIGH-risk only) → `plan.md` (planner)
|
|
117
|
+
→ `tests.md` (qa-architect, points to the feature's QA plan). Ceremony is right-sized to blast
|
|
118
|
+
radius: trivial → none, low → single `intent.md`, high (auth/DB/public API/flow-siblings)
|
|
119
|
+
→ full chain. Docs live beside the code, are written-back before continuing when
|
|
120
|
+
implementation invalidates them, and are archived on ship. `.agents/features/INDEX.md`
|
|
121
|
+
is a pointer to `BACKLOG.md`. See `.agents/skills/features/SKILL.md`.
|
|
122
|
+
|
|
123
|
+
**Product-first planning (`.agents/memory/product-principles.md`)** — the project-owned
|
|
124
|
+
product concepts (actors, product concepts, UX heuristics, design language, key journeys,
|
|
125
|
+
value-maximization rules) that LEAD planning. The `planner` reads it (plus a feature's
|
|
126
|
+
`intent.md`) before emitting a dispatch plan and sequences work value-first — smallest
|
|
127
|
+
slice that delivers the core outcome first — rather than by tech dependency. `intent.md`
|
|
128
|
+
must define Actor(s) → Need → Outcome → Acceptance criteria, and `plan.md` a Value-first
|
|
129
|
+
sequence + Product concepts applied; `npm run test:product` fails a feature that reaches
|
|
130
|
+
planning/implementation without them (a plan with no intent, or an intent that never
|
|
131
|
+
names a user/need/outcome). Fill `product-principles.md` in at `init`; evolve it as the
|
|
132
|
+
product does — see `.agents/skills/planner/SKILL.md` and
|
|
133
|
+
`.agents/skills/features/SKILL.md`.
|
|
134
|
+
|
|
135
|
+
**Flow map (`.agents/memory/flow-map.md`)** — the project-owned registry powering the
|
|
136
|
+
flow-closure half of `test:qa-plan`. Each user-facing flow lists the code surfaces that
|
|
137
|
+
implement the same behavior across codebases/layers (e.g. web component, `mobile/` sheet,
|
|
138
|
+
API route) plus its optional variants (e.g. `condition-selector-present` vs `-absent`). Fill
|
|
139
|
+
it in so a change to one surface is forced to account for all the others. If empty, the gate
|
|
140
|
+
warns but does not block; the guarantee only applies to registered flows.
|
|
141
|
+
|
|
142
|
+
**Environment registry (`.agents/memory/environments.md`)** — the project-owned
|
|
143
|
+
canonical registry of the three environments: **development** (dirty by design —
|
|
144
|
+
QA/test data lives and dies here), **User Acceptance (`uat`)**, and **production**
|
|
145
|
+
(both enforced clean). The rulebook's non-negotiable law: only **code**, **schema
|
|
146
|
+
migrations** (`prisma migrate deploy`), and **idempotent seeds** move forward
|
|
147
|
+
(dev → uat → prod); **data never does** — no dump/restore across environments.
|
|
148
|
+
Live QA tiers target the `development` DB only. Finalizing a task means deploying
|
|
149
|
+
to **uat**: the Definition of Done routes it through `devops-engineer` →
|
|
150
|
+
`deploy:uat`, then verifies the boundary with `test:data-hygiene -- --env uat`.
|
|
151
|
+
Production is human-gated and out of the per-task flow. The harness scaffolds
|
|
152
|
+
`environments.md` (create-if-missing, project-owned) and reminds projects to wire
|
|
153
|
+
`deploy:uat` / `deploy:prod` / `test:data-hygiene` via `check-qa-scripts.js`.
|
|
154
|
+
|
|
155
|
+
**Orchestration & context budget (`.agents/memory/orchestration.md`)** — the
|
|
156
|
+
project-owned tuning file for the cost/context guards the operating rules
|
|
157
|
+
reference: the main-orchestrator soft turn budget / hard safety ceiling, the
|
|
158
|
+
request-context observe → warn → checkpoint → intervene thresholds, dispatch
|
|
159
|
+
fan-out review bands, and the stuck/retry-loop heuristics. Shipped with sensible
|
|
160
|
+
experimental defaults; tune from post-change data and record why. Scaffolded
|
|
161
|
+
create-if-missing (project-owned).
|
|
162
|
+
|
|
163
|
+
**Bounded orchestration & structured session telemetry** — the harness keeps the
|
|
164
|
+
main context from growing unbounded: one bounded orchestration lifecycle per work
|
|
165
|
+
unit, compact deterministic checkpoints into the session's `.agents/handoffs/<id>.md`
|
|
166
|
+
when a session nears its budget (see `orchestration.md`), and a fresh context that
|
|
167
|
+
resumes from the checkpoint instead of replaying the transcript. The
|
|
168
|
+
**`context-guard` plugin** makes the budgets mechanical: it parses
|
|
169
|
+
`orchestration.md` at runtime (thresholds are never hardcoded) and nudges the
|
|
170
|
+
primary orchestrator session as it crosses them — turn bands AND request-token
|
|
171
|
+
levels (whichever is stronger), flags repeated identical tool calls, whole turns
|
|
172
|
+
with no material state change, and repeated failures sharing a signature, and
|
|
173
|
+
records band/request/loop/no-state/failure crossings in
|
|
174
|
+
`.agents/guard-events.jsonl` (local-only, excluded clone-locally). It also
|
|
175
|
+
**blocks two tool calls outright**: a `git checkout`/`git switch` that would move
|
|
176
|
+
HEAD under another live session in the same checkout, and any code change aimed
|
|
177
|
+
at the shared `main` checkout before the session isolates into its feature
|
|
178
|
+
worktree (`backlog worktree <id>`) — board/`.agents`/docs maintenance on `main`
|
|
179
|
+
stays allowed. A git op is judged by the paths it actually moves (explicit
|
|
180
|
+
pathspecs, or the live index/upstream diff for a whole-index `commit`/`push`)
|
|
181
|
+
against the checkout it selects, so `git -C <main>` is resolved rather than
|
|
182
|
+
bypassed. At the
|
|
183
|
+
checkpoint band the nudge is imperative: write ONE checkpoint, then stop at the
|
|
184
|
+
current **phase boundary** — a fresh bounded context resumes from it. The nudge is
|
|
185
|
+
injected **cache-safely**: it is appended as a synthetic tail message via the V2
|
|
186
|
+
`context` session hook (`ctx.session.hook("context")`), never written into the
|
|
187
|
+
system prompt — a
|
|
188
|
+
system-prompt change on a band crossing evicts the provider's entire prompt cache
|
|
189
|
+
and re-bills the whole transcript at full input price (measured: every full-price
|
|
190
|
+
re-read landed on turn 50/60/80/100). Appending at the tail keeps the cached
|
|
191
|
+
prefix byte-stable. Every handoff can
|
|
192
|
+
carry a `## Session metadata` block (`session`, `work_type`, `outcome`,
|
|
193
|
+
`termination_reason`, `checkpoint_count`, `model_escalation_evidence` —
|
|
194
|
+
controlled vocabularies, never fabricated) that `npm run report` aggregates
|
|
195
|
+
deterministically per feature.
|
|
196
|
+
`npm run report -- --cost --since=14d` (also `npm run report:cost`) closes the
|
|
197
|
+
telemetry loop: the `session_info` tool returns the primary session id, and
|
|
198
|
+
`agent-report` joins it to observed provider data
|
|
199
|
+
(`scripts/qa/provider-stats.js` reads the local opencode store, including
|
|
200
|
+
registered git worktrees) — totals, model mix by tier, cache-read share, P50/P90
|
|
201
|
+
cost and turns, >60-turn sessions, identical-call loop candidates, mid-cycle
|
|
202
|
+
context resets (resume/checkpoint sessions), and **cost per shipped feature**
|
|
203
|
+
(primary session + its subagent sessions = one feature run).
|
|
204
|
+
A primary session observed on an `escalation_models:` model is flagged when no
|
|
205
|
+
`model_escalation_evidence` / `## Escalations` reason is recorded — escalation is
|
|
206
|
+
visible, never assumed. Nothing is inferred from text length.
|
|
207
|
+
|
|
208
|
+
**End-to-end auto-resume (`agent-harness run`)** — chains bounded orchestration
|
|
209
|
+
contexts so a full delivery cycle (pick → plan → implement → QA → gates → ship →
|
|
210
|
+
land → UAT deploy) completes without a manual resume per phase. It runs the
|
|
211
|
+
next-item workflow, and whenever a phase ends with the feature not landed, it
|
|
212
|
+
launches a fresh opencode session that resumes from the checkpoint only. It stops
|
|
213
|
+
on landed (archived row or shipped outcome), the phase cap, an empty queue, or a
|
|
214
|
+
failed phase that did not land. The decision core
|
|
215
|
+
(`scripts/qa/run-loop.js`) is pure and unit-tested; `--dry-run` prints the phase
|
|
216
|
+
plan.
|
|
217
|
+
|
|
218
|
+
## Model routing & enforcement
|
|
219
|
+
|
|
220
|
+
- Concrete models are set in `.opencode/agents/<name>.md` (`model:
|
|
221
|
+
provider/model#variant`) and `opencode.json` (`model`, plus `agents.title.model`
|
|
222
|
+
for the small-model pin).
|
|
223
|
+
- Personas also carry mechanical guardrails in native V2 `permissions` frontmatter:
|
|
224
|
+
- thinkers (`planner`, `product-manager`) → `edit` deny-by-default with a narrow
|
|
225
|
+
artifact write grant (planner → `.agents/features/<feature>/plan.md`,
|
|
226
|
+
product-manager → `.agents/features/<feature>/intent.md`, each writable in the
|
|
227
|
+
main tree or the feature's `.worktrees` sibling), plus a `shell` deny
|
|
228
|
+
- `qa-architect`, `handoff`, `docs` → a `shell` deny
|
|
229
|
+
- code personas (`frontend-engineer`, `mobile-engineer`, `ui-designer`,
|
|
230
|
+
`data-engineer`, `devops-engineer`, `security-engineer`, `system-architect`,
|
|
231
|
+
`diagnostics-expert`) → an `edit` allow narrowed by denies for
|
|
232
|
+
`opencode.json`, `.harness.json`, `.opencode/**`, `.agents/**` (governance
|
|
233
|
+
and harness files are read-only), plus a `shell` allow
|
|
234
|
+
- deterministic personas → a `#low` **model variant** (`model: <provider/model>#low`) — V2 treats `request.body.temperature` as a no-op, so the old temperature pin was replaced by the variant
|
|
235
|
+
- all personas → a `steps:` cap (cost ceiling)
|
|
236
|
+
- `planner`, `handoff` → `hidden: true`
|
|
237
|
+
- `.agents/skills/*/SKILL.md` carries a `model:` label only (informational).
|
|
238
|
+
- `npx opencode-agent-harness list` prints the persona → model mapping.
|
|
239
|
+
- `npm run test:dispatch` mechanically verifies model pins against
|
|
240
|
+
`scripts/qa/models.allowlist.txt` and that `model-routing.md` does not name a
|
|
241
|
+
stale model no longer pinned anywhere (doc↔config drift). Concrete IDs on the
|
|
242
|
+
machine-readable `opportunistic_models:` / `escalation_models:` lines are
|
|
243
|
+
legal declared targets, not drift.
|
|
244
|
+
- **Opportunistic tier** (`.agents/memory/model-routing.md`): free/low-cost
|
|
245
|
+
models for best-effort bulk exploration/summarization, pinned through
|
|
246
|
+
`opencode.json` `agents.explore.model` (default `opencode-go/glm-5.3-flash`) and
|
|
247
|
+
ADD-ONLY overridable per project — with a mandatory fallback to the persona's
|
|
248
|
+
normal tier and a no-confidential-data caveat. `report` classifies the model
|
|
249
|
+
mix by tier.
|
|
250
|
+
- **Provider priority & fallback**: models run on the **OpenCode Go
|
|
251
|
+
subscription first** (`opencode-go/*`), with **DeepSeek direct**
|
|
252
|
+
(`deepseek/*`) as the pay-per-token fallback — except the **V4 Pro architect
|
|
253
|
+
tier** (`planner`, `qa-architect`, `system-architect`, `security-engineer`),
|
|
254
|
+
which always pins **direct `deepseek/deepseek-v4-pro`**. Every fallback is
|
|
255
|
+
announced immediately (a fallback the user cannot see is a silent process
|
|
256
|
+
change).
|
|
257
|
+
- **Provider funds stop**: a provider funds/quota error (`insufficient
|
|
258
|
+
balance`/`funds`/`credits`, usage limit, HTTP 402) is a hard stop, never a
|
|
259
|
+
silent inline degrade: the orchestrator announces the failed provider/model and
|
|
260
|
+
the exact unfinished step, checkpoints, and waits for the user's explicit
|
|
261
|
+
top-up-complete message. The `context-guard` plugin mechanically detects such
|
|
262
|
+
an error from **structured failure evidence only** — a failed dispatch
|
|
263
|
+
(`task` error), a non-zero-exit command, or a subagent session error — and
|
|
264
|
+
injects the same stop; reading a document that merely quotes the rule (the
|
|
265
|
+
session-start `model-routing.md`, a handoff, a plan) never trips it.
|
|
266
|
+
- **`/switch-model` command** — every deploy ships an opencode command
|
|
267
|
+
(`.opencode/commands/switch-model.md`) plus per-platform twins
|
|
268
|
+
`scripts/switch-reasoning-model.ps1` (Windows PowerShell) and
|
|
269
|
+
`scripts/switch-reasoning-model.sh` (WSL/Linux/macOS; the command invokes this
|
|
270
|
+
one on POSIX). It rewrites the main `opencode.json` `model` and the six
|
|
271
|
+
reasoning-tier agents (planner, system-architect, security-engineer,
|
|
272
|
+
diagnostics-expert, product-manager, qa-architect) in one step — a blunt
|
|
273
|
+
override of the tiered default. Aliases: `go`/`go-flash`/`go-deepseek` →
|
|
274
|
+
`opencode-go/deepseek-v4.1-flash` (default, OpenCode Go), `go-pro` →
|
|
275
|
+
`opencode-go/deepseek-v4-pro` (Go escalation),
|
|
276
|
+
`deepseek`/`flash`/`direct` → `deepseek/deepseek-flash` (direct fallback),
|
|
277
|
+
`deepseek-v4-flash` → `deepseek/deepseek-v4-flash` (legacy V4 pin),
|
|
278
|
+
`pro`/`deepseek-pro`/`deepseek-v4-pro` → `deepseek/deepseek-v4-pro`
|
|
279
|
+
(direct escalation), `nvidia`/`kimi`/`kimi-k3` →
|
|
280
|
+
`nvidia/moonshotai/kimi-k3` (NVIDIA NIM), `nemotron`/`nemotron-ultra` →
|
|
281
|
+
`nvidia/nemotron-3-ultra-550b-a55b:free` (NVIDIA NIM, free),
|
|
282
|
+
`openrouter`/`or`/`minimax-m3`/`m3` → `openrouter/minimax/minimax-m3`
|
|
283
|
+
(OpenRouter), or any explicit `provider/model`. Restart opencode after
|
|
284
|
+
switching (config reads once).
|
|
285
|
+
- **`/board` command** — every deploy ships an opencode command
|
|
286
|
+
(`.opencode/commands/board.md`) that runs the deterministic `scripts/backlog.js
|
|
287
|
+
list` and shows the active rows verbatim — no LLM filtering, no re-ordering, no
|
|
288
|
+
transformation. Read-only, no git — the local file is the source of truth.
|
|
289
|
+
|
|
290
|
+
### Backlog management — fast, deterministic, no LLM in the loop
|
|
291
|
+
|
|
292
|
+
`BACKLOG.md` is the single source of truth; it is managed by a **deterministic
|
|
293
|
+
Node CLI** (no model round-trip) that both humans and agents share:
|
|
294
|
+
|
|
295
|
+
```bash
|
|
296
|
+
npm run backlog -- list # In progress + Open, evidence on its own line (add --all for Frozen/Archive, --full to skip truncation)
|
|
297
|
+
npm run backlog -- add "NLI search times out" --p P2 --evidence docs/issues.md
|
|
298
|
+
npm run backlog -- take F-001 --handoff .agents/handoffs/F-001.md
|
|
299
|
+
npm run backlog -- archive F-001 --closed "shipped 2026-09-04"
|
|
300
|
+
npm run backlog -- freeze F-002 --why "not now" --reopen "customer asks"
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
`list` renders each row on two lines (task on top, evidence/handoff/reopen on a
|
|
304
|
+
labeled line below) and truncates long cells by default for scannability — pass
|
|
305
|
+
`--full` for the untruncated text. The `backlog_list` tool always uses `--full`
|
|
306
|
+
so agents see complete descriptions.
|
|
307
|
+
|
|
308
|
+
- The CLI validates the schema (`P1..P4`, non-empty evidence/handoff/reopen, `Depends on`
|
|
309
|
+
references naming real rows), generates unique IDs, and sorts `Open` by priority — every
|
|
310
|
+
write stays `npm run test:backlog`-green.
|
|
311
|
+
- **Dependencies are machine-readable**: a row's `Depends on` cell (`backlog depends <id>
|
|
312
|
+
--on F-039,F-041` / `backlog add ... --depends-on ...`) lists IDs that must be archived
|
|
313
|
+
first. `/next`, `take`, and `worktree` skip or refuse a row whose dependencies aren't
|
|
314
|
+
archived — no more "until F-041" living in prose.
|
|
315
|
+
- **Isolation is a worktree per feature**: `backlog worktree <id>` (from the MAIN tree)
|
|
316
|
+
creates a `git worktree` + branch and auto-takes the row. The branch is based on the
|
|
317
|
+
current upstream (`origin/main`), never a stale local HEAD, and `--no-track` keeps it
|
|
318
|
+
from silently tracking main. Every feature works in its own checkout — `main` stays
|
|
319
|
+
board + shippable code only — so one session's uncommitted work can't leak into another's
|
|
320
|
+
pre-push gate. Worktrees land in a single hidden container sibling,
|
|
321
|
+
`<repo>/../.worktrees/<repo>/<id>`, so the parent folder (e.g. `C:\develop`) only ever
|
|
322
|
+
holds top-level projects. Pass `--open` to launch the agent CLI *in the new worktree*
|
|
323
|
+
after the board is written, so the session is root-scoped there and its lease + gates
|
|
324
|
+
never land in `main`. If the worktree is instead created **mid-session** (no `--open`),
|
|
325
|
+
the tools forward their session id and the CLI records the target at
|
|
326
|
+
`.serve/sessions/<id>.worktree`; `backlog_*`, `checkpoint_*`, and `session_info` then
|
|
327
|
+
follow the session into the worktree, and `archive` clears the pointer. `backlog archive
|
|
328
|
+
<id>` removes the shipped feature's worktree + merged branch, so a session cleans up
|
|
329
|
+
after itself on close.
|
|
330
|
+
- **Single-authority board (main-checkout freshness)**: because a feature's commits reach
|
|
331
|
+
`origin/main` from its own worktree, the MAIN checkout's board can lag origin until it is
|
|
332
|
+
pulled. Every mutating command in the MAIN checkout is therefore a transaction
|
|
333
|
+
(`scripts/qa/board-sync.js`): fetch → row-aware reconcile against `origin/main` (an
|
|
334
|
+
archived-upstream row wins over a stale local take; local-only rows survive) → apply →
|
|
335
|
+
commit → fast-forward push. Main never carries an uncommitted board copy, so a mutation
|
|
336
|
+
can never resurrect a shipped row; a genuine non-board local edit fails closed with an
|
|
337
|
+
actionable message, while a redundant one (already identical to upstream) is cleared
|
|
338
|
+
losslessly. `ship`'s post-landing convergence runs the same logic under the board lock
|
|
339
|
+
(so it can't race a concurrent `backlog` command) and runs even when CI is red.
|
|
340
|
+
`backlog sync` publishes offline edits later; `agent-harness doctor` warns when the
|
|
341
|
+
checkout is behind. `agent-harness update` likewise fast-forwards a stale target before
|
|
342
|
+
it auto-commits and refuses to commit onto a diverged branch (`--no-fetch` skips the
|
|
343
|
+
network step for `backlog`).
|
|
344
|
+
- **Row-aware merge driver**: `.gitattributes` routes `BACKLOG.md` through
|
|
345
|
+
`scripts/qa/merge-backlog.js` (wired by `init`/`update`), so two sessions editing
|
|
346
|
+
*disjoint* rows merge by ID instead of conflicting — concurrent take/archive no longer
|
|
347
|
+
produces a `BACKLOG.md` merge conflict.
|
|
348
|
+
- **Owned files**: `backlog owns <id> --files "scripts/test-*.ts, scripts/qa/routes.js"`
|
|
349
|
+
records the files a row owns in `.agents/memory/owned-files.md`, sharpening
|
|
350
|
+
`test:concurrency` to fail *exactly* when two In-progress rows own the same file.
|
|
351
|
+
- **Agents use the same path** via opencode custom tools (`backlog_add`,
|
|
352
|
+
`backlog_take`, `backlog_archive`, `backlog_freeze`, `backlog_depends`, `backlog_owns`,
|
|
353
|
+
`backlog_worktree`, `backlog_list`) that shell
|
|
354
|
+
out to the CLI — never hand-edit `BACKLOG.md`.
|
|
355
|
+
- A **notify plugin** (`.opencode/plugins/backlog-notify.ts`) writes a structured
|
|
356
|
+
log the moment an agent mutates the board. V2 server plugins have no TUI, so
|
|
357
|
+
this is a console log (visible in the opencode log), not the V1 toast — but it
|
|
358
|
+
still surfaces "an agent finished an item" without a manual refresh.
|
|
359
|
+
|
|
360
|
+
### Permission model & limits
|
|
361
|
+
|
|
362
|
+
- **Ordering is last-match-wins, so a project rule can shadow a harness deny.**
|
|
363
|
+
V2 applies `permissions` in order (global → project → agent) and the *last*
|
|
364
|
+
matching rule wins. `init`/`update` append a project's own rules **after** the
|
|
365
|
+
harness rules, so a project-level `allow` can override a harness `deny` (for
|
|
366
|
+
example the credential denies). The deployed baseline is ordered safely
|
|
367
|
+
(denies after the work-root allow), but a hand-added project rule is stronger
|
|
368
|
+
than the baseline — audit project `permissions` whenever a deny must be
|
|
369
|
+
absolute, and treat the project layer as a deliberate escape hatch.
|
|
370
|
+
- **`permissions` gate tool *selection*, not the host.** They are advisory to
|
|
371
|
+
the model; a `shell` call runs with the host user's full authority regardless
|
|
372
|
+
of the rules (V2's own docs say so). The harness compensates with mechanical
|
|
373
|
+
guards — the capacity envelope, the main-checkout / branch-switch guard,
|
|
374
|
+
per-feature worktrees, session leases — not a kernel sandbox. Keep secrets off
|
|
375
|
+
the box, and prefer a container or a dedicated user for untrusted work.
|
|
376
|
+
|
|
377
|
+
## QA gates
|
|
378
|
+
|
|
379
|
+
- `npm run test:dispatch` — persona model-pin preflight + persona↔skill parity + model-routing↔pin drift check.
|
|
380
|
+
- `npm run test:governance` — session wrap-up dispatch-log enforcement.
|
|
381
|
+
- `npm run test:backlog` — canonical single-backlog gate: `BACKLOG.md` is the one
|
|
382
|
+
source of truth; status/priority enums, frozen-reopen conditions, non-empty
|
|
383
|
+
priority/evidence (and non-empty task/handoff on `In progress` rows), no
|
|
384
|
+
duplicate IDs, `Depends on` cells that name real rows, and `INDEX.md`/`todo.md`
|
|
385
|
+
must be pointers (not live lists). Reports an over-wide row honestly ("row F-127
|
|
386
|
+
has 7 cells, expected 6 — unescaped `|`") instead of surfacing a shifted cell as
|
|
387
|
+
a bogus "depends on unknown row".
|
|
388
|
+
- `npm run test:concurrency` — cross-session working-tree guard. Fails when the
|
|
389
|
+
board shows 2+ `In progress` rows while the tree has uncommitted changes; with
|
|
390
|
+
owned files declared (`.agents/memory/owned-files.md`), it fails *exactly* when
|
|
391
|
+
a dirty file is owned by two In-progress rows (or a tree mixes two sessions'
|
|
392
|
+
WIP). The shared `BACKLOG.md` itself is treated as owned by every In-progress
|
|
393
|
+
row, so a dirty board under 2+ active sessions is a hard failure. It also
|
|
394
|
+
refuses two live *primary sessions* on one checkout via `.serve/sessions/`
|
|
395
|
+
leases written by the context-guard plugin — liveness requires the pid **and** a
|
|
396
|
+
matching process birth token (`bootId` + `/proc` starttime) **and** a fresh
|
|
397
|
+
heartbeat, so a recycled pid or a closed TUI can't masquerade as a live session.
|
|
398
|
+
`node scripts/qa/check-concurrency.js --prune` clears dead/recycled/stale leases
|
|
399
|
+
(the plugin also sweeps at startup).
|
|
400
|
+
- `npm run test:integrate` — pre-push rebase check: fails when the current branch
|
|
401
|
+
is behind `origin/main`, reminding you to `git rebase` and re-run the board +
|
|
402
|
+
concurrency gates before pushing, so conflicts surface early.
|
|
403
|
+
- `npm run test:quality` — **mechanical code-quality gate on new/grown code**:
|
|
404
|
+
flags dead exports (a symbol whose only reference is its own declaration) and
|
|
405
|
+
files that are new or grew past the line limit (default 1000). Runs against the
|
|
406
|
+
diff by default (`--paths a,b` to target files, `--base <ref>` to set the
|
|
407
|
+
baseline, `--strict` for CI). Canonical rubric: `.agents/memory/quality-parameters.md`.
|
|
408
|
+
- `npm run test:wiring` — **orphan-test gate**: every `*.test.*` / `*.spec.*`
|
|
409
|
+
file must be executed by some package script (directly, as a directory prefix,
|
|
410
|
+
or via a glob). An authored test wired into no tier is neither protection nor a
|
|
411
|
+
failure signal — test-design parameter T7. Default-discovery runners (`vitest
|
|
412
|
+
run`, bare `node --test`, …) downgrade unwired files to warnings unless
|
|
413
|
+
`--strict`; a deliberate orphan carries an auditable
|
|
414
|
+
`// test-wiring-waived: reason` comment. Tags: `.agents/memory/test-design-parameters.md`.
|
|
415
|
+
- `npm run test:linger` — **exit-contract gate**: runs `test:quick` by default
|
|
416
|
+
(or an explicit command after `--`), measures real process wall-clock, parses
|
|
417
|
+
the runner's self-reported duration (`node:test` `duration_ms`, jest `Time:`,
|
|
418
|
+
vitest `Duration`), and fails when the process lingers after the tests are done
|
|
419
|
+
(T1/T6/T9) — the measured bug where 22 tests finished in 76 ms but the process
|
|
420
|
+
exited 60.4 s later. Tune with `--max-linger <sec>` / `--ratio <x>`.
|
|
421
|
+
- `npm run test:prefix` — **cache-prefix stability gate**: the always-loaded
|
|
422
|
+
prefix (root `AGENTS.md`, the rulebook, `00-operating.md`, and the session-start
|
|
423
|
+
memory reads) must carry no per-run content — clock timestamps, machine-specific
|
|
424
|
+
absolute paths, or session ids — because one changing byte breaks prompt-cache
|
|
425
|
+
locality for every later turn. Bare historical dates are fine; `BACKLOG.md`,
|
|
426
|
+
handoffs, and feature docs are out of scope.
|
|
427
|
+
- `npm run checkpoint -- write --feature <id> ...` / `resume --feature <id>` —
|
|
428
|
+
deterministic bounded-state checkpoint in `.agents/handoffs/<id>.md`
|
|
429
|
+
(agents: the `checkpoint_write` / `checkpoint_resume` tools, or `/checkpoint` /
|
|
430
|
+
`/resume`). Rewriting identical state is a no-op; changed state increments
|
|
431
|
+
`checkpoint_count`; no timestamps, `unknown` for anything not recorded.
|
|
432
|
+
- `npm run test:product` — **product/UX-first gate**: every feature doc in
|
|
433
|
+
`.agents/features/<slug>/` must define its user before planning/implementation.
|
|
434
|
+
`intent.md` must carry Actor(s) → Need → Outcome → Acceptance criteria, and `plan.md`
|
|
435
|
+
a Value-first sequence + Product concepts applied; a `plan.md` with no `intent.md`
|
|
436
|
+
fails (never plan around an undefined user need). Backward-compatible — no feature
|
|
437
|
+
docs, gate passes.
|
|
438
|
+
- `npm run test:docs` — **docs-as-code gate**: `README.md` / `docs/**` must have no
|
|
439
|
+
un-substituted `{{PLACEHOLDER}}` template vars, no dangling relative links, and every
|
|
440
|
+
ADR (`docs/adr/*.md`) must carry Context → Decision → Consequences + a Status.
|
|
441
|
+
Backward-compatible — no docs, gate passes.
|
|
442
|
+
- `npm run test:qa-plan` — **diff-coverage + flow-closure gate**:
|
|
443
|
+
every changed CODE path must have a covering assertion (or a waivered reason) in
|
|
444
|
+
a QA plan (one per-change file under `.agents/qa-plans/`) before a change is verified — and every touched flow
|
|
445
|
+
(`.agents/memory/flow-map.md`) must have every sibling surface and declared optional
|
|
446
|
+
variant addressed in the plan's `## Parallel-surface & variant audit`. Kills the
|
|
447
|
+
"verified by a suite that never touched the change" failure mode: a tier label never
|
|
448
|
+
proves coverage. It also makes **"Fix One, Fix All" mechanical**: a change to one
|
|
449
|
+
surface (e.g. web) cannot ship while the same flow in another codebase (e.g. `mobile/`)
|
|
450
|
+
silently keeps old behavior — the plan must name each sibling as covered (`->`) or
|
|
451
|
+
out-of-scope (`audited: reason`, e.g. `deferred — logged in handoffs/`).
|
|
452
|
+
- `node scripts/qa/check-qa-scripts.js` — warns (or `--strict` fails) when the
|
|
453
|
+
DoD-referenced runtime QA tiers aren't wired into `package.json`.
|
|
454
|
+
|
|
455
|
+
The harness ships only these gates. The runtime QA tiers (`test:quick`,
|
|
456
|
+
`test:routes`, `test:api`, `test:verify`, `test:security`) and their backing
|
|
457
|
+
scripts are **project-provided** — the rulebook references them, and
|
|
458
|
+
`check-qa-scripts.js` reminds you if they're missing.
|
|
459
|
+
|
|
460
|
+
## Update
|
|
461
|
+
|
|
462
|
+
```bash
|
|
463
|
+
npx opencode-agent-harness update --target /path/to/project
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
- Overwrites harness-owned files, preserves `.agents/memory/*`, `.agents/reviews/*`, `.agents/handoffs/*`, `.agents/qa-plans/*`, and `BACKLOG.md`.
|
|
467
|
+
- **Fails closed on a locally-modified harness-owned file**: if a harness-owned
|
|
468
|
+
file's bytes no longer match the checksum in `.harness.json` (someone hand-edited
|
|
469
|
+
it in the project), `update` aborts *before writing anything* and names the file.
|
|
470
|
+
Port the change into the harness `templates/` (with a drift-guard test for a
|
|
471
|
+
gate/QA script), release, and re-run — or pass `--accept-harness` to overwrite
|
|
472
|
+
deliberately. This prevents the F-289 class of incident, where a project-side
|
|
473
|
+
fix to `scripts/qa/board-sync.js` was silently clobbered by a routine deploy.
|
|
474
|
+
- Auto-wires the harness gate scripts (`test:dispatch`, `test:governance`,
|
|
475
|
+
`test:qa-plan`, `test:backlog`, `test:product`, `test:docs`, `test:quality`,
|
|
476
|
+
`test:wiring`, `test:linger`, `test:prefix`) plus the `report`,
|
|
477
|
+
`report:cost`, `checkpoint`, and `serve` helpers into the target's `package.json`
|
|
478
|
+
(merged, add-only).
|
|
479
|
+
- **Auto-commits** the harness files it changed (`chore(harness): opencode-agent-harness
|
|
480
|
+
<old> -> <new>`) and **pushes** to origin, so the next session never sees unexplained
|
|
481
|
+
modified harness files. Your unrelated uncommitted work is never staged. The push
|
|
482
|
+
uses `--no-verify` — a `chore(harness)` maintenance commit must not be stranded by a
|
|
483
|
+
project pre-push gate that legitimately refuses a direct main push.
|
|
484
|
+
- `--no-commit` to skip commit+push, `--no-push` to commit but not push,
|
|
485
|
+
`--accept-harness` to overwrite a locally-modified harness-owned file.
|
|
486
|
+
- `init` does **not** commit or push by default: pass `--commit` to commit the
|
|
487
|
+
files it scaffolds and `--push` to also push. A first run in an existing repo
|
|
488
|
+
is always reviewable before anything enters git. A pre-existing `AGENTS.md`
|
|
489
|
+
the harness did not create is refused (nothing is written); `--accept-harness`
|
|
490
|
+
overwrites it deliberately after backing it up under `.harness-backup/`.
|
|
491
|
+
- Harness-owned paths are **force-added**, so a project that gitignores deployment
|
|
492
|
+
artifacts (an inherited `.agents/` `.opencode/` `AGENTS.md` pattern) still gets the
|
|
493
|
+
harness commit instead of a raw `git add` failure that silently skips it — force-added
|
|
494
|
+
files are called out in the summary.
|
|
495
|
+
- **`[Nothing-to-Update]` confirmation**: if the target is already at this CLI's version and no
|
|
496
|
+
harness-owned file changed, `update` says so explicitly, writes nothing, and makes no commit —
|
|
497
|
+
a no-op is never mistaken for a sync and never churns `.harness.json`.
|
|
498
|
+
- **Downgrade guard**: `update` refuses to run on a target whose deployed harness is NEWER than
|
|
499
|
+
this CLI (e.g. deployed from a local checkout that was never published) and tells you to publish
|
|
500
|
+
that version first.
|
|
501
|
+
- **Published-version check**: if this CLI's version is not the latest `dist-tags.latest` on npm,
|
|
502
|
+
`update` warns you — catches the "bumped the version and updated a project from a local
|
|
503
|
+
checkout, but never published" gap before it silently forks the projects.
|
|
504
|
+
- **Non-destructive**: a locally-modified harness-owned file is backed up to
|
|
505
|
+
`.harness-backup/<timestamp>/` before any overwrite. With `--accept-harness`,
|
|
506
|
+
after the overwrite the target's own `npm run test:quick` is run **before** the
|
|
507
|
+
harness commit; if it is red the clobbered files and `.harness.json` are rolled
|
|
508
|
+
back and the commit is aborted, so a deploy can never land a broken suite.
|
|
509
|
+
- `opencode.json` is merged (project keys preserved).
|
|
510
|
+
- **Local-only excludes — never `.gitignore`**: the harness's local artifacts
|
|
511
|
+
(`.harness-backup/`, `.backlog.lock`, `.serve/`, `.agents/guard-events.jsonl`)
|
|
512
|
+
are recorded in the clone-local `.git/info/exclude` (add-only; pre-existing
|
|
513
|
+
excludes preserved). That file is untracked and never pushed, so the project's
|
|
514
|
+
committed `.gitignore` is **never** read or rewritten. (A pre-0.1.55 managed
|
|
515
|
+
`.gitignore` section truncated project entries after its marker, silently
|
|
516
|
+
un-ignoring `.env`/`data/` — FamilyBudget F-020.) New harness files are tracked
|
|
517
|
+
(committed), not ignored — so they don't need a gitignore change.
|
|
518
|
+
- **Managed `.gitattributes` + merge driver**: the harness merges a marked section
|
|
519
|
+
(`BACKLOG.md merge=backlog`) into the project's `.gitattributes` and registers the
|
|
520
|
+
row-aware driver in the local `.git/config` (`merge.backlog.driver`). The driver script is
|
|
521
|
+
committed; the config pointer is per-clone, so `init`/`update` (re)register it on every
|
|
522
|
+
deploy.
|
|
523
|
+
- `--dry-run` previews the plan without writing.
|
|
524
|
+
|
|
525
|
+
### Release cycle & `doctor`
|
|
526
|
+
|
|
527
|
+
`init` seeds a working CI/CD release scaffold create-if-missing (never overwritten,
|
|
528
|
+
so your edits survive `update`): the CI gate, the CI-triggered artifact deploy,
|
|
529
|
+
the UAT health probe, `.husky/pre-push` (process gates), `.vercelignore`, and
|
|
530
|
+
`docs/ci-cd-pipeline.md`. The cycle is:
|
|
531
|
+
|
|
532
|
+
```
|
|
533
|
+
worktree → npm run ship → direct fast-forward push to main → CI → (on CI success) deploy UAT → health probe
|
|
534
|
+
```
|
|
535
|
+
|
|
536
|
+
`ship` runs the harness process gates itself (not just via the git hook), lands
|
|
537
|
+
`HEAD:main` with a direct fast-forward push (retrying after a concurrent
|
|
538
|
+
landing), and **waits for CI to go green on the landed SHA** — the deploy runs
|
|
539
|
+
only after CI succeeds. Check readiness at any time with the deterministic report:
|
|
540
|
+
|
|
541
|
+
```bash
|
|
542
|
+
npx opencode-agent-harness doctor --target /path/to/project
|
|
543
|
+
```
|
|
544
|
+
|
|
545
|
+
It reports git/remote/branch, `gh` + auth, the CI/deploy workflows, the pre-push
|
|
546
|
+
gate, the Vercel link, and the local-only ignores. Missing infrastructure is a
|
|
547
|
+
warning; a missing prerequisite for the cycle the harness promises is a failure.
|
|
548
|
+
|
|
549
|
+
### Backlog migration (`migrate-backlog`)
|
|
550
|
+
|
|
551
|
+
```bash
|
|
552
|
+
npx opencode-agent-harness migrate-backlog --target /path/to/project
|
|
553
|
+
```
|
|
554
|
+
|
|
555
|
+
Consolidates any live `.agents/features/INDEX.md` F-rows and
|
|
556
|
+
`.agents/memory/todo.md` list items into the canonical `BACKLOG.md`, then rewrites
|
|
557
|
+
both as pointers. Idempotent — re-running never duplicates rows (it only merges into
|
|
558
|
+
an empty board) — and never deletes a source before `BACKLOG.md` is written and
|
|
559
|
+
verified. Logs a summary: `N open · M frozen · K archived`.
|
|
560
|
+
|
|
561
|
+
## Develop
|
|
562
|
+
|
|
563
|
+
```bash
|
|
564
|
+
npm test # node --test
|
|
565
|
+
npm run lint # syntax-check the CLI + QA scripts
|
|
566
|
+
node bin/agent-harness.js list
|
|
567
|
+
node bin/agent-harness.js init --target /tmp/demo --name Demo --yes
|
|
568
|
+
```
|
|
569
|
+
|
|
570
|
+
`npm test` runs the hermetic unit suite **and** `tests/plugin-loader.e2e.js` — a
|
|
571
|
+
**real-loader** check that loads the shipped plugins into a fixture location on a
|
|
572
|
+
running OpenCode service and asserts one guard event fires end-to-end (a session
|
|
573
|
+
lease). It **skips** when no service is running (always the case in CI), so
|
|
574
|
+
`npm run test:plugin-loader` is the explicit invocation on a dev box. See
|
|
575
|
+
`docs/opencode-v2-migration.md` §20.
|
|
576
|
+
|
|
577
|
+
### Running on WSL2
|
|
578
|
+
|
|
579
|
+
- Keep the checkout and target projects on the Linux filesystem
|
|
580
|
+
(`~/develop/...`), never on `/mnt/c` — Node/npm I/O over the Windows drvfs
|
|
581
|
+
mount is far slower. `init`/`update` warn when a target is on `/mnt/<drive>/`.
|
|
582
|
+
- `.gitattributes` pins `*.sh` to LF (and `*.ps1` to CRLF); the same rules are
|
|
583
|
+
merged into every deployed project, so POSIX scripts survive a Windows-side
|
|
584
|
+
checkout. See the `switch-reasoning-model.sh` POSIX twin, platform-dispatched
|
|
585
|
+
by the `/switch-model` command.
|
|
586
|
+
- Worktrees live in a sibling container (`<repo>/../.worktrees/<repo>/<id>`), so
|
|
587
|
+
allow `~/develop/**` in the global `opencode.jsonc` (an `external_directory`
|
|
588
|
+
allow rule in the `permissions` array), or each worktree access prompts.
|
|
589
|
+
|
|
590
|
+
Clear the data-test except keep `templates/` generic; do not commit a target
|
|
591
|
+
project's `.agents/memory/` into this repo.
|