Metadata-Version: 2.4
Name: rollout-cli
Version: 0.3.0
Summary: Cross-repo propagation workflow built on refactor-cli — apply a transformation across many repos at once.
Project-URL: Homepage, https://github.com/agentculture/rollout-cli
Project-URL: Issues, https://github.com/agentculture/rollout-cli/issues
Author: Ori Nachum
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# 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](https://github.com/agentculture/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`](docs/skill-sources.md).
- **A build + deploy baseline** — pytest, lint, the agent-first rubric gate, and
  PyPI Trusted Publishing wired into GitHub Actions.

## Quickstart

```bash
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`](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`](docs/skill-sources.md)).

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

## License

Apache 2.0 — see [`LICENSE`](LICENSE).
