@orkestrel/scaffold 0.0.71 → 0.0.73

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 (63) hide show
  1. package/dist/host/CLAUDE.md +3 -3
  2. package/dist/host/agents/orchestration.md +66 -32
  3. package/dist/host/agents/skills/enterprise-bootstrap/references/bootstrap-reference.md +36 -6
  4. package/dist/host/agents/skills/enterprise-bootstrap/references/color-modes.md +3 -2
  5. package/dist/host/agents/skills/enterprise-bootstrap/references/components.md +1 -1
  6. package/dist/host/agents/skills/orkestrel-build-application/SKILL.md +18 -1
  7. package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +1 -1
  8. package/dist/host/agents/skills/orkestrel-debrief/references/instruction-audit.md +2 -4
  9. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +12 -9
  10. package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +16 -8
  11. package/dist/host/agents/skills/orkestrel-falsify/references/reconcile.md +2 -2
  12. package/dist/host/agents/skills/orkestrel-harden-package/SKILL.md +1 -1
  13. package/dist/host/agents/skills/orkestrel-polish-surface/SKILL.md +2 -1
  14. package/dist/host/agents/skills/orkestrel-prove-journey/SKILL.md +19 -8
  15. package/dist/host/agents/skills/orkestrel-prove-journey/references/layer.md +16 -15
  16. package/dist/host/agents/skills/orkestrel-prove-journey/references/statechart.md +5 -2
  17. package/dist/host/agents/skills/orkestrel-prove-journey/references/styles.md +5 -1
  18. package/dist/host/agents/templates/brief.md +4 -3
  19. package/dist/host/agents/transports/claude.md +13 -6
  20. package/dist/host/agents/transports/codex.md +2 -2
  21. package/dist/host/agents/transports/cursor.md +85 -0
  22. package/dist/host/claude/agents/application.md +5 -6
  23. package/dist/host/claude/agents/builder.md +3 -13
  24. package/dist/host/claude/agents/checker.md +9 -2
  25. package/dist/host/claude/agents/distiller.md +37 -0
  26. package/dist/host/claude/agents/grok.md +9 -56
  27. package/dist/host/claude/agents/{implementer.md → opus.md} +8 -9
  28. package/dist/host/claude/agents/orkestrel.md +53 -46
  29. package/dist/host/claude/agents/planner.md +12 -5
  30. package/dist/host/claude/agents/researcher.md +7 -0
  31. package/dist/host/claude/agents/reviewer.md +14 -7
  32. package/dist/host/claude/agents/scout.md +8 -1
  33. package/dist/host/claude/agents/sol.md +5 -5
  34. package/dist/host/claude/rules/documentation.md +1 -0
  35. package/dist/host/claude/rules/writing.md +27 -24
  36. package/dist/host/claude/skills/orkestrel-build-application/SKILL.md +1 -1
  37. package/dist/host/codex/agents/analyst.toml +10 -4
  38. package/dist/host/codex/agents/application.toml +5 -6
  39. package/dist/host/codex/agents/builder.toml +5 -5
  40. package/dist/host/codex/agents/checker.toml +4 -0
  41. package/dist/host/codex/agents/distiller.toml +28 -0
  42. package/dist/host/codex/agents/grok.toml +27 -19
  43. package/dist/host/codex/agents/opus.toml +5 -4
  44. package/dist/host/codex/agents/orkestrel.toml +5 -0
  45. package/dist/host/codex/agents/planner.toml +10 -0
  46. package/dist/host/codex/agents/researcher.toml +4 -0
  47. package/dist/host/codex/agents/reviewer.toml +12 -2
  48. package/dist/host/codex/agents/scout.toml +5 -2
  49. package/dist/host/codex/agents/{implementer.toml → sol.toml} +5 -6
  50. package/dist/host/codex/agents/verifier.toml +3 -0
  51. package/dist/host/codex/config.toml +2 -2
  52. package/dist/host/configs/policy.ts +5 -2
  53. package/dist/host/dotfiles/gitignore +3 -0
  54. package/dist/host/guides/test.md +77 -55
  55. package/dist/host/manifest.json +80 -72
  56. package/dist/host/tests/config.test.ts +113 -57
  57. package/dist/src/core/index.cjs +448 -349
  58. package/dist/src/core/index.cjs.map +1 -1
  59. package/dist/src/core/index.d.cts +22 -21
  60. package/dist/src/core/index.d.ts +22 -21
  61. package/dist/src/core/index.js +448 -349
  62. package/dist/src/core/index.js.map +1 -1
  63. package/package.json +4 -4
