geneseed 5.4.0 → 5.5.1

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 (191) hide show
  1. package/CHANGELOG.md +51 -0
  2. package/README.md +31 -1
  3. package/SHIPPED.md +1 -1
  4. package/adapters/bob/README.md +12 -1
  5. package/adapters/opencode/README.md +2 -1
  6. package/adapters/opencode/plugins/geneseed-context.js +71 -10
  7. package/adapters/opencode/plugins/geneseed-guard.js +101 -19
  8. package/adapters/opencode/plugins/geneseed-learn.js +641 -6
  9. package/bin/geneseed-cli.mjs +3 -0
  10. package/bin/geneseed-hook.mjs +2 -1
  11. package/docs/concepts/agents.md +13 -1
  12. package/docs/concepts/enforcement-table.md +1 -1
  13. package/docs/concepts/foreman-mode.md +22 -3
  14. package/docs/concepts/hook-gates.md +1 -1
  15. package/docs/concepts/hooks.md +22 -5
  16. package/docs/concepts/host-matrix.md +2 -2
  17. package/docs/concepts/hosts.md +1 -1
  18. package/docs/concepts/shared-tier.md +1 -1
  19. package/docs/concepts/skills.md +21 -1
  20. package/docs/concepts/themes.md +1 -1
  21. package/docs/extending.md +11 -2
  22. package/docs/guides/install-clone.md +18 -0
  23. package/docs/guides/install-scripted.md +8 -2
  24. package/docs/guides/install.md +19 -1
  25. package/docs/guides/upgrade.md +1 -1
  26. package/docs/reference/env-context.md +1 -1
  27. package/docs/reference/environment.md +1 -1
  28. package/docs/reference/plugin-learn.md +4 -0
  29. package/docs/reference/profiles.md +226 -0
  30. package/docs/token-footprint.md +9 -4
  31. package/docs/understand/design-choices-engineering.md +1 -1
  32. package/docs/web-ui.md +3 -1
  33. package/harness.config.json +1 -1
  34. package/js/README.md +9 -2
  35. package/js/build/args.mjs +4 -3
  36. package/js/build/catalog.mjs +11 -1
  37. package/js/build/driver.mjs +42 -11
  38. package/js/build/emit-claude.mjs +24 -1
  39. package/js/build/emit-opencode.mjs +3 -0
  40. package/js/build/export.mjs +12 -17
  41. package/js/build/generate.mjs +2 -1
  42. package/js/build/notes-migrate.mjs +99 -0
  43. package/js/build/profile.mjs +14 -6
  44. package/js/build/render.mjs +34 -10
  45. package/js/build/source.mjs +85 -2
  46. package/js/cli-table.json +164 -4
  47. package/js/hosts/agent-runs.mjs +205 -0
  48. package/js/hosts/done-checks.mjs +3 -1
  49. package/js/hosts/hooks-done.mjs +91 -16
  50. package/js/hosts/hooks-learn.mjs +85 -0
  51. package/js/hosts/hooks-prims.mjs +39 -1
  52. package/js/hosts/hooks.mjs +10 -4
  53. package/js/hosts/hosts.mjs +10 -0
  54. package/js/hosts/installs.mjs +25 -1
  55. package/js/hosts/link.mjs +45 -10
  56. package/js/hosts/native.mjs +42 -5
  57. package/js/hosts/opencode.mjs +1 -1
  58. package/js/hosts/settings.mjs +72 -0
  59. package/js/hosts/spec-feedback.mjs +538 -0
  60. package/js/hosts/usage.mjs +67 -8
  61. package/js/inspect/agent-scores.mjs +118 -0
  62. package/js/inspect/checks-authoring.mjs +2 -1
  63. package/js/inspect/checks-build.mjs +20 -4
  64. package/js/inspect/checks-repo.mjs +27 -2
  65. package/js/inspect/cost.mjs +6 -5
  66. package/js/inspect/diff.mjs +25 -5
  67. package/js/inspect/doctor.mjs +4 -0
  68. package/js/inspect/status.mjs +3 -1
  69. package/js/inspect/validate.mjs +1 -0
  70. package/js/lib/machine-dir.mjs +8 -0
  71. package/js/lib/paths.mjs +4 -1
  72. package/js/maintain/profile-scope.mjs +145 -0
  73. package/js/maintain/profiles.mjs +486 -0
  74. package/js/maintain/setup.mjs +409 -15
  75. package/js/maintain/uninstall.mjs +4 -1
  76. package/js/maintain/update.mjs +1 -1
  77. package/js/web/actions.mjs +28 -38
  78. package/js/web/api.mjs +7 -2
  79. package/js/web/handler.mjs +8 -0
  80. package/js/web/jobs.mjs +5 -4
  81. package/js/web/profiles-api.mjs +201 -0
  82. package/js/web/routes.mjs +5 -0
  83. package/package.json +2 -1
  84. package/profiles/autonomous.json +14 -0
  85. package/profiles/corporate.json +14 -0
  86. package/profiles/guillaume-claude-global.json +16 -0
  87. package/profiles/mentor.json +13 -0
  88. package/profiles/minimal.json +15 -0
  89. package/profiles/starter.json +14 -0
  90. package/src/AGENT.md.tmpl +1 -1
  91. package/src/agents/_self-improvement.md +15 -7
  92. package/src/agents/_template.md +4 -2
  93. package/src/agents/advocate.md +1 -1
  94. package/src/agents/architect.md +1 -1
  95. package/src/agents/developer.md +10 -3
  96. package/src/agents/devops-engineer.md +7 -6
  97. package/src/agents/docker-expert.md +1 -1
  98. package/src/agents/docs.md +1 -1
  99. package/src/agents/empiricist.md +1 -1
  100. package/src/agents/explorer.md +4 -2
  101. package/src/agents/framer.md +1 -1
  102. package/src/agents/historian.md +1 -1
  103. package/src/agents/kubernetes-specialist.md +4 -2
  104. package/src/agents/memory-curator.md +1 -1
  105. package/src/agents/operator.md +1 -1
  106. package/src/agents/performance.md +1 -1
  107. package/src/agents/pragmatist.md +1 -1
  108. package/src/agents/react-engineer.md +1 -1
  109. package/src/agents/react-reviewer.md +1 -1
  110. package/src/agents/researcher.md +1 -1
  111. package/src/agents/reviewer.md +10 -3
  112. package/src/agents/security.md +1 -1
  113. package/src/agents/skeptic.md +1 -1
  114. package/src/agents/spring-boot-engineer.md +4 -4
  115. package/src/agents/spring-reviewer.md +5 -3
  116. package/src/agents/spring-security.md +1 -1
  117. package/src/agents/steward.md +1 -1
  118. package/src/agents/tester.md +4 -2
  119. package/src/agents/user-advocate.md +1 -1
  120. package/src/agents/visionary.md +1 -1
  121. package/src/memory/README.md +12 -2
  122. package/src/modes/foreman.md +23 -10
  123. package/src/skill-descriptions.json +63 -0
  124. package/src/skills/_self-improvement.md +42 -26
  125. package/src/skills/_template.md +3 -1
  126. package/src/skills/brainstorm.md +35 -22
  127. package/src/skills/codebase-design.md +2 -2
  128. package/src/skills/daydream/VENDOR.md +6 -0
  129. package/src/skills/diagram-design/SKILL.md +12 -7
  130. package/src/skills/diagram-design/VENDOR.md +23 -14
  131. package/src/skills/diagram-design/references/layout-budget.md +7 -1
  132. package/src/skills/diagram-design/references/onboarding.md +1 -1
  133. package/src/skills/diagram-design/references/primitives-core.md +1 -1
  134. package/src/skills/diagram-design/references/semantic-patterns.md +1 -1
  135. package/src/skills/diagram-design/references/style-guide.md +1 -1
  136. package/src/skills/diagram-design/references/type-dependency.md +69 -0
  137. package/src/skills/diagram-design/references/type-event-modeling.md +36 -0
  138. package/src/skills/diagram-design/references/type-requirement-traceability.md +45 -0
  139. package/src/skills/diagram-design/references/type-sbgn.md +80 -0
  140. package/src/skills/diagram-design/references/type-scatter.md +1 -1
  141. package/src/skills/diagram-design/references/type-steps.md +180 -0
  142. package/src/skills/diagram-design/references/type-unit-grid.md +63 -0
  143. package/src/skills/explain-changes/VENDOR.md +5 -1
  144. package/src/skills/geneseed-code-review.md +2 -1
  145. package/src/skills/parallel-agents.md +12 -1
  146. package/src/skills/pipeline.md +3 -3
  147. package/src/skills/plan.md +5 -4
  148. package/src/skills/react-view-transitions/AGENTS.md +26 -26
  149. package/src/skills/react-view-transitions/SKILL.md +1 -1
  150. package/src/skills/react-view-transitions/VENDOR.md +19 -4
  151. package/src/skills/release.md +7 -2
  152. package/src/skills/rule/approve.md +2 -1
  153. package/src/skills/skill-forge.md +5 -3
  154. package/src/skills/spring-boot/cloud.md +19 -1
  155. package/src/skills/spring-boot/logging.md +5 -3
  156. package/src/skills/spring-boot/web.md +27 -2
  157. package/src/skills/spring-boot.md +4 -2
  158. package/src/skills/spring-data-jpa.md +18 -4
  159. package/src/skills/spring-testing.md +4 -0
  160. package/src/skills/token-report/VENDOR.md +5 -1
  161. package/src/upstreams.json +6 -6
  162. package/themes/README.md +3 -1
  163. package/web/dist/assets/{ActiveLoops-BJJN3P-V.js → ActiveLoops-DOJCPPPc.js} +1 -1
  164. package/web/dist/assets/{Activity-D2kOc3yi.js → Activity-bUSPM3Dl.js} +1 -1
  165. package/web/dist/assets/{ActivityDetail-By3xOr21.js → ActivityDetail-AHRoXeFN.js} +1 -1
  166. package/web/dist/assets/{Bonsai-CBWDTBA4.js → Bonsai-B5XY9pid.js} +1 -1
  167. package/web/dist/assets/{CopyButton-BVbpriMB.js → CopyButton-C0wwRR9H.js} +1 -1
  168. package/web/dist/assets/{Dashboard-CIJLPHM9.js → Dashboard-DPAA96EI.js} +2 -2
  169. package/web/dist/assets/{Docs-CiRRIELs.js → Docs-CpGDq165.js} +1 -1
  170. package/web/dist/assets/{Factories-DhyK0O8d.js → Factories-cNhETa5Q.js} +1 -1
  171. package/web/dist/assets/{GreenhouseView-DW3PgTPy.js → GreenhouseView-DO3ADmT9.js} +1 -1
  172. package/web/dist/assets/Installs-D3dDyq10.js +3 -0
  173. package/web/dist/assets/{JournalView-O65qEWfp.js → JournalView--W-Lw_V9.js} +1 -1
  174. package/web/dist/assets/{Kits-C5U-yT6Z.js → Kits-ChfehxY6.js} +1 -1
  175. package/web/dist/assets/Laws-CNxYmV36.js +4 -0
  176. package/web/dist/assets/{LibRows-D6-CVa3K.js → LibRows-CiPvsRYB.js} +1 -1
  177. package/web/dist/assets/{Library-CzPlerd6.js → Library-BxQvbwVU.js} +1 -1
  178. package/web/dist/assets/{Loops-CqNF_-nS.js → Loops-DAblKkyq.js} +1 -1
  179. package/web/dist/assets/{OperatorHudView-BNr8K5qj.js → OperatorHudView-QtSaSyYm.js} +1 -1
  180. package/web/dist/assets/{Personal-DeDb9e8O.js → Personal-DxSGv638.js} +1 -1
  181. package/web/dist/assets/{Settings-B8MPN_AD.js → Settings-CgTbhvRv.js} +1 -1
  182. package/web/dist/assets/{Tabs-DJzAez4h.js → Tabs-Cf4X1hdz.js} +1 -1
  183. package/web/dist/assets/api-CZ-x0iWG.js +1 -0
  184. package/web/dist/assets/{controls-D4wmg_pl.js → controls-CK7qHA8H.js} +1 -1
  185. package/web/dist/assets/{index-BL3P-9Rg.js → index-B_pTwZra.js} +4 -4
  186. package/web/dist/assets/index-CzfImiYb.css +1 -0
  187. package/web/dist/index.html +3 -3
  188. package/web/dist/assets/Installs-B6nlo-Ly.js +0 -3
  189. package/web/dist/assets/Laws-CuTw_XNf.js +0 -4
  190. package/web/dist/assets/api-DLDVY3K-.js +0 -1
  191. package/web/dist/assets/index-CRWqKxfY.css +0 -1
