steward-cli 0.25.2__tar.gz → 0.26.0__tar.gz

steward_cli-0.26.0/.claude/skills/agent-roster/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: agent-roster
+description: >
+  Inventory every Culture agent declared across the workspace's culture.yaml
+  files and reconcile it against the local Culture server's enrollment — one
+  flat table answering "which agents exist, which are actually registered with
+  the server, and what channels do they join?" Shows backend, model, channels,
+  and an enrolled (yes/no) column per agent, then flags enrolled-but-undeclared
+  suffixes (stale or out-of-workspace registrations). Use when the user asks to
+  list/roster/map the agents, "what agents do we have", "which agents are
+  enrolled / on the server", "what channels is each agent in", or "is anything
+  registered that we don't declare". Read-only; no graph, no LLM, no repo
+  writes — that is `org-overview`'s job. Steward-specific.
+---
+
+# Agent Roster — list every culture.yaml agent and its enrollment
+
+A roster is the plainest sense-making question in steward's lane: *who is on
+the mesh, and who is actually wired up?* It sits below the two existing verbs:
+
+- `steward doctor` asks *"is this agent healthy and aligned?"* (compliance).
+- `steward overview` / `org-overview` asks *"how do agents relate?"* (graph).
+- **`agent-roster` (this skill) asks *"what exists and what's enrolled?"*** — a
+  flat inventory, no graph, no interpretation.
+
+It joins two deterministic sources by agent `suffix`:
+
+1. **Declarations** — every `<workspace>/*/culture.yaml` agent (the same corpus
+   walk `doctor`/`overview` use).
+2. **Enrollment** — the `agents:` table in the local Culture server manifest
+   (`server.yaml`), which says which suffixes are *registered* with the running
+   server. Enrollment is **dir-aware**: when the server records a repo dir, a
+   suffix is only counted enrolled for the repo that dir resolves to, so a
+   suffix collision across two repos (e.g. two `daria` declarations) is
+   attributed to the one the server actually registered.
+
+## When to use
+
+- "List / roster / map the agents." / "What agents do we have?"
+- "Which agents are enrolled?" / "What's running on the server?"
+- "What channels is each agent in?"
+- "Is anything registered that no culture.yaml declares?" (stale enrollment)
+
+For "how do they relate / overlap / who's overloaded", use `org-overview`
+instead — that is the graph + interpretation layer.
+
+## How to run
+
+One script wrapping `steward roster`:
+
+```bash
+# Every declared agent + enrollment, as a table (default)
+.claude/skills/agent-roster/scripts/roster.sh
+
+# Only agents registered with the server
+.claude/skills/agent-roster/scripts/roster.sh --enrolled-only
+
+# Machine-readable for precise reasoning ({agents, unmatched_enrollments, totals})
+.claude/skills/agent-roster/scripts/roster.sh --json
+
+# Non-default checkout layout / explicit server manifest (passthrough)
+.claude/skills/agent-roster/scripts/roster.sh --workspace-root /path/to/workspace
+.claude/skills/agent-roster/scripts/roster.sh --server-yaml /path/to/server.yaml
+```
+
+The table has one row per declared agent: `AGENT REPO BACKEND MODEL CHANNELS
+ENROLLED`. Below it, an "Enrolled but no culture.yaml declares them" list names
+any suffix the server registered that the workspace doesn't declare — a stale
+registration, or a repo outside the scanned workspace. A diagnostic line (on
+stderr) gives the declared / enrolled / unmatched totals, and notes when no
+server manifest was readable (every agent then shows `no`).
+
+## Server manifest resolution
+
+The enrollment source is resolved in order: `--server-yaml` →
+`culture_server_yaml` in `.claude/skills.local.yaml` → its committed
+`.example` → `~/.culture/server.yaml`. A missing manifest is **not** an error —
+the roster still lists every declared agent, just with enrollment blank.
+
+## Reflect-only
+
+This skill reports facts and stops. Reconciling a stale enrollment (server
+knows an agent the workspace doesn't declare, or vice versa) is a separate,
+explicit step — start a server agent, add the missing `culture.yaml`, or
+deregister — none of which this skill does. Output is the chat conversation; it
+writes nothing to disk and mutates no repo.

steward_cli-0.26.0/.claude/skills/agent-roster/scripts/roster.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# agent-roster — inventory every culture.yaml agent + its server enrollment.
+#
+# Steward-the-agent (or the user) runs this to answer "what agents exist and
+# which are enrolled?". Deterministic glue only: it resolves how to invoke
+# steward and delegates to `steward roster`. No interpretation, no repo writes.
+#
+# Usage:
+#   roster.sh                          # every declared agent + enrollment (table)
+#   roster.sh --enrolled-only          # only server-registered agents
+#   roster.sh --json                   # machine-readable evidence
+#   roster.sh --workspace-root DIR     # non-default layout (passthrough)
+#   roster.sh --server-yaml FILE       # explicit server manifest (passthrough)
+#
+# All arguments pass through to `steward roster`.
+#
+# Exit codes:
+#   0   success (delegates to `steward roster`)
+#   1   environment error (no way to invoke steward)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+REPO_ROOT="$(cd "$SKILL_DIR/../../.." && pwd)"
+
+# Resolve how to invoke steward: installed console script, then uv, then module.
+if command -v steward >/dev/null 2>&1; then
+    STEWARD=(steward)
+elif [ -f "$REPO_ROOT/pyproject.toml" ] && command -v uv >/dev/null 2>&1; then
+    STEWARD=(uv run --project "$REPO_ROOT" steward)
+elif command -v python3 >/dev/null 2>&1; then
+    STEWARD=(python3 -m steward)
+else
+    echo "agent-roster: cannot invoke steward (need 'steward', 'uv', or 'python3' on PATH)" >&2
+    exit 1
+fi
+
+exec "${STEWARD[@]}" roster "$@"

{steward_cli-0.25.2 → steward_cli-0.26.0}/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.26.0] - 2026-06-13
+
+### Added
+
+- **`steward roster`** — flat inventory of every `culture.yaml` agent in the
+  workspace, joined by `suffix` against the local Culture server manifest's
+  `agents:` enrollment table. One row per declared agent (backend, model,
+  channels, enrolled yes/no), plus an "enrolled but no `culture.yaml` declares
+  them" list for stale or out-of-workspace registrations. Enrollment is
+  dir-aware, so a suffix collision across two repos (e.g. two `daria`
+  declarations) is attributed to the repo the server actually registered.
+  Table by default; `--json` for `{agents, unmatched_enrollments, totals}`;
+  `--enrolled-only` restricts to registered agents. Server manifest resolved
+  from `--server-yaml` → `culture_server_yaml` in `skills.local.yaml(.example)`
+  → `~/.culture/server.yaml`; a missing manifest is not an error. Read-only —
+  no graph, no LLM, no repo writes. New helper module `_roster.py`
+  (`load_enrollment` / `build_report`) with unit + CLI tests.
+- **`agent-roster` skill** (`.claude/skills/agent-roster/`) — chat wrapper over
+  `steward roster` for "list/roster/map the agents", "which are enrolled", and
+  "what channels is each agent in". Reflect-only.
+
+### Changed
+
+### Fixed
+
 ## [0.25.2] - 2026-06-13
 
 ### Added

