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
@@ -0,0 +1,45 @@
1
+ # Requirement traceability
2
+
3
+ **Best for:** answering which identified requirements come from a source, have a design element that satisfies them, and have a test or inspection that verifies them. The fixed source × requirement × design × verification trace makes an absent link visible. Use it only when the IDs and relationships come from supplied sources. An illustrative example must say so.
4
+
5
+ **Not this type:** A generic package dependency graph has no required requirement or verification column; use [Dependency graph](type-dependency.md) for that. Use [Heatmap](type-heatmap.md) when each cell encodes a value rather than a cited element ID and a typed relationship. Use [UML class](type-uml-class.md) for type structure and inheritance.
6
+
7
+ Keep the shipped SVG static: place each paper rectangle behind its own labels, use explicit house ink and readable text, and keep page styles off SVG marks. The verifier checks this bounded layout; the browser render gate checks the shipped pages.
8
+
9
+ ## Layout conventions
10
+
11
+ - One row per requirement, in a stable source order. Four fixed columns: **Source**, **Requirement**, **Satisfied by**, **Verified by**. The latter two headings state the relationship direction without relying on arrow placement.
12
+ - Each source cell prints a source ID and citation. Each requirement cell prints a stable ID and short statement. Each linked cell prints its element ID and short name. Its relationship type is visible in the column heading and in the cell label.
13
+ - Keep the three cells on the same horizontal row. Separate rows with a solid neutral rule. Do not draw links across rows or rely on color alone to imply coverage.
14
+ - If a relationship is absent in real input, show `No linked element` or `No verification` in its cell. Do not invent a link or turn a missing relationship into an empty box.
15
+ - Preserve one focal row at most. Accent may mark a coverage gap or an important requirement, but the text must name the condition.
16
+
17
+ ### Machine-readable contract
18
+
19
+ Each row is a `<g data-trace-row="REQ-ID" data-trace-source="source reference">` containing:
20
+
21
+ - one source and one requirement with `data-trace-kind`, unique `data-trace-id`, and a visible matching ID;
22
+ - an optional design and test element with the same kind and ID attributes;
23
+ - one `derives` relationship from source to requirement;
24
+ - one `satisfies` relationship from design to requirement, or an explicit missing relationship;
25
+ - one `verifies` relationship from test to requirement, or an explicit missing relationship.
26
+
27
+ Relationships use `data-trace-rel`, `data-trace-from`, and `data-trace-to`. A missing relationship uses `data-trace-missing="true"` and `data-trace-to` with no `data-trace-from`. The row ID and printed ID must agree. Every endpoint must be an authored ID in the same SVG. An ID is not evidence that the relationship is true; the source reference and visible label are still required. `scripts/verify-requirement-traceability.py` checks the structural contract for the shipped examples.
28
+
29
+ ## Complexity budget
30
+
31
+ - At most 6 requirement rows, each with one primary design link and one primary verification link in this overview. Split complex many-to-many trace data into an overview and a detail or use a table.
32
+ - At most one focal row. Do not shrink text to fit more rows.
33
+
34
+ ## Anti-patterns
35
+
36
+ - Anonymous boxes, untyped lines, or a design-to-test arrow presented as proof that a test verifies the requirement.
37
+ - A green status that hides a missing test ID or source reference.
38
+ - Repeating one test across requirements without checking that it actually verifies each requirement.
39
+ - Treating an illustrative specimen as evidence of a real system's compliance.
40
+
41
+ ## Examples
42
+
43
+ - `assets/example-requirement-traceability.html` — minimal light, illustrative account-access requirements.
44
+ - `assets/example-requirement-traceability-dark.html` — the same illustrative trace on the dark skin.
45
+ - `assets/example-requirement-traceability-full.html` — full editorial page with reading notes.
@@ -0,0 +1,80 @@
1
+ # SBGN
2
+
3
+ **Best for:** a biological process as a bipartite species/process graph — carotenoid cleavage, a signalling cascade, a metabolic map — where each reaction is a process node, each molecule is a species node, and every arc has a role (consumption, production, reversible, modulation). Use when the reader must see *what is consumed, what is produced, and inside which compartment*.
4
+
5
+ **Not this type:**
6
+
7
+ - Boxes and arrows of a runtime system → **Architecture** (`type-architecture.md`). Architecture has no species/process bipartition and no role-typed arcs.
8
+ - Decision logic with branches → **Flowchart** (`type-flowchart.md`).
9
+ - Containment without reactions → **Nested** (`type-nested.md`). Nested shows scope; it does not host process nodes or consumption/production.
10
+ - A quantity splitting across stages → **Sankey** (`type-sankey.md`). Sankey conserves width, not stoichiometry.
11
+
12
+ Authoring-only: the model arrives as text in the prompt. This type does not import SBML or SBGN-ML.
13
+
14
+ ## Layout conventions
15
+
16
+ - **Bipartite.** Every reaction is a **process** glyph (a 32×32 square). Every molecule is a **macromolecule** (a rounded rectangle). Never attach two species directly; never attach two processes directly.
17
+ - **Compartment first.** Draw the enclosing compartment (cytosol, chloroplast, nucleus) as a zone rect before arrows and nodes. One compartment in the canonical budget. Label it on a paper mask on the top edge.
18
+ - **Primary flow left → right:** substrates, then processes, then products. Fan-in to a shared product uses a dedicated vertical trunk; do not stack two productions on one y.
19
+ - **Orthogonal connectors** with `r=8` elbows (SKILL.md §6). Consumption and production take the filled arrow marker. A reversible pair is two-headed. Modulation takes the open-circle marker.
20
+ - **1 coral focal:** the species or process the figure exists to show, at most two accent elements in all. In the worked fixture that is beta-carotene and its cleavage process v1; every arc stays in ink.
21
+ - **House style, SBGN shapes.** Monochrome ink/muted, one accent. Keep SBGN's shape semantics (square process, rounded macromolecule, empty-set source/sink, circle-headed modulation) rather than colour-coding roles.
22
+
23
+ ### Glyphs (PD subset)
24
+
25
+ | Kind | Shape | `data-kind` |
26
+ |---|---|---|
27
+ | Macromolecule | Rounded rect, `rx=16`, 144×64 (or 160×64) | `macromolecule` |
28
+ | Process | Square 32×32, `rx=2` | `process` |
29
+ | Compartment | Zone rect, `rx=8`, paper-mask label | `compartment` |
30
+ | Source / sink | Empty-set: circle r=12 plus a diagonal | `source-sink` |
31
+ | Consumption | Filled arrow, species → process | `consumption` |
32
+ | Production | Filled arrow, process → species | `production` |
33
+ | Reversible | Two-headed, species ↔ process | `reversible` |
34
+ | Modulation | Open-circle head, species → process | `modulation` |
35
+
36
+ ```svg
37
+ <!-- Macromolecule -->
38
+ <g data-kind="macromolecule" data-entity-id="bcar" data-compartment="cyt">
39
+ <rect data-role="bounds" x="80" y="80" width="144" height="64" rx="16" fill="#f5f5f5"/>
40
+ <rect x="80" y="80" width="144" height="64" rx="16"
41
+ fill="rgba(191,69,32,0.08)" stroke="#bf4520" stroke-width="1"/>
42
+ <text x="152" y="108" …>B-carotene</text>
43
+ </g>
44
+
45
+ <!-- Process -->
46
+ <g data-kind="process" data-process-id="v1" data-compartment="cyt">
47
+ <rect data-role="bounds" x="280" y="96" width="32" height="32" rx="2"
48
+ fill="#f5f5f5" stroke="#2d3142" stroke-width="1"/>
49
+ </g>
50
+
51
+ <!-- Consumption / production -->
52
+ <path data-kind="consumption" data-from="bcar" data-to="v1"
53
+ d="M 224,112 H 280" fill="none" stroke="#4f5d75" stroke-width="1.2"
54
+ marker-end="url(#arrow)"/>
55
+ <path data-kind="production" data-from="v1" data-to="b10"
56
+ d="M 312,112 H 480" fill="none" stroke="#4f5d75" stroke-width="1.2"
57
+ marker-end="url(#arrow)"/>
58
+ ```
59
+
60
+ The file has exactly one `<svg data-diagram="sbgn">`. Process squares are 32×32 so they stay below the geometry-checker's 60×40 node floor; macromolecules are the nodes the connector rules attach to. Source/sink circles are decoration-sized and also below that floor.
61
+
62
+ **Machine-readable contract.** Species, processes, and the compartment carry stable IDs. Every arc declares `data-kind`, `data-from`, and `data-to`. `scripts/verify-sbgn.py` fails duplicate IDs, unresolved endpoints, an arc whose drawn path does not start on its `data-from` glyph's edge and end on its `data-to` glyph's edge, an arc with more than one `M` subpath, an arc that touches any other glyph or meets its own glyphs anywhere but its two ends, an arc hidden by `display`, `visibility`, `opacity`, `stroke-opacity`, `stroke` or `stroke-width`, a glyph part drawn outside its bounds rect, an arc whose `data-kind` is missing or unknown, an arc that skips the bipartite rule, a macromolecule drawn outside its compartment, a glyph or arc moved by a `transform` or positional CSS, and a figure over the Bruno ceiling. Place glyphs with `x`, `y`, `width`, and `height` only, and draw arcs in map coordinates with path data only. Every other `<path>`, `<line>`, `<polyline>`, `<polygon>`, or `<use>` in the map must be a declared arc; legend samples go inside `<g data-role="legend">`, use only `<line>`, `<rect>`, `<circle>`, and `<text>`, and stay clear of every glyph. Arcs never cross, touch, stack, or end on one another, measured on the drawn stroke including curves and corners; two arcs may share only a port on a glyph's edge. Route around first, and where the layout forces a single crossing, bridge it with the hop from [type-architecture.md](type-architecture.md#crossing-arrows--bridge--hop). The shipped map has one, where v3's product route hops v4's.
63
+
64
+ ## Budget
65
+
66
+ ≤7 macromolecules, ≤6 processes, ≤1 compartment, ≤2 source/sink glyphs, ≤16 arcs, 2 accent elements. This ceiling replaces SKILL.md §7's 9 nodes and 12 arrows rows for SBGN only (see [layout-budget.md](layout-budget.md#complexity-budget-per-diagram)); the other universal rows still apply. That ceiling is the Bruno_JExpBot2016 fixture: seven carotenoid species, six cleavage reactions, one cytosol. More species → split the map (overview of the pools, then one cleavage family).
67
+
68
+ ## Anti-patterns
69
+
70
+ - A species–species arrow with no process node — that is a flowchart, and it hides the reaction.
71
+ - A database or architecture box used as a macromolecule.
72
+ - Colour as the only distinction between consumption and modulation — the markers must differ, because greyscale still has to tell them apart.
73
+ - Importing SBML or SBGN-ML in this skill — author from the prompt; an extractor is a later, separate surface.
74
+ - Flattening the compartment into a caption (`all of this is cytosol`) — the compartment is a glyph.
75
+
76
+ ## Examples
77
+
78
+ - `assets/example-sbgn.html` — Bruno carotenoid cleavage, minimal light
79
+ - `assets/example-sbgn-dark.html` — identical IDs, topology, and coordinates, dark
80
+ - `assets/example-sbgn-full.html` — full editorial treatment of the same map
@@ -245,7 +245,7 @@ What each binding buys, and what it costs to omit:
245
245
  | `data-name` on the group and its category label | Two labels exchanged between rows rename both series, with every number still correct in isolation. |
