README
¶
open-seed-engine
The protocol engine for open-seed: the
pinned seed CLI binary that the template's bootstrap shim downloads, hash-verifies,
and execs.
Per open-seed design decision 7.5, this repo carries the protocol-critical core:
the task port, claim/lease/fence protocol, validators, receipt verify, fan-out
sync, init, as one static, cross-compiled Go binary. The contract (schemas,
transition table, guardrails) stays as files in the open-seed template; this engine
is a replaceable implementation of that spec, and a repo without it installed must
remain workable.
Status
The full v1 port is shipped, and the v2 surface is in: the task verbs
(create/ready/get/list/claim/transition/release/close + the operator
verbs), the seed-state ref store and the builtin fastcards SQLite
store, receipt generate/verify, the validators, seed sync fan-out,
seed upgrade / template upgrade, init / init-github,
state lint|anchor|export|import|resume, maintain reap|report,
mirror plan|record, mail + handoff packets, the checked-in workflow
engine (seed workflow validate|run), the skills manifest/lockfile,
and the MCP stdio transport (seed mcp serve). The current release is
the VERSION file (releases are cut from it).
The open-seed build plan
tracks per-phase acceptance; the architecture
map
is the cross-repo design map (layering, the port, the evidence chain,
where each gate grounds). Package map: internal/<pkg> mirrors those
responsibilities: the pure table-driven decision core is
internal/port, and the store boundary is internal/stateref +
internal/fastcards behind one Backing interface.
Install
Pinned binaries (what the shim uses) come from
GitHub Releases: each
release carries a checksums.txt and GitHub build-provenance attestations
(verify with gh attestation verify <artifact> -R shaunlmason/open-seed-engine).
From source:
go install github.com/shaunlmason/open-seed-engine/cmd/seed@latest
Exit codes
0 success · 2 claim contention · 3 invalid transition · 4 not found ·
5 backend unavailable · 6 fenced out (stale claim token) · 10
protocol-version mismatch: the full registry is reserved by the port
contract (.seed/port-schema/port.json). CLI usage errors exit 64
(EX_USAGE) so they can never be mistaken for a port result.
Releasing
Releases are driven by the VERSION file: bump it (e.g. to v0.2.0) and push to
main. The release workflow mints the tag at HEAD in-runner, so the tag and
the released commit can never disagree, and no contributor needs tag-push
rights, then runs goreleaser across linux/darwin/windows × amd64/arm64,
publishes archives + checksums.txt, and attests provenance.
(workflow_dispatch with a tag input does the same manually.)
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
seed
command
Command seed is the open-seed protocol engine: the pinned binary that the template's bootstrap shim (scripts/seed) downloads, verifies, and execs.
|
Command seed is the open-seed protocol engine: the pinned binary that the template's bootstrap shim (scripts/seed) downloads, verifies, and execs. |
|
internal
|
|
|
backend
Package backend implements the external-plugin dispatch seam (open-seed §7.1 / research/10 §5.3–5.5): when the configured backend's manifest entry is not "builtin", port verbs are executed by .seed/backends/<name>/<entry> <verb> [args] --json.
|
Package backend implements the external-plugin dispatch seam (open-seed §7.1 / research/10 §5.3–5.5): when the configured backend's manifest entry is not "builtin", port verbs are executed by .seed/backends/<name>/<entry> <verb> [args] --json. |
|
card
Package card parses and serializes task cards: markdown files with YAML frontmatter, living at tasks/<id>.md on the seed-state ref.
|
Package card parses and serializes task cards: markdown files with YAML frontmatter, living at tasks/<id>.md on the seed-state ref. |
|
config
Package config loads .seed/config.toml: the checked-in, human-owned coordination config (control surface, D4.1).
|
Package config loads .seed/config.toml: the checked-in, human-owned coordination config (control surface, D4.1). |
|
fastcards
Package fastcards is the builtin single-machine store (§7.1 builtin-store amendment, §8 R4): coordination state in a local SQLite database instead of the seed-state ref.
|
Package fastcards is the builtin single-machine store (§7.1 builtin-store amendment, §8 R4): coordination state in a local SQLite database instead of the seed-state ref. |
|
gitx
Package gitx drives the system git binary.
|
Package gitx drives the system git binary. |
|
mcptransport
Package mcptransport implements `seed mcp serve` (plan os-67a1bf14, research/10 §5.4): MCP as an ADDITIONAL transport, never a replacement: an MCP stdio server exposing one tool per port verb, dispatching through the identical task-service path the CLI uses.
|
Package mcptransport implements `seed mcp serve` (plan os-67a1bf14, research/10 §5.4): MCP as an ADDITIONAL transport, never a replacement: an MCP stdio server exposing one tool per port verb, dispatching through the identical task-service path the CLI uses. |
|
mirror
Package mirror computes the one-way GitHub Issues export (open-seed D1: the mirror is a component, not a backend: cards are authoritative and the export direction always wins).
|
Package mirror computes the one-way GitHub Issues export (open-seed D1: the mirror is a component, not a backend: cards are authoritative and the export direction always wins). |
|
plan
Package plan parses and lints plan files (open-seed D3): thin, mandatory, gated, pinned.
|
Package plan parses and lints plan files (open-seed D3): thin, mandatory, gated, pinned. |
|
plugin
Package plugin renders the Claude Code plugin/marketplace channel (open-seed §10 Q4, R8, plan os-221f5929): the second distribution path for the evolving parts, carrying capabilities while the template repo carries structure.
|
Package plugin renders the Claude Code plugin/marketplace channel (open-seed §10 Q4, R8, plan os-221f5929): the second distribution path for the evolving parts, carrying capabilities while the template repo carries structure. |
|
port
Package port evaluates port verbs against the loaded spec tables.
|
Package port evaluates port verbs against the loaded spec tables. |
|
prclass
Package prclass classifies PRs by head branch (open-seed D3 purity rule): plan PRs (seed/<id>-plan) touch exactly one plan file; task PRs (seed/<id>) may not touch plans/** at all, not even another task's plan, which would launder plan tampering through an unrelated review, and may touch no receipt but their own, which would launder a forged evidence record the same way.
|
Package prclass classifies PRs by head branch (open-seed D3 purity rule): plan PRs (seed/<id>-plan) touch exactly one plan file; task PRs (seed/<id>) may not touch plans/** at all, not even another task's plan, which would launder plan tampering through an unrelated review, and may touch no receipt but their own, which would launder a forged evidence record the same way. |
|
receipt
Package receipt implements the evidence chain (open-seed D4.5), split into the two things it was always trying to be at once.
|
Package receipt implements the evidence chain (open-seed D4.5), split into the two things it was always trying to be at once. |
|
skills
Package skills implements the D8 shared-skills story (plan os-6f3104db): seed.yaml names skill sources, seed.lock pins them (commit SHA + content sha256, skillfold semantics), and `seed skills install --frozen` makes the pins load-bearing in CI.
|
Package skills implements the D8 shared-skills story (plan os-6f3104db): seed.yaml names skill sources, seed.lock pins them (commit SHA + content sha256, skillfold semantics), and `seed skills install --frozen` makes the pins load-bearing in CI. |
|
spec
Package spec loads and validates the port contract from a repository's .seed/port-schema/ directory.
|
Package spec loads and validates the port contract from a repository's .seed/port-schema/ directory. |
|
stateref
Package stateref implements the seed-state ref lifecycle (§7.2): the dedicated branch carrying machine-written coordination state, written only by this shim, one commit per verb, never checked out.
|
Package stateref implements the seed-state ref lifecycle (§7.2): the dedicated branch carrying machine-written coordination state, written only by this shim, one commit per verb, never checked out. |
|
sync
Package sync generates the per-harness fan-outs from the source trees (open-seed R1): .seed/agents/ → .claude/agents/, skills/ → .claude/skills/ and .agents/skills/, rules/ fragments → the AGENTS.md managed block, and the Claude Code plugin/marketplace channel (internal/plugin, §10 Q4).
|
Package sync generates the per-harness fan-outs from the source trees (open-seed R1): .seed/agents/ → .claude/agents/, skills/ → .claude/skills/ and .agents/skills/, rules/ fragments → the AGENTS.md managed block, and the Claude Code plugin/marketplace channel (internal/plugin, §10 Q4). |
|
task
Maintenance verbs (open-seed D7/§7.2): deterministic steps the seed-maintenance workflow runs under its operator credential, no model secrets involved.
|
Maintenance verbs (open-seed D7/§7.2): deterministic steps the seed-maintenance workflow runs under its operator credential, no model secrets involved. |
|
template
Package template implements `seed template upgrade` (open-seed R8, plan os-23494e11): pull-based template updates for instantiated repos.
|
Package template implements `seed template upgrade` (open-seed R8, plan os-23494e11): pull-based template updates for instantiated repos. |
|
upgrade
Package upgrade implements `seed upgrade` (open-seed R8, plan os-4a347bd1): move the template's engine pin (.seed/engine.lock) against tagged releases: resolve the target, fetch and validate its checksums, preflight protocol compatibility, and rewrite the lockfile atomically.
|
Package upgrade implements `seed upgrade` (open-seed R8, plan os-4a347bd1): move the template's engine pin (.seed/engine.lock) against tagged releases: resolve the target, fetch and validate its checksums, preflight protocol compatibility, and rewrite the lockfile atomically. |
|
validate
Package validate lints the orchestration artifacts (open-seed R9: a shipped convention and its validator are one deliverable): guardrails (auto-merge intersection rule), team files (tier ceiling, unique priorities, non-overlapping scopes, human lead), role variants (body-hash identity: variance in binding, never in craft, §6), and plan files.
|
Package validate lints the orchestration artifacts (open-seed R9: a shipped convention and its validator are one deliverable): guardrails (auto-merge intersection rule), team files (tier ceiling, unique priorities, non-overlapping scopes, human lead), role variants (body-hash identity: variance in binding, never in craft, §6), and plan files. |
|
workflow
Package workflow implements the v2 workflow engine (plan os-52b9aed0, design §7.3 + inspirations/04 SYNTHESIS): checked-in step DAGs under .seed/workflows/<name>.yaml, validated by thirteen preflight rules and executed in topological parallel waves.
|
Package workflow implements the v2 workflow engine (plan os-52b9aed0, design §7.3 + inspirations/04 SYNTHESIS): checked-in step DAGs under .seed/workflows/<name>.yaml, validated by thirteen preflight rules and executed in topological parallel waves. |