{steward_cli-0.25.2 → steward_cli-0.26.0}/CLAUDE.md

@@ -150,14 +150,18 @@ rule applied to skills.
 
 ## Roadmap (CLI surface)
 
-The CLI ships three verbs today: `steward show`, `steward doctor`, and
-`steward overview`. 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.
-
-`doctor` and `overview` are complementary: `doctor` asks *"is this sibling
-healthy and aligned?"* (health / compliance); `overview` asks *"what exists,
-how does it fit together, and what seems missing?"* (sense-making).
+The CLI ships these verbs today: `steward show`, `steward doctor`,
+`steward overview`, `steward roster`, and `steward liveness`. 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.
+
+`doctor`, `overview`, and `roster` are complementary cuts at the corpus:
+`doctor` asks *"is this sibling healthy and aligned?"* (health / compliance);
+`overview` asks *"what exists, how does it fit together, and what seems
+missing?"* (sense-making via a typed graph); `roster` asks the plainest
+question — *"what agents exist, which are enrolled with the server, and what
+channels do they join?"* (a flat inventory, no graph).
 
 - `steward doctor <path>` (default `--scope self`) — score a target repo
   against `docs/sibling-pattern.md`. Aggregates findings across all
@@ -203,6 +207,22 @@ how does it fit together, and what seems missing?"* (sense-making).
   repo mutation. That narration is driven by this repo's `org-overview` skill
   (`.claude/skills/org-overview/`), which runs `steward overview` and speaks
   the three layers in chat, reflect-only.