246
246
  | `data-tick` / `data-value` on a tick | The printed axis could be relabelled wholesale — every box honestly placed on a scale the axis lies about. |
247
247
 
248
- `scripts/verify-box-plot.py` derives the value scale from the summaries themselves, requires the five-number order, holds every box, median, whisker and outlier to that scale, refuses an outlier inside the whiskers, caps the accent at one series (read through `var()`, `hsl()` and class, id or attribute selectors), refuses a bound mark hidden by `display`, `visibility` or `opacity`, and checks every bound tick against the mark it describes; `scripts/test-verify-box-plot.py` proves each check in both polarities and pins the sibling scope treaty in both directions.
248
+ `scripts/verify-box-plot.py` derives the value scale from the summaries themselves, requires the five-number order, holds every box, median, whisker and outlier to that scale, refuses an outlier inside the whiskers, caps the accent at one series (read through `var()`, `hsl()` and class, id or attribute selectors), refuses a bound mark hidden by `display`, `visibility` or `opacity` and a bound mark whose own paint draws it nothing (`none`, or a zero `stroke-width`, `stroke-opacity` or `fill-opacity`), and checks every bound tick against the mark it describes; `scripts/test-verify-box-plot.py` proves each check in both polarities and pins the sibling scope treaty in both directions.
249
249
 
