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.
Files changed (169) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/LICENSE +21 -0
  3. package/README.md +590 -2
  4. package/bin/agent-harness.js +3059 -0
  5. package/contrib/global-plugins/README.md +49 -0
  6. package/contrib/global-plugins/harness-freshness.ts +355 -0
  7. package/package.json +48 -4
  8. package/templates/.agents/AGENTS.md +204 -0
  9. package/templates/.agents/features/INDEX.md +10 -0
  10. package/templates/.agents/handoffs/README.md +87 -0
  11. package/templates/.agents/memory/dev-loop.md +59 -0
  12. package/templates/.agents/memory/domain-map.md +29 -0
  13. package/templates/.agents/memory/environments.md +35 -0
  14. package/templates/.agents/memory/flow-map.md +23 -0
  15. package/templates/.agents/memory/history.md +7 -0
  16. package/templates/.agents/memory/locations.md +14 -0
  17. package/templates/.agents/memory/model-routing.md +261 -0
  18. package/templates/.agents/memory/orchestration.md +183 -0
  19. package/templates/.agents/memory/owned-files.md +19 -0
  20. package/templates/.agents/memory/product-principles.md +37 -0
  21. package/templates/.agents/memory/quality-parameters.md +37 -0
  22. package/templates/.agents/memory/stack-versions.md +35 -0
  23. package/templates/.agents/memory/test-design-parameters.md +36 -0
  24. package/templates/.agents/nightly.json +17 -0
  25. package/templates/.agents/qa-plans/README.md +70 -0
  26. package/templates/.agents/qa-runs/README.md +21 -0
  27. package/templates/.agents/reviews/README.md +47 -0
  28. package/templates/.agents/rules/00-operating.md +199 -0
  29. package/templates/.agents/skills/data-engineer/SKILL.md +31 -0
  30. package/templates/.agents/skills/devops-engineer/SKILL.md +50 -0
  31. package/templates/.agents/skills/diagnostics-expert/SKILL.md +44 -0
  32. package/templates/.agents/skills/docs/SKILL.md +140 -0
  33. package/templates/.agents/skills/features/SKILL.md +187 -0
  34. package/templates/.agents/skills/frontend-engineer/SKILL.md +81 -0
  35. package/templates/.agents/skills/handoff/SKILL.md +85 -0
  36. package/templates/.agents/skills/mobile-engineer/SKILL.md +101 -0
  37. package/templates/.agents/skills/planner/SKILL.md +112 -0
  38. package/templates/.agents/skills/product-manager/SKILL.md +115 -0
  39. package/templates/.agents/skills/qa-architect/SKILL.md +224 -0
  40. package/templates/.agents/skills/qa-runner/SKILL.md +64 -0
  41. package/templates/.agents/skills/security-engineer/SKILL.md +53 -0
  42. package/templates/.agents/skills/system-architect/SKILL.md +42 -0
  43. package/templates/.agents/skills/ui-designer/SKILL.md +71 -0
  44. package/templates/.github/workflows/ci.yml +148 -0
  45. package/templates/.github/workflows/deploy-uat.yml +95 -0
  46. package/templates/.github/workflows/nightly.yml +83 -0
  47. package/templates/.github/workflows/uat-health.yml +41 -0
  48. package/templates/.husky/pre-push +23 -0
  49. package/templates/.ignore +28 -0
  50. package/templates/.opencode/agents/data-engineer.md +37 -0
  51. package/templates/.opencode/agents/devops-engineer.md +37 -0
  52. package/templates/.opencode/agents/diagnostics-expert.md +37 -0
  53. package/templates/.opencode/agents/docs.md +37 -0
  54. package/templates/.opencode/agents/features.md +21 -0
  55. package/templates/.opencode/agents/frontend-engineer.md +37 -0
  56. package/templates/.opencode/agents/handoff.md +21 -0
  57. package/templates/.opencode/agents/mobile-engineer.md +37 -0
  58. package/templates/.opencode/agents/planner.md +34 -0
  59. package/templates/.opencode/agents/product-manager.md +29 -0
  60. package/templates/.opencode/agents/qa-architect.md +27 -0
  61. package/templates/.opencode/agents/qa-runner.md +17 -0
  62. package/templates/.opencode/agents/security-engineer.md +37 -0
  63. package/templates/.opencode/agents/system-architect.md +37 -0
  64. package/templates/.opencode/agents/ui-designer.md +37 -0
  65. package/templates/.opencode/commands/board.md +15 -0
  66. package/templates/.opencode/commands/checkpoint.md +25 -0
  67. package/templates/.opencode/commands/feature.md +56 -0
  68. package/templates/.opencode/commands/finish.md +36 -0
  69. package/templates/.opencode/commands/next.md +49 -0
  70. package/templates/.opencode/commands/report.md +55 -0
  71. package/templates/.opencode/commands/resume.md +39 -0
  72. package/templates/.opencode/commands/switch-model.md +34 -0
  73. package/templates/.opencode/commands/tidy.md +49 -0
  74. package/templates/.opencode/plugins/backlog-notify.ts +57 -0
  75. package/templates/.opencode/plugins/backlog.ts +272 -0
  76. package/templates/.opencode/plugins/checkpoint.ts +160 -0
  77. package/templates/.opencode/plugins/context-guard.ts +1164 -0
  78. package/templates/.opencode/plugins/diff.ts +85 -0
  79. package/templates/.opencode/plugins/gates.ts +71 -0
  80. package/templates/.opencode/plugins/job-notify.ts +241 -0
  81. package/templates/.opencode/plugins/orient.ts +67 -0
  82. package/templates/.opencode/plugins/session.ts +89 -0
  83. package/templates/.opencode/plugins/wait.ts +101 -0
  84. package/templates/.opencode/plugins/where.ts +70 -0
  85. package/templates/.opencode/skills/bounded-explore/SKILL.md +38 -0
  86. package/templates/.opencode/skills/dev-loop/SKILL.md +87 -0
  87. package/templates/.vercelignore +16 -0
  88. package/templates/AGENTS.md +27 -0
  89. package/templates/BACKLOG.md +95 -0
  90. package/templates/docs/ci-cd-pipeline.md +81 -0
  91. package/templates/docs/gates.md +128 -0
  92. package/templates/docs/mcp-integrations.md +97 -0
  93. package/templates/docs/mobile-testing.md +555 -0
  94. package/templates/docs/nightly-testing.md +106 -0
  95. package/templates/docs/wsl-optimizations.md +290 -0
  96. package/templates/opencode.json +188 -0
  97. package/templates/scripts/agent-report.js +541 -0
  98. package/templates/scripts/agent-search.sh +117 -0
  99. package/templates/scripts/backlog.js +1864 -0
  100. package/templates/scripts/board-service.sh +207 -0
  101. package/templates/scripts/checkpoint.js +290 -0
  102. package/templates/scripts/finalize.js +277 -0
  103. package/templates/scripts/nightly.js +913 -0
  104. package/templates/scripts/orient.js +514 -0
  105. package/templates/scripts/qa/board-client.js +260 -0
  106. package/templates/scripts/qa/board-lib.js +96 -0
  107. package/templates/scripts/qa/board-sync.js +469 -0
  108. package/templates/scripts/qa/capacity-lib.js +916 -0
  109. package/templates/scripts/qa/check-backlog.js +427 -0
  110. package/templates/scripts/qa/check-capacity.js +85 -0
  111. package/templates/scripts/qa/check-ci-policy.js +164 -0
  112. package/templates/scripts/qa/check-concurrency.js +344 -0
  113. package/templates/scripts/qa/check-dispatch-config.js +296 -0
  114. package/templates/scripts/qa/check-docs.js +284 -0
  115. package/templates/scripts/qa/check-integrate.js +98 -0
  116. package/templates/scripts/qa/check-linger.js +160 -0
  117. package/templates/scripts/qa/check-prefix-stability.js +183 -0
  118. package/templates/scripts/qa/check-product.js +177 -0
  119. package/templates/scripts/qa/check-qa-plan.js +378 -0
  120. package/templates/scripts/qa/check-qa-scripts.js +85 -0
  121. package/templates/scripts/qa/check-quality.js +249 -0
  122. package/templates/scripts/qa/check-test-wiring.js +253 -0
  123. package/templates/scripts/qa/ci-triage.js +346 -0
  124. package/templates/scripts/qa/ci-usage-lib.js +185 -0
  125. package/templates/scripts/qa/ci-wait-lib.js +294 -0
  126. package/templates/scripts/qa/command-classifier.js +552 -0
  127. package/templates/scripts/qa/context-guard-core.js +1618 -0
  128. package/templates/scripts/qa/diff.js +174 -0
  129. package/templates/scripts/qa/feature-scaffold.js +224 -0
  130. package/templates/scripts/qa/fixtures/backlog.md +104 -0
  131. package/templates/scripts/qa/governance.js +174 -0
  132. package/templates/scripts/qa/hash-file.js +32 -0
  133. package/templates/scripts/qa/lease-lib.js +263 -0
  134. package/templates/scripts/qa/merge-backlog.js +324 -0
  135. package/templates/scripts/qa/mobile-e2e/analyze-timings.js +300 -0
  136. package/templates/scripts/qa/mobile-e2e/apk-cache.js +420 -0
  137. package/templates/scripts/qa/mobile-e2e/backend-build-cache.js +203 -0
  138. package/templates/scripts/qa/mobile-e2e/boot-emulator.sh +432 -0
  139. package/templates/scripts/qa/mobile-e2e/build-apk.sh +210 -0
  140. package/templates/scripts/qa/mobile-e2e/check-flows.js +453 -0
  141. package/templates/scripts/qa/mobile-e2e/config.yaml +18 -0
  142. package/templates/scripts/qa/mobile-e2e/device-down.sh +88 -0
  143. package/templates/scripts/qa/mobile-e2e/device-up.sh +258 -0
  144. package/templates/scripts/qa/mobile-e2e/ios-simulator-down.sh +72 -0
  145. package/templates/scripts/qa/mobile-e2e/ios-simulator-up.sh +153 -0
  146. package/templates/scripts/qa/mobile-e2e/job-events.js +181 -0
  147. package/templates/scripts/qa/mobile-e2e/prewarm.sh +56 -0
  148. package/templates/scripts/qa/mobile-e2e/run-detached.sh +222 -0
  149. package/templates/scripts/qa/mobile-e2e/run-maestro.js +1543 -0
  150. package/templates/scripts/qa/mobile-e2e/ui-dump.js +327 -0
  151. package/templates/scripts/qa/models.allowlist.txt +32 -0
  152. package/templates/scripts/qa/provider-stats.js +878 -0
  153. package/templates/scripts/qa/run-clean.js +83 -0
  154. package/templates/scripts/qa/run-gates.js +212 -0
  155. package/templates/scripts/qa/run-loop.js +220 -0
  156. package/templates/scripts/qa/session-recon.js +512 -0
  157. package/templates/scripts/qa/store-lib.js +324 -0
  158. package/templates/scripts/qa/tool-lib.js +134 -0
  159. package/templates/scripts/qa/where.js +214 -0
  160. package/templates/scripts/qa/wslconfig-merge.js +157 -0
  161. package/templates/scripts/serve.js +1328 -0
  162. package/templates/scripts/setup-nightly.sh +185 -0
  163. package/templates/scripts/setup-tmpfs.sh +374 -0
  164. package/templates/scripts/ship.js +586 -0
  165. package/templates/scripts/switch-reasoning-model.ps1 +101 -0
  166. package/templates/scripts/switch-reasoning-model.sh +104 -0
  167. package/templates/scripts/wait-for.js +342 -0
  168. package/templates/scripts/wsl-gpu.sh +180 -0
  169. package/templates/scripts/wsl-tune.sh +261 -0
