geneseed 5.4.0 → 5.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (162) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +30 -0
  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 +10 -1
  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 +142 -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 +1 -1
  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 +6 -3
  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/guillaume-claude-global.json +16 -0
  85. package/profiles/starter.json +14 -0
  86. package/src/AGENT.md.tmpl +1 -1
  87. package/src/agents/_self-improvement.md +15 -7
  88. package/src/agents/_template.md +4 -2
  89. package/src/agents/advocate.md +1 -1
  90. package/src/agents/architect.md +1 -1
  91. package/src/agents/developer.md +10 -3
  92. package/src/agents/devops-engineer.md +1 -1
  93. package/src/agents/docker-expert.md +1 -1
  94. package/src/agents/docs.md +1 -1
  95. package/src/agents/empiricist.md +1 -1
  96. package/src/agents/explorer.md +4 -2
  97. package/src/agents/framer.md +1 -1
  98. package/src/agents/historian.md +1 -1
  99. package/src/agents/kubernetes-specialist.md +1 -1
  100. package/src/agents/memory-curator.md +1 -1
  101. package/src/agents/operator.md +1 -1
  102. package/src/agents/performance.md +1 -1
  103. package/src/agents/pragmatist.md +1 -1
  104. package/src/agents/react-engineer.md +1 -1
  105. package/src/agents/react-reviewer.md +1 -1
  106. package/src/agents/researcher.md +1 -1
  107. package/src/agents/reviewer.md +10 -3
  108. package/src/agents/security.md +1 -1
  109. package/src/agents/skeptic.md +1 -1
  110. package/src/agents/spring-boot-engineer.md +1 -1
  111. package/src/agents/spring-reviewer.md +1 -1
  112. package/src/agents/spring-security.md +1 -1
  113. package/src/agents/steward.md +1 -1
  114. package/src/agents/tester.md +4 -2
  115. package/src/agents/user-advocate.md +1 -1
  116. package/src/agents/visionary.md +1 -1
  117. package/src/memory/README.md +12 -2
  118. package/src/modes/foreman.md +23 -10
  119. package/src/skill-descriptions.json +63 -0
  120. package/src/skills/_self-improvement.md +42 -26
  121. package/src/skills/_template.md +3 -1
  122. package/src/skills/brainstorm.md +35 -22
  123. package/src/skills/daydream/VENDOR.md +6 -0
  124. package/src/skills/diagram-design/VENDOR.md +4 -0
  125. package/src/skills/explain-changes/VENDOR.md +5 -1
  126. package/src/skills/parallel-agents.md +11 -0
  127. package/src/skills/pipeline.md +3 -3
  128. package/src/skills/plan.md +5 -4
  129. package/src/skills/react-view-transitions/VENDOR.md +7 -1
  130. package/src/skills/release.md +7 -2
  131. package/src/skills/rule/approve.md +2 -1
  132. package/src/skills/skill-forge.md +5 -3
  133. package/src/skills/token-report/VENDOR.md +5 -1
  134. package/src/upstreams.json +2 -2
  135. package/themes/README.md +3 -1
  136. package/web/dist/assets/{ActiveLoops-BJJN3P-V.js → ActiveLoops-DOJCPPPc.js} +1 -1
  137. package/web/dist/assets/{Activity-D2kOc3yi.js → Activity-LKsDzsnK.js} +1 -1
  138. package/web/dist/assets/{ActivityDetail-By3xOr21.js → ActivityDetail-DhwTfPm6.js} +1 -1
  139. package/web/dist/assets/{Bonsai-CBWDTBA4.js → Bonsai-CePMLrpr.js} +1 -1
  140. package/web/dist/assets/{CopyButton-BVbpriMB.js → CopyButton-CuoaJ6k7.js} +1 -1
  141. package/web/dist/assets/{Dashboard-CIJLPHM9.js → Dashboard-D1VKuvLe.js} +2 -2
  142. package/web/dist/assets/{Docs-CiRRIELs.js → Docs-CUrHJKaU.js} +1 -1
  143. package/web/dist/assets/{Factories-DhyK0O8d.js → Factories-Ci1XfmSy.js} +1 -1
  144. package/web/dist/assets/{GreenhouseView-DW3PgTPy.js → GreenhouseView-CNfH2lPK.js} +1 -1
  145. package/web/dist/assets/Installs-ZHQZM1iS.js +3 -0
  146. package/web/dist/assets/{JournalView-O65qEWfp.js → JournalView-CMsWahkS.js} +1 -1
  147. package/web/dist/assets/{Kits-C5U-yT6Z.js → Kits-CkliyK0n.js} +1 -1
  148. package/web/dist/assets/{Laws-CuTw_XNf.js → Laws-hh4O3HZ4.js} +1 -1
  149. package/web/dist/assets/{LibRows-D6-CVa3K.js → LibRows-Brv0Hmkr.js} +1 -1
  150. package/web/dist/assets/{Library-CzPlerd6.js → Library-BYmiLjJr.js} +1 -1
  151. package/web/dist/assets/{Loops-CqNF_-nS.js → Loops-ytm-xJ68.js} +1 -1
  152. package/web/dist/assets/{OperatorHudView-BNr8K5qj.js → OperatorHudView-KaqCx_HP.js} +1 -1
  153. package/web/dist/assets/{Personal-DeDb9e8O.js → Personal-CmcnRKYE.js} +1 -1
  154. package/web/dist/assets/{Settings-B8MPN_AD.js → Settings-tUrpdOfq.js} +1 -1
  155. package/web/dist/assets/{Tabs-DJzAez4h.js → Tabs-CD7etcGD.js} +1 -1
  156. package/web/dist/assets/api-CZ-x0iWG.js +1 -0
  157. package/web/dist/assets/{controls-D4wmg_pl.js → controls-CK7qHA8H.js} +1 -1
  158. package/web/dist/assets/{index-CRWqKxfY.css → index-Ba_Kg3Af.css} +1 -1
  159. package/web/dist/assets/{index-BL3P-9Rg.js → index-COKbhFNo.js} +3 -3
  160. package/web/dist/index.html +3 -3
  161. package/web/dist/assets/Installs-B6nlo-Ly.js +0 -3
  162. package/web/dist/assets/api-DLDVY3K-.js +0 -1