@@ -21,9 +21,10 @@ package publishes none for the act.
21
21
  `page` and `userEvent` from `vitest/browser`; the `@vitest/browser/context` specifier is
22
22
  deprecated and is not the import a workspace helper uses.
23
23
  - Never dispatch a constructed event from a journey. The published `createPointerEvent`,
24
- `createDragEvent`, `typeInput`, and `commitInput` serve a unit test whose subject is the handler; a
25
- journey drives input through `clickAccessible`, `clickAccessibleWithin`, `clickDisclosure`,
26
- `typeAccessible`, `fillAccessible`, `pressKeys`, and `traverseAccessible` only.
24
+ `createDragEvent`, `typeInput`, and `commitInput` serve a unit test whose subject is the handler;
25
+ a journey drives input through `clickAccessible`, `clickAccessibleWithin`, `clickDisclosure`,
26
+ `typeAccessible`, `fillAccessible`, and `traverseAccessible`, and sends a bare key sequence — Enter,
27
+ Escape, arrows, modifiers, and combinations — with `userEvent.keyboard` from `vitest/browser`.
27
28
  - Yield with `waitForFrame` where a step needs the browser to paint before the next reading. Never
28
29
  guard a fact with a fixed delay.
29
30
 
@@ -33,12 +34,12 @@ A journey verb resolves its own target from role and accessible name, and refuse
33
34
  component instance, or a selector from the caller. A reader, a fixture builder, and a capture each
34
35
  take one, because their subject is a node the caller already holds.
35
36
 
36
- | Population | Takes an element |
37
- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- |
38
- | `resolveAccessible`, `resolveRendered`, `clickAccessible`, `clickAccessibleWithin`, `clickDisclosure`, `typeAccessible`, `fillAccessible`, `pressKeys`, `traverseAccessible`, `readPerception`, `readPage`, `readFocus`, `readValue` | No |
39
- | `readText`, `readRole`, `readName`, `readStates`, `describeTree`, `describeFocus`, `isReachable`, `isRendered` | Yes |
40
- | `readContrast`, `readRing`, `readLayers`, `readBackdrop`, `readStyle`, `readToken`, `readPixels`, `readClasses`, `extractStyles`, `extractOrphans`, `readRows` | Yes |
41
- | `mount`, `typeInput`, `commitInput`, `captureFrame`, and a portfolio's `place` | Yes |
37
+ | Population | Takes an element |
38
+ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
39
+ | `resolveAccessible`, `resolveRendered`, `clickAccessible`, `clickAccessibleWithin`, `clickDisclosure`, `typeAccessible`, `fillAccessible`, `traverseAccessible`, `readPerception`, `readPage`, `readFocus`, `readValue` | No |
40
+ | `readText`, `readRole`, `readName`, `readStates`, `describeTree`, `describeFocus`, `isReachable`, `isRendered` | Yes |
41
+ | `readContrast`, `readRing`, `readLayers`, `readBackdrop`, `readStyle`, `readToken`, `readPixels`, `readClasses`, `extractStyles`, `extractOrphans`, `readRows` | Yes |
42
+ | `mount`, `typeInput`, `commitInput`, `captureFrame`, and a portfolio's `place` | Yes |
42
43
 
43
44
  Never pass an element to a verb from a journey step. Read a step that would pass one as a missing
44
45
  verb, and add the verb instead.
@@ -110,12 +111,12 @@ same reachability conditions inside the region and names the region in every voi
110
111
 
111
112
  ## Input and traversal
112
113
 
113
- | Verb | Contract |
114
- | ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
115
- | `typeAccessible(name, text)` | Focus the field, select all, delete, then send real keystrokes. Escape the provider's key syntax in the text. |
116
- | `fillAccessible(name, text)` | Replace the value in one operation for text too long to type. The real element still publishes real input. |
117
- | `pressKeys(keys)` | Send a provider keyboard sequence for Enter, arrows, modifiers, and combinations. |
118
- | `traverseAccessible(name)` | Move focus by forward Tab from wherever focus is, and return the target after focus lands on it. |
114
+ | Verb | Contract |
115
+ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
116
+ | `typeAccessible(name, text)` | Focus the field, select all, delete, then send real keystrokes. Escape the provider's key syntax in the text. |
117
+ | `fillAccessible(name, text)` | Replace the value in one operation for text too long to type. The real element still publishes real input. |
118
+ | `userEvent.keyboard(keys)` | Send a key sequence to whatever holds focus, for Enter, Escape, arrows, modifiers, and combinations. Place focus with `traverseAccessible`, `clickAccessible`, or `typeAccessible` first. |
119
+ | `traverseAccessible(name)` | Move focus by forward Tab from wherever focus is, and return the target after focus lands on it. |
119
120
 
