geneseed 5.3.1 → 5.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (161) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/README.md +21 -18
  3. package/SHIPPED.md +7 -7
  4. package/adapters/opencode/README.md +3 -2
  5. package/adapters/opencode/plugins/geneseed-context.js +6 -0
  6. package/adapters/opencode/plugins/geneseed-guard.js +5 -3
  7. package/bin/geneseed-cli.mjs +7 -0
  8. package/bin/geneseed-hook.mjs +3 -3
  9. package/docs/PRD.md +1 -1
  10. package/docs/README.md +1 -0
  11. package/docs/concepts/agents.md +1 -1
  12. package/docs/concepts/collaboration.md +2 -2
  13. package/docs/concepts/enforcement-table.md +5 -2
  14. package/docs/concepts/exclusions.md +16 -2
  15. package/docs/concepts/footprint.md +1 -1
  16. package/docs/concepts/foreman-mode.md +1 -1
  17. package/docs/concepts/hook-gates.md +3 -3
  18. package/docs/concepts/hooks.md +4 -3
  19. package/docs/concepts/host-matrix.md +2 -2
  20. package/docs/concepts/kits.md +12 -2
  21. package/docs/concepts/loop-bricks.md +3 -3
  22. package/docs/concepts/loops.md +6 -4
  23. package/docs/concepts/ownership.md +1 -1
  24. package/docs/concepts/rules.md +2 -2
  25. package/docs/concepts/skills.md +1 -1
  26. package/docs/extending.md +63 -28
  27. package/docs/guides/auto-merge.md +100 -0
  28. package/docs/guides/choose-your-setup.md +1 -1
  29. package/docs/guides/headless.md +1 -1
  30. package/docs/guides/install-clone.md +1 -1
  31. package/docs/guides/install.md +1 -1
  32. package/docs/guides/loop-finish.md +3 -3
  33. package/docs/guides/loop-running.md +4 -4
  34. package/docs/guides/project-context.md +1 -1
  35. package/docs/guides/run-a-factory.md +2 -2
  36. package/docs/guides/setup-doctrines.md +2 -2
  37. package/docs/guides/setup-footprint.md +1 -1
  38. package/docs/guides/uninstall.md +3 -3
  39. package/docs/guides/upgrade.md +1 -1
  40. package/docs/guides/worktree.md +1 -1
  41. package/docs/reference/environment.md +4 -2
  42. package/docs/reference/plugin-activity.md +1 -1
  43. package/docs/reference/plugin-guard.md +1 -1
  44. package/docs/reference/plugin-learn.md +1 -1
  45. package/docs/reference/plugin-workflow.md +1 -1
  46. package/docs/reference/troubleshoot-doctor.md +1 -1
  47. package/docs/reference/troubleshoot-hooks.md +2 -2
  48. package/docs/reference/troubleshoot-install.md +3 -3
  49. package/docs/reference/troubleshoot-tools.md +1 -1
  50. package/docs/token-footprint.md +2 -2
  51. package/docs/understand/enforced-vs-asked.md +1 -1
  52. package/docs/understand/machine-claude.md +2 -2
  53. package/docs/understand/on-your-machine.md +1 -1
  54. package/docs/web-ui.md +5 -5
  55. package/harness.config.json +1 -1
  56. package/js/README.md +2 -1
  57. package/js/build/args.mjs +12 -1
  58. package/js/build/driver.mjs +33 -6
  59. package/js/build/emit-claude.mjs +8 -4
  60. package/js/build/emit-opencode.mjs +13 -9
  61. package/js/build/generate.mjs +10 -156
  62. package/js/build/profile.mjs +318 -0
  63. package/js/build/render.mjs +81 -3
  64. package/js/build/retired-skills.mjs +60 -13
  65. package/js/build/source.mjs +15 -1
  66. package/js/build/stubs.mjs +4 -1
  67. package/js/cli-table.json +48 -3
  68. package/js/hosts/hooks-done.mjs +345 -55
  69. package/js/hosts/hooks-learn.mjs +4 -3
  70. package/js/hosts/hooks-prims.mjs +5 -3
  71. package/js/hosts/hooks.mjs +153 -6
  72. package/js/hosts/installs.mjs +19 -1
  73. package/js/hosts/native.mjs +19 -2
  74. package/js/hosts/settings.mjs +29 -3
  75. package/js/inspect/checks-constitution.mjs +32 -0
  76. package/js/inspect/diff.mjs +21 -3
  77. package/js/inspect/inventory.mjs +1 -1
  78. package/js/maintain/setup.mjs +5 -1
  79. package/js/maintain/update.mjs +4 -2
  80. package/js/web/actions.mjs +16 -3
  81. package/js/web/api.mjs +7 -2
  82. package/package.json +1 -1
  83. package/registry.json +14 -0
  84. package/src/AGENT.md.tmpl +15 -17
  85. package/src/bricks/pr-open.md +3 -2
  86. package/src/doctrines/ops.md +2 -2
  87. package/src/doctrines/process.md +40 -36
  88. package/src/factories/analysis-to-build.json +1 -1
  89. package/src/factories/bug-report-to-fix.json +1 -1
  90. package/src/factories/issue-to-pr.json +1 -1
  91. package/src/kits/terminal-tools/rules.md +10 -0
  92. package/src/kits/terminal-tools.json +13 -0
  93. package/src/licenses/herdr.txt +201 -0
  94. package/src/modes/foreman.md +6 -3
  95. package/src/skills/_self-improvement.md +9 -7
  96. package/src/skills/commit.md +17 -17
  97. package/src/skills/debug/ci.md +1 -1
  98. package/src/skills/dependencies.md +3 -3
  99. package/src/skills/document-project.md +3 -2
  100. package/src/skills/factory.md +13 -4
  101. package/src/skills/geneseed.md +4 -2
  102. package/src/skills/git-history.md +5 -7
  103. package/src/skills/herdr.md +135 -0
  104. package/src/skills/loop.md +3 -2
  105. package/src/skills/opencode-cli.md +84 -0
  106. package/src/skills/pipeline.md +1 -1
  107. package/src/skills/release.md +5 -8
  108. package/src/skills/review-response.md +4 -2
  109. package/src/skills/rule.md +27 -1
  110. package/src/skills/ship.md +54 -7
  111. package/src/skills/worktree.md +2 -2
  112. package/src/upstreams.json +7 -0
  113. package/themes/_TEMPLATE.json +2 -0
  114. package/themes/biker.json +2 -0
  115. package/themes/commentator.json +2 -0
  116. package/themes/cyberpunk.json +2 -0
  117. package/themes/gamer.json +2 -0
  118. package/themes/imperial.json +2 -0
  119. package/themes/joker.json +2 -0
  120. package/themes/marvin.json +2 -0
  121. package/themes/mean.json +2 -0
  122. package/themes/military.json +2 -0
  123. package/themes/neutral.json +2 -0
  124. package/themes/pirate.json +2 -0
  125. package/themes/sports.json +2 -0
  126. package/themes/verstappen.json +2 -0
  127. package/themes/wizard.json +2 -0
  128. package/web/dist/assets/Activity-D2kOc3yi.js +1 -0
  129. package/web/dist/assets/ActivityDetail-By3xOr21.js +1 -0
  130. package/web/dist/assets/{Bonsai-BBl4XXqs.js → Bonsai-CBWDTBA4.js} +1 -1
  131. package/web/dist/assets/{CopyButton-Beven8yn.js → CopyButton-BVbpriMB.js} +1 -1
  132. package/web/dist/assets/Dashboard-CIJLPHM9.js +2 -0
  133. package/web/dist/assets/Docs-CiRRIELs.js +5 -0
  134. package/web/dist/assets/Factories-DhyK0O8d.js +1 -0
  135. package/web/dist/assets/{GreenhouseView-Bce212qd.js → GreenhouseView-DW3PgTPy.js} +1 -1
  136. package/web/dist/assets/Installs-B6nlo-Ly.js +3 -0
  137. package/web/dist/assets/{JournalView-CV4omyww.js → JournalView-O65qEWfp.js} +1 -1
  138. package/web/dist/assets/Kits-C5U-yT6Z.js +1 -0
  139. package/web/dist/assets/Laws-CuTw_XNf.js +4 -0
  140. package/web/dist/assets/{LibRows-Dag1s0ZX.js → LibRows-D6-CVa3K.js} +1 -1
  141. package/web/dist/assets/Library-CzPlerd6.js +3 -0
  142. package/web/dist/assets/Loops-CqNF_-nS.js +2 -0
  143. package/web/dist/assets/{OperatorHudView-JmYY1pBR.js → OperatorHudView-BNr8K5qj.js} +1 -1
  144. package/web/dist/assets/Personal-DeDb9e8O.js +2 -0
  145. package/web/dist/assets/Settings-B8MPN_AD.js +1 -0
  146. package/web/dist/assets/{Tabs-8zsyEPSK.js → Tabs-DJzAez4h.js} +1 -1
  147. package/web/dist/assets/index-BL3P-9Rg.js +6 -0
  148. package/web/dist/index.html +1 -1
  149. package/web/dist/assets/Activity-WQ3ykgxU.js +0 -1
  150. package/web/dist/assets/ActivityDetail-7rt04SkS.js +0 -1
  151. package/web/dist/assets/Dashboard-BgLArtgu.js +0 -2
  152. package/web/dist/assets/Docs-B5aHp86J.js +0 -5
  153. package/web/dist/assets/Factories-BjqzXAw8.js +0 -1
  154. package/web/dist/assets/Installs-B1OsrHXF.js +0 -3
  155. package/web/dist/assets/Kits-CW1e7xNa.js +0 -1
  156. package/web/dist/assets/Laws-1Ckf1lbs.js +0 -4
  157. package/web/dist/assets/Library-B3FuFLel.js +0 -3
  158. package/web/dist/assets/Loops-CwqgnLNw.js +0 -2
  159. package/web/dist/assets/Personal-DKLgLa7Z.js +0 -2
  160. package/web/dist/assets/Settings-BwErnh-R.js +0 -1
  161. package/web/dist/assets/index-Ce6qF2nG.js +0 -6