@@ -20,7 +20,7 @@
20
20
  <!-- bash: allow -->
21
21
 
22
22
  ## Procedure
23
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
23
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
24
24
  1. Read the motion and the arguments, then list the load-bearing claims on both sides ({{DOCTRINE:read-the-docs-first}}).
25
25
  2. Mark each claim evidenced or unevidenced — and call out any asserted as fact without a source ({{LAW:verify-before-asserting}}).
26
26
  3. For the decisive unknowns, name the cheapest experiment, benchmark, or check that would settle them.
@@ -24,14 +24,16 @@
24
24
  <!-- bash: allow -->
25
25
 
26
26
  ## Procedure
27
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
27
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
28
+ When the brief says to answer from what it hands you alone, skip steps 0–2.
28
29
  1. Search to locate the relevant files before reading them ({{DOCTRINE:context-economy}}).
29
30
  2. Read only the slices that matter; follow references outward as needed.
30
31
  3. Synthesize — return findings, not raw dumps.
31
32
 
32
33
  ## Output contract
33
34
  - A concise answer: the conclusion, the key `file:line` references that support
34
- it, and any open questions. Never the full contents of what was read.
35
+ it, and any open questions. Never the full contents of what was read. In a git repo, name
36
+ the commit the facts were read at (`git rev-parse --short HEAD`).
35
37
  - If the search comes up empty, report what was searched and where, and answer
36
38
  not-found — a confident wrong location costs more than an honest blank
37
39
  ({{LAW:verify-before-asserting}}).
@@ -17,7 +17,7 @@
17
17
  - **Read-only.** Search and read, to ground the reframe in the real need. Never edits, never runs commands, never casts the verdict.
18
18
 
19
19
  ## Procedure
20
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
20
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
21
21
  1. Read the motion and what prompted it, then restate the underlying need in one plain sentence ({{DOCTRINE:read-the-docs-first}}).
22
22
  2. Test whether the motion addresses that need or only a symptom of it; ask what problem it would leave unsolved.
23
23
  3. If the framing is off, offer the reframed problem — the question the council should actually be debating.
@@ -20,7 +20,7 @@
20
20
  <!-- bash: allow -->
21
21
 
22
22
  ## Procedure
23
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
23
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
24
24
  1. Read the motion, then search the codebase, changelog, and docs for prior attempts, reverts, and related decisions ({{DOCTRINE:read-the-docs-first}}).
25
25
  2. Reconstruct what was tried, how it went, and *why* — separating what actually happened from lore.
26
26
  3. Draw the lesson that bears on this decision; flag if the conditions have since changed enough to make it moot.
@@ -21,7 +21,7 @@ Deploys Spring Boot 4 applications on Kubernetes.
21
21
  - Never applies to a live cluster and never pushes without the user's say-so ({{DOCTRINE:consent-before-push}}).
22
22
 
23
23
  ## Procedure
24
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
24
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
25
25
  1. Match the project's manifest style; do not introduce a new tool.
26
26
  2. Probes: liveness `/actuator/health/liveness`, readiness `/actuator/health/readiness` (on the management port if `management.server.port` is set); add a startup probe for slow starts. Boot exposes these health groups by default; `management.endpoint.health.probes.enabled=false` turns them off.
27
27
  3. Shutdown: `server.shutdown=graceful` with `spring.lifecycle.timeout-per-shutdown-phase` below `terminationGracePeriodSeconds`; a short `preStop` sleep lets endpoints drain.
@@ -29,7 +29,7 @@
29
29
  approved by code ({{LAW:deletion-is-deliberate}}).
30
30
 
31
31
  ## Procedure
32
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
32
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
33
33
  1. Read the map (`MEMORY.md`), then one topic file at a time, then only the facts
34
34
  that topic needs ({{DOCTRINE:context-economy}}). On a large store, work topic by
35
35
  topic and report progress after each one (`3/14 topics: 4 merged, 2 archived`).
@@ -18,7 +18,7 @@
18
18
  - **Read-only.** Search and read, to judge operability against the real system. Never edits, never runs commands, never casts the verdict.
19
19
 
20
20
  ## Procedure
21
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
21
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
22
22
  1. Read the motion and how it would run, so the concerns are this system's, not generic ({{DOCTRINE:read-the-docs-first}}).
23
23
  2. Pre-mortem the 3am incident: how it fails under load, whether you can see it failing (metrics, logs), and how you roll it back. Treat a production deploy with no tested rollback or fix-forward path and no retained previous artifact as not ready to ship — there must be a way back before there is a way out.
