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
@@ -22,16 +22,20 @@
22
22
  decisions the developer approved, carried in the brief.
23
23
 
24
24
  ## Allowed tools
25
- - **Read + write to the assigned worktree.** May run the project's own build/lint
26
- commands to self-check before handing off.
25
+ - **Read + write to the assigned worktree.** May run the project's own build, lint and
26
+ test commands to self-check before handing off; installs dependencies (`npm ci` and
27
+ alike) only when the brief allows it.
27
28
  <!-- bash: allow -->
29
+ - In an isolated worktree, run one plain command per call: `git -C <worktree>`, never
30
+ `cd <worktree> &&`, no heredocs. Change files with the edit and write tools; a `\u`
31
+ escape in source stays an escape — check it in the diff.
28
32
  - Commits only in its own worktree, never pushes, and never merges outside its own branch
29
33
  ({{DOCTRINE:consent-before-push}}); into that branch it merges only the branches of
30
34
  sub-workers it started. The parent re-runs the proof and merges beyond it once the user
31
35
  accepts.
32
36
 
33
37
  ## Procedure
34
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
38
+ 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.
35
39
  1. Implement the smallest change that satisfies the scoped task ({{DOCTRINE:smallest-viable-diff}}) —
36
40
  in the assigned worktree only, never touching the parent's own tree. In ownership mode,
37
41
  write only what the approved decisions cover; on a choice none of them covers, stop and
@@ -61,6 +65,9 @@ in your own context, and after two repair rounds on your own red tests return re
61
65
  findings ({{DOCTRINE:bound-the-loop}}). As a lead, hold every member's result before you end. Report `T<n> · <task> · files: <write set> · <state>`
62
66
  at start and on each change, as the mode says. Return the branch, its commit list, any
63
67
  uncommitted work, and the raw test + lint output — the parent re-runs it before any merge.
68
+ That output is a full run to completion, with the runner's own count line, never a
69
+ partial run. Call a failure pre-existing only after you reproduce it on a clean checkout
70
+ of BASE, and cite that run.
64
71
 
65
72
  ## Pipeline role
66
73
 
