rollout-cli

Cross-repo propagation workflow built on refactor-cli — apply a transformation across many repos at once.

What you get

• An agent-first CLI cited from teken (afi-cli) — the runtime package has no third-party dependencies.
• A mesh identity — culture.yaml (suffix + backend) and the matching prompt file (CLAUDE.md for backend: claude).
• The canonical guildmaster skill kit (11 skills) under .claude/skills/, vendored cite-don't-import. See docs/skill-sources.md.
• A build + deploy baseline — pytest, lint, the agent-first rubric gate, and PyPI Trusted Publishing wired into GitHub Actions.

Quickstart

uv sync
uv run pytest -n auto                 # run the test suite
uv run rollout-cli whoami  # identity from culture.yaml
uv run rollout-cli learn   # self-teaching prompt (add --json)
uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs

CLI

Verb	What it does
whoami	Report this agent's nick, version, backend, and model from culture.yaml.
learn	Print a structured self-teaching prompt.
explain <path>	Markdown docs for any noun/verb path.
overview	Read-only descriptive snapshot of the agent.
doctor	Check the agent-identity invariants (prompt-file-present, backend-consistency).
cli overview	Describe the CLI surface itself.

Every command supports --json. Results go to stdout, errors/diagnostics to stderr (never mixed). Exit codes: 0 success, 1 user error, 2 environment error, 3+ reserved.

Rollout Engine

Operator vs Agent Roles

• Operator — defines the recipe, selects targets (--org / --repos), reviews the plan output, and confirms the apply. The operator is the only party that can merge PRs.
• Agent — executes the deterministic steps: resolve targets, classify repos, branch, apply scripts, bump versions, commit, push, and open PRs. The agent never merges and never makes edits not declared by a recipe.

Recipe Model

A recipe is a directory containing:

• manifest.toml — metadata (name, touched_files, bump_level, changelog_text).
• apply.sh — idempotent script that applies the transformation.
• check.sh — pre-flight script that classifies a repo as done, ok, or needs-attention.

The recipe model ensures every file change is declared up-front; rollout never writes to the worktree outside of apply.sh and the deterministic version bumper.

Two-Phase Flow: Plan → Apply

1. rollout plan — dry-run. Resolves targets, classifies each as clean, already-done, or needs-attention, and renders per-repo diffs. No branches, no pushes.
2. rollout apply — after operator confirmation (or --yes), applies the recipe to clean targets only: branch from origin/main, run apply.sh, bump version, commit, push, and open one PR per repo. A summary table of PR URLs is printed.

Boundary

• Rollout never merges PRs — that is the operator's responsibility.
• Rollout never makes edits not declared by a recipe's apply.sh or the deterministic version bumper.
• CI is each repo's own — each target repo runs its own CI pipeline; rollout does not gate on CI results.

Make it your own

1. Rename the package rollout/ and the rollout-cli CLI/dist name throughout pyproject.toml, the package, tests/, sonar-project.properties, and this README.md. The name is hard-coded in ~100 places, so list every occurrence first — see the git grep discovery command in CLAUDE.md, the authoritative rename procedure.
2. Edit culture.yaml with your suffix and backend.
3. Rewrite CLAUDE.md for your agent and run /init.
4. Re-vendor only the skills you need from guildmaster (see docs/skill-sources.md).

See CLAUDE.md for the full conventions (version-bump-every-PR, the cicd PR lane, deploy setup).

License

Apache 2.0 — see LICENSE.