250
250
  **Nothing may position a mark except its own attributes.** The checker reads raw `x`/`width`/`x1`/`cx` and `y`/`cy`, so anything applied afterwards invalidates the check that passed. Every carrier is refused — the `transform` attribute, an inline `style="…"`, and a rule in a `<style>` block — on a series group, on a box, on a bound label or tick, or on an ancestor `<g>`/`<svg>`. Bake the offset into the coordinates.
251
251
 
@@ -0,0 +1,180 @@
1
+ # Steps
2
+
3
+ **Best for:** a short, ordered sequence of stages where the order is the claim and each stage needs a number, a compact visual cue, a title, and one brief explanation. Use it for methods, playbooks, onboarding paths, launch checklists, and “how it works” explainers.
4
+
5
+ Prefer **Timeline** when spacing encodes real elapsed time, **Flowchart** when the route branches, **Swimlane** when ownership and handoffs matter, and **Process** when each stage must expose actors, tools, or input/output payloads. Steps has one rail, no branches, no time scale, and no actor lanes.
6
+
7
+ ---
8
+
9
+ ## 1. Inputs
10
+
11
+ ```yaml
12
+ steps: # 3..7, left to right
13
+ - number: "01"
14
+ title: "Frame"
15
+ description: ["Define the decision", "and its success signal"]
16
+ icon: file # optional; from primitive-icons.md
17
+ - number: "02"
18
+ title: "Research"
19
+ description: ["Gather evidence from", "customers and operators"]
20
+ icon: users
21
+ - number: "03"
22
+ title: "Synthesize"
23
+ description: ["Turn observations into", "one testable direction"]
24
+ icon: search
25
+ focal: true
26
+ - number: "04"
27
+ title: "Decide"
28
+ description: ["Commit the scope and", "name the trade-offs"]
29
+ icon: database
30
+ - number: "05"
31
+ title: "Ship"
32
+ description: ["Release, measure, and", "feed learning forward"]
33
+ icon: container
34
+ dark: false
35
+ ```
36
+
37
+ Rules:
38
+
39
+ - `steps` contains 3–7 entries. Fewer than three is a list; more than seven needs grouping or a second diagram.
40
+ - Exactly one step is `focal: true`. It is the decision, transformation, or risk the figure exists to emphasize.
41
+ - `number` is two digits for fewer than 100 steps (`01`, `02`, …) so the rail scans evenly.
42
+ - `description` is one or two short lines, each no longer than 26 characters at the standard ramp. Rewrite rather than shrink.
43
+ - `icon` is optional and must come from [`primitive-icons.md`](primitive-icons.md). Omit icons from every step if a coherent set is unavailable; never mix line icons, emoji, and brand marks.
44
+
45
+ ---
46
+
47
+ ## 2. Layout grammar
48
+
49
+ The canonical `doc-wide` canvas is `1280×720`. All structural coordinates sit on the 4px grid.
50
+
51
+ ```text
52
+ outer_x = 80
53
+ rail_y = 240
54
+ rail_h = 48
55
+ n = len(steps)
56
+ usable_w = 1280 - 2 * outer_x
57
+ stage_w = min(224, 4 * floor(usable_w / (4 * n)))
58
+ content_w = n * stage_w
59
+ start_x = (1280 - content_w) / 2
60
+ stage_x(i) = start_x + i * stage_w
61
+ stage_cx(i) = stage_x(i) + stage_w / 2
62
+ medallion_cy = rail_y + rail_h / 2
63
+ medallion_r = 36
64
+ number_y = 164
65
+ number_rule_y = 184..220
66
+ title_y = 360
67
+ description_y = 388, 408
68
+ legend_rule_y = 600
69
+ legend_y = 636
70
+ ```
71
+
72
+ This yields a 224px stage for 3–5 steps, 184px for 6, and 160px for 7. Keep `stage_w` on the 4px grid, center the combined rail, and preserve at least 24px between description columns. If copy does not fit the narrower six- or seven-stage columns, widen the canvas or rewrite the copy; do not reduce the type ramp.
73
+
74
+ ### Rail
75
+
76
+ - Draw one contiguous horizontal rail from `stage_x(0)` to `stage_x(n-1) + stage_w`.
77
+ - Each stage owns one `stage_w × 48` segment. Alternate `ink @ 0.05` and `ink @ 0.09` fills to make the segmentation visible without introducing a series palette.
78
+ - The focal segment uses `accent-tint` with a 1px `accent` top and bottom rule.
79
+ - The rail itself expresses order. Do not add arrows between adjacent stages; they duplicate the layout.
80
+
81
+ ### Number and guide
82
+
83
+ - Number: `{eyebrow}` role, 8px, weight 600, letter-spacing `0.14em`, centered at `stage_cx(i)`.
84
+ - Guide: 1px vertical rule from `y=184` to `y=220`, `rule-solid`; focal guide uses `accent`.
85
+ - The number is `muted` by default and `accent` for the focal step.
86
+
87
+ ### Icon medallion
88
+
89
+ - Circle center `(stage_cx(i), 264)`, radius 36.
90
+ - Draw an opaque `paper` circle first so the rail does not show through, then a 1px outline.
91
+ - Default outline and icon use `ink`; focal outline and icon use `accent` and the circle may use `accent-tint`.
92
+ - Place one 24×24 primitive at `(stage_cx(i)-12, 252)`. Icons are decorative (`aria-hidden="true"`); the accessible name comes from the SVG title and description.
93
+
94
+ ### Copy block
95
+
96
+ - Title: `{node-name}` role, 12px, weight 600, centered at `y=360`.
97
+ - Description: `{sublabel}` role, 9px, centered, at most two lines at `y=388` and `y=408`.
98
+ - Titles use `ink`; descriptions use `muted`. The focal title may use `accent`; the description remains `muted`.
99
+
100
+ ---
101
+
102
+ ## 3. Focal and color rules
103
+
104
+ One step is focal. Treat its number, guide, rail segment, medallion outline/icon, and title as one visual unit. All remaining steps stay neutral.
105
+
106
+ Do not assign a different hue to every step. The familiar five-color infographic treatment turns sequence into a legend-reading task and conflicts with the global 1–2 accent rule. If stages genuinely encode categories rather than order, use a chart or another type whose color carries data.
107
+
108
+ ---
109
+
110
+ ## 4. Legend
111
+
112
+ Use a bottom strip only when the focal state needs explanation. The canonical examples show:
113
+
114
+ - neutral outlined medallion — `Stage`
115
+ - accent outlined medallion — `Focal stage`
116
+ - italic note — `Equal spacing shows order, not elapsed time.`
117
+
118
+ If the title or subtitle already names the focal stage and the distinction is obvious, remove the legend.
119
+
120
+ ---
121
+
122
+ ## 5. Reproducibility checklist
123
+
124
+ 1. Step count is 3–7 and exactly one entry is focal.
125
+ 2. Step origins, segment widths, medallion centers, and copy anchors derive from §2.
126
+ 3. The rail is contiguous; there are no gaps, arrowheads, or diagonal connectors.
127
+ 4. Every medallion has an opaque paper mask beneath its outline.
128
+ 5. Every step either has one icon from `primitive-icons.md` or all icons are omitted.
129
+ 6. Titles stay at 12px and descriptions at 9px; long copy is rewritten, not shrunk.
130
+ 7. The focal step is the only accent-bearing stage.
131
+ 8. The SVG uses the accessible SVG contract and the wrapper owns horizontal scrolling.
132
+
133
+ ---
134
+
135
+ ## 6. What `verify-steps.py` requires
136
+
137
+ The checker reads attributes, so every mark binds itself to its stage and draws exactly what it states.
138
+
139
+ - **Bindings.** Each stage has one rail `<rect data-role="rail">`, one medallion `<circle data-role="medallion">` and one number `<text data-role="number">`, all with the same unique `data-step`. Rails also carry `data-index` 1..n in left-to-right order. Exactly one rail and its medallion carry `data-focal="true"`.
140
+ - **Geometry.** Rails share `y`, `width` and `height` and touch end to end. Medallions are centered on their segment with one shared radius; numbers are centered on it at `x` and print the two-digit index. Every mark stays inside the viewBox.
141
+ - **Allowed attributes.** A rail may carry only `x y width height fill fill-opacity`, a medallion only `cx cy r fill stroke stroke-width`, a number only `x y fill font-size font-weight font-family text-anchor`, plus their `data-*` bindings. No `style`, `class`, `id`, `transform`, `dx`/`dy`, `opacity` or anything else. A number contains only its text.
142
+ - **Groups.** Marks sit only inside plain `<g>` groups of the one root `<svg>`, never inside `defs`, a nested `svg` or any other element. A group above a mark may carry only `aria-hidden fill stroke stroke-width stroke-linecap stroke-linejoin font-family font-size font-weight letter-spacing text-anchor`. No attribute may appear twice on any element.
143
+ - **Paint and type.** The first `<rect>` in the SVG is the paper (`#f5f5f5` light, `#2d3142` dark). Rails fill with a non-paper house ink above zero alpha. Medallion outlines and numbers use a house ink at 0.4 alpha or more. Numbers resolve to font-size 8 or more, a font family starting with Geist, Geist Mono or Instrument Serif, and `text-anchor="middle"`. Strokes are at most 4 wide.
144
+ - **Page and CSS.** Style marks with presentation attributes. Stylesheet rules that can reach the SVG may set only `box-sizing`, `margin`, `padding` and custom properties; nothing may move or hide the diagram. CONTRIBUTING.md lists the page rules in full.
145
+
146
+ A minimal three-stage figure that passes, with the second stage focal:
147
+
148
+ ```html
149
+ <svg viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="steps-min-title steps-min-desc">
150
+ <title id="steps-min-title">Plan, build, ship</title>
151
+ <desc id="steps-min-desc">Three equal stages on one rail; build is the focal stage.</desc>
152
+ <rect width="100%" height="100%" fill="#f5f5f5"/>
153
+ <g aria-hidden="true">
154
+ <rect x="304" y="240" width="224" height="48" fill="rgba(45,49,66,0.05)" data-role="rail" data-step="plan" data-index="1"/>
155
+ <rect x="528" y="240" width="224" height="48" fill="rgba(191,69,32,0.08)" data-role="rail" data-step="build" data-index="2" data-focal="true"/>
156
+ <rect x="752" y="240" width="224" height="48" fill="rgba(45,49,66,0.05)" data-role="rail" data-step="ship" data-index="3"/>
157
+ </g>
158
+ <g font-family="'Geist Mono', monospace" font-size="8" font-weight="600" letter-spacing="0.14em" text-anchor="middle">
159
+ <text x="416" y="164" fill="#4f5d75" data-role="number" data-step="plan">01</text>
160
+ <text x="640" y="164" fill="#bf4520" data-role="number" data-step="build">02</text>
161
+ <text x="864" y="164" fill="#4f5d75" data-role="number" data-step="ship">03</text>
162
+ </g>
163
+ <g aria-hidden="true" fill="#f5f5f5" stroke-width="1">
164
+ <circle cx="416" cy="264" r="36" stroke="#2d3142" data-role="medallion" data-step="plan"/>
165
+ <circle cx="640" cy="264" r="36" stroke="none"/>
166
+ <circle cx="640" cy="264" r="36" fill="rgba(191,69,32,0.08)" stroke="#bf4520" data-role="medallion" data-step="build" data-focal="true"/>
167
+ <circle cx="864" cy="264" r="36" stroke="#2d3142" data-role="medallion" data-step="ship"/>
168
+ </g>
169
+ </svg>
170
+ ```
171
+
172
+ ---
173
+
174
+ ## 7. Anti-patterns
175
+
176
+ - Rainbow stage bands with no categorical meaning.
177
+ - Using Steps for dated events, branching decisions, actor handoffs, or feedback loops.
178
+ - Paragraphs under each stage; two short lines is the ceiling.
179
+ - A different icon style per stage, emoji mixed with line icons, or icons that repeat the title without adding recognition.
180
+ - Arrowheads between every adjacent segment. The left-to-right rail already says “next.”
@@ -0,0 +1,63 @@
1
+ # Unit Grid
2
+
3
+ **Best for:** one bounded whole expressed as equal, discrete units: completion, capacity, survey responses, inventory, or a checklist. Use the canonical waffle form when the reader needs to see an exact count out of 100.
4
+
5
+ Not for: category-by-category comparison (use a **bar chart**), a part-of-whole with unequal pieces (use a **treemap**), continuous change (use a **line chart**), or a matrix where row and column positions carry meaning (the future punch-card variant).
6
+
7
+ ## Input contract
8
+
9
+ ```yaml
10
+ title: "Release readiness"
11
+ total: 100
12
+ filled: 64
13
+ unit_label: "release check"
14
+ focal_index: 63
15
+ source_note: "Illustrative checklist"
16
+ ```
17
+
18
+ Validation rules:
19
+
20
+ 1. Version 1 is a 10 by 10 grid with exactly 100 cells.
21
+ 2. `total` is exactly `100`; `filled` is an integer from `0` through `100`.
22
+ 3. Every cell represents one unit. Do not use fractional cells, scaled cells, or merged cells.
23
+ 4. At most one completed cell is focal. Accent is editorial emphasis, never a larger unit.
24
+ 5. Cells fill in reading order, left to right and top to bottom. A different order needs an explicit future variant.
25
+ 6. Rows and columns carry no category meaning in the canonical waffle form.
26
+
27
+ ## Layout conventions
28
+
29
+ - Use a 10 by 10 grid of equal 20px cells with a 4px gutter. The shipped examples begin at `(382, 86)`, making the grid 236px square inside a `1000 × 390` viewBox.
30
+ - Every chart root carries `data-unit-grid="true"`, `data-unit-total="100"`, `data-unit-filled`, `data-unit-rows="10"`, and `data-unit-columns="10"`.
31
+ - Every cell is a `<rect>` with `data-unit-cell="filled"` or `data-unit-cell="empty"` and a unique `data-unit-index` from 0 through 99. `scripts/verify-unit-grid.py` checks count, geometry, indices, the declared filled value, and printed labels.
32
+ - Use one ink fill for completed cells, a quieter paper-relative fill for remaining cells, and no more than one accent completed cell. The count, not color, carries the value. Set each cell's literal fill on the `<rect>` (or a parent `<g>`): completed cells must match the page's `:root` `--ink` or `--accent`, and remaining cells share one other fill well away from both. Cells sit directly in the chart `<svg>` or in plain `<g>`/`<a>` groups with no `style`, `transform` or conditional attributes; cell strokes stay at or under 2px and corner radii at or under a quarter of the cell. The verifier rejects opacity, visibility, display, filter, mask, clip-path, paint-order and mix-blend-mode on cells or their ancestors, paint, stroke or hiding rules in `<style>` (after decoding escapes), `@import`, any linked stylesheet but Google Fonts, SMIL animation, and any element drawn after the first cell whose box touches the grid or cannot be computed from plain numeric attributes. It does not see HTML wrappers around the SVG or scripts.
33
+ - Mark the percentage text with `data-unit-percent="true"` and the count text with `data-unit-count="true"`. They must read `64%` and `64 complete · 36 remaining` for `filled: 64`; both are checked against `data-unit-filled`. Each label is plain visible `<text>` inside the chart SVG (no child elements, no hiding or `style` attributes), painted `--ink` or `--muted`, at least 8px, and inside the viewBox.
34
+ - Do not apply transforms to cells or their SVG/group ancestors, or move geometry through CSS. Bake movement into the coordinates so the verifier checks the rendered positions.
35
+ - Put the exact count in text near the grid and state the unit in the source line. The grid must remain understandable in grayscale.
36
+ - Keep the legend block below the grid. Label the focal cell as editorial emphasis, so it cannot be mistaken for a special unit.
37
+
38
+ ## Honest-data rule
39
+
40
+ A unit grid claims that one mark equals one unit. Never round a 63.4% result to 64 filled cells without saying that the display is rounded. Never use a partial fill, larger focal cell, gradient, or area-sized mark to recover precision. If the denominator is not naturally bounded to 100, choose a number of whole cells that makes the unit honest or choose a different chart.
41
+
42
+ ## Complexity budget
43
+
44
+ - Exactly 100 cells in a 10 by 10 grid.
45
+ - One count and one optional focal completed cell.
46
+ - One legend and one source note.
47
+ - Static output only.
48
+ - No categorical row or column axes in version 1.
49
+
50
+ ## Anti-patterns
51
+
52
+ - Partial, merged, oversized, or differently shaped cells.
53
+ - Rainbow status fills or multiple accent cells.
54
+ - Using the grid for a denominator other than 100 without an explicit future variant.
55
+ - Treating rows and columns as categories. That is the later punch-card variant, not this canonical waffle form.
56
+ - Gradients, heatmap ramps, 3-D treatments, or shadows.
57
+ - Filling in a non-reading order without explaining that order.
58
+
59
+ ## Examples
60
+
61
+ - `assets/example-unit-grid.html` - minimal light.
62
+ - `assets/example-unit-grid-dark.html` - minimal dark with the same dataset and geometry.
63
+ - `assets/example-unit-grid-full.html` - full editorial with unchanged grid geometry.
@@ -15,6 +15,10 @@ Consequences of riding this mechanism (deliberate):
15
15
  - exempt from the flat-skill authoring gates (theme DESC tokens, dead-link,
16
16
  hermeticity) — the SKILL.md carries its own frontmatter `description`, and it