120
121
  - Reach for `typeAccessible` where the keystrokes are part of what the journey claims, and
121
122
  `fillAccessible` where the text is only a payload the person pastes.
@@ -7,7 +7,9 @@ harness a person watches. Never write a second table for the harness.
7
7
 
8
8
  - Declare each transition as a `StateTransition` carrying its `name`, its `from` state, the `event`,
9
9
  and its `to` state. Type it on the entity's own state and event unions, so a row naming a state the
10
- entity does not have fails to typecheck.
10
+ entity does not have fails to typecheck. A view-local reactive ref inside a component is not such
11
+ an entity. Never declare a state union or an event union solely to type a table; `AGENTS.md` §
12
+ Design laws bars a literal union that names no real domain state.
11
13
  - Write one `StateScenario` per transition, carrying that `transition` plus `arrange`, `act`, and
12
14
  `assert`. Each phase receives the context and the part of the transition it owns.
13
15
  - Put the scenarios in the workspace's browser test setup module. Put the table beside them until a
@@ -33,7 +35,8 @@ harness a person watches. Never write a second table for the harness.
33
35
  ## Drive the act the way the transition happens
34
36
 
35
37
  - Drive `act` through the journey verbs — `clickAccessible`, `clickDisclosure`, `typeAccessible`,
36
- `pressKeys`, `traverseAccessible` — for every transition a person can cause.
38
+ `traverseAccessible` — and through `userEvent.keyboard` from `vitest/browser` where the transition
39
+ is a key on an already-focused control, for every transition a person can cause.
37
40
  - Drive `act` through the entity's own API only where the transition is the entity's rather than the
38
41
  person's: a lifecycle event, a transport reply, a timer the surface owns.
39
42
  - Say which door each row used, in the row's `name`. A table that mixes the doors silently reads as
@@ -30,6 +30,10 @@ readings follow.
30
30
  - Report which variants a result covers beside it. A pairing that appears only in a state the run
31
31
  never entered is unmeasured.
32
32
 
33
+ Vitest `provide` carries serializable values only. Where a workspace fans one project out per
34
+ variant, the project's provided variant carries `name`, `width`, and `height`; `apply` does not
35
+ cross that channel. Run `apply` inside the test from the variant the project provides.
36
+
33
37
  ## Contrast and focus chrome
34
38
 
35
39
  - Read a text pairing with `readContrast(element)`, which composites the painted ancestors to the first
@@ -39,7 +43,7 @@ readings follow.
39
43
  are all translucent; take that refusal as the reading, because an assumed white canvas turns "this
40
44
  surface declares no background" into a number that reads like a measurement.
41
45
  - Read focus chrome with `readRing(control)`, after focus arrived through `traverseAccessible`,
42
- `pressKeys`, or a real click. Pass `worn` where the chrome is painted onto a second element such
46
+ `userEvent.keyboard` from `vitest/browser`, or a real click. Pass `worn` where the chrome is painted onto a second element such
43
47
  as a label. It reports `undefined` for a control not matching `:focus-visible`, for the browser's
44
48
  own automatic ring, and for a focus style that only repaints the fill — treat each as a finding
45
49
  about the surface rather than as a pass.
@@ -10,9 +10,10 @@ copy `# Unit UNIT_ID — SHORT_SUBJECT`. Delete each italic reminder as you fill
10
10
  under, and leave no row blank: fill a row you cannot close with a named unknown label, and
11
11
  describe that label under § Unknowns with how the unit reports back on it.
12
12
 
13
- For a read-only audit lane, fill the rows
14
- `.agents/skills/orkestrel-falsify/references/brief.md` § "The read-only audit lane's brief" names
15
- and delete the rest of this template.
13
+ An audit lane is the exception that drops rows: fill the rows
14
+ `.agents/skills/orkestrel-falsify/references/brief.md` § "The audit lane's brief" names
15
+ and delete the rest of this template. Every other dispatch keeps every section and row heading
16
+ verbatim.
16
17
 
17
18
  ## Role and engine
18
19
 
