steward-cli 0.21.0

Steward — aligns and maintains resident agents across Culture projects.

steward

Steward aligns and maintains resident agents across Culture projects. It owns the AgentCulture sibling-repo pattern, the corpus-derived "perfect patient" baseline, and the canonical copies of the skills that other siblings vendor.

What steward is responsible for

• Owning the sibling pattern every AgentCulture sibling repo follows — see docs/sibling-pattern.md.
• Maintaining the perfect-patient baseline synthesized from the live corpus on every steward doctor --scope siblings run — see docs/perfect-patient.md.
• Hosting the canonical copies of skills that siblings vendor (cite, don't import) — see docs/skill-sources.md.
• Running diagnostics today, not repairs. The repair mode (--apply) is described in docs/sibling-pattern.md but is not implemented yet.

Concepts

• Sibling repo — a Culture-mesh-adjacent project (e.g. culture, daria, cfafi, ghafi) that wears the shape defined in docs/sibling-pattern.md. Steward is itself a sibling and the reference exemplar.
• Perfect patient — the corpus-derived baseline of what a healthy sibling looks like, regenerated from every culture.yaml in the workspace each time steward doctor --scope siblings runs. The frequency-derived sections (culture.yaml fields, CLAUDE.md headings) are regenerated wholesale; the skills tier list is manually curated.
• Skill supplier — steward owns the canonical copy of most cross-sibling skills. Siblings copy those skills into their own .claude/skills/ and may diverge intentionally; steward tracks who owns what in docs/skill-sources.md.

When to use steward

• You're starting a new AgentCulture sibling repo and want to know the shape it should wear.
• You want to check whether an existing sibling still matches the pattern.
• You want to audit a sibling's vendored skill copies for drift against the canonical upstream (the --apply repair mode that performs the refresh itself is on the roadmap).
• You're auditing the corpus to decide what the "common skills baseline" should be.

How the pieces fit

flowchart LR
    subgraph Steward["steward (this repo)"]
        SCLI["steward CLI<br/>(show / doctor / overview)"]
        Skills[".claude/skills/<br/>canonical copies"]
        SP["docs/sibling-pattern.md<br/>(the contract)"]
        PP["docs/perfect-patient.md<br/>(corpus baseline)"]
        SS["docs/skill-sources.md<br/>(upstream/downstream map)"]
    end

    subgraph Sibling["each sibling repo"]
        SC["culture.yaml<br/>CLAUDE.md<br/>.claude/skills/"]
        Sugg["docs/steward/<br/>steward-suggestions.md"]
    end

    SCLI -- "reads" --> SC
    SCLI -- "scores against" --> SP
    SCLI -- "regenerates" --> PP
    SCLI -- "writes per-target" --> Sugg
    Skills -- "vendored into (cite, don't import)" --> SC
    SS -. "tracks" .-> Skills
    SS -. "tracks" .-> SC

Install

pip install steward-cli

Or, with uv:

uv tool install steward-cli

This provides the steward, agents-lens, and culture-lens commands (all the same CLI). culture-lens is also published as its own thin-wrapper package — pip install culture-lens pulls in steward-cli and exposes the culture-lens command:

pip install culture-lens   # installs steward-cli + the `culture-lens` command

Usage

steward show <target> — surface a sibling's agent config

Prints the target sibling's CLAUDE.md, the parallel culture.yaml, and an index of its .claude/skills/ in one view. Thin wrapper over the agent-config skill at .claude/skills/agent-config/scripts/show.sh.

$ steward show ../culture
=== ../culture/CLAUDE.md ===
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**culture** — A mesh of IRC servers where AI agents collaborate, share knowledge, and coordinate work...
...

steward doctor <target> — single-repo diagnosis

Runs the AgentCulture sibling-pattern invariants against a single repo (currently portability and skills-convention; see the status table below). Read-only. Exits non-zero on findings.

$ steward doctor .
doctor clean (2 checks against /<workspace>/steward)
$ echo $?
0

Findings against a repo with a /home/<user>/... path leak:

$ steward doctor /tmp/doctor-demo
portability: .: ❌ Hard-coded /home/<user>/ paths:
    notes.md:1:/home/<user>/secrets
   Fix: use ../sibling, repo URL, or $WORKSPACE/sibling instead.
$ echo $?
1

The same findings as JSON (for scripting):

steward doctor /tmp/doctor-demo --json

[
  {
    "check": "portability",
    "path": ".",
    "message": "Hard-coded /home/<user>/ paths: notes.md:1:/home/<user>/secrets — use ../sibling, repo URL, or $WORKSPACE/sibling instead."
  }
]

Run a single check with --check:

steward doctor . --check portability
steward doctor . --check skills-convention

steward doctor --scope siblings — corpus walk

Walks every culture.yaml in the workspace, scores each declared agent against a corpus-derived baseline, regenerates docs/perfect-patient.md from the corpus, and writes per-target feedback into each sibling's docs/steward/steward-suggestions.md. Diagnostic-only — exits 0 even when individual agents drift from the baseline; per-agent gaps are reported in the per-target file.

steward doctor --scope siblings
# wrote: ../culture/docs/steward/steward-suggestions.md
# wrote: ../daria/docs/steward/steward-suggestions.md
# refreshed: docs/perfect-patient.md (8 agents across 6 repos)

The synthesized docs/perfect-patient.md looks like:

# Perfect patient

> Auto-generated by `steward doctor` on 2026-04-26.
> Synthesized from 8 agents across 6 repos.

## Required `culture.yaml` fields
- `backend`
- `suffix`

## Recommended skills
- `cicd` — Branch, commit, push, create PR, wait for bots, triage, reply, ...
- `run-tests` — Run pytest with parallel execution and coverage.
- `version-bump` — Bump semver in `pyproject.toml` ...
...

steward overview — ecosystem sense-making

The sense-making companion to doctor. Where doctor asks "is this sibling healthy?", overview asks "what exists, how does it fit together, and what seems missing?". It deterministically assembles an evidence pack — an agent inventory plus a typed relationship graph — and leaves the interpretation to the agent (or human) reading it. No LLM, no repo mutation.

By default overview is the agent-relationship layer. The graph has typed nodes (repo, agent, channel, package) and observed edges, each citing its source:

Edge	Meaning	Source
declares	repo → agent	culture.yaml
present_on	agent → channel	culture.yaml
depends_on	repo → package (and repo → sibling repo)	pyproject.toml
references	repo → repo	CLAUDE.md / README.md
documents	repo → repo	doc-source registry

It also emits candidate signals — neutral, deterministic flags for the narrating agent to interpret (not conclusions): over-connected-agent, isolated-repo, overlap, doc-coverage-gap, backend-mismatch.

Skill-supply layer (--include-skills, transitional). The skill node type, the supplies / consumes / uses edges (from docs/skill-sources.md and SKILL.md/scripts), and the orphan-skill / ledger-gap / unowned-skill signals are off by default. Pass --include-skills to restore them. That inventory is moving to guildmaster's guild overview (guildmaster#12); the flag is a bridge until cutover (#63).

# Whole ecosystem, human-readable (markdown with a mermaid graph):
steward overview --scope siblings

# A single repo's ego graph (the repo + its directly-incident edges):
steward overview ../culture

# Machine-readable, neo4j-loadable graph for scripts:
steward overview --scope siblings --json

# Include the (transitional) skill-supply layer:
steward overview --scope siblings --include-skills

The --json output is a flat {scope, generated, nodes, edges, signals} structure (plus a warnings array when a culture.yaml can't be parsed):

{
  "scope": "siblings",
  "generated": "2026-05-21",
  "nodes": [{"id": "culture/culture", "type": "agent", "props": {"backend": "claude"}}],
  "edges": [{"source": "culture", "target": "afi-cli", "type": "depends_on", "basis": "pyproject.toml"}],
  "signals": [{"kind": "over-connected-agent", "subject": "culture/culture", "detail": "..."}]
}

Steward stops at observed facts + neutral signals; the agent that ran it narrates the inferred relationships (owns / depends-on / observes / aligns / governs / overlaps-with / …) and suggestions layers, keeping them clearly separate from the facts.

Status: diagnostics vs repairs

steward is read-only today. The --apply repair mode is described in docs/sibling-pattern.md but is not implemented.

Check / repair	Status	Verb
portability (no /home/..., no ~/.<dotfile> refs in committed docs)	Implemented	steward doctor --check portability
skills-convention (every SKILL.md has scripts/ + matching frontmatter name)	Implemented	steward doctor --check skills-convention
changelog-format	Planned	—
lint-config-local (repo-local .markdownlint-cli2.yaml)	Planned	—
Repair: vendor missing .markdownlint-cli2.yaml	Planned (--apply)	—
Repair: vendor missing .claude/skills.local.yaml.example	Planned (--apply)	—
Repair: create empty .claude/skills/<name>/scripts/	Planned (--apply)	—
Repair: skeleton CHANGELOG.md	Planned (--apply)	—

Relationship to other AgentCulture tools

• culture runs the agent mesh. Steward does not run agents — it aligns their configuration and lifecycle policies across the mesh.
• daria is an awareness agent that observes Culture state at runtime. Steward is the static-analysis counterpart: it runs against repos on disk, not live agents.
• afi-cli and ghafi are sibling CLIs that follow the same sibling pattern steward maintains. The eventual --apply repair mode will consume ../afi-cli/afi/cite/_engine.py rather than re-implement vendoring.

Further reading

• docs/sibling-pattern.md — the contract steward doctor honors (required artifacts, invariants, planned repairs).
• docs/perfect-patient.md — the auto-generated corpus baseline.
• docs/skill-sources.md — which repo owns the canonical copy of each skill.
• CLAUDE.md — project shape, build/test/publish details, and the skills convention.

License

MIT — see LICENSE.