17
17
  names no themed term: the notebook directory reaches the script as `--out`;
18
- - listed in AGENT.md's folder-skills section, not the main skills table.
18
+ - listed in AGENT.md's folder-skills section, not the main skills table;
19
+ - at emit time the `description:` of `SKILL.md` is replaced with the skill's line in
20
+ `src/skill-descriptions.json` (at most 80 characters: the host's skill listing has a budget),
21
+ and the description written here is kept as the first body line, a blockquote
22
+ (`vendoredWithCatalogueLine`, `js/hosts/native.mjs`).
19
23
 
20
24
  The script needs only `node` and `git`, both already present wherever Geneseed runs.
@@ -21,7 +21,8 @@
21
21
  4. For a large change, consider dispatching the
22
22
  [reviewer {{AGENT}}](../{{DIR_AGENTS}}/reviewer.md) to keep the main context clean.
23
23
  When a spec exists and the diff spans more than a few files, run pass 3 in its own
24
- subagent, handed only the diff command and the spec, alongside passes 1–2: a pass
24
+ subagent — started fresh, never a fork of your own context — handed only the diff
25
+ command and the spec, alongside passes 1–2: a pass
25
26
  that has already filled up on code findings stops reading the spec closely, and
26
27
  kept apart, one axis's findings never mask the other's.
27
28
  5. Pass 1 — correctness: logic errors, edge cases, error handling, race
@@ -11,7 +11,18 @@
11
11
  ## Procedure
12
12
  1. Confirm independence: the subtasks must not depend on each other's output or write the same files ({{DOCTRINE:one-writer-per-file}}). Write down each unit's **write set** — the files or globs it may change — and intersect them; an overlap runs in sequence or goes to one owner, and shared append files (registries, index tables, lockfiles, generated bundles) stay with you. If they're sequential or share state, use [plan](plan.md) instead.
13
13
  2. Split the work into self-contained units, each with one clear goal and a defined output contract — what it must return. Several small edits of one kind (the same fix, constant or field across files) form ONE unit with the union write set and get one review.
14
- 3. Dispatch each unit to its own subagent in one batch — units that call one rationed resource run in sequence instead ({{DOCTRINE:serialize-against-a-rationed-resource}}) — each under a handoff envelope: the unit's goal, the inputs it needs, its **write set** (edit nothing outside it; return rows for a shared file instead of writing it), the observable check that proves it done, its output contract — naming every file it changed — and the inherited constraints (a unit in the shared tree never commits or pushes; a slice on its own branch (step 6) commits only there, never pushes — {{DOCTRINE:consent-before-push}} stays with you; no sub-agents of its own — review comes from you; gaps reported, never invented). Hand each unit only the access its goal needs ({{LAW:least-privilege}}). Prefer the read-only [explorer {{AGENT}}](../{{DIR_AGENTS}}/explorer.md) for investigation so the heavy reading stays out of the main context ({{DOCTRINE:context-economy}}). Where no subagent capability exists, run the units sequentially as personas instead, converging the same way.
14
+ 3. Dispatch each unit to its own fresh subagent (never a fork: a fork carries your context and model tier) in one batch — units that call one rationed resource run in sequence instead ({{DOCTRINE:serialize-against-a-rationed-resource}}) — each under a handoff envelope: the unit's goal, the inputs it needs, its **write set** (edit nothing outside it; return rows for a shared file instead of writing it), the observable check that proves it done, its output contract — naming every file it changed — and the inherited constraints (a unit in the shared tree never commits or pushes; a slice on its own branch (step 6) commits only there, never pushes — {{DOCTRINE:consent-before-push}} stays with you; no sub-agents of its own — review comes from you; gaps reported, never invented). Hand each unit only the access its goal needs ({{LAW:least-privilege}}). Prefer the read-only [explorer {{AGENT}}](../{{DIR_AGENTS}}/explorer.md) for investigation so the heavy reading stays out of the main context ({{DOCTRINE:context-economy}}). Where no subagent capability exists, run the units sequentially as personas instead, converging the same way.
15
+
16
+ **Brief checklist** — the envelope also states:
17
+ - **Git state:** the ref to measure (`HEAD` or `origin/main`, after a fetch) and whether the diff is staged, on disk or committed; after a restart, `git log` before redoing "uncommitted" work — a stale ref redoes every finding.
18
+ - **The whole write set:** every other call or literal site of a touched symbol, and its twin or generated copies, found by search before dispatch — a new field breaks the sites nobody listed.
19
+ - **Scratch and load:** one scratch path per unit, at most cores/2 full suites at once, and default test concurrency where spawning is CPU-bound (Windows) — shared scratch clobbers, an oversubscribed suite fails as time-outs.
20
+ - **Model tier:** you pick each unit's tier per task and name it in the brief. The strongest tier is your own current model (no override = inherit); step down, never up — intermediate for well-scoped writing, light for read-only search, counting and digests, your own for judgement (review, security, design) and for a retry after a failed attempt. Host with no lower tier, or model names unknown (OpenCode: set per machine): inherit. (Claude: opus > sonnet > haiku.)
21
+ - **Long runs and the done gate:** a suite over about two minutes runs through the host's background mechanism and is waited on to completion before the unit ends — a foreground run dies at the tool's time-out. Where the project has a done gate (`.geneseed/done-checks.txt`), its checks run unpiped; output piped through `tail` or `grep` does not count.
22
+ - **Dependency installs:** whether a dependency install (`npm ci` or the stack's own) is allowed in a fresh worktree — a new worktree has none.
23
+ - **Host shell limits:** one plain command per call, from the worktree as working directory or with absolute paths (`git -C`, `npm --prefix`), never opening with `cd <worktree> &&`; the isolated host may refuse or ask approval for heredocs, shell variables and compound commands, so prefer plain single commands unless the brief's proof commands need one; a multi-line commit message goes through `git commit -F <file>`, the file written with the edit tools. Paths outside the worktree (a scratch path) may be refused too: scratch files go through the file tools.
24
+ - **One judge per copy:** when a global and a project install both run, a stand-down that lets one copy record for several is safe only for records every copy sees the same way (counts, child runs) — never for a verdict each copy reaches from its own config.
25
+ - **Report delivery:** the unit writes its full final report to a file in its scratch path and replies with the path — long reports were lost in relay.
15
26
  4. Keep the main context lean: collect each subagent's distilled result, not its working transcript. Watch every unit you dispatched in the background as the [pipeline {{SKILL}}](pipeline.md)'s step 2 watches a crew: a result without its check, or one that says it is still waiting, is a failure to act on at once — resume the unit or redo it — never a notification to wait for.
16
27
  5. Converge: compare each unit's changed files against its write set and against its siblings' — an edit outside the set, a file two units touched, or a file in a batch's set that never changed is a conflict you resolve before anything else — apply the shared-file rows yourself, then verify the combined outcome. A conflict or ambiguity between the plan, the findings and the code is yours to decide: decide it, record `Ruling: <choice> — <why> — <cost if wrong>` in the worklog, and continue. Stop only for what {{LAW:echo-the-intent}}, {{LAW:deletion-is-deliberate}} or {{DOCTRINE:consent-before-push}} names; every ruling goes in the final report ({{DOCTRINE:declare-the-judgment-calls}}).
17
28
  6. **A plan with blocking edges.** To build a [plan](plan.md) file's slices — each with its `Blocked by:` line — in one run, dispatch every unblocked slice on its own branch off one integration branch, merge each into it as it returns (each merge is a commit — {{DOCTRINE:consent-before-push}} stays with you), and recompute the unblocked set from the plan after every merge — newly freed slices go out at once. When the plan names a `Spec:`, every slice reads it once; the spec outranks the plan where they conflict. Each slice branches off the integration tip at its own dispatch (its BASE) and merges the current tip back into its branch before returning, so a conflict with a sibling resolves on the slice's branch; before re-running the proof, confirm the branch descends from BASE and the diff is non-empty — an empty diff is a failure, not a clean result. Never diff against `HEAD~1`. When the plan is exhausted, review the integration branch whole with [geneseed-code-review](geneseed-code-review.md) before reporting.
@@ -25,8 +25,8 @@ The minimum roster per task type. The crew lead chooses the crew from the whole
25
25
 
26
26
  ## Procedure
27
27
 
28
- 1. Take the trigger as given: the user's request for a crew, or foreman's judgement that the task needs several specialists. Do not weigh it again and fall back to doing the work yourself.
29
- 2. **Dispatch the crew lead** in the background, using the host's general-purpose {{AGENT}}. Before dispatch, record BASE and set the crew's **write set**; check it against every other pipeline in flight ({{DOCTRINE:one-writer-per-file}}) — two crews whose sets overlap do not run at once. The brief carries: the task as the user stated it, the task type, BASE, the write set, the proof commands, a pointer to this {{SKILL}}, the rule that it commits only in its own worktree, never pushes, and never merges outside its own branch, and the rule that each command runs from the worktree as working directory or with absolute paths (`git -C`, `npm --prefix`), never opening with `cd <worktree> &&`, which makes the host ask the user. Tell the user the pipeline is running, then go back to the user. Do not wait on the crew lead. **Then watch what you dispatched.** An envelope without proof, or one that says the crew is still waiting, is a failure: act on it at once — resume the crew lead (`SendMessage` on Claude Code) or take over its worktree — never wait for a notification it promised. A crew member's report that reaches you directly means its crew lead has already ended; act on it the same way. Set no timer to watch a crew: where the host re-invokes you when a background agent ends (Claude Code), that notification is the watch; check every crew still out at the start of every turn. A crew is stalled when its transcript and output have not grown for 15 minutes **and** it has no live child process: ping it once; if the next check shows no change, stop it, then take over from its worktree. A crew whose output still grows, or that runs a child process, is never taken over — a long suite or canary is not a stall.
28
+ 1. Take the trigger as given: the user's request for a crew, or foreman's judgement that the task needs several specialists. Do not weigh it again and fall back to doing the work yourself. Where you hold no dispatch tool, you are the crew lead: play each role in turn in one tree, and say so.
29
+ 2. **Dispatch the crew lead** in the background, using the host's general-purpose {{AGENT}}. Before dispatch, record BASE and set the crew's **write set**; check it against every other pipeline in flight ({{DOCTRINE:one-writer-per-file}}) — two crews whose sets overlap do not run at once. The brief carries: the task as the user stated it, the task type, BASE, the write set, the proof commands, a pointer to this {{SKILL}}, the rule that it commits only in its own worktree, never pushes, and never merges outside its own branch, and the **Brief checklist** in [parallel-agents](parallel-agents.md). Tell the user the pipeline is running, then go back to the user. Do not wait on the crew lead. **Then watch what you dispatched.** An envelope without proof, or one that says the crew is still waiting, is a failure: act on it at once — resume the crew lead (`SendMessage` on Claude Code, and on OpenClaude in its agent-teams mode; on OpenCode the `subagent` tool with its `sessionID`, V1 `task` with `task_id`) or, where the host has no resume (Bob, OpenClaude without agent teams), take over its worktree — never wait for a notification it promised. A crew member's report that reaches you directly means its crew lead has already ended; act on it the same way. Set no timer to watch a crew: where the host re-invokes you when a background agent ends (Claude Code), that notification is the watch; check every crew still out at the start of every turn. A crew is stalled when its transcript and output have not grown for 15 minutes **and** it has no live child process: ping it once; if the next check shows no change, stop it, then take over from its worktree. A crew whose output still grows, or that runs a child process, is never taken over — a long suite or canary is not a stall.
30
30
  3. **The crew lead composes the crew** from the floor above and adds any {{AGENT}} the task needs. It dispatches each crew member as its own subagent, each handed what the previous one produced. **The crew lead never ends with a member unresolved.** Its last message is its result: once it ends, nothing wakes it, and a member that outlives it reports past it, to the parent. It may run members in parallel, but holds every member's result before it ends — returned, or failed and then redone or named as failed in the envelope. A member that returns nothing has failed. Where the crew lead holds no dispatch tool (see *Hosts* below), it plays each role in turn itself, with the same hand-offs and the same envelope. Steps 4 to 7 are the crew lead's, except where they name the parent.
31
31
  4. Isolate the crew's work in its own git worktree/branch. Where worktrees are unavailable, fall back to a single tree, one pipeline at a time, and say so; without a worktree, the crew never commits. The crew writes only inside its write set; shared append files (registries, index tables, lockfiles, generated bundles) are the parent's to apply, never a crew's.
32
32
  5. **The dev↔tester loop:** the developer implements, the tester validates — runs the tests and lint, produces raw logs. On failure, the findings go back to the developer — two repair rounds at most, then one fresh developer (a higher model tier where the host offers one) carrying the tester's findings ({{DOCTRINE:bound-the-loop}}); if that fails too, stop, do not merge, and report the failure with the branch left in place for inspection. A conflict or ambiguity between the plan, the findings and the code is yours to decide: decide it, record `Ruling: <choice> — <why> — <cost if wrong>` in the worklog, and continue. Stop only for what {{LAW:echo-the-intent}}, {{LAW:deletion-is-deliberate}} or {{DOCTRINE:consent-before-push}} names; every ruling goes in the final report ({{DOCTRINE:declare-the-judgment-calls}}). When the plan names a `Spec:`, the analyst reads it once; the spec outranks the plan.
@@ -40,7 +40,7 @@ The minimum roster per task type. The crew lead chooses the crew from the whole
40
40
  | Claude Code | yes — a subagent started from the main conversation runs in the background by default | yes — the install caps nesting at two layers (`env.CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH = "2"`; Claude Code allows three by default), and a background subagent keeps the `Agent` tool | crew lead → crew subagents. Not the `Workflow` tool: it refuses without the user's opt-in for that task, and the mode is not one |
41
41
  | OpenCode | the `task` tool starts a child session; whether the parent's turn waits is unverified | unverified — `permission.task` decides which subagents an agent may start; the install caps nesting at two (`subagent_depth: 2`) | crew lead → crew subagents where it holds `task`; else roles in turn. A saved `workflow` script (no opt-in needed) may stand in for the crew lead |
42
42
  | OpenClaude | expected as Claude Code (it reads Claude's subagent dialect); unverified | unverified | as Claude Code; else roles in turn |
43
- | Bob | unverified — Bob reads Claude's subagent dialect | unverified | crew lead plays the roles in turn |
43
+ | Bob | unverified on Bob IDE, where `spawn_subagent` exists only in a mode whose groups hold `subagent`; Bob Shell has no subagents (reported by Bob Shell itself, not read in code) | no — a Bob subagent cannot spawn subagents (`spawn_subagent` is forbidden to subagents, Bob IDE 2.2.3), and Bob Shell has none | crew lead plays the roles in turn; where the session cannot start a writing subagent (Bob Shell; `ask` mode, which may start only `explore`), the session is the crew lead and plays them in one tree |
44
44
 
45
45
  Check, do not assume: before the first pipeline of a session on a host marked unverified, look at the tools you and the crew lead actually hold ({{DOCTRINE:tool-discovery}}). When a fact above proves wrong, report it through this {{SKILL}}'s self-improvement loop.
46
46
 
@@ -15,8 +15,9 @@
15
15
  [brainstorm {{SKILL}}](brainstorm.md) first rather than planning blind. Otherwise
16
16
  restate the goal in one line. Either way, confirm the actual starting state before
17
17
  designing the steps ({{LAW:verify-before-asserting}} — verify before designing).
18
- 2. Write a numbered plan to `WORKLOG.md` (or `plans/<task>.md`) in your {{NOTEBOOK}}
19
- (§6) — into the repository only when the user asks. A worker or slice
18
+ 2. Write a numbered plan beside its spec, in the project's spec or plan home (e.g.
19
+ `docs/plans/`) when one exists; else to `WORKLOG.md` (or `plans/<task>.md`) in your
20
+ {{NOTEBOOK}} (§6). A worker or slice
20
21
  in another worktree cannot see the {{NOTEBOOK}}, so its brief carries the plan's path
21
22
  or text. The plan holds ordered steps, each
22
23
  independently checkable. Group the steps into milestones — coherent chunks after
@@ -55,7 +56,7 @@
55
56
 
56
57
  > The worklog is external memory: it lets a context-limited agent recover its
57
58
  > place after the window fills, and lets the user correct course early. The
58
- > {{NOTEBOOK}} is git-ignored; a worklog the user asked for in the repository is
59
- > committed or ignored as they decide.
59
+ > {{NOTEBOOK}} is git-ignored; a plan in the project's own spec or plan home is
60
+ > tracked there like its spec.
60
61
 
61
62
  <!-- INCLUDE: skills/_self-improvement.md -->