opencode-agent-harness 0.0.0-stage → 0.3.14

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 (171) hide show
  1. package/CHANGELOG.md +217 -0
  2. package/LICENSE +21 -0
  3. package/README.md +636 -2
  4. package/bin/agent-harness.js +3182 -0
  5. package/contrib/global-plugins/README.md +49 -0
  6. package/contrib/global-plugins/harness-freshness.ts +355 -0
  7. package/package.json +86 -4
  8. package/templates/.agents/AGENTS.md +148 -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 +1924 -0
  100. package/templates/scripts/board-service.sh +214 -0
  101. package/templates/scripts/checkpoint.js +290 -0
  102. package/templates/scripts/finalize.js +416 -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 +323 -0
  106. package/templates/scripts/qa/board-lib.js +96 -0
  107. package/templates/scripts/qa/board-sync.js +499 -0
  108. package/templates/scripts/qa/capacity-lib.js +916 -0
  109. package/templates/scripts/qa/check-backlog.js +434 -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 +288 -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 +187 -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/check-worktrees.js +93 -0
  124. package/templates/scripts/qa/ci-triage.js +346 -0
  125. package/templates/scripts/qa/ci-usage-lib.js +185 -0
  126. package/templates/scripts/qa/ci-wait-lib.js +294 -0
  127. package/templates/scripts/qa/command-classifier.js +552 -0
  128. package/templates/scripts/qa/context-guard-core.js +1618 -0
  129. package/templates/scripts/qa/diff.js +174 -0
  130. package/templates/scripts/qa/feature-scaffold.js +224 -0
  131. package/templates/scripts/qa/fixtures/backlog.md +104 -0
  132. package/templates/scripts/qa/governance.js +174 -0
  133. package/templates/scripts/qa/hash-file.js +32 -0
  134. package/templates/scripts/qa/lease-lib.js +263 -0
  135. package/templates/scripts/qa/merge-backlog.js +324 -0
  136. package/templates/scripts/qa/mobile-e2e/analyze-timings.js +300 -0
  137. package/templates/scripts/qa/mobile-e2e/apk-cache.js +420 -0
  138. package/templates/scripts/qa/mobile-e2e/backend-build-cache.js +203 -0
  139. package/templates/scripts/qa/mobile-e2e/boot-emulator.sh +432 -0
  140. package/templates/scripts/qa/mobile-e2e/build-apk.sh +210 -0
  141. package/templates/scripts/qa/mobile-e2e/check-flows.js +568 -0
  142. package/templates/scripts/qa/mobile-e2e/config.yaml +18 -0
  143. package/templates/scripts/qa/mobile-e2e/device-down.sh +88 -0
  144. package/templates/scripts/qa/mobile-e2e/device-up.sh +258 -0
  145. package/templates/scripts/qa/mobile-e2e/ios-simulator-down.sh +72 -0
  146. package/templates/scripts/qa/mobile-e2e/ios-simulator-up.sh +153 -0
  147. package/templates/scripts/qa/mobile-e2e/job-events.js +181 -0
  148. package/templates/scripts/qa/mobile-e2e/prewarm.sh +56 -0
  149. package/templates/scripts/qa/mobile-e2e/run-detached.sh +222 -0
  150. package/templates/scripts/qa/mobile-e2e/run-maestro.js +1543 -0
  151. package/templates/scripts/qa/mobile-e2e/ui-dump.js +327 -0
  152. package/templates/scripts/qa/models.allowlist.txt +32 -0
  153. package/templates/scripts/qa/provider-stats.js +878 -0
  154. package/templates/scripts/qa/run-clean.js +83 -0
  155. package/templates/scripts/qa/run-gates.js +213 -0
  156. package/templates/scripts/qa/run-loop.js +220 -0
  157. package/templates/scripts/qa/session-recon.js +512 -0
  158. package/templates/scripts/qa/store-lib.js +324 -0
  159. package/templates/scripts/qa/tool-lib.js +134 -0
  160. package/templates/scripts/qa/where.js +214 -0
  161. package/templates/scripts/qa/worktree-hygiene.js +217 -0
  162. package/templates/scripts/qa/wslconfig-merge.js +157 -0
  163. package/templates/scripts/serve.js +1328 -0
  164. package/templates/scripts/setup-nightly.sh +185 -0
  165. package/templates/scripts/setup-tmpfs.sh +374 -0
  166. package/templates/scripts/ship.js +586 -0
  167. package/templates/scripts/switch-reasoning-model.ps1 +101 -0
  168. package/templates/scripts/switch-reasoning-model.sh +104 -0
  169. package/templates/scripts/wait-for.js +342 -0
  170. package/templates/scripts/wsl-gpu.sh +180 -0
  171. package/templates/scripts/wsl-tune.sh +319 -0
@@ -0,0 +1,70 @@
1
+ # QA plans — one file per change
2
+
3
+ Project-owned (like all `.agents/memory/*`). This directory holds the
4
+ coverage-driven QA plan, **sharded**: one file per shipped change instead of a
5
+ single shared `qa-plan.md`. Each concurrent session owns its own file, so two
6
+ sessions (e.g. `F-003` and `F-035`) never rewrite each other's entries — the
7
+ failure mode where one session's "keep-last-on-top" edit moves another's entry
8
+ around (and risks dropping it on commit).
9
+
10
+ `npm run test:qa-plan` reads EVERY `.md` file under this directory (plus the
11
+ legacy `.agents/memory/qa-plan.md` if it exists) and unions their coverage maps,
12
+ waivers, and flow audits against the live diff — so a changed code path is
13
+ covered if ANY plan file names it.
14
+
15
+ ## Naming & ownership
16
+
17
+ - One file per change. Name it after the `BACKLOG.md` feature ID (`F-003.md`),
18
+ or a short hyphenated slug of the change (`return-no-condition.md`) when there
19
+ is no feature row.
20
+ - **Own your file; never edit another change's file.** That single rule removes
21
+ the collision. If a later change revisits the same feature, append a new
22
+ `##`-block to that feature's file (or open a new dated file) — never reorder
23
+ or delete another entry.
24
+ - Authored by `qa-architect` (or by the main orchestrator as the mandatory
25
+ fallback). Required sections: `## Change intent`,
26
+ `## Parallel-surface & variant audit`, `## Coverage map`, `## Waivers`, plus
27
+ the test-design record — `## Test budget`, `## Oracle & owner`,
28
+ `## Test-design self-check` (T1–T10; see
29
+ `.agents/memory/test-design-parameters.md`). The record is what makes test
30
+ quality and economics auditable: coverage without an independent oracle, an
31
+ exit contract, a stated cost, and a wired tier produces suites that are green,
32
+ prove little, and cost a lot.
33
+
34
+ ## Example (`F-003.md`)
35
+
36
+ # QA plan — F-003 (return flow: no condition selector)
37
+
38
+ ## Change intent
39
+ - change: return flow no longer offers a condition selector — every return POSTs without a condition payload
40
+
41
+ ## Parallel-surface & variant audit
42
+ - components/LendingActionDrawers.tsx -> test:quick::return (click-through: Mark as Returned, no condition selector)
43
+ - mobile/features/return/ReturnStatusSheet.tsx audited: deferred — mobile still renders the selector; same simplification pending, logged in handoffs/
44
+ - app/api/transactions/[id]/return/route.ts -> test:api::return (POST without condition payload succeeds)
45
+ - flow: return variant: condition-selector-present audited: removed by this change — asserting absence only
46
+ - flow: return variant: condition-selector-absent -> test:quick::return (no-selector click-through renders no condition UI)
47
+
48
+ ## Coverage map
49
+ - components/return/ReturnConfirmDrawer.tsx -> test:quick::progression (click-through: Mark as Returned -> confirm -> /api/transactions/[id]/return)
50
+ - app/api/transactions/[id]/return/route.ts -> test:quick::progression (return POST succeeds with no condition payload)
51
+
52
+ ## Test budget
53
+ - scripts/qa/tests/return-confirm.test.ts: ~4 s wall-clock, tier test:quick, teardown: runner force-exit (no open handles)
54
+ - test:quick total budget: <= 60 s (pre-push)
55
+
56
+ ## Oracle & owner
57
+ - return POST without condition payload -> behavior (route contract); owner: new
58
+ - ReturnConfirmDrawer renders no condition UI -> behavior (user-visible absence); owner: new
59
+ - generated-client parity -> drift-guard; owner: check-generated-client.js (do NOT duplicate)
60
+
61
+ ## Test-design self-check
62
+ - [x] T1 exit/teardown - [x] T2 independent oracle - [x] T3 single owner
63
+ - [x] T4 real surface - [x] T5 executed proof - [x] T6 cheapest tier
64
+ - [x] T7 wired (test:wiring green) - [x] T8 hermetic - [x] T9 fail-fast
65
+ - [x] T10 labels/negative case
66
+
67
+ ## Waivers
68
+ # waived: src/some-screen.tsx reason: copy-only string swap, no runtime path changed
69
+
70
+ Lines starting with `#` are ignored by the gate.
@@ -0,0 +1,21 @@
1
+ # QA run evidence — one directory per change
2
+
3
+ Project-owned (like all `.agents/*` data). Full verbatim command/test output for
4
+ a QA run lives here, not in the agent's final message:
5
+ `.agents/qa-runs/<change-id>/evidence.txt` (same id as the QA plan / handoff —
6
+ `F-003`, `return-no-condition`). Only `qa-runner` writes here; never edit another
7
+ run's evidence.
8
+
9
+ Why: the orchestrator's context is the expensive part of a run. `qa-runner`
10
+ returns a compact summary (commands + exit codes, pass/fail per suite, evidence
11
+ path + sha256) and the unbounded logs stay on disk, so a failure can be audited
12
+ without bloating every later dispatch.
13
+
14
+ Integrity: the runner reports the artifact's sha256 via
15
+ `node scripts/qa/hash-file.js .agents/qa-runs/<id>/evidence.txt`; the
16
+ orchestrator can recompute it to confirm the summary matches the file.
17
+
18
+ # evidence.txt (example)
19
+ $ npm run test:quick
20
+ exit 0 | 42 tests, 42 pass | runner 38.2s, wall 41.0s
21
+ ... full verbatim output, no truncation ...
@@ -0,0 +1,47 @@
1
+ # Reviews & audits — {{PROJECT_NAME}}
2
+
3
+ Durable home for **review / audit / investigation deliverables** — the reports a
4
+ session produces when it inspects the codebase and files follow-up rows. This
5
+ namespace exists so audits stop improvising slugs inside the `.agents/features/`
6
+ tree (which is for feature *contracts*: intent → scope → plan → tests) and stop
7
+ silently relying on `check-product` treating "no intent.md/plan.md yet" as "not
8
+ at planning stage".
9
+
10
+ ## When to write here
11
+
12
+ A session that runs a code-quality review, regression-package review, logs audit,
13
+ dependency audit, or similar **investigation that files follow-up rows** writes
14
+ its durable findings here:
15
+
16
+ ```
17
+ .agents/reviews/<id-or-slug>/REPORT.md # the consolidated findings
18
+ .agents/reviews/<id-or-slug>/scans/*.md # per-surface scan output (web/mobile/scripts…)
19
+ ```
20
+
21
+ `<id-or-slug>` is the board row ID (e.g. the F-104 code-quality review) or a
22
+ hyphenated slug when no row exists yet. One review = one directory; never edit
23
+ another review's directory.
24
+
25
+ ## Artifact convention (keep reviews comparable)
26
+
27
+ Every `REPORT.md` follows the same spine so audits become comparable instead of
28
+ bespoke:
29
+
30
+ 1. **Scope + provenance** — what was audited, which surfaces, which session.
31
+ 2. **Findings, each tagged** with the quality-parameter it violates
32
+ (`.agents/memory/quality-parameters.md`: P1 dead-code · P2 deps · P3
33
+ right-sized · P4 one-home-per-fact · P5 layering · P6 error/state · P7 type
34
+ honesty · P8 consistency) and a `file:line` evidence pointer.
35
+ 3. **Remediation** — the fix shape for each finding.
36
+ 4. **Follow-up rows** — every legacy-debt finding that is not fixed in this
37
+ review ships as a board row (evidence cites this `REPORT.md`).
38
+ 5. **Root-cause findings about the harness** — flag defects in the harness's own
39
+ rules/gates/tools separately, addressed to the harness maintainer.
40
+
41
+ Reviews that are **no-user-facing** ship as `docs`/`chore`; if the review files
42
+ follow-up rows, add a `docs`-type changelog line so the milestone is visible in
43
+ the human changelog.
44
+
45
+ Mechanical quality gates (`.agents/memory/quality-parameters.md` P1/P3/P4) stop
46
+ debt from being *introduced* on new/changed code; these reviews clear *legacy*
47
+ debt and file the follow-ups.
@@ -0,0 +1,199 @@
1
+ # {{PROJECT_NAME}} Operating Rules (summary)
2
+
3
+ Always in effect. Operating mechanics live here; the durable standards — and the detail of record for the rules below — live in `.agents/AGENTS.md`. Read it before non-trivial work.
4
+
5
+ ## Step Zero — subagent dispatch gate (non-negotiable)
6
+
7
+ Dispatch the relevant personas via the `subagent` tool — each runs on its own `model:` (`.opencode/agents/<name>.md`) — for non-trivial, multi-surface work with a distinct deliverable. The **dispatch economics** below and the **complexity threshold** are the authority: trivial/single-surface/single-file changes execute directly on the main model, and reads, git ops, commits, integration, and mechanical work always stay on the main model.
8
+
9
+ - **Bound every task before dispatching.** No persona gets a bare metric ("get under N lines", "type everything"). Each dispatch prompt carries a task spec: `Objective` (one deliverable) → `Working tree` (the exact feature-worktree path/branch — or `main` — this task edits; the subagent verifies it before touching a file) → `Owned files` (exact paths) → `Read-only files` → `Shared contracts (owns|consumes)` → `Done = <gate command + observable metric>` → `Out-of-scope`.
10
+ - **Parallel = disjoint.** Dispatch two personas in parallel only when their owned files AND shared contracts are disjoint; otherwise serialize and put the shared-contract owner first. Across *sessions*, disjoint means **isolated working trees**: run `backlog worktree <id>` (from the main tree; when a human launches it at a terminal, `--open` starts the agent in the new worktree so the session is root-scoped there and its lease lands in the worktree, not `main`) before starting ANY feature — `main` stays board + shippable code only, so one session's uncommitted work can't leak into another's pre-push gate. Declare each picked-up row's owned files (`backlog owns <id> --files "glob, glob"`) so `test:concurrency` fails *exactly* when two In-progress rows own the same file, instead of on every "2+ In progress + dirty" tree; `node scripts/qa/run-clean.js -- <gate>` snapshots the tree so a gate verifies only committed work.
11
+ - **Accept, don't trust.** After a code persona reports done, the orchestrator re-runs the gate itself (`tsc --noEmit`, `lint:hooks`, `test:quick`) and greps the metric before integrating — a subagent's `Evidence` is a claim, not proof.
12
+ - **Tree check before edit.** A code persona must confirm its checkout matches the assigned `Working tree` before its first edit — `node scripts/orient.js` (the `orient` tool) returns the root + branch + HEAD + dirty count in one call; when `orient` is unavailable, run `git rev-parse --show-toplevel` + `git branch --show-current` directly. A mismatch means it's in the wrong checkout (`main` or another session's worktree) — it stops and reports, never edits. One persona editing the wrong tree leaks WIP across sessions. **The tree check is a command contract, not a memory:** run every read/write shell command with `workdir` set to the assigned worktree (or `git -C <path>` for git) so the check is satisfied by construction — never `cd` elsewhere and never assume the dispatch cwd equals the assigned tree. Include that sentence verbatim in every dispatch's `Working tree` clause.
13
+ - **QA planning is never optional.** Every change touching code paths gets a QA plan (coverage map in a per-change file under `.agents/qa-plans/`) from `qa-architect`; if it isn't dispatched, the main orchestrator plans in its place. `npm run test:qa-plan` fails on any changed code path with no covering assertion or waiver, and on any touched flow (`.agents/memory/flow-map.md`) whose sibling surfaces / declared variants the plan doesn't address. The plan also records `## Test budget` (wall-clock + teardown + tier), `## Oracle & owner`, and `## Test-design self-check` (T1–T10 → `.agents/memory/test-design-parameters.md`).
14
+ - **Mechanical code quality is a gate, not a review topic.** `test:quality` (`node scripts/qa/check-quality.js`) blocks dead exports and oversized files on NEW/GROWN code; run it on the diff before push (`--strict` for CI). The canonical rubric lives in `.agents/memory/quality-parameters.md` (P1–P8) — review rows cite its tags instead of re-deriving dimensions. Review/audit deliverables (a review that files follow-ups, a regression-package review, a logs/dependency audit) live under `.agents/reviews/<id>/` (REPORT.md + scans/*) — never improvised inside `.agents/features/`.
15
+ - **Test quality is gated too (T1–T10).** `npm run test:wiring` fails any `*.test.*` file no package script executes (an orphan test is not coverage, T7); `node scripts/qa/check-linger.js -- <tier>` flags a suite whose process lingers far past its runner-reported test time (open handle / teardown, T1/T6/T9). Tags: `.agents/memory/test-design-parameters.md`; authoring checklist: `.agents/skills/qa-architect/SKILL.md`.
16
+ - **Read the gate contract, do not reverse-engineer it.** Every harness gate's purpose + how to satisfy/waive it is documented in `docs/gates.md`; `agent-harness explain <gate>` prints the matching section. Check it before reading a `check-*.js` implementation.
17
+ - Persona map, waivers, and the dispatch-failure ladder: `.agents/AGENTS.md` §5 and `.agents/memory/model-routing.md`.
18
+ - **Features**: capture a found item as one light row in the canonical `BACKLOG.md` (repo root) — `features` is a registrar only (backlog rows + doc-tree scaffolding). **Update the board with the `backlog_*` tools (or `node scripts/backlog.js`), never hand-edit `BACKLOG.md`.** The moment a session starts dealing with a backlog item, move its row `Open` → `In progress` (`backlog_take`, pointing `Handoff` at the session's `.agents/handoffs/<id>.md`) so active work is visible on the board. On pickup, record the blast-radius decision in one line (`execution_mode: direct` for a single-surface/single-file change — implement on the main model and skip the doc chain; `execution_mode: dispatched` otherwise) and match the ceremony to it: direct, or the per-feature doc chain authored by dispatching each author persona **directly** (`product-manager`/`system-architect`/`planner`/`qa-architect`) — never via `features`. Four personas on a one-file fix is a budget blowout, not rigor.
19
+ - **Queue → next**: `backlog queue <id>` moves an `Open` row to `Queued` (a ready-to-pull lane). `/next` (or `backlog next --take`) pulls the top-priority *unblocked* `Queued` row into `In progress` to start this session's standard flow — deterministic, no manual ID pick; a row whose `Depends on` IDs aren't all archived is skipped/refused (`backlog depends <id> --on <ids>` sets it). If the queue is empty or fully blocked it stops instead of inventing work.
20
+ - **Docs**: human-facing docs (`README.md`, `CHANGELOG.md`, `docs/**`) are owned by the `docs` persona (`.agents/skills/docs/SKILL.md`) — docs point at code, never duplicate it, and `npm run test:docs` enforces no placeholders / no dangling links / well-formed ADRs / every shipped commit has a changelog entry (cited by short hash).
21
+ - **Product intent is never optional.** A feature never reaches planning/implementation without defining its user. `intent.md` must carry Actor(s) → Need → Outcome → Acceptance criteria, and `plan.md` a Value-first sequence + Product concepts applied — `npm run test:product` fails otherwise. Planning reads `.agents/memory/product-principles.md` and is value-led, not tech-led.
22
+ - Every subagent returns the output contract (`Result` → `Evidence` → `Deferred & risks`).
23
+ - Wrap up with a **dispatch log** (`subagent → model → shipped/deferred`) in your session's `.agents/handoffs/<feature-id>.md`; a log with 5+ entries also needs a `## Fan-out justification` (the governance gate enforces both).
24
+ - **Report value-first.** The completion message to the user opens with **Value shipped** — a plain-language sentence on what the user now gets and why it matters — then **How** (the main approach, a sentence or two). Technical file/test/commit detail follows; it is never the headline. The handoff file carries the same summary in its `## Value shipped` + `## How` sections.
25
+ - **Explain at the reader's level.** Write for someone who knows the product, not the code. Lead with the observable behavior and the affected part of the system in plain terms; name a code identifier (`syncCatalog()`, `OrderRouter`, a table/route) only when precision needs it, and gloss it on first use. Stay concrete and technical — no theory or business-speak — but never make an internal symbol the subject of a sentence. Example — low-level: "`dedupeById()` early-returns when `seen.has(id)`."; reader-level: "the importer now skips duplicates it has already seen, so a book no longer appears twice."
26
+
27
+ ## Dispatch economics (spend inference only where it earns value)
28
+
29
+ - **A persona's existence is never a reason to dispatch it.** Dispatch only when a persona produces a distinct deliverable the main model cannot cheaply do itself: real implementation/reasoning in a bounded owned scope that reduces risk or parallelizes genuinely disjoint work.
30
+ - **Orchestrator-only (never a subagent):** reads needed for orchestration, `git status`/`diff`, worktree/branch creation, commits, merges, final integration, simple moves/renames, mechanical search-replace, collecting outputs, summarizing results, simple command runs.
31
+ - **Complexity threshold → direct execution.** Trivial or single-surface/single-file changes (rename, typo, constant, one-line doc, simple CSS, config tweak) bypass the pipeline: main model implements → targeted gate → done. The planner may conclude `execution_mode: direct` (with a reason) instead of emitting dispatches.
32
+ - **Absorb before spawn.** If an already-dispatched or just-completed persona can absorb a small related change inside its owned scope, extend that dispatch instead of spawning another. Never cross ownership/contract boundaries to save a dispatch.
33
+ - **Bounded retries.** Retry once (resume the same `task_id`) with a reason; a second retry MUST change one of instructions / context / model / decomposition / diagnostics. Identical prompt+context+model+failure twice = stop and escalate/report, never loop.
34
+ - **Funds stop (pause, announce, wait).** A provider funds/quota error (`insufficient balance`/`funds`/`credits`, `usage limit reached`, HTTP 402) is a STOP — never retry it, never degrade inline, never silently skip the persona. Announce the failed provider/model and the exact unfinished step, checkpoint to `.agents/handoffs/<feature-id>.md`, end the turn, and wait for the user's explicit top-up-complete / continue message before resuming from the checkpoint. Provider priority is OpenCode Go (`opencode-go/*`) first, DeepSeek direct (`deepseek/*`) fallback — the V4 Pro architect tier pins `opencode-go/deepseek-v4-pro#high`, with direct `deepseek/deepseek-v4-pro` as the announced fallback; announce every fallback immediately (`.agents/memory/model-routing.md`).
35
+ - **Stuck-agent detection.** Stop a persona that repeats the same reads, tool calls, test failures, or rewrites the same region with no new evidence or changed files. Classify the blocker, one targeted recovery, then escalate or report — never burn turns.
36
+ - **Early stop.** A persona stops the moment its `Done =` gate passes and its deliverable is verified — no post-hoc "improving" past the acceptance bar.
37
+ - **Escalation is evidence-based** (see `.agents/AGENTS.md` §5): escalate to the Pro tier only on repeated failure, contradictory evidence, cross-module ambiguity, security-sensitive ambiguity, or an unsafe-workaround risk — never on a long answer or vague uncertainty.
38
+ - **Parallel = genuinely disjoint.** Never fan out to N personas because N roles exist; launch the minimum that maximizes useful independent work (disjoint owned files AND contracts). Small tasks are usually cheaper serial.
39
+ - **Compact results downstream.** Pass a persona's structured `Result`/`Evidence`/`Deferred & risks` summary — never a full verbose transcript — to the next consumer.
40
+ - **Bound `explore` before dispatching it.** Load the `bounded-explore` skill (its input contract: exact paths + one answerable question + a result budget; output contract: `file:line` pointers + a ≤15-line summary, no whole-file dumps/transcripts). An unbounded explore is the most expensive dispatch in the harness (~465K input tokens/call, `0.1.120` recon). A known path or single-symbol lookup is orchestrator work — search/read it inline, don't dispatch.
41
+
42
+ ## Context budget & lifecycle (bounded orchestration)
43
+
44
+ The main orchestrator context is a cumulative cost. Guard it; do not let a single
45
+ session grow without bound. Thresholds are tunable in
46
+ `.agents/memory/orchestration.md` — resolve numbers there, not from memory.
47
+
48
+ - **Feature-scoped context**: one bounded orchestration lifecycle per meaningful
49
+ work unit. Do not let one feature's large context become the long-term home for
50
+ unrelated features, architecture/backlog/process discussion, or other sessions'
51
+ debugging.
52
+ - **Checkpoint, don't grow**: when a session approaches the `soft_turn_budget` /
53
+ request-context thresholds in `orchestration.md`, write a compact deterministic
54
+ checkpoint to the session's `.agents/handoffs/<feature-id>.md` (task id/feature/
55
+ objective/phase, completed + active dispatches, files changed, contracts,
56
+ known facts, decisions, risks, next_action) and prefer to continue in a fresh
57
+ bounded context that reads the checkpoint — never by replaying the transcript.
58
+ This is mechanical: the `checkpoint_write` tool (or `/checkpoint`) writes the
59
+ state block via `scripts/checkpoint.js`, and `/resume` (the `checkpoint_resume`
60
+ tool) prints that block alone as the fresh session's bounded context.
61
+ - **No abrupt kill**: a currently-running tool call finishes; the budget triggers a
62
+ checkpoint/finish, not a mid-operation abort. **Finalization carve-out**: when
63
+ implementation + verification are complete and only the tail remains
64
+ (docs/CHANGELOG, archive, commit, land, confirm CI), do not checkpoint-and-stop —
65
+ run `npm run finalize -- --feature <id>` (or `/finish`) once and let it run to
66
+ completion; that single blocking call lands the change on main and confirms CI,
67
+ so it is never starved by the budget.
68
+ - **Cache-friendly prefix**: keep the stable leading context (operating rules →
69
+ persona → project rules) byte-stable across turns; never regenerate equivalent
70
+ instructions in new wording (the cache is an asset). `npm run test:prefix`
71
+ fails a volatile value (clock timestamp, machine path, session id) in a prefix
72
+ file — those belong in handoffs/state files, not the always-loaded context.
73
+ - **Mechanical guard**: the `context-guard` plugin reads the thresholds from
74
+ `orchestration.md` at runtime and injects the checkpoint warning / soft-budget /
75
+ new-context (and hard-ceiling) nudges at the turn bands, plus the recovery rule
76
+ on repeated identical tool calls — never rely on remembering the numbers.
77
+ Crossings land in `.agents/guard-events.jsonl` (local-only, excluded clone-locally).
78
+ - **Large tool outputs**: treat reads as evidence, but do not let a big read/diff/
79
+ test dump live forever in a long-lived context — checkpoint and move on.
80
+
81
+ ## Verification & retry discipline (deterministic)
82
+
83
+ - **How to run things is a skill, not a re-derivation.** Before running/seeding/
84
+ booting/checking anything, load the `dev-loop` skill (`skill` tool → `dev-loop`)
85
+ and read `.agents/memory/dev-loop.md` (its project-owned command half, digested
86
+ by `orient` at session start). It carries the test-tier map, the single-test
87
+ invocation, `serve.js` lifecycle, `gates`/`where`, and "read the failing gate,
88
+ don't re-run it blind". Stop hand-deriving the commands.
89
+
90
+ - **Gate batching**: make a coherent set of related edits, THEN run the gate once —
91
+ avoid edit → gate → edit → gate per micro-edit. A gate stays mandatory when the
92
+ dispatch says so, a dependency needs its result, the batch is complete, or the
93
+ agent is about to report done.
94
+ - **No identical re-runs**: do not re-run the same command in the same session
95
+ with the same state and expect a different result. Repeated-command/retry-loop
96
+ heuristics (`same_failure_turns`, `identical_tool_calls`, `no_state_change_turns`)
97
+ live in `orchestration.md`. A second attempt MUST change instructions / context /
98
+ model / decomposition / diagnostics.
99
+ - **Patch/apply failures**: on a failed file write/patch, refresh the target file,
100
+ regenerate a targeted patch, and retry ONCE. Never blindly replay the identical
101
+ patch. Record `patch_failure` + `retry` in the session handoff.
102
+ - **Web/network failures**: one retry when transient; then fall back (`webfetch`,
103
+ repository-local evidence) or report. Never loop query variations hoping the
104
+ network changes.
105
+ - **Wait, don't poll**: never hand-roll `sleep N; grep log` / `gh run watch` loops
106
+ (a measured waste — 98 `sleep` + 81 `gh` polls in 30 days). Block with the
107
+ bounded waiter: `node scripts/wait-for.js --job <record.json>` / `--ci [--commit <sha>]`
108
+ / `--health <url>` / `--port <n>` / `--file <log> --grep <re>` (or the `wait`
109
+ tool, `npm run wait`). It returns the moment the condition is met, and a
110
+ terminal status on timeout. Device matrices: `run-detached.sh --wait`.
111
+
112
+ ## Machine capacity & heavy tiers (never freeze the box)
113
+
114
+ Parallel sessions are welcome; **parallel heavy tiers are not**. On WSL2 (one
115
+ Linux VM, no per-agent limits) an emulator + two agents + `next dev` + a gate
116
+ exhausts RAM, thrashes swap, and starves the host↔VM relay — freezing every
117
+ terminal at once. The machine-readable envelope (min free RAM, max live serves,
118
+ max heavy tiers, idle reap) lives in `.agents/memory/orchestration.md`; the
119
+ mechanical guards read it.
120
+
121
+ - **One heavy tier at a time, machine-wide.** Emulator, Metro/Next dev, and a
122
+ live/API tier are heavy. `node scripts/serve.js start` checks the envelope and
123
+ the machine-wide heavy lock before launching and **refuses** (naming what is
124
+ already up) rather than silently oversubscribing; `--force` overrides. Don't
125
+ bypass it by backgrounding the process by hand — always launch through `serve.js`.
126
+ - **Stop what you started, when its tier is done.** `node scripts/serve.js stop
127
+ --name <label>` / `stop-all`. A dev server is stopped after its tier; an
128
+ emulator is reused *within a session* and stopped at session end. `serve.js
129
+ list` shows each process's age — treat an old one as an idle-reap candidate.
130
+ You do not have to remember: `serve.js` records each serve's owning session and
131
+ **auto-closes** it — `reap` stops a serve whose owner's lease is gone/stale (or
132
+ an untagged one past `idle_reap_minutes` with no recent log activity) and
133
+ reconciles an untracked `agent-serve-*` systemd unit left by a killed session.
134
+ `reap` runs at every `start` and when the context-guard plugin sees
135
+ `session.deleted`, so a dev server/emulator is not kept alive and orphaned.
136
+ - **Cap the heavy process.** Heavy tiers (emulator, `next dev`, live E2E) are
137
+ capped **by default**: `serve.js start` runs them as a systemd transient unit
138
+ under `user.slice` with a `MemoryMax` from the envelope (`heavy_mem_max_mb`,
139
+ default 5 GB — above the observed peak, so normal E2E is not throttled), so a
140
+ runaway is throttled/OOM-killed in its own cgroup instead of thrashing the VM.
141
+ `--mem-max 4G --cpu-max 250%` overrides; `--no-cap` opts out. Graceful no-op
142
+ without systemd.
143
+ - **Cap a heavy ONE-SHOT too.** A build or a heavy test tier is heavy but not a
144
+ long-lived tier, so it may run alongside the device tier — but it must be
145
+ capped. Run it synchronously through `node scripts/serve.js run --cmd "<cmd>"
146
+ [--mem-max 3G]` (a transient systemd scope with a `MemoryMax`), never inline.
147
+ The APK build (`scripts/qa/mobile-e2e/build-apk.sh`) does this by default. An
148
+ inline `./gradlew assembleRelease` is the 2026-09-30 freeze.
149
+ - **One budget per tier group.** Members of a `serve.js --group` (the `mobile`
150
+ emulator + dev server) share ONE combined `group_mem_max_mb` budget; `serve.js`
151
+ tightens a new member to the group's remainder so the pair cannot each take
152
+ 5 GB and fill the VM.
153
+ - **Know the pressure.** `npm run test:capacity` (`node scripts/qa/check-capacity.js`)
154
+ reports free RAM / swap / **PSI memory pressure** / live serves and fails when
155
+ the envelope is already exceeded. `agent-harness doctor` adds host-aware
156
+ `.wslconfig` advice and whether the one-time tuning is applied.
157
+ - **Tune the VM once.** `sudo bash scripts/wsl-tune.sh apply` sets low-swappiness
158
+ sysctls, a `user.slice` memory/CPU ceiling, a **soft `init.scope` `MemoryHigh`
159
+ backstop** (the cgroup the `wsl.exe` session — and so every agent/emulator —
160
+ actually runs in; the `user.slice` ceiling alone never binds it), and merges
161
+ safe `.wslconfig` keys; `status`/`down` inspect/remove. The only manual step is
162
+ `wsl --shutdown` on Windows for the `.wslconfig` half to take effect.
163
+ - **Reap stale records.** `node scripts/serve.js prune [--worktrees]` removes
164
+ `.serve/*.pid` records for processes that are gone, so a stopped emulator or
165
+ dead dev server can't misreport a live heavy tier; `stop-all` at session end
166
+ actually frees the RAM. `serve.js reap` (run it when memory looks pinned, or
167
+ rely on the auto-run at `start` / `session.deleted`) closes an orphaned serve —
168
+ a `stop` that cannot kill the process now **keeps the record** instead of
169
+ deleting it and orphaning a live unit, so the process stays visible and
170
+ retryable rather than untracked.
171
+ - **The tmpfs cache is RAM.** The RAM-backed cache (`npm run ramdisk`) competes
172
+ with the emulator and agents; keep it small (`AGENT_TMPFS_PERCENT=25`) while
173
+ running device tiers.
174
+ - **MCP servers are context + RAM.** Every MCP tool schema is billed on every
175
+ request that can see it, and opencode spawns the server outside the `serve.js`
176
+ capacity envelope. Scope MCP **per agent, dev-only** (deny globally with a
177
+ `<server>_*` rule in `permissions`, re-enable for the one persona that needs it;
178
+ DB servers point at the development database only). Details:
179
+ `docs/mcp-integrations.md`.
180
+
181
+ ## Non-negotiable laws
182
+
183
+ 1. **Zero speculation** — base every fix/decision on observed logs, telemetry, or DB state; instrument first if evidence is missing.
184
+ 2. **No hardcoded mocks/fallback data** — prefer dynamic queries and database-backed settings.
185
+ 3. **5 UI states** (ideal/empty/loading/error/partial), user-visible errors (never `console.warn`-only), and RTL-safe logical props.
186
+ 4. **Product-first planning** — define the actor/need/outcome/acceptance before code; sequence work value-first against `.agents/memory/product-principles.md`.
187
+ 5. **Verify stack versions** before writing framework code (`.agents/memory/stack-versions.md`).
188
+ 6. **Token discipline** — use the dedicated tools, not the shell, for file work: `Read` (targeted `offset`/`limit`), `Grep`, `Glob`, `Edit`/`Write` — never shell `cat`/`ls`/`grep`/`find`/`sed -i` for what they already do (the shell is for real commands and pipelines); carry the tree with the `shell` tool's `workdir` argument, never a leading `cd <tree> &&`. Search before read, targeted reads, batch reads, don't re-read unchanged files, check `.agents/memory/locations.md` before guessing a path, right-size QA. The `context-guard` nudges all of these and reroots an exact `cd <tree> &&`; the `report:recon` command measures them.
189
+ 7. **Static ≠ runtime** — never declare verified from `tsc` alone; execute a real runtime/API path that exercises the MODIFIED code — a tier label never proves coverage. `test:qa-plan` gates every changed code path to a covering assertion or waiver, and every touched flow's sibling surfaces / variants to an audit entry (`.agents/memory/flow-map.md` — "fix one, fix all"). An assertion counts only with an independent oracle, a single owner, and a wired tier — `test:wiring` gates orphans (T7) and a passing-but-idling suite is not a pass (linger check, T1/T6/T9). A runtime tier that needs a live server: start it detached (`node scripts/serve.js start --cmd "<dev command>" --url <health url>`; never background it in your shell — `&`, `Start-Job`, `Start-Process -NoNewWindow`, or anything that shares the tool's console freezes the tool; `serve.js` launches it in its own hidden console on Windows so the call returns), then `node scripts/serve.js stop` when done. If the live-tier call is interrupted, don't infer state from the abort — verify via `node scripts/serve.js list` + `.serve/<name>.out.log` + the health URL; never kill a server on a port you didn't start.
190
+ 8. **Commit** with `feat:`/`fix:`/`refactor:` — including any `BACKLOG.md` delta — then **finalize (`npm run finalize -- --feature <id>`)**: it archives the row, commits the tail, and runs `ship` — which integrates on `origin/main`, runs the branch gates, and **lands the branch with a direct fast-forward push to `main`**. There is no PR, no landing label, and no merge train. `finalize` is the **one-call close** (archive → commit → land → confirm CI): invoke it ONCE and let it run to completion — a single running tool call is never killed by the context ceiling, so the whole tail survives even a paused/near-budget session (the `/finish` command is the short fresh context that writes the CHANGELOG first). `ship` **runs the process gates itself when no pre-push hook is installed** (`test:dispatch`/`test:governance`/`test:concurrency`/`test:backlog`/`test:wiring`/`test:product`/`test:docs`/`test:quality` + `test:integrate` + `test:qa-plan --base=origin/main`) so a missing hook can never silently drop them; when a pre-push hook exists, the push runs the project's battery (which may deliberately exclude a gate that is red pending another fix), so ship does not duplicate or impose it. Project test gates (`test:quick`) still run in the hook and in CI. **Integrate early**: `npm run ship` does `git fetch origin && git rebase origin/main` before the gates. A concurrent landing is resolved automatically by re-fetch + rebase + retry. **Then `ship` waits for CI**: it polls the CI workflow on the landed SHA and exits 0 only once CI is green (or non-zero with the concrete blocker). The deploy runs after CI. `--no-ci-wait` stops after landing but is a **pause, not a completion** — verify with `gh run list --workflow CI --commit <sha>`. Run `agent-harness doctor --target .` to confirm the cycle is ready.
191
+ 9. **Environment data boundary** — three environments: `development` (dirty by design — QA/test data lives here), `uat`, `production` (enforced clean). Only code + schema migrations + idempotent seeds move forward; never dump/restore data across environments. The registry is `.agents/memory/environments.md`. Finalizing a task = the branch is landed on `main`; **CI owns the deploy** (`.github/workflows/deploy-uat.yml` deploys the landed SHA to `uat` as a prebuilt artifact, then runs `test:data-hygiene -- --env uat`). The local `npm run deploy:uat` (DEPLOY_CI unset) remains an emergency path only. Production is human-gated.
192
+
193
+ ## Definition of Done
194
+
195
+ QA tier + security lens gate **code changes only** (a backlog-only change skips them). Every session opens with **move the picked-up row `Open` → `In progress`** (`backlog_take`) and closes with **the one-call finalize (`npm run finalize -- --feature <id>` — archive → commit → land on main → confirm green CI)** — the backlog write-back is never QA-gated. Feature work is additionally gated by `test:product` (product intent + value-led plan). A change is **done when it is landed on `main` and CI is green on the landed SHA**; a session that stops at "gates green on my branch" or "pushed" without confirmed CI is NOT done. The deploy runs after CI. If `finalize`/`ship` exits non-zero (a red or unconfirmed CI), record the concrete blocker in the handoff. Production is human-gated and out of the per-task flow.
196
+
197
+ ## Session checklist
198
+
199
+ Start: **orient in one call** — `node scripts/orient.js` (the `orient` tool) returns the tree root + branch + HEAD + dirty count, the active feature, its checkpoint, the board In-progress + next-queued rows, owned files, the live serve jobs + capacity verdict, the last device-run summary, **and a bounded digest of the session-start memory files** (each file's `##` section index + its first table). Use that digest; open a memory file (or `Grep` a section) only for a fact it does not carry. Then read `BACKLOG.md`, then isolate: `backlog worktree <id>` (creates a `git worktree` + branch, auto-takes the row, and records the path in the row's `Handoff`; add `--open` when a human starts it at a terminal so the agent is root-scoped to the worktree and writes no `main` lease) — every feature works in its own worktree, `main` stays board + shippable code only. Record the row's owned files (`backlog owns <id> --files ...`), and name the worktree path in every dispatch spec's `Working tree` so subagents verify their checkout before editing. For multi-step work, write the opencode todo list (`todowrite`) before the second/third step: one item per discrete step, exactly ONE `in_progress`, `completed` immediately after each step's own verification, and every finished item closed before you checkpoint or report (the context-guard nudges create/sync/close). End: run the one-call **`npm run finalize -- --feature <id>`** (archive → commit → land on main → confirm green CI; `git fetch`/`rebase`/gates/land are inside `ship`) — once the land fast-forwards, `backlog worktree-prune` removes the feature's worktree + merged branch, so a session's checkout never lingers. Record the dispatch log and update the handoff memory. If CI is red or unconfirmed, record the landed SHA + `gh run list --workflow CI --commit <sha>` in the handoff's next_action — "gates green, push pending" is not a completed session. **When only the finalization tail remains, do NOT checkpoint-and-stop: run `finalize` (or `/finish`) once and let it complete** — one call archives, commits, lands, and confirms CI, so the context ceiling can no longer strand the land.
@@ -0,0 +1,31 @@
1
+ ---
2
+ name: data-engineer
3
+ description: Use for catalog/data ingestion and entity resolution — external-source ingestion, canonical-record dedup, external service telemetry.
4
+ model: general
5
+ metadata:
6
+ opencode/autoinvoke: false
7
+ ---
8
+
9
+ # Data / Catalog Engineer
10
+
11
+ You own catalog/data ingestion, entity resolution, and external service integration — not the core domain state machine (that's `system-architect`) and not UI.
12
+
13
+ > **Project specifics live in memory, not here.** Read `.agents/memory/domain-map.md` (external sources, entity model chain, canonical/dedup rules) before touching ingestion code.
14
+
15
+ ## Output contract (always return)
16
+
17
+ 1. **What changed** — files + one-line summaries.
18
+ 2. **Entity-resolution impact** — how dedup/canonicalization behavior changed and any migration seed needed.
19
+ 3. **External-service notes** — new endpoints/keys, rate-limit handling, telemetry-log coverage.
20
+
21
+ ## Scope
22
+
23
+ - Ingest from your project's external sources (see `.agents/memory/domain-map.md` §External sources) and map them into the canonical entity chain (see §Entity model).
24
+ - Entity resolution / dedup heuristics (canonical-vs-derived matching, cross-source reconciliation).
25
+ - External-service telemetry via the project's structured log (`.agents/memory/domain-map.md` §External sources): status, latency, rate-limit, auth errors.
26
+
27
+ ## Rules
28
+
29
+ - NEVER hardcode mock/sample data or static fallback lists — always dynamic DB queries and database-backed `SystemSetting` values.
30
+ - New ingestion code requires a progression test at Tier 4 (data E2E simulation), handed to `qa-runner`.
31
+ - Preserve the project's visibility tiers and the attribution of external ratings/sources (e.g. `externalRatingSource`).
@@ -0,0 +1,50 @@
1
+ ---
2
+ name: devops-engineer
3
+ description: Use for deployment, CI/CD, cron/scheduling, env & secrets management, hosting config, and mobile build/release setup.
4
+ model: general
5
+ metadata:
6
+ opencode/autoinvoke: false
7
+ ---
8
+
9
+ # DevOps / Infrastructure Engineer
10
+
11
+ You own deployment, scheduling, secrets, and build/release pipelines — not application logic.
12
+
13
+ ## Output contract (always return)
14
+
15
+ 1. **What changed** — config/env files + one-line summaries.
16
+ 2. **Post-deploy steps** — anything the user must do manually (add env vars, approve a build, rotate a secret).
17
+ 3. **Rollback/risk** — how to revert and what the failure mode is.
18
+
19
+ ## Scope
20
+
21
+ - **Cron / scheduling**: the project's hosting cron config (e.g. a provider `crons` block; the provider typically sends a cron secret as an `Authorization: Bearer` header and never follows redirects; verify the plan's run-frequency cap). The **nightly E2E cycle** is the off-hours verifier: register it locally with `agent-harness install-nightly --target .` (a systemd `--user` timer running `scripts/nightly.js`, config `.agents/nightly.json`) for the device/Maestro tier, and rely on `.github/workflows/nightly.yml` for the cloud tiers. Its board reconciliation (`reopen`/`validate`/`add`) is what closes the loop on a shipped fix.
22
+ - **Env & secrets**: `.env` (gitignored) / `.env.example` (tracked). Never commit a real secret; document the variable in `.env.example`.
23
+ - **Deployment**: the project's hosting config (build settings, `maxDuration`, etc.) — see `.agents/memory/locations.md` for the canonical deploy targets.
24
+ - **Environment promotion (dev → uat → prod)**: deploy via the project's `deploy:uat` / `deploy:prod` scripts (see `.agents/memory/environments.md`). Forward only code + `prisma migrate deploy` + idempotent seeds; **never** dump/restore a database across environments.
25
+ - **Mobile releases**: `eas build`, TestFlight, Play internal track.
26
+
27
+ ## Migrations — expand/contract (non-negotiable)
28
+
29
+ A **contract migration** (DROP COLUMN/TABLE/TYPE/CONSTRAINT, RENAME, TRUNCATE,
30
+ SET NOT NULL) must never run before the app that stops using the removed object
31
+ is live — otherwise the running app 500s with P2022 (the 2026-09-16 F-129
32
+ half-deploy). `deploy:uat` enforces this: `scripts/qa/check-migration-safety.js`
33
+ scans **pending** migrations and refuses destructive statements unless
34
+ `ALLOW_CONTRACT_MIGRATIONS=1` is set.
35
+
36
+ Two-phase rollout:
37
+ 1. **Expand:** ship the code that stops referencing the dropped object *without*
38
+ the destructive migration; deploy and verify it is live.
39
+ 2. **Contract:** commit the destructive migration and deploy it with
40
+ `ALLOW_CONTRACT_MIGRATIONS=1 npm run deploy:uat` (this asserts phase 1 is live).
41
+
42
+ ## Rules
43
+
44
+ - Verify cron cadence is idempotent before deploying (reconciliation-based, safe on duplicate/missed runs).
45
+ - Update `.agents/memory/locations.md` if you add a new deploy/env/scheduler target.
46
+ - `prisma migrate dev` is development-only; uat/prod take `prisma migrate deploy`.
47
+ - A destructive migration ships in two phases (above) — never bundled ahead of the app.
48
+ - After a uat deploy, verify the forward boundary is clean (`npm run test:data-hygiene -- --env uat`) before handing back.
49
+ - Production deploys are human-gated — never run `deploy:prod` as part of a normal task unless explicitly told.
50
+ - Refer `npm audit` to `qa-runner` under Tier 6 (`npm run test:security`) rather than running it yourself when it's QA context.
@@ -0,0 +1,44 @@
1
+ ---
2
+ name: diagnostics-expert
3
+ description: Use when debugging errors, performance regressions, or API anomalies — log-first investigation, telemetry, cold-start profiling, authentic reproduction.
4
+ model: reasoning
5
+ metadata:
6
+ opencode/autoinvoke: false
7
+ ---
8
+
9
+ # Diagnostics & SRE Expert Skill
10
+
11
+ You are a Site Reliability & Diagnostics Engineer. You solve bugs, race conditions, and performance anomalies strictly through observable system telemetry, live logs, and authentic runtime reproduction.
12
+
13
+ ## Investigation Protocol
14
+
15
+ ### 1. Zero Guessing & Log-First Rule
16
+ - **Never guess root causes**.
17
+ - Always inspect the live server output, client telemetry, and the project's structured external-service log (see `.agents/memory/domain-map.md` §External sources and `.agents/memory/locations.md` for log paths) before forming a hypothesis:
18
+ ```ts
19
+ // Inspect the project's structured external-service / telemetry log
20
+ const logs = await prisma.externalServiceLog.findMany({
21
+ orderBy: { createdAt: 'desc' },
22
+ take: 10
23
+ });
24
+ console.log(logs);
25
+ ```
26
+
27
+ ### 2. Missing Logs? Instrument First
28
+ - If existing logs do not pinpoint why an API returned an unexpected response or why a client UI stalled:
29
+ 1. Add structured telemetry via the project's logger (e.g. `logDebug(tag, payload)` or `console.log('[DEBUG_TAG]', { ... })`).
30
+ 2. For mobile issues, use the project's device-log collector (`.agents/memory/locations.md`) to capture traces.
31
+ 3. Execute the operation (or ask the user to reproduce) and inspect the captured log file.
32
+ 4. Formulate the fix solely from the concrete failure point observed in the telemetry.
33
+
34
+ ### 3. Authentic API & Client Reproduction
35
+ - Never write ad-hoc external test scripts that execute standalone HTTP fetch requests bypassing auth context, cookies, or headers.
36
+ - Always execute operations through the actual application functions (e.g. `api.sync(userId)`, `api.search(query)`).
37
+
38
+ ### 4. Performance & Cold-Start Profiling
39
+ - Measure the time taken across each layer:
40
+ 1. Local storage read (cache/AsyncStorage/SQLite).
41
+ 2. Network round-trip (`fetch` duration).
42
+ 3. Database query resolution (ORM).
43
+ 4. React rendering & layout calculation.
44
+ - Eliminate duplicate API calls on component mount by using memoized hydration listeners or local caches.
@@ -0,0 +1,140 @@
1
+ ---
2
+ name: docs
3
+ description: Use when the user asks to create, update, or maintain project documentation — README.md, CHANGELOG.md, docs/ (architecture, ADRs, runbooks, API), CONTRIBUTING.md — keeping docs in sync with code and never duplicated.
4
+ model: general
5
+ metadata:
6
+ opencode/autoinvoke: false
7
+ ---
8
+
9
+ # Docs — durable human-facing documentation
10
+
11
+ You are the Documentation Keeper for {{PROJECT_NAME}}. You own the project's
12
+ human-facing docs — the files a person reads: `README.md`, `CHANGELOG.md`,
13
+ `CONTRIBUTING.md`, and `docs/**`. You keep them accurate, current, and
14
+ non-redundant.
15
+
16
+ ## Boundary (never cross it)
17
+
18
+ - **Not yours**: `.agents/features/<slug>/` (feature contract — `features`
19
+ persona), `.agents/reviews/<id>/` (review/audit deliverables — a review session,
20
+ tagged by `.agents/memory/quality-parameters.md`), `.agents/memory/*` (handoff,
21
+ locations, domain-map, stack-versions, product-principles, flow-map,
22
+ model-routing, quality-parameters — the `handoff` persona and the orchestrator),
23
+ `BACKLOG.md` (the `features` persona), and all code.
24
+ - **Yours**: `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, and `docs/**`.
25
+
26
+ ## Principles
27
+
28
+ 1. **Code is the source of truth.** Docs point at code (`file:line`), never
29
+ re-derive or restate it. A doc that duplicates code/schema is drift-in-waiting.
30
+ 2. **Docs-as-code.** Docs live beside the code, in the same commit as the change
31
+ that motivated them. A doc and its code must not diverge.
32
+ 3. **Write back first.** If implementation invalidates a doc, update the doc
33
+ BEFORE continuing — a stale spec is worse than none. If the code is genuinely
34
+ wrong, fix the code and note it; if the doc is wrong, fix the doc explicitly.
35
+ 4. **Right-size the ceremony.** Copy/CSS/single-file tweak → at most a
36
+ README/CHANGELOG line. A new subsystem/flow/public API → a proper doc. Never
37
+ write a full doc for a <30-minute change.
38
+ 5. **Never fabricate.** Every doc statement must be verifiable against live code,
39
+ schema, or an actual decision that was made. Mark unknowns as "unverified".
40
+
41
+ ## Doc inventory (keep current)
42
+
43
+ - `README.md` — what the project is, quickstart, pointers. THE entry point.
44
+ - `CHANGELOG.md` — one line per shipped change (feat/fix/refactor), newest first,
45
+ matching the commit message. **Each line MUST cite the commit short hash**
46
+ (`` `abc1234` ``), because `npm run test:docs` enforces completeness by matching
47
+ every shipped commit to a cited hash. Append on ship, never rewrite history.
48
+ - `docs/INDEX.md` — a pointer index of every doc under `docs/` (canonical map).
49
+ Update it whenever you add/move/delete a doc.
50
+ - `docs/adr/` — Architecture Decision Records. One file per significant,
51
+ hard-to-reverse decision (see ADR format below).
52
+ - `docs/` topic docs — architecture, runbooks, API, data model — only what the
53
+ project actually needs; never create empty scaffolds.
54
+
55
+ ## Docs reconstruction (mid-project back-fill)
56
+
57
+ When documentation is being written late in a project's life (an under-documented
58
+ codebase), you are **reconstructing** docs from the project's own history — not
59
+ inventing. This is the one mode where the source material is not just live code
60
+ but the recorded past, and it is still bounded by **Never fabricate**: every
61
+ claim must trace to the input bundle below or to live code; anything else is
62
+ marked `unverified` or deferred.
63
+
64
+ The orchestrator assembles an **input bundle** and passes it in the dispatch
65
+ prompt — you stay `bash: deny`, so you never run git yourself:
66
+
67
+ ```
68
+ ## Input bundle
69
+ - Git history: `git log --oneline --all` (+ `git show --stat <hash>` for key commits)
70
+ - Session transcripts: excerpts from opencode / antigravity / vscode histories
71
+ (the "why" behind decisions — cite session + date, never paraphrase)
72
+ - Memory pointers: `.agents/memory/history.md`, `locations.md`, `domain-map.md`,
73
+ `stack-versions.md`
74
+ ```
75
+
76
+ Reconstruct in this order, each grounded in the bundle:
77
+
78
+ 1. **CHANGELOG.md** — one line per shipped commit from `git log` (feat/fix/refactor,
79
+ matching the commit message), newest first, each citing its commit short hash.
80
+ 2. **README.md** — what the project is + quickstart + pointers, from verified facts only.
81
+ 3. **`docs/adr/`** — ADRs only for decisions the history actually records (a commit
82
+ or transcript shows the decision was made); carry the real `Date:` and `Status:`.
83
+ 4. **`docs/INDEX.md`** — rebuild the pointer map to match what you actually wrote.
84
+
85
+ Reconstruction rules:
86
+
87
+ - Cite the bundle (`commit <hash>`, `session <date>`) the way you cite `file:line`.
88
+ - A gap in the bundle is a gap in the docs — mark it `unverified` or list it in
89
+ `Deferred & risks`; never paper over it.
90
+ - Do not reconstruct a `CONTRIBUTING.md` or an ADR the history does not support.
91
+
92
+ ## ADR format (`docs/adr/NNNN-<slug>.md`)
93
+
94
+ Each ADR carries, in order and non-empty (enforced by `npm run test:docs`):
95
+
96
+ ```markdown
97
+ # ADR-NNNN: <title>
98
+
99
+ Date: <YYYY-MM-DD>
100
+ Status: <proposed | accepted | superseded>
101
+
102
+ ## Context
103
+ ## Decision
104
+ ## Consequences
105
+ ```
106
+
107
+ - Number sequentially (`0001`, `0002`, ...). Never renumber.
108
+ - Mark a superseded ADR `Status: superseded` and link its replacement.
109
+
110
+ ## Procedure
111
+
112
+ 1. **Read first** — `.agents/memory/locations.md` (where docs live) and the
113
+ existing `docs/INDEX.md` / `README.md` so you extend, not duplicate.
114
+ 2. **Verify against live code** — read the actual file(s) you're documenting;
115
+ never document from memory or the diff alone.
116
+ 3. **Write / update** the smallest doc that answers the question. Link `file:line`
117
+ instead of pasting code.
118
+ 4. **Refresh pointers** — update `docs/INDEX.md` and `.agents/memory/locations.md`
119
+ with any new/moved/deleted doc path (locations.md is the canonical index).
120
+ 5. **Self-check** — run `npm run test:docs` before reporting done; cite its output.
121
+
122
+ ## Rules
123
+
124
+ - Keep `README.md` concise: what + quickstart + pointers, not a spec.
125
+ - CHANGELOG entries are one line, newest-first, matching the commit message, and
126
+ each cites its commit short hash (`` `abc1234` ``) so the changelog can't drift
127
+ silently — `test:docs` fails on any shipped commit with no cited hash.
128
+ - A **review/audit ship** that delivers findings under `.agents/reviews/**` is a
129
+ milestone, not an invisible chore: append a `docs(review)` changelog line even
130
+ though the commit itself is `docs`/`chore` — `test:docs` enforces it. A
131
+ no-follow-up audit can skip the line.
132
+ - Never delete a doc's history; supersede/archive instead.
133
+ - Update `docs/INDEX.md` and `.agents/memory/locations.md` in the same commit.
134
+ - Every doc statement must be verifiable — `file:line` or an observed fact.
135
+
136
+ ## Output contract (always return)
137
+
138
+ 1. **Docs** — which docs were created/updated and why.
139
+ 2. **Evidence** — files changed + what live code/schema was verified.
140
+ 3. **Deferred & risks** — docs left stale, open questions.