steward-cli 0.1.2__tar.gz → 0.3.0__tar.gz

steward_cli-0.3.0/.claude/skills/doc-test-alignment/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: doc-test-alignment
+description: >
+  Verify that committed docs (README.md, CLAUDE.md, SKILL.md descriptions) still
+  describe what the code and tests actually do. Use at the end of a plan, before
+  PR creation, or when the user says "check doc-test alignment", "verify docs",
+  or "do the docs still match the code". STUB — `scripts/check.sh` exits with a
+  not-yet-implemented error today; the contract for what it will do lives in
+  this file.
+---
+
+# doc-test-alignment (stub)
+
+This skill is a stub. The real workflow is intentionally not yet implemented —
+the file exists so that `steward verify` can find it and so contributors who
+land here know it is on the roadmap, not forgotten.
+
+## How to run
+
+`scripts/check.sh` is the entry point. Today it prints a not-yet-implemented
+notice and exits non-zero. When the workflow lands, the script will gate
+PR-readiness on the alignment contract below; until then, treat any green
+exit code from this script as a bug.
+
+## What it will check
+
+The skill is the contract for four narrow alignments. README.md command
+examples must still execute against the current checkout and produce output
+that matches the surrounding prose. The "build/test/publish" command lines in
+CLAUDE.md must do the same. For each `.claude/skills/<name>/`, the SKILL.md
+`description` frontmatter must agree with what the scripts under
+`scripts/` actually do — surfacing disagreements (e.g. SKILL.md claims the
+skill bumps versions but `scripts/` has no bump script). And for each test,
+the test name should still describe the assertions the test makes — flagging
+drift where the name advertises a feature the assertions no longer touch.
+
+## Why it ships as a stub
+
+Each of those four checks is independently non-trivial. Shipping a partial
+implementation would either silently pass when it shouldn't, or false-positive
+on intentional doc-vs-code differences. The right path is to land the checks
+one at a time, with their own tests, behind a
+`steward verify --check doc-test-alignment` flag. The parent verbs (`verify`,
+`doctor`) are named in the "Roadmap" section of `CLAUDE.md`; the broader
+sibling-pattern contract lives in `docs/sibling-pattern.md`.
+
+## What this stub guarantees today
+
+- The skill directory exists, so `steward verify`'s skills-convention check
+  finds the standard layout (SKILL.md + `scripts/` with an entry-point).
+- `scripts/check.sh` is the entry-point script, satisfying the steward skills
+  convention requirement that every skill ships an executable script.
+- This `SKILL.md` is the contract for what the skill will do — when the
+  implementation lands, it must satisfy this description or the description
+  must move first.

steward_cli-0.3.0/.claude/skills/doc-test-alignment/scripts/check.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# doc-test-alignment skill — entry point.
+#
+# STUB: the real workflow is not implemented yet. This script exists so the
+# steward skills convention is satisfied (every skill ships an executable
+# entry-point script); when the real implementation lands here, it must
+# satisfy the contract documented in ../SKILL.md.
+#
+# Exits 2 (EXIT_USER_ERROR-ish for "you asked for something that isn't
+# wired up yet") so callers can tell the difference between "checks passed"
+# (would be 0) and "stub".
+
+set -euo pipefail
+
+cat >&2 <<'EOF'
+doc-test-alignment: not yet implemented.
+
+This skill is a stub; the contract for what `check.sh` will assert lives in
+.claude/skills/doc-test-alignment/SKILL.md. Until the implementation lands,
+treat any green exit code from this script as a bug.
+
+Roadmap: see CLAUDE.md ("Roadmap (CLI surface)") and docs/sibling-pattern.md.
+EOF
+exit 2

{steward_cli-0.1.2 → steward_cli-0.3.0}/.markdownlint-cli2.yaml

@@ -1,6 +1,6 @@
 # markdownlint-cli2 config for steward.