@@ -150,6 +150,9 @@ const VERBS = {
150
150
  // (upstream Python, pinned in the module's docblock). There is no recorded cell — its absolute gate is
151
151
  // tests/unit/scorecard.test.mjs. Lazy like every row: the 31 checks load only when asked.
152
152
  scorecard: () => import('../js/inspect/scorecard.mjs').then((m) => m.cmdScorecard),
153
+ // Native: writes an install profile from a global install (`setup --profile` installs one).
154
+ // Its absolute gate is tests/unit/profiles.test.mjs.
155
+ profile: () => import('../js/maintain/profiles.mjs').then((m) => m.cmdProfile),
153
156
  };
154
157
 
155
158
  /** Levenshtein distance, for the one "did you mean" an unknown verb gets. */
@@ -348,7 +348,8 @@ async function main(argv) {
348
348
  }
349
349
  let rc;
350
350
  try {
351
- rc = (await spec.load())[spec.fn](parsed.args);
351
+ // Awaited: `activity` is async (its slash counter imports on demand); the rest return a number.
352
+ rc = await (await spec.load())[spec.fn](parsed.args);
352
353
  } catch (e) {
353
354
  return verbFailed(verb, parsed.args, e);
354
355
  }
@@ -40,7 +40,19 @@ In [foreman mode](foreman-mode.md) the session hands each task that would block
40
40
 
41
41
  ### Agents learn too
42
42
 
