Skip to content

oliverweissl/context-garden / skills/seedbank

seedbank

Verified

Maintain a small, generated AGENTS.md of repository facts (build commands, conventions, invariants, past mistakes) that were rediscovered often or were costly to get wrong. Use at task start to check cached facts, and at task end to log and promote what you had to dig for.

references/schema.md

View on GitHub
# CLI reference

Store state is plain JSON under `.seedbank/`; safe to hand-edit between CLI
calls (each call does a full load/mutate/save).

## `seedbank observe <kind> ...`

Kinds: `read <path>`, `search <pattern>`, `run -- <cmd>`,
`mistake <text>`, `fact <text>`. Costs per kind: `references/scoring.md`.

`--scope` defaults to `invariants` for `mistake`, else `general`.
`--source <path>` (repeatable) applies to `mistake`/`fact` only; a
source whose content hash changed since the last observation increments
`hash_changes` (lowers `stability`). `mistake`/`fact` keys hash the
normalised text (case, whitespace, trailing punctuation), so trivial
variants share a key. `read` of a missing path is an error and records
nothing.

`run` executes the command and echoes merged stdout+stderr (truncated past
2000 chars) but does **not** store the raw output; for large/repetitive
output use compost for the command and `observe run` only to record that
you had to run it. `--timeout SECONDS` (default 600) kills a hung command,
recorded as failed (exit 124, `timed_out: true`).

## `seedbank candidates [--threshold N] [--all] [--json]`

Keys without a fact, sorted by `value`; threshold defaults to
`promote_threshold` (1.0), `--all` ignores it. `representation` is `null`
unless an `observe fact`/`mistake` supplied one; then pass
`--representation` at promote time.

## `seedbank promote <key> [--representation TEXT] [--tier hot|warm] [--scope S] [--critical] [--budget N] [--force] [--replace FACT_ID]`

`--tier` defaults to `warm`. Errors if no representation is available.
Sources are copied from the key and hashed at promote time. `--critical`
exempts the fact from eviction and decay. Promoting to `hot` past the
budget auto-demotes the lowest-value non-critical hot facts to `warm`;
if nothing can be evicted, promotion is refused (raise `--budget`, demote
something, or use `--tier warm`). Stale `--critical` facts
still count against the budget (they stay published). A key that already
has a fact is refused unless `--force`.

**Contradictions.** A new fact whose content words overlap an existing
same-scope fact (Jaccard >= 0.4) with opposite polarity (exactly one side
says never/not/no/don't/avoid/cannot...) is refused, listing the
conflicts. `--replace FACT_ID` deletes that fact and promotes the new one;
`--force` keeps both. Lexical only: antonyms like tabs vs spaces are missed.

## `seedbank hook`

Claude Code `PostToolUse` entry point for `Read|Grep|Glob|Bash` (setup:
`references/guide.md`). Bash counts only read-only commands (cat/head/tail/
sed/awk... as reads, grep/rg/ag/git grep/find -name as searches; `cd` is
followed). Each call is filed under the repo holding the touched path, so a
session started in a folder of repos still works. Skips files outside any
repo and under `.git/` or `.seedbank/`. Prints nothing on stdout; a crash exits 1
with its traceback on stderr (a non-blocking hook error in Claude Code).

## `seedbank demote <fact_id> --tier warm|cold`

`--tier cold` **deletes** the fact.

## `seedbank invalidate [--confirm FACT_ID]`

No args: marks `stale` every fact with a source whose hash changed or that
no longer exists. Facts without sources are never marked stale. `compile`
runs this first.

`--confirm FACT_ID`: after you've reviewed a stale fact (optionally
editing its text in `facts.json`), re-hashes its sources, clears `stale`,
bumps `confidence` +0.05 and returns it to the published set (hot budget
re-enforced).

## `seedbank gc [--purge-stale] [--keep-per-key N]`

Re-applies hot-budget eviction (e.g. after lowering `hot_budget` in
`config.json`), with `--purge-stale` deletes stale facts, and prunes the
raw observation log to the last N (default 5) entries per key. Aggregate
stats are kept, so scores are unaffected.

## `seedbank compile [--targets AGENTS.md,...] [--force]`

Writes the hot section + warm-scope pointers to each target (default
`AGENTS.md`) and `.seedbank/warm/<scope>.md` per warm scope with an active
fact. With an empty store it refuses to wipe an existing seedbank block
(fresh clone); `--force` overrides. For Claude Code, prefer the
`CLAUDE.md` import over adding it to `--targets` (`references/guide.md`).

## `seedbank status` / `seedbank stats [--json]`

`status`: counts, hot-budget usage, candidates above threshold, stale
facts. `stats`: estimated tokens avoided per fact =
`max(0, retrieval cost before promotion - persistent_token_cost)`; no
future projection.

## `seedbank import <file>`

`#`/`##` headings set the scope; each `- `/`* ` bullet becomes one
`imported` candidate (deduplicated). Review with `candidates` and promote
deliberately.

## `seedbank export [--out FILE]` / `seedbank import <bundle.json> [--force]`

`export` writes the non-stale facts (text, scope, tier, `--critical`,
repo-relative sources + hashes) and the repo's fingerprint as JSON
(stdout by default). Fingerprint: origin URL without scheme, user, port
and `.git`, host lowercased, plus the root commit SHA(s); no local paths,
and sources outside the repo are dropped.

`import` of such a bundle refuses unless the fingerprint matches this repo
(same remote or a shared root commit) or `--force` is given. Facts are
added as promoted facts, never replacing one: a duplicate (same key or
text) or a contradiction of an active fact is skipped, and a hot fact that
would exceed the hot budget comes in warm. Exported source hashes are
kept, so a fact whose source differs here goes stale at the next
`compile`. Run `compile` afterwards.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall