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.
- package/CHANGELOG.md +217 -0
- package/LICENSE +21 -0
- package/README.md +636 -2
- package/bin/agent-harness.js +3182 -0
- package/contrib/global-plugins/README.md +49 -0
- package/contrib/global-plugins/harness-freshness.ts +355 -0
- package/package.json +86 -4
- package/templates/.agents/AGENTS.md +148 -0
- package/templates/.agents/features/INDEX.md +10 -0
- package/templates/.agents/handoffs/README.md +87 -0
- package/templates/.agents/memory/dev-loop.md +59 -0
- package/templates/.agents/memory/domain-map.md +29 -0
- package/templates/.agents/memory/environments.md +35 -0
- package/templates/.agents/memory/flow-map.md +23 -0
- package/templates/.agents/memory/history.md +7 -0
- package/templates/.agents/memory/locations.md +14 -0
- package/templates/.agents/memory/model-routing.md +261 -0
- package/templates/.agents/memory/orchestration.md +183 -0
- package/templates/.agents/memory/owned-files.md +19 -0
- package/templates/.agents/memory/product-principles.md +37 -0
- package/templates/.agents/memory/quality-parameters.md +37 -0
- package/templates/.agents/memory/stack-versions.md +35 -0
- package/templates/.agents/memory/test-design-parameters.md +36 -0
- package/templates/.agents/nightly.json +17 -0
- package/templates/.agents/qa-plans/README.md +70 -0
- package/templates/.agents/qa-runs/README.md +21 -0
- package/templates/.agents/reviews/README.md +47 -0
- package/templates/.agents/rules/00-operating.md +199 -0
- package/templates/.agents/skills/data-engineer/SKILL.md +31 -0
- package/templates/.agents/skills/devops-engineer/SKILL.md +50 -0
- package/templates/.agents/skills/diagnostics-expert/SKILL.md +44 -0
- package/templates/.agents/skills/docs/SKILL.md +140 -0
- package/templates/.agents/skills/features/SKILL.md +187 -0
- package/templates/.agents/skills/frontend-engineer/SKILL.md +81 -0
- package/templates/.agents/skills/handoff/SKILL.md +85 -0
- package/templates/.agents/skills/mobile-engineer/SKILL.md +101 -0
- package/templates/.agents/skills/planner/SKILL.md +112 -0
- package/templates/.agents/skills/product-manager/SKILL.md +115 -0
- package/templates/.agents/skills/qa-architect/SKILL.md +224 -0
- package/templates/.agents/skills/qa-runner/SKILL.md +64 -0
- package/templates/.agents/skills/security-engineer/SKILL.md +53 -0
- package/templates/.agents/skills/system-architect/SKILL.md +42 -0
- package/templates/.agents/skills/ui-designer/SKILL.md +71 -0
- package/templates/.github/workflows/ci.yml +148 -0
- package/templates/.github/workflows/deploy-uat.yml +95 -0
- package/templates/.github/workflows/nightly.yml +83 -0
- package/templates/.github/workflows/uat-health.yml +41 -0
- package/templates/.husky/pre-push +23 -0
- package/templates/.ignore +28 -0
- package/templates/.opencode/agents/data-engineer.md +37 -0
- package/templates/.opencode/agents/devops-engineer.md +37 -0
- package/templates/.opencode/agents/diagnostics-expert.md +37 -0
- package/templates/.opencode/agents/docs.md +37 -0
- package/templates/.opencode/agents/features.md +21 -0
- package/templates/.opencode/agents/frontend-engineer.md +37 -0
- package/templates/.opencode/agents/handoff.md +21 -0
- package/templates/.opencode/agents/mobile-engineer.md +37 -0
- package/templates/.opencode/agents/planner.md +34 -0
- package/templates/.opencode/agents/product-manager.md +29 -0
- package/templates/.opencode/agents/qa-architect.md +27 -0
- package/templates/.opencode/agents/qa-runner.md +17 -0
- package/templates/.opencode/agents/security-engineer.md +37 -0
- package/templates/.opencode/agents/system-architect.md +37 -0
- package/templates/.opencode/agents/ui-designer.md +37 -0
- package/templates/.opencode/commands/board.md +15 -0
- package/templates/.opencode/commands/checkpoint.md +25 -0
- package/templates/.opencode/commands/feature.md +56 -0
- package/templates/.opencode/commands/finish.md +36 -0
- package/templates/.opencode/commands/next.md +49 -0
- package/templates/.opencode/commands/report.md +55 -0
- package/templates/.opencode/commands/resume.md +39 -0
- package/templates/.opencode/commands/switch-model.md +34 -0
- package/templates/.opencode/commands/tidy.md +49 -0
- package/templates/.opencode/plugins/backlog-notify.ts +57 -0
- package/templates/.opencode/plugins/backlog.ts +272 -0
- package/templates/.opencode/plugins/checkpoint.ts +160 -0
- package/templates/.opencode/plugins/context-guard.ts +1164 -0
- package/templates/.opencode/plugins/diff.ts +85 -0
- package/templates/.opencode/plugins/gates.ts +71 -0
- package/templates/.opencode/plugins/job-notify.ts +241 -0
- package/templates/.opencode/plugins/orient.ts +67 -0
- package/templates/.opencode/plugins/session.ts +89 -0
- package/templates/.opencode/plugins/wait.ts +101 -0
- package/templates/.opencode/plugins/where.ts +70 -0
- package/templates/.opencode/skills/bounded-explore/SKILL.md +38 -0
- package/templates/.opencode/skills/dev-loop/SKILL.md +87 -0
- package/templates/.vercelignore +16 -0
- package/templates/AGENTS.md +27 -0
- package/templates/BACKLOG.md +95 -0
- package/templates/docs/ci-cd-pipeline.md +81 -0
- package/templates/docs/gates.md +128 -0
- package/templates/docs/mcp-integrations.md +97 -0
- package/templates/docs/mobile-testing.md +555 -0
- package/templates/docs/nightly-testing.md +106 -0
- package/templates/docs/wsl-optimizations.md +290 -0
- package/templates/opencode.json +188 -0
- package/templates/scripts/agent-report.js +541 -0
- package/templates/scripts/agent-search.sh +117 -0
- package/templates/scripts/backlog.js +1924 -0
- package/templates/scripts/board-service.sh +214 -0
- package/templates/scripts/checkpoint.js +290 -0
- package/templates/scripts/finalize.js +416 -0
- package/templates/scripts/nightly.js +913 -0
- package/templates/scripts/orient.js +514 -0
- package/templates/scripts/qa/board-client.js +323 -0
- package/templates/scripts/qa/board-lib.js +96 -0
- package/templates/scripts/qa/board-sync.js +499 -0
- package/templates/scripts/qa/capacity-lib.js +916 -0
- package/templates/scripts/qa/check-backlog.js +434 -0
- package/templates/scripts/qa/check-capacity.js +85 -0
- package/templates/scripts/qa/check-ci-policy.js +164 -0
- package/templates/scripts/qa/check-concurrency.js +344 -0
- package/templates/scripts/qa/check-dispatch-config.js +296 -0
- package/templates/scripts/qa/check-docs.js +288 -0
- package/templates/scripts/qa/check-integrate.js +98 -0
- package/templates/scripts/qa/check-linger.js +160 -0
- package/templates/scripts/qa/check-prefix-stability.js +187 -0
- package/templates/scripts/qa/check-product.js +177 -0
- package/templates/scripts/qa/check-qa-plan.js +378 -0
- package/templates/scripts/qa/check-qa-scripts.js +85 -0
- package/templates/scripts/qa/check-quality.js +249 -0
- package/templates/scripts/qa/check-test-wiring.js +253 -0
- package/templates/scripts/qa/check-worktrees.js +93 -0
- package/templates/scripts/qa/ci-triage.js +346 -0
- package/templates/scripts/qa/ci-usage-lib.js +185 -0
- package/templates/scripts/qa/ci-wait-lib.js +294 -0
- package/templates/scripts/qa/command-classifier.js +552 -0
- package/templates/scripts/qa/context-guard-core.js +1618 -0
- package/templates/scripts/qa/diff.js +174 -0
- package/templates/scripts/qa/feature-scaffold.js +224 -0
- package/templates/scripts/qa/fixtures/backlog.md +104 -0
- package/templates/scripts/qa/governance.js +174 -0
- package/templates/scripts/qa/hash-file.js +32 -0
- package/templates/scripts/qa/lease-lib.js +263 -0
- package/templates/scripts/qa/merge-backlog.js +324 -0
- package/templates/scripts/qa/mobile-e2e/analyze-timings.js +300 -0
- package/templates/scripts/qa/mobile-e2e/apk-cache.js +420 -0
- package/templates/scripts/qa/mobile-e2e/backend-build-cache.js +203 -0
- package/templates/scripts/qa/mobile-e2e/boot-emulator.sh +432 -0
- package/templates/scripts/qa/mobile-e2e/build-apk.sh +210 -0
- package/templates/scripts/qa/mobile-e2e/check-flows.js +568 -0
- package/templates/scripts/qa/mobile-e2e/config.yaml +18 -0
- package/templates/scripts/qa/mobile-e2e/device-down.sh +88 -0
- package/templates/scripts/qa/mobile-e2e/device-up.sh +258 -0
- package/templates/scripts/qa/mobile-e2e/ios-simulator-down.sh +72 -0
- package/templates/scripts/qa/mobile-e2e/ios-simulator-up.sh +153 -0
- package/templates/scripts/qa/mobile-e2e/job-events.js +181 -0
- package/templates/scripts/qa/mobile-e2e/prewarm.sh +56 -0
- package/templates/scripts/qa/mobile-e2e/run-detached.sh +222 -0
- package/templates/scripts/qa/mobile-e2e/run-maestro.js +1543 -0
- package/templates/scripts/qa/mobile-e2e/ui-dump.js +327 -0
- package/templates/scripts/qa/models.allowlist.txt +32 -0
- package/templates/scripts/qa/provider-stats.js +878 -0
- package/templates/scripts/qa/run-clean.js +83 -0
- package/templates/scripts/qa/run-gates.js +213 -0
- package/templates/scripts/qa/run-loop.js +220 -0
- package/templates/scripts/qa/session-recon.js +512 -0
- package/templates/scripts/qa/store-lib.js +324 -0
- package/templates/scripts/qa/tool-lib.js +134 -0
- package/templates/scripts/qa/where.js +214 -0
- package/templates/scripts/qa/worktree-hygiene.js +217 -0
- package/templates/scripts/qa/wslconfig-merge.js +157 -0
- package/templates/scripts/serve.js +1328 -0
- package/templates/scripts/setup-nightly.sh +185 -0
- package/templates/scripts/setup-tmpfs.sh +374 -0
- package/templates/scripts/ship.js +586 -0
- package/templates/scripts/switch-reasoning-model.ps1 +101 -0
- package/templates/scripts/switch-reasoning-model.sh +104 -0
- package/templates/scripts/wait-for.js +342 -0
- package/templates/scripts/wsl-gpu.sh +180 -0
- package/templates/scripts/wsl-tune.sh +319 -0
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
# Model routing
|
|
2
|
+
|
|
3
|
+
This project's subagent personas run on their own models via the `model:`
|
|
4
|
+
frontmatter in `.opencode/agents/<name>.md`. This file documents the tiering
|
|
5
|
+
policy — the concrete model IDs are the source of truth in the agent files
|
|
6
|
+
(and `opencode.json` for the main conversation).
|
|
7
|
+
|
|
8
|
+
## Tiers (recommended — override per-project)
|
|
9
|
+
|
|
10
|
+
| Tier | Purpose | Default lane |
|
|
11
|
+
|---|---|---|
|
|
12
|
+
| reasoning (hard) | System architecture, security review | strongest reasoning |
|
|
13
|
+
| reasoning (plan/review) | Planning, QA architecture — an unrecoverable logic error here poisons everything downstream | strongest reasoning |
|
|
14
|
+
| reasoning (debug) | Error / performance / API debugging | fast frontier |
|
|
15
|
+
| engineering (general) | Everyday coding, mobile native, infra/devops, data, QA execution | cheap fast coder |
|
|
16
|
+
| content (general) | UI design, product journeys, feature registrar, docs | strong generalist |
|
|
17
|
+
| mechanical | Handoffs | cheap fast |
|
|
18
|
+
| opportunistic (free/low-cost) | Bulk exploration, repo-wide search/summarize, mechanical repetition — best-effort only, never authoritative | free/low-cost |
|
|
19
|
+
|
|
20
|
+
The reasoning tier is split by persona. Hard reasoning (architecture, security)
|
|
21
|
+
and plan/review (planner, qa-architect) run on the strongest reasoning model —
|
|
22
|
+
a planner/QA architect that makes a logic error invalidates the whole dispatch
|
|
23
|
+
plan, so they are priced as architects, not as coders. Debugging and general
|
|
24
|
+
engineering run on a fast frontier coder (cheap, strong on coding benchmarks,
|
|
25
|
+
better cache pricing); UI/docs/features/product content keeps the strong
|
|
26
|
+
generalist. The harness ships a recommended concrete mapping for each lane
|
|
27
|
+
(strongest reasoning → `opencode-go/deepseek-v4-pro#high` on the **OpenCode Go
|
|
28
|
+
subscription**, with the direct `deepseek/deepseek-v4-pro` key as the announced
|
|
29
|
+
fallback; fast frontier + engineering → `opencode-go/deepseek-v4.1-flash#high`,
|
|
30
|
+
content → `opencode-go/gpt-5.6-luna`, mechanical → `opencode-go/glm-5.3-flash`).
|
|
31
|
+
Change it only by editing `.opencode/agents/<name>.md` `model:` — the `model:`
|
|
32
|
+
label in `.agents/skills/*/SKILL.md` is informational only and does NOT route
|
|
33
|
+
models.
|
|
34
|
+
|
|
35
|
+
## Provider priority & fallback (Go first for every tier; direct is the announced fallback)
|
|
36
|
+
|
|
37
|
+
Every tier runs through the **OpenCode Go subscription first** (`opencode-go/*`),
|
|
38
|
+
including the **V4 Pro architect tier** (`planner`, `qa-architect`,
|
|
39
|
+
`system-architect`, `security-engineer`), which pins
|
|
40
|
+
`opencode-go/deepseek-v4-pro#high`. The **DeepSeek direct API key**
|
|
41
|
+
(`deepseek/deepseek-v4-pro`) is the **announced fallback** for the Pro tier when
|
|
42
|
+
Go is unavailable or its usage limit is hit. (This inverted the older "V4 Pro
|
|
43
|
+
always runs direct" rule: the 2026-09-16/17 field log recorded 3 `funds` stops on
|
|
44
|
+
`deepseek/deepseek-v4-pro` direct, so a single pay-per-token key was gating the
|
|
45
|
+
highest-value personas — exactly the failure mode Go-first removes.)
|
|
46
|
+
|
|
47
|
+
| Priority | Provider | Main-tier example | Role |
|
|
48
|
+
|---|---|---|---|
|
|
49
|
+
| 1 | OpenCode Go (`opencode-go/<model-id>`) | `opencode-go/deepseek-v4.1-flash#high`, `opencode-go/deepseek-v4-pro#high` | default for every tier (flash/content/mechanical *and* the Pro architect tier) — the $10/mo subscription quota pays for it |
|
|
50
|
+
| 2 | DeepSeek direct (`deepseek/<model-id>`) | `deepseek/deepseek-v4-pro`, `deepseek/deepseek-flash` | announced fallback when Go is unavailable or its usage limit is hit |
|
|
51
|
+
|
|
52
|
+
**Zen pay-as-you-go (`opencode/*`) is not part of the policy.** The only two
|
|
53
|
+
providers are the Go subscription and the direct DeepSeek API key — no agent,
|
|
54
|
+
`opencode.json` override, switch alias, or machine-read target may pin a Zen
|
|
55
|
+
model (`explore` included: default `opencode-go/glm-5.3-flash`).
|
|
56
|
+
|
|
57
|
+
- **V4 Pro runs on Go first.** The architect tier pins
|
|
58
|
+
`opencode-go/deepseek-v4-pro#high`; the direct `deepseek/deepseek-v4-pro` key is
|
|
59
|
+
the **announced fallback** (availability/usage-limit only), so no single key
|
|
60
|
+
gates the Pro personas.
|
|
61
|
+
- **Announce every fallback immediately.** Name the failed provider/model, the
|
|
62
|
+
observed reason, and the provider you are switching to — in chat, before
|
|
63
|
+
continuing. A fallback the user cannot see is a silent process change and is
|
|
64
|
+
forbidden. Record it in the session handoff dispatch log too.
|
|
65
|
+
- Fall back to direct only for **availability / usage-limit** errors. A
|
|
66
|
+
**funds/credit** error is a stop (below), never a fallback trigger.
|
|
67
|
+
- opencode reads model config once at startup and does not hot-reload it: switch
|
|
68
|
+
the main conversation with the `/switch-model` command (alias `go` → Go
|
|
69
|
+
default, `direct`/`deepseek` → direct fallback), and switch a persona by
|
|
70
|
+
editing its `.opencode/agents/<name>.md` `model:` then restarting/re-dispatching.
|
|
71
|
+
The `switch-reasoning-model.ps1` replace list is derived from its alias map, so
|
|
72
|
+
any alias it can switch TO it can also switch FROM.
|
|
73
|
+
|
|
74
|
+
## Provider funds stop (hard rule — pause, announce, wait)
|
|
75
|
+
|
|
76
|
+
A provider error reporting **insufficient funds / balance / credits / quota**
|
|
77
|
+
(`insufficient balance`, `insufficient funds`, `out of credits`, `usage limit
|
|
78
|
+
reached`, HTTP 402, ...) is NOT a retry, NOT a degraded-inline condition, and NOT
|
|
79
|
+
a reason to silently leave the designed multi-agent process.
|
|
80
|
+
|
|
81
|
+
1. **Stop starting work** — no inline substitute for the failed persona, no
|
|
82
|
+
silent re-scope, no repeated dispatch/retry of the same call.
|
|
83
|
+
2. **Announce immediately** in chat: which provider/model failed, the exact
|
|
84
|
+
error, and the exact step left unfinished — never a vague "dispatch failed".
|
|
85
|
+
3. **Checkpoint** the session state into `.agents/handoffs/<feature-id>.md` so the
|
|
86
|
+
work resumes exactly where it stopped.
|
|
87
|
+
4. **Wait** — end the turn and wait for the user's explicit *top-up done /
|
|
88
|
+
continue* message. Never assume a top-up happened.
|
|
89
|
+
5. On the user's go-ahead, **resume from the checkpoint** (never by replaying the
|
|
90
|
+
transcript) and record the pause honestly (`termination_reason` in the
|
|
91
|
+
handoff).
|
|
92
|
+
|
|
93
|
+
This overrides the dispatch-failure ladder below for funds/quota errors. The
|
|
94
|
+
`context-guard` plugin mechanically detects such an error from **structured
|
|
95
|
+
failure evidence only** — a failed dispatch (the task error text), a command
|
|
96
|
+
that exited non-zero, or a subagent session error — attributes it with the
|
|
97
|
+
observed provider/model (the task result's `metadata.model` or the child
|
|
98
|
+
assistant message's `providerID/modelID`) and injects the stop naming that
|
|
99
|
+
provider/model into the next request — the top-up target is evidence, never a
|
|
100
|
+
guess. Reading a document that merely quotes this rule (the mandated
|
|
101
|
+
session-start `model-routing.md` itself, a handoff, a QA plan) is **not**
|
|
102
|
+
failure evidence and never trips the stop. Each detection is recorded in
|
|
103
|
+
`.agents/guard-events.jsonl` with `provider`/`model`.
|
|
104
|
+
|
|
105
|
+
### Opportunistic tier (free / low-cost models)
|
|
106
|
+
|
|
107
|
+
Free or near-free models are a **best-effort** lane, never an authority. Use
|
|
108
|
+
them for genuinely disposable work: broad exploration/searches, chunk
|
|
109
|
+
summarization, mechanical repetition, first-pass drafts. The built-in `explore`
|
|
110
|
+
subagent is the reference pin — the harness ships it as
|
|
111
|
+
`opencode.json` → `agents.explore.model` (default `opencode-go/glm-5.3-flash` —
|
|
112
|
+
the Go subscription's cheap flash model; Zen pay-as-you-go `opencode/*` is not
|
|
113
|
+
in the policy) and a project may repoint it, on its main persona set or not at
|
|
114
|
+
all.
|
|
115
|
+
|
|
116
|
+
- **Mandatory fallback.** When an opportunistic model fails, returns empty, or
|
|
117
|
+
is unavailable, fall back to the persona's normal tier (retry once per the
|
|
118
|
+
dispatch-failure ladder, then degrade inline and log
|
|
119
|
+
`degraded: <persona> model: <reason>`). Never block a deliverable on a free
|
|
120
|
+
model. **Exception:** a funds/quota error follows the provider funds stop
|
|
121
|
+
above — pause and announce, never silently degrade.
|
|
122
|
+
- **Not for authoritative output.** Explore→summaries and mechanical edits must
|
|
123
|
+
be verified by the normal tier before they count as evidence; never route a
|
|
124
|
+
thinker (planner/product-manager/system-architect/qa-architect) or a persona
|
|
125
|
+
whose output gates work to the opportunistic tier.
|
|
126
|
+
- **Privacy caveat.** Free models may be training-enabled. Never send
|
|
127
|
+
confidential data, secrets, credentials, personal/customer data, or unpublishable
|
|
128
|
+
source to an opportunistic model.
|
|
129
|
+
- **Machine-readable list** (reports classify model mix with it):
|
|
130
|
+
`opportunistic_models:` in the section below.
|
|
131
|
+
|
|
132
|
+
## Per-persona enforcement
|
|
133
|
+
|
|
134
|
+
In addition to `model:`, agent files carry mechanical guardrails in their
|
|
135
|
+
frontmatter:
|
|
136
|
+
|
|
137
|
+
- **Thinkers** (`planner`, `product-manager`) have edit **deny-by-default** with a
|
|
138
|
+
**narrow artifact write grant**: `planner` may write only
|
|
139
|
+
`.agents/features/<feature>/plan.md`, `product-manager` only
|
|
140
|
+
`.agents/features/<feature>/intent.md` — each writable in the main tree **or the
|
|
141
|
+
feature's git worktree sibling** (`../.worktrees/**`, where every feature's doc
|
|
142
|
+
chain lives) — so a thinker authors its own doc instead of forcing a
|
|
143
|
+
dispatch → blocked → orchestrator-write cycle — and `bash: deny`.
|
|
144
|
+
Every other path stays read-only.
|
|
145
|
+
- **`qa-architect`** has `permissions` deny the `shell` action (authors tests, never runs).
|
|
146
|
+
- **`handoff`** has `permissions` deny the `shell` action.
|
|
147
|
+
- **`features`** (Feature Registrar) has `permissions` deny the `shell` action — owns `BACKLOG.md` (repo root) + `.agents/features/*` **tree structure only** (scaffolding, never doc content). It does NOT author `intent`/`scope`/`plan`/`tests` and does NOT dispatch author personas — those are dispatched by the orchestrator directly.
|
|
148
|
+
- **`docs`** (Documentation Keeper) has `permissions` deny the `shell` action and `edit` allowing everything except harness/governance paths — owns `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, and `docs/**` (human-facing docs); never edits code or `.agents/**` memory.
|
|
149
|
+
- **Code personas** (`frontend-engineer`, `mobile-engineer`, `ui-designer`,
|
|
150
|
+
`data-engineer`, `devops-engineer`, `security-engineer`, `system-architect`,
|
|
151
|
+
`diagnostics-expert`) allow `edit` everywhere except governance/harness paths
|
|
152
|
+
— `opencode.json`, `.harness.json`, `.opencode/**`, `.agents/**` are denied —
|
|
153
|
+
so out-of-scope edits are blocked mechanically, not just by prose.
|
|
154
|
+
- **Model variants encode reasoning effort** (V2 ignores the V1
|
|
155
|
+
`request.body.temperature` pin this replaced). The **architect tier**
|
|
156
|
+
(`planner`, `qa-architect`, `system-architect`, `security-engineer`) pins
|
|
157
|
+
`#high` on `opencode-go/deepseek-v4-pro`; the **flash engineering/debug tier**
|
|
158
|
+
(`frontend-engineer`, `mobile-engineer`, `data-engineer`, `devops-engineer`,
|
|
159
|
+
`diagnostics-expert`) pins `#high` on `opencode-go/deepseek-v4.1-flash` — the
|
|
160
|
+
field showed those personas exhausting their step budget (`Maximum steps`) at
|
|
161
|
+
`#low`. Only the mechanical/content personas (`docs`, `features`, `handoff`,
|
|
162
|
+
`qa-runner`) keep `#low`.
|
|
163
|
+
- **`steps:`** caps iterations per persona (cost ceiling).
|
|
164
|
+
- **`planner` / `handoff`** are `hidden: true` (orchestration-only, not in the
|
|
165
|
+
`@` menu).
|
|
166
|
+
|
|
167
|
+
## Subagent output contract
|
|
168
|
+
|
|
169
|
+
Every subagent must return a single final message with, in order:
|
|
170
|
+
|
|
171
|
+
1. **Result** — what was shipped / decided.
|
|
172
|
+
2. **Evidence** — commands run or files changed with observed output.
|
|
173
|
+
3. **Deferred & risks** — what remains and follow-ups the orchestrator must handle.
|
|
174
|
+
|
|
175
|
+
## Dispatch failure ladder (never silent)
|
|
176
|
+
|
|
177
|
+
0. **Funds/quota error** — the provider funds stop above: pause, announce, wait
|
|
178
|
+
for the user's top-up-complete message. Never retry, never degrade inline,
|
|
179
|
+
never silently skip.
|
|
180
|
+
1. Retry once (resume the same `task_id`).
|
|
181
|
+
2. Degrade inline on the main model and log `degraded: <persona> model: <reason>`.
|
|
182
|
+
3. Never silently skip or re-scope — only waive via the explicit waiver path.
|
|
183
|
+
|
|
184
|
+
## Escalation ladder (evidence-based, never by default)
|
|
185
|
+
|
|
186
|
+
Cheap/default models are the normal execution tier. Escalate a persona to a
|
|
187
|
+
stronger reasoning tier only on concrete evidence, in this order:
|
|
188
|
+
|
|
189
|
+
1. **Attempt** the task on its pinned (cheap) model.
|
|
190
|
+
2. On failure, **one targeted retry** with corrected evidence/context (see
|
|
191
|
+
§Dispatch failure ladder).
|
|
192
|
+
3. On repeated failure, **escalate to the next tier** only when the blocker is
|
|
193
|
+
one of: repeated test failures after materially different fixes, contradictory
|
|
194
|
+
evidence, cross-module reasoning failure, security-sensitive ambiguity,
|
|
195
|
+
unresolved concurrency/state issues, or a genuinely-blocking workaround risk.
|
|
196
|
+
4. **Record it** — log the escalation as `escalated: <persona> -> <tier> reason: <...>`
|
|
197
|
+
in the session's dispatch log, and set the handoff's
|
|
198
|
+
`- model_escalation_evidence: <persona -> tier: reason>` metadata line (or
|
|
199
|
+
`none` when no escalation happened), so the cost is visible and auditable.
|
|
200
|
+
`npm run report -- --cost` flags a primary session observed on an
|
|
201
|
+
`escalation_models:` model with no recorded evidence.
|
|
202
|
+
|
|
203
|
+
Do NOT escalate merely because a first attempt was imperfect, the answer was
|
|
204
|
+
long, the task is technically complex, the agent asked for more context, or the
|
|
205
|
+
agent expressed uncertainty without evidence. A strong model is a scarce
|
|
206
|
+
resource, not a preference.
|
|
207
|
+
|
|
208
|
+
## Machine-read tier targets (gates + report)
|
|
209
|
+
|
|
210
|
+
Concrete model IDs here are **declared targets, not pins** — `test:dispatch`
|
|
211
|
+
accepts a model named on these lines without requiring an agent/config pin, and
|
|
212
|
+
`npm run report -- --cost` uses them to classify observed sessions by tier.
|
|
213
|
+
Everything not listed is the standard execution tier.
|
|
214
|
+
|
|
215
|
+
```
|
|
216
|
+
opportunistic_models: opencode-go/glm-5.3-flash
|
|
217
|
+
escalation_models: opencode-go/deepseek-v4-pro, deepseek/deepseek-v4-pro
|
|
218
|
+
fallback_models: deepseek/deepseek-flash
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
## Role-aware context (inject the minimum sufficient context)
|
|
222
|
+
|
|
223
|
+
A persona must consume only the context its role actually needs — never every
|
|
224
|
+
memory artifact "because it exists". The dispatch prompt carries the persona's
|
|
225
|
+
required reads plus the bounded task spec; the persona's `SKILL.md` lists its
|
|
226
|
+
own mandatory inputs. Reference map (project may override):
|
|
227
|
+
|
|
228
|
+
| Persona (class) | Required context |
|
|
229
|
+
|---|---|
|
|
230
|
+
| planner | product-principles, feature `intent.md`, flow-map, model-routing |
|
|
231
|
+
| product-manager | product-principles, feature `intent.md` |
|
|
232
|
+
| system-architect / security-engineer | stack-versions, environments, relevant flow-map |
|
|
233
|
+
| frontend-engineer / mobile-engineer / ui-designer | relevant product-principles, relevant flow-map, assigned feature context |
|
|
234
|
+
| diagnostics-expert | locations, stack-versions, relevant flow-map |
|
|
235
|
+
| devops-engineer / data-engineer | environments, stack-versions, assigned task context |
|
|
236
|
+
| qa-architect / qa-runner | flow-map, changed-surface info, QA memory |
|
|
237
|
+
| docs | only the product/feature info needed to produce the requested docs |
|
|
238
|
+
| features / handoff | BACKLOG.md + `.agents/features/*` (features); locations (handoff) |
|
|
239
|
+
|
|
240
|
+
The rule is **minimum sufficient context, not minimum possible context** — never
|
|
241
|
+
drop context that is required for correctness.
|
|
242
|
+
|
|
243
|
+
## Gates
|
|
244
|
+
|
|
245
|
+
- `npm run test:dispatch` — `scripts/qa/check-dispatch-config.js` verifies model
|
|
246
|
+
pins, persona↔skill parity, the output-contract marker, and that this doc does
|
|
247
|
+
not name a concrete model no longer pinned anywhere (doc↔config drift).
|
|
248
|
+
- `npm run test:governance` — `scripts/qa/governance.js` enforces the wrap-up
|
|
249
|
+
dispatch log.
|
|
250
|
+
- `npm run test:qa-plan` — `scripts/qa/check-qa-plan.js` enforces diff coverage:
|
|
251
|
+
every changed CODE path must have a covering assertion (or a waivered reason)
|
|
252
|
+
in `.agents/memory/qa-plan.md` before the change is verified.
|
|
253
|
+
- `scripts/qa/check-qa-scripts.js` — verifies the DoD-referenced QA tier scripts
|
|
254
|
+
(project-provided) are wired into `package.json`.
|
|
255
|
+
|
|
256
|
+
Run `test:dispatch` after editing any agent/skill path, and `test:qa-plan` on any
|
|
257
|
+
change that touches code paths.
|
|
258
|
+
|
|
259
|
+
## Gotchas
|
|
260
|
+
|
|
261
|
+
- Restart the agent CLI after editing `opencode.json` or agent files (read once at startup).
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
# Orchestration & context budget — tunable thresholds
|
|
2
|
+
|
|
3
|
+
Project-owned (like all `.agents/memory/*`). This file is the single place the
|
|
4
|
+
project tunes the cost/context guards the operating rules reference. The values
|
|
5
|
+
below are **initial experimental defaults**, not permanent truths — tune them from
|
|
6
|
+
post-change data, and record why when you do.
|
|
7
|
+
|
|
8
|
+
Read this file at session start alongside the other memory files. When a rule
|
|
9
|
+
below says "see `.agents/memory/orchestration.md`", resolve the number here.
|
|
10
|
+
|
|
11
|
+
## Orchestrator (main) context lifecycle
|
|
12
|
+
|
|
13
|
+
| Setting | Default | Meaning |
|
|
14
|
+
|---|---|---|
|
|
15
|
+
| `soft_turn_budget` | 60 | main-orchestrator turns before it must checkpoint/compact rather than keep growing |
|
|
16
|
+
| `checkpoint_warning_turn` | 50 | first context-pressure warning point (~50) |
|
|
17
|
+
| `compaction_target_turn` | 60 | prefer a checkpoint + fresh bounded context (~60) |
|
|
18
|
+
| `hard_safety_turn_limit` | 100 | hard runaway ceiling — stop and checkpoint, never kill a running tool call |
|
|
19
|
+
| `new_context_preference_turn` | 80 | strongly prefer a new bounded orchestration context (~80) |
|
|
20
|
+
|
|
21
|
+
## Request-context thresholds (observe → warn → checkpoint → intervene)
|
|
22
|
+
|
|
23
|
+
Driven by the request-token size the provider reports (input + cache read/write).
|
|
24
|
+
These now inject the same nudges as the turn bands, so context pressure is caught
|
|
25
|
+
even when the turn count is low.
|
|
26
|
+
|
|
27
|
+
| Level | Request tokens (approx) | Behavior |
|
|
28
|
+
|---|---|---|
|
|
29
|
+
| observe | 50K | record; no action |
|
|
30
|
+
| warn | 80K | warn / record context pressure |
|
|
31
|
+
| checkpoint | 120K | strong checkpoint recommendation |
|
|
32
|
+
| intervene | 160K+ | forced lifecycle intervention (checkpoint + fresh context) |
|
|
33
|
+
|
|
34
|
+
## Machine capacity envelope
|
|
35
|
+
|
|
36
|
+
WSL2 is one Linux VM: every agent, worktree, emulator, dev server, and gate
|
|
37
|
+
shares its RAM/CPU/swap with no per-agent cgroup limit. When the working set
|
|
38
|
+
exceeds the VM cap the kernel thrashes reclaim/swap and starves the host↔VM
|
|
39
|
+
vsock relay — every terminal freezes at once (2026-09-29: `memory=10GB`, 4 GB swap
|
|
40
|
+
full, load 60; 2026-09-30: the same class via an inline, uncapped Gradle APK build
|
|
41
|
+
plus the emulator + dev server). **Parallel agents are fine; parallel heavy tiers
|
|
42
|
+
are not — and a heavy one-shot build must run capped.** These numbers are the
|
|
43
|
+
machine-readable envelope that `serve.js`,
|
|
44
|
+
`test:capacity`, the `context-guard` plugin, and `agent-harness doctor` all read
|
|
45
|
+
(one owner, one set of numbers). Tune them to the host, not to hope.
|
|
46
|
+
|
|
47
|
+
| `min_available_mem_mb` | 1024 | minimum free RAM before a heavy launch is refused (raise on a busy host) |
|
|
48
|
+
| `max_swap_used_pct` | 80 | swap usage that raises a capacity warning |
|
|
49
|
+
| `max_live_serves` | 2 | `.serve/` processes before a warning (dev server + emulator ceiling) |
|
|
50
|
+
| `max_heavy_tiers` | 1 | emulator/dev-server/live-tier launches allowed at once, machine-wide; members of ONE tier group (`serve.js --group <tier>`, e.g. the `mobile` emulator + dev server) count as a single tier |
|
|
51
|
+
| `idle_reap_minutes` | 90 | age at which a running serve is flagged as an idle-reap candidate |
|
|
52
|
+
| `emulator_ram_mb` | 2048 | budget for the Android emulator (it used ~3 GB with software GPU); `boot-emulator.sh` reads this as the guest RAM default |
|
|
53
|
+
| `heavy_mem_max_mb` | 5120 | default cgroup `MemoryMax` for ONE heavy process (`serve.js start`/`run` applies it; above the observed peak so E2E is not throttled; `--mem-max` overrides). Keep ≥ `emulator_ram_mb` + ~2 GB QEMU overhead, or the emulator is OOM-killed inside its own unit |
|
|
54
|
+
| `group_mem_max_mb` | 7168 | combined cgroup budget for ONE tier group (`serve.js --group`, e.g. the `mobile` emulator + dev server). Each member's cap is generous, so `serve.js` tightens a new member to the group's remainder — two members can no longer fill the VM (the 2026-09-30 emulator + `next dev` shape). Keep ≥ `heavy_mem_max_mb` + ~2 GB |
|
|
55
|
+
| `backstop_mem_high_mb` | 8704 | soft `MemoryHigh` on `init.scope` (`wsl-tune.sh`) — the cgroup agents actually run in; 8.5 GB is above the observed non-reclaimable set (~6.9 GB) so it only reclaims cache in normal E2E, and below the ~9.5 GB freeze peak; never OOM-kills |
|
|
56
|
+
| `heavy_lock_ttl_minutes` | 240 | TTL before a crashed heavy-tier lock is considered stale |
|
|
57
|
+
|
|
58
|
+
**One-shot heavy commands.** A long-lived heavy tier (emulator/dev server/Metro)
|
|
59
|
+
holds RAM and is limited to `max_heavy_tiers`; a **one-shot** heavy command (the
|
|
60
|
+
APK/Gradle build, a heavy test tier, `maestro`) spikes RAM and releases it, so it
|
|
61
|
+
may run alongside the device tier (the live-tier test pattern) — but it MUST be
|
|
62
|
+
capped. Run it through `node scripts/serve.js run --cmd "<build>" [--mem-max 3G]`
|
|
63
|
+
(a cgroup `MemoryMax` scope) rather than inline; the APK build wrapper
|
|
64
|
+
(`scripts/qa/mobile-e2e/build-apk.sh`) does this by default. An inline
|
|
65
|
+
`./gradlew assembleRelease` with no cgroup is the 2026-09-30 freeze.
|
|
66
|
+
|
|
67
|
+
## Dispatch fan-out review
|
|
68
|
+
|
|
69
|
+
Review the planner's dispatch count against these bands (configurable):
|
|
70
|
+
|
|
71
|
+
| Fan-out | Policy |
|
|
72
|
+
|---|---|
|
|
73
|
+
| 1–4 | normal |
|
|
74
|
+
| 5–7 | planner must provide explicit decomposition justification |
|
|
75
|
+
| 8–9 | require explicit fan-out review before dispatch |
|
|
76
|
+
| 10+ | require strong evidence of independent work |
|
|
77
|
+
|
|
78
|
+
## Stuck / repeated-failure detection
|
|
79
|
+
|
|
80
|
+
Defaults for the stuck-agent and retry-loop heuristics:
|
|
81
|
+
|
|
82
|
+
| Setting | Default | Meaning |
|
|
83
|
+
|---|---|---|
|
|
84
|
+
| `same_failure_turns` | 3 | N consecutive turns with the same failure before recovery |
|
|
85
|
+
| `identical_tool_calls` | 3 | N identical tool calls (same tool+args) before it is a loop |
|
|
86
|
+
| `no_state_change_turns` | 4 | N turns with no material file/state change before stuck is declared |
|
|
87
|
+
| `no_state_grace_turns` | 8 | Startup turns (orientation) excluded from the no-state streak, so a normal read/grep prologue does not read as "stuck" |
|
|
88
|
+
| `inspect_rearm_every` | 10 | N further shell inspections before the dedicated-tools advisory re-arms |
|
|
89
|
+
| `gate_rerun_turns` | 3 | N runs of the same gate with no intervening edit before the batching advisory |
|
|
90
|
+
|
|
91
|
+
## Todo-list discipline
|
|
92
|
+
|
|
93
|
+
The opencode right-hand todo panel is driven only by the model's `todowrite`
|
|
94
|
+
calls. The guard nudges when the panel falls behind (material-call counts, so a
|
|
95
|
+
long tool loop between model steps still triggers):
|
|
96
|
+
|
|
97
|
+
| Setting | Default | Meaning |
|
|
98
|
+
|---|---|---|
|
|
99
|
+
| `use_after_calls` | 4 | N material tool calls without any todo list before "create one" |
|
|
100
|
+
| `stale_after_calls` | 3 | N material tool calls since the last `todowrite` before "sync it" |
|
|
101
|
+
|
|
102
|
+
A list with more than one `in_progress` item is flagged immediately; at the
|
|
103
|
+
checkpoint band and above, open items arm a final "close the list" nudge.
|
|
104
|
+
|
|
105
|
+
## Escalation
|
|
106
|
+
|
|
107
|
+
Escalate (per `.agents/memory/model-routing.md`) only on evidence. Record every
|
|
108
|
+
escalation structurally in the session handoff.
|
|
109
|
+
|
|
110
|
+
## Machine-read thresholds (context-guard)
|
|
111
|
+
|
|
112
|
+
`.opencode/plugins/context-guard.ts` (core: `scripts/qa/context-guard-core.js`)
|
|
113
|
+
parses this file at runtime and injects nudges into the primary orchestrator
|
|
114
|
+
session:
|
|
115
|
+
|
|
116
|
+
- **turn bands** — `checkpoint_warning_turn`, `compaction_target_turn`,
|
|
117
|
+
`new_context_preference_turn`, `hard_safety_turn_limit` (the highest value the
|
|
118
|
+
current turn has reached wins; the hard band is an injected nudge, not a
|
|
119
|
+
mechanical block — `agents.build.steps` already ends the turn);
|
|
120
|
+
- **request levels** — `observe` / `warn` / `checkpoint` / `intervene` crossings
|
|
121
|
+
from provider token data are injected too, mapped onto the same bands
|
|
122
|
+
(`warn` → warning, `checkpoint` → checkpoint, `intervene` → new-context). The
|
|
123
|
+
guard acts on whichever signal is stronger (turn count OR request context), so
|
|
124
|
+
a bloated context is caught without waiting for a turn threshold;
|
|
125
|
+
- **phase boundary, not mid-step** — at the checkpoint band the nudge is
|
|
126
|
+
imperative: write ONE checkpoint, then STOP at the current phase boundary (a
|
|
127
|
+
fresh bounded context resumes from the checkpoint). It never asks for a second
|
|
128
|
+
checkpoint in the same transcript. `agent-harness run` can chain those phases
|
|
129
|
+
automatically instead of requiring a manual `/resume`;
|
|
130
|
+
- **loops / stuck** — `identical_tool_calls` arms the recovery nudge on repeated
|
|
131
|
+
tool+args calls (the runtime's own identical-call guard also arms it);
|
|
132
|
+
`no_state_change_turns` arms it when whole turns pass with no material
|
|
133
|
+
file/state change (a checkpoint with no progress is not progress), counting
|
|
134
|
+
only past `no_state_grace_turns` so the orientation prologue never cries wolf; and
|
|
135
|
+
`same_failure_turns` arms it when the same failure signature repeats across
|
|
136
|
+
calls (same failure, different arguments).
|
|
137
|
+
- **hygiene advisories** — `inspect_rearm_every` re-arms the dedicated-tools
|
|
138
|
+
reminder (shell `cat`/`ls`/`grep`/`find`/`sed`) after N further inspections or
|
|
139
|
+
on a new shell head, since a one-shot nudge did not move the habit;
|
|
140
|
+
`gate_rerun_turns` nudges batching when the same gate is re-run with no edit in
|
|
141
|
+
between. A failed `edit`/`write`/`apply_patch` (a guessed/stale path) and a
|
|
142
|
+
hand-rolled poll (`sleep N; grep log`, `gh run watch`) each arm a one-shot
|
|
143
|
+
advisory pointing at `.agents/memory/locations.md` / `npm run wait`.
|
|
144
|
+
- **todo list** — `use_after_calls` / `stale_after_calls` drive the "create the
|
|
145
|
+
list" / "sync the list" nudges; more than one `in_progress` is flagged as
|
|
146
|
+
invalid, and at the checkpoint band an open list gets a "close it before you
|
|
147
|
+
report" nudge. The guard never writes the panel itself (the V2 plugin API has
|
|
148
|
+
no todo store) — the model's `todowrite` call is the single writer.
|
|
149
|
+
|
|
150
|
+
Two guards BLOCK a tool call instead of nudging:
|
|
151
|
+
|
|
152
|
+
- **branch-switch** — `git checkout`/`git switch` is refused while another live
|
|
153
|
+
primary session shares the checkout (the 2026-09-18 direct-push-to-main
|
|
154
|
+
incident); isolate with `backlog worktree <id>`.
|
|
155
|
+
- **main-checkout (worktree) guard** — a code change is refused while the target
|
|
156
|
+
is inside the shared `main` checkout (the F-278 stranded-work shape): an
|
|
157
|
+
`edit`/`write`/`patch`/`multiedit` to a source/test/config path, a content
|
|
158
|
+
writer (`sed -i`, `perl -i`, `patch`, `tee`, or a redirect) into the tree, or
|
|
159
|
+
a git op whose PATHS are code. A git op is judged by what it actually moves —
|
|
160
|
+
the explicit pathspecs when present (`git add <paths>`, `git commit -- <paths>`),
|
|
161
|
+
the live index for a whole-index `commit` (the `HEAD` diff for `commit -a`),
|
|
162
|
+
and the commits not yet on the upstream for a `push` — against the checkout the
|
|
163
|
+
command SELECTS, so `git -C <main>` is resolved rather than bypassed from an
|
|
164
|
+
unrelated cwd. Board / `.agents/` / docs maintenance on `main` therefore stays
|
|
165
|
+
allowed: a docs-only `git add .agents/... BACKLOG.md && git commit && git push`
|
|
166
|
+
is not a code mutation. `merge`/`rebase`/`am`/`cherry-pick`/`revert`/`reset`/
|
|
167
|
+
`clean`/`stash`, and any git op whose content cannot be resolved (git
|
|
168
|
+
unavailable, no upstream), block conservatively. It covers every session,
|
|
169
|
+
subagents included, and has no override: create the worktree first (`backlog
|
|
170
|
+
worktree <id> --open`), then work inside it.
|
|
171
|
+
|
|
172
|
+
It appends threshold/loop/no-state/failure/branch-switch/main-edit events to
|
|
173
|
+
`.agents/guard-events.jsonl` (local-only, gitignored). Keep the table row shapes
|
|
174
|
+
above; a missing row falls back to the documented default.
|
|
175
|
+
|
|
176
|
+
## Policy notes
|
|
177
|
+
|
|
178
|
+
- Never destroy cache locality to shorten a prompt: keep the stable leading
|
|
179
|
+
context (operating rules → persona → project rules) byte-stable between turns.
|
|
180
|
+
- A retry must change instructions / context / model / decomposition /
|
|
181
|
+
diagnostics. Never repeat the identical failing action.
|
|
182
|
+
- Checkpoints are compact deterministic state (`.agents/handoffs/<feature-id>.md`
|
|
183
|
+
+ this repo's doc/memory), never a full transcript dump.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Owned files per active row
|
|
2
|
+
|
|
3
|
+
Project-owned (like all `.agents/memory/*`). Maps each **in-progress** backlog row
|
|
4
|
+
to the files/globs it owns, so the cross-session collision check is precise instead
|
|
5
|
+
of coarse.
|
|
6
|
+
|
|
7
|
+
`npm run test:concurrency` reads this file: when the working tree is dirty and 2+
|
|
8
|
+
rows are In progress, it attributes each dirty file to the row(s) whose globs match
|
|
9
|
+
it — and fails *exactly* when a file is owned by two sessions (or a tree mixes two
|
|
10
|
+
sessions' WIP), instead of failing on every "2+ In progress + dirty" tree.
|
|
11
|
+
|
|
12
|
+
Keep it current: record a row's owned files the moment you pick it up
|
|
13
|
+
(`backlog owns <id> --files "glob, glob"`), and clear it when it ships
|
|
14
|
+
(`backlog owns <id> --files "?"`). A row not listed here is simply unattributed.
|
|
15
|
+
|
|
16
|
+
Format — one line per row, comma-separated globs/paths (`*` = within a segment,
|
|
17
|
+
`**` = any depth, `?` = one char):
|
|
18
|
+
|
|
19
|
+
- F-041: lib/wikidata.ts, scripts/qa/tests/wikidata-genres.test.ts
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Product principles — {{PROJECT_NAME}}
|
|
2
|
+
|
|
3
|
+
Project-owned product concepts that **lead** planning. The planner reads this
|
|
4
|
+
before emitting a dispatch plan; `product-manager` and `ui-designer` keep it
|
|
5
|
+
current. Fill it in during `npx opencode-agent-harness init`; evolve it as the
|
|
6
|
+
product does. Skills reference this instead of hardcoding product/UX assumptions.
|
|
7
|
+
|
|
8
|
+
## Actors
|
|
9
|
+
<!-- who uses the product, their goals, and emotional states -->
|
|
10
|
+
_TODO: list each actor (role), their primary goal, and what frustrates/delights them._
|
|
11
|
+
|
|
12
|
+
## Product concepts
|
|
13
|
+
<!-- the durable product ideas every feature must honor (e.g. community trust, one-tap primary actions) -->
|
|
14
|
+
_TODO: name the 2-5 concepts that define this product._
|
|
15
|
+
|
|
16
|
+
## UX heuristics
|
|
17
|
+
<!-- the standing UX rules every screen/flow follows -->
|
|
18
|
+
- **The 5 UI states** — ideal / empty (with CTA) / loading (skeleton) / error (retry) / partial.
|
|
19
|
+
- **Progressive disclosure** — high-frequency actions primary (one tap); fold secondary tiers behind menus/sheets.
|
|
20
|
+
- **Empty = default** — a new user's empty state is a primary design target, never an edge case.
|
|
21
|
+
- **Mobile ergonomics** — thumb-reachability, bottom sheets over modals, swipe actions.
|
|
22
|
+
- **RTL** — logical properties (`ps-*`/`pe-*`), direction-aware layout.
|
|
23
|
+
- **No dead-ends** — every state has a way forward (CTA, retry, dismissal).
|
|
24
|
+
|
|
25
|
+
## Design language
|
|
26
|
+
<!-- tokens & patterns (from ui-designer): color/typography/spacing, shared components -->
|
|
27
|
+
_TODO: reference the shared component / token system._
|
|
28
|
+
|
|
29
|
+
## Key journeys
|
|
30
|
+
<!-- the user-facing flows that matter most, with their happy + unhappy paths -->
|
|
31
|
+
_TODO: list the core journeys and their critical states._
|
|
32
|
+
|
|
33
|
+
## Value maximization rules
|
|
34
|
+
<!-- how planning sequences work to maximize user value first -->
|
|
35
|
+
- Ship the smallest slice that delivers the core outcome first.
|
|
36
|
+
- Order steps by user value, not by tech-dependency convenience.
|
|
37
|
+
- Prune anything that does not advance the user outcome.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Quality parameters — {{PROJECT_NAME}}
|
|
2
|
+
|
|
3
|
+
The canonical definition of "quality code" for this project — the rubric a
|
|
4
|
+
code-quality review applies and the standard the Definition-of-Done's quality
|
|
5
|
+
lens points at. Read it before authoring a review/report row; a review cites
|
|
6
|
+
these P-tags instead of re-deriving dimensions, so audits (and their follow-up
|
|
7
|
+
rows) become comparable across sessions.
|
|
8
|
+
|
|
9
|
+
The eight parameters, each with what "good" looks like and how it is measured:
|
|
10
|
+
|
|
11
|
+
| # | Parameter | What good looks like | Measured by |
|
|
12
|
+
|---|---|---|---|
|
|
13
|
+
| P1 | Dead-code-free | No export/symbol/file with zero consumers; no computed-then-discarded value; no orphaned script/route that "used to" matter | zero-consumer scan; `void x` / discarded-local detector; route-surface single-source |
|
|
14
|
+
| P2 | Dependency hygiene | Deps are used, current, and justified; no duplicate/obsolete libraries; lockfile honest | `npm audit`; dep-usage grep; package.json review |
|
|
15
|
+
| P3 | Right-sized units | Files/units small enough to read in one sitting; one responsibility each; extract beyond ~500 lines | per-file line-count lint; component/module boundaries in review |
|
|
16
|
+
| P4 | One home per fact | No copy-pasted logic — a rule/helper/schema lives once and is imported | verbatim-duplicate-block detector across sibling files |
|
|
17
|
+
| P5 | Clean layering | UI, API, business logic, data access separated; handlers thin; no provider/ORM logic inline in a route | layer-boundary review; route-handler size |
|
|
18
|
+
| P6 | Error & state contract | Every state handled (ideal/empty/loading/error/partial); user-visible errors; no silent `catch`; no 500 leaking internals | code review; runtime assertions on error paths |
|
|
19
|
+
| P7 | Type honesty | No file-level suppressions (`@ts-nocheck`, blanket `eslint-disable`); no loose `any` seams | suppression scan; type-strictness review |
|
|
20
|
+
| P8 | Consistency & i18n | One pattern per concern; RTL-safe; no hardcoded strings where `t()` applies | cross-surface audit; i18n-parity guard |
|
|
21
|
+
|
|
22
|
+
## How a review uses this
|
|
23
|
+
|
|
24
|
+
- A review's findings cite the tag: `W2.1 [P4] admin community summary duplicated
|
|
25
|
+
across 3 routes` — not a prose re-definition of "duplication".
|
|
26
|
+
- Test-quality findings (oracle independence, isolation, exit contract, tier
|
|
27
|
+
cost, wiring) cite the T1–T10 tags in
|
|
28
|
+
`.agents/memory/test-design-parameters.md` — P-tags are code quality, T-tags
|
|
29
|
+
are test quality; keep the two lenses separate.
|
|
30
|
+
- The "fix one, fix all" rule still applies: a finding names every surface that
|
|
31
|
+
carries the defect (web / mobile / scripts), per `.agents/memory/flow-map.md`.
|
|
32
|
+
- Mechanical, provable parameters (P1 zero-consumer, P3 size, P4 duplicate
|
|
33
|
+
blocks) are enforced by the `test:quality` gate on NEW/CHANGED code, so debt
|
|
34
|
+
is not *introduced*; this rubric lets review rows clear *legacy* debt.
|
|
35
|
+
|
|
36
|
+
Keep this list current when the project adopts a new quality rule worth
|
|
37
|
+
enforcing project-wide — add a parameter row, don't leave it implicit.
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# Stack versions — {{PROJECT_NAME}}
|
|
2
|
+
|
|
3
|
+
Confirmed framework / runtime versions. Verify against `package.json` and
|
|
4
|
+
`mobile/package.json` before trusting this file.
|
|
5
|
+
|
|
6
|
+
- **Web**:
|
|
7
|
+
- **Styling**:
|
|
8
|
+
- **ORM / DB**:
|
|
9
|
+
- **Mobile**:
|
|
10
|
+
- **Key native libs**:
|
|
11
|
+
|
|
12
|
+
## Web gotchas
|
|
13
|
+
|
|
14
|
+
Record framework/library gotchas that bite during builds. Seed with any that
|
|
15
|
+
apply to your stack; prune the rest.
|
|
16
|
+
|
|
17
|
+
- **Async route params (App Router)**: dynamic route params in `page.tsx` /
|
|
18
|
+
`route.ts` are Promises — always `const { id } = await params;`.
|
|
19
|
+
- **Framer Motion typing**: import the `Variants` type explicitly to avoid
|
|
20
|
+
strict-TS build failures.
|
|
21
|
+
|
|
22
|
+
## ORM / DB gotchas
|
|
23
|
+
|
|
24
|
+
- **Generator & config layout**: a recent ORM major renamed the client generator
|
|
25
|
+
and moved config out of `schema.prisma` (e.g. a `prisma.config.ts`). Confirm the
|
|
26
|
+
exact generator name and datasource location before editing the schema.
|
|
27
|
+
- Record migrate + generate commands here once confirmed.
|
|
28
|
+
|
|
29
|
+
## Mobile gotchas
|
|
30
|
+
|
|
31
|
+
- **css-interop freeze race**: on `shadow-*` / `opacity-*` / `#NN` color
|
|
32
|
+
shorthand in Expo Go — prefer inline styles for animated/opacity properties.
|
|
33
|
+
- **Expo Go vs dev build**: remote push notifications require an `eas` dev build
|
|
34
|
+
(Expo Go cannot receive them).
|
|
35
|
+
- Record any other native/runtime caveats discovered during sessions here.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Test-design parameters — {{PROJECT_NAME}}
|
|
2
|
+
|
|
3
|
+
The canonical definition of "quality tests" for this project — the companion to
|
|
4
|
+
`.agents/memory/quality-parameters.md` (P1–P8, code quality). The `qa-architect`
|
|
5
|
+
applies these before authoring; reviews cite the T-tags instead of re-deriving
|
|
6
|
+
them, so test-quality findings are comparable across sessions.
|
|
7
|
+
|
|
8
|
+
A test can be green, counted as coverage, and still prove nothing — or cost far
|
|
9
|
+
more than it is worth. These ten parameters name the ways that happens:
|
|
10
|
+
|
|
11
|
+
| # | Parameter | Anti-pattern (what to reject) | What good looks like | Measured by |
|
|
12
|
+
|---|---|---|---|---|
|
|
13
|
+
| T1 | Exit/teardown contract | A suite passes, then the process lingers on an open handle until a timeout (e.g. 22 tests finish in 76 ms, process exits 60.4 s later) | The suite terminates inside its stated wall-clock budget; pools/handles closed in `after()` or the runner force-exits | linger detector (process wall-clock vs runner-reported `duration_ms`); QA-plan `## Test budget` |
|
|
14
|
+
| T2 | Independent oracle | The assertion restates the implementation's own literal/module (`SOFT_TTL_MS === 48*60*60*1000`) — a change detector that can only fail when the test is edited too | The assertion fails for a behavioral reason independent of the implementation's own literals | review; `## Oracle & owner` names the behavior it proves |
|
|
15
|
+
| T3 | Single owner | A new test duplicates an assertion an existing gate/preflight already runs against the real tree | The contract has exactly one owner; the plan names it (`new owner` only when none exists) | `## Oracle & owner`; grep wired tiers before authoring |
|
|
16
|
+
| T4 | Real exercised surface | A mount/render-only baseline (no effects, presses, or timers) is counted as coverage of a component's behavior | The assertion drives the path from the user's perspective and states what it executes | coverage map `->` entry names the executed assertion |
|
|
17
|
+
| T5 | Executed proof | Tier chosen by path label ("components → test:quick") though no suite imports the changed helper | Exact command + executed (non-skipped) assertion count ≥ 1 exercising the changed path | coverage map + runner `tests >= 1` report |
|
|
18
|
+
| T6 | Cost economics | An expensive suite sits in the per-push tier because risk coverage was the only selection criterion | Cheapest tier that still executes it; stated runtime; a total wall-clock budget for the pre-push tier | `## Test budget`; linger detector |
|
|
19
|
+
| T7 | Wired, not orphaned | A test file is authored but referenced by no npm script — neither protection nor failure signal | The file is executed by a named tier command and load-gated (`tests >= 1`) | `npm run test:wiring` |
|
|
20
|
+
| T8 | Hermetic isolation | A unit test imports real data-access/singleton modules; a side effect fires a real DB write or network call | No real data-access/network in a hermetic test; ambient env pinned to a fast-fail dummy before module load; unavoidable side effects own their teardown | review; isolation scan of test imports |
|
|
21
|
+
| T9 | Fail-loud AND fail-fast | Prerequisite failures throw (good), but each suite still lingers ~60 s on teardown, so a red run takes minutes | Bounded prerequisite timeout; the process exits promptly; a red run returns in seconds | linger detector |
|
|
22
|
+
| T10 | Value feedback & labeling | No per-suite failure telemetry; drift-guards/constant-pins counted as behavior coverage; a guard never proven to fire | Each assertion labeled `behavior`/`drift-guard`/`constant-pin`; guards carry a negative fixture that fails when the guard is removed; cheap labels stay off the per-push path | `## Oracle & owner` + `## Test-design self-check` |
|
|
23
|
+
|
|
24
|
+
## How a review uses this
|
|
25
|
+
|
|
26
|
+
- Cite the tag with evidence: `T1 [test-design] friction.test.ts lingers 60.4 s
|
|
27
|
+
after 22 tests` — not a prose re-derivation of "slow teardown".
|
|
28
|
+
- The QA architect's 10-point checklist (`.agents/skills/qa-architect/SKILL.md`)
|
|
29
|
+
is the authoring-time form of this table; the per-change QA plan records the
|
|
30
|
+
outcome in `## Test budget`, `## Oracle & owner`, and
|
|
31
|
+
`## Test-design self-check`.
|
|
32
|
+
- Mechanical coverage of this rubric: `npm run test:wiring` (T7) and the linger
|
|
33
|
+
detector `node scripts/qa/check-linger.js -- <tier command>` (T1/T6/T9).
|
|
34
|
+
|
|
35
|
+
Keep this list current when the project adopts a new test-quality rule worth
|
|
36
|
+
enforcing project-wide — add a parameter row, don't leave it implicit.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schema": "nightly/1",
|
|
3
|
+
"worktree": null,
|
|
4
|
+
"seedCmd": null,
|
|
5
|
+
"waitForQuietMin": 30,
|
|
6
|
+
"stalePendingNights": 3,
|
|
7
|
+
"keepDays": 30,
|
|
8
|
+
"fileBacklog": true,
|
|
9
|
+
"notify": "",
|
|
10
|
+
"phases": [
|
|
11
|
+
{ "name": "static-unit", "kind": "gate", "script": "test:quick", "heavy": false, "timeoutMin": 20 },
|
|
12
|
+
{ "name": "api", "kind": "gate", "script": "test:api", "heavy": false, "timeoutMin": 30 },
|
|
13
|
+
{ "name": "routes", "kind": "gate", "script": "test:routes", "heavy": false, "timeoutMin": 20 },
|
|
14
|
+
{ "name": "web-e2e", "kind": "gate", "script": "test:e2e", "heavy": true, "timeoutMin": 30 },
|
|
15
|
+
{ "name": "device-e2e", "kind": "device-e2e", "heavy": true, "timeoutMin": 90 }
|
|
16
|
+
]
|
|
17
|
+
}
|