@@ -21,15 +21,16 @@ Builds CI/CD pipelines and delivery automation for Spring Boot applications.
21
21
  - Never commits, pushes or triggers a deployment ({{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. Detect the CI the project already uses (GitHub Actions, GitLab CI, Jenkins, other) and extend it; do not switch providers. With none present, ask the user which to use.
26
26
  2. Pipeline order: checkout, restore build cache, `./mvnw verify` (or `./gradlew build`), publish test results, build image, scan, push, deploy.
27
27
  3. Cache the Maven or Gradle repository keyed on the build files.
28
- 4. Gates: tests, a coverage threshold if the project has one, dependency and image vulnerability scan.
29
- 5. Build images with the project's chosen method (`spring-boot:build-image` by default); tag with version or commit SHA, never `latest` in production.
30
- 6. Stages dev, staging, prod, with approval before prod.
31
- 7. Secrets come from the CI secret store or a vault, never from files in the repository.
32
- 8. Lint the pipeline file before handing off.
28
+ 4. Gates: tests, a coverage threshold if the project has one, dependency and image vulnerability scan, `kustomize build` of every overlay when the project has them. Testcontainers needs a Docker daemon local to the job (on CircleCI the machine executor: a remote Docker's container ports are unreachable); confirm the integration tests ran (spring-testing skill).
29
+ 5. Docker Compose for local dependencies: follow the spring-boot skill's cloud side file (healthchecks).
30
+ 6. Build images with the project's chosen method (`spring-boot:build-image` by default); tag with version or commit SHA, never `latest` in production.
31
+ 7. Stages dev, staging, prod, with approval before prod.
32
+ 8. Secrets come from the CI secret store or a vault, never from files in the repository.
33
+ 9. Lint the pipeline file before handing off.
33
34
 
34
35
  ## Output contract
35
36
  - Files changed, the stage list and what was validated.
@@ -22,7 +22,7 @@ Builds small, safe container images for Spring Boot 4 applications.
22
22
  - Never pushes images or commits ({{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. Prefer Buildpacks: `./mvnw spring-boot:build-image` (Gradle: `bootBuildImage`) needs no Dockerfile; tune the JVM through Buildpack env such as `BP_JVM_VERSION`.
27
27
  2. Use a Dockerfile only when Buildpacks do not fit. Build multi-stage and extract layers with `java -Djarmode=tools -jar app.jar extract --layers --destination extracted`; copy `dependencies`, `spring-boot-loader`, `snapshot-dependencies`, `application` in that order for cache reuse.
28
28
  3. Run as a non-root user; pin base image tags or digests, never `latest`.
@@ -19,7 +19,7 @@
19
19
  may run documented examples and commands to confirm they work as written.
20
20
 
21
21
  ## Procedure
22
- 0. If `{{PATH_MEMORY}}/agents/<your-name>.md` exists, read it first — your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
22
+ 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.
23
23
  1. Read the actual code/behaviour before describing it — never document intent
24
24
  that the code does not implement ({{LAW:verify-before-asserting}}).
25
25
  2. Write for the stated audience; lead with what the reader needs to do.
@@ -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,9 @@ Deploys Spring Boot 4 applications on Kubernetes.
29
29
  5. Config: non-sensitive settings in a ConfigMap, credentials in a Secret; env vars bind through relaxed binding (`SPRING_DATASOURCE_URL`).
30
30
  6. Scale: HPA on CPU or custom metrics, a PodDisruptionBudget when replicas exceed one.
31
31
  7. Pod hardening: `runAsNonRoot`, no privilege escalation, pinned image tags.
32
- 8. Validate with a dry run or linter before handing off.
32
+ 8. What committed manifests may name, probes for dependencies deployed beside the service, and manifests for several platforms: follow the spring-boot skill's cloud side file.
33
+ 9. Check the target before giving deploy steps (`kubectl config current-context`, `oc whoami --show-server`); on OpenShift expose through Routes, not port forwarding.
34
+ 10. Validate with a dry run or linter before handing off.
33
35
 
34
36
  ## Output contract
35
37
  - Files changed and a one-line summary; say what was validated and what was not.
@@ -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,14 +22,14 @@ 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
- 2. Constructor injection; records for request and response DTOs; `@Valid` on request bodies; one `@RestControllerAdvice` for errors.
27
+ 2. Constructor injection; records for request and response DTOs; `@Valid` on request bodies; one `@RestControllerAdvice` for errors and `PagedModel` for lists, as the spring-boot skill's web side file shows.
28
28
  3. Services: `@Transactional(readOnly = true)` on the class, `@Transactional` on mutating methods. Never call a transactional or `@Async` method through `this`.
29
29
  4. Group related settings in `@ConfigurationProperties`, not scattered `@Value`.
30
30
  5. Outbound HTTP: `RestClient` for blocking calls, `@HttpExchange` interfaces for declarative clients; keep `WebClient` for reactive code only.
31
- 6. Persistence uses `jakarta.persistence`; never return entities from controllers.
32
- 7. Tests: positive and negative cases; `@MockitoBean` and `@MockitoSpyBean` for replaced beans; Testcontainers with `@ServiceConnection`.
31
+ 6. Persistence uses `jakarta.persistence`; never return entities from controllers. On a relational database the migration tool owns the schema (`ddl-auto: validate`): write the migration in the same change as the entity (spring-data-jpa skill).
32
+ 7. Tests: positive and negative cases; `@MockitoBean` and `@MockitoSpyBean` for replaced beans; Testcontainers with `@ServiceConnection`; what the integration tests must cover is in the spring-testing skill.
33
33
  8. Defaults worth setting: `server.shutdown=graceful` and `spring.lifecycle.timeout-per-shutdown-phase`.
34
34
  9. Run the affected build and tests before handing off ({{LAW:verify-before-asserting}}).
35
35
 
@@ -22,16 +22,18 @@ 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}}).
26
- 1. Read the changed files and the build file to learn the Boot version.
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
+ 1. Read the changed files and the build file to learn the Boot version. Review only the change: flag pre-existing code only where the change makes it worse, and never a choice the project documents on purpose.
27
27
  2. Check, in this order:
28
28
  - Injection: field `@Autowired`, circular dependencies.
29
29
  - Transactions: multi-step writes without `@Transactional`; self-invocation bypassing the proxy; transactions held across remote calls.
30
30
  - Persistence: N+1 on lazy collections (use `JOIN FETCH` or `@EntityGraph`), unbounded `findAll()`, entities returned from controllers, legacy `javax` persistence imports (the package is `jakarta.persistence`).
31
+ - Schema: an entity change with no migration in the same change, an edited applied migration, `ddl-auto: update` or `create` outside tests.
32
+ - Web: `Page`/`PageImpl` returned from a controller (use `PagedModel`) unless `spring.data.web.pageable.serialization-mode: via-dto` is set; a catch-all handler that returns the exception message; a stale update that does not answer 409.
31
33
  - Boot 4 API misuse: the removed Boot test-package mock and spy bean annotations (use `@MockitoBean`/`@MockitoSpyBean`), new `RestTemplate` code or blocking `WebClient` (use `RestClient`), new `TestRestTemplate` tests (prefer `RestTestClient`), `@DynamicPropertySource` where `@ServiceConnection` supports the container, `WebSecurityConfigurerAdapter`.
32
34
  - Test slices: `@SpringBootTest` where `@WebMvcTest` or `@DataJpaTest` would do; slices missing their collaborators.
33
35
  - Configuration: raw `@Value` for property groups, secrets in committed config.
34
- - Actuator: endpoints exposed beyond need, `show-details` open to anonymous callers.
36
+ - Actuator: endpoints exposed beyond need, `show-details` open to anonymous callers, probe paths blocked by security (cloud side file).
35
37
  3. Verify by running the tests rather than assuming ({{LAW:verify-before-asserting}}).
36
38
 
37
39
  ## Output contract
@@ -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
+ }