@@ -112,8 +112,9 @@ write; with none, step 5 proposes them.
112
112
  sizes and weights; spacing, radius and shadow on sample squares; components as cards
113
113
  (variants, states, path) — no live rendering, which would need the project's framework; and
114
114
  the hard-coded-value drift in a separate callout.
115
- 10. **Do not auto-publish.** Leave the changes for the user to review; stage and commit only
116
- on consent, via the [commit {{SKILL}}](commit.md) ({{DOCTRINE:consent-before-push}}).
115
+ 10. **Do not auto-publish.** Commit on your own branch via the [commit {{SKILL}}](commit.md)
116
+ and leave the change for the user to review before it reaches the main branch
117
+ ({{DOCTRINE:consent-before-push}}).
117
118
 
118
119
  ## The doc set
119
120
 
@@ -11,8 +11,8 @@ or asks to carry an issue, request or document to a PR with green CI.
11
11
  brick or a whole loop; the engine decides every transition, cycle count and stop, and you run the
12
12
  stage it hands you and report the outcome. Every action prints one JSON object: act on its keys,
13
13
  never on your own reading of the graph. The run ends at an open PR with green CI. **No stage
14
- merges:** once the run has closed, you ask the user once whether to merge (*The end*), and never
15
- enable auto-merge.
14
+ merges:** once the run has closed, you ask the user once whether to merge (*The end*), and enable
15
+ auto-merge only as the user's standing auto-merge rule allows.
16
16
 
17
17
  **Holdout rule.** The `holdout-write` stage writes scenarios the developer never sees, and the
18
18
  `holdout` stage plays them before the PR. Both run as the `tester` {{AGENT}}, never as the
@@ -180,12 +180,21 @@ in it makes the gate ask. On a record line that ask is a false alarm: the user c
180
180
  final state (green, red with the failing checks, or still pending at the bound) to the run
181
181
  report. With no close commit, CI did not re-run: the final state is the one `merge-gate`
182
182
  read. A red result is reported, never reworked: the run has closed.
183
- **The merge proposal.** Only when that final state is green: show the user the PR URL, the CI
183
+ **The merge proposal** (no standing auto-merge rule, or the rule does not arm this PR). Only
184
+ when that final state is green: show the user the PR URL, the CI
184
185
  state and each `review-panel` seat's verdict, and ask once whether to merge. Only on the
185
186
  user's explicit yes in chat: `gh pr merge <pr> --squash` (`glab mr merge <mr> --squash` on
186
187
  GitLab). No Geneseed gate asks before that command: the user's yes is the only guard, so
187
188
  never run it on anything else (not on a rule, a note, or an earlier yes). On a no, or no