@@ -0,0 +1,57 @@
1
+ import type { Plugin } from "@opencode/plugin"
2
+
3
+ // Pushes a structured log whenever an agent mutates the board via the
4
+ // `backlog_*` tools, so "an agent finished an item" reaches you as a notification
5
+ // instead of a manual `/board` refresh.
6
+
7
+ function summarize(name: string, args: any): string {
8
+ switch (name) {
9
+ case "backlog_add":
10
+ return `added "${args?.task ?? ""}"`
11
+ case "backlog_take":
12
+ return `picked up ${args?.id ?? ""}`
13
+ case "backlog_queue":
14
+ return `queued ${args?.id ?? ""}`
15
+ case "backlog_next":
16
+ return args?.take ? `took next item off the queue` : "checked the next queued item"
17
+ case "backlog_archive":
18
+ return `archived ${args?.id ?? ""}`
19
+ case "backlog_freeze":
20
+ return `froze ${args?.id ?? ""}`
21
+ case "backlog_epic":
22
+ return `moved ${args?.id ?? ""} to epic ${args?.to ?? ""}`
23
+ case "backlog_epic_add":
24
+ return `added epic "${args?.key ?? ""}"`
25
+ case "backlog_worktree":
26
+ return `isolated ${args?.id ?? ""} in a worktree`
27
+ case "backlog_depends":
28
+ return `set ${args?.id ?? ""} depends on ${args?.on ?? ""}`
29
+ case "backlog_owns":
30
+ return `recorded files owned by ${args?.id ?? ""}`
31
+ case "backlog_list":
32
+ return "listed the board"
33
+ default:
34
+ return name
35
+ }
36
+ }
37
+
38
+ const BacklogNotify: Plugin = {
39
+ id: "backlog-notify",
40
+ async setup(ctx) {
41
+ await ctx.tool.hook("execute.after", (event: any) => {
42
+ const name = event?.tool || ""
43
+ if (!name.startsWith("backlog_")) return
44
+
45
+ const args = (event?.input as any) ?? {}
46
+ const message = `Backlog: ${summarize(name, args)}`
47
+
48
+ // V1 pushed a TUI toast + `client.app.log`; V2 server plugins have no
49
+ // toast and no `client`, so this is a best-effort console log.
50
+ console.log(message)
51
+ })
52
+
53
+ return () => {}
54
+ },
55
+ }
56
+
57
+ export default BacklogNotify
@@ -0,0 +1,272 @@
1
+ import type { Plugin } from "@opencode/plugin"
2
+ import toolLib from "../../scripts/qa/tool-lib.js"
3
+
4
+ // Thin wrappers around the deterministic `scripts/backlog.js` CLI. The tools
5
+ // only shell out — they never edit BACKLOG.md themselves, so the agent-side and
6
+ // human-side write-paths share one implementation. node resolution and the
7
+ // mid-session-worktree reroot live in scripts/qa/tool-lib.js (one home, shared
8
+ // with the checkpoint/session tools).
9
+ //
10
+ // V2: these are registered from a plugin via `ctx.tool.transform`. The V2 tool
11
+ // executor has no `directory`/`worktree`, so the launch directory is captured in
12
+ // `setup` and paired with the call's sessionID — the same shape `sessionRoot`
13
+ // expects, keeping the mid-session-worktree reroot intact.
14
+
15
+ function run(context: any, args: string[]): string {
16
+ return toolLib.runScript(context, "scripts/backlog.js", args, {
17
+ marker: "BACKLOG.md",
18
+ label: "backlog",
19
+ env: { HARNESS_SESSION_ID: String(context?.sessionID || "") },
20
+ })
21
+ }
22
+
23
+ export default {
24
+ id: "backlog-tools",
25
+ async setup(ctx) {
26
+ const directory = ctx.location.directory
27
+ const h = (context: any) => ({ directory, sessionID: context?.sessionID, agent: context?.agent })
28
+ await ctx.tool.transform((editor) => {
29
+ editor.add({
30
+ name: "backlog_list",
31
+ description:
32
+ "List the active BACKLOG.md rows (In progress + Open) — deterministic and bounded: true status counts + up to `limit` rows per section (default 40, 0 = all). Use instead of reading BACKLOG.md directly.",
33
+ input: {
34
+ type: "object",
35
+ properties: {
36
+ limit: { type: "string", description: "max rows shown per section (default 40; 0 = all) — raise only when the board's tail matters" },
37
+ },
38
+ required: [],
39
+ additionalProperties: false,
40
+ },
41
+ async execute(input, context) {
42
+ const argv = ["list"]
43
+ if (input.limit) argv.push("--limit", input.limit)
44
+ return { content: run(h(context), argv) }
45
+ },
46
+ })
47
+
48
+ editor.add({
49
+ name: "backlog_add",
50
+ description:
51
+ "Add one row to BACKLOG.md (Open section) — capture a found item / todo / bug. Validates priority, generates a unique ID, and (optionally) records its dependencies.",
52
+ input: {
53
+ type: "object",
54
+ properties: {
55
+ task: { type: "string", description: "short task description (what's known)" },
56
+ priority: { type: "string", description: "P1..P4, optional (defaults P3)" },
57
+ evidence: { type: "string", description: "pointer to evidence (file/log/ticket/words), optional" },
58
+ epic: { type: "string", description: "epic key from the ## Epics registry, or ? for unassigned (optional, defaults ?)" },
59
+ dependsOn: { type: "string", description: "comma-separated row IDs that must be archived first, optional (defaults ?)" },
60
+ },
61
+ required: ["task"],
62
+ additionalProperties: false,
63
+ },
64
+ async execute(input, context) {
65
+ const argv = ["add", input.task]
66
+ if (input.priority) argv.push("--p", input.priority)
67
+ if (input.evidence) argv.push("--evidence", input.evidence)
68
+ if (input.epic) argv.push("--epic", input.epic)
69
+ if (input.dependsOn) argv.push("--depends-on", input.dependsOn)
70
+ return { content: run(h(context), argv) }
71
+ },
72
+ })
73
+
74
+ editor.add({
75
+ name: "backlog_take",
76
+ description:
77
+ "Move a BACKLOG.md row Open/Queued -> In progress (pick it up), optionally linking the session handoff file.",
78
+ input: {
79
+ type: "object",
80
+ properties: {
81
+ id: { type: "string", description: "row ID, e.g. F-001" },
82
+ handoff: { type: "string", description: "session handoff path, e.g. .agents/handoffs/F-001.md" },
83
+ },
84
+ required: ["id"],
85
+ additionalProperties: false,
86
+ },
87
+ async execute(input, context) {
88
+ const argv = ["take", input.id]
89
+ if (input.handoff) argv.push("--handoff", input.handoff)
90
+ return { content: run(h(context), argv) }
91
+ },
92
+ })
93
+
94
+ editor.add({
95
+ name: "backlog_queue",
96
+ description:
97
+ "Move a BACKLOG.md row Open -> Queued (allocate it to a worker / ready-to-pull lane). Pull it back later with backlog_next.",
98
+ input: {
99
+ type: "object",
100
+ properties: { id: { type: "string", description: "row ID, e.g. F-001" } },
101
+ required: ["id"],
102
+ additionalProperties: false,
103
+ },
104
+ async execute(input, context) {
105
+ return { content: run(h(context), ["queue", input.id]) }
106
+ },
107
+ })
108
+
109
+ editor.add({
110
+ name: "backlog_next",
111
+ description:
112
+ "Pick the next item off the Queue: report the top-priority unblocked Queued row, or (with take) atomically claim it — move it Queued -> In progress in a locked write and link the session handoff, so two sessions can never pick the same row. This is the primitive behind /next; always take to claim before working.",
113
+ input: {
114
+ type: "object",
115
+ properties: {
116
+ take: { type: "boolean", description: "when true, move the top Queued row to In progress (default: dry-run, just report it)" },
117
+ handoff: { type: "string", description: "session handoff path when taking, e.g. .agents/handoffs/F-001.md" },
118
+ },
119
+ required: [],
120
+ additionalProperties: false,
121
+ },
122
+ async execute(input, context) {
123
+ const argv = ["next"]
124
+ if (input.take) argv.push("--take")
125
+ if (input.handoff) argv.push("--handoff", input.handoff)
126
+ return { content: run(h(context), argv) }
127
+ },
128
+ })
129
+
130
+ editor.add({
131
+ name: "backlog_archive",
132
+ description:
133
+ "Move a BACKLOG.md row to Archive (shipped · done) — call when a task ships.",
134
+ input: {
135
+ type: "object",
136
+ properties: {
137
+ id: { type: "string", description: "row ID" },
138
+ closed: { type: "string", description: "closed note, e.g. shipped + commit/date" },
139
+ },
140
+ required: ["id"],
141
+ additionalProperties: false,
142
+ },
143
+ async execute(input, context) {
144
+ const argv = ["archive", input.id]
145
+ if (input.closed) argv.push("--closed", input.closed)
146
+ return { content: run(h(context), argv) }
147
+ },
148
+ })
149
+
150
+ editor.add({
151
+ name: "backlog_freeze",
152
+ description:
153
+ "Move a BACKLOG.md row to Frozen (parked, not deleted) — a why and/or reopen condition is required.",
154
+ input: {
155
+ type: "object",
156
+ properties: {
157
+ id: { type: "string", description: "row ID" },
158
+ why: { type: "string", description: "why frozen" },
159
+ reopen: { type: "string", description: "reopen condition" },
160
+ },
161
+ required: ["id"],
162
+ additionalProperties: false,
163
+ },
164
+ async execute(input, context) {
165
+ const argv = ["freeze", input.id]
166
+ if (input.why) argv.push("--why", input.why)
167
+ if (input.reopen) argv.push("--reopen", input.reopen)
168
+ return { content: run(h(context), argv) }
169
+ },
170
+ })
171
+
172
+ editor.add({
173
+ name: "backlog_epic",
174
+ description:
175
+ "Assign/reassign the epic of a BACKLOG.md row in place (any section). <to> must be a key in the ## Epics registry or ? (unassigned).",
176
+ input: {
177
+ type: "object",
178
+ properties: {
179
+ id: { type: "string", description: "row ID, e.g. F-001" },
180
+ to: { type: "string", description: "epic key (from ## Epics) or ? for unassigned" },
181
+ },
182
+ required: ["id", "to"],
183
+ additionalProperties: false,
184
+ },
185
+ async execute(input, context) {
186
+ return { content: run(h(context), ["epic", input.id, "--to", input.to]) }
187
+ },
188
+ })
189
+
190
+ editor.add({
191
+ name: "backlog_epic_add",
192
+ description:
193
+ "Add an epic to the ## Epics registry in BACKLOG.md — a logical container (key/label/goal) that work rows group under. No code change required.",
194
+ input: {
195
+ type: "object",
196
+ properties: {
197
+ key: { type: "string", description: "stable slug key, e.g. metrics" },
198
+ label: { type: "string", description: "human label, e.g. Metrics & observability" },
199
+ goal: { type: "string", description: "one-line goal/scope of the epic, optional" },
200
+ },
201
+ required: ["key", "label"],
202
+ additionalProperties: false,
203
+ },
204
+ async execute(input, context) {
205
+ const argv = ["epic-add", input.key, "--label", input.label]
206
+ if (input.goal) argv.push("--goal", input.goal)
207
+ return { content: run(h(context), argv) }
208
+ },
209
+ })
210
+
211
+ editor.add({
212
+ name: "backlog_worktree",
213
+ description:
214
+ "Create an isolated git worktree + feature branch for a backlog item so concurrent sessions don't collide on one working tree. Run it from the MAIN tree before starting ANY feature — main stays board + shippable code only, every feature works in its own worktree.",
215
+ input: {
216
+ type: "object",
217
+ properties: {
218
+ id: { type: "string", description: "row ID, e.g. F-060" },
219
+ branch: { type: "string", description: "branch name (defaults to the lowercased id)" },
220
+ dir: { type: "string", description: "worktree directory (defaults to <repo>/../.worktrees/<repo>/<id>)" },
221
+ handoff: { type: "string", description: "session handoff path recorded in the row (optional)" },
222
+ },
223
+ required: ["id"],
224
+ additionalProperties: false,
225
+ },
226
+ async execute(input, context) {
227
+ const argv = ["worktree", input.id]
228
+ if (input.branch) argv.push("--branch", input.branch)
229
+ if (input.dir) argv.push("--dir", input.dir)
230
+ if (input.handoff) argv.push("--handoff", input.handoff)
231
+ return { content: run(h(context), argv) }
232
+ },
233
+ })
234
+
235
+ editor.add({
236
+ name: "backlog_depends",
237
+ description:
238
+ "Set/clear a BACKLOG.md row's \"Depends on\" cell (Open/Queued only) — a comma-separated list of row IDs that must be archived before this row is picked up. next/take/worktree skip or refuse a row whose dependencies aren't archived. A dependency cycle is rejected.",
239
+ input: {
240
+ type: "object",
241
+ properties: {
242
+ id: { type: "string", description: "row ID, e.g. F-052" },
243
+ on: { type: "string", description: "comma-separated row IDs it depends on, or ? to clear" },
244
+ },
245
+ required: ["id", "on"],
246
+ additionalProperties: false,
247
+ },
248
+ async execute(input, context) {
249
+ return { content: run(h(context), ["depends", input.id, "--on", input.on]) }
250
+ },
251
+ })
252
+
253
+ editor.add({
254
+ name: "backlog_owns",
255
+ description:
256
+ "Record the files/globs a backlog row owns in .agents/memory/owned-files.md — feeds the cross-session overlap check in test:concurrency (two In-progress rows must not own the same file).",
257
+ input: {
258
+ type: "object",
259
+ properties: {
260
+ id: { type: "string", description: "row ID, e.g. F-052" },
261
+ files: { type: "string", description: 'comma-separated globs/paths, e.g. "scripts/test-*.ts, scripts/qa/routes.js", or ? to clear' },
262
+ },
263
+ required: ["id", "files"],
264
+ additionalProperties: false,
265
+ },
266
+ async execute(input, context) {
267
+ return { content: run(h(context), ["owns", input.id, "--files", input.files]) }
268
+ },
269
+ })
270
+ })
271
+ },
272
+ } satisfies Plugin
@@ -0,0 +1,160 @@
1
+ import type { Plugin } from "@opencode/plugin"
2
+ import toolLib from "../../scripts/qa/tool-lib.js"
3
+
4
+ // Thin wrappers around the deterministic `scripts/checkpoint.js` CLI. The tool
5
+ // only shells out — the state block is written/replaced by one implementation,
6
+ // so an agent checkpoint and a human resume share the same format. Checkpoint
7
+ // is bounded state, never a transcript dump. Node resolution + the mid-session
8
+ // worktree reroot live in scripts/qa/tool-lib.js (one home for all tools).
9
+ //
10
+ // V2: registered from a plugin via `ctx.tool.transform`. The executor context has
11
+ // no `directory`/`worktree`, so the launch directory is captured in `setup` and
12
+ // paired with the call's sessionID for tool-lib's sessionRoot reroot.
13
+
14
+ function run(context: any, args: string[]): string {
15
+ return toolLib.runScript(context, "scripts/checkpoint.js", args, {
16
+ marker: ".agents",
17
+ label: "checkpoint",
18
+ })
19
+ }
20
+
21
+ function items(value: unknown): string[] {
22
+ return String(value || "")
23
+ .split(/\r?\n|;/)
24
+ .map((s) => s.trim())
25
+ .filter(Boolean)
26
+ }
27
+
28
+ // An unset `feature` reaches the wrapper as the literal string "undefined" (the
29
+ // only shape the runner forwards); the CLI now rejects it, but fail here first
30
+ // with an actionable message instead of a stray `.agents/handoffs/undefined.md`.
31
+ const RESERVED_FEATURE = new Set(["undefined", "null", "none", "nan", "nil"])
32
+ function requireFeature(raw: unknown, verb: string): string {
33
+ const feature = String(raw ?? "").trim()
34
+ if (!feature || RESERVED_FEATURE.has(feature.toLowerCase())) {
35
+ throw new Error(
36
+ `checkpoint ${verb} needs the feature id (e.g. "F-001") — got ${JSON.stringify(raw ?? "")}. ` +
37
+ `Pass the BACKLOG row (or slug) you are checkpointing; never the literal string "undefined".`
38
+ )
39
+ }
40
+ return feature
41
+ }
42
+
43
+ export default {
44
+ id: "checkpoint-tools",
45
+ async setup(ctx) {
46
+ const directory = ctx.location.directory
47
+ const h = (context: any) => ({
48
+ directory,
49
+ sessionID: context?.sessionID,
50
+ agent: context?.agent,
51
+ })
52
+ await ctx.tool.transform((editor) => {
53
+ editor.add({
54
+ name: "checkpoint_write",
55
+ description:
56
+ "Write (or replace) the deterministic bounded-state checkpoint in `.agents/handoffs/<feature>.md` — objective/phase, completed + active work, files changed, contracts, facts, decisions, risks, next action. Use when approaching the turn/context budgets so a fresh session can resume from the checkpoint instead of the transcript. Rewriting identical state is a no-op; changed state increments checkpoint_count. Never invent a field — omit it.",
57
+ input: {
58
+ type: "object",
59
+ properties: {
60
+ feature: {
61
+ type: "string",
62
+ description: "BACKLOG row ID or slug naming the handoff file, e.g. F-001",
63
+ },
64
+ objective: {
65
+ type: "string",
66
+ description: "the work unit's single objective (optional)",
67
+ },
68
+ phase: {
69
+ type: "string",
70
+ description: "current phase, e.g. implementing / verifying (optional)",
71
+ },
72
+ completed: {
73
+ type: "string",
74
+ description: "completed items, newline- or ';'-separated (optional)",
75
+ },
76
+ active: {
77
+ type: "string",
78
+ description: "in-flight dispatches/work, newline- or ';'-separated (optional)",
79
+ },
80
+ filesChanged: {
81
+ type: "string",
82
+ description: "changed files/paths, newline- or ';'-separated (optional)",
83
+ },
84
+ contracts: {
85
+ type: "string",
86
+ description: "shared contracts in play, newline- or ';'-separated (optional)",
87
+ },
88
+ facts: {
89
+ type: "string",
90
+ description:
91
+ "known facts established this session, newline- or ';'-separated (optional)",
92
+ },
93
+ decisions: {
94
+ type: "string",
95
+ description: "decisions taken, newline- or ';'-separated (optional)",
96
+ },
97
+ risks: {
98
+ type: "string",
99
+ description: "known risks/open questions, newline- or ';'-separated (optional)",
100
+ },
101
+ nextAction: {
102
+ type: "string",
103
+ description: "the single next action for the resuming session (optional)",
104
+ },
105
+ session: {
106
+ type: "string",
107
+ description: "primary orchestrator session id from session_info (optional)",
108
+ },
109
+ },
110
+ required: ["feature"],
111
+ additionalProperties: false,
112
+ },
113
+ async execute(input, context) {
114
+ const feature = requireFeature(input.feature, "write")
115
+ const argv = ["write", "--feature", feature]
116
+ if (input.objective) argv.push("--objective", input.objective)
117
+ if (input.phase) argv.push("--phase", input.phase)
118
+ if (input.nextAction) argv.push("--next-action", input.nextAction)
119
+ if (input.session) argv.push("--session", input.session)
120
+ for (const it of items(input.completed)) argv.push("--completed", it)
121
+ for (const it of items(input.active)) argv.push("--active", it)
122
+ for (const it of items(input.filesChanged)) argv.push("--files-changed", it)
123
+ for (const it of items(input.contracts)) argv.push("--contracts", it)
124
+ for (const it of items(input.facts)) argv.push("--facts", it)
125
+ for (const it of items(input.decisions)) argv.push("--decisions", it)
126
+ for (const it of items(input.risks)) argv.push("--risks", it)
127
+ return { content: run(h(context), argv) }
128
+ },
129
+ })
130
+
131
+ editor.add({
132
+ name: "checkpoint_resume",
133
+ description:
134
+ "Print a session's checkpoint block — the bounded state a fresh context resumes from (never the transcript). Fails loudly when the feature has no checkpoint yet.",
135
+ input: {
136
+ type: "object",
137
+ properties: {
138
+ feature: {
139
+ type: "string",
140
+ description: "BACKLOG row ID or slug naming the handoff file, e.g. F-001",
141
+ },
142
+ json: {
143
+ type: "boolean",
144
+ description:
145
+ "print the parsed state as JSON instead of markdown (optional)",
146
+ },
147
+ },
148
+ required: ["feature"],
149
+ additionalProperties: false,
150
+ },
151
+ async execute(input, context) {
152
+ const feature = requireFeature(input.feature, "resume")
153
+ const argv = ["resume", "--feature", feature]
154
+ if (input.json) argv.push("--json")
155
+ return { content: run(h(context), argv) }
156
+ },
157
+ })
158
+ })
159
+ },
160
+ } satisfies Plugin