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:

Rendered, the graph reads like an org chart. Here is a slice around culture showing every default node and edge type (GitHub renders the Mermaid below; steward overview emits the whole-ecosystem version):

graph LR
  classDef repo fill:#cde,stroke:#369,color:#000;
  classDef agent fill:#dfd,stroke:#393,color:#000;
  classDef channel fill:#fde,stroke:#a39,color:#000;
  classDef package fill:#eee,stroke:#999,color:#000;

  culture["culture"]:::repo
  culture_agent["culture/culture"]:::agent
  general["#general"]:::channel
  agtag["agtag"]:::repo
  pyyaml["PyYAML"]:::package
  daria["daria"]:::repo
  katvan["katvan"]:::repo

  culture -->|declares| culture_agent
  culture_agent -->|present_on| general
  culture -->|depends_on| agtag
  culture -->|depends_on| pyyaml
  daria -->|references| culture
  katvan -->|documents| culture

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

# Interactive HTML page — open in a browser for edge-type toggles,
# pan/zoom, and node click-to-focus (filter to a node's neighbours):
steward overview --scope siblings --html > overview.html

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

--json and --html are mutually exclusive. The HTML page renders the same graph client-side (Mermaid + pan/zoom from a CDN, so it needs network to draw; the inventory/connectivity/signal tables work offline).

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.

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

Apache 2.0 — see LICENSE.