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.
- package/CHANGELOG.md +68 -0
- package/README.md +21 -18
- package/SHIPPED.md +7 -7
- package/adapters/opencode/README.md +3 -2
- package/adapters/opencode/plugins/geneseed-context.js +6 -0
- package/adapters/opencode/plugins/geneseed-guard.js +5 -3
- package/bin/geneseed-cli.mjs +7 -0
- package/bin/geneseed-hook.mjs +3 -3
- package/docs/PRD.md +1 -1
- package/docs/README.md +1 -0
- package/docs/concepts/agents.md +1 -1
- package/docs/concepts/collaboration.md +2 -2
- package/docs/concepts/enforcement-table.md +5 -2
- package/docs/concepts/exclusions.md +16 -2
- package/docs/concepts/footprint.md +1 -1
- package/docs/concepts/foreman-mode.md +1 -1
- package/docs/concepts/hook-gates.md +3 -3
- package/docs/concepts/hooks.md +4 -3
- package/docs/concepts/host-matrix.md +2 -2
- package/docs/concepts/kits.md +12 -2
- package/docs/concepts/loop-bricks.md +3 -3
- package/docs/concepts/loops.md +6 -4
- package/docs/concepts/ownership.md +1 -1
- package/docs/concepts/rules.md +2 -2
- package/docs/concepts/skills.md +1 -1
- package/docs/extending.md +63 -28
- package/docs/guides/auto-merge.md +100 -0
- package/docs/guides/choose-your-setup.md +1 -1
- package/docs/guides/headless.md +1 -1
- package/docs/guides/install-clone.md +1 -1
- package/docs/guides/install.md +1 -1
- package/docs/guides/loop-finish.md +3 -3
- package/docs/guides/loop-running.md +4 -4
- package/docs/guides/project-context.md +1 -1
- package/docs/guides/run-a-factory.md +2 -2
- package/docs/guides/setup-doctrines.md +2 -2
- package/docs/guides/setup-footprint.md +1 -1
- package/docs/guides/uninstall.md +3 -3
- package/docs/guides/upgrade.md +1 -1
- package/docs/guides/worktree.md +1 -1
- package/docs/reference/environment.md +4 -2
- package/docs/reference/plugin-activity.md +1 -1
- package/docs/reference/plugin-guard.md +1 -1
- package/docs/reference/plugin-learn.md +1 -1
- package/docs/reference/plugin-workflow.md +1 -1
- package/docs/reference/troubleshoot-doctor.md +1 -1
- package/docs/reference/troubleshoot-hooks.md +2 -2
- package/docs/reference/troubleshoot-install.md +3 -3
- package/docs/reference/troubleshoot-tools.md +1 -1
- package/docs/token-footprint.md +2 -2
- package/docs/understand/enforced-vs-asked.md +1 -1
- package/docs/understand/machine-claude.md +2 -2
- package/docs/understand/on-your-machine.md +1 -1
- package/docs/web-ui.md +5 -5
- package/harness.config.json +1 -1
- package/js/README.md +2 -1
- package/js/build/args.mjs +12 -1
- package/js/build/driver.mjs +33 -6
- package/js/build/emit-claude.mjs +8 -4
- package/js/build/emit-opencode.mjs +13 -9
- package/js/build/generate.mjs +10 -156
- package/js/build/profile.mjs +318 -0
- package/js/build/render.mjs +81 -3
- package/js/build/retired-skills.mjs +60 -13
- package/js/build/source.mjs +15 -1
- package/js/build/stubs.mjs +4 -1
- package/js/cli-table.json +48 -3
- package/js/hosts/hooks-done.mjs +345 -55
- package/js/hosts/hooks-learn.mjs +4 -3
- package/js/hosts/hooks-prims.mjs +5 -3
- package/js/hosts/hooks.mjs +153 -6
- package/js/hosts/installs.mjs +19 -1
- package/js/hosts/native.mjs +19 -2
- package/js/hosts/settings.mjs +29 -3
- package/js/inspect/checks-constitution.mjs +32 -0
- package/js/inspect/diff.mjs +21 -3
- package/js/inspect/inventory.mjs +1 -1
- package/js/maintain/setup.mjs +5 -1
- package/js/maintain/update.mjs +4 -2
- package/js/web/actions.mjs +16 -3
- package/js/web/api.mjs +7 -2
- package/package.json +1 -1
- package/registry.json +14 -0
- package/src/AGENT.md.tmpl +15 -17
- package/src/bricks/pr-open.md +3 -2
- package/src/doctrines/ops.md +2 -2
- package/src/doctrines/process.md +40 -36
- package/src/factories/analysis-to-build.json +1 -1
- package/src/factories/bug-report-to-fix.json +1 -1
- package/src/factories/issue-to-pr.json +1 -1
- package/src/kits/terminal-tools/rules.md +10 -0
- package/src/kits/terminal-tools.json +13 -0
- package/src/licenses/herdr.txt +201 -0
- package/src/modes/foreman.md +6 -3
- package/src/skills/_self-improvement.md +9 -7
- package/src/skills/commit.md +17 -17
- package/src/skills/debug/ci.md +1 -1
- package/src/skills/dependencies.md +3 -3
- package/src/skills/document-project.md +3 -2
- package/src/skills/factory.md +13 -4
- package/src/skills/geneseed.md +4 -2
- package/src/skills/git-history.md +5 -7
- package/src/skills/herdr.md +135 -0
- package/src/skills/loop.md +3 -2
- package/src/skills/opencode-cli.md +84 -0
- package/src/skills/pipeline.md +1 -1
- package/src/skills/release.md +5 -8
- package/src/skills/review-response.md +4 -2
- package/src/skills/rule.md +27 -1
- package/src/skills/ship.md +54 -7
- package/src/skills/worktree.md +2 -2
- package/src/upstreams.json +7 -0
- package/themes/_TEMPLATE.json +2 -0
- package/themes/biker.json +2 -0
- package/themes/commentator.json +2 -0
- package/themes/cyberpunk.json +2 -0
- package/themes/gamer.json +2 -0
- package/themes/imperial.json +2 -0
- package/themes/joker.json +2 -0
- package/themes/marvin.json +2 -0
- package/themes/mean.json +2 -0
- package/themes/military.json +2 -0
- package/themes/neutral.json +2 -0
- package/themes/pirate.json +2 -0
- package/themes/sports.json +2 -0
- package/themes/verstappen.json +2 -0
- package/themes/wizard.json +2 -0
- package/web/dist/assets/Activity-D2kOc3yi.js +1 -0
- package/web/dist/assets/ActivityDetail-By3xOr21.js +1 -0
- package/web/dist/assets/{Bonsai-BBl4XXqs.js → Bonsai-CBWDTBA4.js} +1 -1
- package/web/dist/assets/{CopyButton-Beven8yn.js → CopyButton-BVbpriMB.js} +1 -1
- package/web/dist/assets/Dashboard-CIJLPHM9.js +2 -0
- package/web/dist/assets/Docs-CiRRIELs.js +5 -0
- package/web/dist/assets/Factories-DhyK0O8d.js +1 -0
- package/web/dist/assets/{GreenhouseView-Bce212qd.js → GreenhouseView-DW3PgTPy.js} +1 -1
- package/web/dist/assets/Installs-B6nlo-Ly.js +3 -0
- package/web/dist/assets/{JournalView-CV4omyww.js → JournalView-O65qEWfp.js} +1 -1
- package/web/dist/assets/Kits-C5U-yT6Z.js +1 -0
- package/web/dist/assets/Laws-CuTw_XNf.js +4 -0
- package/web/dist/assets/{LibRows-Dag1s0ZX.js → LibRows-D6-CVa3K.js} +1 -1
- package/web/dist/assets/Library-CzPlerd6.js +3 -0
- package/web/dist/assets/Loops-CqNF_-nS.js +2 -0
- package/web/dist/assets/{OperatorHudView-JmYY1pBR.js → OperatorHudView-BNr8K5qj.js} +1 -1
- package/web/dist/assets/Personal-DeDb9e8O.js +2 -0
- package/web/dist/assets/Settings-B8MPN_AD.js +1 -0
- package/web/dist/assets/{Tabs-8zsyEPSK.js → Tabs-DJzAez4h.js} +1 -1
- package/web/dist/assets/index-BL3P-9Rg.js +6 -0
- package/web/dist/index.html +1 -1
- package/web/dist/assets/Activity-WQ3ykgxU.js +0 -1
- package/web/dist/assets/ActivityDetail-7rt04SkS.js +0 -1
- package/web/dist/assets/Dashboard-BgLArtgu.js +0 -2
- package/web/dist/assets/Docs-B5aHp86J.js +0 -5
- package/web/dist/assets/Factories-BjqzXAw8.js +0 -1
- package/web/dist/assets/Installs-B1OsrHXF.js +0 -3
- package/web/dist/assets/Kits-CW1e7xNa.js +0 -1
- package/web/dist/assets/Laws-1Ckf1lbs.js +0 -4
- package/web/dist/assets/Library-B3FuFLel.js +0 -3
- package/web/dist/assets/Loops-CwqgnLNw.js +0 -2
- package/web/dist/assets/Personal-DKLgLa7Z.js +0 -2
- package/web/dist/assets/Settings-BwErnh-R.js +0 -1
- package/web/dist/assets/index-Ce6qF2nG.js +0 -6
package/docs/concepts/hooks.md
CHANGED
|
@@ -17,8 +17,9 @@ Geneseed writes its hooks into the host's settings file. Every hook calls one pr
|
|
|
17
17
|
| Event | When | Command | What it does | Conditional? |
|
|
18
18
|
| --- | --- | --- | --- | --- |
|
|
19
19
|
| `SessionStart` | `startup`, `resume`, `clear`, `compact`, `fork` | `geneseed-hook context` | injects your harness files and the repo's docs, or re-injects them after a resume, a fork, or an auto-compaction summarised them away | no |
|
|
20
|
-
| `PreToolUse` | `Bash`, `PowerShell` | `geneseed-hook git-gate` | asks before a command that would really lose data, and before a recursive scan of a whole filesystem; asks before every commit and push | the commit/push question only |
|
|
20
|
+
| `PreToolUse` | `Bash`, `PowerShell`, `Monitor` | `geneseed-hook git-gate` | asks before a command that would really lose data, and before a recursive scan of a whole filesystem; asks before every commit and push | the commit/push question only |
|
|
21
21
|
| `PreToolUse` | `Write`, `Edit`, `NotebookEdit` | `geneseed-hook rule-gate` | asks before a secret lands in a file, or a write to your standing rules; stops the session's first write once in an application repo with no `## Ownership` section | no |
|
|
22
|
+
| `PreToolUse` | `Skill`, `Agent`, `Task` | `geneseed-hook tool-gate` | records the skill or subagent call in the usage count; judges nothing and never blocks | no |
|
|
22
23
|
| `Stop` | the agent finishes a reply | `geneseed-hook learn` | distils durable facts into the memory store | needs `GENESEED_LLM` |
|
|
23
24
|
| `SubagentStop` | a subagent finishes | `geneseed-hook learn` | records a lesson for that agent in the store's `agents/<name>.md` | needs `GENESEED_LLM` |
|
|
24
25
|
| `PreCompact` | before auto-compaction | `geneseed-hook learn` | captures memory before the transcript is summarised | needs `GENESEED_LLM` |
|
|
@@ -53,7 +54,7 @@ On Bob, a subagent's files cannot be told apart from its session's files (its ho
|
|
|
53
54
|
- removing files (`rm`, `rmdir`, `del`, `erase`, `Remove-Item`) that git cannot restore: untracked, ignored or modified files, a repository's `.git`, or anything outside a repository.
|
|
54
55
|
|
|
55
56
|
A force push to a feature branch, the protected-branch-only forms above on a feature branch, a new branch (`checkout -b`, `switch -c`), `reset --hard` over uncommitted work or to a commit that keeps every unpushed one, `branch -D` of a pushed branch, or `rm` of a tracked, unmodified file passes. When the gate cannot tell — a glob or `$variable` it would have to expand, a `cd` it cannot follow, `sh -c`/`xargs`, git failing or missing — it asks, and says it could not verify. To read the state it runs `git` itself, only once a command already looked destructive; every other command pays nothing. That is a Rule, so it holds in every build — unless you switch its gate off for one install with `--no-deletion-gate` (or the switch on Rule IV in the console's Constitution page). The hook is then wired with `--no-deletion-gate` and this check stands down; the Rule's text still binds the agent, and the catastrophic-command check above and the root-scan and consent checks below still run ([Exclusions](exclusions.md)).
|
|
56
|
-
- **
|
|
57
|
+
- **A `git commit` or `git push` onto the main branch** gets a prompt citing *Consent Before Push*: the main branch changes only through a pull request with green checks. The main branch is `main`, `master`, a remote's default branch, or, in a linked worktree, the branch the main checkout holds. On any other branch, a commit, a local merge and a plain push of the checked-out branch (`git push -u origin feature`, `git push origin HEAD:feature`) pass. A bare `git push` (where `push.default` and your git config decide the target), a push of a branch other than the checked-out one, a forced push, a tag push, a sub-agent's push, or a command the gate cannot read still asks. A quoted message is data: `git commit -m "fix(hooks): x"` passes, and so does a bash `git commit -F - <<'EOF'` heredoc whose delimiter is quoted; a `$(` or a backtick inside double quotes still asks. In a repository with no remote, or with a remote whose default branch is not recorded (`git remote add` records none; `git remote set-head origin --auto` does), the gate cannot tell your branch from the default one, so every commit and push asks. Build with `--strict-consent` (or turn on *Strict consent* on the console's Constitution page) and every commit and push asks again. This part belongs to the **process** doctrine pack: build without it, or exclude that rule, and the hook stays wired with `--no-consent` — commits and pushes go through without asking, real data loss is still stopped ([Rules](rules.md)).
|
|
57
58
|
- **A recursive scan of a whole filesystem** — `find /`, `du -sh /`, `grep -r foo /`, `rg x C:\`, `Get-ChildItem C:\ -Recurse` — gets a prompt citing *Commands Must Return* (on Bob, it is blocked). In Git Bash `/` mounts every drive and mounted share, so such a scan runs for hours, and `| head` does not stop it. The prompt tells the agent to search a specific directory instead. A deeper path (`find /c/Users/me/project`), `ls /` without `-R` (`ls -r` is reverse order, not recursion), a quoted argument (a search pattern such as `grep -rn "/" src`), a `#` comment, and the remote half of an `ssh` command pass. It belongs to the **ops** pack: build without it, or exclude that rule, and the hook is wired with `--no-root-scan` and this check stands down (also on Bob and in the OpenCode guard); every other check stays ([Exclusions](exclusions.md)).
|
|
58
59
|
- **A shell write to a protected check or a gate's own configuration** gets the same *External Gate* prompt as a write tool (see rule-gate below; on Bob, it is blocked). `--no-consent` does not touch it.
|
|
59
60
|
- Any other command passes untouched.
|
|
@@ -75,7 +76,7 @@ On Bob, a subagent's files cannot be told apart from its session's files (its ho
|
|
|
75
76
|
- An edit that weakens a test gets a note to the agent, citing *Cure the Cause*. It is **advisory**: it asks nothing and blocks nothing. An install built `--no-test-note` gets no note, here or at turn end ([Exclusions](exclusions.md)). A test file has a path segment `test`, `tests`, `__tests__` or `spec`, or a name `*.test.*`, `*.spec.*`, `*_test.*` or `test_*`. The edit weakens it when it adds `.skip(`, `xit(`, `xfail`, `@Disabled`, `@Ignore`, `pytest.mark.skip` or `t.Skip(`, or when it removes an assertion line and adds no other. The done gate repeats it to you when the turn ends. On Bob the note is a line in the hook log. On OpenCode it is one reminder on the next request.
|
|
76
77
|
- Ordinary edits pass untouched.
|
|
77
78
|
|
|
78
|
-
**The done gate.** Runs when a turn ends, inside `learn` and before it calls any model. You do not have to set it up: with no list, the gate infers the checks from the manifests at the project's git root — the `test`, `lint` and `typecheck` scripts of `package.json` (run with the package manager its lockfile names; npm's default "no test specified" script is skipped), `mvn test` for `pom.xml`, `gradle test` for `build.gradle(.kts)`, `pytest` for `pyproject.toml` when the project shows pytest (a `[tool.pytest` section, `pytest.ini`, `conftest.py` or a `tests/` folder), `cargo test` for `Cargo.toml`, `go test` for `go.mod`. Subprojects of a monorepo are not inferred. Each inferred check accepts its usual spellings: `npm test`, `npm run test` and `npm t` all count, and so do `./mvnw clean verify` or `.\gradlew build` — but not with a flag that skips the tests (`-DskipTests`, `-Dmaven.test.skip`, `-x test`, `cargo test --no-run`). Spellings it does not know (`npm run test:unit`, `npx vitest`, `CI=1 npm test`, `./gradlew :app:test`) read as not run. Inferred checks are **advisory**, and they stay advisory, with no date: only a list the project wrote can block. A turn that ends without them still ends, and you see a warning naming them (a `systemMessage`), plus a `done-gate-advisory` line in the gate ledger. To make the gate block, or to choose the checks yourself, list them in `.geneseed/done-checks.txt` at the git root: one command per line, `#` for comments, for example `npm run lint` and `node --test`. That file replaces the inference; a file that lists nothing turns the gate off for the project. With a listed file, if the turn edited a file under that root and a listed check has not passed since the last edit, the turn does not end: the agent is told which checks are owed, citing *Verify Before Asserting*. Every session starts with one line naming the checks and their source, for example `Done gate: inferred from package.json — npm test, npm run lint (advisory)`. On Bob, which never judges a turn, the line ends `(not judged on this host)` instead. A check counts when it ran as a shell command, unpiped (`npm test | tail` exits with `tail`'s code, so it proves nothing), with nothing after it that masks its exit code (`|| true`, `; true`, `; exit 0` all exit 0 on a red suite, so any `||` after the check, or a `;` or newline followed by `true`, `:`, `exit 0` or a bare `exit`, reads as "not run"), and its result was not an error. The gate never runs a check itself. It reads the transcript from its end, back only to the prompt that
|
|
79
|
+
**The done gate.** Runs when a turn ends, inside `learn` and before it calls any model. You do not have to set it up: with no list, the gate infers the checks from the manifests at the project's git root — the `test`, `lint` and `typecheck` scripts of `package.json` (run with the package manager its lockfile names; npm's default "no test specified" script is skipped), `mvn test` for `pom.xml`, `gradle test` for `build.gradle(.kts)`, `pytest` for `pyproject.toml` when the project shows pytest (a `[tool.pytest` section, `pytest.ini`, `conftest.py` or a `tests/` folder), `cargo test` for `Cargo.toml`, `go test` for `go.mod`. Subprojects of a monorepo are not inferred. Each inferred check accepts its usual spellings: `npm test`, `npm run test` and `npm t` all count, and so do `./mvnw clean verify` or `.\gradlew build` — but not with a flag that skips the tests (`-DskipTests`, `-Dmaven.test.skip`, `-x test`, `cargo test --no-run`). Spellings it does not know (`npm run test:unit`, `npx vitest`, `CI=1 npm test`, `./gradlew :app:test`) read as not run. Inferred checks are **advisory**, and they stay advisory, with no date: only a list the project wrote can block. A turn that ends without them still ends, and you see a warning naming them (a `systemMessage`), plus a `done-gate-advisory` line in the gate ledger. To make the gate block, or to choose the checks yourself, list them in `.geneseed/done-checks.txt` at the git root: one command per line, `#` for comments, for example `npm run lint` and `node --test --test-reporter=tap "tests/**/*.test.mjs"`. A listed line matches as a prefix of the command: `node --test` listed would accept `node --test tests/one.test.mjs`, one file of the suite, so list each command whole. That file replaces the inference; a file that lists nothing turns the gate off for the project. With a listed file, if the turn edited a file under that root and a listed check has not passed since the last edit, the turn does not end: the agent is told which checks are owed, citing *Verify Before Asserting*. Every session starts with one line naming the checks and their source, for example `Done gate: inferred from package.json — npm test, npm run lint (advisory)`. On Bob, which never judges a turn, the line ends `(not judged on this host)` instead. A check counts when it ran as a shell command, unpiped (`npm test | tail` exits with `tail`'s code, so it proves nothing), with nothing after it that masks its exit code (`|| true`, `; true`, `; exit 0` all exit 0 on a red suite, so any `||` after the check, or a `;` or newline followed by `true`, `:`, `exit 0` or a bare `exit`, reads as "not run"), and its result was not an error. A check that runs in the background (Claude Code's `run_in_background`, or a command moved there after its foreground timeout) counts only when its task notification says it completed with exit code 0; the launch alone says only that it started. The gate never runs a check itself. It reads the transcript from its end, back only to the last prompt a person typed: a background task's notification opens no turn, so a turn spans every continuation the notifications drive. Its cost grows with that turn, not with the session; in a long run kept going by notifications it may read back to the start of the file. A sub-agent's turn is judged too, when it stops (SubagentStop): the gate reads the sub-agent's own transcript and judges each project it wrote files in by that project's git root and list, so a worker in its own worktree owes its worktree's checks, not its parent's. A block there keeps the sub-agent working, with the owed checks as its next instruction. An inferred check there is only a stderr line and a ledger entry, since nobody sees a sub-agent's warning. It blocks again only when the agent edited a file since the last block, or when a check's background run changed its verdict (still running, then failed), and at most 3 times per continuation: a stop with neither, or a fourth stop, ends the turn and leaves a `done-gate-cap` line in the gate ledger. A task notification starts a new continuation with a fresh count, so early blocks do not spend the cap for the rest of an unattended run. Over the whole turn, until the next prompt a person types, it blocks at most 10 times: a suite relaunched in the background after each failure would otherwise loop, one full run per cycle. Past that ceiling the turn ends, and the stderr line says the total ceiling was reached. The block names the checks whose background run is still running or reported a failure. The count is kept per session (and per sub-agent) in the install's `notebook/done-gate/`; without an install, the second stop ends the turn. Only file-write tools count as edits: a shell `sed -i` or redirect is not one here. When a turn weakened a test (see the rule gate), the gate adds a line that the agent cannot suppress, `[done-gate] advisory — test weakened this turn: tests/a.test.js (.skip added)`. The line needs no checks and stays out of the ask counts. `--no-done-gate` silences this line and OpenCode's reminder, but not the note the agent gets at edit time on Claude Code, OpenClaude and Bob: the rule gate never receives that flag. A block prints only the block; the line comes at the stop that ends the turn. On OpenCode the gate is a reminder on the next request (OpenCode 1 only), listed or inferred; on Bob, whose Stop carries no transcript, the turn is not judged, and with a listed file a log line says so. An install built `--no-done-gate` wires `learn` with that flag: the check is skipped, learning still runs ([Exclusions](exclusions.md)).
|
|
79
80
|
|
|
80
81
|
**learn.** Takes the tail of the transcript and asks a model to distil what is worth keeping into one-fact-per-file entries in the memory store: on a global install, the shared one when it exists. It is shown the facts already stored, so it updates one with the merged text rather than writing a twin (the old version is kept in `memory/archive/`), and moves one the session proved obsolete into `memory/archive/`. It needs `GENESEED_LLM` set to a model command, for example:
|
|
81
82
|
|
|
@@ -23,7 +23,7 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
|
|
|
23
23
|
| User-only skills hidden from the model | 🔒 `permission.skill` deny | ✅ `disable-model-invocation` | ✅ `/`-command, no skill | ✅ `disable-model-invocation` |
|
|
24
24
|
| Sovereign-repo exclusions⁵ | ⚙️ plugins stand down | ✅ `claudeMdExcludes` | ✅ rules shadow stub | ✅ `claudeMdExcludes` |
|
|
25
25
|
| Subagent depth capped at two ([Foreman mode](foreman-mode.md)) | ✅ `subagent_depth` | ✅ `env` setting | ➖ undocumented | ➖ no cap in the host |
|
|
26
|
-
| MCP
|
|
26
|
+
| MCP servers (Geneseed reads and lists them, never writes them) | ✅ `mcp` | ✅ `mcpServers` | ✅ `mcp.json` | ✅ `mcpServers` |
|
|
27
27
|
| Colour themes · LSP · workflow runner · primary agent · `/`-commands | ✅ | ➖ | ➖ | ➖ |
|
|
28
28
|
|
|
29
29
|
✅ native · ⚙️ OpenCode plugin · 🔒 `permission` entry in `opencode.json` · 🪝 `settings.json` hook · ➖ no host mechanism (the rule still applies as prose).
|
|
@@ -54,7 +54,7 @@ No check on any host calls a model. `geneseed doctor --probe` covers the other h
|
|
|
54
54
|
|
|
55
55
|
## The one conditional row
|
|
56
56
|
|
|
57
|
-
The **consent before commit and push** row depends on a choice you make at build time. It enforces the rule *Consent Before Push*, which belongs to the **process** doctrine pack ([Rules](rules.md)). Build without that pack, or exclude that one rule, and the commit/push question goes away — but the gate itself stays: on Claude Code and OpenClaude the `git-gate` hook is still wired (with `--no-consent`), so destructive git is still caught. The standing-rule row is conditional the same way: it enforces *Persist Insight*, also in the process pack, and excluding it (or the pack) drops that hook on every host ([Exclusions](exclusions.md)). Everything else in the table is always on.
|
|
57
|
+
The **consent before commit and push** row depends on a choice you make at build time. It enforces the rule *Consent Before Push*, which belongs to the **process** doctrine pack ([Rules](rules.md)). By default it asks only for a commit or push onto the main branch; `--strict-consent` makes it ask for every one. OpenCode always asks for every commit and push: its permission globs cannot read which branch is checked out. Build without that pack, or exclude that one rule, and the commit/push question goes away — but the gate itself stays: on Claude Code and OpenClaude the `git-gate` hook is still wired (with `--no-consent`), so destructive git is still caught. The standing-rule row is conditional the same way: it enforces *Persist Insight*, also in the process pack, and excluding it (or the pack) drops that hook on every host ([Exclusions](exclusions.md)). Everything else in the table is always on.
|
|
58
58
|
|
|
59
59
|
One OpenCode asymmetry: Geneseed shares `opencode.json` with you, so it removes only what it recorded writing. The manifest lists the `permission.bash` gates it added (`bash_gates`), and a rebuild without the process pack, or with `--no-deletion-gate`, takes back those that still read as it wrote them. An entry that was already there, one you changed, and every gate on an install made before 5.2.0 (which has no record) stays and is named in a warning; `--prune-gates` on one build removes the last kind. A `permission.skill` deny works the same way. Uninstall takes back both: every recorded deny and every recorded `permission.bash` gate that still reads as Geneseed wrote it. A gate you changed, and one with no record, stays.
|
|
60
60
|
|
package/docs/concepts/kits.md
CHANGED
|
@@ -54,18 +54,28 @@ The fourth kit is `docker`, for Docker and Compose operations on any stack. It a
|
|
|
54
54
|
|
|
55
55
|
It does not overlap the spring-boot kit's `docker-expert` agent: that agent builds a Spring Boot service's own image (Buildpacks, layered or native) and its local-dev Compose file, and `compose-ops` operates any Compose stack. Either kit works without the other. `compose-ops` is adapted in part from the `docker-patterns` skill of [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) by Affaan Mustafa (MIT), rewritten for operations; its skill folder ships `LICENSE-everything-claude-code.txt`.
|
|
56
56
|
|
|
57
|
+
The fifth kit is `terminal-tools`, for terminal programs the agent drives through their own CLI. It adds two skills:
|
|
58
|
+
|
|
59
|
+
| Member | Kind | What it is for |
|
|
60
|
+
|---|---|---|
|
|
61
|
+
| `herdr` | skill | Herdr workspaces, tabs, panes and agents, from inside a Herdr pane (`HERDR_ENV=1`) and only when the user names Herdr: split a sibling pane, start and prompt another agent, wait on state, read output. It carries the Windows notes of herdr's own docs page (signed binaries unsupported, so SmartScreen may warn) |
|
|
62
|
+
| `opencode-cli` | skill | OpenCode V2 from another session: headless `opencode run` (JSON output, model, agent, continue and fork), the background service against `--standalone` and `--server`, `serve` and `pair`, sessions, MCP, plugins, models, stats, debug |
|
|
63
|
+
|
|
64
|
+
Its rules gate each tool on its environment, read live state before acting, close only what the agent opened, never stop the user's server or service, and leave every login and credential to the user. `herdr` is adapted from the official skill of [herdrdev/herdr](https://github.com/herdrdev/herdr) by herdrdev (Apache-2.0), condensed into house format; its skill folder ships `LICENSE-herdr.txt`. `opencode-cli` is first-party and targets OpenCode V2 only, verified against the V2 source at v2.3.0: the V1 commands top-level `export` and `import`, `attach`, `agent create` and `mcp debug` are not in its command table.
|
|
65
|
+
|
|
57
66
|
### Switching kits on and off
|
|
58
67
|
|
|
59
68
|
```bash
|
|
60
69
|
geneseed build --emit claude-global --kits spring-boot
|
|
61
70
|
geneseed build --emit claude-global --kits react,spring-boot
|
|
62
71
|
geneseed build --emit claude-global --kits ci-pipelines,docker
|
|
72
|
+
geneseed build --emit claude-global --kits terminal-tools
|
|
63
73
|
geneseed build --emit claude-global --kits none
|
|
64
74
|
```
|
|
65
75
|
|
|
66
76
|
`--kits` takes a comma-separated list. `none` and an empty value both mean no kits. An unknown kit name is refused with exit code 2, and the error lists the kits this Geneseed ships. `none` is reserved and can never name a kit. The flag's row is in the [CLI reference](../reference/cli.md), under `build`.
|
|
67
77
|
|
|
68
|
-
A build does exactly what its flags say
|
|
78
|
+
A build does exactly what its flags say, so a plain `build` without `--kits` would turn off a kit the install has on. Over an existing install it refuses instead: it names the change (`kits: <k> -> none`) and prints the command that keeps the kit. With `--reset` it goes ahead and first warns: `this install has kit <k>; this build turns it off — pass --kits <k> to keep it`.
|
|
69
79
|
|
|
70
80
|
The setup wizard asks one yes/no question per kit, each defaulting to whether the install has that kit on. It asks them only when at least one kit exists.
|
|
71
81
|
|
|
@@ -73,7 +83,7 @@ The setup wizard asks one yes/no question per kit, each defaulting to whether th
|
|
|
73
83
|
|
|
74
84
|
An install with a kit on records it in its instructions file, under the skill section: `Active kits: spring-boot`. The line is written only when at least one kit is on. A missing line means no kits, so an install built before kits existed reads as having none.
|
|
75
85
|
|
|
76
|
-
`geneseed rebuild-all`, `geneseed update` and `geneseed migrate` read the line back and rebuild with the same kits. `geneseed diff` and the web console read it too, so they compare against or rebuild that same set. `geneseed validate` does not read it: pass `--kits` to dry-run a kit build. A plain `build` does not read it; it
|
|
86
|
+
`geneseed rebuild-all`, `geneseed update` and `geneseed migrate` read the line back and rebuild with the same kits. `geneseed diff` and the web console read it too, so they compare against or rebuild that same set. `geneseed validate` does not read it: pass `--kits` to dry-run a kit build. A plain `build` does not read it; it refuses or warns, as above. If the line names a kit this Geneseed no longer ships, the rebuild drops that kit with a notice and keeps the others. It never fails `rebuild-all`. A retired kit name is never reused for a new kit.
|
|
77
87
|
|
|
78
88
|
`geneseed status` shows `kits: spring-boot` on the install's row, and `status --json` carries the same list.
|
|
79
89
|
|
|
@@ -43,6 +43,6 @@ the repository.
|
|
|
43
43
|
- **`fitness-define`** (`enforce-architecture-rule`) reaches for ArchUnit first on Java — a
|
|
44
44
|
`FreezingArchRule`, whose violation store doubles as the allowlist of today's violations —
|
|
45
45
|
before dependency-cruiser, import-linter, eslint-plugin-boundaries or size-limit elsewhere.
|
|
46
|
-
- **`
|
|
47
|
-
already records consumer contracts, as the check
|
|
48
|
-
|
|
46
|
+
- **`compat-check`** (`update-contract`) treats Pact or Spring Cloud Contract, where the repo
|
|
47
|
+
already records consumer contracts, as the check it runs against each step rather than only
|
|
48
|
+
the consumers' own test suites.
|
package/docs/concepts/loops.md
CHANGED
|
@@ -27,10 +27,12 @@ array names every cycle that is allowed to exist, each with a `max` number of ti
|
|
|
27
27
|
it may be re-entered. Picture it as rings: the outer ring is the iteration itself (plan, apply,
|
|
28
28
|
test, review, back to plan), and inner rings sit inside it for retries (apply failed its test, try
|
|
29
29
|
`apply` again without going all the way back around). The shipped templates that center on
|
|
30
|
-
`apply` — `bugfix`, `feature`, `refactor`, `tdd`, `legacy-refactor`, `deps-upgrade`
|
|
31
|
-
short
|
|
32
|
-
`review-fix` ring around that. `legacy-tests
|
|
33
|
-
|
|
30
|
+
`apply` — `bugfix`, `feature`, `refactor`, `tdd`, `legacy-refactor`, `deps-upgrade` among them —
|
|
31
|
+
all nest a short retry ring inside the iteration ring (`apply`↔`test`; `apply`↔`flake-check` in
|
|
32
|
+
`fix-flaky-tests`), and most nest a second, wider `review-fix` ring around that. `legacy-tests`,
|
|
33
|
+
`ci-repair` and `architecture-decision` have no `apply` at all: the first only ever writes
|
|
34
|
+
tests, the second repairs CI directly through `ci-fix`, the third drafts a decision record and
|
|
35
|
+
challenges it.
|
|
34
36
|
|
|
35
37
|
Work closes into a commit whenever the graph re-enters the iteration loop's head — so any setup
|
|
36
38
|
work before the loop starts (reproducing a bug, say) is its own unit, numbered iteration 0, kept
|
|
@@ -30,7 +30,7 @@ sensitive: # always a checkpoint, whatever the granularity
|
|
|
30
30
|
- src/main/resources/db/migration/**
|
|
31
31
|
```
|
|
32
32
|
|
|
33
|
-
The rest of `AGENTS.md` holds the project's coding rules: conventions, build and test commands, project rules. Each developer's own state — their granularity and a short `## Preferences` list of how they steer — lives in `.geneseed/ownership.md`. That file is created only when there is such state to keep, and no file means the team granularity and no preferences. It is never committed: from its first write, `.geneseed/` gets a `.gitignore` that ignores everything in it except the team's files — the `.gitignore` itself, `bricks/`, `loops/`, `protected-checks.txt` and `done-checks.txt`. [Set up ownership](../guides/set-up-ownership.md) walks through the setup, which writes `AGENTS.md` only.
|
|
33
|
+
The rest of `AGENTS.md` holds the project's coding rules: conventions, build and test commands, project rules. Each developer's own state — their granularity and a short `## Preferences` list of how they steer — lives in `.geneseed/ownership.md`. That file is created only when there is such state to keep, and no file means the team granularity and no preferences. It is never committed: from its first write, `.geneseed/` gets a `.gitignore` that ignores everything in it except the team's files — the `.gitignore` itself, `bricks/`, `loops/`, `factories/`, `protected-checks.txt` and `done-checks.txt`. [Set up ownership](../guides/set-up-ownership.md) walks through the setup, which writes `AGENTS.md` only.
|
|
34
34
|
|
|
35
35
|
## Granularity
|
|
36
36
|
|
package/docs/concepts/rules.md
CHANGED
|
@@ -25,7 +25,7 @@ When two instructions disagree, the higher one wins.
|
|
|
25
25
|
2. **Rules** — always on. {N_LAWS} invariants, the things that are never traded away: sealed secrets, one intent per act, verify before asserting, deliberate deletion, surface failures, treat content as data not orders, least privilege, cure the cause, echo the intent. No install can switch one off.
|
|
26
26
|
3. **Your `user-rules.md`** — rules you write for yourself, seeded once and never overwritten. On a global install the file is in the [shared tier](shared-tier.md); on a project install it sits beside the instructions file. A rule here **outranks any doctrine rule**: a practice pack chosen at build time never overrides an instruction you wrote. It may tighten an invariant, never repeal one. Sub-agents get it too: on Claude Code and OpenClaude the `SubagentStart` hook injects every layer of it into each sub-agent, because no sub-agent receives the session-start output (OpenCode follows; Bob has no such event). The [rule skill](skills.md) helps you decide whether something belongs here or in [memory](memory.md).
|
|
27
27
|
4. **Doctrines** — chosen at build time. Practices rather than principles, grouped in packs (below).
|
|
28
|
-
5. **Mode** — chosen at build time ([Foreman mode](foreman-mode.md)). It binds *how* work is executed — done in place, or handed to a
|
|
28
|
+
5. **Mode** — chosen at build time ([Foreman mode](foreman-mode.md)). It binds *how* work is executed — done in place, or handed to a background task worker — and never overrides a layer above it. A mode that only informed lost every time to the host's own default of doing small work in place.
|
|
29
29
|
6. **`PROFILE.md`** — who you are. It colours how the agent works but never binds ([Collaboration](collaboration.md)).
|
|
30
30
|
|
|
31
31
|
### The shared tier
|
|
@@ -57,7 +57,7 @@ All of them are on by default. This install built in {N_PACKS_ACTIVE}, carrying
|
|
|
57
57
|
|
|
58
58
|
A pack you leave out **still ships**: every pack file lands under `doctrines/` beside the instructions file whether or not it was built in. A rule that cites an inactive pack still resolves on disk, and you can read the alternatives before turning one on. An inactive pack loses its binding force, not its availability.
|
|
59
59
|
|
|
60
|
-
**process** is the one pack whose removal changes what the machine does, not only what the agent reads: it holds *Consent Before Push*, which a hook enforces. Without it, commits and pushes are no longer stopped for a question — destructive git still is, because that is a Rule ([Hooks](hooks.md)).
|
|
60
|
+
**process** is the one pack whose removal changes what the machine does, not only what the agent reads: it holds *Consent Before Push*, which a hook enforces: the main branch changes only through a pull request with green checks, and your own branch takes commits and plain pushes freely (or every commit and push asks, with `--strict-consent`). Without it, commits and pushes are no longer stopped for a question — destructive git still is, because that is a Rule ([Hooks](hooks.md)).
|
|
61
61
|
|
|
62
62
|
### Themes do not move rules
|
|
63
63
|
|
package/docs/concepts/skills.md
CHANGED
|
@@ -42,7 +42,7 @@ The full list, with each description, is in the catalog.
|
|
|
42
42
|
|
|
43
43
|
### Skills improve themselves
|
|
44
44
|
|
|
45
|
-
Every skill ends with one beat of reflection: if a step misled or a step was missing, the agent writes the exact correction, with no prompt, into that skill's notes file, `notebook/skill-notes/<name>.md` (`notes/skill-notes/<name>.md` in the [shared tier](shared-tier.md) on a global install), and reads those notes the next time the skill runs. It never edits the installed skill itself: that file is rendered from `src/`, a rebuild would overwrite the edit, and
|
|
45
|
+
Every skill ends with one beat of reflection: if a step misled or a step was missing, the agent writes the exact correction, with no prompt, into that skill's notes file, `notebook/skill-notes/<name>.md` (`notes/skill-notes/<name>.md` in the [shared tier](shared-tier.md) on a global install), and reads those notes the next time the skill runs. It never edits the installed skill itself: that file is rendered from `src/`, and a rebuild would overwrite the edit. A bundled script that is broken is the one exception: fix it in place, and tell the user which file you changed. Agents work the same way through `agent-notes/`. Each note is one line that carries its evidence, `- [skill|general] <correction> [— situation: <when it applies>] — seen: <what happened, against what was expected> (<date>)`: `situation:` says where the correction holds (it is optional, and older lines without it stay valid; without it, the circumstance in `seen:` stands in), `seen:` is what you judge the correction by before folding it in, and `general` marks one that belongs in a law, doctrine or memory rather than in that one skill. `geneseed diff` lists the notes so you can fold them back into `src/`. Folding a skill or agent note is your call: the `skill-forge` skill first replays one past task whose original ask still exists, as two dispatched agents from the pre-fix revision, one told to read no notes and one given the note. The `fresh-eyes` skill freezes one rubric from the ask and judges both results blind against it. A note is folded only when it wins, on the result or on a stated process gain; on a tie or a loss you decide whether to keep or delete it. A trivial wording fix skips that probe. Most runs end with nothing to change.
|
|
46
46
|
|
|
47
47
|
### Old names keep working
|
|
48
48
|
|
package/docs/extending.md
CHANGED
|
@@ -6,7 +6,7 @@ doctrine rule, one skill, one plugin, one hook verb, one doc page, one theme, on
|
|
|
6
6
|
It exists because the answer is never one file. Every user-visible noun in Geneseed has
|
|
7
7
|
*satellites* — a themed title in fourteen voices, a class in a hand-written map, a count in a
|
|
8
8
|
badge, a row in a ledger, a page in the console — and the gates that keep them in step are spread
|
|
9
|
-
across `doctor`, the Node suite and
|
|
9
|
+
across `doctor`, the Node suite and the CI jobs (§1). A contributor who knows the satellites ships in
|
|
10
10
|
one pass; one who does not discovers them one red gate at a time.
|
|
11
11
|
|
|
12
12
|
The governance surface is three tiers and they cost very different amounts. **Adding a doctrine
|
|
@@ -53,12 +53,13 @@ literally, on the screen, as those nine characters.
|
|
|
53
53
|
|
|
54
54
|
Typing a literal number into a `docs/web` page is caught by `proseMirrorProblems`. The README
|
|
55
55
|
badges and prose, and the `N laws, N agents, N skills` line in `SHIPPED.md`, are the hand-written
|
|
56
|
-
exceptions — and each has its own arm in `js/inspect/
|
|
57
|
-
badge keys `agents`/`skills`/`laws`/`themes`/`plugins
|
|
56
|
+
exceptions — and each has its own arm in `js/inspect/checks-counts.mjs` (`countTableProblems` walks
|
|
57
|
+
the six badge keys `agents`/`skills`/`laws`/`doctrines`/`themes`/`plugins`, `doctrines` riding the
|
|
58
|
+
laws badge as `+ N doctrines`; `proseMirrorProblems` holds the prose).
|
|
58
59
|
|
|
59
60
|
---
|
|
60
61
|
|
|
61
|
-
## 1 — The baseline, and the
|
|
62
|
+
## 1 — The baseline, and the commands that reproduce CI
|
|
62
63
|
|
|
63
64
|
The baseline is whatever these commands report on your checkout — run them; no count is
|
|
64
65
|
written here, because a typed count is stale by the next commit.
|
|
@@ -68,6 +69,14 @@ Windows (the suite in shards, which `suite-count` sums), `node-cells` on Linux *
|
|
|
68
69
|
`package-no-python`, `web`, `audit` and `links` on Linux; `ci-ok` is the one required check. From
|
|
69
70
|
the repo root — never from a worktree, see §5.3:
|
|
70
71
|
|
|
72
|
+
```bash
|
|
73
|
+
npm run lint
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
npm run typecheck
|
|
78
|
+
```
|
|
79
|
+
|
|
71
80
|
```bash
|
|
72
81
|
node bin/geneseed-cli.mjs doctor --all
|
|
73
82
|
```
|
|
@@ -76,6 +85,14 @@ node bin/geneseed-cli.mjs doctor --all
|
|
|
76
85
|
node --test --test-reporter=tap "tests/**/*.test.mjs"
|
|
77
86
|
```
|
|
78
87
|
|
|
88
|
+
```bash
|
|
89
|
+
node tests/shim_intact.mjs
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
node --test --test-reporter=tap "fuzz/*.fuzz.mjs"
|
|
94
|
+
```
|
|
95
|
+
|
|
79
96
|
```bash
|
|
80
97
|
node tests/golden.mjs --idempotent
|
|
81
98
|
```
|
|
@@ -114,12 +131,12 @@ Notes that matter:
|
|
|
114
131
|
a `find` that stops matching exactly once fails the cell loudly.
|
|
115
132
|
- `--deletion` is the only thing that exercises the write-before-delete prune. Anyone renaming or
|
|
116
133
|
removing a plugin, a skill or an emitted file needs it.
|
|
117
|
-
- **A local pass is weaker than CI.**
|
|
118
|
-
`{ skip: NO_NPM }`
|
|
134
|
+
- **A local pass is weaker than CI.** The tests in `tests/unit/package_manifest.test.mjs` that carry
|
|
135
|
+
`{ skip: NO_NPM }` are every tarball, install and rename gate. On a machine without `npm`
|
|
119
136
|
on PATH they report *skipped* and the run is green.
|
|
120
137
|
- CI additionally re-runs the packaging suite under `npm@11`, the release's npm (Linux, last in the job), and
|
|
121
138
|
packs the tarball into a `node:22-slim` container with no interpreter. Neither is reproducible
|
|
122
|
-
from the
|
|
139
|
+
from the commands above; the container one is reachable locally through
|
|
123
140
|
`tests/helpers/no-python-container.sh` with a docker daemon.
|
|
124
141
|
- **Two assertions in `tests/unit/claude.test.mjs` silently stand down** on any machine where an
|
|
125
142
|
ancestor of the temp sandbox is a `.claude`/`.bob`/`.openclaude` install — which is every developer machine
|
|
@@ -128,9 +145,10 @@ Notes that matter:
|
|
|
128
145
|
|
|
129
146
|
### The gates CI does not run
|
|
130
147
|
|
|
131
|
-
- **The mutation matrix itself.** `tests/mutate.mjs` —
|
|
132
|
-
product file with a written argument for which gate should catch it. The
|
|
133
|
-
workflow** and should not be: it mutates the product tree
|
|
148
|
+
- **The mutation matrix itself.** `tests/mutate.mjs` — a table of rows (`--list` prints them), each a
|
|
149
|
+
one-string edit to a product file with a written argument for which gate should catch it. The
|
|
150
|
+
full run is **in no workflow** and should not be: it mutates the product tree once per row and
|
|
151
|
+
runs a gate per edit.
|
|
134
152
|
Run `node tests/mutate.mjs --all` (or `--only M7`) by hand when you change something a gate is
|
|
135
153
|
supposed to be watching. ⚠ An interrupted run leaves the **product tree mutated** — check
|
|
136
154
|
`git status` before doing anything else.
|
|
@@ -148,7 +166,8 @@ Notes that matter:
|
|
|
148
166
|
gate `publish.yml`'s shape (found by `publishWorkflow`), and the test *every workflow that
|
|
149
167
|
count-gates `node --test` pins the TAP reporter* discovers every workflow with a test-count gate
|
|
150
168
|
and pins `--test-reporter=tap` on each `node --test` line. A unit test gates the CI files.
|
|
151
|
-
- **Adding any tracked file** — `tests/unit/package_manifest.test.mjs
|
|
169
|
+
- **Adding any tracked file** — `tests/unit/package_manifest.test.mjs` (*every tracked file matches
|
|
170
|
+
exactly one side of the partition*) demands every tracked
|
|
152
171
|
path fall on exactly one side of a declared partition, *with a written reason*. Adding this very
|
|
153
172
|
document required a `SHIPS` row; without one the tarball test fails, and it fails **before** the
|
|
154
173
|
file is committed too, because npm packs by glob while the partition reads `git ls-files`.
|
|
@@ -181,7 +200,7 @@ not.
|
|
|
181
200
|
|
|
182
201
|
### 2a — Adding a DOCTRINE RULE (the common case)
|
|
183
202
|
|
|
184
|
-
|
|
203
|
+
Five steps, plus the written-out rule totals in the test files named below. This is the slot most new
|
|
185
204
|
material belongs in, and it is cheap on purpose so that the invariant slot stays scarce.
|
|
186
205
|
|
|
187
206
|
1. `src/doctrines/<pack>.md` — add `### {{DOCTRINE:<new-id>}} <Principle Name>` plus the body,
|
|
@@ -211,13 +230,17 @@ material belongs in, and it is cheap on purpose so that the invariant slot stays
|
|
|
211
230
|
`cmdBuild` (`BUILD_FORWARD`) does not forward `--sync-themes`. Then restyle all
|
|
212
231
|
fourteen by hand: `--sync-themes` writes the template's placeholder and only *prints*
|
|
213
232
|
`RESTYLE these`; a shipped placeholder passes every gate.
|
|
214
|
-
4. `
|
|
233
|
+
4. `README.md` — the `+ N doctrines` half of the laws badge (`badge/laws-N%20%2B%20N%20doctrines`).
|
|
234
|
+
`countTableProblems` holds it to the rule count across every pack, so `doctor` is red until it
|
|
235
|
+
is bumped.
|
|
236
|
+
5. `CHANGELOG.md`.
|
|
215
237
|
|
|
216
238
|
**What a doctrine rule does *not* cost**, and each of these is a deliberate asymmetry:
|
|
217
239
|
|
|
218
240
|
- **No class entry.** There is no `LAW_CLASS` analogue: a doctrine rule's class *is* its pack, and
|
|
219
241
|
there is no second taxonomy over it.
|
|
220
|
-
- **
|
|
242
|
+
- **One count in the product, and only one.** The README laws badge (step 4); no `SHIPPED.md`
|
|
243
|
+
triple, no prose mirror. The console spends
|
|
221
244
|
`{N_PACKS}` / `{N_PACKS_ACTIVE}` / `{N_DOCTRINE_RULES}`, all computed at request time.
|
|
222
245
|
- **No citation to rewire.** But there *are* written-out rule totals to bump — expected values are
|
|
223
246
|
written out, never recorded — in `tests/unit/emit_smoke.test.mjs`, `harness.test.mjs`,
|
|
@@ -229,6 +252,13 @@ material belongs in, and it is cheap on purpose so that the invariant slot stays
|
|
|
229
252
|
`full` carrier ceiling in `emit_smoke` — raise it with a dated note there, as every earlier
|
|
230
253
|
move did.
|
|
231
254
|
|
|
255
|
+
⚠ **A doctrine citation in carrier text stands alone in its parentheses.** In
|
|
256
|
+
`src/AGENT.md.tmpl`, `src/modes/`, `src/postures/`, `src/doctrines/` and a kit's `rules.md`, write `… so X
|
|
257
|
+
({{DOCTRINE:<id>}})`, never `({{DOCTRINE:<id>}} says X)`. `dropExcludedCitations`
|
|
258
|
+
(`js/build/render.mjs`) removes an excluded rule's citation from the carrier only when its group
|
|
259
|
+
holds citations alone; `citationGroupProblems` (`js/inspect/checks-constitution.mjs`) refuses
|
|
260
|
+
anything else. A prose mention outside parentheses is fine.
|
|
261
|
+
|
|
232
262
|
⚠ **Cite only downward.** An always-on tier may never reference a toggleable one:
|
|
233
263
|
`constitutionProblems` refuses a `{{DOCTRINE:…}}` token anywhere under `src/ontology/` or
|
|
234
264
|
`src/laws/`, because a `--doctrines craft` build would then ship an invariant pointing at text its
|
|
@@ -355,8 +385,8 @@ candidate for routing to choose between, so add only what no sharpened existing
|
|
|
355
385
|
|
|
356
386
|
**Order matters at the first two steps.** `missingReferencedSpecs` (in `js/build/bundle.mjs`) *aborts the
|
|
357
387
|
build* when `AGENT.md.tmpl` names a spec with no file — so the file comes before the table row, or
|
|
358
|
-
nothing builds at all. The refusal is clean: `tests/unit/emit_gates.test.mjs
|
|
359
|
-
emit leaves the prior install intact.
|
|
388
|
+
nothing builds at all. The refusal is clean: `tests/unit/emit_gates.test.mjs` (*a missing agent aborts a
|
|
389
|
+
global emit and leaves the install intact*) proves a refused emit leaves the prior install intact.
|
|
360
390
|
|
|
361
391
|
1. `src/skills/<name>.md` or `src/agents/<name>.md`. The shape is load-bearing: `# {{SKILL}}: <name>`,
|
|
362
392
|
a blank line, then a `>` blockquote holding `{{DESC_<NAME>}}` — title, blockquote, nothing
|
|
@@ -383,8 +413,8 @@ emit leaves the prior install intact.
|
|
|
383
413
|
never fires. Hand-run, spends model calls on your own login, not part of the suite.
|
|
384
414
|
|
|
385
415
|
**A vendored skill folder** (`src/skills/<name>/SKILL.md`) is a different shape: add it to
|
|
386
|
-
`VENDORED_SKILL_DIRS` (`js/hosts/native.mjs
|
|
387
|
-
`tests/unit/authoring_gates.test.mjs
|
|
416
|
+
`VENDORED_SKILL_DIRS` (`js/hosts/native.mjs` — the literal is frozen in
|
|
417
|
+
`tests/unit/authoring_gates.test.mjs`), add a `src/upstreams.json` entry (`repo`, `commit` —
|
|
388
418
|
a 40-hex commit, never a moving branch — `author`, `license`, and `licenseFile`, a path under
|
|
389
419
|
`src/` or `null`; an optional `"frozen": true` marks text left at its pin on purpose: the weekly drift job skips it, `creditProblems` still validates it), write a `VENDOR.md` carrying `**Upstream key:** <that key>` and a
|
|
390
420
|
`{{CREDIT:<key>:<upstream path>}}` line, which renders the attribution into every install (the
|
|
@@ -412,8 +442,8 @@ distinguishes it from first-party text.
|
|
|
412
442
|
Two traps worth knowing before you write the spec:
|
|
413
443
|
|
|
414
444
|
- **The word "Read-only" anywhere in an agent spec locks its emit.** It is a bare substring test
|
|
415
|
-
(`js/hosts/native.mjs
|
|
416
|
-
re-opens bash on
|
|
445
|
+
(`isReadonly` in `js/hosts/native.mjs`). The escape hatches are explicit markers: `<!-- bash: allow -->`
|
|
446
|
+
re-opens bash on every host (OpenCode gates it to `ask`), and `<!-- webfetch: allow -->`
|
|
417
447
|
re-opens web fetch — the researcher is the one spec that carries it.
|
|
418
448
|
- **The console has a fourth, ungated copy of the skill taxonomy.** `SKILL_CATS` in
|
|
419
449
|
`web/src/lib/lawCats.js` mirrors `SKILL_CLASS` with nothing comparing them (contrast the
|
|
@@ -429,7 +459,10 @@ OpenClaude and Bob get a user-only `skills/<alias>/SKILL.md`, and OpenCode gets
|
|
|
429
459
|
now excludes the merged skill (`resolveSkillNames` in `js/build/source.mjs`), so a rebuild still
|
|
430
460
|
works. A skill removed with no successor goes into `RETIRED_SKILL_IDS` in the same file: its
|
|
431
461
|
exclusion is dropped with a notice instead of failing the rebuild, and the name can never be
|
|
432
|
-
used for a new skill. The
|
|
462
|
+
used for a new skill. The one exception is a skill that comes back for the same tool, where an
|
|
463
|
+
old exclusion keeps its meaning: `herdr` left the list when the terminal-tools kit brought it
|
|
464
|
+
back. Such a name moves to `REVIVED_SKILL_IDS`, so an older build's unowned render under it is
|
|
465
|
+
still moved aside on a canonical global emit, with the kit on or off. The doctor (`aliasProblems`) refuses an alias that is malformed, duplicated,
|
|
433
466
|
already a skill, retired, or the name of an OpenCode command.
|
|
434
467
|
|
|
435
468
|
**A rarely-needed half goes in a side file.** A skill body is paid in full every time the skill
|
|
@@ -553,7 +586,8 @@ The `geneseed-` prefix and the `.js` suffix are mechanically load-bearing: the b
|
|
|
553
586
|
4. `docs/concepts/host-matrix.md` — check the capability matrix still tells the truth.
|
|
554
587
|
5. `README.md` — **three** sites: the badge, the `N plugins` prose, and the 🔌 Plugins row.
|
|
555
588
|
6. `SHIPPED.md` — the bare name inside `plugins (…)`; that list must equal the directory exactly,
|
|
556
|
-
in both directions (`tests/unit/web_api_docs.test.mjs
|
|
589
|
+
in both directions (`tests/unit/web_api_docs.test.mjs`, *every plugin ships a reference page and
|
|
590
|
+
its README/SHIPPED rows*).
|
|
557
591
|
7. `adapters/opencode/README.md` and `docs/opencode-plugin-setup.md` — spelled-out counts, in
|
|
558
592
|
**word form** ("seven" → "eight"), the second file twice.
|
|
559
593
|
8. `tests/plugins/<name>.test.mjs`. Auto-discovered; no workflow edit.
|
|
@@ -668,7 +702,8 @@ rather than assumed:
|
|
|
668
702
|
`git ls-files --cached --others --exclude-standard`, which honours `.gitignore`, and
|
|
669
703
|
`.gitignore` ignores `/node_modules/`. The copy is written outside the repository, under the OS
|
|
670
704
|
temp root, and the product is run out of it as a real child process — so Node's upward resolver
|
|
671
|
-
walk starts in temp and finds nothing.
|
|
705
|
+
walk starts in temp and finds nothing. Every test file that calls `copyCheckout` builds such a
|
|
706
|
+
copy. And this is not a
|
|
672
707
|
fixture defect to work around: a user's fresh `git clone` has no `node_modules` either. **The
|
|
673
708
|
fixture is that clone.** Giving the fixture something the real install lacks makes it stop
|
|
674
709
|
reproducing the failure it exists to catch.
|
|
@@ -721,7 +756,7 @@ anything owns **every** install's hooks. Emitting from a git worktree or a temp
|
|
|
721
756
|
repoint the shim at that disposable path; removing the worktree then killed hooks for every
|
|
722
757
|
install on the machine.
|
|
723
758
|
|
|
724
|
-
**`hookPrefix` now refuses the claim** (`js/hosts/
|
|
759
|
+
**`hookPrefix` now refuses the claim** (`js/hosts/shim.mjs`, `ephemeralCheckout`): an emit whose
|
|
725
760
|
checkout is under the OS temp root, or is a linked git worktree (`.git` is a *file*), leaves a
|
|
726
761
|
shim that still resolves exactly as it is and wires the emitted hooks to it anyway. The bundle it
|
|
727
762
|
writes is byte-identical to a normal emit — the install simply keeps running the durable
|
|
@@ -739,7 +774,7 @@ CI's `.suite-fence`, any file in the tier.
|
|
|
739
774
|
|
|
740
775
|
This is not hypothetical — it happened while this file was being written. Several agents were
|
|
741
776
|
verifying gates out of copied checkouts (the `copyCheckout` fixture pattern
|
|
742
|
-
`tests/unit/harness.test.mjs
|
|
777
|
+
`tests/unit/harness.test.mjs` uses), one of them emitted, and the shim ended up pointing at
|
|
743
778
|
`…/Temp/gs-fix-8DYuJP/bin/geneseed-hook.mjs` — a directory that no longer existed. Every hook in
|
|
744
779
|
every install on the machine was dead and nothing said so.
|
|
745
780
|
|
|
@@ -764,7 +799,7 @@ The CLI surface is no longer the most expensive thing in the repo to change. Edi
|
|
|
764
799
|
text or flags is now an ordinary edit: `js/cli-table.json` is the owned document, and
|
|
765
800
|
`tests/unit/text_layout.test.mjs` renders every verb through `formatHelp` to check the layout
|
|
766
801
|
holds. Three hand-written equalities still converge on it and are cheap to keep in step — the
|
|
767
|
-
|
|
802
|
+
command count and the hidden-argument rule (`tests/unit/cli_table.test.mjs`), and
|
|
768
803
|
`tests/unit/docs.test.mjs`, which validates every fenced `geneseed <verb> <flags>` line in
|
|
769
804
|
`README.md`, `SHIPPED.md` and every page under `docs/{understand,guides,concepts,reference}/` against the table.
|
|
770
805
|
|
|
@@ -779,7 +814,7 @@ only, at best, on its presence.
|
|
|
779
814
|
|---|---|---|
|
|
780
815
|
| `§N` cross-references into `AGENT.md`'s anatomy | `src/skills/*`, `src/agents/*`, `adapters/**` | **range only.** `constitutionProblems` refuses a `§N` the template declares no section for — which catches a pointer past the end, the shape *removing* a section leaves. It cannot catch one that still resolves and now means something else, which is the shape *inserting* a section leaves, and is what actually happened when `## 2. Doctrines` pushed every later section down one. **Renumbering the anatomy means `grep -rn '§' src/ adapters/` and reading every hit.** Four satellites and a live OpenCode deny message shipped stale because the sweep stopped at `AGENT.md.tmpl` |
|
|
781
816
|
| Per-rule Principle lines | the `<!-- note: summary: … -->` line under each rule heading in `src/laws/universal.md` and `src/doctrines/*.md` | presence and placement only (`ruleSummaryProblems`), never accuracy |
|
|
782
|
-
|
|
|
817
|
+
| The themed constitution titles, one key per rule and per pack in each of the 14 voices — `LEX_<ID>` (one per law), `DOC_<ID>` (one per doctrine rule), `PACK_<NAME>` | `themes/*.json` | key presence only — a shipped placeholder is green. `LEX_*` and `DOC_*` are held across the template too, and in both directions; `PACK_*` only across the voices |
|
|
783
818
|
| The README keyword enumerations | `README.md`, `docs/concepts/rules.md` | nothing |
|
|
784
819
|
| The per-host map of what lands on a machine | `docs/understand/machine-opencode.md`, `docs/understand/machine-claude.md` | table shape only, never accuracy |
|
|
785
820
|
| Section labels and page subtitles | `web/src/lib/sections.js`, `web/src/pages/Docs/index.jsx` | nothing |
|
|
@@ -814,7 +849,7 @@ gated. Every other appearance is derived at runtime (`.geneseed-version` markers
|
|
|
814
849
|
why no test pins a version string and none should.
|
|
815
850
|
|
|
816
851
|
Do not run `npm version`. Bump the two files by hand, add the `CHANGELOG` section, update
|
|
817
|
-
`SHIPPED.md`, rebuild `web/dist` if `web/src` moved, run the
|
|
852
|
+
`SHIPPED.md`, rebuild `web/dist` if `web/src` moved, run the commands from §1, and merge to
|
|
818
853
|
`main`. **The bump is the release** (since 2026-10-23): when CI finishes green on that push,
|
|
819
854
|
`publish.yml` sees a version npm does not have, re-runs its gates, publishes it, and creates the
|
|
820
855
|
`v<version>` tag and the GitHub release from the version's CHANGELOG section. A push that does not
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
---
|
|
2
|
+
group: guides
|
|
3
|
+
order: 24.6
|
|
4
|
+
title: "Auto-merge green PRs"
|
|
5
|
+
kind: "concept"
|
|
6
|
+
section: "Factories"
|
|
7
|
+
description: "Let the forge merge a PR the agent opens once its required checks are green: how to turn it on and off, the forge settings it needs, and the three tiers."
|
|
8
|
+
---
|
|
9
|
+
Auto-merge ships **off**. When it is off, the agent opens a PR and the merge stays yours. When you
|
|
10
|
+
turn it on, the agent arms the forge's own auto-merge on a PR it opens, and the forge merges the
|
|
11
|
+
PR when its required checks pass. The agent never decides that a PR is green: the forge does
|
|
12
|
+
(`external-gate`).
|
|
13
|
+
|
|
14
|
+
## Turn it on or off
|
|
15
|
+
|
|
16
|
+
Say **"turn on auto-merge"**. The `rule` skill asks one question, every repo or this project only,
|
|
17
|
+
then shows a standing rule for `user-rules.md` and writes it on your yes:
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
## R<n> — Auto-merge green PRs
|
|
21
|
+
(scope: global | source: user, <date>)
|
|
22
|
+
Arm auto-merge on a PR I open, only when the forge has required checks.
|
|
23
|
+
- docs-tests: auto
|
|
24
|
+
- normal: human # human | reviewer
|
|
25
|
+
- sensitive: never
|
|
26
|
+
- Before any further push to a PR with auto-merge armed, disarm it first, then classify, review and arm again on the new head.
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
The rule files are layered: shared, then host, then project, and the later layer wins. So a
|
|
30
|
+
global rule sets the default and a project's own copy overrides it. To turn it off, say **"turn
|
|
31
|
+
off auto-merge"**: the agent removes the rule, or writes a project copy with all three tier lines
|
|
32
|
+
`never`. When a repo has no rule, the agent tells you once per session in that repo, when it
|
|
33
|
+
opens a PR there, that auto-merge is off and how to turn it on.
|
|
34
|
+
|
|
35
|
+
The rule is your durable authorization for the forge's merge (`deletion-is-deliberate`). It arms
|
|
36
|
+
only that merge. Pushes still follow `consent-before-push`: a plain push of your own branch goes
|
|
37
|
+
through, and a push onto the main branch asks you.
|
|
38
|
+
|
|
39
|
+
## The tiers
|
|
40
|
+
|
|
41
|
+
The agent sorts each PR by its diff, the first match wins:
|
|
42
|
+
|
|
43
|
+
| Tier | When | Accepted values |
|
|
44
|
+
|---|---|---|
|
|
45
|
+
| `sensitive` | Any file in a sensitive zone: each `sensitive:` zone of the ownership block in the **base** branch's `AGENTS.md` (see [Set up ownership](set-up-ownership.md)), plus auth and authz, secrets and credentials, data migrations and schema, CI and deploy config, dependency manifests and lockfiles, release and versioning, gate and hook config, `AGENTS.md`, `CLAUDE.md`, `CODEOWNERS`, any `user-rules.md`, agent, skill and instruction files, and gate machinery (check scripts, CI-only harnesses, coverage thresholds; not ordinary unit tests) | None: it never arms, whatever the rule says |
|
|
46
|
+
| `docs-tests` | Every file is docs (prose that is neither shipped nor executed) or tests, and no test or assertion is removed, skipped or loosened (that diff is `normal`) | `auto`, `human`, `reviewer`, `never` |
|
|
47
|
+
| `normal` | Anything else | `human`, `reviewer`, `never` (`auto` is not valid) |
|
|
48
|
+
|
|
49
|
+
`auto` arms. `human` arms only when the forge also requires one approving review and dismisses it on a new push. `reviewer` arms
|
|
50
|
+
after the agent's blind reviewer passes, with its verdict added to the PR body first (in a factory,
|
|
51
|
+
the `review-panel` verdict). `never` does not arm. A missing or other value counts as `human`. Use `reviewer` only in a solo repo: GitHub does not
|
|
52
|
+
let you approve your own PR, and a PR the agent opens carries your identity, so `human` would never
|
|
53
|
+
merge there.
|
|
54
|
+
|
|
55
|
+
## Forge settings it needs
|
|
56
|
+
|
|
57
|
+
The agent arms auto-merge only when it can read all of these. When it cannot, it does not arm, and
|
|
58
|
+
the merge stays yours.
|
|
59
|
+
|
|
60
|
+
| Setting | GitHub (how the agent reads it) | GitLab |
|
|
61
|
+
|---|---|---|
|
|
62
|
+
| Auto-merge allowed | Settings › General › *Allow auto-merge* (`gh repo view --json autoMergeAllowed`) | No switch: GitLab offers auto-merge on every project, so the agent checks this on GitHub only |
|
|
63
|
+
| Required checks on the base branch | A ruleset (`required_status_checks` in `gh api repos/{owner}/{repo}/rules/branches/<base>`) or branch protection (`required_status_checks` in `.../branches/<base>/protection`), with a non-empty list of checks: an empty list requires nothing, and `--auto` then merges at once | *Pipelines must succeed* (`only_allow_merge_if_pipeline_succeeds` in `glab api projects/:id`) |
|
|
64
|
+
| One approving review (`human`) | A ruleset `pull_request` rule, or branch protection, with `required_approving_review_count` of 1 or more | An approval rule with `approvals_required` of 1 or more (`glab api projects/:id/approval_rules`) |
|
|
65
|
+
| Stale approvals (required for `human`) | *Dismiss stale pull request approvals when new commits are pushed* (`dismiss_stale_reviews_on_push` in the ruleset, `dismiss_stale_reviews` in the protection) | *Remove all approvals when commits are added* (`reset_approvals_on_push` in `glab api projects/:id/approvals`) |
|
|
66
|
+
| Backstop on sensitive paths (recommended) | `CODEOWNERS` plus *Require review from Code Owners* | `CODEOWNERS` plus code owner approval on the protected branch |
|
|
67
|
+
|
|
68
|
+
The agent arms on the head it classified and reviewed:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
gh pr merge <pr> --auto --squash --match-head-commit <sha>
|
|
72
|
+
glab mr merge <mr> --auto-merge --squash --sha <sha>
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`glab mr merge` arms auto-merge by default, so the agent always names the flag. On GitHub the
|
|
76
|
+
pinned head is checked only when auto-merge is armed: an armed PR stays armed after a later push by
|
|
77
|
+
someone with write access. So before any further push to an armed PR, the agent disarms it
|
|
78
|
+
(`gh pr merge <pr> --disable-auto`; on GitLab, `POST
|
|
79
|
+
projects/:id/merge_requests/:iid/cancel_merge_when_pipeline_succeeds` through `glab api`), then
|
|
80
|
+
classifies, reviews and arms again on the new head. If the head is already green when the agent
|
|
81
|
+
arms, the forge merges at once.
|
|
82
|
+
|
|
83
|
+
## On each host
|
|
84
|
+
|
|
85
|
+
The rule is text in the `ship` and `factory` skills. No Geneseed gate guards a merge command, so all
|
|
86
|
+
four hosts behave the same:
|
|
87
|
+
|
|
88
|
+
| Host | What guards `gh pr merge` / `glab mr merge` |
|
|
89
|
+
|---|---|
|
|
90
|
+
| Claude Code | Nothing: the git gate matches only `git commit` and `git push` |
|
|
91
|
+
| OpenClaude | Same as Claude Code |
|
|
92
|
+
| OpenCode | Nothing: the permission globs cover only `git commit*` and `git push*` |
|
|
93
|
+
| Bob | Nothing: consent is a log line |
|
|
94
|
+
|
|
95
|
+
An MCP merge tool (a GitHub MCP server's merge, or a host's own auto-merge tool) is not a shell
|
|
96
|
+
command, so no shell gate sees it on any host. The forge's required checks and reviews are the
|
|
97
|
+
boundary.
|
|
98
|
+
|
|
99
|
+
A [factory](run-a-factory.md) follows the same rule: at the end of a green run it arms auto-merge
|
|
100
|
+
when the rule allows, and otherwise asks you once whether to merge.
|
|
@@ -14,7 +14,7 @@ All of these choices are made **at build time**. The build writes them into the
|
|
|
14
14
|
|
|
15
15
|
## Theme: the voice
|
|
16
16
|
|
|
17
|
-
A theme changes how the harness *sounds*: the banner, the readiness sigil the agent opens with, and the vocabulary of its prose. It never changes which rules apply or which files ship. The wizard
|
|
17
|
+
A theme changes how the harness *sounds*: the banner, the readiness sigil the agent opens with, and the vocabulary of its prose. It never changes which rules apply or which files ship. The wizard lists each theme with a one-line description.
|
|
18
18
|
|
|
19
19
|
`neutral` is plain English. The others are `imperial`, `military`, `pirate`, `wizard`, `cyberpunk`, `gamer`, `sports`, `biker`, `commentator`, `joker`, `marvin`, `mean` and `verstappen`.
|
|
20
20
|
|
package/docs/guides/headless.md
CHANGED
|
@@ -19,6 +19,6 @@ cat issue.md | opencode run "triage this and propose a fix plan" # pipe inp
|
|
|
19
19
|
|
|
20
20
|
## Things to know
|
|
21
21
|
|
|
22
|
-
- **Permission prompts still apply, and in CI nobody can answer them.** Any command the config marks `ask` blocks a non-interactive run: `
|
|
22
|
+
- **Permission prompts still apply, and in CI nobody can answer them.** Any command the config marks `ask` blocks a non-interactive run: `git commit` and `git push` whenever the *Consent Before Push* rule is built in (OpenCode's globs cannot see the branch, so they ask for every commit and push, not only those onto the main branch) (it is part of the `process` pack; see [Doctrine packs and single rules](setup-doctrines.md)). A CI job that has to commit should set those commands back to `"allow"` in its own `permission.bash` map, or limit the run to read-only work. Do not disable the guards wholesale.
|
|
23
23
|
- **`--pure`** runs OpenCode without any local or global config. Use it to reproduce a bug without the harness in the way, or to confirm that a behaviour comes from the harness.
|
|
24
24
|
- **The plugins still load.** The context plugin injects the repo's docs, and the learn plugin still writes memory when the session goes idle. To change their behaviour for a run, set `GENESEED_GUARD=warn` or `off`, `GENESEED_CONTEXT_INJECT=off`, or `GENESEED_DEBUG=1`. See [Context and memory variables](../reference/env-context.md) and [OpenCode plugins](../reference/opencode-plugins.md).
|
|
@@ -8,7 +8,7 @@ description: "Install from a git clone when npm is out of reach, or when you wan
|
|
|
8
8
|
---
|
|
9
9
|
Clone the repository when npm is out of reach (for example, a corporate network with no registry access), or when you want to change the harness rather than just use it. A clone needs **git** as well as Node 22.7 or newer. git is what updates the clone.
|
|
10
10
|
|
|
11
|
-
Each OS has a one-step installer at the root of the clone. It checks for Node and git
|
|
11
|
+
Each OS has a one-step installer at the root of the clone. It checks for Node and git and names what to install and where to get it. A missing Node stops the installer; a missing git only warns, because setup runs without it and updates need it. **It never installs anything itself.** When the checks pass, it runs the setup wizard (it then runs `geneseed link` if `geneseed` is not on your `PATH`) and offers to open the web console.
|
|
12
12
|
|
|
13
13
|
```bash
|
|
14
14
|
git clone https://github.com/Arylmera/Geneseed.git
|
package/docs/guides/install.md
CHANGED
|
@@ -16,7 +16,7 @@ The only prerequisite is **Node 22.7 or newer**.
|
|
|
16
16
|
npx geneseed setup
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
The command is the same on macOS, Linux and Windows (cmd, PowerShell or any POSIX shell). The setup wizard lists the AI coding tools it found on your `PATH
|
|
19
|
+
The command is the same on macOS, Linux and Windows (cmd, PowerShell or any POSIX shell). The setup wizard lists the AI coding tools it found on your `PATH` or in the usual per-user folders, then asks for a theme, a posture, a mode, the doctrine packs, the kits, an install mode and a footprint. Each one has a safe default, so you can hold Enter through all of them. [Choose your setup](choose-your-setup.md) explains each question. **OpenCode global** is the recommended install mode: you install once and every repo inherits it, with nothing committed into your projects. The wizard then builds the harness and ends with a short summary: the root file your tool loads and where it was written, the hooks it wired (Claude Code, Bob and OpenClaude), whether memory learning is on, which tool to restart, and a link to what was installed. It then offers to run a health check.
|
|
20
20
|
|
|
21
21
|
To keep the command on your machine:
|
|
22
22
|
|