188
- answer, the PR stays open. Red or pending CI: no proposal. Never enable auto-merge.
189
+ answer, the PR stays open. Red or pending CI: no proposal.
190
+ **Auto-merge** (a separate path, in place of the proposal). Only when the user's standing rule
191
+ *Auto-merge green PRs* allows it, with the same tiers and forge probes as the
192
+ [ship {{SKILL}}](ship.md)'s auto-merge step, arm it on the final head: `gh pr merge <pr> --auto
193
+ --squash --match-head-commit <sha>` (`glab mr merge <mr> --auto-merge --squash --sha <sha>`).
194
+ For the `reviewer` tier, the `review-panel` verdict is the reviewer pass: add it to the PR
195
+ body before arming. The final head is often green already, so `--auto` then merges at once:
196
+ the standing rule is the authorization for that merge, never for the direct `--squash`
197
+ command above. With no rule, or when a tier or probe does not allow it, the proposal applies.
189
198
  9. On `$stop`: the engine hands out no stage after a stop, so have the `docs` {{AGENT}} write the
190
199
  run report the `retro` brick would: the stop `reason` first, then the work item, the PR URL if
191
200
  any, every stage with its outcome and each rework with its reason, read from `FACTORY.md` and
@@ -3,13 +3,15 @@
3
3
  > {{DESC_GENESEED}}
4
4
  <!-- aliases: opencode-theme -->
5
5
 
6
- **Trigger:** the user mentions Geneseed, the harness, or `AGENT.md`; asks how the install is set up; asks to change its theme, footprint, posture, mode, doctrine packs or excluded rules; asks for their own OpenCode colour theme or to tweak the shipped colours ("make me a theme", "a theme that matches my brand", "a darker/transparent version of this theme") — or you need to know what {{LAWS}}, {{AGENTS}}, or {{SKILLS}} this install carries.
6
+ **Trigger:** the user mentions Geneseed, the harness, or `AGENT.md`, or asks to reinstall, update, upgrade, repair or re-run its install; asks how the install is set up; asks to change its theme, footprint, posture, mode, doctrine packs or excluded rules; asks for their own OpenCode colour theme or to tweak the shipped colours ("make me a theme", "a theme that matches my brand", "a darker/transparent version of this theme") — or you need to know what {{LAWS}}, {{AGENTS}}, or {{SKILLS}} this install carries.
7
+
8
+ **Reinstall = rebuild the same install.** Start from that install's `rebuild` command in `geneseed status --json` and change only the flag the user named. Never run a bare `geneseed build`: each omitted flag returns its setting to the default. A build that would do that refuses (`refused: this build would change settings…`) and prints the command that keeps them: run that command. Add `--reset` only when the user asked to return the settings to their defaults. Updating Geneseed itself is `geneseed upgrade`, which keeps every install's settings.
7
9
 
8
10
  ## Procedure
9
11
  1. **Locate.** Run `geneseed status --json` first: `installs` lists every install on this machine — host, scope, root, state, theme, footprint, posture, mode, packs, excluded rules — and `rebuild`, the command that reproduces each one exactly. `geneseed` not on PATH → ask the user before using `npx geneseed` (it downloads the package), and prefix every command below the same way. Still nothing → look for a host root file: `~/.config/opencode/AGENT.md` or `.opencode/AGENT.md` (OpenCode), `~/.claude/CLAUDE.md` or `.claude/` (Claude Code), `.openclaude/` (OpenClaude), `AGENTS.md` beside `.bob/` (Bob). None → say so; never install to "fix" it.
10
12
  2. **Read state** with the read-only verbs, cheapest first ({{DOCTRINE:context-economy}}): `geneseed status --json`, `geneseed version`, `geneseed catalog` (optionally `agents|skills|laws|ontology|doctrines`), `geneseed doctor`, `geneseed diff`, `geneseed mcp`, `geneseed memory list`, `geneseed memory consolidate` (rebuilds only the generated index, from the fact files), `geneseed exclude list`.
11
13
  3. **Read a piece** from disk, not from recall ({{LAW:verify-before-asserting}}): `<root>/agents/<name>.md`, `<root>/skills/<name>/SKILL.md`, `<root>/memory/`, `<root>/notebook/`. The {{ONTOLOGY}}, the {{LAWS}} and the active {{DOCTRINES}} are numbered `## N. …` sections of the install's root file.
12
- 4. **Change an install only when the user asked for that change** ({{LAW:one-intent-one-act}}). Take that install's `rebuild` command from step 1, edit only the flag the user named (add it if the command omits it — `--posture`, `--mode` and `--trust` are left out at their defaults) — `--theme`, `--footprint lean|full`, `--posture`, `--mode direct|foreman`, `--trust prudent|balanced|aggressive`, `--doctrines craft,rigor|none`, `--exclude-rules "process 7"|none` — dry-run it first by running the same flags through `geneseed validate`, show the command, and run it once the user agrees. Never rebuild from a bare `geneseed build`: every omitted flag resets that setting to the generator default. Confirm with `geneseed status`.
14
+ 4. **Change an install only when the user asked for that change** ({{LAW:one-intent-one-act}}). Take that install's `rebuild` command from step 1, edit only the flag the user named (add it if the command omits it — `--posture`, `--mode` and `--trust` are left out at their defaults) — `--theme`, `--footprint lean|full`, `--posture`, `--mode direct|foreman`, `--trust prudent|balanced|aggressive`, `--doctrines craft,rigor|none`, `--exclude-rules "process 7"|none` — dry-run it first by running the same flags through `geneseed validate`, show the command, and run it once the user agrees. Confirm with `geneseed status`.
13
15
  5. **Other writes also need the user's word:** `geneseed memory rm <name>` (archives; `--purge` deletes for good), `geneseed exclude add|remove <path>`, `geneseed web start|stop`, `geneseed uninstall --target <root> --yes`. Personal rules and the profile belong to their own {{SKILLS}}; do not edit `user-rules.md` or `PROFILE.md` from here.
14
16
  6. **Never on your own initiative:** `geneseed setup` (interactive only), `geneseed upgrade`, `geneseed update`, `geneseed upgrade --setup`, `geneseed rebuild-all`, `geneseed migrate`, `geneseed link`, `geneseed unlink`. `learn`, `context` and the `*-gate` verbs are `geneseed-hook` verbs the host's hooks run — never run them by hand.
15
17
  7. Directory and section names are plain English in every theme; only prose changes. Do not search by flavour words.
@@ -60,15 +60,13 @@ never changes history; Part B does. To write a new commit, use the
60
60
  you were asked to resolve. Before concluding, run the project's checks (typecheck,
61
61
  tests, format) and fix what the merge broke.
62
62
  5. **Deliberate rewrite** (interactive rebase, squash, fixup, amend): on a dedicated
63
- branch, never a shared one, as the only change in flight ({{LAW:one-intent-one-act}}). A
64
- rewrite *creates commits*, so present what will change and get the user's
65
- acceptance first, as for any commit ({{DOCTRINE:consent-before-push}}).
63
+ branch, never the main branch, as the only change in flight ({{LAW:one-intent-one-act}}).
64
+ Present what will change first ({{DOCTRINE:consent-before-push}}).
66
65
  6. Verify against `git log --oneline`, `git status` and the diff to the intended state
67
66
  — read the output, do not assume the rewrite landed ({{LAW:verify-before-asserting}}).
68
- 7. Push only with the user's explicit per-push consent. A rewrite needs a
69
- `--force-with-lease` push, doubly outward-facing: present what changed and wait for
70
- acceptance ({{DOCTRINE:consent-before-push}} / {{LAW:deletion-is-deliberate}}). Never force-push a shared
71
- branch without confirming it is safe.
67
+ 7. A rewrite needs a `--force-with-lease` push, and a forced push asks: present what
68
+ changed and wait for acceptance ({{DOCTRINE:consent-before-push}} / {{LAW:deletion-is-deliberate}}).
69
+ Never force-push the main branch.
72
70
 
73
71
  ## Done when
74
72
  - **Part A:** the question is answered with specific commit(s) and the output that