24
24
  3. Weigh the standing cost — the on-call burden, the toil, the new ways to be paged — against the benefit.
@@ -25,7 +25,7 @@
25
25
  <!-- bash: allow -->
26
26
 
27
27
  ## Procedure
28
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
28
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
29
29
  1. Pin the question: which metric (wall time, p95 latency, peak memory, allocations,
30
30
  query count), under which workload, and what number would count as fixed.
31
31
  2. Take a baseline with the project's own tooling where it has some, run several
@@ -18,7 +18,7 @@
18
18
  - **Read-only.** Search and read, to size the work against the real codebase. Never edits, never runs commands, never casts the verdict.
19
19
 
20
20
  ## Procedure
21
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
21
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
22
22
  1. Read the motion and the artifact so the estimate is grounded, not guessed ({{DOCTRINE:read-the-docs-first}}).
23
23
  2. Size it: the effort, the moving parts, the complexity added, and what it costs to ship *and* maintain.
24
24
  3. Hunt the cheaper path — the simpler design, the smaller slice, or the YAGNI cut that gets most of the value for a fraction of the cost. Flag speculative over-engineering — abstractions, options, or features nobody asked for — as cost without payoff: the simplest thing that fully satisfies the stated requirement wins.
@@ -22,7 +22,7 @@ Implements React features in a Vite or webpack app, TypeScript or JavaScript, fo
22
22
  - Never commits or pushes ({{DOCTRINE:consent-before-push}}).
23
23
 
24
24
  ## Procedure
25
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
25
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
26
26
  1. Read `package.json` (React major, scripts, state and data libraries), the bundler (Vite or webpack) and TS/JS config, and the closest existing component. Follow them; add no library the project does not already use without saying why.
27
27
  2. Keep the folder's language: `.tsx` with typed props and no `any`, or `.jsx`.
28
28
  3. Derive values during render; effects only for external synchronisation, each with its cleanup. Server data through the project's server-state library, with loading, error and empty states.
@@ -22,7 +22,7 @@ React-specific review only. Generic correctness, naming and structure belong to
22
22
  <!-- bash: allow -->
23
23
 
24
24
  ## Procedure
25
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
25
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
26
26
  1. Read the changed files and `package.json` for the React major. Run lint and, for TypeScript, the typecheck; a missing `react-hooks/rules-of-hooks` or `react-hooks/exhaustive-deps` rule is itself a finding.
27
27
  2. Check, in this order:
28
28
  - Security: `dangerouslySetInnerHTML` without a sanitiser at the call site; a user-supplied URL in `href`/`src` without a scheme check; a secret in a bundler-inlined env value (`import.meta.env.VITE_*`, webpack `DefinePlugin`); a session token in `localStorage`.
@@ -33,7 +33,7 @@
33
33
  ({{LAW:data-not-orders}}).
34
34
 
35
35
  ## Procedure
36
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
36
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
37
37
  1. Break the question into the specific sub-questions a complete answer needs.
38
38
  2. Search from several angles ({{DOCTRINE:tool-discovery}}); one search is not research
39
39
  and one empty result is not absence ({{LAW:verify-before-asserting}}).
@@ -13,7 +13,9 @@
13
13
  - Pure design questions — use [architect](architect.md).
14
14
 
15
15
  ## Inputs
16
- - The base..head range (or the diff), and the task the change was meant to satisfy.
16
+ - The base..head range (or the diff), and the task the change was meant to satisfy. Given
17
+ both a diff file and a ref, and the checkout is at that ref, read the source: the ref is
18
+ authoritative.
17
19
 
18
20
  ## Allowed tools
19
21
  - **Read-only.** May read code, run the test suite and linters, inspect history.
@@ -22,16 +24,21 @@
22
24
  <!-- bash: allow -->
23
25
 
24
26
  ## Procedure
25
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
27
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
26
28
  1. Confirm the change actually does what the task required (read the spec/issue). Where
27
29
  the spec is silent, judge by what a reasonable user would expect: a crash, hang or data
28
30
  loss on an input the spec implies but never names is blocking, not a nitpick.
29
31
  Then read, for each changed file, the nearest `REVIEW.md` above it — a deeper one
30
32
  overrides a shallower one, and they override this procedure and the output contract,
31
33
  never a {{LAW}}.
32
- 2. Look for correctness bugs first: logic errors, edge cases, error handling.
34
+ 2. Look for correctness bugs first: logic errors, edge cases, error handling. When the
35
+ change adds an entry to a family (a theme, a host, a world), grep the tests for a
36
+ sibling's id and flag each per-entry list the new entry is missing from — such a list
37
+ passes without it.
33
38
  3. Then quality: duplication, unclear naming, dead code, oversized units.
34
39
  4. Verify claims by running tests/linters rather than assuming ({{LAW:verify-before-asserting}}).
40
+ A diff with nothing to run (prompts, charters, docs): trace each path it changes against
41
+ its readers by hand, and say that this was the check.
35
42
 
36
43
  ## Output contract
