geneseed 5.3.1 → 5.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +102 -0
- package/README.md +51 -18
- package/SHIPPED.md +7 -7
- package/adapters/bob/README.md +12 -1
- package/adapters/opencode/README.md +5 -3
- package/adapters/opencode/plugins/geneseed-context.js +77 -10
- package/adapters/opencode/plugins/geneseed-guard.js +106 -22
- package/adapters/opencode/plugins/geneseed-learn.js +641 -6
- package/bin/geneseed-cli.mjs +10 -0
- package/bin/geneseed-hook.mjs +5 -4
- package/docs/PRD.md +1 -1
- package/docs/README.md +1 -0
- package/docs/concepts/agents.md +14 -2
- 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 +23 -4
- package/docs/concepts/hook-gates.md +4 -4
- package/docs/concepts/hooks.md +25 -7
- package/docs/concepts/host-matrix.md +4 -4
- package/docs/concepts/hosts.md +1 -1
- 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/shared-tier.md +1 -1
- package/docs/concepts/skills.md +21 -1
- package/docs/concepts/themes.md +1 -1
- package/docs/extending.md +73 -29
- 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 +19 -1
- package/docs/guides/install-scripted.md +8 -2
- package/docs/guides/install.md +20 -2
- 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 +2 -2
- package/docs/guides/worktree.md +1 -1
- package/docs/reference/env-context.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 +5 -1
- package/docs/reference/plugin-workflow.md +1 -1
- package/docs/reference/profiles.md +142 -0
- 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 +11 -6
- package/docs/understand/design-choices-engineering.md +1 -1
- 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 +8 -6
- package/harness.config.json +1 -1
- package/js/README.md +11 -3
- package/js/build/args.mjs +16 -4
- package/js/build/catalog.mjs +11 -1
- package/js/build/driver.mjs +74 -16
- package/js/build/emit-claude.mjs +32 -5
- package/js/build/emit-opencode.mjs +16 -9
- package/js/build/export.mjs +1 -1
- package/js/build/generate.mjs +12 -157
- package/js/build/notes-migrate.mjs +99 -0
- package/js/build/profile.mjs +326 -0
- package/js/build/render.mjs +110 -8
- package/js/build/retired-skills.mjs +60 -13
- package/js/build/source.mjs +100 -3
- package/js/build/stubs.mjs +4 -1
- package/js/cli-table.json +212 -7
- package/js/hosts/agent-runs.mjs +205 -0
- package/js/hosts/done-checks.mjs +3 -1
- package/js/hosts/hooks-done.mjs +428 -63
- package/js/hosts/hooks-learn.mjs +89 -3
- package/js/hosts/hooks-prims.mjs +44 -4
- package/js/hosts/hooks.mjs +159 -9
- package/js/hosts/hosts.mjs +10 -0
- package/js/hosts/installs.mjs +44 -2
- package/js/hosts/link.mjs +45 -10
- package/js/hosts/native.mjs +61 -7
- package/js/hosts/opencode.mjs +1 -1
- package/js/hosts/settings.mjs +101 -3
- package/js/hosts/spec-feedback.mjs +538 -0
- package/js/hosts/usage.mjs +67 -8
- package/js/inspect/agent-scores.mjs +118 -0
- package/js/inspect/checks-authoring.mjs +2 -1
- package/js/inspect/checks-build.mjs +20 -4
- package/js/inspect/checks-constitution.mjs +32 -0
- package/js/inspect/checks-repo.mjs +27 -2
- package/js/inspect/cost.mjs +6 -5
- package/js/inspect/diff.mjs +46 -8
- package/js/inspect/doctor.mjs +4 -0
- package/js/inspect/inventory.mjs +1 -1
- package/js/inspect/status.mjs +3 -1
- package/js/inspect/validate.mjs +1 -0
- package/js/lib/machine-dir.mjs +8 -0
- package/js/lib/paths.mjs +4 -1
- package/js/maintain/profile-scope.mjs +145 -0
- package/js/maintain/profiles.mjs +486 -0
- package/js/maintain/setup.mjs +413 -15
- package/js/maintain/uninstall.mjs +4 -1
- package/js/maintain/update.mjs +4 -2
- package/js/web/actions.mjs +44 -41
- package/js/web/api.mjs +13 -3
- package/js/web/handler.mjs +8 -0
- package/js/web/jobs.mjs +5 -4
- package/js/web/profiles-api.mjs +201 -0
- package/js/web/routes.mjs +5 -0
- package/package.json +2 -1
- package/profiles/guillaume-claude-global.json +16 -0
- package/profiles/starter.json +14 -0
- package/registry.json +14 -0
- package/src/AGENT.md.tmpl +16 -18
- package/src/agents/_self-improvement.md +15 -7
- package/src/agents/_template.md +4 -2
- package/src/agents/advocate.md +1 -1
- package/src/agents/architect.md +1 -1
- package/src/agents/developer.md +10 -3
- package/src/agents/devops-engineer.md +1 -1
- package/src/agents/docker-expert.md +1 -1
- package/src/agents/docs.md +1 -1
- package/src/agents/empiricist.md +1 -1
- package/src/agents/explorer.md +4 -2
- package/src/agents/framer.md +1 -1
- package/src/agents/historian.md +1 -1
- package/src/agents/kubernetes-specialist.md +1 -1
- package/src/agents/memory-curator.md +1 -1
- package/src/agents/operator.md +1 -1
- package/src/agents/performance.md +1 -1
- package/src/agents/pragmatist.md +1 -1
- package/src/agents/react-engineer.md +1 -1
- package/src/agents/react-reviewer.md +1 -1
- package/src/agents/researcher.md +1 -1
- package/src/agents/reviewer.md +10 -3
- package/src/agents/security.md +1 -1
- package/src/agents/skeptic.md +1 -1
- package/src/agents/spring-boot-engineer.md +1 -1
- package/src/agents/spring-reviewer.md +1 -1
- package/src/agents/spring-security.md +1 -1
- package/src/agents/steward.md +1 -1
- package/src/agents/tester.md +4 -2
- package/src/agents/user-advocate.md +1 -1
- package/src/agents/visionary.md +1 -1
- 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/memory/README.md +12 -2
- package/src/modes/foreman.md +25 -9
- package/src/skill-descriptions.json +63 -0
- package/src/skills/_self-improvement.md +42 -24
- package/src/skills/_template.md +3 -1
- package/src/skills/brainstorm.md +35 -22
- package/src/skills/commit.md +17 -17
- package/src/skills/daydream/VENDOR.md +6 -0
- package/src/skills/debug/ci.md +1 -1
- package/src/skills/dependencies.md +3 -3
- package/src/skills/diagram-design/VENDOR.md +4 -0
- package/src/skills/document-project.md +3 -2
- package/src/skills/explain-changes/VENDOR.md +5 -1
- 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/parallel-agents.md +11 -0
- package/src/skills/pipeline.md +3 -3
- package/src/skills/plan.md +5 -4
- package/src/skills/react-view-transitions/VENDOR.md +7 -1
- package/src/skills/release.md +11 -9
- package/src/skills/review-response.md +4 -2
- package/src/skills/rule/approve.md +2 -1
- package/src/skills/rule.md +27 -1
- package/src/skills/ship.md +54 -7
- package/src/skills/skill-forge.md +5 -3
- package/src/skills/token-report/VENDOR.md +5 -1
- package/src/skills/worktree.md +2 -2
- package/src/upstreams.json +9 -2
- package/themes/README.md +3 -1
- 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/{ActiveLoops-BJJN3P-V.js → ActiveLoops-DOJCPPPc.js} +1 -1
- package/web/dist/assets/Activity-LKsDzsnK.js +1 -0
- package/web/dist/assets/ActivityDetail-DhwTfPm6.js +1 -0
- package/web/dist/assets/{Bonsai-BBl4XXqs.js → Bonsai-CePMLrpr.js} +1 -1
- package/web/dist/assets/{CopyButton-Beven8yn.js → CopyButton-CuoaJ6k7.js} +1 -1
- package/web/dist/assets/Dashboard-D1VKuvLe.js +2 -0
- package/web/dist/assets/Docs-CUrHJKaU.js +5 -0
- package/web/dist/assets/Factories-Ci1XfmSy.js +1 -0
- package/web/dist/assets/{GreenhouseView-Bce212qd.js → GreenhouseView-CNfH2lPK.js} +1 -1
- package/web/dist/assets/Installs-ZHQZM1iS.js +3 -0
- package/web/dist/assets/{JournalView-CV4omyww.js → JournalView-CMsWahkS.js} +1 -1
- package/web/dist/assets/Kits-CkliyK0n.js +1 -0
- package/web/dist/assets/Laws-hh4O3HZ4.js +4 -0
- package/web/dist/assets/{LibRows-Dag1s0ZX.js → LibRows-Brv0Hmkr.js} +1 -1
- package/web/dist/assets/Library-BYmiLjJr.js +3 -0
- package/web/dist/assets/Loops-ytm-xJ68.js +2 -0
- package/web/dist/assets/{OperatorHudView-JmYY1pBR.js → OperatorHudView-KaqCx_HP.js} +1 -1
- package/web/dist/assets/Personal-CmcnRKYE.js +2 -0
- package/web/dist/assets/Settings-tUrpdOfq.js +1 -0
- package/web/dist/assets/{Tabs-8zsyEPSK.js → Tabs-CD7etcGD.js} +1 -1
- package/web/dist/assets/api-CZ-x0iWG.js +1 -0
- package/web/dist/assets/{controls-D4wmg_pl.js → controls-CK7qHA8H.js} +1 -1
- package/web/dist/assets/{index-CRWqKxfY.css → index-Ba_Kg3Af.css} +1 -1
- package/web/dist/assets/index-COKbhFNo.js +6 -0
- package/web/dist/index.html +3 -3
- 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/api-DLDVY3K-.js +0 -1
- package/web/dist/assets/index-Ce6qF2nG.js +0 -6
|
@@ -20,7 +20,7 @@ Each iteration is one commit on `loop/<slug>`, pushed as it lands. Work done bef
|
|
|
20
20
|
|
|
21
21
|
The agent ends its turn and shows you what it is waiting on:
|
|
22
22
|
|
|
23
|
-
- **A blocking score**: the change it plans (before it runs) or the staged diff (after), with the reasons for the score. One file outside the declared write set, more than 20 deleted lines, or a file that matches the loop's `contracts` is enough.
|
|
23
|
+
- **A blocking score**: the change it plans (before it runs) or the staged diff (after), with the reasons for the score. One file outside the declared write set, more than 20 deleted lines, or a file that matches the loop's `contracts` is enough under `prudent` and `balanced`; under `aggressive` each of these lands as a soft score, and a template can lower the deletion weight (`remove-dead-code` does).
|
|
24
24
|
- **A human gate**: some bricks always stop for you, whatever the preset. An ADR that survived its skeptic (`adr-challenge`), an architecture rule and its allowlist (`fitness-define`), a contract migration plan (`migration-plan`) and a feature spec (`spec`) are all gated.
|
|
25
25
|
- **Launch**, under `prudent`: the graph it is about to run.
|
|
26
26
|
|
|
@@ -29,8 +29,8 @@ Answer in the agent's session, in your own words:
|
|
|
29
29
|
| You say | What happens |
|
|
30
30
|
| --- | --- |
|
|
31
31
|
| ok / go ahead | It continues. On a gate held on a failure, ok follows that failure's edge, which usually stops the loop. |
|
|
32
|
-
| no |
|
|
33
|
-
| amend, with a note ("keep the old field until v3") |
|
|
32
|
+
| no | At a gate, at the launch prompt or during a setup unit, the loop stops. On a blocking score, that iteration's change is dropped (the planned one) or discarded (the diff), and the loop goes on from the iteration head. |
|
|
33
|
+
| amend, with a note ("keep the old field until v3") | Your note is added to `LOOP.md`. At a gate the same brick runs again; on a blocking score the brick that changes code runs with your note. A gate can be amended three times per iteration; a fourth amend stops the loop. |
|
|
34
34
|
| amend, at the `prudent` launch prompt | The loop stops ("graph to amend") with your note: nothing has run yet, so ask again for the loop you want. |
|
|
35
35
|
|
|
36
36
|
The agent passes your answer on as `geneseed loop decide --verdict ok|no|amend --note "<your words>"`. The console never answers for you.
|
|
@@ -57,7 +57,7 @@ A loop ends one of two ways:
|
|
|
57
57
|
| End | When |
|
|
58
58
|
| --- | --- |
|
|
59
59
|
| `$close` | The iteration head reports nothing left to do. Some templates first run an independent `done-check`. |
|
|
60
|
-
| `$stop` | A brick reported an outcome wired to stop (a red baseline in `baseline-green`, say), you answered no, a gate was amended a fourth time, two iterations in a row produced no diff, an inner retry ring ran out twice in one iteration, a read-only brick changed files, or the iteration ceiling was reached (the template's `max`, never above 20). |
|
|
60
|
+
| `$stop` | A brick reported an outcome wired to stop (a red baseline in `baseline-green`, say), you answered no at a gate, at launch or during setup, a gate was amended a fourth time, two iterations in a row produced no diff, an inner retry ring ran out twice in one iteration, a read-only brick changed files, or the iteration ceiling was reached (the template's `max`, never above 20). |
|
|
61
61
|
|
|
62
62
|
On `$stop` the agent reports the reason and leaves the branch as it is.
|
|
63
63
|
|
|
@@ -21,7 +21,7 @@ The context step sorts every doc it finds into one of two lists:
|
|
|
21
21
|
|
|
22
22
|
With no configuration, the context step finds these files:
|
|
23
23
|
|
|
24
|
-
- **Eager:** root `AGENTS.md`, `AGENT.md`, `CLAUDE.md` and `.cursorrules`, plus `README.md` and `CONTRIBUTING.md` (or their AsciiDoc `.adoc` twins). The root file your tool already loads by itself is skipped, so you never pay for it twice. On Claude Code that covers `AGENTS.md` too, when `CLAUDE.md` imports it with `@AGENTS.md`, or when the repo has no `CLAUDE.md` and Claude Code is 2.1.277 or newer. If the hook cannot read the version, it injects the file.
|
|
24
|
+
- **Eager:** root `AGENTS.md`, `AGENT.md`, `CLAUDE.md` and `.cursorrules`, plus `README.md` and `CONTRIBUTING.md` (or their AsciiDoc `.adoc` twins), and a repo-root `user-rules.md` and `PROFILE.md`. The root file your tool already loads by itself is skipped, so you never pay for it twice. On Claude Code that covers `AGENTS.md` too, when `CLAUDE.md` imports it with `@AGENTS.md`, or when the repo has no `CLAUDE.md` and Claude Code is 2.1.277 or newer. If the hook cannot read the version, it injects the file.
|
|
25
25
|
- **Lazy:** `docs/`, `doc/`, `documentation/`, `architecture/`, `adr/` and `ADR/`, monorepo `packages/*/README.md` and `apps/*/README.md`, and any other root `*.md`. AsciiDoc docs (`.adoc`) are found everywhere a `.md` is.
|
|
26
26
|
- **Never scanned:** `node_modules`, `.git`, `dist`, `build`, `vendor`, `.next`, `target`, `.venv`, `__pycache__`, `.opencode` and `.harness`.
|
|
27
27
|
|
|
@@ -6,7 +6,7 @@ kind: "concept"
|
|
|
6
6
|
section: "Factories"
|
|
7
7
|
description: "Carry a bug report, an issue or an analysis to an open PR with green CI: what you need, how to ask, and where it stops for you."
|
|
8
8
|
---
|
|
9
|
-
A **factory** carries one work item to an open pull request with green CI. Each stage is a brick or a whole loop, and a red CI run sends the work back to the loop, a bounded number of times. You ask in plain words. The agent drives `geneseed factory`, which decides every step. No stage merges: at the end the agent asks you once whether to merge, and merges only on your yes.
|
|
9
|
+
A **factory** carries one work item to an open pull request with green CI. Each stage is a brick or a whole loop, and a red CI run sends the work back to the loop, a bounded number of times. You ask in plain words. The agent drives `geneseed factory`, which decides every step. No stage merges: at the end the agent asks you once whether to merge, and merges only on your yes. With your standing auto-merge rule it arms the forge's auto-merge instead ([Auto-merge green PRs](auto-merge.md)).
|
|
10
10
|
|
|
11
11
|
This page is the how-to. For how the engine works (stages, cycles, state files), see [Factories](../concepts/factories.md).
|
|
12
12
|
|
|
@@ -116,7 +116,7 @@ run the analysis-to-build factory on docs/analysis/export-csv.md
|
|
|
116
116
|
| `merge-gate` reports `none` | The repo runs no CI on the PR: `ok` goes on to `retro`, `no` stops the run. Or the finding starts `environment:`: CI was still pending after 30 minutes, or `gh`/`glab` is missing or failed. `amend` waits again (after you fix the tool), `ok` goes on to `retro` without a green verdict (the close step reads CI once more, and proposes the merge only when it is green), `no` stops. |
|
|
117
117
|
| A `geneseed factory record` line asks | The git gate asks on any command line that holds the word `git` and the word `commit` or `push`. A record line starts with `git status`, so a spec path, a finding's path or an outcome name with `commit` or `push` in it makes the gate ask. On a record line this is a false alarm: answer yes. |
|
|
118
118
|
| The close commit | The last commit removes `FACTORY.md`, and it asks. Its push runs CI again: the agent reads the checks once more and reports the final state. A run with no loop (the `docs` lane) never committed `FACTORY.md`: the agent deletes the file, there is no close commit, and the final state is the one `merge-gate` read. |
|
|
119
|
-
| The merge proposal | Only when that final CI state is green: the agent shows the PR, the CI state and each review seat's verdict, and asks once whether to merge. Only on your explicit yes in chat does it squash-merge (`gh pr merge --squash`); no Geneseed gate asks before that command, so your answer is the only guard. Otherwise the PR stays open.
|
|
119
|
+
| The merge proposal | Only when that final CI state is green: the agent shows the PR, the CI state and each review seat's verdict, and asks once whether to merge. Only on your explicit yes in chat does it squash-merge (`gh pr merge --squash`); no Geneseed gate asks before that command, so your answer is the only guard. Otherwise the PR stays open. With your standing auto-merge rule, it arms the forge's auto-merge on the final head instead (the `review-panel` verdict counts as the `reviewer` pass), and a green head then merges at once; see [Auto-merge green PRs](auto-merge.md). |
|
|
120
120
|
|
|
121
121
|
Red CI does not stop for you: it sends the work back to the run's loop (`bugfix`, or the lane `triage` chose) with the failing checks as its first note, twice at most. A third red result stops the run. A failed holdout scenario works the same way, with its own count of two, and so do a failed `checks` and a failed `review-panel`. A holdout `error` stops the run: the diff touched the holdout folder, or a scenario could not be played.
|
|
122
122
|
|
|
@@ -31,7 +31,7 @@ The packs always load in the same order (craft, rigor, ops, process, comms), wha
|
|
|
31
31
|
|
|
32
32
|
**Dropping `process` changes what the machine does, not only what the agent reads.** The *Consent Before Push* rule in that pack is enforced at the tool boundary as well as in the prose:
|
|
33
33
|
|
|
34
|
-
- On Claude Code and OpenClaude, the git hook stays wired but stops asking before a commit or push.
|
|
34
|
+
- On Claude Code and OpenClaude, the git hook stays wired but stops asking before a commit or push onto the main branch.
|
|
35
35
|
- On OpenCode, a fresh install no longer gets the `git commit*` and `git push*` ask entries in `opencode.json`. On an existing install, the entries Geneseed recorded adding are removed. Entries you typed, and those on an install made before 5.2.0, are left in place and reported; build once with `--prune-gates` to remove the second kind.
|
|
36
36
|
|
|
37
37
|
The refusals of destructive git and `rm -rf` belong to the always-on Rules, not to the pack, so they stay in every build. See [Enforced vs. asked](../understand/enforced-vs-asked.md).
|
|
@@ -48,7 +48,7 @@ geneseed build --emit opencode-global --exclude-rules none
|
|
|
48
48
|
|
|
49
49
|
The number in an address is the rule's position in its pack, so it can change if a rule is added or removed. To see the current addresses, pass an address that does not exist: the build refuses it and lists every valid address. The web console's **Constitution** page has one switch per rule. You stage the changes there and apply them in a single rebuild.
|
|
50
50
|
|
|
51
|
-
Excluding *Consent Before Push* (`process 5` today) takes the commit and push consent gate with it, exactly as dropping the whole `process` pack does. The console and the wizard both warn you before applying it. A pack whose every rule is excluded drops out of the build entirely. See [Exclusions](../concepts/exclusions.md) for excluding whole folders instead.
|
|
51
|
+
Excluding *Consent Before Push* (`process 5` today) takes the commit and push consent gate with it, exactly as dropping the whole `process` pack does. To keep the rule but ask for every commit and push, not only those onto the main branch, keep it on and build with `--strict-consent` instead (the *Strict consent* switch on the Constitution page). The console and the wizard both warn you before applying it. A pack whose every rule is excluded drops out of the build entirely. See [Exclusions](../concepts/exclusions.md) for excluding whole folders instead.
|
|
52
52
|
|
|
53
53
|
---
|
|
54
54
|
|
|
@@ -41,7 +41,7 @@ You have three ways to change a choice:
|
|
|
41
41
|
|
|
42
42
|
- **Re-run the wizard** with `geneseed setup`. It pre-selects what the install already has, so holding Enter cannot widen a set you narrowed on purpose. The wizard does not ask about single rules, but it keeps any rule exclusions already in place.
|
|
43
43
|
- **Use the web console** (`geneseed web`). the **Installs** page changes theme, footprint and the rest per install. **Constitution** toggles packs and rules.
|
|
44
|
-
- **Run the build yourself.** Watch out: a flag you leave out takes the *generator's* default, not your install's current value. `geneseed status --json` prints, for every install, the exact `geneseed build` command that rebuilds it as it is. Start from that command and change the one flag you want.
|
|
44
|
+
- **Run the build yourself.** Watch out: a flag you leave out takes the *generator's* default, not your install's current value. So a build over an existing install that would change a setting you did not pass refuses, names each change, and prints the command that keeps them. `geneseed status --json` prints, for every install, the exact `geneseed build` command that rebuilds it as it is. Start from that command and change the one flag you want. `--reset` returns the settings you left out to their defaults, for that one build.
|
|
45
45
|
|
|
46
46
|
---
|
|
47
47
|
|
package/docs/guides/uninstall.md
CHANGED
|
@@ -11,12 +11,12 @@ description: "Remove an install, and what stays behind."
|
|
|
11
11
|
## Remove an install
|
|
12
12
|
|
|
13
13
|
```
|
|
14
|
-
geneseed uninstall # the project install in this folder, else the
|
|
14
|
+
geneseed uninstall # the project install in this folder, else the one global install
|
|
15
15
|
geneseed uninstall --target /path/to/repo # a project install
|
|
16
16
|
geneseed uninstall --target ~/.claude # a global install: pass its config directory
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
Without `--target`, the command picks the project install in the current folder if there is one, and the
|
|
19
|
+
Without `--target`, the command picks the project install in the current folder if there is one, and the one global install on the machine otherwise, whatever its host. With several global installs it refuses (exit code 2) and prints the `--target` command for each. It prints what it will remove and asks before going on. Pass `--yes` to skip the question. In a shell without an interactive terminal, `--yes` is required: without it, the command refuses and exits 1.
|
|
20
20
|
|
|
21
21
|
To see where each install lives, run `geneseed status`. The web console's **Installs** page can also uninstall.
|
|
22
22
|
|
|
@@ -24,7 +24,7 @@ To see where each install lives, run `geneseed status`. The web console's **Inst
|
|
|
24
24
|
|
|
25
25
|
Each install keeps a manifest, a list of the files Geneseed wrote. **Uninstall deletes exactly those files and nothing else**, then removes any folders they leave empty. A file of yours that sits in the same folder stays.
|
|
26
26
|
|
|
27
|
-
- **OpenCode global:** `AGENT.md`, `agents/`, `skills/`, `plugins/`, the marker files, and the `instructions` entry in `opencode.json`.
|
|
27
|
+
- **OpenCode global:** `AGENT.md`, Geneseed's managed block in `AGENTS.md`, `agents/`, `skills/`, `plugins/`, the marker files, and the `instructions` entry in `opencode.json`.
|
|
28
28
|
- **OpenCode per repo:** `AGENT.md`, `.opencode/`, `laws/`, `agents/`, `skills/`, and the `instructions` entry in `opencode.json`.
|
|
29
29
|
- **Claude Code, Bob, OpenClaude:** `agents/`, `skills/`, the marker files, Geneseed's managed block in the instructions file (`CLAUDE.md` or `AGENTS.md`), and Geneseed's own hooks and exclusions in `settings.json`. Your own settings keys and hooks stay.
|
|
30
30
|
|
package/docs/guides/upgrade.md
CHANGED
|
@@ -76,7 +76,7 @@ A rebuild of a global install in its host's own config directory also runs [the
|
|
|
76
76
|
|
|
77
77
|
## Local edits, and the improvements file
|
|
78
78
|
|
|
79
|
-
The agent records what it learns about a skill or agent in notes, which rebuilds never overwrite: under `notes/skill-notes/` and `notes/agent-notes/` in the shared tier
|
|
79
|
+
The agent records what it learns about a skill or agent in notes, which rebuilds never overwrite: under `notes/skill-notes/` and `notes/agent-notes/` in the shared tier for a fix true in any repo, and under `notebook/skill-notes/` and `notebook/agent-notes/` at the project root for a fact true only there. A project install kept all its notes in its host layer's notebook before (`.claude/notebook/`, `.bob/notebook/`, `.openclaude/notebook/`, `.opencode/notebook/`); its next rebuild merges them into the project's `notebook/` as project notes, prints one line, and sets the originals aside in `notebook/archived-agent-notes/` and `notebook/archived-skill-notes/` at the project root (in a linked worktree, the main checkout's, so removing the worktree keeps them). The clone's `.git/info/exclude` keeps these folders out of every commit. A file it cannot merge stays where it is and is named. Edits made to the deployed agent and skill files themselves, by you or by an older harness, are another matter: a rebuild would overwrite those, so **setup, re-theme and upgrade export them first**. When deployed files carry local edits (files only behind the source are not edits and are not exported), the differences are written to a markdown **improvements file** in `improvements/`, inside the install's own folder (for the OpenCode global install, `~/.config/opencode/improvements/`). The manifest does not list that folder, so rebuilds never overwrite it and uninstall never removes it.
|
|
80
80
|
|
|
81
81
|
A rebuild also refuses to overwrite a file you edited. The manifest records a fingerprint of every file Geneseed wrote; when a file no longer matches it, the rebuild leaves it alone and prints `kept your edited <file> — delete it to get Geneseed's copy back`. From then on the file is yours and later rebuilds skip it. A file the new version no longer ships is kept the same way, with `(no longer shipped)`. Line-ending changes from a git checkout do not count as edits. Installs made before fingerprints existed are overwritten as before.
|
|
82
82
|
|
|
@@ -88,7 +88,7 @@ geneseed diff --full # with line-level diffs
|
|
|
88
88
|
geneseed diff --out improvements.md # write the improvements file
|
|
89
89
|
```
|
|
90
90
|
|
|
91
|
-
`diff` compares the global
|
|
91
|
+
`diff` compares the global install there is by default, whatever its host (with several, the first, which it names on stderr). Pass `--target <config dir>` to compare another install. A file you replaced with a link to your own copy (a skill folder junctioned or symlinked elsewhere, say) is listed as `linked`: Geneseed never writes through a link, so it is yours and not drift, and it stays out of the improvements file. A file unmodified since its build that differs only because the source moved on is listed as behind source; a rebuild updates it, and it stays out of the improvements file too. `diff` also lists every non-empty self-improvement note, the tier's included, and `--out` copies them into the improvements file; the upgrade export does not fire on notes alone, since a rebuild cannot lose them. The improvements file is self-contained. To make the changes permanent, hand it to an agent in a Geneseed clone and ask it to fold them back into `src/`. Then they survive every future build. The **Local edits** tab of the web console's **Installs** page exports the same file.
|
|
92
92
|
|
|
93
93
|
## Moving from a clone to npm
|
|
94
94
|
|
package/docs/guides/worktree.md
CHANGED
|
@@ -46,4 +46,4 @@ It cannot ride Geneseed's install. Geneseed's plugins are single dependency-free
|
|
|
46
46
|
|
|
47
47
|
## Consent
|
|
48
48
|
|
|
49
|
-
`worktree_delete` **commits before it removes the worktree.** The harness's *Consent Before Push* rule (when the `process` pack is built in) asks before a *shell* `git commit` through `opencode.json` permissions. This plugin commits through its own tool, so that gate never sees the commit. Before you call delete, review what it will commit, or keep the worktree and commit yourself.
|
|
49
|
+
`worktree_delete` **commits before it removes the worktree.** The harness's *Consent Before Push* rule (when the `process` pack is built in) asks before a *shell* `git commit` through `opencode.json` permissions (OpenCode asks for every commit: its globs cannot see the branch). This plugin commits through its own tool, so that gate never sees the commit. Before you call delete, review what it will commit, or keep the worktree and commit yourself.
|
|
@@ -38,6 +38,6 @@ Where distilled memories land at session end, and which model distils them. See
|
|
|
38
38
|
| `GENESEED_HARNESS` | learn, context, guard plugins; CLI | Base whose `memory/` is written (and where `geneseed-wiki.jsonc` is looked up). Optional — a global install finds the shared store by itself. Set it only to pin another store: it wins over the shared one, so a value such as `~/.config/opencode` keeps facts out of the tier. |
|
|
39
39
|
| `GENESEED_MEMORY` | learn plugin, CLI, hand-run `learn` | Explicit memory dir; wins over `GENESEED_HARNESS` and the shared store. It moves what the OpenCode learn plugin, `geneseed memory` and a hand-run `learn` use. It does not move the `learn` hook, which is told its store by `--memory`, or what a session loads and the console shows: those read the tier. Without either variable, `geneseed memory`, `status` and a hand-run `learn` use a project install in the cwd or `./Harness`, then the shared store, then the OpenCode config store. A `memory/` folder counts only when an emit made it: a known `.geneseed-emit`, `.geneseed-version` beside the folder and `MEMORY.md` in it. Any other is not a store: name it with `--memory`. Two host installs in one repo keep two stores, and these commands use the one the marker names: name the other with `--memory`. |
|
|
40
40
|
| `GENESEED_MODEL` | learn + context plugins | `provider/model` fallback when the session's model can't be read from the transcript. |
|
|
41
|
-
| `GENESEED_LLM` | learn hook (Claude Code, Bob, OpenClaude) | Model CLI used to distil, e.g. `claude -p`. Unset, a real Stop/SubagentStop/PreCompact call returns
|
|
41
|
+
| `GENESEED_LLM` | learn hook (Claude Code, Bob, OpenClaude) | Model CLI used to distil, e.g. `claude -p`. Unset, a real Stop/SubagentStop/PreCompact call distils nothing and returns without reading the transcript for it — nothing reads its stdout there. The SubagentStop copy of `spec-feedback:` lines into `agent-notes/`, and the Stop copy of a skill's `[skill:<name>]` lines into `skill-notes/`, run either way; a manual `learn` run (notes piped or given as a file) still prints the prompt instead of distilling. |
|
|
42
42
|
| `GENESEED_LEARN_CHILD` | learn hook | Set by `learn` itself on the model CLI it spawns; a nested session's own Stop hook sees it and returns immediately, which stops `GENESEED_LLM="claude -p"` (hooks not disabled) from recursing. Not meant to be set by hand. |
|
|
43
43
|
| `GENESEED_LEARN_DEBOUNCE_MS` | learn plugin | Quiet period before distilling, in ms (default 60000). |
|
|
@@ -20,6 +20,8 @@ Where Geneseed writes an install, and what an upgrade re-renders.
|
|
|
20
20
|
| --- | --- | --- |
|
|
21
21
|
| `GENESEED_HOME` | build / hooks | Directory holding the hook shim `bin/geneseed-hook` (default `~/.geneseed`). Change it, then rebuild, so the emitted hooks point at the new location. |
|
|
22
22
|
| `GENESEED_ACTIVITY` | hooks, OpenCode plugin | `off` (or `0`, `false`, `no`) stops the activity writer; the hooks then load none of its code. Absent means on. See [geneseed-activity](plugin-activity.md). |
|
|
23
|
+
| `GENESEED_NO_USAGE` | hooks, OpenCode guard and learn plugins, web console | Any value stops the usage counter: no skill or subagent call, and no typed `/<skill>`, is appended to `notebook/usage.jsonl`, no finished subagent to `notebook/agent-runs.jsonl`, and the console reports the counter as off. |
|
|
24
|
+
| `GENESEED_LLM_TIMEOUT` | `learn` hook | Seconds the `learn` hook waits for the model CLI before it stops it and drops the partial reply (default 120; anything but a positive number means the default). |
|
|
23
25
|
| `GENESEED_HOOK_TAP` | hooks | An absolute directory outside any repository. Every hook call then writes one file there, `<host>-<event>-<n>.json`, holding the payload's shape: keys kept, every string replaced by its type and length. For recording what a host really sends; unset, nothing is written. A directory inside a git worktree is refused. See [Verify it works](../guides/verify.md#bob-by-hand). |
|
|
24
26
|
| `GENESEED_NO_SHIM_CHECK` | CLI | `1` silences the warning every `geneseed` command prints when the hook shim points at a path that no longer exists. For scripted callers; the `status` gates row still says `DEAD`. |
|
|
25
27
|
| `OPENCODE_CONFIG_DIR` | OpenCode emits, `diff`, plugins | OpenCode's config dir — where the global install is written. OpenCode still loads `$XDG_CONFIG_HOME/opencode` beside it, so `status` and `doctor` warn when both hold a Geneseed install. |
|
|
@@ -36,7 +38,7 @@ Where Geneseed writes an install, and what an upgrade re-renders.
|
|
|
36
38
|
|
|
37
39
|
## OpenCode plugin variables
|
|
38
40
|
|
|
39
|
-
Each OpenCode plugin's page lists its own switches: [guard](plugin-guard.md) (`GENESEED_GUARD`), [notify](plugin-notify.md) (`GENESEED_NOTIFY`, `GENESEED_NOTIFY_MIN_SECONDS`, `GENESEED_NOTIFY_TITLE`), [ponytail](plugin-ponytail.md) (`GENESEED_PONYTAIL`), [workflow](plugin-workflow.md) (`GENESEED_WORKFLOWS_DIR`) and [activity](plugin-activity.md) (`GENESEED_ACTIVITY`). `GENESEED_DEBUG=1` makes every plugin but guard and learn (which always log) say what it decided on stderr. `OPENCODE_DISABLE_LSP_DOWNLOAD` belongs to OpenCode itself: see [Language servers](../concepts/lsp.md).
|
|
41
|
+
Each OpenCode plugin's page lists its own switches: [guard](plugin-guard.md) (`GENESEED_GUARD`), [notify](plugin-notify.md) (`GENESEED_NOTIFY`, `GENESEED_NOTIFY_MIN_SECONDS`, `GENESEED_NOTIFY_TITLE`), [ponytail](plugin-ponytail.md) (`GENESEED_PONYTAIL`), [workflow](plugin-workflow.md) (`GENESEED_WORKFLOWS_DIR`) and [activity](plugin-activity.md) (`GENESEED_ACTIVITY`). `GENESEED_DEBUG=1` makes every plugin but guard and learn (which always log) say what it decided. Context, notify, ponytail and activity write to stderr; guard, learn and workflow write to OpenCode's own log on OpenCode 1 (service `geneseed-<name>`) and to stderr on OpenCode 2. `OPENCODE_DISABLE_LSP_DOWNLOAD` belongs to OpenCode itself: see [Language servers](../concepts/lsp.md).
|
|
40
42
|
|
|
41
43
|
## Web console and CLI
|
|
42
44
|
|
|
@@ -44,7 +46,7 @@ How the `geneseed` command behaves and prints.
|
|
|
44
46
|
|
|
45
47
|
| Variable | Read by | Effect |
|
|
46
48
|
| --- | --- | --- |
|
|
47
|
-
| `GENESEED_NO_WEB` | `geneseed` (bare) |
|
|
49
|
+
| `GENESEED_NO_WEB` | `geneseed` (bare) | Any value stops bare `geneseed` opening the web console; it prints the command list instead. |
|
|
48
50
|
| `GENESEED_NODE` | `./geneseed`, `geneseed.cmd`, `install` scripts | Node interpreter to run (default `node` on PATH). |
|
|
49
51
|
| `GENESEED_TUI_ASCII` | CLI output | Pure-ASCII output: no box-drawing or emoji. |
|
|
50
52
|
| `GENESEED_TUI_PLAIN` | CLI output | Drop emoji and animation. |
|
|
@@ -12,7 +12,7 @@ One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](envi
|
|
|
12
12
|
|
|
13
13
|
**When it runs.** On session events. A sub-agent's child session (one with a `parentID`) is folded into its root session: it becomes an `agents[]` row (`{id, type, status: "running" | "done"}`, the child's id and agent), and its files join the root's `files` with `by` set to the child's id. Only learn's throwaway `geneseed-*` sessions are skipped. On OpenCode 2 the files come from `session.step.ended`, which carries no line counts, so those read `null`. A session whose process died, went stale (30 minutes untouched) or ended leaves the live list and is listed as ended; the reader never deletes a file.
|
|
14
14
|
|
|
15
|
-
**Claude Code, OpenClaude and Bob.** Their hooks write the same files into `activity/` beside the install (`~/.claude/activity/`, `<repo>/.claude/activity/`, `~/.bob/activity/`). No hook is added per tool call: the writer runs after the hooks that already run — the gates, `context` and `learn` — plus `geneseed-hook activity` on `UserPromptSubmit` and, on Claude Code and OpenClaude, `SessionEnd` (their `SubagentStart` runs `context`, which records the same way). So a Claude session's phase moves on the gated tools (`Bash`, `PowerShell`, `Write`, `Edit`, `NotebookEdit`, `Skill`, `Agent`, `Task`), and the rest of the turn — every tool call, the model, the token totals, the last reply — arrives at `Stop`, read from the transcript where the previous `Stop` left off (at most 2 MB per turn). Bob sends no transcript, so a Bob session shows only the calls its `tool-gate` sees, and leaves the live list by staleness alone (Bob has no `SessionEnd`). Bob's `SessionStart` is recorded only after a compaction (`source: "compact"`, counted as one): a startup or resume fires just before the first prompt, which records the session anyway. Bob 2.2.3 writes every hook's payload to stdin and closes it, so reading it there is safe. These writers have no resident process, so their snapshots carry `pid: null` and stay live by staleness alone. Recorded: tool names, each changed file's path relative to the session's git root (a file outside the root, or a session outside any repo, keeps its basename only; a path is never stored absolute; labels show basenames), who changed it (the session or a subagent's `agent_id`), the subagents, the prompt count, the context size and the compactions, line counts, todo text, and 240-character snippets of the prompt and the last reply — never a shell command, a file's content or an edit's text — and any credential the secrets gate would catch in a snippet is written as `[redacted]`. A project install's `activity/` gets its own `.gitignore` (`*`), and the writer never writes through, or sweeps, an `activity/` or `activity/archive/` that is a link. Nothing is recorded in a repo listed in `excludes.json`, or inside a model CLI that `learn` started.
|
|
15
|
+
**Claude Code, OpenClaude and Bob.** Their hooks write the same files into `activity/` beside the install (`~/.claude/activity/`, `<repo>/.claude/activity/`, `~/.bob/activity/`). No hook is added per tool call: the writer runs after the hooks that already run — the gates, `context` and `learn` — plus `geneseed-hook activity` on `UserPromptSubmit` and, on Claude Code and OpenClaude, `SessionEnd` (their `SubagentStart` runs `context`, which records the same way). So a Claude session's phase moves on the gated tools (`Bash`, `PowerShell`, `Monitor`, `Write`, `Edit`, `NotebookEdit`, `Skill`, `Agent`, `Task`), and the rest of the turn — every tool call, the model, the token totals, the last reply — arrives at `Stop`, read from the transcript where the previous `Stop` left off (at most 2 MB per turn). Bob sends no transcript, so a Bob session shows only the calls its `tool-gate` sees, and leaves the live list by staleness alone (Bob has no `SessionEnd`). Bob's `SessionStart` is recorded only after a compaction (`source: "compact"`, counted as one): a startup or resume fires just before the first prompt, which records the session anyway. Bob 2.2.3 writes every hook's payload to stdin and closes it, so reading it there is safe. These writers have no resident process, so their snapshots carry `pid: null` and stay live by staleness alone. Recorded: tool names, each changed file's path relative to the session's git root (a file outside the root, or a session outside any repo, keeps its basename only; a path is never stored absolute; labels show basenames), who changed it (the session or a subagent's `agent_id`), the subagents, the prompt count, the context size and the compactions, line counts, todo text, and 240-character snippets of the prompt and the last reply — never a shell command, a file's content or an edit's text — and any credential the secrets gate would catch in a snippet is written as `[redacted]`. A project install's `activity/` gets its own `.gitignore` (`*`), and the writer never writes through, or sweeps, an `activity/` or `activity/archive/` that is a link. Nothing is recorded in a repo listed in `excludes.json`, or inside a model CLI that `learn` started.
|
|
16
16
|
|
|
17
17
|
**Archive.** On `SessionStart` and `SessionEnd` the hook writer moves every snapshot that is no longer live into `activity/archive/`, keeping the newest 50 and none older than 7 days. `/api/activity` returns them, with the stale and dead ones still in `activity/`, in its `ended` list — capped there by the same rule, since the OpenCode plugin never sweeps.
|
|
18
18
|
|
|
@@ -48,7 +48,7 @@ There is no DYNAMIC loop/* exemption on OpenCode — OpenCode 1 declares a `perm
|
|
|
48
48
|
|
|
49
49
|
[What a prompt says](../concepts/hooks.md#what-a-prompt-says) lists what this text can and cannot tell you.
|
|
50
50
|
|
|
51
|
-
The guard's reasons are the same words as the hooks'. The reason never names the switches below: the agent reads it, and a switch named there reads as leave to get round the block. The *Persist Insight* reason tells the agent to ask you and that a re-issue changes nothing — never to write the file another way (through a shell command, say). Warnings go to stderr.
|
|
51
|
+
The guard's reasons are the same words as the hooks'. The reason never names the switches below: the agent reads it, and a switch named there reads as leave to get round the block. The *Persist Insight* reason tells the agent to ask you and that a re-issue changes nothing — never to write the file another way (through a shell command, say). Warnings go to OpenCode's own log on OpenCode 1 (service `geneseed-guard`) and to stderr on OpenCode 2.
|
|
52
52
|
|
|
53
53
|
**Switches.**
|
|
54
54
|
- `GENESEED_GUARD=warn` — log every block, allow the call.
|
|
@@ -12,7 +12,7 @@ One of the [OpenCode plugins](opencode-plugins.md). Its switches are also listed
|
|
|
12
12
|
|
|
13
13
|
**When it runs.** After the session goes quiet. OpenCode signals "idle" after every turn, so each idle re-arms a timer and the distil runs once nothing has happened for `GENESEED_LEARN_DEBOUNCE_MS` (default 60 s). Trivial sessions are skipped.
|
|
14
14
|
|
|
15
|
-
**What you see.**
|
|
15
|
+
**What you see.** `wrote N memory file(s): …` (or `updated` / `archived`), or `skipped: <reason>`: in OpenCode's own log on OpenCode 1 (service `geneseed-learn`), on stderr as `[geneseed-learn] …` on OpenCode 2. Total silence in that place means it did not load.
|
|
16
16
|
|
|
17
17
|
**Where it writes** — the first that resolves:
|
|
18
18
|
1. `GENESEED_MEMORY` — an explicit memory dir;
|
|
@@ -29,6 +29,10 @@ or when it is the host's own config dir, as the hook does.
|
|
|
29
29
|
|
|
30
30
|
So a global install needs nothing set. `GENESEED_HARNESS` and `GENESEED_MEMORY` are deprecated, with removal planned for 6.0. If none resolves, it logs `no memory dir — this install has no memory/ folder, and neither does the shared tier or this repo.` and does nothing.
|
|
31
31
|
|
|
32
|
+
**A finished child session.** For a child session that names its agent, the plugin first copies the report's `spec-feedback:` lines into `agent-notes/<name>.md`, then appends one line to the install's `notebook/agent-runs.jsonl`: the day, the agent, its spec hash, its tool calls and refused calls, its feedback lines and whether it reported. The done-gate fields stay empty, because that gate is in the context plugin. The tool counts read the session's `tool` parts: on OpenCode 1 the whole child session; on OpenCode 2 the shape of `session.context()` tool parts is UNVERIFIED against a live host, so when no tool part it knows is seen, both counts are empty rather than 0. A refused call is one whose error opens with `[geneseed-guard] blocked:` (OpenCode 1) or `No tool named "BLOCKED, not a missing tool:` (OpenCode 2). It writes once per child session, at its first quiet period in each OpenCode process, only when that `notebook/` exists, and not with `GENESEED_NO_USAGE` set or a `.usage-off` file in the install. The install's `notebook/` is beside `plugins/` for a global install (`<config dir>/notebook`) and at the repo root for a project install (`<repo>/notebook`, not `<repo>/.opencode/notebook`). The spec-feedback notes follow each line's scope, as the Claude hook does: a machine line to the tier's `notes/`, a project line (`[agent:project]`, `[general:project]`, `[skill:<name>:project]`, `[skill:<name>:general:project]`) to `<project>/notebook/`, where the project is `<repo>` for a project install and the session root's git root for a global one. When a global and a project install both load, only one of them records a run, as for `usage.jsonl`. `geneseed catalog agents --scores` reads it. See [Agents](../concepts/agents.md).
|
|
33
|
+
|
|
34
|
+
**A skill's feedback line.** At the end of every turn (`session.idle` on OpenCode 1, `session.execution.succeeded` on OpenCode 2), not after the quiet period, the plugin reads the session's last reply and copies each `spec-feedback: [skill:<name>]` line into `skill-notes/<name>.md` (`[skill:<name>:general]` into `skill-notes/_general.md`) in the machine notes, or a `[skill:<name>:project]` line into the project's `notebook/skill-notes/<name>.md`, as for the agents' notes. A line counts only for a skill the install serves under that name (`skills/<name>/SKILL.md` beside `plugins/` names its own notes file); an untagged, `[agent]` or plain `[general]` line in a reply is a relayed sub-agent line and is not copied. On OpenCode 1 the turn's capture reads ONE message: the newest assistant message a `message.updated` event named, by `session.message`; only when no such event was seen (a plugin loaded mid-turn) does it read the session's messages once. On OpenCode 2 it reads `session.context()`, the messages since the last compaction, once per turn: V2 offers no single-message read the plugin knows of. Nothing is read in an install with no `skills/` folder or in an excluded folder. A line already in the notes is not added again. With a global and a project install both loaded, both copies resolve the same two notes files, so a line lands once: the duplicate check runs under the file lock (on Claude Code the global hook stands down instead). See [Skills](../concepts/skills.md).
|
|
35
|
+
|
|
32
36
|
**Switches.**
|
|
33
37
|
- `GENESEED_MODEL=provider/model` — fallback when the session's model can't be read. Without it you get `could not determine a model`.
|
|
34
38
|
- `GENESEED_LEARN_DEBOUNCE_MS` — the quiet period.
|
|
@@ -20,6 +20,6 @@ One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](envi
|
|
|
20
20
|
|
|
21
21
|
**Switches.**
|
|
22
22
|
- `GENESEED_WORKFLOWS_DIR` — load scripts from another directory.
|
|
23
|
-
- `GENESEED_DEBUG=1` — log to stderr.
|
|
23
|
+
- `GENESEED_DEBUG=1` — log to OpenCode's own log on OpenCode 1 (service `geneseed-workflow`), to stderr on OpenCode 2.
|
|
24
24
|
|
|
25
25
|
Ask the agent to *"list available workflows"* to check it loaded.
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
---
|
|
2
|
+
group: reference
|
|
3
|
+
order: 2.7
|
|
4
|
+
title: "Install profiles"
|
|
5
|
+
kind: "concept"
|
|
6
|
+
section: "CLI & environment"
|
|
7
|
+
description: "The profile file format, its two sources, how to apply one globally or to a project, and how to save your own."
|
|
8
|
+
---
|
|
9
|
+
An install profile is a whole install selection written down once, as `<name>.json`. A profile has no scope: you choose it when you apply the profile, globally or to one project folder. `geneseed setup --profile <name>` is the onboarding: it installs the profile globally, with no question. The install scripts pass the flag through, so a new user types one line.
|
|
10
|
+
|
|
11
|
+
On Windows (cmd or PowerShell), from the clone folder:
|
|
12
|
+
|
|
13
|
+
```bat
|
|
14
|
+
.\install.cmd --profile starter
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
On macOS and Linux:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
./install --profile starter
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
On Windows, type `.\` before `install.cmd`. PowerShell does not run a program from the current folder without it, and cmd does not either when the `NoDefaultCurrentDirectoryInExePath` policy is set.
|
|
24
|
+
|
|
25
|
+
## Where profiles come from
|
|
26
|
+
|
|
27
|
+
| Source | Folder | Who adds one |
|
|
28
|
+
| --- | --- | --- |
|
|
29
|
+
| **Shipped** | `profiles/` in this checkout, shipped in the npm package and the clone | An admin, by pull request |
|
|
30
|
+
| **Personal** | `profiles/` in the machine-wide Geneseed folder (`~/.config/geneseed/profiles/`), beside your memory and rules | You, with `geneseed profile save`. An update never touches it |
|
|
31
|
+
|
|
32
|
+
Both sources load the same way, and `geneseed doctor` checks every profile of both. A broken Shipped profile is a doctor failure. A broken Personal profile is a note only, so a file of yours never stops an update. A Personal profile may not use the name of a Shipped one: `profile save` refuses that name. A Personal file under a Shipped name that you made by hand is never loaded (the Shipped profile is), and `geneseed doctor` names that file in a note.
|
|
33
|
+
|
|
34
|
+
## What `setup --profile` does
|
|
35
|
+
|
|
36
|
+
1. It loads and checks the profile. A wrong value stops the run and names the field and the values it accepts.
|
|
37
|
+
2. It finds each tool the profile lists (`hosts`) on this machine, as the wizard does: the command on `PATH`, or the program in a usual per-user folder. When it finds none, it prints each tool's install link, installs nothing and exits 1. A listed tool that is missing is a line in the summary.
|
|
38
|
+
3. It builds the harness **globally** into each tool it found, one after the other. A failure on one tool does not stop the others; the run then exits 1. Before each build it saves any edits you made to that deployed harness, as the wizard does.
|
|
39
|
+
4. It puts `geneseed` on your `PATH`. On macOS and Linux it adds the PATH block to your shell's startup file without asking, and the summary names the file.
|
|
40
|
+
5. When `login` is true, it sets the web console to start at login (Windows and macOS) and starts it now, without a browser. A console that already runs is restarted, so it serves the code you just pulled. On Linux there is no login item; the console still starts.
|
|
41
|
+
6. It runs `geneseed doctor` for the profile's theme.
|
|
42
|
+
7. It prints a summary in plain ASCII: each tool and its result, the settings a re-run put back, the console address and three next steps.
|
|
43
|
+
|
|
44
|
+
A profile run needs no terminal, so it also works from a script or a remote shell. Run the same line again to update and repair: a tool installed since the first run is added, the login item is rewritten only when it is out of date, and the console is not started twice. **A profile wins over what you changed since:** a second run puts each setting back to the profile's value, and the summary lists every setting it put back.
|
|
45
|
+
|
|
46
|
+
A profile run never forces a build. When one of your own skills or agents sits under a name Geneseed ships, that tool's build fails; the summary prints the build command with `--force` that replaces it.
|
|
47
|
+
|
|
48
|
+
## Apply a profile
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
geneseed profile apply <name> # globally
|
|
52
|
+
geneseed profile apply <name> --project ~/work/api # into one project folder
|
|
53
|
+
geneseed profile apply <name> --hosts claude,opencode # only these tools
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
`profile apply` builds a profile without the onboarding: it puts nothing on `PATH`, writes no login item, starts no console and runs no doctor. Use it to change what an install runs, or to give one project its own setup.
|
|
57
|
+
|
|
58
|
+
- **Global** builds `<host>-global` for each tool, as `setup --profile` does.
|
|
59
|
+
- **`--project <dir>`** builds the per-project install of each tool into that folder (`geneseed build --emit <host> --out <dir> --root <dir>`). The folder must exist, be writable, and not be a tool's own global config folder. It must also not hold that global folder as its marker folder: `--project ~` is refused for Claude Code, because `~/.claude` is its global install. In the web console the folder must be an absolute path (`~` counts).
|
|
60
|
+
- **`--hosts`** narrows the run to some of the tools the profile lists. It refuses a tool the profile does not list. Without it, the run takes each tool of the profile that this machine has; a missing one is a line in the summary.
|
|
61
|
+
|
|
62
|
+
It touches only the installs of the tools it builds, in the scope you chose. Every other install stays as it is. As with `setup --profile`, a failure on one tool does not stop the others, the run then exits 1, and the summary lists every setting a build put back to the profile's value.
|
|
63
|
+
|
|
64
|
+
### A project beside a global install
|
|
65
|
+
|
|
66
|
+
When you apply a profile to a project and a global install of the same tool is active, both installs work in that project: the tool loads the global instructions file and the project's. The project install does not switch the global one off. `profile apply` adds one line per such tool to its summary, with the global gates that still run in the project. The rule comes from [Hook gates](../concepts/hook-gates.md) and [Exclusions](../concepts/exclusions.md):
|
|
67
|
+
|
|
68
|
+
| Tool | Global hooks that stand down for the project install | Global gates that still run in the project |
|
|
69
|
+
| --- | --- | --- |
|
|
70
|
+
| Claude Code, OpenClaude | `context`, `git-gate` and `learn`, when the project install wires the same hook. So the project's own deletion gate, consent check and done gate decide | `rule-gate`: the secrets gate, the ownership gate, the external gate and the test note, when they are on in the global install |
|
|
71
|
+
| IBM Bob | `context` and `learn` | `tool-gate`: every gate except the done gate |
|
|
72
|
+
| OpenCode | none: the global plugins do not stand down | every gate that is on in the global install |
|
|
73
|
+
|
|
74
|
+
A gate that is off in the global install runs nowhere, so the line does not name it. To silence the global install in a folder completely, use an [exclusion](../concepts/exclusions.md) (`geneseed exclude add <dir>`).
|
|
75
|
+
|
|
76
|
+
## The file
|
|
77
|
+
|
|
78
|
+
| Key | Required | Values |
|
|
79
|
+
| --- | --- | --- |
|
|
80
|
+
| `description` | no | One line that says who the profile is for |
|
|
81
|
+
| `hosts` | yes | A list of the hosts Geneseed installs into (the host ids `geneseed build --emit <host>-global` takes) |
|
|
82
|
+
| `theme` | yes | A theme in `themes/` |
|
|
83
|
+
| `footprint` | yes | `lean` or `full`, as `geneseed build --footprint` |
|
|
84
|
+
| `posture` | yes | A posture in `src/postures/`, as `geneseed build --posture` |
|
|
85
|
+
| `mode` | yes | A mode in `src/modes/`, as `geneseed build --mode` |
|
|
86
|
+
| `trust` | yes | A loop trust preset, as `geneseed build --trust` |
|
|
87
|
+
| `doctrines` | yes | `"all"`, or a list of the packs in `src/doctrines/` |
|
|
88
|
+
| `excludeRules` | no | A list of rule ids, such as `craft.4` (the console's Constitution page lists them) |
|
|
89
|
+
| `excludeSkills` | no | A list of skill names, as `geneseed build --exclude-skills` |
|
|
90
|
+
| `kits` | no | A list of the kits in `src/kits/` |
|
|
91
|
+
| `sharedTier` | no | `true` lets a **project** install read the machine-wide shared tier (`geneseed build --shared-tier on`). A global apply ignores it, because a global install owns the tier |
|
|
92
|
+
| `contextWindow` | no | `"200k"` (the default) or `"1m"`, as `geneseed build --context-window`: the model context the install is built for. On Claude Code it sets the skill-listing budget ([Skills](../concepts/skills.md#the-listing-budget-on-claude-code)); other hosts record it and write nothing |
|
|
93
|
+
| `gates` | no | An object that maps a gate switch to `false` to turn it off. Each key is a gate flag of `geneseed build --help` (`deletionGate: false` is `--no-deletion-gate`); a wrong key's refusal lists them all. `ownBranchPass: false` is `--strict-consent`, which adds asks |
|
|
94
|
+
| `login` | no | `true` (default) lets `setup --profile` set the console to start at login and start it; `false` does neither, for a server or a CI machine. `profile apply` ignores it |
|
|
95
|
+
|
|
96
|
+
`geneseed build --help` prints the current choices for each build flag. Every value is checked against the generator's own lists, never a copy, so this page does not repeat them: a refusal names the field and every value it accepts. An unknown key is an error, not ignored: a typo must not fall back to a default in silence.
|
|
97
|
+
|
|
98
|
+
## `starter`
|
|
99
|
+
|
|
100
|
+
```json
|
|
101
|
+
{
|
|
102
|
+
"description": "For a first install: neutral voice, every guardrail except the ownership gate.",
|
|
103
|
+
"hosts": ["opencode", "bob", "claude", "openclaude"],
|
|
104
|
+
"theme": "neutral",
|
|
105
|
+
"footprint": "lean",
|
|
106
|
+
"posture": "peer",
|
|
107
|
+
"mode": "direct",
|
|
108
|
+
"trust": "balanced",
|
|
109
|
+
"doctrines": "all",
|
|
110
|
+
"kits": [],
|
|
111
|
+
"contextWindow": "200k",
|
|
112
|
+
"gates": { "ownershipGate": false },
|
|
113
|
+
"login": true
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
`peer` and not `expert`, because `expert` does not explain the basics a new user needs; not `mentor`, because it checks understanding with questions. Every gate stays armed except the ownership gate, whose first-write stop is heavy for a new user. `200k`, because most machines run a 200k-token model, a locked-down work PC included; `guillaume-claude-global` sets `1m` for a 1M-token model.
|
|
118
|
+
|
|
119
|
+
## Save your own
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
geneseed profile save <name> --from claude-global
|
|
123
|
+
geneseed profile save <name> --from claude --project ~/work/api
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
It reads one install and writes `<name>.json` with every setting as it is, gates turned off included, and `hosts` set to that one tool. `--from` names a global install (`opencode-global`, `claude-global`, `bob-global` or `openclaude-global`), or a tool (`opencode`, `claude`, `bob`, `openclaude`) with `--project <dir>` for the project install in that folder. A project install's shared tier comes with it.
|
|
127
|
+
|
|
128
|
+
- By default it writes a **Personal** profile. It then prints the `profile apply` command that uses it.
|
|
129
|
+
- `--shipped` writes `profiles/<name>.json` in this checkout instead, for everyone. Only a git clone takes it, because a Shipped profile reaches others by pull request. Edit its `description`, then open a pull request.
|
|
130
|
+
- It refuses a name that already exists unless you add `--force`, which replaces that file only. It always refuses a name the other source holds.
|
|
131
|
+
|
|
132
|
+
It then prints how the new profile differs from `starter`, gates first, so you see what a reviewer will see.
|
|
133
|
+
|
|
134
|
+
A saved profile holds build settings only. Your user rules, `PROFILE.md`, memory, wiki and notebook are not build settings, and `profile save` never reads them.
|
|
135
|
+
|
|
136
|
+
## In the web console
|
|
137
|
+
|
|
138
|
+
**Installs › Profiles** lists every profile of both sources, with its tools, its settings, the gates it turns off and the installs that follow it (an install follows a profile when every build setting is the same). **Apply…** opens a panel: choose Global or One project, untick a tool to leave it out, and read per tool what the build would put back. In project scope the panel shows the global install that keeps running beside it. **Save an install as profile…** writes one from an active install, Personal or Shipped, and shows how it differs from `starter`. The **Selected install** panel on the Hosts tab names the profiles that install follows and has the same **Save as profile…** button. Both writes run as a background job of the CLI command above.
|
|
139
|
+
|
|
140
|
+
---
|
|
141
|
+
|
|
142
|
+
**Next:** [Install from a clone](../guides/install-clone.md) · [CLI](cli.md)
|
|
@@ -31,7 +31,7 @@ geneseed build
|
|
|
31
31
|
git add Harness
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
-
If the drift is your own edits, export them first — `geneseed diff` (or the console's **
|
|
34
|
+
If the drift is your own edits, export them first — `geneseed diff --out` (or the **Local edits** tab of the console's **Installs** page) writes them up so they can be folded back into `src/`.
|
|
35
35
|
|
|
36
36
|
**Confirm.** `geneseed doctor` no longer reports the bundle.
|
|
37
37
|
|
|
@@ -37,7 +37,7 @@ If you moved the shim itself with `GENESEED_HOME`, set it the same way before re
|
|
|
37
37
|
|
|
38
38
|
## A Bash/Write/Edit call is refused with `onFailure is "block"`
|
|
39
39
|
|
|
40
|
-
Claude Code refuses a `Bash`, `PowerShell`, `Write`, `Edit` or `NotebookEdit` call outright, and the transcript carries wording like:
|
|
40
|
+
Claude Code refuses a `Bash`, `PowerShell`, `Monitor`, `Write`, `Edit` or `NotebookEdit` call outright, and the transcript carries wording like:
|
|
41
41
|
|
|
42
42
|
> `PreToolUse:Bash hook error: [...]: failed; blocking because onFailure is "block"`
|
|
43
43
|
|
|
@@ -127,7 +127,7 @@ export GENESEED_MEMORY=/abs/path/to/memory
|
|
|
127
127
|
|
|
128
128
|
This variable and `GENESEED_HARNESS` win over the shared store, so leave them unset on a global install. Both are deprecated, with removal planned for 6.0.
|
|
129
129
|
|
|
130
|
-
**Confirm.** About a minute after the session goes quiet, stderr
|
|
130
|
+
**Confirm.** About a minute after the session goes quiet, OpenCode's own log (OpenCode 1, service `geneseed-learn`) or stderr (OpenCode 2, as `[geneseed-learn] …`) shows `wrote N memory file(s): …` or a `skipped:` reason. Total silence in that place means the plugin did not load.
|
|
131
131
|
<!--/harness-->
|
|
132
132
|
|
|
133
133
|
Model, read-only agent, document and MCP problems are on [their own page](troubleshoot-tools.md).
|
|
@@ -32,7 +32,7 @@ Run without the installer — `npx geneseed`, a global npm install, or a hook
|
|
|
32
32
|
|
|
33
33
|
> `geneseed needs Node 22.7 or newer; this is Node 20.18.1. Install a current Node from https://nodejs.org (or your package manager), then run the command again.`
|
|
34
34
|
|
|
35
|
-
**Cause.** The `node` on PATH is older than 22.7. npm only *warns* about the engine requirement, so a global install succeeds anyway. A hook prints the same sentence and
|
|
35
|
+
**Cause.** The `node` on PATH is older than 22.7. npm only *warns* about the engine requirement, so a global install succeeds anyway. A hook prints the same sentence on stderr and judges nothing: on Claude Code and OpenClaude each gated tool call then asks you, since no gate checked it, and on Bob the call passes. The other hooks (context, learn, activity) do nothing until Node is upgraded.
|
|
36
36
|
|
|
37
37
|
**Fix.** Install the current Node.js LTS (see above), open a **new** terminal, and run the command again.
|
|
38
38
|
|
|
@@ -59,7 +59,7 @@ See [Install](../guides/install.md) for the emit target that matches your tool.
|
|
|
59
59
|
|
|
60
60
|
Setup opens with `AI coding tools on this machine:` and an `ok` or `--` per tool.
|
|
61
61
|
|
|
62
|
-
**Cause.** The check
|
|
62
|
+
**Cause.** The check looks for the command (`opencode`, `claude`, `bob`, `openclaude`) on your PATH, then in the usual per-user folders, where a hit shows as `ok … (<where>, not on PATH)`. When it finds none of the four, it asks "Installed somewhere else?" and takes a path. An install in a folder it does not search shows as missing; an unrelated program with the same name shows as present.
|
|
63
63
|
|
|
64
64
|
**Fix.** Nothing to fix — the line is advisory. Pick the install mode for the tool you actually use; a missing tool among several present is just a line, and you can continue without one.
|
|
65
65
|
|
|
@@ -85,7 +85,7 @@ reports `version "21` or higher.
|
|
|
85
85
|
|
|
86
86
|
## `geneseed: command not found`
|
|
87
87
|
|
|
88
|
-
**Cause.** The `geneseed` launcher is not on your PATH.
|
|
88
|
+
**Cause.** The `geneseed` launcher is not on your PATH. The clone's installer (`./install`, `install.cmd`) runs `link` for you, but a clone set up with `geneseed setup` alone is not linked, and a terminal opened before `link` ran does not see the change (an `npm install -g geneseed` install is put on PATH by npm).
|
|
89
89
|
|
|
90
90
|
**Fix.** From the cloned folder:
|
|
91
91
|
|
|
@@ -22,7 +22,7 @@ export GENESEED_MODEL=provider/model
|
|
|
22
22
|
|
|
23
23
|
## A read-only agent won't run a command
|
|
24
24
|
|
|
25
|
-
**Cause.** By design: read-only agents are denied the shell.
|
|
25
|
+
**Cause.** By design: read-only agents are denied the shell. Those that must run read-only commands (the reviewer, security and explorer, for example) are allowed it in their own spec.
|
|
26
26
|
|
|
27
27
|
**Fix.** Hand the task to an agent that can run commands, or run it yourself. See [Agents](../concepts/agents.md).
|
|
28
28
|
|
package/docs/token-footprint.md
CHANGED
|
@@ -72,10 +72,15 @@ until 2026-09 it did, and the whole harness was paid twice per session.
|
|
|
72
72
|
`tests/unit/emit_smoke.test.mjs` rather than a byte count quoted here; the
|
|
73
73
|
figure moved twice while this paragraph went on stating the old one.
|
|
74
74
|
- **Skill descriptions are the second bill** on a host that catalogues natively.
|
|
75
|
-
Each is the skill's
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
75
|
+
Each is the skill's line in `src/skill-descriptions.json`: purpose and trigger
|
|
76
|
+
in at most 80 characters, theme-neutral (`skillDescription` in
|
|
77
|
+
`js/hosts/native.mjs`). The host lists skills under a budget of about 1% of
|
|
78
|
+
the context window and drops the descriptions of the least-used skills when
|
|
79
|
+
the listing overruns it. Read the listing's size off `SKILL_LISTING_CEILING`
|
|
80
|
+
in `js/inspect/cost.mjs`, which carries the measurement, rather than a figure
|
|
81
|
+
quoted here. Before the 80-character lines, the purpose line plus the first
|
|
82
|
+
trigger sentence ran to 320 characters. The themed purpose and the full
|
|
83
|
+
trigger still live in the body, read as soon as the skill is chosen.
|
|
79
84
|
- **§5–§9 carry authored lean halves too** (Memory, Notebook, Workspace, Wiki,
|
|
80
85
|
Context): each keeps its obligations — read `MEMORY.md`, read
|
|
81
86
|
`context.json` before the first reply, the git-ignored folders — and points at
|
|
@@ -94,12 +99,12 @@ until 2026-09 it did, and the whole harness was paid twice per session.
|
|
|
94
99
|
- **User-only skills leave the catalogue.** A skill whose source carries
|
|
95
100
|
`<!-- invocation: user -->` renders `disable-model-invocation: true`; Claude
|
|
96
101
|
Code and Bob then drop its description from the always-on skill metadata and
|
|
97
|
-
only `/name` opens it.
|
|
102
|
+
only `/name` opens it. Three skills (`teach`, `learn-mode`, `adhd`)
|
|
98
103
|
carry it today.
|
|
99
104
|
- **Aliases cost 0 always-on.** A merged skill's old names (`<!-- aliases: -->`)
|
|
100
105
|
ship as user-only stubs on Claude Code, Bob and OpenClaude, and as `/name` commands
|
|
101
106
|
on OpenCode — never in the model's catalogue, so a rename or merge is free.
|
|
102
|
-
- Plugin JavaScript (OpenCode,
|
|
107
|
+
- Plugin JavaScript (OpenCode, about 380 KB on disk) runs in the host runtime and
|
|
103
108
|
never enters the context window.
|
|
104
109
|
|
|
105
110
|
## Why there is no chat mode
|
|
@@ -25,5 +25,5 @@ How Geneseed's own code and tests are kept, and what the harness offers the agen
|
|
|
25
25
|
- **User-only skills and the aliases of old names cost no tokens and are hidden from the model.** The agent sees each skill once. See [Skills](../concepts/skills.md).
|
|
26
26
|
- **`--exclude-skills` filters in one place, `renderAll`.** A new host inherits the exclusion with no work of its own. See [Exclusions](../concepts/exclusions.md).
|
|
27
27
|
- **No skill is named like a Claude Code built-in command.** The built-in would win; the review skill is `geneseed-code-review` for this reason. See [Project context](../guides/project-context.md).
|
|
28
|
-
- **
|
|
28
|
+
- **A skill's description is one theme-neutral line of at most 80 characters, purpose and trigger, in the third person, never cut off and never with an XML-like tag.** The description is the only text a host routes on, so a defect there is a skill that silently never fires. The host lists skills under a budget and drops the least-used skills' descriptions first, so every line has to be short. The lines live in `src/skill-descriptions.json`, and the doctor checks them and the emitted form (`catalogueLineProblems`, `descriptionProblems`). See [Skills](../concepts/skills.md).
|
|
29
29
|
- **Skills that sound alike each have one job.** `roast-me` critiques your own ask or plan, `geneseed-code-review` reviews code, `fresh-eyes` is a blind second reading, and `pipeline` relays work between agents. Clear scopes make routing precise. See [Skills](../concepts/skills.md).
|
|
@@ -29,7 +29,7 @@ On Claude Code and OpenClaude the hooks never block silently. They make the host
|
|
|
29
29
|
- **Your rules and memory**: any write by the agent to `user-rules.md` or to the memory store. Whether something is a standing rule or a fact to remember is your call.
|
|
30
30
|
- **The first write in an application with no ownership setup**: in a repo with a build manifest whose root `AGENTS.md` has no `## Ownership` section, the session's first write is refused once, as a reminder rather than a gate, with the reason sent to the agent rather than to you: it then asks you to set [ownership](../concepts/ownership.md) up now, skip this session, or skip in this repo until you ask. Off per repo with `mode: off`, for you alone in one repo with `Setup: declined <YYYY-MM-DD>` in `.geneseed/ownership.md`, per install with `--no-ownership-gate`.
|
|
31
31
|
- **The checks you are judged by, and the gates' own switches**: a write to a file listed in `.geneseed/protected-checks.txt`, to the done gate's list, or to a file that can switch a gate off (the hook settings, `excludes.json`, a gate marker in `AGENT.md`, the hook shim). You get a prompt. A shell write counts too, for the common forms: `>`, `>>`, `tee`, `sed -i`, `cp`, `mv`, `rm`. A script or an interpreter's inline code is not seen, so run the checks in CI as well.
|
|
32
|
-
- **Ending a turn without the proof**: only in a project whose `.geneseed/done-checks.txt` lists at least one check; a file that lists none turns the gate off for that project. A turn that edited files cannot end until every listed check has passed since the last edit. The agent is stopped
|
|
32
|
+
- **Ending a turn without the proof**: only in a project whose `.geneseed/done-checks.txt` lists at least one check; a file that lists none turns the gate off for that project. A turn that edited files cannot end until every listed check has passed since the last edit. The agent is stopped again only after a new edit or a changed background result, at most 3 times between two task notifications and 10 times in the whole turn, then the turn may end. A sub-agent is held to the same proof when it stops. Without that file, Geneseed infers the checks from the project's manifest (`package.json` scripts, Maven, Gradle, `pyproject.toml`, `Cargo.toml`, `go.mod`): you get a warning when a turn ends without them, but the turn is not stopped.
|
|
33
33
|
|
|
34
34
|
If a gate crashes, it asks instead of letting the call through. If it cannot start at all (a deleted or broken shim) or times out, Claude Code blocks the call instead: see [Troubleshoot hooks](../reference/troubleshoot-hooks.md) to recover. Other shell commands go through Claude Code's normal permission flow; an `rm` of files git cannot restore is the real-loss case above.
|
|
35
35
|
|
|
@@ -14,11 +14,11 @@ What a Claude Code or OpenClaude install writes, piece by piece. The **Kind** wo
|
|
|
14
14
|
| `CLAUDE.md` (managed block) | The rules, the pointers to agents and skills, and how memory works. Geneseed writes only its own block; your own lines in the file stay | asked | ~7.2k tokens every session | Shrink it with fewer doctrine packs (`--doctrines`); remove it with `geneseed uninstall` |
|
|
15
15
|
| `user-rules.md` | Your own standing rules, read every session. A global install reads the [shared](../concepts/shared-tier.md) file first, then this one, which can narrow it. Seeded empty | asked | 0 until you write in it | Leave it empty |
|
|
16
16
|
| `PROFILE.md` | Who you are and how you like answers pitched. Fill it with the `profile` skill. On a global install it lives in the shared tier, and a filled host file replaces the shared one | asked | 0 until you fill it | Leave the seeded text untouched |
|
|
17
|
-
| context hook | At session start, and again after a resume or compaction, puts your repo's README, CONTRIBUTING and a listing of `docs/` in front of the agent, with your rules, profile, memory index and wiki | automatic | Your docs
|
|
17
|
+
| context hook | At session start, and again after a resume or compaction, puts your repo's README, CONTRIBUTING and a listing of `docs/` in front of the agent, with your rules, profile, memory index and wiki | automatic | Your docs; the whole hook output is capped at 9,000 characters, and what does not fit is listed for the agent to read on demand | `geneseed exclude add <folder>` silences every hook in that folder |
|
|
18
18
|
| git-gate hook | Before each shell command: asks you before any `git commit` or `git push`, and before a command that would really lose data — a force-push to `main`, a `reset --hard` that abandons unpushed commits, `branch -D` of an unpushed branch, an `rm` git cannot undo | enforced | ~14 ms per shell call | The commit/push question goes away if you build without the **process** pack; the destructive-git question has no switch except `geneseed exclude` |
|
|
19
19
|
| rule-gate hook | Before each write or edit: asks you when the file would carry a credential-shaped string (outside `.env`), or when the agent writes to `user-rules.md` or memory. In an application repo with no `## Ownership` section in its root `AGENTS.md`, stops the session's first write once so the agent proposes the [ownership](../concepts/ownership.md) setup | enforced | ~14 ms per write | `geneseed exclude add <folder>`; the ownership stop alone: `mode: off` in the repo's `## Ownership`, `Setup: declined <YYYY-MM-DD>` in your personal `.geneseed/ownership.md`, or rebuild with `--no-ownership-gate` |
|
|
20
20
|
| learn hook | When the agent finishes a reply, and before compaction, distils durable facts from the recent conversation into the memory store. Off until you set `GENESEED_LLM` to a model command such as `claude -p` | automatic | One model call each time it runs, once enabled | Leave `GENESEED_LLM` unset (the default) |
|
|
21
|
-
| `skills/` | Written procedures you call by name, such as `brainstorm` or `plan` | on demand | ~
|
|
21
|
+
| `skills/` | Written procedures you call by name, such as `brainstorm` or `plan` | on demand | ~2.2k tokens for names and descriptions; a skill's body loads only when called | No per-skill switch; `geneseed uninstall` removes them all |
|
|
22
22
|
| `agents/` | Specialists the agent can delegate to, such as `reviewer` or `tester` | on demand | ~0.5k tokens | `geneseed uninstall` |
|
|
23
23
|
| `memory/` | Durable facts, one per file, with a `MEMORY.md` index the context hook injects. A global install keeps them in the shared `~/.config/geneseed/memory/`; this folder holds only the convention and a seeded index | automatic | 0 when fresh; grows as facts accumulate | `geneseed memory list`, then `geneseed memory rm <name>` (archives; `--purge` deletes) |
|
|
24
24
|
| `notebook/` | The agent's own working space: plans, scratch notes, and the gate log `gates.jsonl`. It stays per host; on a global install only the self-improvement notes live in the shared `notes/` | automatic | 0 when fresh; its index grows with use | Delete what you do not want; it is git-ignored and yours |
|
|
@@ -13,7 +13,7 @@ An install writes a handful of files into your host's config folder and, where t
|
|
|
13
13
|
- **asked**: text the model reads every session. It usually follows it, but nothing makes it.
|
|
14
14
|
- **on demand**: loads only when you or the agent call it by name.
|
|
15
15
|
|
|
16
|
-
Token costs are for the default *lean* footprint. Before you type anything, a session carries about 12k tokens of harness. That is roughly 6% of a 200k window. A `--footprint full` build adds about
|
|
16
|
+
Token costs are for the default *lean* footprint. Before you type anything, a session carries about 12k tokens of harness. That is roughly 6% of a 200k window. A `--footprint full` build adds about 7k on the rules file. For a live figure on your own install, ask the agent to use the `token-report` skill.
|
|
17
17
|
|
|
18
18
|
## One folder for the whole machine
|
|
19
19
|
|