@@ -0,0 +1,135 @@
1
+ # {{SKILL}}: herdr
2
+
3
+ > {{DESC_HERDR}}
4
+
5
+ {{CREDIT:herdr:skills/herdr/SKILL.md}}
6
+
7
+ **Trigger:** the user explicitly mentions Herdr, or asks to use Herdr to inspect or control panes, tabs, workspaces, commands or another agent. Do not use it only because a task could benefit from a background terminal, delegation or parallel work. Requires `HERDR_ENV=1`.
8
+
9
+ Herdr organizes terminals into workspaces, tabs and panes, recognizes coding agents running inside panes, and exposes the current session through the `herdr` CLI.
10
+
11
+ ## Gate: are you inside Herdr?
12
+
13
+ Before any control command, verify that this agent runs inside a Herdr-managed pane:
14
+
15
+ ```bash
16
+ test "${HERDR_ENV:-}" = 1
17
+ ```
18
+
19
+ On native Windows (PowerShell): `$env:HERDR_ENV -eq '1'`. Herdr's v0.9.5 "Windows support" docs page says native Windows support is generally available, with some capabilities that differ from Linux and macOS. The same page lists "Signed binary / SmartScreen avoidance" as unsupported, so SmartScreen may warn. The v0.9.5 release ships `herdr-windows-x86_64.zip` as its only Windows asset.
20
+
21
+ If the check fails, say that you are not running inside Herdr and stop. Do not inspect or control the focused Herdr session from outside Herdr. When the check passes, the `herdr` binary on `PATH` talks to the current session.
22
+
23
+ ## Learn the current CLI
24
+
25
+ The installed binary is the authority for command syntax. Start with `herdr --help`, then print a command group by running it without a subcommand: `herdr agent`, `herdr pane`, `herdr workspace`, `herdr tab`, `herdr worktree`, `herdr terminal`, `herdr notification`, `herdr integration`, `herdr session`, `herdr machine`.
26
+
27
+ - Do not run bare `herdr` for discovery: it launches or attaches the TUI.
28
+ - Do not probe a mutating nested command by omitting arguments. Commands such as `herdr workspace create` are valid with defaults and will execute.
29
+ - Most control commands return JSON. Read identifiers and state from those responses instead of predicting them.
30
+
31
+ ## Layout, panes and agents
32
+
33
+ - Workspace, tab and pane topology organize terminal locations.
34
+ - Pane commands control raw terminals, shells, tests, servers, input and output.
35
+ - Agent commands control the recognized coding agent that occupies a pane.
36
+
37
+ A pane exists whether or not it holds an agent. `agent start` requires an existing available shell pane and never creates, splits or moves layout. Use pane commands for ordinary processes; use agent commands when Herdr must validate agent identity or interpret the `idle`, `working`, `blocked`, `done` and `unknown` states.
38
+
39
+ Agent commands accept a unique live agent name or the pane ID that hosts that agent, never a terminal ID or a bare agent-kind label. Names match `[a-z][a-z0-9_-]{0,31}` and are unique among live agents. A name follows the current pane occupant and is cleared when that agent exits, is released or is replaced. A retained identity (Ctrl+Z, then a non-agent command) does not mean the agent is in the foreground: inspect the pane before you send input.
40
+
41
+ - `idle` and `done` normally mean ready for input, but neither proves an unfamiliar approval dialog was recognized. Antigravity and Grok can be idle while background tasks keep running.
42
+ - `blocked` means Herdr recognized an approval or question UI.
43
+ - `unknown` means an agent is present but Herdr cannot classify it; it does not prove completion.
44
+ - The CLI and each TUI client track seen state apart, so a Done badge can differ between them.
45
+
46
+ ## IDs and caller context
47
+
48
+ Public IDs are opaque stable handles: workspace `w1`, tab `w1:t1`, pane `w1:p1`. Closed tab and pane IDs are not reused. A pane moved into another workspace gets a new ID: after `pane move`, continue with `.result.move_result.pane.pane_id` or the live agent name.
49
+
50
+ Herdr injects the caller's context into each managed pane: `$HERDR_WORKSPACE_ID`, `$HERDR_TAB_ID`, `$HERDR_PANE_ID`. Prefer `--current` when a pane command should target the calling pane. Other commands may use the UI-focused pane, which can belong to the user or another client.
51
+
52
+ Discover live state:
53
+
54
+ ```bash
55
+ herdr workspace list
56
+ herdr tab list --workspace "$HERDR_WORKSPACE_ID"
57
+ herdr pane current --current
58
+ herdr pane list --workspace "$HERDR_WORKSPACE_ID"
59
+ herdr agent list
60
+ ```
61
+
62
+ Creation responses expose the next IDs: `workspace create` returns `.result.workspace`, `.result.tab` and `.result.root_pane`; `tab create` returns `.result.tab` and `.result.root_pane`; `pane split` returns `.result.pane`.
63
+
64
+ ### Saved SSH machines
65
+
66
+ IDs and agent names are scoped to one server. Selecting a machine in the TUI does not retarget your pane's commands. To control a saved machine, put the same prefix on discovery and every later command:
67
+
68
+ ```bash
69
+ herdr --machine <label-or-id> agent list
70
+ herdr --machine <label-or-id> agent prompt <remote-agent-name> "Reply with your current status." --wait --timeout 120000
71
+ ```
72
+
73
+ - The selector is an enabled saved profile ID or a unique, case-sensitive label, never an arbitrary hostname. Do not combine `--machine` with `--session` or `--remote`. Local IDs and `--current` do not identify remote panes.
74
+ - Forwarding never installs, starts or restarts a server. A connection failure does not prove a mutation was not applied: inspect remote state before you retry.
75
+ - `herdr machine list` lists saved profiles (`--json` for scripts); `herdr machine status [<label-or-id>] --json` diagnoses one. Add, remove, enable or disable profiles only when the user asks.
76
+ - `herdr machine reconnect` needs the user to complete SSH authentication; do not run it for them. Never approve replacing an incompatible server without the user's consent.
77
+
78
+ ## Start and coordinate an agent
79
+
80
+ Default to a sibling pane in the current tab and working directory. Do not create a workspace, tab, worktree or other cwd unless the user asks for it. Honor a direction the user names; otherwise read `herdr pane layout --pane "$HERDR_PANE_ID"` and split a wide pane right, a narrow or tall one down:
81
+
82
+ ```bash
83
+ herdr pane split --current --direction right --cwd "$PWD" --no-focus
84
+ ```
85
+
86
+ Read the new pane ID from `.result.pane.pane_id`. The pane must sit at its interactive shell prompt, with nothing in the foreground. Start the agent kind the user asked for (`herdr agent` lists the installed kinds), with a unique name; native agent arguments go after `--`:
87
+
88
+ ```bash
89
+ herdr agent start reviewer --kind codex --pane <returned-pane-id> [-- <agent-args...>]
90
+ ```
91
+
92
+ `agent start` returns once Herdr detects the agent ready for input (30 s default timeout). If the agent is blocked during startup it returns `agent_not_ready` but keeps the name for `agent read` and `agent send-keys`; wait until it is idle before you prompt it.
93
+
94
+ ```bash
95
+ herdr agent prompt reviewer "Review the current diff and report only actionable findings." --wait --timeout 120000
96
+ ```
97
+
98
+ - `agent prompt` rejects an agent already at an approval or question dialog with `agent_blocked` before it sends any input. Inspect the blocked UI and ask the user before you answer it.
99
+ - `--wait` waits for the first settled `idle`, `done` or `blocked` state; do not repeat those defaults with `--until`. From a non-working state it must see `working` or `blocked` within five seconds, or it returns `agent_prompt_stalled`. The timeout includes submission time; without one the wait is indefinite.
100
+ - Use `--until` only for a state-specific wait: `herdr agent wait reviewer --until blocked --timeout 120000`.
101
+ - Logical keys for agent UI controls: `herdr agent send-keys reviewer esc`, `... ctrl+c`. Herdr validates all keys before it writes any byte.
102
+ - Read results: `herdr agent get reviewer`, `herdr agent read reviewer --source recent-unwrapped --lines 120`.
103
+
104
+ If a wait fails or returns `blocked`, inspect `agent get` and `agent read` before you send anything. A timeout or stall does not prove the prompt was not delivered: never resubmit it blindly.
105
+
106
+ ## Run an ordinary command in another pane
107
+
108
+ Split a sibling pane as above, then:
109
+
110
+ ```bash
111
+ herdr pane run <returned-pane-id> "just test"
112
+ herdr pane wait-output <returned-pane-id> --match "test result" --timeout 120000
113
+ herdr pane read <returned-pane-id> --source recent-unwrapped --lines 120
114
+ ```
115
+
116
+ - `pane run` queues the text and Enter together; success acknowledges admission, not execution. On macOS it rejects a line longer than the terminal's input limit: wait for the prompt before you retry.
117
+ - `pane wait-output` also matches output that already exists. `--match <text>` is a literal substring, `--regex <pattern>` a Rust regex. No `--timeout` means an indefinite wait.
118
+ - Read sources: `visible` (viewport), `recent` (with soft wraps), `recent-unwrapped` (wraps joined; prefer it for logs), `detection` (the agent-detection buffer). `--format ansi` only when colour is evidence.
119
+ - If a larger read still misses a finished response, ask the agent to write it as Markdown in a temporary directory and reply with the path, then read that file. Fallback only.
120
+
121
+ ## Safety and coordination
122
+
123
+ - `--no-focus` for background work unless the user asked to switch context.
124
+ - Target with `--current`, an explicit pane ID or a unique agent name, never another client's focused pane. Parse IDs from JSON, never from sidebar order or examples.
125
+ - Do not close workspaces, tabs, panes or sessions you did not create unless the user asked. CLI closes skip the TUI's last-pane confirmation. Never add `workspace close --group` only to get past `workspace_group_close_required`.
126
+ - `--trust-repository` only after the user has verified the repository; it is not a retry for a failed worktree command.
127
+ - Client and server versions can differ after an update: check `herdr status` before you rely on a new server feature. A missing method is not permission to stop or upgrade a server.
128
+ - Never run `herdr server stop` from an active session unless the user means to stop the server and its pane processes. Never kill the main Herdr process; use a named test session for experiments.
129
+ - Server errors are JSON on stderr with exit status 1; CLI syntax errors exit 2.
130
+
131
+ ## Done when
132
+
133
+ - Every pane, tab or agent you created for the task is closed or handed to the user by name, and the user's own layout is as you found it.
134
+
135
+ <!-- INCLUDE: skills/_self-improvement.md -->
@@ -24,8 +24,9 @@ action prints one JSON object — act on its keys, never on your own reading of
24
24
  1. `git worktree add ../<repo>-loop-<slug> -b loop/<slug>`, then make that worktree the session's