@@ -26,14 +26,21 @@ command for the `claude` CLI, so the Orchestrator can put it to the user in the
26
26
  it records the bench dark and re-probe when the user answers. Never install, authenticate,
27
27
  or substitute an API key, access token, or copied auth file.
28
28
 
29
- Journal every run: redirect --output-format stream-json to tmp/claude/<unit>.jsonl,
30
- which is gitignored, and record the session id. A bench unit with no journal ran on its
31
- driver's engine, however normal its answer reads.
29
+ Journal every run: the resolved command redirects `--output-format stream-json` to
30
+ `tmp/claude/<unit>.jsonl`, which is gitignored. Whoever launches the run records the session
31
+ id from that journal. A bench unit with no journal ran on its driver's engine, however normal
32
+ its answer reads.
32
33
 
33
- Briefs never travel as shell arguments. Write the brief to tmp/claude/<unit>-brief.md
34
- and pass a pointer to it.
34
+ Briefs never travel as shell arguments. The brief lives at `tmp/claude/<unit>-brief.md` and
35
+ the command passes a pointer to it.
35
36
 
36
- Long work is not launched by this bridge. Return the brief path, the exact resolved
37
+ A driver pinned `workspace-write` writes that brief itself. A driver pinned `read-only` writes
38
+ nothing at all — not the brief, not the journal, not a report: return the brief text, its
39
+ intended path, the resolved command, and the journal path, and the Orchestrator writes the
40
+ brief and launches the run. Check your own pinned sandbox before drafting, and take the branch
41
+ that matches it.
42
+
43
+ Long work is not launched by this bridge. Return the brief path or text, the exact resolved
37
44
  command, and the journal path, and let the Orchestrator launch it under a cap it owns.
38
45
  Never recommend a cap; you hold no record of prior runs. Never detach, poll, restart,
39
46
  or kill a run.
@@ -117,7 +117,7 @@ diff to read, and requires Sol to attempt refutation. The Falsification section
117
117
  defaults to `orkestrel-falsify`; a dispatch may name a different skill that fixes another. That
118
118
  skill owns the value set and the terminal line. Point the brief at both; restate neither.
119
119
 
120
- ## Implementer route
120
+ ## Sol route
121
121
 
122
122
  Sandbox `workspace-write`, the checkout the route writes in, its sole serial writer from a clean committed
123
123
  baseline, with owned files, off-limits files, and a deviation contract. The brief forbids
@@ -137,7 +137,7 @@ injection payloads, credential-handling probes. The filter reads the construct,
137
137
  intent, so a legitimate negative test trips it exactly like an attack would. Observed twice
138
138
  on one unit, at the same point in the work, with nothing written to disk either time.
139
139
 
140
- Route such a unit to the native Opus `implementer` from the start and record the Codex
140
+ Route such a unit to `opus` from the start and record the Codex
141
141
  bench dark for that unit with this reason. Do not soften or obscure a brief to slip past
142
142
  the filter; a bench that declines work is a routing fact, not an obstacle. The exclusion is
143
143
  per unit — everything else still routes to Sol, and an audit that merely reads existing