+- `steward roster` — flat inventory of every `culture.yaml` agent in the
+  workspace (`<workspace-root>/*/culture.yaml`), joined by `suffix` against
+  the local Culture server manifest's `agents:` enrollment table (resolved
+  from `--server-yaml` → `culture_server_yaml` in `skills.local.yaml(.example)`
+  → `~/.culture/server.yaml`). One row per declared agent — backend, model,
+  channels, and an enrolled (yes/no) column — plus an "enrolled but no
+  `culture.yaml` declares them" list for stale or out-of-workspace
+  registrations. Enrollment is **dir-aware**: when the manifest records a
+  repo dir, a suffix only counts as enrolled for the repo that dir resolves
+  to, so a suffix collision across two repos (e.g. two `daria` declarations)
+  is attributed to the one the server registered. Table by default,
+  `--json` for `{agents, unmatched_enrollments, totals}`, `--enrolled-only`
+  to restrict to registered agents. A missing manifest is not an error
+  (every agent then shows `no`). Read-only; no graph, no LLM, no repo writes.
+  Driven in chat by this repo's `agent-roster` skill
+  (`.claude/skills/agent-roster/`).
 - `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`,

{steward_cli-0.25.2 → steward_cli-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steward-cli
-Version: 0.25.2
+Version: 0.26.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

{steward_cli-0.25.2 → steward_cli-0.26.0}/packaging/culture-lens/pyproject.toml

@@ -4,7 +4,7 @@ name = "culture-lens"
 # source of truth). The placeholder below is overwritten in CI before build;
 # it stays a valid PEP 440 string so a local `uv build packaging/culture-lens`
 # still works for smoke-testing the build mechanics.
-version = "0.25.2"
+version = "0.26.0"
 description = "culture-lens — parallel console name for steward-cli (thin wrapper; installs steward-cli and exposes the `culture-lens` command)."
 readme = "README.md"
 license = "Apache-2.0"
@@ -20,7 +20,7 @@ classifiers = [
 # The `==<version>` pin is injected at build time to match this wrapper's own
 # version, keeping culture-lens and steward-cli in lockstep.
 dependencies = [
-    "steward-cli==0.25.2",
+    "steward-cli==0.26.0",
 ]
 
 [project.urls]

{steward_cli-0.25.2 → steward_cli-0.26.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "steward-cli"
-version = "0.25.2"
+version = "0.26.0"
 description = "Steward — aligns and maintains resident agents across Culture projects."
 readme = "README.md"
 license = "Apache-2.0"

{steward_cli-0.25.2 → steward_cli-0.26.0}/steward/cli/__init__.py

@@ -36,6 +36,7 @@ def _build_parser() -> argparse.ArgumentParser:
     from steward.cli._commands import doctor as _doctor_cmd
     from steward.cli._commands import liveness as _liveness_cmd
     from steward.cli._commands import overview as _overview_cmd
+    from steward.cli._commands import roster as _roster_cmd
     from steward.cli._commands import show as _show_cmd
 
     parser = _StewardArgumentParser(
@@ -54,6 +55,7 @@ def _build_parser() -> argparse.ArgumentParser:
     _asu_cmd.register(sub)
     _overview_cmd.register(sub)
     _liveness_cmd.register(sub)
+    _roster_cmd.register(sub)
 
     return parser
 

steward_cli-0.26.0/steward/cli/_commands/_roster.py

@@ -0,0 +1,238 @@
+"""Roster helpers for ``steward roster``.
+
+Pure helpers, no CLI surface. The ``roster`` command imports from here to:
+
+1. Read the local Culture server's enrollment map (:func:`load_enrollment`)
+   — the ``agents:`` table in ``server.yaml`` (``suffix → repo dir``) that
+   says which declared agents are actually *registered* with the running
+   server.
+2. Cross-reference declared agents (from :func:`steward.cli._commands._corpus.discover_agents`)
+   against that enrollment to build a flat inventory (:func:`build_report`):
+   one row per declared agent — backend, model, channels, enrollment — plus
+   the enrolled-but-undeclared suffixes that have no matching ``culture.yaml``.
+
+Why a separate module: ``_corpus.py`` already owns the doctor/baseline
+scoring surface. The roster is a different question ("what exists and what's
+wired up?", not "is it healthy?"), so its data shaping lives on its own and
+stays testable without argparse.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+from steward.cli._commands._corpus import Agent
+
+
+@dataclass
+class RosterRow:
+    """One declared agent, cross-referenced with server enrollment."""
+
+    suffix: str
+    repo: str
+    backend: str
+    model: str | None
+    channels: list[str]
+    tags: list[str]
+    inline_prompt: bool  # culture.yaml carries an inline ``system_prompt:``
+    enrolled: bool  # suffix present in the server's ``agents:`` map
+    enrolled_dir: str | None  # the dir the server registered for this suffix
+
+    def to_dict(self) -> dict:
+        return {
+            "suffix": self.suffix,
+            "repo": self.repo,
+            "backend": self.backend,
+            "model": self.model,
+            "channels": self.channels,
+            "tags": self.tags,
+            "inline_prompt": self.inline_prompt,
+            "enrolled": self.enrolled,
+            "enrolled_dir": self.enrolled_dir,
+        }
+
+
+@dataclass
+class UnmatchedEnrollment:
+    """A suffix registered with the server that no ``culture.yaml`` declares."""
+
+    suffix: str
+    enrolled_dir: str
+
+    def to_dict(self) -> dict:
+        return {"suffix": self.suffix, "enrolled_dir": self.enrolled_dir}
+
+
+@dataclass
+class RosterReport:
+    """The full inventory: declared agents + enrollment reconciliation."""
+
+    rows: list[RosterRow] = field(default_factory=list)
+    unmatched_enrollments: list[UnmatchedEnrollment] = field(default_factory=list)
+    server_yaml: str | None = None  # resolved path, or None when no manifest found
+    server_present: bool = False  # the manifest existed and parsed
+
+    def to_dict(self) -> dict:
+        return {
+            "agents": [r.to_dict() for r in self.rows],
+            "unmatched_enrollments": [u.to_dict() for u in self.unmatched_enrollments],
+            "server_yaml": self.server_yaml,
+            "server_present": self.server_present,
+            "totals": {
+                "declared": len(self.rows),
+                "enrolled": sum(1 for r in self.rows if r.enrolled),
+                "unmatched_enrollments": len(self.unmatched_enrollments),
+            },
+        }
+
+
+def load_enrollment(server_yaml: Path) -> tuple[dict[str, str], bool]:
+    """Return ``(enrollment, present)`` from a Culture ``server.yaml``.
+
+    ``enrollment`` maps each registered agent ``suffix`` to the repo dir the
+    server recorded for it (the ``agents:`` table). ``present`` is True iff the
+    manifest existed and parsed as a mapping — when False, enrollment is ``{}``
+    and the caller renders every agent as "not enrolled" rather than crashing.
+
+    A missing or malformed manifest is not an error: a roster is still useful
+    without a running server (it just can't say what's enrolled).
+    """
+    try:
+        text = server_yaml.read_text(encoding="utf-8")
+    except OSError:
+        return {}, False
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError:
+        return {}, False
+    if not isinstance(data, dict):
+        return {}, False
+    agents = data.get("agents")
+    if not isinstance(agents, dict):
+        # Manifest parsed but has no agents table — treat as present-but-empty.
+        return {}, True
+    enrollment: dict[str, str] = {}
+    for suffix, repo_dir in agents.items():
+        enrollment[str(suffix)] = _entry_dir(repo_dir)
+    return enrollment, True
+
+
+def _entry_dir(repo_dir) -> str:
+    """Normalize a server.yaml ``agents:`` value to a repo-dir string.
+
+    Culture's manifest registers each suffix as either a bare path string or a
+    mapping with a ``directory`` key — the same two shapes the ``agent-config``
+    skill handles (``show.sh``: ``entry['directory'] if isinstance(entry, dict)
+    else entry``). Mirror that here so a mapping-form entry resolves to its
+    path instead of stringifying to a dict repr that could never match a repo.
+    A null value (or a mapping missing ``directory``) becomes ``""`` — present
+    but undisambiguatable, enrolled on suffix alone.
+    """
+    if repo_dir is None:
+        return ""
+    if isinstance(repo_dir, dict):
+        directory = repo_dir.get("directory")
+        return "" if directory is None else str(directory)
+    return str(repo_dir)
+
+
+def _channels(raw: dict) -> list[str]:
+    value = raw.get("channels")
+    if not isinstance(value, list):
+        return []
+    return [str(c) for c in value]
+
+
+def _tags(raw: dict) -> list[str]:
+    value = raw.get("tags")
+    if not isinstance(value, list):
+        return []
+    return [str(t) for t in value]
+
+
+def _same_dir(a: str, b: Path) -> bool:
+    """True if registered dir string *a* resolves to repo path *b*.
+
+    Best-effort: a registration whose dir can't be resolved (e.g. a relative
+    path against an unknown cwd) falls back to False so a mismatch never
+    silently claims enrollment.
+    """
+    if not a:
+        return False
+    try:
+        return Path(a).expanduser().resolve() == b.resolve()
+    except OSError:
+        return False
+
+
+def _is_enrolled(agent: Agent, enrollment: dict[str, str]) -> bool:
+    """Whether *agent* is registered with the server.
+
+    Suffix match is necessary; when the server also records a dir, it must
+    resolve to this agent's repo (so a suffix collision across two repos —
+    e.g. two ``daria`` declarations — is attributed to the one the server
+    actually registered). A blank registered dir can't disambiguate, so it
+    is accepted on the suffix alone.
+    """
+    if agent.suffix not in enrollment:
+        return False
+    registered_dir = enrollment[agent.suffix]
+    if not registered_dir:
+        return True
+    return _same_dir(registered_dir, agent.repo_path)
+
+
+def _row(agent: Agent, enrollment: dict[str, str]) -> RosterRow:
+    raw = agent.raw
+    model = raw.get("model")
+    enrolled = _is_enrolled(agent, enrollment)
+    return RosterRow(
+        suffix=agent.suffix,
+        repo=agent.repo_name,
+        backend=agent.backend or "",
+        model=str(model) if model else None,
+        channels=_channels(raw),
+        tags=_tags(raw),
+        inline_prompt=bool(raw.get("system_prompt")),
+        enrolled=enrolled,
+        enrolled_dir=enrollment.get(agent.suffix) if enrolled else None,
+    )
+
+
+def build_report(
+    agents: list[Agent],
+    enrollment: dict[str, str],
+    *,
+    server_yaml: str | None = None,
+    server_present: bool = False,
+) -> RosterReport:
+    """Turn discovered agents + an enrollment map into a :class:`RosterReport`.
+
+    Rows are sorted by ``(repo, suffix)`` for stable output. Any enrolled
+    suffix that no discovered agent claims becomes an
+    :class:`UnmatchedEnrollment` — the server knows about an agent the corpus
+    doesn't declare (a stale registration, or a repo outside the scanned
+    workspace).
+    """
+    rows = sorted(
+        (_row(a, enrollment) for a in agents),
+        key=lambda r: (r.repo, r.suffix),
+    )
+    # A registration is "matched" when some declared agent claimed it (enrolled
+    # row). Anything left over — suffix never declared, or declared only in a
+    # different dir than the server registered — is an unmatched enrollment.
+    matched_suffixes = {r.suffix for r in rows if r.enrolled}
+    unmatched = [
+        UnmatchedEnrollment(suffix=s, enrolled_dir=d)
+        for s, d in sorted(enrollment.items())
+        if s not in matched_suffixes
+    ]
+    return RosterReport(
+        rows=rows,
+        unmatched_enrollments=unmatched,
+        server_yaml=server_yaml,
+        server_present=server_present,
+    )