spawn-cli 0.1.20

What is Spawn?

Spawn is a framework for building AIDD (AI-driven development) methodologies — an agent harness that wraps your coding agent in an orchestration layer. It supports both authoring methodologies and applying them in a project. Within a single repository you can use several AIDD methodologies in a coherent way—shared navigation, skills, rules, and tooling stay aligned instead of competing ad hoc setups.

What is spawn-cli?

spawn-cli is the utility that manages methodologies installed in your project. In Spawn terminology those packs are extensions: versioned content that usually lives in a Git repository. The CLI instantiates instruction files, process descriptions, rules, agent skills, and wires their behavior together (navigation, IDE-facing outputs, optional lifecycle hooks). Extensions can also declare MCP servers, agent-ignore patterns, git-ignore entries, and similar integration points—see spec/design/extension-author-guide.md.

How spawn-cli keeps methodologies coherent

Several methodologies in one repo stay aligned because Spawn maintains one shared navigation index: spawn/navigation.yaml aggregates mandatory and contextual reads from every installed extension plus local spawn/rules/ (refreshed with spawn rules refresh). Agents are steered through that file instead of chasing disconnected README fragments.

On each install or refresh, the CLI regenerates IDE-facing artifacts so skills and entry points stay consistent across extensions: rendered skill bodies include paths and descriptions wired from navigation (required reads, contextual hints, rule files), MCP snippets normalize server definitions per IDE adapter, and ignore lists merge without manual copy-paste. The net effect is that methodology files, generated skill links, and repo rules compose rather than contradict each other. Optional hints add short reminders to rendered skills and the Spawn-managed entry block.

Example: spawn-ext-spectask (Spec-Tasks methodology: spec layout, skills, design index) and spawn-ext-creator (authoring flows, including agent-guided extension bootstrap) can be installed in the same repository and still share that single index and merged IDE outputs.

How to install spawn-cli

Recommended: install spawn on your PATH with uv:

uv tool install spawn-cli && spawn --help

Run once without installing (ephemeral uvx):

uvx --from spawn-cli spawn --help

Upgrade the persistent uv tool:

uv tool upgrade spawn-cli && spawn --help

Force a fresh resolver for a one-shot run:

uvx --refresh --from spawn-cli spawn --help

Additional installers (pip, pipx, local checkout) and upgrade notes: spec/design/user-guide.md.

How spawn-cli works

Run commands from the root of the repository you are configuring. Almost every command requires spawn init first (it creates the spawn/ tree). Only one Spawn process should touch a repo at a time (file lock).

Initialize a repo

spawn init

IDE adapters

For each supported IDE adapter, show whether it looks used in the current repository and what it can render (e.g. skills, MCP, agent-ignore):

spawn ide list-supported-ides

Register or drop IDE keys for this repo (examples: cursor, codex):

spawn ide add cursor
spawn ide add cursor codex
spawn ide remove codex
spawn ide list

Extensions

Add from a Git URL, optional branch (also supports ZIP paths and local directories/archives):

spawn extension add https://github.com/noant/spawn-ext-spectask
spawn extension add https://github.com/noant/spawn-ext-spectask --branch main

Maintain installed packs:

spawn extension list
spawn extension update spectask
spawn extension reinstall spectask
spawn extension remove spectask
spawn extension healthcheck spectask

Authoring helpers (run inside or next to an extension project):

spawn extension init ./my-ext --name my-ext
spawn extension check ./my-ext
spawn extension check ./my-ext --strict
spawn extension from-rules ./repo-with-spawn-rules --name my-ext --output ./out

Navigation from repo rules

After editing files under spawn/rules/, refresh mandatory reads in spawn/navigation.yaml:

spawn rules refresh

Batch install from a build manifest

spawn build list / spawn build install take a build source (positional argument; there is no implicit default):

• Local directory whose root contains extensions.yaml. Spawn resolves the path (e.g. . → current working directory) and reads <that-directory>/extensions.yaml — not a path to the YAML file itself.
• Otherwise a Git URL, ZIP URL, or local path to a repository tree: Spawn stages it, then looks for extensions.yaml at that root or, if there is exactly one top-level subdirectory, under that folder (extensions.yaml not found if neither applies).

Each manifest entry is an extension source; optional per-entry branch overrides the CLI default for that row.

Minimal extensions.yaml:

extensions:
  - path: https://github.com/org/extension-one.git
    branch: main
  - path: https://github.com/org/extension-two.git

Dry-run (prints resolved entries as YAML), then install:

# Manifest at ./extensions.yaml (cwd is usually your initialized target repo if you keep it there)
spawn build list .
spawn build install .