-# markdownlint-cli2 stops walking at the git root, so the user's global
-# ~/.markdownlint-cli2.yaml isn't picked up from inside the repo.
+# markdownlint-cli2 stops walking at the git root, so a per-user global
+# config in the home directory isn't picked up from inside the repo.
 # Mirrors the afi-cli / cfafi preset for workspace consistency.
 
 config:

steward_cli-0.3.0/CHANGELOG.md

@@ -0,0 +1,106 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/). This project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-04-26
+
+### Added
+
+- `steward doctor --scope siblings` walks every `culture.yaml` in the workspace, scores each declared agent against a corpus-derived baseline, writes per-target feedback into `<target>/docs/steward/steward-suggestions.md` (gated by a marker line so hand-written content there is preserved), and refreshes `docs/perfect-patient.md` in the steward checkout. Diagnostic-only — corpus mode never exits non-zero on per-agent drift.
+- `docs/perfect-patient.md` — committed placeholder; populated on each `--scope siblings` run with required/recommended `culture.yaml` fields, the common skills baseline, common `CLAUDE.md` sections, and corpus stats.
+- `steward/cli/_commands/_corpus.py` — pure helpers (`discover_agents`, `synthesize_baseline`, `render_perfect_patient`, `score_culture_yaml_shape`, `score_agent_against_baseline`, `write_repo_report`) used by `doctor --scope siblings`. Tested in isolation by `tests/test_corpus.py`.
+- `tests/test_corpus.py` and `tests/test_cli_doctor_siblings.py` — unit + end-to-end coverage for corpus mode (discovery handles both `agents:` lists and flat root-level `suffix:` shapes; baseline classification by frequency; report writer is idempotent and preserves hand-written content; JSON output shape; empty-workspace diagnostic; --no-write-reports / --no-refresh-perfect-patient gates).
+
+### Changed
+
+- **Renamed `steward verify` → `steward doctor`** (single-repo mode). Same checks (`portability`, `skills-convention`), same flags (`--json`, `--check`), same exit semantics (non-zero on findings). New flags: `--scope {self,siblings}` (default `self` is backward-compatible with `verify`), `--workspace-root`, `--no-write-reports`, `--no-refresh-perfect-patient`, `--perfect-patient-out`. No `verify` alias kept — this is a breaking CLI change.
+- Added `pyyaml>=6.0` as the first runtime dependency. Required to parse sibling `culture.yaml` manifests in corpus mode; the existing `agent-config` skill already shells out to a Python+PyYAML one-liner, so the dep was implicit.
+- `docs/sibling-pattern.md` and `CLAUDE.md` Roadmap section rewritten to describe `doctor`'s two scopes (self / siblings) and reposition the planned `--apply` repair handlers as the next layer.
+
+## [0.2.0] - 2026-04-26
+
+### Added
+
+- `steward verify <path>` — read-only diagnosis of a sibling repo against the
+  AgentCulture sibling pattern. Two checks today: `portability` (runs steward's
+  own vendored `portability-lint.sh --all` with `cwd=<target>`, so the target
+  doesn't need to vendor it and `verify` only ever executes a known-trusted
+  script) and `skills-convention` (every `SKILL.md` has a sibling `scripts/`
+  directory and a matching frontmatter `name`). Aggregates findings across all
+  selected checks; human-readable findings go to stderr, `--json` puts the
+  structured findings list on stdout. `--check <name>` repeatable. Exits 1 if
+  any finding was reported.
+- `docs/sibling-pattern.md` — single source of truth for the AgentCulture
+  sibling pattern (12 required artifacts, 5 machine-checkable invariants,
+  5 deterministic repairs). Consumed by `steward verify`; will be consumed
+  by the future `steward doctor`.
+- `docs/skill-sources.md` — per-skill upstream declarations and vendoring
+  policy so `doctor` can vendor deterministically.
+- `.claude/skills/doc-test-alignment/` — stub skill describing the intended
+  doc/test alignment workflow. Implementation TBD.
+- `tests/test_skills_convention.py` — repo-level invariants for steward's own
+  skills (every skill has SKILL.md + scripts/, frontmatter name matches dir,
+  no per-user/home-dir paths in skill scripts).
+- `tests/test_cli_verify.py` — end-to-end tests for the new verb, including a
+  dogfood test that runs `steward verify` against steward itself.
+
+### Changed
+
+- `CLAUDE.md` gains a "Roadmap (CLI surface)" section naming `verify` and
+  `doctor` as the next two verbs.
+- `.markdownlint-cli2.yaml` header comment reworded to avoid tripping the
+  portability lint with its own self-reference (caught by the new
+  `tests/test_cli_verify.py` dogfood test on first run).
+- `tests/test_cli.py` help-output assertion loosened to match individual
+  verb names instead of the literal `{show}` group, so adding verbs doesn't
+  break it.
+
+## [0.1.2] - 2026-04-26
+
+### Added
+
+- `.markdownlint-cli2.yaml` at repo root mirroring afi-cli/cfafi (3143024675).
+- `lint` job in tests.yml running black --check, isort --check, flake8, bandit -c pyproject.toml, and markdownlint-cli2 (3143024677).
+- `.flake8` config so flake8 honors the 100-char line length and ignores E203/W503 (matches black).
+
+### Changed
+
+- `steward show` walk-up now stops at the git repo boundary so the script is only ever resolved within the user's current checkout (3143024681; eliminates the path-injection risk).
+- `bump.py` changelog formatter emits single blank lines between elements (markdownlint MD012 compliant). Past triple-newlines in the 0.1.1 entry cleaned up.
+- Tightened the `version-bump` SKILL.md: dropped the numbered Workflow section, replaced with short prose pointing to the script (3143024680).
+- Replaced the inline `# noqa: S603 - explanation` syntax in show.py with a separate explanatory comment block above and a bare `# noqa: S603` (SonarCloud python:S7632).
+
+### Fixed
+
+- CLAUDE.md: code-block fence now `text`-tagged (markdownlint MD040).
+
+## [0.1.1] - 2026-04-26
+
+### Changed
+
+- test_python_m_steward_version uses sys.executable instead of literal python (3143024074).
+- show.sh returns exit 2 for user errors (unknown suffix) and exit 1 for env errors (missing manifest, missing PyYAML); the steward CLI maps these to USER_ERROR/ENV_ERROR respectively (3143024081).
+
+### Fixed
+
+- bump.py docstring no longer overstates what gets updated; the `__init__.py` rewrite is conditional and is a no-op for steward (3143024085).
+
+## [0.1.0] - 2026-04-26
+
+### Added
+
+- `pyproject.toml` (steward-cli) with hatchling backend, `steward = "steward.cli:main"` entry point, Python ≥3.12. Zero runtime dependencies.
+- `steward/` package: `__init__.py` (importlib.metadata version lookup), `__main__.py` (`python -m steward`), `cli/` (argparse entry point modeled on afi-cli's pattern with structured `StewardError` plumbing).
+- `steward show <target>` subcommand that wraps the `agent-config` skill's `show.sh`. Walks up from cwd to locate the script; fails cleanly with a remediation hint if not in a Steward checkout.
+- `tests/test_cli.py` — pytest suite covering `--version`, no-args help, unknown-subcommand error path, the `show` happy path against this repo, and `show` outside a Steward checkout.
+- `.github/workflows/tests.yml` — pytest on every PR + push to main, with a `version-check` job that fails if `pyproject.toml` version isn't bumped (mirrors the cfafi convention; allows the initial scaffold via the "no main version yet" branch).
+- `.github/workflows/publish.yml` — push to main publishes to PyPI via OIDC Trusted Publishing; PRs publish a `.dev<run_number>` to TestPyPI for smoke-testing. Fork PRs are skipped (no OIDC context).
+- `.claude/skills/version-bump/` — vendored from afi-cli; bumps `pyproject.toml` and prepends a Keep-a-Changelog entry.
+
+### Changed
+
+- `CLAUDE.md` — drop the "greenfield" framing, document the build/test/publish convention, and replace "Conventions to apply when scaffolding" with "Conventions in use".
+- `README.md` — add Install + Usage sections.

{steward_cli-0.1.2 → steward_cli-0.3.0}/CLAUDE.md

@@ -25,7 +25,9 @@ steward/                    # Python package (pip install steward-cli)
     ├── _errors.py          # StewardError + EXIT_USER_ERROR / EXIT_ENV_ERROR
     ├── _output.py          # emit_result / emit_error / emit_diagnostic
     └── _commands/          # subcommand modules; each has register(sub) + handler
-        └── show.py         # `steward show <target>` → wraps agent-config skill
+        ├── show.py         # `steward show <target>` → wraps agent-config skill
+        ├── doctor.py       # `steward doctor` → single-repo or corpus diagnosis
+        └── _corpus.py      # corpus helpers used by `doctor --scope siblings`
 tests/                      # pytest suite
 .claude/skills/             # see "Skills convention" below
 .github/workflows/          # tests.yml + publish.yml (OIDC Trusted Publishing)
@@ -61,6 +63,42 @@ Per-machine paths (Culture server manifest location, sibling-project paths, etc.
 
 Steward is a "skills supplier" for the Culture mesh. When a skill stabilizes here, the next step is propagating it to sibling projects (`culture`, `daria`, etc.) — the all-backends rule applied to skills.
 
+## Roadmap (CLI surface)
+
+The CLI ships two verbs today: `steward show` and `steward doctor`. Doctor
+runs in two modes — single-repo diagnosis (the original "verify" flow,
+folded into doctor) and corpus mode (the agent-iteration flow). The
+`--apply` repair mode is the next layer on top.
+
+- `steward doctor <path>` (default `--scope self`) — score a target repo
+  against `docs/sibling-pattern.md`. Aggregates findings across all
+  selected checks, then exits non-zero if any finding was reported.
+  Human-readable findings go to stderr; `--json` emits the structured
+  findings list to stdout. Today: `portability` (runs steward's own
+  vendored `.claude/skills/pr-review/scripts/portability-lint.sh` against
+  the target, so the target doesn't need to vendor it) and
+  `skills-convention` (every `SKILL.md` has a sibling `scripts/`
+  entry-point and matching frontmatter `name`).
+- `steward doctor --scope siblings` — walks every `culture.yaml` in the
+  workspace (`<workspace-root>/*/culture.yaml`, sibling-only by default),
+  tallies field/skill/CLAUDE.md-section frequency across the corpus to
+  synthesize `docs/perfect-patient.md`, scores every declared agent
+  against that baseline, and writes per-target feedback into
+  `<target>/docs/steward/steward-suggestions.md` (gated by a marker line
+  so hand-written content in that path is preserved). Diagnostic-only —
+  exits 0 even when individual agents drift from the baseline; that is
+  reported in the per-target file rather than as a CLI failure.
+- `steward doctor --apply` *(planned)* — repair what diagnosis flagged,
+  where the repair is unambiguous (missing `scripts/` directory, missing
+  `.markdownlint-cli2.yaml`, missing `.claude/skills.local.yaml.example`,
+  etc.). Larger emissions (CLI scaffold) land later as additional repair
+  handlers, eventually consuming `../afi-cli/afi/cite/_engine.py` rather
+  than re-implementing it.
+
+Per-skill upstreams (which repo owns the canonical copy of `version-bump`,
+`pr-review`, etc.) are recorded in `docs/skill-sources.md` so `doctor` can
+vendor deterministically.
+
 ## Working with Culture from here
 
 Steward will need to read or write Culture artifacts (agent definitions, server configs, mesh links). Useful entry points:

{steward_cli-0.1.2 → steward_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steward-cli
-Version: 0.1.2
+Version: 0.3.0
 Summary: Steward — aligns and maintains resident agents across Culture projects.
 Project-URL: Homepage, https://github.com/agentculture/steward
 Project-URL: Issues, https://github.com/agentculture/steward/issues
@@ -13,6 +13,7 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development
 Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6.0
 Description-Content-Type: text/markdown
 
 # steward

steward_cli-0.3.0/docs/perfect-patient.md

@@ -0,0 +1,35 @@
+# Perfect patient
+
+> This file is auto-generated by `steward doctor --scope siblings`. The
+> committed copy is a placeholder; run the command locally to populate it
+> with real corpus statistics from the `culture.yaml` files in your
+> workspace.
+>
+> The baseline is descriptive, not prescriptive: it describes what a
+> typical healthy agent looks like in the current corpus, so drift can
+> be spotted. Edit by hand only if you intend to ratchet the bar —
+> `steward doctor --scope siblings` overwrites this file.
+
+## Required `culture.yaml` fields
+
+Populated on first `steward doctor --scope siblings` run.
+
+## Recommended `culture.yaml` fields
+
+Populated on first `steward doctor --scope siblings` run.
+
+## Common skills baseline
+
+Populated on first `steward doctor --scope siblings` run.
+
+## Recommended skills
+
+Populated on first `steward doctor --scope siblings` run.
+
+## Common `CLAUDE.md` sections
+
+Populated on first `steward doctor --scope siblings` run.
+
+## Corpus stats
+
+Populated on first `steward doctor --scope siblings` run.

steward_cli-0.3.0/docs/sibling-pattern.md

@@ -0,0 +1,90 @@
+# AgentCulture sibling pattern
+
+The shape every AgentCulture sibling repo (`steward`, `cfafi`, `ghafi`, `daria`,
+…) is expected to wear. This document is the single source of truth that
+`steward doctor` consumes.
+
+The companion file `sibling-pattern.json` (TBD; emit from this doc) is the
+machine-readable form. Until it lands, the checks `doctor` runs are hard-coded
+in `steward/cli/_commands/doctor.py`; this document remains the human-readable
+contract that those hard-coded checks are expected to honor.
+
+`steward doctor` runs in two modes:
+
+- **`--scope self <target>`** (default) — the single-repo invariants below
+  (portability, skills-convention).
+- **`--scope siblings`** — walks every `culture.yaml` in the workspace, scores
+  each declared agent against a corpus-derived baseline
+  (`docs/perfect-patient.md`, regenerated on each run), and writes a per-target
+  report into `<target>/docs/steward/steward-suggestions.md`.
+
+## Required artifacts
+
+| # | Artifact | Path | Why |
+|---|----------|------|-----|
+| 1 | Toolchain | `pyproject.toml` (hatchling, Python ≥3.12, zero runtime deps where possible) | Uniform install/build/publish across the mesh. |
+| 2 | Top-level package | `<pkg>/__init__.py`, `<pkg>/__main__.py` | `__version__` via `importlib.metadata`; `python -m <pkg>` works. |
+| 3 | CLI scaffolding | `<pkg>/cli/__init__.py`, `cli/_errors.py`, `cli/_output.py`, `cli/_commands/` | The afi-cli pattern: structured errors, stdout/stderr split, `--json`. |
+| 4 | Agent-first verbs | `cli/_commands/{learn,explain,whoami}.py` | `learn`/`explain` are the agent-affordance verbs; `whoami` is the smallest auth probe. |
+| 5 | Mutation safety | Any write verb defaults to dry-run; `--apply` to commit | Agents call CLIs in loops; safe-by-default is mandatory. |
+| 6 | Tests | `tests/test_cli_*.py`, pytest-xdist, coverage | CI gate; no untested verb ships. |
+| 7 | CI | `.github/workflows/tests.yml`, `.github/workflows/publish.yml` | Tests + lint + version-check; PyPI/TestPyPI via Trusted Publishing. |
+| 8 | Changelog | `CHANGELOG.md` (Keep-a-Changelog) | Bumped on every PR by the `version-bump` skill. |
+| 9 | Skills | `.claude/skills/<name>/SKILL.md` + `scripts/` entry-point per skill | Convention: no external path deps, no per-user dotfile refs. |
+| 10 | Per-machine config | `.claude/skills.local.yaml.example` (committed) + `.claude/skills.local.yaml` (git-ignored) | Skills read the local file, fall back to the example. |
+| 11 | Lint configs | `.flake8`, `.markdownlint-cli2.yaml` (repo-local) | No reliance on per-user home-directory configs. |
+| 12 | `CLAUDE.md` | Project shape, build/test/publish commands, conventions | What future Claude instances need that isn't discoverable from a 30-second `ls`. |
+
+## Invariants (machine-checkable)
+
+The full set of invariants the AgentCulture sibling pattern asserts. The
+**Status** column reflects what is wired into `steward doctor --scope self`
+*today*; items marked `(planned)` are described here as the contract `doctor`
+is expected to grow into.
+
+- **portability** *(implemented as `--check portability`)* — no
+  `/home/<user>/...` paths in tracked files; no `~/.<dotfile>` config refs in
+  committed `.md`/`.yaml`/`.toml`/`.json`/`.jsonc` outside the carve-outs
+  (`~/.claude/skills/.../scripts/`, `~/.culture/`).
+  *Source:* `.claude/skills/pr-review/scripts/portability-lint.sh`.
+- **skills-convention** *(implemented as `--check skills-convention`)* —
+  every `.claude/skills/<name>/SKILL.md` has a sibling
+  `.claude/skills/<name>/scripts/` directory, **and** the SKILL.md frontmatter
+  `name` equals the directory name. (The "every skill has at least one
+  entry-point script" invariant is satisfied by the directory existing today
+  to keep the check noise-free; tightening to "directory has ≥1 file" is
+  *(planned)*.)
+- **changelog-format** *(planned)* — `CHANGELOG.md` has at least one
+  `## [x.y.z] - YYYY-MM-DD` heading.
+- **lint-config-local** *(planned)* — `.markdownlint-cli2.yaml` exists at the
+  repo root (no reliance on per-user home configs).
+
+## Repairs (machine-fixable, run by `steward doctor`)
+
+`steward doctor --apply` is **not yet implemented** (see `CLAUDE.md`'s
+Roadmap section); the table below is the contract it will honor when it
+lands. A repair is included only if it is **deterministic and idempotent**.
+Where the right answer depends on judgement, `doctor` will report the gap
+and stop.
+
+| Invariant violated | Planned repair |
+|--------------------|----------------|
+| `.claude/skills/<name>/scripts/` missing | Create the empty directory + a stub entry-point script. |
+| `.markdownlint-cli2.yaml` missing | Vendor steward's copy verbatim. |
+| `.claude/skills.local.yaml.example` missing | Vendor a minimal template documenting the `culture_server_yaml` and `sibling_projects` keys. |
+| `CHANGELOG.md` missing | Create a Keep-a-Changelog skeleton with one `## [Unreleased]` heading. |
+| `SKILL.md` frontmatter `name` ≠ dir name | Reported only — too many false-positive renames to auto-correct. |
+| Hard-coded `/home/...` path in tracked file | Reported only — fix requires understanding intent. |
+
+## Skill upstream policy
+
+Per-skill upstream declarations live in `docs/skill-sources.md`. `doctor`
+consults that file when vendoring a skill into a target sibling: each skill
+has exactly one canonical source repo, and `doctor` copies from there.
+
+## Out of scope (for the pattern, not for steward)
+
+- Pre-commit hooks (suggested but not required; siblings vary on this).
+- Specific CI runners or Python versions beyond ≥3.12.
+- Anything Culture-mesh-specific (server manifest, agent definitions) — that
+  belongs in `docs/` of the relevant Culture-side project, not in this pattern.

steward_cli-0.3.0/docs/skill-sources.md

@@ -0,0 +1,43 @@
+# Skill upstream sources
+
+Each skill has exactly one canonical source repo. `steward doctor` consults
+this file when vendoring a skill into a target sibling so the choice is
+deterministic.
+
+When a skill exists in multiple repos, the **upstream** column wins. Other
+repos are downstream copies that may lag and should periodically re-sync from
+upstream.
+
+| Skill | Upstream | Downstream copies (known) | Notes |
+|-------|----------|---------------------------|-------|
+| `version-bump` | `steward` (`.claude/skills/version-bump/`) | `cfafi`, `afi-cli` | Pure Python, prepends Keep-a-Changelog entry; no per-repo customization needed. |
+| `pr-review` | `steward` (`.claude/skills/pr-review/`) | `cfafi` (variant) | Steward owns the canonical workflow; downstream copies may add reviewer-specific wiring (Qodo/Copilot, etc.). |
+| `agent-config` | `steward` (`.claude/skills/agent-config/`) | — | Steward-specific (resolves Culture agent suffixes); not portable as-is. |
+| `doc-test-alignment` | `steward` (`.claude/skills/doc-test-alignment/`) | — | Stub; real implementation TBD. |
+| `cfafi`, `cfafi-write` | `cfafi` (`.claude/skills/cfafi*/`) | — | CloudFlare-specific; not vendored elsewhere. |
+| `poll` | `cfafi` (`.claude/skills/poll/`) | — | Background-reviewer subagent; candidate for promotion to `steward` if it stabilizes. |
+
+## Vendoring policy
+
+- **Cite, don't import.** Skills are copied into the consuming repo, not
+  symlinked or installed as a dependency. Each consumer owns and may modify
+  their copy.
+- **Re-sync explicitly.** When upstream changes, downstream copies do not
+  auto-update. `steward doctor --skill <name>` is the intended re-sync path
+  (TBD).
+- **Diverge intentionally.** A downstream copy may diverge for repo-specific
+  reasons (e.g. `cfafi`'s `pr-review` adds CloudFlare-API reviewers). Record
+  the divergence in the downstream `SKILL.md`'s frontmatter `description`.
+
+## When a skill should be promoted upstream
+
+A skill currently owned downstream (e.g. `poll` in `cfafi`) should be promoted
+to `steward` when:
+
+1. At least one other sibling has copy-pasted it, OR
+2. Its scripts have no repo-specific assumptions (no hard-coded API
+   credentials, no per-product paths), AND
+3. Its `SKILL.md` describes a pattern (not a single product's workflow).
+
+Promotion is a manual decision — `steward doctor` will not move skills
+between repos.

{steward_cli-0.1.2 → steward_cli-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "steward-cli"
-version = "0.1.2"
+version = "0.3.0"
 description = "Steward — aligns and maintains resident agents across Culture projects."
 readme = "README.md"
 license = "MIT"
@@ -13,7 +13,9 @@ classifiers = [
     "Topic :: Software Development",
     "Intended Audience :: Developers",
 ]
-dependencies = []
+dependencies = [
+    "pyyaml>=6.0",
+]
 
 [project.urls]
 Homepage = "https://github.com/agentculture/steward"

{steward_cli-0.1.2 → steward_cli-0.3.0}/steward/cli/__init__.py

@@ -32,6 +32,7 @@ class _StewardArgumentParser(argparse.ArgumentParser):
 def _build_parser() -> argparse.ArgumentParser:
     # Deferred import to avoid coupling the parser module to the command modules
     # at import time (matches afi-cli's pattern; cheap insurance).
+    from steward.cli._commands import doctor as _doctor_cmd
     from steward.cli._commands import show as _show_cmd
 
     parser = _StewardArgumentParser(
@@ -46,6 +47,7 @@ def _build_parser() -> argparse.ArgumentParser:
     sub = parser.add_subparsers(dest="command", parser_class=_StewardArgumentParser)
 
     _show_cmd.register(sub)
+    _doctor_cmd.register(sub)
 
     return parser