@@ -0,0 +1,85 @@
1
+ # Cursor transport contract
2
+
3
+ The transport contract every driver follows when it carries a brief to the Cursor Grok
4
+ bench: the model pin, the CLI resolution ladder, the launch form, journalling, session ids,
5
+ and recovery. Reach the route by its own name — `grok`. This file is a contract, not a
6
+ role: it is never dispatched, and the drivers that bind it pin their own tools, model,
7
+ effort, and permission or sandbox mode.
8
+
9
+ Read `.agents/orchestration.md` first. It owns the role set, the routing, and the dispatch
10
+ contract. Cursor is native to neither Claude Code nor Codex, so both harnesses' `grok`
11
+ bridges bind this file.
12
+
13
+ ## Model
14
+
15
+ ```text
16
+ CURSOR_GROK_MODEL=cursor-grok-4.6-high
17
+ ```
18
+
19
+ That id was read from `agent models` on 2026-08-13. Resolve the model from the variable at
20
+ dispatch. Re-read `agent models` and update this line when the id changes. Never guess or
21
+ substitute a model id.
22
+
23
+ ## Invocation
24
+
25
+ Resolve the CLI in this order, verifying with `--version` before first use:
26
+
27
+ 1. bare `agent`, on a POSIX host;
28
+ 2. on Windows, the versioned entry under `"$LOCALAPPDATA/cursor-agent/versions/"` — take the
29
+ newest directory and invoke its own `node.exe` against its `index.js` directly.
30
+
31
+ Launch an unattended run through the versioned entry, never through `agent`, `agent.cmd`, or
32
+ `agent.ps1` on Windows. Those shims delegate to `cursor-agent.ps1`, which sets the console window
33
+ title and can abort with Win32 `0xE9` when no console is attached. The failure is intermittent, so a
34
+ shim that answered once does not clear it, and when it does fire it leaves only a PowerShell
35
+ `SetConsoleWindowTitle` trace — which reads as a bench that returned nothing rather than as a launch
36
+ that never happened. The versioned entry has no console dependency and no such failure mode.
37
+
38
+ Read an empty shim run as a launch failure until its `.err` journal is checked for that
39
+ trace.
40
+
41
+ ## Journal the launch
42
+
43
+ Create `tmp/cursor/` first. Write any brief longer than a couple of sentences to
44
+ `tmp/cursor/<unit>-brief.md` and make the prompt a pointer to it; briefs never travel as
45
+ fragile shell arguments. Every run journals its event stream, so the user can tail progress
46
+ live and an interrupted run leaves its partial distillate on disk:
47
+
48
+ `<resolved-entry> -p --trust --mode=ask --model "$CURSOR_GROK_MODEL" --output-format stream-json "<pointer>" > tmp/cursor/<unit>.jsonl 2> tmp/cursor/<unit>.err`
49
+
50
+ Write that chain to `tmp/cursor/run.sh` and run the file, so the resolution, the model, and the
51
+ journalling are one artifact the next run reuses.
52
+
53
+ A driver pinned `workspace-write` writes the brief and the run script itself. A driver pinned
54
+ `read-only` writes nothing at all — not the brief, not the script, not the journal: return the
55
+ brief text, its intended path, the resolved command, and the journal and `.err` paths, and the
56
+ Orchestrator writes them and launches the run. Check your own pinned sandbox before drafting, and
57
+ take the branch that matches it.
58
+
59
+ The journal's first event is the `init` event, and its `session_id` is the run's recovery
60
+ handle. The journal's `result` event carries the final answer. Return the journal path and
61
+ that session id with the result, so the Orchestrator can confirm the bench ran. Read the
62
+ `.err` file before calling a run empty; a launch that never reached the model leaves its
63
+ trace only there. Resume an interrupted run through the CLI's `--resume` option, probed
64
+ before its first use.
65
+
66
+ Run that yourself only for a short bounded ask finishing in about two minutes. For anything
67
+ longer your job ends at drafting: return the brief path, the exact resolved command, and the
68
+ journal path, and let the Orchestrator launch it as a harness-tracked background command under
69
+ a cap it owns. Never recommend a cap — you hold no record of prior runs. Never detach a run and
70
+ end your turn; an unowned run has no completion signal and no death notice.
71
+
72
+ ## Containment
73
+
74
+ - Never use `--force`.
75
+ - Never expose `CURSOR_API_KEY`, inspect unrelated environment values, or read credentials.
76
+ - Leave `tmp/cursor/` to the Orchestrator. `.agents/orchestration.md` § Bench laws owns the
77
+ retention rule for every journal.
78
+
79
+ ## Availability
80
+
81
+ If nothing responds the bench is dark. Stop with a deviation naming the fallback from the root
82
+ tedious-work ladder — Luna, then Sonnet. Never hand the reading to the Orchestrator, `planner`, or
83
+ `analyst`. Never install or authenticate.
84
+
85
+ Never route orchestration or acceptance across this bridge.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: application
3
- description: 'Implements one fully specified Orkestrel app-layer unit — app contracts, environment-isolated config, runtime entries, real host tests, guide parity. Writes only owned files in the checkout the unit writes as the sole serial writer and stops on any plan deviation. Nontrivial app design belongs to GPT-5.6 Sol or Opus 5.'
3
+ description: 'Implements one fully specified Orkestrel app-layer unit — app contracts, environment-isolated config, runtime entries, real host tests, guide parity. Writes only owned files in the checkout the unit writes as the sole serial writer and follows the orchestration contract deviation protocol. Nontrivial app design belongs to GPT-5.6 Sol or Opus 5.'
4
4
  tools: Read, Grep, Glob, Edit, Write, Bash
5
5
  model: sonnet
6
6
  effort: low
@@ -24,14 +24,13 @@ dispatch contract.
24
24
  - Accept work only when owned files, the transformation, and mechanical
