--- id: 01KY3NRFFZTXNE3NC88F1T1GSE name: sporo version: 1.1.0 title: sporo — the recipe & seed CLI, self-installed into this repository target: sporo@0.13.0 source: https://sporo.dev stack: { language: go, runtime: darwin/arm64, why: "the verifying install ran a darwin/arm64 release archive; sporo ships static binaries for darwin and linux on amd64 and arm64" } verified: { project: sporo, release: v0.13.0, date: 2026-07-22 } effort: reference --- # sporo — the recipe & seed CLI, self-installed into this repository ## Summary sporo is a single self-installing CLI that turns a build you already finished into a transferable **recipe** — one self-contained file that teaches an agent in a repository which has never heard of your work how to rebuild the capability from principles. Standing it up gives this repository the authoring surface: the verbs to scaffold, lint, seal, and export both recipes and seeds. When this seed is done the tool answers on the command line, its embedded corpus lists, and the repository can author its own transferable builds. ## What it is sporo is a single static binary — no runtime to install, no dependency tree to resolve — that puts itself on the command line and then works inside any repository. It keeps its per-repo state in a home directory it owns, carries an embedded corpus of recipes and seeds, and maintains a registry that seals what it authors: a sealed artifact records its version and content hash, so it can never silently mutate underneath a reader. Two shapes travel through it. A **recipe** teaches an agent to *build* a capability from roles and principles, naming nothing concrete, so it survives being handed to a stranger. A **seed** — the shape you are reading now — teaches an agent to *acquire* one named tool and stand it up. Hold sporo in your head as an authoring tool that produces self-contained, auditable files, not a service you leave running. ## Install ### 1. Detect whether sporo is already present **Detect:** probe the command line for the tool and read what it reports: ``` sporo --version ``` A present install prints a version line — a release build prints its pinned version, a build from source reports a development version. Any version line means the tool is already here, so skip straight to Verify; only a "command not found" means it is absent and you should continue below. **Done when:** the probe either prints a version line (present — go to Verify) or reports the command is missing (absent — continue to step 2). ### 2. Install from the canonical origin (script route) The one-liner the project publishes fetches the latest release, verifies its checksum against the release's own checksums, and installs the binary to the reader's executable path. It traces to the origin the `source` frontmatter declares, and refuses to install anything whose checksum does not match — so the pipe runs only code that comes from the declared source: ``` curl -fsSL https://sporo.dev/install.sh | sh ``` If the chosen executable path is not on the shell's lookup path, the script prints the one line to add. On macOS it also clears the quarantine flag so the fresh binary runs. **Done when:** the version probe prints a released version line on the command line. ### 3. Install with the language toolchain (source route) With a Go 1.26+ toolchain present, the tool can be built and installed from source instead of fetching a release archive: ``` go install sporo.dev/sporo/cmd/sporo@latest ``` This builds the same source, but self-reports a development version rather than a pinned one, because the version stamp is applied only when a release archive is assembled. Make sure the toolchain's install directory is on the shell's lookup path. **Done when:** the tool resolves on the command line and its help lists the verbs. ## Verify Prove the tool actually runs here — not that an installer reported success. Run the version probe together with a functional verb that exercises the embedded corpus: ``` sporo --version sporo list ``` A version line plus a listed corpus is the proof: the binary landed and its embedded corpus reads. A missing binary, or a version line above an empty list, means the install did not fully take — return to Install. ## Use You work sporo through your agent, not by memorising its verbs. The everyday surface is a **skill** the agent now has, `sporo-recipe`: - Tell the agent *"use sporo-recipe to author a recipe from a build already finished here"* — it mines this repository's own record, drafts, lints against the genre, seals, and exports **one self-contained file** for a person to review. *"…author a seed"* packages a named tool the same way. - The raw verbs are there when a person wants them directly — `sporo new`, `sporo lint`, `sporo seal`, `sporo export`, and the `sporo seed` namespace for seeds — but the skill is the surface a human and agent share, and `sporo --help` is the full reference. This is an orientation, not the whole map: an agent working in this repository can point to more — the ways sporo fits how this repository already builds and ships. ## Harness sporo ships its own agent-facing surface, so wiring it in is not "write a rule about sporo" — it is "let sporo plant that surface where this repository keeps such things." The agent does this as part of standing the tool up: `sporo init` reads this repository's own conventions and installs the `sporo-recipe` skill into the skills home it finds, plus an agent-instructions block into the file this repo's agents already read — no path is named by hand; it detects the layout and adapts. Because that writes into files the repository owns, the agent asks before it does — the human's one move may be nothing but granting it. Do **not** hand-author a separate rule restating what sporo is: that is a second source of truth, and it drifts the first time the tool updates (`sporo update` re-syncs the managed surface without clobbering local edits). Let the tool own its harness, and keep the repository's own rules for what sporo does not cover. ## Report | row | what happened | |---|---| | **what it is** | sporo — a single self-installing CLI that turns a build already finished into a transferable recipe (or a seed like this one) an agent in another repository can rebuild from. | | **how it works** | one static binary on the executable path, a per-repo home it owns, and a sealed corpus it authors and exports; a person drives it through a skill in their agent, not by memorising verbs. | | **what was done** | detected and installed the binary from the declared source (or built it from source) and verified it runs; if the harness step was taken, it also planted the `sporo-recipe` skill and an agent-instructions block into this repository — with permission, and nothing else changed. | | **how to use it** | nothing to install by hand — it is set up. To use it, ask the agent to run the `sporo-recipe` skill: *"author a recipe"* (or *"author a seed"*), and it walks the whole build to one sealed file a person reviews. The agent can show more, fitted to this repository. | | **suggest next** | package a build worth keeping as a recipe and share the exported file with someone on a different stack — the agent does the authoring; a person only points it at the build. |