25
25
  working directory with its own command. Every later command runs there **as written below**:
26
26
  no `cd` prefix, no `git -C`, no quoted refspec — any of those makes the git gate ask.
27
- 2. On a `loop/*` branch with a launched loop, the git gate lets exactly the commit form below
28
- through without asking. Merging into a shared branch is never yours.
27
+ 2. A `loop/*` branch is your own: the git gate lets its commits and plain pushes through
28
+ without asking (under strict consent, exactly the commit form below, on a launched loop).
29
+ Merging into the main branch is never yours.
29
30
 
30
31
  ## Compose
31
32
 
@@ -0,0 +1,84 @@
1
+ # {{SKILL}}: opencode-cli
2
+
3
+ > {{DESC_OPENCODE_CLI}}
4
+
5
+ **Trigger:** you drive OpenCode V2 from another session or a script through its `opencode` CLI: a headless run, its sessions, the background service or a server, MCP servers, plugins, models, usage stats, or debug output. Not for work inside an OpenCode session itself.
6
+
7
+ **Targets OpenCode V2 only.** Gate first: `opencode --version` must print `2.x`; on 1.x, say so and stop. The V1 commands top-level `export`/`import`, `attach`, `agent create` and `mcp debug` are not in the V2 command table: use `session export|import` instead of the first two. The installed `opencode --help` (and `opencode <command> --help`) is the live authority. General references: https://opencode.ai/docs/cli/ and https://opencode.ai/docs/migrate-v1/.
8
+
9
+ ## Servers: service, standalone, explicit
10
+
11
+ By default the CLI finds or starts one shared **background service** per user account. Two global flags change that on the commands that take them (the root TUI `opencode`, `run`, `mini`, `session`, `auth`, `models`, `stats`, `mcp list|auth|logout`, `plugin list|check|update`, `debug config|agents`, `api`, `reload`; `debug heap-dump` takes `--server` only):
12
+
13
+ - `--standalone`: a private server for this one command, gone when it exits.
14
+ - `--server <url>`: an existing server, for example one from `opencode serve`.
15
+
16
+ `run` uses the service only when it is already up, and never leaves a new one running. The others (`session`, `models`, `stats` and `mcp` among them) **start the service** when it is down. To leave no trace, check `opencode service status` first and pass `--standalone` when the service was not running.
17
+
18
+ | Command | Use |
19
+ |---|---|
20
+ | `opencode service status` | Read whether the background service runs |
21
+ | `opencode service start` | Start it, only when the task needs a lasting service |
22
+ | `opencode service get disabled\|remote\|hostname\|port\|cors` | Read one non-secret service setting |
23
+ | `opencode service stop\|restart\|set\|unset` | The user's service and settings: only on the user's ask |
24
+ | `opencode service get password`, `get env [name]`, bare `get` | **Never**: they print the server password or the service environment, which can hold provider keys (bare `get` prints `env` too) |
25
+ | `opencode serve [--hostname H] [--port N] [--cors <origin>]` | A foreground V2 API and web server; stop it yourself when done |
26
+ | `opencode pair [--url <url>]` | One-time links for a browser or app. `--remote` exposes the server to the internet: only on the user's ask, and never add `--yes` for them |
27
+
28
+ The server password comes from `OPENCODE_PASSWORD` (V1's `OPENCODE_SERVER_PASSWORD` still works). It is the user's secret: never print it or write it to a file.
29
+
30
+ ## Headless run
31
+
32
+ ```bash
33
+ opencode run --format json --title "review" "Review the diff in this repo and list findings"
34
+ ```
35
+
36
+ | Flag | Effect |
37
+ |---|---|
38
+ | `[message..]` | The prompt; stdin is read too (in full when no message is given, as extra context when one is) |
39
+ | `--format default\|json` | `json`: one JSON object per line, each with `type`, `timestamp`, `sessionID`. Types: `text`, `reasoning` (with `--thinking`), `tool_use`, `step_start`, `step_finish`, `retry`, `background_wait`, `error` |
40
+ | `-m, --model provider/model[#variant]` | Model; list them with `opencode models` |
41
+ | `--agent <name>` | Agent; list them with `opencode debug agents` |
42
+ | `-c, --continue` / `-s, --session <id>` | Continue the last session / a given one (created when it does not exist) |
43
+ | `--fork` | Fork before continuing; needs `--continue` or `--session` |
44
+ | `-w, --worktree [name]` | New session in a new git worktree; not with `--continue` or `--session` |
45
+ | `-f, --file <path>` | Attach a file (repeatable) |
46
+ | `--title <t>`, `--archived` | Session title; `--archived` keeps a scripted run out of session lists |
47
+ | `--auto` | Approve every permission not explicitly denied |
48
+
49
+ - Without `--auto`, a headless run **rejects** each permission request and the model continues without that action. Pass `--auto` only on the user's explicit ask; never the hidden `--yolo` or `--dangerously-skip-permissions`.
50
+ - An error sets exit code 1 (with `--format json`, an `error` line). Read the `sessionID` from the output to continue or clean up.
51
+
52
+ ## Sessions
53
+
54
+ | Command | Use |
55
+ |---|---|
56
+ | `opencode session list [-n N] [--format table\|json]` | Top-level sessions of the current project, newest first |
57
+ | `opencode session export <id> [--sanitize]` | Session data as JSON on stdout; `--sanitize` redacts transcript and file data. Pass the ID: without a terminal it is required |
58
+ | `opencode session import <file\|url> [--directory D]` | Import exported session data |
59
+ | `opencode session delete <id>` | Deletes the session **and its child sessions**: only sessions you created, or on the user's ask |
60
+
61
+ ## MCP, plugins, models, stats, debug
62
+
63
+ | Command | Use |
64
+ |---|---|
65
+ | `opencode mcp list` | Configured MCP servers and their status |
66
+ | `opencode mcp add <name> [--url U] [--header k=v] [--env k=v] [--global] [-- <command...>]` | Writes the project config (or global with `--global`): a config change, on the user's ask |
67
+ | `opencode mcp auth [name]` / `opencode mcp logout <name>` | OAuth for a remote MCP server: the user completes it |
68
+ | `opencode plugin list [--builtin]` / `opencode plugin check [target]` | Read-only plugin state and available updates |
69
+ | `opencode plugin add <pkg>` / `update [target]` / `remove <pkg>` | Install, update or remove plugins (`add` and `remove` edit the global config): on the user's ask |
70
+ | `opencode models` | Available models |
71
+ | `opencode stats [--days N\|--year Y\|--all] [--project .] [--models] [--tools] [--cost] [--json]` | Usage statistics |
72
+ | `opencode debug config` / `debug agents` / `debug paths [name]` | Config sources, agents, and paths (`db`, `config`, `log`, ...) |
73
+
74
+ ## Credentials are the user's
75
+
76
+ `opencode auth login`, `auth logout` and `auth switch` are the user's to run in their own terminal: never run them, answer their prompts, or pass `--answer` values. Never run `opencode auth export` (it prints stored secrets) or `auth import`.
77
+
78
+ ## Done when
79
+
80
+ - The run's output was read from its JSON or text, a server you started with `serve` or `--standalone` is stopped, a service you started is named to the user, and every session you created for a throwaway run is deleted or handed over by ID.
81
+
82
+ Verified against the V2 CLI source of anomalyco/opencode at v2.3.0, commit `a6b15d33daf6ab7d35569f6d711fdb630b9f04e7`: `packages/cli/src/commands/commands.ts` (commands and flags), `commands/handlers/` (which commands start the service), `run/` (JSON events, permissions, stdin), `env.ts` (password variables); `--version` and `--help` are built into its `effect/cli` runner.
83
+
84
+ <!-- INCLUDE: skills/_self-improvement.md -->
@@ -26,7 +26,7 @@ The minimum roster per task type. The crew lead chooses the crew from the whole
26
26
  ## Procedure
27
27
 
28
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}}, and the rule that it commits only in its own worktree, never pushes, and never merges outside its own branch. 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.
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.
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.
@@ -15,15 +15,12 @@
15
15
  3. Update the changelog: a dated section for the new version summarising the