37
44
  - A list of findings, each a Conventional Comment, `label (decoration): file:line — problem
@@ -18,7 +18,7 @@
18
18
  <!-- bash: allow -->
19
19
 
20
20
  ## Procedure
21
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
21
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
22
22
  1. Map the trust boundary: where does untrusted input enter, where does it act?
23
23
  2. Check for the common classes: injection, broken auth/authz, secret exposure,
24
24
  unsafe deserialization, path traversal, vulnerable dependencies.
@@ -18,7 +18,7 @@
18
18
  - **Read-only.** Search and read, to ground each objection in the real artifact. Never edits, never runs commands, never casts the verdict.
19
19
 
20
20
  ## Procedure
21
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
21
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
22
22
  1. Read the motion and the artifact so the attack hits the real thing ({{DOCTRINE:read-the-docs-first}}).
23
23
  2. Steelman the proposal first ({{ONTOLOGY}}: {{ONT_CONDUCT}}), then break *that* — the failure modes, the risks, and the load-bearing assumptions no one has checked.
24
24
  3. Pair every objection with what would resolve it (the roast-me {{SKILL}} discipline); drop any you cannot make concrete.
@@ -22,7 +22,7 @@ Implements Spring Boot 4 / Java 21+ features, following the spring-boot, spring-
22
22
  - Never commits or pushes ({{DOCTRINE:consent-before-push}}).
23
23
 
24
24
  ## Procedure
25
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
25
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
26
26
  1. Follow the project's existing layout and build tool; match its group id, packages and CI. Lombok is fine when the project already uses it.
27
27
  2. Constructor injection; records for request and response DTOs; `@Valid` on request bodies; one `@RestControllerAdvice` for errors.
28
28
  3. Services: `@Transactional(readOnly = true)` on the class, `@Transactional` on mutating methods. Never call a transactional or `@Async` method through `this`.
@@ -22,7 +22,7 @@ Spring-specific review only. Generic correctness, naming and structure belong to
22
22
  <!-- bash: allow -->
23
23
 
24
24
  ## Procedure
25
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
25
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
26
26
  1. Read the changed files and the build file to learn the Boot version.
27
27
  2. Check, in this order:
28
28
  - Injection: field `@Autowired`, circular dependencies.
@@ -21,7 +21,7 @@ Spring Security 7 audit only. The generic audit (injection, secrets, dependencie
21
21
  <!-- bash: allow -->
22
22
 
23
23
  ## Procedure
24
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
24
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
25
25
  1. Read the `SecurityFilterChain` beans first, then method-security usage and config files.
26
26
  2. Check:
27
27
  - Filter chain: a bean, never `WebSecurityConfigurerAdapter`; `authorizeHttpRequests` ends in `anyRequest().authenticated()` or `denyAll()`; only health and login endpoints open.
@@ -17,7 +17,7 @@
17
17
  - **Read-only.** Search and read, to judge fit against the real system. Never edits, never runs commands, never casts the verdict.
18
18
 
19
19
  ## Procedure
20
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
20
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
21
21
  1. Read the motion and the artifact, and the project's own conventions, so the judgement fits this system ({{DOCTRINE:read-the-docs-first}}, {{DOCTRINE:respect-conventions}}).
22
22
  2. Weigh the long game: structural coherence, maintainability, the debt incurred or paid down, reversibility, and fit with where the system is heading.
23
23
  3. Separate the durable consequence from the momentary convenience; name what the team lives with after the change lands.
@@ -18,11 +18,13 @@
18
18
  - Does not change production code; if a fix is needed, it reports the diagnosis.
19
19
 
20
20
  ## Procedure
21
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
21
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
22
22
  1. For new tests: write the test, watch it fail with the behaviour absent or
23
23
  deliberately broken, then confirm it passes against the implementation —
24
24
  a test that has never failed verifies nothing ({{LAW:verify-before-asserting}}).
25
- 2. For failures: reproduce, isolate the smallest failing case, find root cause.
25
+ 2. For failures: reproduce, isolate the smallest failing case, find root cause. A failure
26
+ seen in a concurrent run: re-run that file alone first. Green alone and red together is
27
+ load or a race, not the code — report it as such.
26
28
  3. Cover edge cases and error paths, not just the happy path — including
27
29
  adversarial inputs at any trust boundary the code under test exposes.
28
30
  4. Run the project's linter alongside the suite and report both exit codes — the
@@ -17,7 +17,7 @@
17
17
  - **Read-only.** Search and read, to ground the consumer's view in the real interface. Never edits, never runs commands, never casts the verdict.
18
18
 
19
19
  ## Procedure
20
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
20
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
21
21
  1. Read the motion and the surface it changes, so the view is the real user's, not a guess ({{DOCTRINE:read-the-docs-first}}).
22
22
  2. Stand in the consumer's shoes: walk the path they actually take and surface the friction, the surprise, and the unmet need.
23
23
  3. Separate what the team finds convenient from what the user actually experiences; name the gap.
@@ -17,7 +17,7 @@
17
17
  - **Read-only.** Search and read, to ground the vision in what exists. Never edits, never runs commands, never casts the verdict.
18
18
 
19
19
  ## Procedure
20
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
20
+ 0. Read first, each if it exists — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}): `{{PATH_MEMORY}}/agents/<your-name>.md`, then the feedback notes `{{PATH_NOTES}}/agent-notes/<your-name>.md` and `{{PATH_NOTES}}/agent-notes/_general.md`, then this repo's `{{PATH_PROJECT_NOTES}}/agent-notes/<your-name>.md` and `_general.md` there, which win where they disagree.
21
21
  1. Read the motion and the artifact so the ambition builds on reality, not a blank page ({{DOCTRINE:read-the-docs-first}}).
22
22
  2. Imagine the most valuable version: the 10× upside, the door this could open, what the proposal becomes if pushed further.
23
23
  3. Name what it would take to aim there, and the one bet the bigger version rests on.
@@ -133,8 +133,18 @@ Read and write follow one rule each:
133
133
  spec says so). This is the {{AGENT}}'s memory across dispatches.
134
134
  - **Write** — mechanical, never by the {{AGENT}} itself (most run read-only). When
135
135
  a subagent run ends, the learn step distils at most one lesson into the owning
136
- {{AGENT}}'s file. A caller may also fold a returned `spec-feedback:` line in by
137
- hand.
136
+ {{AGENT}}'s file. It needs `$GENESEED_LLM`; without one, this file is not written.
137
+
138
+ The `spec-feedback:` lines an {{AGENT}} ends its report with are a second, distinct
139
+ value, with one writer of their own: the same hook copies them, with no model call,
140
+ into the machine notes `{{PATH_NOTES}}/agent-notes/<agent-name>.md` (a `general` line into
141
+ `agent-notes/_general.md` there), or a line true only in this repo (`[agent:project]`,
142
+ `[general:project]`) into the same two files under `{{PATH_PROJECT_NOTES}}/agent-notes/` at the
143
+ project root; one dated bullet each, duplicates skipped. They are
144
+ capped: 100 bullets in an {{AGENT}}'s file, 30 in `_general.md`, 8 000 characters a file.
145
+ The {{AGENT}} reads all five files at step 0. Neither the caller nor this store holds a
146
+ copy, except on a host with no subagent-finished hook (Bob), where the caller copies the
147
+ line into the same file by hand. Folding a note into an {{AGENT}}'s source is the user's call.
138
148
 
139
149
  Same bar as {{DOCTRINE:persist-insight}}: capture only how this {{AGENT}} should work *next time* —
140
150
  a boundary that proved wrong, an input it always needs — never task residue. Files
@@ -3,6 +3,11 @@ task that would block it to one background task worker, and keeps answering the
3
3
 
4
4
  - **Stay responsive.** Answer the user immediately; never let a running worker
5
5
  block the conversation.
6
+ - **No dispatch tool, no foreman.** If this context holds no tool that can start a writing
7
+ (developer) worker (`Agent` on Claude Code and OpenClaude, `subagent`/`task` on OpenCode,
8
+ `spawn_subagent` on Bob), work as direct mode: do each task yourself, one at a time, in
9
+ one tree, and say so once to the user. Bob Shell, Bob's `ask` mode (it may start only
10
+ `explore`) and a Bob mode without the `subagent` group are such contexts.
6
11
  - **Triage by what would block you, counted, not felt.** Delegate a task when any one
7
12
  of these holds: it will run a command longer than about a minute (a test suite, a
8
13
  build, a canary); it will change three or more files; or it can run beside work
@@ -16,17 +21,16 @@ task that would block it to one background task worker, and keeps answering the
16
21
  - **One worker per task.** Dispatch one developer {{AGENT}} in the background, in its own
17
22
  worktree (without worktrees: one tree, one worker at a time). The brief carries the task as the user stated it, BASE, the write set, the
18
23
  proof commands, and the rule that it commits only in its own worktree, never pushes, and
19
- never merges outside its own branch; without a worktree, it never commits. It also says
20
- to run each command from the worktree as working directory or with absolute paths
21
- (`git -C`, `npm --prefix`), never opening with `cd <worktree> &&`: the host asks the user
22
- to approve that form. The worker explores, implements and tests in its own context, loading {{SKILLS}}
24
+ never merges outside its own branch; without a worktree, it never commits. It also covers
25
+ the **Brief checklist** in the parallel-agents {{SKILL}}: read it before you write the brief. The worker explores, implements and tests in its own context, loading {{SKILLS}}
23
26
  as it needs them; after two repair rounds on its own red tests it returns red with its
24
27
  findings ({{DOCTRINE:bound-the-loop}}). Check its write set against every task in flight
25
28
  ({{DOCTRINE:one-writer-per-file}}).
26
29
  - **A worker may lead, inside its worktree.** It may dispatch read-only helpers (explorer,
27
30
  researcher) at any time, and writing sub-workers, each in its own worktree branched from
28
31
  its branch, merged into its own with the proof re-run after each merge. Depth stops at
29
- main → worker → sub-worker: a sub-worker dispatches nothing. Every lead holds every member's result
32
+ main → worker → sub-worker: a sub-worker dispatches nothing. A worker that holds no
33
+ dispatch tool (every Bob subagent) does the work itself. Every lead holds every member's result
30
34
  before it ends. The blind reviewer stays the parent's.
31
35
  - **Status, one line per change.** A worker reports
32
36
  `T<n> · <task> · files: <write set> · <state>` at start and on each change: by
@@ -43,11 +47,20 @@ task that would block it to one background task worker, and keeps answering the
43
47
  `{{DIR_NOTEBOOK}}/foreman-ledger.md`, one line per live task:
44
48
  `T3 · <task> · agent <id> · worktree <path> · <state>` (running, green, red, verifying,
45
49
  merged, dropped). Update it on every dispatch and return; re-read it after a compaction.
46
- A correction, follow-up or verifier finding on a task goes to that task's worker
47
- (`SendMessage` on Claude Code), which resumes with its full context. Start a new worker
48
- only when the old one cannot be resumed — the host has no resume, or its context is
49
- spent — and hand it a note: the ask, the diff so far, the findings, what was tried. A
50
- worker serves one task and retires when that task is merged or dropped.
50
+ A correction, follow-up or verifier finding on a task goes to that task's worker, which
51
+ resumes with its full context: by `SendMessage` on Claude Code (on OpenClaude only in its
52
+ agent-teams mode); on OpenCode by the `subagent` tool with that worker's `sessionID` (V1:
53
+ `task` with `task_id`); the same call without `sessionID` (V1: `task_id`) starts a fresh
54
+ worker. Bob has no resume. Start a new worker only when the old one cannot be resumed —
55
+ the host has no resume, or its context is spent — and hand it a note: the ask, the diff
56
+ so far, the findings, what was tried. A new task gets a new worker by default. It may go
57
+ to an idle worker whose own task is settled (merged or dropped) when it works in the
58
+ same files or context and that worker's context is still light: the worker starts it on
59
+ a new branch from the current BASE, with the full brief of *One worker per task* (BASE,
60
+ write set, proof commands, the Brief checklist) and its write set checked against every
61
+ task in flight. Light or heavy is a judgement call, not a number: write the reason (same
62
+ files, context used) in the task's new ledger line. A worker never holds two live tasks;
63
+ one whose context is heavy, or whose last task touched other code, retires.
51
64
  - **Merge on proof you re-ran.** A worker hands back its branch, its local commits and any
52
65
  uncommitted work, with raw test + lint output. The parent re-runs those commands itself —
53
66
  a worker's log is the worker's account, not the state — merges the branch into its own,
@@ -0,0 +1,63 @@
1
+ {
2
+ "adhd": "On /adhd, \"adhd mode\" or \"I have ADHD\": next action first, short numbered steps.",
3
+ "brainstorm": "New feature or project with no design, \"brainstorm\", \"interview me\": spec first.",
4
+ "brick-forge": "New or changed loop brick, \"make a brick\", \"change the test brick\": write it.",
5
+ "bruno": "Bruno API collection, .bru files, OpenCollection YAML: create, convert, test.",
6
+ "codebase-design": "\"Where should the seam go\", module interface, glossary term, ADR: deep modules.",
7
+ "commit": "About to commit changes: stage only the task's paths, one focused message.",
8
+ "compose-ops": "compose.yaml, docker-compose, Dockerfile: health, volumes, pins, secrets.",
9
+ "council": "\"Convene a council\", \"debate this\", \"argue both sides\": viewpoints, a ruling.",
10
+ "daydream": "On /daydream: find hidden links between notes in an Obsidian vault.",
11
+ "debug": "Bug: failing test, crash, an error or stack trace, wrong return value, red CI.",
12
+ "deck": "Presentation, slides or a deck, no file format named: one offline HTML file.",
13
+ "dependencies": "\"What's outdated\", \"are we vulnerable\", audit or upgrade dependencies, CVEs.",
14
+ "develop": "Implement a feature, fix a bug, change behaviour: test first, then code, green.",
15
+ "diagram-design": "Diagram, chart, flowchart, architecture, sequence, ER, Gantt: HTML/SVG output.",
16
+ "document-project": "Docs missing or drifted, PRD, architecture doc, AGENTS.md: write them from code.",
17
+ "explain-changes": "\"What did you change\", \"show me the diff\", explain a PR: one offline HTML page.",
18
+ "factory": "Factory named, issue-to-pr, bug-report-to-fix: carry one item to a green PR.",
19
+ "factory-forge": "New factory, or change one: compose bricks and loops into a checked factory.",
20
+ "forge-mcp": "Build, extend or harden an MCP server that exposes an API as agent tools.",
21
+ "fresh-eyes": "Work claimed done, needs a blind check: a context-free agent judges the ask.",
22
+ "frontend-design": "New UI or redesign needing a point of view: palette, type, layout, no template.",
23
+ "geneseed": "Geneseed, the harness, AGENT.md: install, upgrade, repair, OpenCode theme.",
24
+ "geneseed-code-review": "Review a diff or PR before merge, \"roast my code\": correctness first.",
25
+ "git-history": "Learn from git history (bisect, blame, pickaxe), or repair or rewrite it safely.",
26
+ "gitlab-ci": ".gitlab-ci.yml, GitLab pipeline jobs: rules, needs, includes, cache, variables.",
27
+ "handoff": "Context filling, session ending mid-task, work passing on: write the state down.",
28
+ "herdr": "Only when the user names Herdr: drive its panes, tabs, workspaces and agents.",
29
+ "ingest": "Read a PDF, Word, PowerPoint, Excel, EPUB, HTML or a URL: convert to markdown.",
30
+ "jenkins-pipeline": "Jenkinsfile, Jenkins shared library, CPS or sandbox error: write or fix it.",
31
+ "learn-mode": "User wants to learn while building: they design each part, the agent explains.",
32
+ "loop": "\"Run a loop\", small validated iterations each committed: work a requirement.",
33
+ "opencode-cli": "Drive OpenCode V2 from a script or session: opencode run, sessions, server, MCP.",
34
+ "ownership": "Developer must own production code: they decide each part, the agent proposes.",
35
+ "parallel-agents": "Two or more independent subtasks, no shared state: fan out to parallel agents.",
36
+ "pipeline": "User asks for a pipeline or crew, or a big multi-specialist task: worktree crew.",
37
+ "plan": "Task with several steps or files: write a plan file first, track each step.",
38
+ "ponytail": "\"Ponytail\", \"be lazy\", \"yagni\", \"do less\", over-engineering: laziest fix.",
39
+ "profile": "User wants the agent to know who they are, PROFILE.md a stub: interview, draft.",
40
+ "prose": "Human-facing prose (commit body, PR, docs, reply): write it so it reads human.",
41
+ "prototype": "Design question needing a runnable answer, \"does this feel right\": prototype.",
42
+ "react": "React components, hooks, state, data fetching in a Vite or webpack app (TS/JS).",
43
+ "react-testing": "React tests with Jest, Testing Library, MSW: write or fix them.",
44
+ "react-view-transitions": "React View Transition API: page transitions, shared elements, route animations.",
45
+ "refactor": "Extract, rename, inline, split, dedupe working code; behaviour stays the same.",
46
+ "release": "User asks to cut or publish a release: version bump, changelog, tag, in sync.",
47
+ "research": "Needs current or external facts, not in the repo or the model: sourced answer.",
48
+ "review-response": "Review feedback arrived, from a human or agent: verify each point, then act.",
49
+ "roast-me": "User wants their own ask, plan, idea or writing torn apart, brutally, honestly.",
50
+ "rule": "\"Always\", \"never\", \"from now on\", \"remember that\", auto-merge on/off: record it.",
51
+ "security-audit": "Security review, threat model, \"is this safe\", auth or input change: audit it.",
52
+ "ship": "Change committed and verified: open the pull request, or merge the branch.",
53
+ "skill-forge": "Task repeats and no skill covers it, or a skill to sharpen, merge or retire.",
54
+ "spring-boot": "Spring Boot 4 service: controllers, config, security, HTTP clients, logging.",
55
+ "spring-data-jpa": "Spring Data JPA, Hibernate, N+1, LazyInitializationException, migrations.",
56
+ "spring-testing": "Spring Boot tests: @WebMvcTest, @DataJpaTest, @SpringBootTest, Testcontainers.",
57
+ "teach": "User asks to be taught something, or to have what they know tested: teach, quiz.",
58
+ "token-report": "Token or context usage, \"how full is the context\", what eats it: tables report.",
59
+ "wayfinder": "Work too big for one session, route unclear: map it as decision tickets.",
60
+ "wiki": "Needs the user's machine-wide knowledge base, or a cross-project fact to save.",
61
+ "workflow": "Deterministic multi-agent orchestration, host has a workflow tool: run a script.",
62
+ "worktree": "\"Worktree\", \"isolate this\", work must not share the checkout: own git worktree."
63
+ }
@@ -1,41 +1,57 @@
1
1
  ## Self-improvement
2
2
 
3
3
  <!-- LEAN:begin -->
4
- This {{SKILL}} keeps its own notes in `{{PATH_NOTES}}/skill-notes/<name>.md`,
5
- `<name>` being this {{SKILL}}'s name. When that file exists, read it before the
6
- first step — where it disagrees with this file, the notes win. They are yours to
7
- write, and no rebuild touches them.
4
+ This {{SKILL}} keeps notes in two scopes. Machine notes, true in every repo:
5
+ `{{PATH_NOTES}}/skill-notes/{{SKILL_NAME}}.md`, beside `{{PATH_NOTES}}/skill-notes/_general.md`,
6
+ which every {{SKILL}} shares. Project notes, true only in this repo: the same two files under
7
+ `{{PATH_PROJECT_NOTES}}/skill-notes/` at the project root (in a linked worktree, the main
8
+ checkout's). Read the four in that order, when they exist, before the
9
+ first step — where they disagree with this file, the notes win, and the project notes
10
+ win over the machine notes. No rebuild touches them.
8
11
 
9
12
  Close each run with one beat of reflection on the {{SKILL}} itself:
10
13
  - A step misled, a needed step was missing, or the trigger fired wrongly — that
11
- is a flaw in this file. Write the exact correction (trigger, procedure, or
12
- done-when) into the notes file on your own, with no prompt, as one line:
13
- `- [skill|general] <correction> [— situation: <when it applies>] — seen: <what happened, against what you expected> (<date>)`.
14
- `situation:` bounds where the correction holds; `seen:` is the evidence it is
15
- later judged by; `general` marks one that would fix other {{SKILLS}} too. Never
16
- edit this file: it is a rendered copy, a rebuild overwrites it. A bundled script
17
- that is broken is the one exception: fix it in place, and tell the user which
18
- file you changed. `geneseed diff` carries the notes back to the source;
14
+ is a flaw in this file. End your reply with one line that names it, at the start
15
+ of a line and outside any code:
16
+ `spec-feedback: [skill:{{SKILL_NAME}}] <the one-line fix> [— situation: <when it applies>] — seen: <what happened, against what you expected>`.
17
+ `situation:` bounds where the fix holds; `seen:` is the evidence it is later
18
+ judged by. Ask one question first: is it true in any repo, or only here? Any repo:
19
+ `[skill:{{SKILL_NAME}}]`, or `[skill:{{SKILL_NAME}}:general]` for a fix other {{SKILLS}} need
20
+ too. Only here: `[skill:{{SKILL_NAME}}:project]`, or `[skill:{{SKILL_NAME}}:general:project]`.
21
+ When the turn ends, the harness hook copies the line, dated, into the notes —
22
+ no model call, so do not write the notes file yourself. On Bob, whose hook never
23
+ sees your reply, append it yourself: `- [skill] <the fix> … (<date>)` to the machine
24
+ or the project `skill-notes/{{SKILL_NAME}}.md` above, or `- [general] <the fix> … ({{SKILL_NAME}}, <date>)` to
25
+ that scope's `skill-notes/_general.md`; amend or delete a stale line before adding one, and keep
26
+ each file under about twenty lines.
27
+ Never edit this file: it is a rendered copy, a rebuild overwrites it. A bundled
28
+ script that is broken is the one exception: fix it in place, and tell the user
29
+ which file you changed. `geneseed diff` carries the notes back to the source;
19
30
  folding a note into the source is the user's call, through the skill-forge
20
31
  {{SKILL}} ({{LAW:one-intent-one-act}}).
21
- - Keep the notes sharp: amend or delete a line before adding one — a line with no
22
- `seen:`, or whose `seen:` no longer happens, goes first — and prune past about
23
- twenty lines.
24
32
  - A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
25
33
  clears {{DOCTRINE:persist-insight}}'s bar: it would change how a future session behaves, and a
26
34
  fresh read of the repo would not re-derive it. Update an existing memory over
27
35
  adding one; when in doubt, leave it out.
28
- - No friction, nothing learned — move on; this loop earns no ceremony. Most
36
+ - No friction, nothing learned — no line; this loop earns no ceremony. Most
29
37
  runs end here.
30
38
  <!-- LEAN:else -->
31
- One beat of reflection on this {{SKILL}}: a step that misled, a missing step, or a
32
- wrong trigger is a flaw in this file — write the exact correction on your own, with no
33
- prompt, into `{{PATH_NOTES}}/skill-notes/<name>.md` (`<name>` is this {{SKILL}}'s
34
- name) as `- [skill|general] <correction> [— situation: <when it applies>] — seen: <what happened vs expected> (<date>)`,
35
- never into this rendered file, which a rebuild overwrites. A bundled script that is
36
- broken is the one exception: fix it in place, and tell the user which file you
37
- changed. Folding a note into the source is the user's call ({{LAW:one-intent-one-act}}).
38
- Read that notes file before the first step when it exists; it wins where it disagrees.
39
- Keep it short. A lesson that is not about this file goes to {{MEMORY}} only if it
40
- clears {{DOCTRINE:persist-insight}}'s bar. Nothing learned — move on.
39
+ Before the first step read, when they exist, the machine notes
40
+ `{{PATH_NOTES}}/skill-notes/{{SKILL_NAME}}.md` and `{{PATH_NOTES}}/skill-notes/_general.md`, then the
41
+ same two project notes under `{{PATH_PROJECT_NOTES}}/skill-notes/` at the project root (a linked
42
+ worktree: the main checkout's). Notes win over this file, project notes over machine notes.
43
+ One beat of reflection on this {{SKILL}}: a step that misled, a missing step, or a wrong
44
+ trigger is a flaw in this file — end your reply with one line, at a line start and outside any code,
45
+ `spec-feedback: [skill:{{SKILL_NAME}}] <the one-line fix> [— situation: <when it applies>] — seen: <what happened vs expected>`.
46
+ True in any repo, or only here? Any repo: `[skill:{{SKILL_NAME}}]`, or `[skill:{{SKILL_NAME}}:general]`
47
+ for a fix other {{SKILLS}} need too; only here: `[skill:{{SKILL_NAME}}:project]`, or
48
+ `[skill:{{SKILL_NAME}}:general:project]`. The hook copies it into
49
+ the notes when the turn ends; do not write them yourself, except on Bob, whose hook never
50
+ sees the reply: there append `- [skill] <the fix> … (<date>)` to the machine or the project
51
+ `skill-notes/{{SKILL_NAME}}.md`, or `- [general] <the fix> … ({{SKILL_NAME}}, <date>)` to that scope's
52
+ `skill-notes/_general.md`, pruning stale lines first. Never edit this rendered file; a broken bundled script is the one
53
+ exception: fix it in place, and tell the user which file you changed. Folding a note
54
+ into the source is the user's call ({{LAW:one-intent-one-act}}). A lesson that is not
55
+ about this file goes to {{MEMORY}} only if it clears {{DOCTRINE:persist-insight}}'s bar.
56
+ Nothing learned — no line.
41
57
  <!-- LEAN:end -->
@@ -15,7 +15,9 @@
15
15
  files disagree, so neither can silently drift.
16
16
  Geneseed source repo only (skip in an installed harness):
17
17
  4. Define the DESC_<NAME> token (hyphens -> underscores, uppercased) in ALL theme
18
- JSONs under themes/ — the parity gate fails if any theme is missing it.
18
+ JSONs under themes/ — the parity gate fails if any theme is missing it. Add the
19
+ skill's line to src/skill-descriptions.json: purpose and trigger in at most 80
20
+ characters, theme-neutral. It is the emitted description; doctor fails without it.
19
21
  5. Bump the `skills-N` count badge in README.md (doctor checks it against the real
20
22
  file count; the test counts derive from src/ and need no edit), then run
21
23
  `./geneseed doctor --all` and the repository's test suites.