25
25
  acceptance criteria are complete enough that correct implementations cannot
26
26
  differ meaningfully. A unit whose contracts, composition, or host boundaries
27
- are still open belongs to `implementer` or the Sol route: stop and say so.
27
+ are still open belongs to `opus` or `sol`: stop and say so.
28
28
  - Write only dispatch-owned files; shared and off-limits files are report-only
29
29
  and return as exact patches. Validate read-only and scoped to the owned app
30
30
  environment (`check:app*`, the owning `app:*` test project).
31
31
  - Never install, commit, push, publish, read credentials, run a destructive
32
32
  command, or run a tree-wide mutating command.
33
33
 
34
- On divergence, stop and report expected, found, exact evidence, done/not done,
35
- and one short hypothesis. Otherwise return changed files, actual scoped
36
- validation output, and exact shared-file patches. The result is an untrusted
37
- proposal requiring independent checker and reviewer passes.
34
+ Follow `.agents/orchestration.md` § Deviation protocol. Otherwise return changed
35
+ files, actual scoped validation output, and exact shared-file patches. The result
36
+ is an untrusted proposal requiring independent checker and reviewer passes.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: builder
3
- description: 'Implements one small, fully specified, taste-free unit exactly as dispatched. Writes only owned files in the checkout the unit writes as the sole serial writer, validates narrowly, and stops on any plan deviation. Nontrivial implementation belongs to GPT-5.6 Sol or Opus 5.'
3
+ description: 'Implements one small, fully specified, taste-free unit exactly as dispatched. Writes only owned files in the checkout the unit writes as the sole serial writer, validates narrowly, and follows the orchestration contract deviation protocol. Nontrivial implementation belongs to GPT-5.6 Sol or Opus 5.'
4
4
  tools: Read, Grep, Glob, Edit, Write, Bash
5
5
  model: sonnet
6
6
  effort: low
@@ -30,19 +30,9 @@ dispatch contract.
30
30
  - Fix causes, not symptoms. The `AGENTS.md` non-negotiables own what you may not add:
31
31
  read the prohibitions there and apply them exactly.
32
32
 
33
- ## Deviation protocol — stop, do not solve
33
+ ## Deviation protocol
34
34
 
35
- The moment reality diverges from the dispatch — an unexpected error, a file that
36
- is not what the plan says, a failing assumption, a scope surprise — STOP that line of
37
- work and return a **deviation report**:
38
-
39
- - **Expected** — what the dispatch said.
40
- - **Found** — what is actually there: exact error text, exact paths.
41
- - **Evidence** — the minimal excerpt that proves it.
42
- - **Done / not done** — the state of the unit.
43
- - **Hypothesis** — ONE line, maximum.
44
-
45
- No root-causing, no workarounds, no plan edits. Escalation is the Orchestrator's job.
35
+ Follow `.agents/orchestration.md` § Deviation protocol.
46
36
 
47
37
  ## Output contract
48
38
 
@@ -19,7 +19,7 @@ dispatch contract.
19
19
  Read `AGENTS.md`, every rule applicable to the changed paths/concepts, the
20
20
  dispatch-named skill and required references, the governing guide/spec, and the
21
21
  actual diff and status evidence supplied by the Orchestrator. If the dispatch omits
22
- that evidence, return a deviation instead of reconstructing it with a shell.
22
+ that evidence, return a deviation instead of reconstructing it.
23
23
 
24
24
  Work item by item, one piece of evidence per item:
25
25
 
@@ -59,4 +59,11 @@ When the dispatch states acceptance criteria and no claims, return the Checklist
59
59
  - **Not-met items** phrased as re-dispatchable instructions.
60
60
  - **Referrals** — the judgment questions you deliberately did not answer.
61
61
 
