steward-cli 0.14.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

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.

The graph has typed nodes (repo, agent, skill, channel, package) and observed edges, each citing its source:

Edge	Meaning	Source
declares	repo → agent	culture.yaml
supplies / consumes	repo → skill	docs/skill-sources.md
present_on	agent → channel	culture.yaml
depends_on	repo → package (and repo → sibling repo)	pyproject.toml
references	repo → repo	CLAUDE.md / README.md

It also emits candidate signals — neutral, deterministic flags for the narrating agent to interpret (not conclusions): orphan-skill, unowned-skill, ledger-gap, overlap, over-connected-agent, isolated-repo.

# 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

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": "cicd", "type": "skill", "props": {}}],
  "edges": [{"source": "steward", "target": "cicd", "type": "supplies", "basis": "skill-sources.md"}],
  "signals": [{"kind": "orphan-skill", "subject": "cicd", "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.