43
- When a subagent finishes, the learn step can record a lesson for that agent alone, in `agents/<name>.md` in the memory store (the [shared](shared-tier.md) one on a global install) — one bullet per lesson, capped so it never grows unbounded. The next time that agent runs, it starts with what it learned. See [Memory](memory.md). (Not on Bob, which has no subagent-finished event.)
43
+ When a subagent finishes, the hook copies each `spec-feedback:` line its report ends with into a notes file, with no model call. The line picks its scope with one question: is it true in any repo, or only here? A flaw of the spec is true in any repo: `[agent]` goes into the machine notes, `agent-notes/<name>.md` under `~/.config/geneseed/notes/` (a `[general]` line into `agent-notes/_general.md` there, which every agent reads). A fact true only in this repo is tagged `[agent:project]` and goes into `notebook/agent-notes/<name>.md` at the project root, one folder for every host (in a linked worktree, the main checkout's); a `[general:project]` line goes into `notebook/agent-notes/_general.md`, which every agent reads in that repo. The agent reads the machine notes and then the project notes first at its next dispatch; where they disagree, the project notes win. So a flaw it reported is in front of it until the user folds the fix into the source. See [Hooks](hooks.md). (Not on Bob, which has no subagent-finished event: there the caller copies the line into the machine or the project file.)
44
+
45
+ ### Did a spec change help?
46
+
47
+ When a named subagent finishes, the same hook appends one line to `notebook/agent-runs.jsonl` in the install, beside `usage.jsonl`. The line holds only facts the hook can read: the day, the agent, a short hash of its rendered spec (`agents/<name>.md`, or none for an agent Geneseed does not ship), whether the done gate let the turn end and how many times it blocked it first, the number of tool calls and of refused calls (a call a host or a gate did not run; a red test is not one), the number of `spec-feedback:` lines, and whether a report came back. There is no self-score and no model call. A stop that the done gate blocks writes no line: the line comes at the stop that ends the turn.
48
+
49
+ `geneseed catalog agents --scores` prints one row per agent and spec hash, so the runs before a spec edit and the runs after it are two rows to compare. The UNBLOCKED column is `never blocked / judged`, over the runs the gate judged. It is not a pass rate: the gate cannot tell a pass from an advisory, and a stop past the gate's block limit also ends the turn. REFUSED and TOOLS are means, with the number of runs behind each in brackets; below 3 runs they show `-`.
50
+
51
+ The hash is of the rendered file, so anything that renders the spec differently starts a new row, even with no change to the agent's source: a theme switch, the first seeding of the shared tier, a Geneseed upgrade that changes the renderer, or an agent override. A spec you edited by hand in the install is no longer the file Geneseed shipped, so its runs read `spec: null`.
52
+
53
+ The counts are per turn, as the done gate reads one. A message sent to a running subagent (SendMessage) opens a new turn, so the line written at that turn's end counts only the tools used after the message. On OpenCode the line is written at a child session's first quiet period in each OpenCode process, and it counts the whole child session on OpenCode 1. The same switch as `usage.jsonl` turns the ledger off: `GENESEED_NO_USAGE`, or a `.usage-off` file in the install. On OpenCode the learn plugin writes the line for a named child session, with no done-gate fields, because that host's gate is in another plugin. Bob has no subagent-finished event, so it writes no line.
54
+
55
+ The learn step can also record a lesson for that agent alone, in `agents/<name>.md` in the memory store (the [shared](shared-tier.md) one on a global install) — one bullet per lesson, capped so it never grows unbounded. The next time that agent runs, it starts with what it learned. See [Memory](memory.md). (Not on Bob, which has no subagent-finished event.)
44
56
 
45
57
  <!--harness:opencode-->
46
58
  *(OpenCode only)*
@@ -26,7 +26,7 @@ silently guarding the wrong rule after a renumber. See [ADR 0005](../adr/0005-st
26
26
  | `persist-insight` | process | ask: rule-gate (a write to `user-rules.md` or `user-rules.draft.md`; memory is written freely, and the [change report](hooks.md#the-change-report) and the web console show it). Togglable: build without the process pack, or drop this rule alone with `--exclude-rules`: the hook goes on every host (`--no-rule-store`), OpenCode's `permission.edit` keys on the rule files too. The change report still lists rule-file changes | same as Claude Code | ask: OpenCode's own prompt (`permission.edit`, and `evaluate` on OpenCode 2); the guard plugin refuses a file-tool write the host cannot prompt for | block a file-tool write: exit 2, no ask tier; a parsed shell write only warns |
27
27
  | `consent-before-push` | process | ask: git-gate, on a commit or push onto the main branch (`main`, `master`, a remote's default branch, or the branch the main checkout holds when the command runs in a linked worktree). Off the main branch, a session's commit, local merge and plain push of the checked-out branch (`git push [-u] <remote> <branch>`, or `HEAD:<branch>`) pass. A bare `git push`, a push of another branch, a forced push, a tag push, or any form the gate cannot read still asks, and so does everything in a repository with no remote or whose remote has no default branch recorded (`git remote set-head origin --auto`). A sub-agent's push always asks. With `--strict-consent` (the *Strict consent* switch on the console's Constitution page), every commit and push asks again, as before 2026-11. A sub-agent's commit or merge (`agent_id` in the payload) in a linked worktree, on a branch that is not shared, passes: a Foreman worker's own batch ([Foreman mode](foreman-mode.md) has the exact conditions). A git hook or `core.hooksPath` that pushes on commit is not seen. A push, or a command that mixes one in, still asks. Togglable: build without the process pack, or drop this rule alone with `--exclude-rules` (see [Exclusions](exclusions.md)). Only this question drops; the `deletion-is-deliberate` gate stays. | same as Claude Code | ask: permission prompt (`git commit*`/`git push*`), wired only when the process pack is on; a `loop/*` push is statically allowed. A glob sees only the command, never the worktree, so a worker's commit still asks | log only |
28
28
  | `external-gate` | rigor | ask: rule-gate (a write under a project's `.geneseed/protected-checks.txt` list, or to a gate's own configuration: hook settings, `excludes.json`, `AGENT.md` gate markers, the hook shim) | same as Claude Code | ask: OpenCode's own `permission.edit` rules, written by the emit (every `opencode.json(c)`, the hook settings, the install's `AGENT.md`, `excludes.json`, manifest, plugins, the hook shim); block: guard plugin (the protected-checks list, and the other hosts' Geneseed-only files) | block (exit 2), writes only; a hook `settings.json` only when the edit changes Geneseed's own hook entries |
29
- | `verify-before-asserting` | law | block at Stop, again only after a new edit or a changed background verdict, at most 3 times per continuation and 10 per turn: the done gate in `learn`, at SubagentStop too for a sub-agent's own turn (a turn that edited files, while a check in the project's `.geneseed/done-checks.txt` has not passed since the last edit). Without that file, the checks are inferred from the git root's manifests and only warn (a `systemMessage` at Stop, never a block); switchable per install with `--no-done-gate` (see [Exclusions](exclusions.md)) | same as Claude Code (a frozen fork, and no check runs a model turn: [What is verified](host-matrix.md#what-is-verified)); that its SubagentStop sends `agent_transcript_path` is unverified, and without it a sub-agent's turn is not judged | remind: context plugin, on the next request (OpenCode 1 only; OpenCode 2 is not judged, and logs so) | not judged: Stop carries no transcript (log line) |
29
+ | `verify-before-asserting` | law | block at Stop, again only after a new edit or a changed background verdict, at most 3 times per continuation and 10 per turn: the done gate in `learn`, at SubagentStop too for a sub-agent's own turn (a turn that edited files, while a check in the project's `.geneseed/done-checks.txt` has not passed since the last edit; a check matches as a prefix of the command once both drop `npm --prefix`/`git -C` naming the judged project's own root and `--test-concurrency N`). Without that file, the checks are inferred from the git root's manifests and only warn (a `systemMessage` at Stop, never a block); switchable per install with `--no-done-gate` (see [Exclusions](exclusions.md)) | same as Claude Code (a frozen fork, and no check runs a model turn: [What is verified](host-matrix.md#what-is-verified)); that its SubagentStop sends `agent_transcript_path` is unverified, and without it a sub-agent's turn is not judged | remind: context plugin, on the next request (OpenCode 1 only; OpenCode 2 is not judged, and logs so) | not judged: Stop carries no transcript (log line) |
30
30
  | `commands-must-return` | ops | ask: git-gate (a recursive scan rooted at a filesystem root: `find /`, `du`, `grep -r`, `rg`, `Get-ChildItem -Recurse` at `/`, `/c`, `C:\`). Togglable: build without the ops pack, or drop this rule alone with `--exclude-rules`: the check goes on every host (`--no-root-scan`) | same as Claude Code | block: guard plugin (same root-scan pattern) | block (exit 2) |
31
31
 
32
32
  Bob has no "ask" tier (see [ADR 0007](../adr/0007-gates-fail-closed-per-host-ceiling.md)), so a
@@ -26,6 +26,14 @@ The session sorts every request:
26
26
 
27
27
  When the session is unsure, it delegates. The test is still a count, because "substantial" left to judgement lost every time to the host's own default of doing small work in place. The count asks what would block the session, not how big the task looks.
28
28
 
29
+ ### No dispatch tool, no foreman
30
+
31
+ Foreman needs a tool that can start a writing (`developer`) worker: `Agent` on Claude Code and OpenClaude, `subagent` (V1: `task`) on OpenCode, `spawn_subagent` on Bob. When the session holds no such tool, it works as in direct mode: it does each task itself, one at a time, in one tree, and tells you so once.
32
+
33
+ The check is on the tool the session holds, not on the host, because the same install can run with and without that tool. Bob IDE and Bob Shell (the terminal CLI) read the same `~/.bob` install, so a build cannot tell them apart. Bob IDE 2.2.3 gives `spawn_subagent` only when the `session.subagents` setting is on (the default) and only to a mode whose groups hold `subagent`: the built-in `agent` and `plan` modes can start every subagent. The `ask` mode holds `spawn_subagent` too, but it may start only `explore`, so it cannot start a worker and Foreman runs as direct there. Bob Shell has no subagents, no worktrees and no parallel dispatch; this is reported by Bob Shell itself, not read in code, because IBM does not publish Bob Shell on npm.
34
+
35
+ Bob's `start_subtask` (the `subtask` group, held by the `agent` mode) does not count as a Foreman dispatch tool: it appears to make the parent wait until the subtask ends, which blocks the session. That is inferred from the bundle, not observed live.
36
+
29
37
  ### The task worker
30
38
 
31
39
  A task worker is one `developer` agent in its own git worktree. It explores, implements and tests in a single context, loading skills as it needs them, so nothing it read is lost in a hand-off. After two repair rounds on its own failing tests it returns with its findings instead of looping.
@@ -37,13 +45,24 @@ A worker can lead a small team inside its own worktree. It can start read-only h
37
45
  | Claude Code | the install writes `env.CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH = "2"` into its settings file, only when the key is absent (Claude Code allows three levels by default) |
38
46
  | OpenCode | the install writes a top-level `"subagent_depth": 2` into `opencode.json`, only when the key is absent |
39
47
  | OpenClaude | nothing in the host: its source has no such cap (checked on 0.31). The rule text is the only bound |
40
- | Bob | nothing documented. The rule text is the only bound |
48
+ | Bob | Bob itself: a subagent cannot spawn another (`spawn_subagent` is forbidden to subagents, read in Bob IDE 2.2.3), so one level only, session → worker, and no sub-workers. A Bob worker does the work itself. Bob Shell has no subagents at all (reported by Bob Shell itself, not read in code) |
41
49
 
42
- A value you set yourself is kept. The value 2 is read as session → worker → sub-worker; that reading is the design's, not yet observed live on either host.
50
+ A value you set yourself is kept. On Claude Code and OpenCode, the value 2 is read as session → worker → sub-worker; that reading is the design's, not yet observed live on either host.
43
51
 
44
52
  When a worker returns green with a diff that touches two or more files or changes logic, the session sends a `reviewer` only your request and the diff — never the worker's reasoning — for a blind check. A failing verdict goes back to the same worker.
45
53
 
46
- The session keeps a ledger in its notebook (`notebook/foreman-ledger.md`), one line per task: the task, the agent id, the worktree and the state. A correction, a follow-up or a reviewer finding goes back to **the same worker**, which resumes with everything it already knows. A new worker starts only when the old one cannot be resumed, and it receives a note of the ask, the diff so far and what was tried. A worker serves one task and retires once that task is merged or dropped.
54
+ The session keeps a ledger in its notebook (`notebook/foreman-ledger.md`), one line per task: the task, the agent id, the worktree and the state. A correction, a follow-up or a reviewer finding goes back to **the same worker**, which resumes with everything it already knows. Each host resumes a worker its own way:
55
+
56
+ | Host | How the session resumes a worker |
57
+ | --- | --- |
58
+ | Claude Code | `SendMessage` with the worker's id or name |
59
+ | OpenCode | the `subagent` tool with the worker's `sessionID` (V1: the `task` tool with `task_id`); the TUI shows `↳` on such a call. The same call without `sessionID` (V1: `task_id`) starts a fresh worker |
60
+ | OpenClaude | `SendMessage`, only in its agent-teams mode (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` or `--agent-teams`); otherwise no resume |
61
+ | Bob | no resume: each `spawn_subagent` call starts a fresh subagent |
62
+
63
+ A new worker starts only when the old one cannot be resumed, and it receives a note of the ask, the diff so far and what was tried.
64
+
65
+ A new task gets a new worker by default. The session may give it to an idle worker whose own task is already merged or dropped, when the new task works in the same files or context and that worker has used little of its context. The worker then starts the new task on a new branch from the current BASE. It gets the full brief that any new worker gets (BASE, write set, proof commands, the Brief checklist), and the session checks its write set against every task in flight. Whether a context is light or heavy is a judgement call, not a number: the session writes its reason (same files, context used) in the new task's ledger line. A worker never holds two live tasks at once. A worker whose context is heavy, or whose last task touched other code, retires.
47
66
 
48
67
  ### Status lines
49
68
 
@@ -16,7 +16,7 @@ If a gate cannot evaluate a call — an unreadable payload, a bug — it asks, w
16
16
  geneseed status
17
17
  ```
18
18
 
19
- In an [excluded folder](exclusions.md), every hook of a global install exits silently. And a global install's `context`, `git-gate` and `learn` hooks stand down when the session's project folder (the one the session started in, not a parent of it) has its own live per-repo install of the same host that wires the same hook, so nothing is injected, asked or learned twice. A per-repo install that is deactivated, or whose hooks were never wired, does not count: the global hook keeps running. `GENESEED_STACK_GLOBAL=1` keeps both.
19
+ In an [excluded folder](exclusions.md), every hook of a global install exits silently. And a global install's `context`, `git-gate` and `learn` hooks stand down when the session's project folder (the one the session started in, not a parent of it) has its own live per-repo install of the same host that wires the same hook, so nothing is injected, asked or learned twice. The usage count of `tool-gate` and `activity` stands down in the same case, so a call is counted once ([What the usage count records](hooks.md#what-the-usage-count-records)); those two hooks still do the rest of their work. A per-repo install that is deactivated, or whose hooks were never wired, does not count: the global hook keeps running. `GENESEED_STACK_GLOBAL=1` keeps both.
20
20
 
21
21
  ## Where they are written
22
22
 
@@ -20,13 +20,26 @@ Geneseed writes its hooks into the host's settings file. Every hook calls one pr
20
20
  | `PreToolUse` | `Bash`, `PowerShell`, `Monitor` | `geneseed-hook git-gate` | asks before a command that would really lose data, and before a recursive scan of a whole filesystem; asks before every commit and push | the commit/push question only |
21
21
  | `PreToolUse` | `Write`, `Edit`, `NotebookEdit` | `geneseed-hook rule-gate` | asks before a secret lands in a file, or a write to your standing rules; stops the session's first write once in an application repo with no `## Ownership` section | no |
22
22
  | `PreToolUse` | `Skill`, `Agent`, `Task` | `geneseed-hook tool-gate` | records the skill or subagent call in the usage count; judges nothing and never blocks | no |
23
- | `Stop` | the agent finishes a reply | `geneseed-hook learn` | distils durable facts into the memory store | needs `GENESEED_LLM` |
24
- | `SubagentStop` | a subagent finishes | `geneseed-hook learn` | records a lesson for that agent in the store's `agents/<name>.md` | needs `GENESEED_LLM` |
23
+ | `Stop` | the agent finishes a reply | `geneseed-hook learn` | copies the reply's `spec-feedback: [skill:<name>]` lines into `skill-notes/<name>.md` (no model); distils durable facts into the memory store | the copy needs nothing; the distil needs `GENESEED_LLM` |
24
+ | `SubagentStop` | a subagent finishes | `geneseed-hook learn` | copies the `spec-feedback:` lines of its report into `agent-notes/<name>.md` (no model); appends one outcome line to `notebook/agent-runs.jsonl` (see [Agents](agents.md#did-a-spec-change-help)); records a lesson for that agent in the store's `agents/<name>.md` | the copy and the outcome line need nothing (the line is off with `GENESEED_NO_USAGE` or `.usage-off`); the lesson needs `GENESEED_LLM` |
25
25
  | `PreCompact` | before auto-compaction | `geneseed-hook learn` | captures memory before the transcript is summarised | needs `GENESEED_LLM` |
26
- | `UserPromptSubmit` | you send a message | `geneseed-hook activity` | records the turn's start for the web console's Activity view; prints nothing | off with `GENESEED_ACTIVITY=off` |
26
+ | `UserPromptSubmit` | you send a message | `geneseed-hook activity` | records the turn's start for the web console's Activity view; when the message is `/<name>` and `<name>` is an installed skill, records it in the usage count as `via: "slash"`; prints nothing | the Activity record is off with `GENESEED_ACTIVITY=off`; the count is off with `GENESEED_NO_USAGE` or `.usage-off` |
27
27
  | `SessionEnd` | the session closes | `geneseed-hook activity` | marks the session ended and archives it | off with `GENESEED_ACTIVITY=off` |
28
28
  | `SubagentStart` | a subagent starts | `geneseed-hook context` | injects your `user-rules.md` layers into the subagent (as JSON `additionalContext`, under the same 9 000-character budget), and records the subagent as a branch of its session | the Activity record only, with `GENESEED_ACTIVITY=off` |
29
29
 
30
+ ### What the usage count records
31
+
32
+ The web console's "What fires" chart reads `notebook/usage.jsonl` in every install it finds, and adds the counts together. Each line holds the day, `skill` or `agent`, and the name. A line for a typed skill also holds `"via":"slash"`. A line never holds the prompt or the arguments.
33
+
34
+ - **A skill call and a subagent call.** The `Skill|Agent|Task` hook records one line per call.
35
+ - **A skill that you type as `/<name>`.** A typed skill makes no `Skill` tool call, so the `UserPromptSubmit` hook records it, with `"via":"slash"`. It counts only when `<name>/SKILL.md` exists in the install's `skills/` folder, in the global config folder's `skills/` (`~/.claude/skills/`), or in the project's own `.claude/skills/`. A built-in command such as `/clear` or `/model` is not counted. A plugin skill typed as `/<plugin>:<skill>` is not counted either, because its folder is in the host's plugin cache.
36
+ - **A session in an excluded folder.** It is not counted. In a folder that `geneseed exclude` lists, every hook of that install stays quiet, the counter included. So a repo that was excluded for a time shows fewer calls than its transcripts hold.
37
+ - **A global install beside a project install of the same host.** When the session's project folder holds a live, wired project install, both hooks run. Only the project install counts the call, and the global one stands down, so the console does not count the call twice. `GENESEED_STACK_GLOBAL` makes both count.
38
+
39
+ On OpenCode the guard plugin counts the same calls. A project install writes to `<repo>/notebook/usage.jsonl`. OpenCode loads the global plugins and every project `.opencode/plugins/` from the session's folder up to its worktree. Only one copy counts a call: the copy of the nearest project that can count (it has a `notebook/` and no `.usage-off`). If no project can count, the global copy counts. A `/<name>` command counts on OpenCode 1 (`command.execute.before`), but not on OpenCode 2, which gives the plugin the expanded command text and no name.
40
+
41
+ On Bob two parts are not verified on a live Bob session. The typed-skill count reads the payload's `prompt` field as on Claude Code. The global install finds the project folder from the payload's `cwd`, because Bob sets no project variable. If Bob's `cwd` follows a `cd` into another repo that has a Bob project install, which Bob never loaded, the global install stands down and that call is not counted.
42
+
30
43
  Every hook above also feeds the [Activity view](../reference/plugin-activity.md) after it has decided, unless tracking is off: one file per session under `activity/` beside the install. The gates' verdicts never wait on it.
31
44
 
32
45
  What that file holds for the Activity garden:
@@ -76,7 +89,7 @@ On Bob, a subagent's files cannot be told apart from its session's files (its ho
76
89
  - An edit that weakens a test gets a note to the agent, citing *Cure the Cause*. It is **advisory**: it asks nothing and blocks nothing. An install built `--no-test-note` gets no note, here or at turn end ([Exclusions](exclusions.md)). A test file has a path segment `test`, `tests`, `__tests__` or `spec`, or a name `*.test.*`, `*.spec.*`, `*_test.*` or `test_*`. The edit weakens it when it adds `.skip(`, `xit(`, `xfail`, `@Disabled`, `@Ignore`, `pytest.mark.skip` or `t.Skip(`, or when it removes an assertion line and adds no other. The done gate repeats it to you when the turn ends. On Bob the note is a line in the hook log. On OpenCode it is one reminder on the next request.
77
90
  - Ordinary edits pass untouched.
78
91
 
79
- **The done gate.** Runs when a turn ends, inside `learn` and before it calls any model. You do not have to set it up: with no list, the gate infers the checks from the manifests at the project's git root — the `test`, `lint` and `typecheck` scripts of `package.json` (run with the package manager its lockfile names; npm's default "no test specified" script is skipped), `mvn test` for `pom.xml`, `gradle test` for `build.gradle(.kts)`, `pytest` for `pyproject.toml` when the project shows pytest (a `[tool.pytest` section, `pytest.ini`, `conftest.py` or a `tests/` folder), `cargo test` for `Cargo.toml`, `go test` for `go.mod`. Subprojects of a monorepo are not inferred. Each inferred check accepts its usual spellings: `npm test`, `npm run test` and `npm t` all count, and so do `./mvnw clean verify` or `.\gradlew build` — but not with a flag that skips the tests (`-DskipTests`, `-Dmaven.test.skip`, `-x test`, `cargo test --no-run`). Spellings it does not know (`npm run test:unit`, `npx vitest`, `CI=1 npm test`, `./gradlew :app:test`) read as not run. Inferred checks are **advisory**, and they stay advisory, with no date: only a list the project wrote can block. A turn that ends without them still ends, and you see a warning naming them (a `systemMessage`), plus a `done-gate-advisory` line in the gate ledger. To make the gate block, or to choose the checks yourself, list them in `.geneseed/done-checks.txt` at the git root: one command per line, `#` for comments, for example `npm run lint` and `node --test --test-reporter=tap "tests/**/*.test.mjs"`. A listed line matches as a prefix of the command: `node --test` listed would accept `node --test tests/one.test.mjs`, one file of the suite, so list each command whole. That file replaces the inference; a file that lists nothing turns the gate off for the project. With a listed file, if the turn edited a file under that root and a listed check has not passed since the last edit, the turn does not end: the agent is told which checks are owed, citing *Verify Before Asserting*. Every session starts with one line naming the checks and their source, for example `Done gate: inferred from package.json — npm test, npm run lint (advisory)`. On Bob, which never judges a turn, the line ends `(not judged on this host)` instead. A check counts when it ran as a shell command, unpiped (`npm test | tail` exits with `tail`'s code, so it proves nothing), with nothing after it that masks its exit code (`|| true`, `; true`, `; exit 0` all exit 0 on a red suite, so any `||` after the check, or a `;` or newline followed by `true`, `:`, `exit 0` or a bare `exit`, reads as "not run"), and its result was not an error. A check that runs in the background (Claude Code's `run_in_background`, or a command moved there after its foreground timeout) counts only when its task notification says it completed with exit code 0; the launch alone says only that it started. The gate never runs a check itself. It reads the transcript from its end, back only to the last prompt a person typed: a background task's notification opens no turn, so a turn spans every continuation the notifications drive. Its cost grows with that turn, not with the session; in a long run kept going by notifications it may read back to the start of the file. A sub-agent's turn is judged too, when it stops (SubagentStop): the gate reads the sub-agent's own transcript and judges each project it wrote files in by that project's git root and list, so a worker in its own worktree owes its worktree's checks, not its parent's. A block there keeps the sub-agent working, with the owed checks as its next instruction. An inferred check there is only a stderr line and a ledger entry, since nobody sees a sub-agent's warning. It blocks again only when the agent edited a file since the last block, or when a check's background run changed its verdict (still running, then failed), and at most 3 times per continuation: a stop with neither, or a fourth stop, ends the turn and leaves a `done-gate-cap` line in the gate ledger. A task notification starts a new continuation with a fresh count, so early blocks do not spend the cap for the rest of an unattended run. Over the whole turn, until the next prompt a person types, it blocks at most 10 times: a suite relaunched in the background after each failure would otherwise loop, one full run per cycle. Past that ceiling the turn ends, and the stderr line says the total ceiling was reached. The block names the checks whose background run is still running or reported a failure. The count is kept per session (and per sub-agent) in the install's `notebook/done-gate/`; without an install, the second stop ends the turn. Only file-write tools count as edits: a shell `sed -i` or redirect is not one here. When a turn weakened a test (see the rule gate), the gate adds a line that the agent cannot suppress, `[done-gate] advisory — test weakened this turn: tests/a.test.js (.skip added)`. The line needs no checks and stays out of the ask counts. `--no-done-gate` silences this line and OpenCode's reminder, but not the note the agent gets at edit time on Claude Code, OpenClaude and Bob: the rule gate never receives that flag. A block prints only the block; the line comes at the stop that ends the turn. On OpenCode the gate is a reminder on the next request (OpenCode 1 only), listed or inferred; on Bob, whose Stop carries no transcript, the turn is not judged, and with a listed file a log line says so. An install built `--no-done-gate` wires `learn` with that flag: the check is skipped, learning still runs ([Exclusions](exclusions.md)).
92
+ **The done gate.** Runs when a turn ends, inside `learn` and before it calls any model. You do not have to set it up: with no list, the gate infers the checks from the manifests at the project's git root — the `test`, `lint` and `typecheck` scripts of `package.json` (run with the package manager its lockfile names; npm's default "no test specified" script is skipped), `mvn test` for `pom.xml`, `gradle test` for `build.gradle(.kts)`, `pytest` for `pyproject.toml` when the project shows pytest (a `[tool.pytest` section, `pytest.ini`, `conftest.py` or a `tests/` folder), `cargo test` for `Cargo.toml`, `go test` for `go.mod`. Subprojects of a monorepo are not inferred. Each inferred check accepts its usual spellings: `npm test`, `npm run test` and `npm t` all count, and so do `./mvnw clean verify` or `.\gradlew build` — but not with a flag that skips the tests (`-DskipTests`, `-Dmaven.test.skip`, `-x test`, `cargo test --no-run`). Spellings it does not know (`npm run test:unit`, `npx vitest`, `CI=1 npm test`, `./gradlew :app:test`) read as not run. Inferred checks are **advisory**, and they stay advisory, with no date: only a list the project wrote can block. A turn that ends without them still ends, and you see a warning naming them (a `systemMessage`), plus a `done-gate-advisory` line in the gate ledger. To make the gate block, or to choose the checks yourself, list them in `.geneseed/done-checks.txt` at the git root: one command per line, `#` for comments, for example `npm run lint` and `node --test --test-reporter=tap "tests/**/*.test.mjs"`. A listed line matches as a prefix of the command: `node --test` listed would accept `node --test tests/one.test.mjs`, one file of the suite, so list each command whole. Before the match, the gate removes three things from both the line and the command, and nothing else: `--prefix <dir>` (or `--prefix=<dir>`) on `npm`, and `-C <dir>` right after `git`, when `<dir>` is the judged project's own root (the worktree whose files were edited); and `--test-concurrency N` on `node --test`. So a worker's `npm --prefix <its worktree> run lint` proves `npm run lint`, and a suite run at the default concurrency proves a line that names `--test-concurrency=8`. A `--prefix` that names another project, a sibling worktree, the main checkout or a subfolder still reads as not run (that run never saw this tree's edits). A changed glob or reporter still does not match. The gate does not follow `cd`: it reads the command line only. That file replaces the inference; a file that lists nothing turns the gate off for the project. With a listed file, if the turn edited a file under that root and a listed check has not passed since the last edit, the turn does not end: the agent is told which checks are owed, citing *Verify Before Asserting*. Every session starts with one line naming the checks and their source, for example `Done gate: inferred from package.json — npm test, npm run lint (advisory)`. On Bob, which never judges a turn, the line ends `(not judged on this host)` instead. A check counts when it ran as a shell command, unpiped (`npm test | tail` exits with `tail`'s code, so it proves nothing), with nothing after it that masks its exit code (`|| true`, `; true`, `; exit 0` all exit 0 on a red suite, so any `||` after the check, or a `;` or newline followed by `true`, `:`, `exit 0` or a bare `exit`, reads as "not run"), and its result was not an error. A check that runs in the background (Claude Code's `run_in_background`, or a command moved there after its foreground timeout) counts only when its task notification says it completed with exit code 0; the launch alone says only that it started. The gate never runs a check itself. It reads the transcript from its end, back only to the last prompt a person typed: a background task's notification opens no turn, so a turn spans every continuation the notifications drive. Its cost grows with that turn, not with the session; in a long run kept going by notifications it may read back to the start of the file. A sub-agent's turn is judged too, when it stops (SubagentStop): the gate reads the sub-agent's own transcript and judges each project it wrote files in by that project's git root and list, so a worker in its own worktree owes its worktree's checks, not its parent's. A block there keeps the sub-agent working, with the owed checks as its next instruction. An inferred check there is only a stderr line and a ledger entry, since nobody sees a sub-agent's warning. It blocks again only when the agent edited a file since the last block, or when a check's background run changed its verdict (still running, then failed), and at most 3 times per continuation: a stop with neither, or a fourth stop, ends the turn and leaves a `done-gate-cap` line in the gate ledger. A task notification starts a new continuation with a fresh count, so early blocks do not spend the cap for the rest of an unattended run. Over the whole turn, until the next prompt a person types, it blocks at most 10 times: a suite relaunched in the background after each failure would otherwise loop, one full run per cycle. Past that ceiling the turn ends, and the stderr line says the total ceiling was reached. The block names the checks whose background run is still running or reported a failure. The count is kept per session (and per sub-agent) in the install's `notebook/done-gate/`; without an install, the second stop ends the turn. Only file-write tools count as edits: a shell `sed -i` or redirect is not one here. When a turn weakened a test (see the rule gate), the gate adds a line that the agent cannot suppress, `[done-gate] advisory — test weakened this turn: tests/a.test.js (.skip added)`. The line needs no checks and stays out of the ask counts. `--no-done-gate` silences this line and OpenCode's reminder, but not the note the agent gets at edit time on Claude Code, OpenClaude and Bob: the rule gate never receives that flag. A block prints only the block; the line comes at the stop that ends the turn. On OpenCode the gate is a reminder on the next request (OpenCode 1 only), listed or inferred; on Bob, whose Stop carries no transcript, the turn is not judged, and with a listed file a log line says so. An install built `--no-done-gate` wires `learn` with that flag: the check is skipped, learning still runs ([Exclusions](exclusions.md)).
80
93
 
81
94
  **learn.** Takes the tail of the transcript and asks a model to distil what is worth keeping into one-fact-per-file entries in the memory store: on a global install, the shared one when it exists. It is shown the facts already stored, so it updates one with the merged text rather than writing a twin (the old version is kept in `memory/archive/`), and moves one the session proved obsolete into `memory/archive/`. It needs `GENESEED_LLM` set to a model command, for example:
82
95
 
@@ -84,7 +97,11 @@ On Bob, a subagent's files cannot be told apart from its session's files (its ho
84
97
  export GENESEED_LLM="claude -p"
85
98
  ```
86
99
 
87
- Unset, `learn` does nothing useful: on a real Stop/SubagentStop/PreCompact call it returns immediately rather than reading the transcript for nothing, and on a manual run it prints the prompt it would have sent. Geneseed never stores or embeds an API key. See [Memory](memory.md).
100
+ Unset, `learn` distils nothing: on a real Stop/SubagentStop/PreCompact call it returns before it reads the transcript for a distil, and on a manual run it prints the prompt it would have sent. Geneseed never stores or embeds an API key. See [Memory](memory.md).
101
+
102
+ One part of `learn` needs no model. On SubagentStop it reads the subagent's final report (its last message, or the message of its hand-back call) and copies each `spec-feedback:` line into the notes that agent reads at its next dispatch. Each line names its scope. A machine line (`[agent]`, `[general]`, a skill's `[skill:<name>]` or `[skill:<name>:general]`) goes to the tier's `notes/`, for every host and install kind: `agent-notes/<name>.md`, or `agent-notes/_general.md` for a `general` line, which every agent reads. The tier's folder exists on any machine an emit has run on (the install registry lives there); only `notes/<sub>/` is made under it, and with no such folder a machine line is dropped. A project line (`[agent:project]`, `[skill:<name>:project]`) goes to `<project>/notebook/`: the install's parent for a project install, the git root of the session's project for a global one, a linked worktree's main checkout either way. A global session outside any repo has no project, so its project line is dropped, never sent to the machine notes. A `[general:project]` line goes to that folder's `agent-notes/_general.md`, which every agent reads in this repo. Geneseed writes no ignore file into the project: the notes folders and the migration's archives are named in the clone's own `.git/info/exclude`, once, in a marked block, so they never reach a commit, even in a repo whose `notebook/` is tracked. Outside a git repo nothing extra is written. Each note is one bullet that names its writer and its date, `- [agent] <fix> (<agent>, <date>)`, appended under a short file lock so parallel subagents do not lose each other's lines; a line already there is not added again, and the template placeholder, a quoted (`>`) or fenced line and a line holding a credential are skipped. The line is kept at every stop, one the done gate blocks included: the report that draws the block carries it, and the one that passes need not repeat it. Every dispatch reads these files, so they are capped: an agent's file at 100 bullets, `_general.md` at 30, each file at 8 000 characters. Past a cap the oldest bullets the hook wrote drop, told apart by the writer's name beside the date; a line written by hand is never moved or dropped, a dated one included. The OpenCode learn plugin does the same for a child session that names its agent. Bob has no subagent-finished event, so there the caller copies the line.
103
+
104
+ Skills close the same loop. A skill runs in the main conversation, so no SubagentStop sees it: on Stop, `learn` reads the reply that ends the turn (the host's `last_assistant_message`, and the transcript's final message only when that copy mentions `spec-feedback`) and copies each `spec-feedback: [skill:<name>]` line into `skill-notes/<name>.md`, a `[skill:<name>:general]` line into `skill-notes/_general.md`, which every skill reads (both machine notes), or a `[skill:<name>:project]` line into the project's `notebook/skill-notes/<name>.md` (a `[skill:<name>:general:project]` line into its `_general.md`). The same lines in a subagent's report go there too, on SubagentStop. The tag must name the skill: the main reply often relays a subagent's `[agent]` or `[general]` line, and those are not copied on Stop. A line counts only for a skill the install serves under that name: `<install>/skills/<name>/SKILL.md` names its own notes file (the render writes each skill's id into it), so an invented name, an alias folder an older build left, or a skill rendered before this writes no file. A tag that does not parse (`[skill:a:b]`, `[skill:a, b]`) drops the line, and a line in inline code or a fence is an example the reply quotes, not a note. The bullets, caps, lock and duplicate rule are the agents' (`- [skill] … (<skill>, <date>)`); the `- [skill] … (<date>)` lines written by hand before the hook are never dropped. A Stop the done gate blocks copies its reply's lines too, since the reply that finally ends the turn does not repeat them. An excluded folder copies nothing, as it learns nothing. Bob's Stop payload carries neither a transcript nor the reply, so there the skill text tells the model to append the line itself.
88
105
 
89
106
  ## What a prompt says
90
107
 
@@ -22,7 +22,7 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
22
22
  | Standing-rule write needs your call | 🔒 ask³ | 🪝 ask | 🪝 block¹ | 🪝 ask² |
23
23
  | User-only skills hidden from the model | 🔒 `permission.skill` deny | ✅ `disable-model-invocation` | ✅ `/`-command, no skill | ✅ `disable-model-invocation` |
24
24
  | Sovereign-repo exclusions⁵ | ⚙️ plugins stand down | ✅ `claudeMdExcludes` | ✅ rules shadow stub | ✅ `claudeMdExcludes` |
25
- | Subagent depth capped at two ([Foreman mode](foreman-mode.md)) | ✅ `subagent_depth` | ✅ `env` setting | ➖ undocumented | ➖ no cap in the host |
25
+ | Subagent depth capped at two ([Foreman mode](foreman-mode.md)) | ✅ `subagent_depth` | ✅ `env` setting | ✅ one level, set by Bob itself: a subagent cannot spawn another | ➖ no cap in the host |
26
26
  | MCP servers (Geneseed reads and lists them, never writes them) | ✅ `mcp` | ✅ `mcpServers` | ✅ `mcp.json` | ✅ `mcpServers` |
27
27
  | Colour themes · LSP · workflow runner · primary agent · `/`-commands | ✅ | ➖ | ➖ | ➖ |
28
28
 
@@ -43,7 +43,7 @@ This is the one place that says what was checked against each host itself, how,
43
43
  | Claude Code | canary: `tests/host_canary.mjs` installs the host from npm and starts it in a throwaway home | weekly in CI, at npm `latest` | `claude doctor` lists no invalid setting in the emitted `settings.json`; a logged-out `-p` run shows `SessionStart` running the context hook | hooks that need a model turn: the `PreToolUse` gates, `Stop` |
44
44
  | OpenClaude | canary, the same run | weekly in CI, at npm `latest` | the emitted settings load; `SessionStart` runs the context hook. Its `doctor` checks only the auto-updater, so there is no settings verdict to read | hooks that need a model turn |
45
45
  | OpenClaude | source read | 2026-09 | the config directory, the root files it loads, the settings and hook types (`src/utils/envUtils.ts`, `claudemd.ts`, `config.ts`, `src/types/hooks.ts`) | |
46
- | Bob | bundle read: Bob 2.2.3's shipped `bob-code/dist/extension.js` | 2026-10 | the hook payload (Claude's keys plus `cwd`), the event list, the strict settings schema, the agent frontmatter reader | whether Bob lists agents to the model; a sub-agent depth cap |
46
+ | Bob | bundle read: Bob 2.2.3's shipped `bob-code/dist/extension.js` | 2026-10 | the hook payload (Claude's keys plus `cwd`), the event list, the strict settings schema, the agent frontmatter reader; the sub-agent depth (one level: `SUBAGENT_FORBIDDEN_TOOLS` denies subagents `spawn_subagent` and `start_subtask`) | whether Bob lists agents to the model |
47
47
  | Bob | live session, Bob IDE | 2026-10-23 | a `tool-gate` refusal (exit 2) stopped the call and its reason reached the model; Bob ignores Claude's `disallowedTools`, which is why a read-only agent carries `groups:`; the first-reply override | the `Stop` hook; the ownership gate's sub-agent deferral |
48
48
  | Bob | live session | 2026-10-25 | a prompt wrote an Activity snapshot from `UserPromptSubmit` | |
49
49
  | Bob | canary | never | nothing: IBM does not publish Bob Shell on npm, so the canary reports Bob as `skip` | everything above is a one-time read, not a standing check. [Verify it works](../guides/verify.md) has the by-hand steps |
@@ -18,7 +18,7 @@ Each host has a **global** install (in its config directory, active in every rep
18
18
 
19
19
  ## Two engines
20
20
 
21
- - **OpenCode** runs its own engine: Geneseed installs JavaScript **plugins** that OpenCode loads, plus permission entries in `opencode.json`. The install also caps subagent nesting at two levels there (`subagent_depth`), as it does on Claude Code (`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`); OpenClaude and Bob have no such cap ([Foreman mode](foreman-mode.md)). It also gets OpenCode-only extras: colour themes, [language servers](lsp.md), a workflow runner, a primary agent and `/`-commands.
21
+ - **OpenCode** runs its own engine: Geneseed installs JavaScript **plugins** that OpenCode loads, plus permission entries in `opencode.json`. The install also caps subagent nesting at two levels there (`subagent_depth`), as it does on Claude Code (`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`); OpenClaude has no such cap, and Bob needs none, because a Bob subagent cannot start another ([Foreman mode](foreman-mode.md)). It also gets OpenCode-only extras: colour themes, [language servers](lsp.md), a workflow runner, a primary agent and `/`-commands.
22
22
  - **Claude Code**, **Bob** and **OpenClaude** share one Claude-shaped engine: Geneseed wires **hooks** into the host's `settings.json`, each calling `geneseed-hook <verb>`. See [Hooks](hooks.md).
23
23
 
24
24
  ## Where to go next
@@ -19,7 +19,7 @@ A global install keeps what you teach it in one place for every host on the mach
19
19
  | `geneseed-wiki.jsonc` | Your [wiki](../guides/wiki.md) declaration |
20
20
  | `excludes.json` | [Sovereign folders](exclusions.md) |
21
21
  | `memory/` | The [memory](memory.md) store: facts, `MEMORY.md`, `topics/`, `agents/`, `archive/` |
22
- | `notes/` | The self-improvement notes: `skill-notes/`, `agent-notes/` |
22
+ | `notes/` | The self-improvement notes true in any repo: `skill-notes/`, `agent-notes/`. Every install writes them here, project installs included, and a project install's files name this folder as `~/.config/geneseed/notes`, the same on every machine. The notes true in one repo only live in that repo's `notebook/` |
23
23
  | `user-rules.draft.md` | What waits for your decision. Never loaded |
24
24
  | `.fold-state.json` | The record of each drafted or decided item |
25
25
  | `default-install.json` | The console's default install, once you pick one |
@@ -42,7 +42,7 @@ The full list, with each description, is in the catalog.
42
42
 
43
43
  ### Skills improve themselves
44
44
 
45
- Every skill ends with one beat of reflection: if a step misled or a step was missing, the agent writes the exact correction, with no prompt, into that skill's notes file, `notebook/skill-notes/<name>.md` (`notes/skill-notes/<name>.md` in the [shared tier](shared-tier.md) on a global install), and reads those notes the next time the skill runs. It never edits the installed skill itself: that file is rendered from `src/`, and a rebuild would overwrite the edit. A bundled script that is broken is the one exception: fix it in place, and tell the user which file you changed. Agents work the same way through `agent-notes/`. Each note is one line that carries its evidence, `- [skill|general] <correction> [— situation: <when it applies>] — seen: <what happened, against what was expected> (<date>)`: `situation:` says where the correction holds (it is optional, and older lines without it stay valid; without it, the circumstance in `seen:` stands in), `seen:` is what you judge the correction by before folding it in, and `general` marks one that belongs in a law, doctrine or memory rather than in that one skill. `geneseed diff` lists the notes so you can fold them back into `src/`. Folding a skill or agent note is your call: the `skill-forge` skill first replays one past task whose original ask still exists, as two dispatched agents from the pre-fix revision, one told to read no notes and one given the note. The `fresh-eyes` skill freezes one rubric from the ask and judges both results blind against it. A note is folded only when it wins, on the result or on a stated process gain; on a tie or a loss you decide whether to keep or delete it. A trivial wording fix skips that probe. Most runs end with nothing to change.
45
+ Every skill ends with one beat of reflection: if a step misled or a step was missing, the agent ends its reply with one line, `spec-feedback: [skill:<name>] <the fix> [— situation: <when it applies>] — seen: <what happened, against what was expected>`. When the turn ends, the hook copies that line, dated and with no model call, into the skill's notes file, and the skill reads those notes the next time it runs (see [Hooks](hooks.md)). The tag picks the file by one question: is it true in any repo, or only here? Any repo: `[skill:<name>]` goes into the machine notes, `skill-notes/<name>.md` under `notes/` in the [shared tier](shared-tier.md) (`~/.config/geneseed/notes/`), for every host and install kind. Only here: `[skill:<name>:project]` goes into `notebook/skill-notes/<name>.md` at the project root, one folder for every host, and `[skill:<name>:general:project]` into `notebook/skill-notes/_general.md` there. The skill reads the machine notes first, then the project notes, which win where they disagree. The agent used to be told to write the file itself, and it never did. It never edits the installed skill itself: that file is rendered from `src/`, and a rebuild would overwrite the edit. A bundled script that is broken is the one exception: fix it in place, and tell the user which file you changed. Agents work the same way through `agent-notes/`. Each note is one line that carries its evidence, `- [skill] <correction> [— situation: <when it applies>] — seen: <what happened, against what was expected> (<skill>, <date>)` (a line you write by hand may omit the skill's name, and the hook never drops it): `situation:` says where the correction holds (it is optional, and older lines without it stay valid; without it, the circumstance in `seen:` stands in), and `seen:` is what you judge the correction by before folding it in. A line tagged `[skill:<name>:general]` marks a fix other skills need too: it goes into `skill-notes/_general.md`, which every skill reads. On Bob, whose hook never sees the reply, the agent appends the line itself. `geneseed diff` lists the notes so you can fold them back into `src/`. Folding a skill or agent note is your call: the `skill-forge` skill first replays one past task whose original ask still exists, as two dispatched agents from the pre-fix revision, one told to read no notes and one given the note. The `fresh-eyes` skill freezes one rubric from the ask and judges both results blind against it. A note is folded only when it wins, on the result or on a stated process gain; on a tie or a loss you decide whether to keep or delete it. A trivial wording fix skips that probe. Most runs end with nothing to change.
46
46
 
47
47
  ### Old names keep working
48
48
 
@@ -52,6 +52,26 @@ When two skills merge, the old name still works as a slash command: `/deps-audit
52
52
 
53
53
  The skill *bodies* are read only when used. The *descriptions* are listed to the agent every turn so it can pick the right one — that list is part of the always-on cost described in [Footprint](footprint.md).
54
54
 
55
+ ### The listing budget on Claude Code
56
+
57
+ Claude Code builds the skill list under a character budget: the model's context window, times about 3 characters per token, times `skillListingBudgetFraction` (default 0.01). That is about 6 000 characters on a 200k-token model and 30 000 on a 1M one. Its bundled skills always keep their text. When the list is over budget, the other skills that are used least lose their description and show as a bare name, and the agent no longer knows when to use them. A fresh install on a 200k model lost all of them.
58
+
59
+ `geneseed build --context-window 200k|1m` (default `200k`) tells the build which model the install is for. On a Claude Code emit it writes two keys into the settings file Geneseed already merges (`settings.json`, or `settings.local.json` for a project):
60
+
61
+ | `--context-window` | `skillListingMaxDescChars` | `skillListingBudgetFraction` | Budget at 3 characters per token |
62
+ | --- | --- | --- | --- |
63
+ | `200k` | 80 | 0.013 | 7 800 |
64
+ | `1m` | 120 | not set (default 0.01) | 30 000 |
65
+
66
+ `skillListingMaxDescChars` cuts *every* skill's description to that length, Claude Code's own and other plugins' included, so each one costs less. Simulated on a fresh install (the 14 bundled skills and 46 Geneseed skills, no usage yet):
67
+
68
+ - `200k`: at the default fraction, every description fits with 395 characters to spare, and 113 with one kit. Five skills of your own would push some out. At 0.013, all of them fit with twenty more skills. The fraction is a ceiling, not a cost: a list that fits uses only its own length.
69
+ - `1m`: a fresh install fits even without a cap. The cap is for a machine with many skills: a 143-skill list of 47 617 characters fits whole in 19 427.
70
+
71
+ The keys are merged one by one. A key you set yourself is yours: the build never changes it, and uninstall never removes it. A key the build wrote moves with the setting (from `200k` to `1m` the cap goes to 120 and the fraction is removed), and uninstall removes it. A settings file with comments is never rewritten: the build prints the keys to merge by hand, and a key you merge that way is yours, so the build does not record it and uninstall leaves it. Project settings outrank your user settings, so a project install leaves any listing key that `~/.claude/settings.json` already sets (by a global install or by hand) to that file. A new project install with no `--context-window` and no `--reset` takes the value of the machine's global install; a profile, the console and the wizard pass their own value. A project built before the global install wrote its keys keeps its own until its next rebuild. The first build that writes the keys prints one line that names them and how to choose the other value. Claude Code reads these keys from about version 2.1.129; an older version keeps them and ignores them.
72
+
73
+ OpenClaude (checked on 0.31) and IBM Bob read neither key, and OpenCode does not cap its list, so on those hosts the option writes nothing. Every host records the choice: a `Context window: 1m` line in the install's instruction file, written only when it is not the default. Rebuilds, upgrades, `profile save` and the console read it back. The `setup` wizard keeps it without asking. Set it with the flag, a profile's `contextWindow` key, or the console's **Context window** picker on a Claude Code install.
74
+
55
75
  ### Related
56
76
 
57
77
  [Agents](agents.md) — who does the work · [Rules](rules.md) — what every skill obeys · writing your own: [docs/extending.md](../extending.md)
@@ -17,7 +17,7 @@ A **theme** changes the agent's *voice* and the words the harness uses for its o
17
17
  | how the agent phrases its replies | which rules apply, and their order |
18
18
  | the nouns for the harness's parts — an `imperial` install calls the Rules *Dictates*, agents *Adepts*, skills *Rites* | folder names: `agents/`, `skills/`, `memory/`, `laws/`, `doctrines/`… |
19
19
  | the banner, the readiness line the agent prints when it starts, the closing lines | section layout and the links between files |
20
- | the names and descriptions shown for rules, agents and skills | rule addresses such as `process 5` |
20
+ | the names and descriptions shown for rules, agents and skills, except the short description the host lists for each skill | rule addresses such as `process 5` |
21
21
 
22
22
  `neutral` keeps the plain words — Rule, Doctrine, Agent, Skill, Memory — so it is the theme to pick if you want no flavour at all. The [glossary](../reference/glossary.md) shows each themed word beside its neutral one.
23
23
 
package/docs/extending.md CHANGED
@@ -124,7 +124,7 @@ Notes that matter:
124
124
  held to it as a sum) because `node --test` over a glob that matches nothing prints `# tests 0`
125
125
  and **exits 0**. Node's default reporter changed between majors, which is how a green 1043-test
126
126
  suite once reported zero.
127
- - `--cli` runs the ~320-cell CLI/hook matrix against the expectations written in each cell —
127
+ - `--cli` runs the ~280-cell CLI/hook matrix against the expectations written in each cell —
128
128
  the only end-to-end gate on what a verb prints. CI runs it in `node-cells` on both platforms.
129
129
  A cell that needs a broken checkout plants its fault as an **edit of the real file**
130
130
  (`{ "edit": [[find, replace]] }` in `tests/helpers/matrix/cli.*.json`), never as a copy of it;
@@ -395,7 +395,16 @@ global emit and leaves the install intact*) proves a refused emit leaves the pri
395
395
  2. One row in the hand-authored table in `src/AGENT.md.tmpl` (the `## 3.` table for agents, the `## 4.` one for skills).
396
396
  Gated both ways: a row with no file, and a file with no row.
397
397
  3. `DESC_<NAME>` in **all fourteen** themes. Theme parity catches a missing one; nothing catches
398
- an unstyled placeholder.
398
+ an unstyled placeholder. That themed purpose opens the skill's body. **Skills only**, and
399
+ kit and vendored skills too: one line in `src/skill-descriptions.json`, purpose and trigger
400
+ in at most 80 characters, theme-neutral and in the third person. It is the emitted
401
+ `description:` on every host, the only text the model routes on, and a vendored skill's
402
+ upstream description moves to the first body line. 80 because the host lists skills under
403
+ a budget (about 6 000 characters on a 200k model) and drops the descriptions of the
404
+ least-used skills when the listing overruns it, which on a fresh install is any of them.
405
+ `catalogueLineProblems` refuses a missing, stale, empty or over-long line, and
406
+ `descriptionProblems` holds every emitted `SKILL.md` to the same limit. (This reverses the
407
+ 2026-11-11 themed-catalogue decision for the frontmatter line only, 2026-11-15.)
399
408
  4. **Skills only** — `SKILL_CLASS` in `js/inspect/inventory.mjs`. Gated both ways, inside
400
409
  `countTableProblems`, which matters because the runtime fallback is silent: an unclassified
401
410
  skill renders as `build`.
@@ -25,6 +25,24 @@ cd Geneseed
25
25
  .\install.cmd
26
26
  ```
27
27
 
28
+ ### With no questions: a profile
29
+
30
+ Add `--profile <name>` to either installer and it asks nothing. It installs that profile globally into every AI coding tool the profile lists and finds on the machine, puts `geneseed` on your `PATH`, sets the web console to start at login, starts it and runs the doctor. `starter` is the profile for a first install:
31
+
32
+ Windows (cmd or PowerShell):
33
+
34
+ ```bat
35
+ .\install.cmd --profile starter
36
+ ```
37
+
38
+ macOS, Linux:
39
+
40
+ ```bash
41
+ ./install --profile starter
42
+ ```
43
+
44
+ With `--profile`, the installer skips its own `link` and its "open the console now?" question, and `install.cmd` skips its final pause, so a script that runs it returns. Run the same line again to update and repair. [Install profiles](../reference/profiles.md) has the file format and what each run does.
45
+
28
46
  Later, run the launcher in the clone: `./geneseed setup` (Windows: `.\geneseed.cmd setup`) re-runs the wizard, and bare `./geneseed` opens the web console. Both launchers need `node` on `PATH`. If it is not there (some version managers only patch interactive shells), set `GENESEED_NODE` to the absolute path of the Node binary.
29
47
 
30
48
  From a clone, every `geneseed …` command on these pages is `./geneseed …` (Windows: `.\geneseed.cmd …`). To drop the `./`, see [Run geneseed from anywhere](run-anywhere.md).
@@ -6,13 +6,19 @@ kind: "concept"
6
6
  section: "Install"
7
7
  description: "The build command to run in a script, a CI job, or a shell with no terminal."
8
8
  ---
9
- `setup` needs an interactive terminal. In a script, a CI job, or any shell without one, it stops with exit code 1 and prints the build command to run instead:
9
+ `setup --profile <name>` needs no terminal. It installs a named profile (Shipped, from `profiles/`, or Personal, from `~/.config/geneseed/profiles/`) globally into each AI coding tool the profile lists and finds, with no question, and exits 1 when a build or the doctor fails. A profile with `"login": false` skips the login item and the console, which is what a server or a CI job wants. See [Install profiles](../reference/profiles.md).
10
+
11
+ ```
12
+ geneseed setup --profile starter
13
+ ```
14
+
15
+ The wizard, plain `setup`, needs an interactive terminal. In a script, a CI job, or any shell without one, it stops with exit code 1 and prints the build command to run instead:
10
16
 
11
17
  ```
12
18
  geneseed build --emit opencode-global --theme neutral
13
19
  ```
14
20
 
15
- `geneseed build` takes the same flags as the generator `geneseed-build`. `--emit` picks the host and its scope: `files`, `opencode`, `opencode-global`, `claude`, `claude-global`, `bob`, `bob-global`, `openclaude` or `openclaude-global`. A `-global` emit writes into the tool's own config directory. A project emit writes into the repo you name with `--out <repo> --root <repo>`. All the other flags (`--theme`, `--footprint`, `--posture`, `--mode`, `--trust`, `--doctrines`, `--exclude-rules`) are covered in [Choose your setup](choose-your-setup.md) and the two pages after it. `--exclude-skills` leaves skills you never use out of the install; see [Exclusions](../concepts/exclusions.md). `--kits <kit>` switches on an opt-in kit, and `--kits none` switches every kit off; see [Kits](../concepts/kits.md).
21
+ `geneseed build` takes the same flags as the generator `geneseed-build`. `--emit` picks the host and its scope: `files`, `opencode`, `opencode-global`, `claude`, `claude-global`, `bob`, `bob-global`, `openclaude` or `openclaude-global`. A `-global` emit writes into the tool's own config directory. A project emit writes into the repo you name with `--out <repo> --root <repo>`. All the other flags (`--theme`, `--footprint`, `--posture`, `--mode`, `--trust`, `--doctrines`, `--exclude-rules`) are covered in [Choose your setup](choose-your-setup.md) and the two pages after it. `--exclude-skills` leaves skills you never use out of the install; see [Exclusions](../concepts/exclusions.md). `--kits <kit>` switches on an opt-in kit, and `--kits none` switches every kit off; see [Kits](../concepts/kits.md). `--context-window 1m` builds a Claude Code install for a 1M-token model (the default is `200k`); see [the listing budget](../concepts/skills.md#the-listing-budget-on-claude-code).
16
22
 
17
23
  To test a build before writing anything, use `geneseed validate` with the same flags. See [Verify](verify.md).
18
24
 
@@ -8,6 +8,24 @@ description: "The one-command install, what it needs, and the page for each host
8
8
  ---
9
9
  Geneseed builds a harness (the rules, agents, skills and hooks your AI coding tool loads; see [What a harness is](../understand/harness.md)) and installs it into the tool you already use. Most people need one command.
10
10
 
11
+ ## New to AI agents: one line, no questions
12
+
13
+ You need **git** and **Node 22.7 or newer**. Run one line from the folder that gets the clone. It clones Geneseed the first time and pulls on later runs, so the same line installs, updates and repairs. It runs the installer with the `starter` profile:
14
+
15
+ Windows (cmd, PowerShell 5.1 or 7):
16
+
17
+ ```bat
18
+ cmd /c "(if exist Geneseed (git -C Geneseed pull) else (git clone https://github.com/Arylmera/Geneseed.git)) && cd Geneseed && .\install.cmd --profile starter"
19
+ ```
20
+
21
+ macOS, Linux:
22
+
23
+ ```bash
24
+ { [ -d Geneseed ] && git -C Geneseed pull || git clone https://github.com/Arylmera/Geneseed.git; } && cd Geneseed && ./install --profile starter
25
+ ```
26
+
27
+ It asks nothing. It installs the harness globally into every AI coding tool it finds (OpenCode, IBM Bob, Claude Code, OpenClaude), puts `geneseed` on your `PATH`, sets the web console to start at login, starts it, runs the health check, and prints a summary with the console's address. With no tool on the machine it installs nothing and prints where to get each one. `starter` is a neutral voice, a candid peer posture, and every guardrail armed except the ownership gate. [Install profiles](../reference/profiles.md) has the details: how to save your own setup as a Personal profile, apply a profile to one project with `geneseed profile apply`, and how a team adds a Shipped one.
28
+
11
29
  ## The 5-minute path
12
30
 
13
31
  The only prerequisite is **Node 22.7 or newer**.
@@ -18,7 +36,7 @@ npx geneseed setup
18
36
 
19
37
  The command is the same on macOS, Linux and Windows (cmd, PowerShell or any POSIX shell). The setup wizard lists the AI coding tools it found on your `PATH` or in the usual per-user folders, then asks for a theme, a posture, a mode, the doctrine packs, the kits, an install mode and a footprint. Each one has a safe default, so you can hold Enter through all of them. [Choose your setup](choose-your-setup.md) explains each question. **OpenCode global** is the recommended install mode: you install once and every repo inherits it, with nothing committed into your projects. The wizard then builds the harness and ends with a short summary: the root file your tool loads and where it was written, the hooks it wired (Claude Code, Bob and OpenClaude), whether memory learning is on, which tool to restart, and a link to what was installed. It then offers to run a health check.
20
38
 
21
- To keep the command on your machine:
39
+ `npx geneseed setup` puts no `geneseed` command in your terminal, and its summary ends with a note that says so. To keep the command on your machine:
22
40
 
23
41
  ```
24
42
  npm install -g geneseed
@@ -76,7 +76,7 @@ A rebuild of a global install in its host's own config directory also runs [the
76
76
 
77
77
  ## Local edits, and the improvements file
78
78
 
79
- The agent records what it learns about a skill or agent in notes, which rebuilds never overwrite: under `notes/skill-notes/` and `notes/agent-notes/` in the shared tier on a global install, and under `notebook/skill-notes/` and `notebook/agent-notes/` on a project install. Edits made to the deployed agent and skill files themselves, by you or by an older harness, are another matter: a rebuild would overwrite those, so **setup, re-theme and upgrade export them first**. When deployed files carry local edits (files only behind the source are not edits and are not exported), the differences are written to a markdown **improvements file** in `improvements/`, inside the install's own folder (for the OpenCode global install, `~/.config/opencode/improvements/`). The manifest does not list that folder, so rebuilds never overwrite it and uninstall never removes it.
79
+ The agent records what it learns about a skill or agent in notes, which rebuilds never overwrite: under `notes/skill-notes/` and `notes/agent-notes/` in the shared tier for a fix true in any repo, and under `notebook/skill-notes/` and `notebook/agent-notes/` at the project root for a fact true only there. A project install kept all its notes in its host layer's notebook before (`.claude/notebook/`, `.bob/notebook/`, `.openclaude/notebook/`, `.opencode/notebook/`); its next rebuild merges them into the project's `notebook/` as project notes, prints one line, and sets the originals aside in `notebook/archived-agent-notes/` and `notebook/archived-skill-notes/` at the project root (in a linked worktree, the main checkout's, so removing the worktree keeps them). The clone's `.git/info/exclude` keeps these folders out of every commit. A file it cannot merge stays where it is and is named. Edits made to the deployed agent and skill files themselves, by you or by an older harness, are another matter: a rebuild would overwrite those, so **setup, re-theme and upgrade export them first**. When deployed files carry local edits (files only behind the source are not edits and are not exported), the differences are written to a markdown **improvements file** in `improvements/`, inside the install's own folder (for the OpenCode global install, `~/.config/opencode/improvements/`). The manifest does not list that folder, so rebuilds never overwrite it and uninstall never removes it.
80
80
 
81
81
  A rebuild also refuses to overwrite a file you edited. The manifest records a fingerprint of every file Geneseed wrote; when a file no longer matches it, the rebuild leaves it alone and prints `kept your edited <file> — delete it to get Geneseed's copy back`. From then on the file is yours and later rebuilds skip it. A file the new version no longer ships is kept the same way, with `(no longer shipped)`. Line-ending changes from a git checkout do not count as edits. Installs made before fingerprints existed are overwritten as before.
82
82
 
@@ -38,6 +38,6 @@ Where distilled memories land at session end, and which model distils them. See
38
38
  | `GENESEED_HARNESS` | learn, context, guard plugins; CLI | Base whose `memory/` is written (and where `geneseed-wiki.jsonc` is looked up). Optional — a global install finds the shared store by itself. Set it only to pin another store: it wins over the shared one, so a value such as `~/.config/opencode` keeps facts out of the tier. |
39
39
  | `GENESEED_MEMORY` | learn plugin, CLI, hand-run `learn` | Explicit memory dir; wins over `GENESEED_HARNESS` and the shared store. It moves what the OpenCode learn plugin, `geneseed memory` and a hand-run `learn` use. It does not move the `learn` hook, which is told its store by `--memory`, or what a session loads and the console shows: those read the tier. Without either variable, `geneseed memory`, `status` and a hand-run `learn` use a project install in the cwd or `./Harness`, then the shared store, then the OpenCode config store. A `memory/` folder counts only when an emit made it: a known `.geneseed-emit`, `.geneseed-version` beside the folder and `MEMORY.md` in it. Any other is not a store: name it with `--memory`. Two host installs in one repo keep two stores, and these commands use the one the marker names: name the other with `--memory`. |
40
40
  | `GENESEED_MODEL` | learn + context plugins | `provider/model` fallback when the session's model can't be read from the transcript. |
41
- | `GENESEED_LLM` | learn hook (Claude Code, Bob, OpenClaude) | Model CLI used to distil, e.g. `claude -p`. Unset, a real Stop/SubagentStop/PreCompact call returns immediately — nothing reads its stdout there; a manual `learn` run (notes piped or given as a file) still prints the prompt instead of distilling. |
41
+ | `GENESEED_LLM` | learn hook (Claude Code, Bob, OpenClaude) | Model CLI used to distil, e.g. `claude -p`. Unset, a real Stop/SubagentStop/PreCompact call distils nothing and returns without reading the transcript for it — nothing reads its stdout there. The SubagentStop copy of `spec-feedback:` lines into `agent-notes/`, and the Stop copy of a skill's `[skill:<name>]` lines into `skill-notes/`, run either way; a manual `learn` run (notes piped or given as a file) still prints the prompt instead of distilling. |
42
42
  | `GENESEED_LEARN_CHILD` | learn hook | Set by `learn` itself on the model CLI it spawns; a nested session's own Stop hook sees it and returns immediately, which stops `GENESEED_LLM="claude -p"` (hooks not disabled) from recursing. Not meant to be set by hand. |
43
43
  | `GENESEED_LEARN_DEBOUNCE_MS` | learn plugin | Quiet period before distilling, in ms (default 60000). |
@@ -20,7 +20,7 @@ Where Geneseed writes an install, and what an upgrade re-renders.
20
20
  | --- | --- | --- |
21
21
  | `GENESEED_HOME` | build / hooks | Directory holding the hook shim `bin/geneseed-hook` (default `~/.geneseed`). Change it, then rebuild, so the emitted hooks point at the new location. |
22
22
  | `GENESEED_ACTIVITY` | hooks, OpenCode plugin | `off` (or `0`, `false`, `no`) stops the activity writer; the hooks then load none of its code. Absent means on. See [geneseed-activity](plugin-activity.md). |
23
- | `GENESEED_NO_USAGE` | hooks, OpenCode guard plugin, web console | Any value stops the usage counter: no skill or subagent call is appended to `notebook/usage.jsonl`, and the console reports the counter as off. |
23
+ | `GENESEED_NO_USAGE` | hooks, OpenCode guard and learn plugins, web console | Any value stops the usage counter: no skill or subagent call, and no typed `/<skill>`, is appended to `notebook/usage.jsonl`, no finished subagent to `notebook/agent-runs.jsonl`, and the console reports the counter as off. |
24
24
  | `GENESEED_LLM_TIMEOUT` | `learn` hook | Seconds the `learn` hook waits for the model CLI before it stops it and drops the partial reply (default 120; anything but a positive number means the default). |
25
25
  | `GENESEED_HOOK_TAP` | hooks | An absolute directory outside any repository. Every hook call then writes one file there, `<host>-<event>-<n>.json`, holding the payload's shape: keys kept, every string replaced by its type and length. For recording what a host really sends; unset, nothing is written. A directory inside a git worktree is refused. See [Verify it works](../guides/verify.md#bob-by-hand). |
26
26
  | `GENESEED_NO_SHIM_CHECK` | CLI | `1` silences the warning every `geneseed` command prints when the hook shim points at a path that no longer exists. For scripted callers; the `status` gates row still says `DEAD`. |
@@ -29,6 +29,10 @@ or when it is the host's own config dir, as the hook does.
29
29
 
30
30
  So a global install needs nothing set. `GENESEED_HARNESS` and `GENESEED_MEMORY` are deprecated, with removal planned for 6.0. If none resolves, it logs `no memory dir — this install has no memory/ folder, and neither does the shared tier or this repo.` and does nothing.
31
31
 
32
+ **A finished child session.** For a child session that names its agent, the plugin first copies the report's `spec-feedback:` lines into `agent-notes/<name>.md`, then appends one line to the install's `notebook/agent-runs.jsonl`: the day, the agent, its spec hash, its tool calls and refused calls, its feedback lines and whether it reported. The done-gate fields stay empty, because that gate is in the context plugin. The tool counts read the session's `tool` parts: on OpenCode 1 the whole child session; on OpenCode 2 the shape of `session.context()` tool parts is UNVERIFIED against a live host, so when no tool part it knows is seen, both counts are empty rather than 0. A refused call is one whose error opens with `[geneseed-guard] blocked:` (OpenCode 1) or `No tool named "BLOCKED, not a missing tool:` (OpenCode 2). It writes once per child session, at its first quiet period in each OpenCode process, only when that `notebook/` exists, and not with `GENESEED_NO_USAGE` set or a `.usage-off` file in the install. The install's `notebook/` is beside `plugins/` for a global install (`<config dir>/notebook`) and at the repo root for a project install (`<repo>/notebook`, not `<repo>/.opencode/notebook`). The spec-feedback notes follow each line's scope, as the Claude hook does: a machine line to the tier's `notes/`, a project line (`[agent:project]`, `[general:project]`, `[skill:<name>:project]`, `[skill:<name>:general:project]`) to `<project>/notebook/`, where the project is `<repo>` for a project install and the session root's git root for a global one. When a global and a project install both load, only one of them records a run, as for `usage.jsonl`. `geneseed catalog agents --scores` reads it. See [Agents](../concepts/agents.md).
33
+
34
+ **A skill's feedback line.** At the end of every turn (`session.idle` on OpenCode 1, `session.execution.succeeded` on OpenCode 2), not after the quiet period, the plugin reads the session's last reply and copies each `spec-feedback: [skill:<name>]` line into `skill-notes/<name>.md` (`[skill:<name>:general]` into `skill-notes/_general.md`) in the machine notes, or a `[skill:<name>:project]` line into the project's `notebook/skill-notes/<name>.md`, as for the agents' notes. A line counts only for a skill the install serves under that name (`skills/<name>/SKILL.md` beside `plugins/` names its own notes file); an untagged, `[agent]` or plain `[general]` line in a reply is a relayed sub-agent line and is not copied. On OpenCode 1 the turn's capture reads ONE message: the newest assistant message a `message.updated` event named, by `session.message`; only when no such event was seen (a plugin loaded mid-turn) does it read the session's messages once. On OpenCode 2 it reads `session.context()`, the messages since the last compaction, once per turn: V2 offers no single-message read the plugin knows of. Nothing is read in an install with no `skills/` folder or in an excluded folder. A line already in the notes is not added again. With a global and a project install both loaded, both copies resolve the same two notes files, so a line lands once: the duplicate check runs under the file lock (on Claude Code the global hook stands down instead). See [Skills](../concepts/skills.md).
35
+
32
36
  **Switches.**
33
37
  - `GENESEED_MODEL=provider/model` — fallback when the session's model can't be read. Without it you get `could not determine a model`.
34
38
  - `GENESEED_LEARN_DEBOUNCE_MS` — the quiet period.