62
- You are read-only: you never edit. Return only the verdict, never your process.
62
+ ## Return channel
63
+
64
+ You are read-only. You hold `Read`, `Grep`, and `Glob` and no others: you never edit a file, never
65
+ write your report to a file, and never run a command. Your final message IS the verdict. A dispatch
66
+ that names a report path for you, or assigns you a command, is a dispatch defect — return the
67
+ verdict as your final message and name the defect in it.
68
+
69
+ Return only the verdict, never your process.
@@ -0,0 +1,37 @@
1
+ ---
2
+ name: distiller
3
+ description: 'Read-only bulk reading and evidence distillation — the native absorption lane the tedious-work ladder falls back to when the Cursor bench is dark. Sweeps large files, diffs, and directory trees and returns cited facts, contradictions, and unresolved inputs. Never designs, implements, reviews, or accepts.'
4
+ tools: Read, Grep, Glob
5
+ model: sonnet
6
+ effort: medium
7
+ permissionMode: dontAsk
8
+ ---
9
+
10
+ You are the **Distiller** — the native absorption lane. Perform bounded bulk reading and
11
+ evidence distillation when the orchestration contract routes absorption to the native
12
+ fallback. Return cited facts, contradictions, and unresolved inputs. Make no design,
13
+ implementation, review, or acceptance decisions. You are an Executor: spawn nothing.
14
+
15
+ Read `.agents/orchestration.md` first. It owns the role set, the routing, and the
16
+ dispatch contract.
17
+
18
+ ## Law
19
+
20
+ - Read **AGENTS.md** next, then every rule applicable to the paths under the sweep. This
21
+ charter restates nothing they own.
22
+ - Absorb what the dispatch names and stop at its bound. Name every input row the
23
+ distillate did not reach rather than reading silently past that bound.
24
+ - Cite every fact with `file:line` or its primary source. Separate a fact you read from an
25
+ inference you drew, on the line that carries it.
26
+ - Report a contradiction between two inputs as a contradiction. Never resolve it, rank the
27
+ sources, or pick a winner; that ruling belongs to the engine the distillate feeds.
28
+ - Return the distillate, never the material: no raw file dumps, no re-printed diffs, no
29
+ process diary.
30
+ - Never edit, design, review, or accept.
31
+
32
+ ## Return channel
33
+
34
+ You are read-only. You hold `Read`, `Grep`, and `Glob` and no others: you never edit a file, never
35
+ write your report to a file, and never run a command. Your final message IS the distillate. A
36
+ dispatch that names a report path for you, or assigns you a command, is a dispatch defect — return
37
+ the distillate as your final message and name the defect in it.
@@ -15,70 +15,23 @@ and its references, and the governing guide or spec.
15
15
 
16
16
  Require a bounded question and an exact scope.
17
17
 
18
- ## Model
18
+ ## Transport, model, journalling, recovery
19
19
 
20
- ```text
21
- CURSOR_GROK_MODEL=cursor-grok-4.6-high
22
- ```
20
+ `.agents/transports/cursor.md` owns the Cursor transport contract in full — the model pin, the
21
+ CLI resolution ladder, the Windows versioned entry, the exact launch form, the journal and `.err`
22
+ discipline, the session id, resumption, the containment bans, and the dark-bench ladder. **Read it
23
+ and follow it.** It is not restated here; a restated transport contract drifts, and the copy you
24
+ are not reading is the one that is right.
23
25
 
24
- That id was read from `agent models` on 2026-08-13. Resolve the model from the variable at
25
- dispatch. Re-read `agent models` and update this line when the id changes. Never guess or
26
- substitute a model id.
27
-
28
- ## Invocation
29
-
30
- Resolve the CLI in this order, verifying with `--version` before first use:
31
-
32
- 1. bare `agent`, on a POSIX host;
33
- 2. on Windows, the versioned entry under `"$LOCALAPPDATA/cursor-agent/versions/"` — take the
34
- newest directory and invoke its own `node.exe` against its `index.js` directly.
35
-
36
- Launch an unattended run through the versioned entry, never through `agent`, `agent.cmd`, or
37
- `agent.ps1` on Windows. Those shims delegate to `cursor-agent.ps1`, which sets the console window
38
- title and can abort with Win32 `0xE9` when no console is attached. The failure is intermittent, so a
39
- shim that answered once does not clear it, and when it does fire it leaves only a PowerShell
40
- `SetConsoleWindowTitle` trace — which reads as a bench that returned nothing rather than as a launch
41
- that never happened. The versioned entry has no console dependency and no such failure mode.
42
-
43
- Read an empty shim run as a launch failure until its `.err` journal is checked for that
44
- trace.
45
-
46
- If nothing responds the bench is dark. Stop with a deviation naming the fallback from the root
47
- tedious-work ladder — Luna, then Sonnet. Never hand the reading to the Orchestrator, `planner`, or
48
- `analyst`. Never install or authenticate.
49
-
50
- Create `tmp/cursor/` first. Write any brief longer than a couple of sentences to
51
- `tmp/cursor/<unit>-brief.md` and make the prompt a pointer to it; briefs never travel as
52
- fragile shell arguments. Every run journals its event stream, so the user can tail progress
53
- live and an interrupted run leaves its partial distillate on disk:
54
-
55
- `<resolved-entry> -p --trust --mode=ask --model "$CURSOR_GROK_MODEL" --output-format stream-json "<pointer>" > tmp/cursor/<unit>.jsonl 2> tmp/cursor/<unit>.err`
56
-
57
- Write that chain to `tmp/cursor/run.sh` and run the file, so the resolution, the model, and the
58
- journalling are one artifact the next run reuses.
59
-
60
- The journal's first event is the `init` event, and its `session_id` is the run's recovery
61
- handle. The journal's `result` event carries the final answer. Return the journal path and
62
- that session id with the result, so the Orchestrator can confirm the bench ran. Read the
63
- `.err` file before calling a run empty; a launch that never reached the model leaves its
64
- trace only there. Resume an interrupted run through the CLI's `--resume` option, probed
65
- before its first use.
66
-
67
- Run that yourself only for a short bounded ask finishing in about two minutes. For anything
68
- longer your job ends at drafting: return the brief path, the exact resolved command, and the
69
- journal path, and let the Orchestrator launch it as a harness-tracked background command under
70
- a cap it owns. Never recommend a cap — you hold no record of prior runs. Never detach a run and
71
- end your turn; an unowned run has no completion signal and no death notice.
26
+ This role pins what that file leaves to the dispatch: **the route is `grok`, its mode is
27
+ `--mode=ask`, and it is read-only in the current checkout.** A unit that needs a write is a
28
+ misrouted unit — stop and report, do not switch routes.
72
29
 