spawn build install /path/to/methodology-bundle
spawn build install https://github.com/org/team-methodology.git --branch main

The --branch flag applies when the build source is Git (clone revision). Entries that omit branch fall back to that value.

Example extension

spawn-ext-spectask is a concrete extension you can install with spawn extension add as shown above.

• Python: 3.10+ (see pyproject.toml).
• Deep dives: spec/design/user-guide.md and spec/design/utility.md.

How to create an extension

An extension can be a full AIDD methodology, team conventions (review rules, codestyle), scaffolds for projects that default to AIDD-friendly layouts, skill-only bundles, or anything else you can express as declarative files plus optional setup hooks—anything that fits the extsrc/ layout described in the author guide.

Bootstrap with the creator extension (install like any other extension after spawn init):

spawn extension add https://github.com/noant/spawn-ext-creator

Scaffold an empty extension with the CLI (requires spawn init in the repo you run from — same as other subcommands). This lays out extsrc/ with a starter config.yaml, plus empty skills/, files/, and setup/:

spawn extension init --name my-extension
spawn extension init ./my-extension --name my-extension

Agent-guided scaffold with spawn-ext-creator (install the extension above, then spawn ide add <ide> so skills render into your IDE): invoke the spawn-ext-bootstrap skill so the agent lays out a fuller extension repo than the bare CLI skeleton—for example:

Use the spawn-ext-bootstrap skill to bootstrap a new Spawn extension.

Other creator skills (declaring config.yaml, skill sources, MCP, verification, etc.) ship under the same extension; see the rendered skill list after install.

Read spec/design/extension-author-guide.md for the full model: required extsrc/config.yaml, mapping files under extsrc/files/, optional skills/, mcp.json, agent-ignore, setup/ scripts, and how static vs artifact content is updated on spawn extension update.

Minimal mental model:

• extsrc/config.yaml — schema, version, stable name (install path spawn/.extend/<name>/), plus files, skills, ignores, optional hints, etc.
• extsrc/files/ — template tree mirrored into the target repo according to files: entries.
• spawn extension check . --strict — validate before publishing or tagging a release.

How to add rules without creating an extension

You can steer agents in two complementary ways that do not require an extension: rule files under spawn/rules/ (content the agent must or may read), and short hints in spawn/navigation.yaml (reminders merged into rendered skills and IDE entry-point blocks such as AGENTS.md).

After edits to **spawn/rules/** or to rule rows / hint in spawn/navigation.yaml, run spawn refresh so navigation, skills, and entry points stay in sync. spawn rules refresh only syncs **spawn/rules/** into navigation.yaml—no skill or entry-point updates.

1. Rule files

Project-local conventions live as files under spawn/rules/. After spawn init, add any files there (for example spawn/rules/team.md); Spawn discovers every file under that directory tree.

Wire those paths into spawn/navigation.yaml so reads stay aligned with what is on disk:

spawn refresh

That rescans spawn/rules/, attaches missing rule files under a rules group inside read-required (default description Local rule file. until you edit it), and drops stale entries whose files were deleted (you may see a warning).

Tiers: list a rule under read-required → rules (always read) or read-contextual → rules (read when relevant). Use the same row shape (path, description). A path must not appear in both lists—after you move a row, rerun spawn refresh (or spawn rules refresh if you only need YAML). New files discovered on disk are appended to read-required → rules until you relocate them.

Extension reads: ext: blocks are unrelated; repo-local rule paths live only under spawn/rules/** and the rules groups in spawn/navigation.yaml.

2. Hints in spawn/navigation.yaml

For short, always-visible reminders (tone, language, repo-specific habits), add hint-only rows under read-required → rules (a hint entry without a path). Mandatory rule files use rows with path and description only—do not add hint on the same row as path; if refresh finds legacy pairs, it splits them into a file row and a following hint-only row.

Hints from read-required → rules (hint-only rows) appear in skills’ Hints section and in the managed AGENTS.md rollup together with extension hints.global, using YAML row order within maintainer hints before dedupe (hint on read-contextual → rules is still not included there).

If a path names a spawn/rules/… file that does not exist when navigation is refreshed, that row is removed entirely — fix or drop path first; hint on that same removed row is not downgraded to a hint-only row.

Example:

read-required:
  - rules:
      - path: spawn/rules/team.md
        description: Team conventions.
      - hint: Prefer British spelling in user-facing copy.
      - hint: Short standalone reminder with no rule file.

Then run spawn refresh so skills and entry points pick up the hint.

License

MIT — see LICENSE.

P.S. Below is a diagram that might help you understand how Spawn works.