16
16
  user-visible changes, grouped (added / changed / fixed), derived from the commits
17
17
  since the last tag.
18
- 4. Commit the version bump and changelog as one focused commit, through the
19
- [commit {{SKILL}}](commit.md) — summary and exact message presented for
20
- acceptance ({{LAW:one-intent-one-act}}, {{DOCTRINE:consent-before-push}}).
18
+ 4. Commit the version bump and changelog as one focused commit on a release branch,
19
+ through the [commit {{SKILL}}](commit.md) ({{LAW:one-intent-one-act}}), and land it on
20
+ the main branch through a pull request with green checks ({{DOCTRINE:consent-before-push}}).
21
21
  5. Tag the release (annotated, matching the version). Tagging and publishing are
22
- **outward-facing** ({{LAW:deletion-is-deliberate}}), and the push itself needs explicit
23
- per-push acceptance — a release lands on a shared branch, where {{DOCTRINE:consent-before-push}}
24
- applies with extra care and grants no standing consent.
25
- 6. With that acceptance, push the commit and the tag together; trigger or verify
26
- the publish/release pipeline.
22
+ **outward-facing** and need the user's explicit acceptance ({{LAW:deletion-is-deliberate}}).
23
+ 6. With that acceptance, push the tag; trigger or verify the publish/release pipeline.
27
24
 
28
25
  ## Done when
29
26
  - Version, changelog, and tag all name the same number, and the release is pushed
@@ -20,8 +20,10 @@ to be acted on; or the user wants a review criterion recorded ("add a review rul
20
20
  4. Respond to each comment: the change you will make and why, or a reasoned decline
21
21
  with evidence.
22
22
  5. Apply the accepted changes — one intent per commit ({{LAW:one-intent-one-act}}), each through the
23
- [commit {{SKILL}}](commit.md) so {{DOCTRINE:consent-before-push}}'s per-commit consent holds — then
24
- re-run the checks ({{LAW:verify-before-asserting}}).
23
+ [commit {{SKILL}}](commit.md), on the pull request's own branch ({{DOCTRINE:consent-before-push}}) — then
24
+ re-run the checks ({{LAW:verify-before-asserting}}). If the PR has auto-merge armed, disarm it
25
+ before you push the fixes (the commit {{SKILL}}'s push step says how), then re-arm through the
26
+ [ship {{SKILL}}](ship.md) on the new head.
25
27
  6. Surface anything the review missed that you noticed while addressing it.
26
28
  7. Upgrade the review itself. A finding that recurs, a criterion the user asks for, or a
27
29
  defect a review should have caught becomes a rule in the nearest `REVIEW.md` above the
@@ -5,7 +5,7 @@
5
5
 
6
6
  {{CREDIT:mattpocock-skills-2509:skills/engineering/retro/SKILL.md}}
7
7
 
8
- **Trigger:** the user says "always…", "never…", "from now on…" or "remember that…". Anything the user wants to outlive this session counts: a standing rule ("make that a
8
+ **Trigger:** the user says "always…", "never…", "from now on…" or "remember that…", or "turn on auto-merge" / "turn off auto-merge". Anything the user wants to outlive this session counts: a standing rule ("make that a
9
9
  rule") or a durable fact ("note that…", "keep in mind…"). Also fires when a
10
10
  `feedback` {{MEMORY}} lesson keeps recurring and deserves promotion, or when
11
11
  `user-rules.md` needs review — a trial rule past its date, a stale rule, a bloated
@@ -109,6 +109,32 @@ The asymmetry is deliberate: Branch A costs no question, Branch B costs several.
109
109
  The price is the safeguard — make remembering cheap and legislating expensive, or
110
110
  the user picks "rule" out of impatience and the set inflates.
111
111
 
112
+ **Auto-merge flow** (the user says "turn on auto-merge", or "turn it off"). The wording is fixed
113
+ so the [ship {{SKILL}}](ship.md) reads it reliably: skip reformulation and the counter-example,
114
+ never the consent. Ask one question — every repo (`global`) or this project (`project`) — then
115
+ show this text, with the next free `R<n>`, the scope chosen and today's date, and append it to the
116
+ file Branch B step 5 names for that scope, on explicit consent:
117
+
118
+ ```
119
+ ## R<n> — Auto-merge green PRs
120
+ (scope: <global|project> | source: user, <date>)
121
+ Arm auto-merge on a PR I open, only when the forge has required checks.
122
+ - docs-tests: auto
123
+ - normal: human # human | reviewer
124
+ - sensitive: never
125
+ - Before any further push to a PR with auto-merge armed, disarm it first, then classify, review and arm again on the new head.
126
+ ```
127
+
128
+ `sensitive` never arms, whatever its line says. `docs-tests` accepts `auto | human | reviewer |
129
+ never`, `normal` accepts `human | reviewer | never`; any other value counts as `human`. `human`
130
+ waits for one approving review on the forge. The last line is part of the fixed text: the rule is
131
+ loaded every session, so every path that pushes sees it. `reviewer` is for a solo repo, where the
132
+ forge forbids approving your own PR: the blind reviewer must pass first. The rule arms only the
133
+ forge's merge; pushes still follow {{DOCTRINE:consent-before-push}} (a plain push of your own branch is
134
+ free, a push onto the main branch asks). To turn it off, remove
135
+ the rule with the same consent; to turn it off for one project only, write the rule into that
136
+ project's file with all three tier lines `never` (the later layer wins).
137
+
112
138
  **Review flow** (on request, or when a `trial until:` date has passed): for each rule
113
139
  due, ask whether it actually fired since adoption — graduate it (drop the trial
114
140
  marker), demote it back to a {{MEMORY}} fact, or delete it. Same consent gate as
@@ -22,11 +22,10 @@ request or merge the branch.
22
22
  before pushing.
23
23
  3. Confirm the branch carries only this change's commits and is rebased/updated on
24
24
  the base branch; resolve any divergence before opening.
25
- 4. Push the branch only with the user's explicit, per-push acceptance — on every
26
- branch, feature branches included ({{DOCTRINE:consent-before-push}}); present the change summary + commit
27
- message and wait, and never treat an earlier approval as consent for this push.
28
- Opening a PR or merging is **outward-facing** — get explicit confirmation first too,
29
- unless already authorized ({{LAW:deletion-is-deliberate}}).
25
+ 4. Push the branch with a plain push and open the pull request: the pull request is
26
+ the consent the main branch needs ({{DOCTRINE:consent-before-push}}). Merge only once its
27
+ required checks are green — never red, pending or absent. A forced push, or a push
28
+ straight onto the main branch, asks ({{LAW:deletion-is-deliberate}}).
30
29
  5. Open the PR with a three-part body. **Summary**: what changed and why, with the
31
30
  smallest visual that makes the point (a call tree, diff sketch, file tree or
32
31
  Mermaid diagram). **Evidence**: how it was tested, as before/after — the test that
@@ -35,9 +34,54 @@ request or merge the branch.
35
34
  published contract) or two-way (cheap to roll back), the blast radius (what breaks if
36
35
  it is wrong — consumers, layout, data), and any follow-up. Link the
37
36
  issue it closes; keep the title an imperative one-line summary.
38
- 6. If the project merges locally instead, merge into the base branch only after
37
+ 6. **Auto-merge.** It is off unless the user's standing rule *Auto-merge green PRs* in
38
+ `user-rules.md` arms it (the later layer wins: project over host over shared). That rule is
39
+ the durable authorization {{LAW:deletion-is-deliberate}} permits for the forge's merge; it
40
+ arms only that merge, and pushes still follow {{DOCTRINE:consent-before-push}}. With no such rule, say once per session in
41
+ each repo, when you open a PR there: "Auto-merge is off; say 'turn on auto-merge' to set a
42
+ standing rule" — the [rule {{SKILL}}](rule.md) writes it. With the rule, arm only when all of
43
+ these hold; otherwise leave the merge to the user:
44
+ - **Tier**, from the PR's diff. Any sensitive file → `sensitive`. Else, when every file is
45
+ docs (prose that is neither shipped nor executed) or tests → `docs-tests`, unless the diff
46
+ removes, skips or loosens a test or an assertion: CI cannot see a weakened test, so that diff
47
+ is `normal`. Anything else → `normal`. Sensitive is each `sensitive:` zone of the ownership block in the *base* branch's
48
+ `AGENTS.md` (never the head's), plus by default: auth and authz, secrets and credentials,
49
+ data migrations and schema, CI and deploy config, dependency manifests and lockfiles,
50
+ release and versioning, gate and hook config, `AGENTS.md`, `CLAUDE.md`, `CODEOWNERS`, any
51
+ `user-rules.md`, agent, skill and instruction files, and gate machinery (check scripts, CI-only
52
+ harnesses, coverage thresholds; not ordinary unit tests).
53
+ - **The rule's line for the tier.** `sensitive` never arms, whatever the rule says.
54
+ `docs-tests` accepts `auto | human | reviewer | never`; `normal` accepts `human | reviewer
55
+ | never` (`auto` is not valid there). A missing or other value counts as `human`. `auto`
56
+ arms. `human` arms only when the forge requires one approving review and dismisses it on a
57
+ new push. `reviewer` arms only
58
+ after the [fresh-eyes {{SKILL}}](fresh-eyes.md) passes: first add its verdict to the PR
59
+ body (`gh pr edit <pr> --body-file <file>`, `glab mr update <mr> --description <text>`).
60
+ `never` does not arm.
61
+ - **Forge**, one probe each; a result you cannot read counts as absent. Required checks on
62
+ the base: a `required_status_checks` rule in `gh api repos/{owner}/{repo}/rules/branches/<base>`,
63
+ or `required_status_checks` in `gh api repos/{owner}/{repo}/branches/<base>/protection`,
64
+ with a non-empty list of checks (`contexts` or `checks`): an empty list requires nothing,
65
+ and `--auto` then merges at once; GitLab: `only_allow_merge_if_pipeline_succeeds` in
66
+ `glab api projects/:id`. One approving review dismissed on a new push (`human`): a
67
+ `pull_request` rule with `required_approving_review_count` of 1 or more and
68
+ `dismiss_stale_reviews_on_push`, or the same under `required_pull_request_reviews`
69
+ (`dismiss_stale_reviews`) in the protection; GitLab: an approval rule with
70
+ `approvals_required` of 1 or more in `glab api projects/:id/approval_rules`, and
71
+ `reset_approvals_on_push` in `glab api projects/:id/approvals`. Auto-merge allowed:
72
+ `gh repo view --json autoMergeAllowed` (GitHub only; GitLab has no such switch). Never judge
73
+ green yourself: the forge's checks are the gate ({{DOCTRINE:external-gate}}).
74
+ Arm with the reviewed head named: `gh pr merge <pr> --auto --squash --match-head-commit
75
+ <sha>`, or `glab mr merge <mr> --auto-merge --squash --sha <sha>` (a plain `glab mr merge`
76
+ arms it too, so always name the flag). On GitHub the pin is checked only when you arm: an
77
+ armed PR stays armed after a later push. So before any further push to an armed PR, disarm
78
+ it (`gh pr merge <pr> --disable-auto`; GitLab: `glab api --method POST
79
+ projects/:id/merge_requests/<iid>/cancel_merge_when_pipeline_succeeds`), then classify,
80
+ review and arm again on the new head. Recommend CODEOWNERS with required code-owner review on
81
+ sensitive paths as the forge's own backstop.
82
+ 7. If the project merges locally instead, merge into the base branch only after
39
83
  review/approval.
40
- 7. Once the branch is merged — locally or through the PR — delete it, local and remote
84
+ 8. Once the branch is merged — locally or through the PR — delete it, local and remote
41
85
  (`git branch -d <branch>`, `git push origin --delete <branch>`), with consent: it is a
42
86
  deletion ({{LAW:deletion-is-deliberate}}). A PR usually merges after your turn ends,
43
87
  with nobody left to delete its branch, so the first time you ship in a repo, check
@@ -52,6 +96,9 @@ request or merge the branch.
52
96
  ## Done when
53
97
  - The diff passed review with no `blocking` finding, and the PR is open (or the branch is merged) with a Summary / Evidence / Merge danger
54
98
  body, and nothing unrelated rides along.
99
+ - Auto-merge is armed only under the user's standing rule, never for a sensitive diff, on a
100
+ forge that requires checks, on the reviewed head, and disarmed before any later push — or it
101
+ is off and the user was told once this session how to turn it on.
55
102
  - A branch merged while you are still working is deleted, local and remote, or the user
56
103
  declined.
57
104
 
@@ -32,8 +32,8 @@ not make.
32
32
  state (a global config, a hook shim) run from the worktree only when they resolve
33
33
  the repo through it; verify with the tool's own status command rather than assume.
34
34
  5. **Integrate through the normal gate** — commit via the [commit {{SKILL}}](commit.md),
35
- ship via [ship](ship.md). A worktree earns no exemption from per-commit and
36
- per-push consent ({{DOCTRINE:consent-before-push}}). Expect conflicts with a sibling tree that
35
+ ship via [ship](ship.md). The worktree's branch is your own; the main branch still
36
+ changes only through a green pull request ({{DOCTRINE:consent-before-push}}). Expect conflicts with a sibling tree that
37
37
  touched the same files; resolve them on the branch, not in the other tree.
38
38
  6. **Clean up when the branch is merged or abandoned** — with consent, since removal
39
39
  is deletion ({{LAW:deletion-is-deliberate}}):
@@ -70,6 +70,13 @@
70
70
  "license": "MIT",
71
71
  "licenseFile": "licenses/everything-claude-code.txt"
72
72
  },
73
+ "herdr": {
74
+ "repo": "herdrdev/herdr",
75
+ "commit": "1cbd794559fb139f95f1bdb4b2a8998082017d0e",
76
+ "author": "herdrdev",
77
+ "license": "Apache-2.0",
78
+ "licenseFile": "licenses/herdr.txt"
79
+ },
73
80
  "i-have-adhd": {
74
81
  "repo": "ayghri/i-have-adhd",
75
82
  "commit": "1ecea1993b7fce257ffbd686c070948b5e07eda6",
@@ -165,6 +165,8 @@
165
165
  "DESC_JENKINS_PIPELINE": "<one-line description: write or fix a declarative Jenkinsfile or shared library — stages, when, parallel, credentials, CPS and @NonCPS, sandbox approval, JenkinsPipelineUnit>",
166
166
  "DESC_GITLAB_CI": "<one-line description: write or fix .gitlab-ci.yml — rules, needs DAG, include and extends, cache and artifacts, protected and masked variables, environments, CI lint>",
167
167
  "DESC_COMPOSE_OPS": "<one-line description: write, review or run any Compose stack — healthchecks, volumes, pinned images, secrets, limits, logs, networks, safe update and rollback; not a Spring Boot image build (docker-expert)>",
168
+ "DESC_HERDR": "<one-line description: control Herdr workspaces, tabs, panes and agents from inside a Herdr pane (HERDR_ENV=1); only when the user names Herdr>",
169
+ "DESC_OPENCODE_CLI": "<one-line description: drive OpenCode V2 from another session through its CLI — headless run, sessions, background service, MCP, plugins, models, stats, debug; never auth login>",
168
170
  "AGENT_COLORS": {
169
171
  "architect": "primary",
170
172
  "reviewer": "warning",
package/themes/biker.json CHANGED
@@ -165,6 +165,8 @@
165
165
  "DESC_JENKINS_PIPELINE": "Write or fix a declarative Jenkinsfile or shared library.",
166
166
  "DESC_GITLAB_CI": "Write or fix .gitlab-ci.yml before the ride.",
167
167
  "DESC_COMPOSE_OPS": "Write, review or run a Compose stack; not image builds.",
168
+ "DESC_HERDR": "Drive Herdr panes and agents from inside it; only when the user names Herdr.",
169
+ "DESC_OPENCODE_CLI": "Drive OpenCode V2 from its CLI: run, sessions, server, MCP, plugins.",
168
170
  "AGENT_COLORS": {
169
171
  "architect": "primary",
170
172
  "reviewer": "warning",
@@ -165,6 +165,8 @@
165
165
  "DESC_JENKINS_PIPELINE": "Write or fix a declarative Jenkinsfile or shared library.",
166
166
  "DESC_GITLAB_CI": "Write or fix .gitlab-ci.yml before the lights go out.",
167
167
  "DESC_COMPOSE_OPS": "Write, review or run a Compose stack; not image builds.",
168
+ "DESC_HERDR": "Drive Herdr panes and agents from inside it; only when the user names Herdr.",
169
+ "DESC_OPENCODE_CLI": "Drive OpenCode V2 from its CLI: run, sessions, server, MCP, plugins.",
168
170
  "AGENT_COLORS": {
169
171
  "architect": "primary",
170
172
  "reviewer": "warning",
@@ -165,6 +165,8 @@
165
165
  "DESC_JENKINS_PIPELINE": "Write or fix a declarative Jenkinsfile or shared library.",
166
166
  "DESC_GITLAB_CI": "Write or fix .gitlab-ci.yml before the run.",
167
167
  "DESC_COMPOSE_OPS": "Write, review or run a Compose stack; not image builds.",
168
+ "DESC_HERDR": "Drive Herdr panes and agents from inside it; only when the user names Herdr.",
169
+ "DESC_OPENCODE_CLI": "Drive OpenCode V2 from its CLI: run, sessions, server, MCP, plugins.",
168
170
  "AGENT_COLORS": {
169
171
  "architect": "primary",
170
172
  "reviewer": "warning",
package/themes/gamer.json CHANGED
@@ -165,6 +165,8 @@
165
165
  "DESC_JENKINS_PIPELINE": "Write or fix a declarative Jenkinsfile or shared library.",
166
166
  "DESC_GITLAB_CI": "Write or fix .gitlab-ci.yml before the boss fight.",
167
167
  "DESC_COMPOSE_OPS": "Write, review or run a Compose stack; not image builds.",
168
+ "DESC_HERDR": "Drive Herdr panes and agents from inside it; only when the user names Herdr.",
169
+ "DESC_OPENCODE_CLI": "Drive OpenCode V2 from its CLI: run, sessions, server, MCP, plugins.",
168
170
  "AGENT_COLORS": {
169
171
  "architect": "primary",
170
172
  "reviewer": "warning",
@@ -165,6 +165,8 @@
165
165
  "DESC_JENKINS_PIPELINE": "Forge and mend a declarative Jenkinsfile or shared library.",
166
166
  "DESC_GITLAB_CI": "Forge and mend .gitlab-ci.yml: rules, needs, cache.",
167
167
  "DESC_COMPOSE_OPS": "Muster and command a Compose stack; not image builds.",
168
+ "DESC_HERDR": "Command Herdr panes and agents from within; only when Herdr is named.",
169
+ "DESC_OPENCODE_CLI": "Command OpenCode V2 through its CLI: run, sessions, server, MCP, plugins.",
168
170
  "AGENT_COLORS": {
169
171
  "architect": "primary",
170
172
  "reviewer": "warning",