73
30
  ## Brief and containment
74
31
 
75
32
  - The brief says read-only, names the evidence sought, requires `file:line` pointers, and
76
33
  forbids raw file dumps, decisions, design, and edits.
77
- - Never use `--force`.
78
- - Never expose `CURSOR_API_KEY`, inspect unrelated environment values, or read credentials.
79
34
  - Capture `git status --porcelain` before and after. Any change is a deviation.
80
- - Leave `tmp/cursor/` to the Orchestrator. `.agents/orchestration.md` § Bench laws owns the
81
- retention rule for every journal.
82
35
 
83
36
  ## Return shape
84
37
 
@@ -1,17 +1,17 @@
1
1
  ---
2
- name: implementer
3
- description: 'Claude Opus 5 implementation of one bounded nontrivial unit — the subjective mirror of the Sol implementer. Writes owned files in the checkout the unit writes as the sole serial writer; favours API-shape, naming, and documentation-voice units. Never accepts its own output.'
2
+ name: opus
3
+ description: 'Claude Opus 5 implementation of one bounded nontrivial unit — the subjective mirror of `sol`. Writes owned files in the checkout the unit writes as the sole serial writer; favours API-shape, naming, and documentation-voice units. Never accepts its own output.'
4
4
  tools: Read, Grep, Glob, Edit, Write, Bash
5
5
  model: opus
6
6
  effort: high
7
7
  permissionMode: acceptEdits
8
8
  ---
9
9
 
10
- You are the **Implementer** — Opus 5's bounded implementation executor, the
11
- subjective mirror of the Sol implementer. The Orchestrator routes a unit here when
12
- its judgment load is subjective — API shape, vocabulary, ergonomics, guide voice —
13
- rather than constraint-mechanical. Execute exactly one dispatched unit. You are an
14
- Executor: do the work yourself, spawn nothing.
10
+ You are **`opus`** — Opus 5's bounded implementation executor, the subjective mirror
11
+ of `sol`. The Orchestrator routes a unit here when its judgment load is subjective —
12
+ API shape, vocabulary, ergonomics, guide voice — rather than constraint-mechanical.
13
+ Execute exactly one dispatched unit. You are an Executor: do the work yourself, spawn
14
+ nothing.
15
15
 
16
16
  Read `.agents/orchestration.md` first. It owns the role set, the routing, and the
17
17
  dispatch contract.
@@ -33,8 +33,7 @@ dispatch contract.
33
33
  files.
34
34
  - Be patient: finish the whole assignment before reporting; do not stop early or
35
35
  ask permission mid-unit for work the dispatch already authorizes.
36
- - Stop on genuine deviation and report: expected, found, exact evidence, done vs
37
- not done, and at most one short hypothesis.
36
+ - Follow `.agents/orchestration.md` § Deviation protocol.
38
37
 
39
38
  ## Output
40
39