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

{steward_cli-0.3.0 → steward_cli-0.3.2}/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.2] - 2026-04-26
+
+### Changed
+
+- `README.md` — document `steward doctor`. The previous Usage section listed only `steward show`, leaving the second verb (added in 0.2.0 as `verify`, renamed in 0.3.0, refined in 0.3.1) invisible to anyone who only reads the README. Adds both scopes (`--scope self` default, `--scope siblings`), the `--json` / `--check` flags, the `--apply` roadmap caveat, and cross-links to `docs/sibling-pattern.md` (the contract `doctor` honors) and `docs/perfect-patient.md` (the auto-generated corpus baseline).
+
+## [0.3.1] - 2026-04-26
+
+### Changed
+
+- `docs/perfect-patient.md` — first real corpus snapshot, generated by running `steward doctor --scope siblings` against the `agentculture` workspace (8 agents across 6 sibling repos: agex, culture, culture-sonar-cli, daria, reachy_nova, shushu). Replaces the placeholder shipped in 0.3.0. Required `culture.yaml` fields settle at `backend` + `suffix`; `acp_command` and `model` fall in the recommended band; common skills baseline is empty so far while `pr-review` and `run-tests` show up as recommended.
+- Skill bullets in the synthesized `perfect-patient.md` now carry a high-level one-liner per skill, sourced from each `SKILL.md`'s frontmatter `description:` (first-wins across the corpus, trimmed to the first sentence or 200 chars). Adds `Baseline.skill_descriptions: dict[str, str]` and a new `_skill_bullets` renderer; bare-bullet fallback when no description can be parsed. Reader can now scan the baseline and see what each skill ideally does without opening the upstream repo.
+
+### Fixed
+
+- `render_perfect_patient` no longer emits markdown that fails `markdownlint`. The empty-set placeholder switched from `_(none)_` (tripped MD036 emphasis-as-heading) to plain `None yet.`, and `_refresh_perfect_patient` no longer appends an extra trailing newline on top of the one the renderer already produces (which previously left a blank EOF line and tripped MD012).
+
 ## [0.3.0] - 2026-04-26
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steward-cli
-Version: 0.3.0
+Version: 0.3.2
 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
@@ -50,6 +50,30 @@ steward show ../daria
 `.claude/skills/agent-config/scripts/show.sh`. The skill remains the canonical
 implementation; the CLI is the typed entry point.
 
+```bash
+# Diagnose a single sibling repo against the AgentCulture sibling pattern
+# (portability + skills-convention checks). Exits non-zero on findings.
+steward doctor ../culture
+steward doctor ../culture --json --check portability
+
+# Walk every culture.yaml in the workspace, score each declared agent
+# against the corpus baseline, and write per-repo feedback into
+# <target>/docs/steward/steward-suggestions.md. Diagnostic-only.
+steward doctor --scope siblings
+```
+
+`steward doctor` is read-only diagnosis. `--scope self` (default) runs the
+single-repo invariant checks against `TARGET`. `--scope siblings` walks every
+`culture.yaml` in the workspace, refreshes
+[`docs/perfect-patient.md`](docs/perfect-patient.md) from the corpus, and
+writes per-target feedback into each sibling's
+`docs/steward/steward-suggestions.md`. The repair mode (`--apply`) is on the
+roadmap but not implemented yet.
+
+See [`docs/sibling-pattern.md`](docs/sibling-pattern.md) for the contract
+`doctor` honors and [`docs/perfect-patient.md`](docs/perfect-patient.md) for
+the auto-generated corpus baseline.
+
 See [`CLAUDE.md`](CLAUDE.md) for project-shape, build/test/publish details, and
 the skills convention.
 

steward_cli-0.3.2/README.md

@@ -0,0 +1,64 @@
+# steward
+
+Steward aligns and maintains resident agents across Culture projects.
+
+## Install
+
+```bash
+pip install steward-cli
+```
+
+Or, with [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv tool install steward-cli
+```
+
+## Usage
+
+```bash
+steward --version
+steward --help
+
+# Show a Culture agent's full configuration in one view
+# (CLAUDE.md + the parallel culture.yaml + .claude/skills/ index).
+# Run from inside a Steward checkout — the command finds the agent-config
+# skill script via a walk-up from the current working directory.
+steward show ../culture
+steward show ../daria
+```
+
+`steward show` is a thin wrapper over the `agent-config` skill at
+`.claude/skills/agent-config/scripts/show.sh`. The skill remains the canonical
+implementation; the CLI is the typed entry point.
+
+```bash
+# Diagnose a single sibling repo against the AgentCulture sibling pattern
+# (portability + skills-convention checks). Exits non-zero on findings.
+steward doctor ../culture
+steward doctor ../culture --json --check portability
+
+# Walk every culture.yaml in the workspace, score each declared agent
+# against the corpus baseline, and write per-repo feedback into
+# <target>/docs/steward/steward-suggestions.md. Diagnostic-only.
+steward doctor --scope siblings
+```
+
+`steward doctor` is read-only diagnosis. `--scope self` (default) runs the
+single-repo invariant checks against `TARGET`. `--scope siblings` walks every
+`culture.yaml` in the workspace, refreshes
+[`docs/perfect-patient.md`](docs/perfect-patient.md) from the corpus, and
+writes per-target feedback into each sibling's
+`docs/steward/steward-suggestions.md`. The repair mode (`--apply`) is on the
+roadmap but not implemented yet.
+
+See [`docs/sibling-pattern.md`](docs/sibling-pattern.md) for the contract
+`doctor` honors and [`docs/perfect-patient.md`](docs/perfect-patient.md) for
+the auto-generated corpus baseline.
+
+See [`CLAUDE.md`](CLAUDE.md) for project-shape, build/test/publish details, and
+the skills convention.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

steward_cli-0.3.2/docs/perfect-patient.md

@@ -0,0 +1,48 @@
+# Perfect patient
+
+> Auto-generated by `steward doctor` on 2026-04-26.
+> Synthesized from 8 agents across 6 repos.
+>
+> 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
+
+Present in ≥80% of agents.
+
+- `backend`
+- `suffix`
+
+## Recommended `culture.yaml` fields
+
+Present in 30–80% of agents.
+
+- `acp_command`
+- `model`
+
+## Common skills baseline
+
+Skills present in ≥80% of agent repos.
+
+None yet.
+
+## Recommended skills
+
+Skills present in 30–80% of agent repos.
+
+- `pr-review` — Full PR workflow for culture: branch, commit, push, create PR, wait for automated reviewers, fetch comments, fix or pushback, reply, resolve threads.
+- `run-tests` — Run pytest with parallel execution and coverage.
+
+## Common `CLAUDE.md` sections
+
+Top-level `## …` headings present in ≥80% of agent repos.
+
+None yet.
+
+## Corpus stats
+
+- Agents counted: 8
+- Repos counted: 6
+- Generated on: 2026-04-26

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

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

{steward_cli-0.3.0 → steward_cli-0.3.2}/steward/cli/_commands/_corpus.py

@@ -42,7 +42,7 @@ RECOMMENDED_THRESHOLD = 0.30
 
 # Placeholder used in baseline sections when no items are present. Kept
 # as a constant so the surface is single-sourced and matches in tests.
-NONE_PLACEHOLDER = "_(none)_"
+NONE_PLACEHOLDER = "None yet."
 
 
 @dataclass
@@ -119,6 +119,7 @@ class Baseline:
     recommended_skills: set[str] = field(default_factory=set)
     required_claude_md_sections: set[str] = field(default_factory=set)
     recommended_claude_md_sections: set[str] = field(default_factory=set)
+    skill_descriptions: dict[str, str] = field(default_factory=dict)
     agent_count: int = 0
     repo_count: int = 0
 
@@ -244,6 +245,68 @@ def _agent_skills(agent: Agent) -> set[str]:
     return {p.name for p in skills_dir.iterdir() if p.is_dir()}
 
 
+def _read_skill_description(skill_md: Path) -> str:
+    """Pull a one-line summary out of a SKILL.md frontmatter `description:`.
+
+    Frontmatter is the leading ``---``-delimited YAML block. Many skills
+    use a folded scalar (``description: >\\n  ...``) so we hand the block
+    to ``yaml.safe_load`` rather than line-grepping. The returned string
+    is whitespace-collapsed and trimmed to the first sentence (or 200
+    chars, whichever is shorter) so the rendered baseline stays compact.
+    Returns ``""`` when the file is missing, has no frontmatter, or
+    can't be parsed — the caller renders a bare bullet in that case.
+    """
+    try:
+        text = skill_md.read_text()
+    except OSError:
+        return ""
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return ""
+    end = next((i for i in range(1, len(lines)) if lines[i].strip() == "---"), -1)
+    if end == -1:
+        return ""
+    try:
+        meta = yaml.safe_load("\n".join(lines[1:end])) or {}
+    except yaml.YAMLError:
+        return ""
+    desc = meta.get("description") if isinstance(meta, dict) else None
+    if not isinstance(desc, str):
+        return ""
+    desc = " ".join(desc.split())
+    if not desc:
+        return ""
+    cut = desc.find(". ")
+    if 0 < cut < 200:
+        desc = desc[: cut + 1]
+    elif len(desc) > 200:
+        desc = desc[:197].rstrip() + "…"
+    return desc
+
+
+def _corpus_skill_descriptions(agents: list[Agent]) -> dict[str, str]:
+    """Best one-liner per skill name, sourced from SKILL.md frontmatter.
+
+    Walks each repo (deterministic by name), takes the first non-empty
+    description we encounter for each skill. "First-wins" rather than
+    "longest-wins" so the output is stable across re-runs even when a
+    downstream copy of a skill has tweaked its description.
+    """
+    out: dict[str, str] = {}
+    repos = sorted({a.repo_path for a in agents}, key=lambda p: p.name)
+    for repo in repos:
+        skills_dir = repo / ".claude" / "skills"
+        if not skills_dir.is_dir():
+            continue
+        for skill_dir in sorted(skills_dir.iterdir(), key=lambda p: p.name):
+            if not skill_dir.is_dir() or skill_dir.name in out:
+                continue
+            desc = _read_skill_description(skill_dir / "SKILL.md")
+            if desc:
+                out[skill_dir.name] = desc
+    return out
+
+
 def _agent_claude_md_sections(agent: Agent) -> set[str]:
     """Extract level-2 (`## ...`) heading titles from the agent's CLAUDE.md.
 
@@ -301,6 +364,7 @@ def synthesize_baseline(agents: list[Agent]) -> Baseline:
         recommended_skills=rec_skills,
         required_claude_md_sections=req_sec,
         recommended_claude_md_sections=rec_sec,
+        skill_descriptions=_corpus_skill_descriptions(agents),
         agent_count=len(agents),
         repo_count=len(repos),
     )
@@ -342,7 +406,7 @@ def render_perfect_patient(baseline: Baseline) -> str:
         "Skills present in ≥80% of agent repos.",
         "",
     ]
-    lines.extend(_bullets(baseline.required_skills))
+    lines.extend(_skill_bullets(baseline.required_skills, baseline.skill_descriptions))
     lines += [
         "",
         "## Recommended skills",
@@ -350,7 +414,7 @@ def render_perfect_patient(baseline: Baseline) -> str:
         "Skills present in 30–80% of agent repos.",
         "",
     ]
-    lines.extend(_bullets(baseline.recommended_skills))
+    lines.extend(_skill_bullets(baseline.recommended_skills, baseline.skill_descriptions))
     lines += [
         "",
         "## Common `CLAUDE.md` sections",
@@ -377,6 +441,17 @@ def _bullets(items: set[str]) -> list[str]:
     return [f"- `{item}`" for item in sorted(items)]
 
 
+def _skill_bullets(items: set[str], descriptions: dict[str, str]) -> list[str]:
+    """Render skill bullets with frontmatter-sourced one-liners when available."""
+    if not items:
+        return [NONE_PLACEHOLDER]
+    out: list[str] = []
+    for name in sorted(items):
+        desc = descriptions.get(name, "")
+        out.append(f"- `{name}` — {desc}" if desc else f"- `{name}`")
+    return out
+
+
 def synthesize_perfect_patient(agents: list[Agent]) -> str:
     """Convenience: discover → render in one call (used by doctor)."""
     return render_perfect_patient(synthesize_baseline(agents))

{steward_cli-0.3.0 → steward_cli-0.3.2}/steward/cli/_commands/doctor.py

@@ -330,7 +330,7 @@ def _resolve_perfect_patient_path(args: argparse.Namespace, steward_root: Path)
 
 def _refresh_perfect_patient(baseline: _corpus.Baseline, pp_path: Path) -> None:
     pp_path.parent.mkdir(parents=True, exist_ok=True)
-    pp_path.write_text(_corpus.render_perfect_patient(baseline) + "\n")
+    pp_path.write_text(_corpus.render_perfect_patient(baseline))
 
 
 def _run_repo_checks(repo_path: Path, selected_repo_checks: list[str]) -> list[Finding]:

{steward_cli-0.3.0 → steward_cli-0.3.2}/tests/test_corpus.py

@@ -203,6 +203,43 @@ def test_render_perfect_patient_has_expected_sections(tmp_path: Path) -> None:
     assert "Corpus stats" in body
 
 
+def test_skill_bullets_carry_frontmatter_descriptions(tmp_path: Path) -> None:
+    """Skills in the rendered baseline get a one-liner pulled from
+    their SKILL.md frontmatter `description:`. First-encountered repo
+    wins so the output is stable across runs."""
+    repo = tmp_path / "alpha"
+    repo.mkdir()
+    (repo / "culture.yaml").write_text(
+        yaml.safe_dump({"agents": [{"suffix": "a", "backend": "claude"}]})
+    )
+    (repo / ".claude" / "skills" / "run-tests" / "scripts").mkdir(parents=True)
+    (repo / ".claude" / "skills" / "run-tests" / "SKILL.md").write_text(
+        "---\nname: run-tests\n"
+        "description: Run pytest with parallel execution and coverage. "
+        "Use when running tests.\n---\n"
+    )
+    (repo / ".claude" / "skills" / "no-meta" / "scripts").mkdir(parents=True)
+    (repo / ".claude" / "skills" / "no-meta" / "SKILL.md").write_text("# no frontmatter\n")
+
+    agents, _errors = _corpus.discover_agents(tmp_path)
+    baseline = _corpus.synthesize_baseline(agents)
+    # 1-of-1 repo carries each skill, so both are required.
+    assert {"run-tests", "no-meta"} <= baseline.required_skills
+    # Description is collected for the skill that has frontmatter and trimmed
+    # to the first sentence (the trailing "Use when..." is dropped).
+    assert baseline.skill_descriptions["run-tests"].startswith(
+        "Run pytest with parallel execution and coverage."
+    )
+    assert "Use when" not in baseline.skill_descriptions["run-tests"]
+    # Skills without a parseable description are absent from the dict, not
+    # mapped to an empty string — render falls back to a bare bullet.
+    assert "no-meta" not in baseline.skill_descriptions
+
+    body = _corpus.render_perfect_patient(baseline)
+    assert "- `run-tests` — Run pytest with parallel execution and coverage." in body
+    assert "- `no-meta`\n" in body
+
+
 def test_write_repo_report_writes_marked_file(tmp_path: Path) -> None:
     repo = tmp_path / "alpha"
     repo.mkdir()

{steward_cli-0.3.0 → steward_cli-0.3.2}/uv.lock

@@ -439,7 +439,7 @@ wheels = [
 
 [[package]]
 name = "steward-cli"
-version = "0.3.0"
+version = "0.3.2"
 source = { editable = "." }
 dependencies = [
     { name = "pyyaml" },

steward_cli-0.3.0/README.md

@@ -1,40 +0,0 @@
-# steward
-
-Steward aligns and maintains resident agents across Culture projects.
-
-## Install
-
-```bash
-pip install steward-cli
-```
-
-Or, with [uv](https://github.com/astral-sh/uv):
-
-```bash
-uv tool install steward-cli
-```
-
-## Usage
-
-```bash
-steward --version
-steward --help
-
-# Show a Culture agent's full configuration in one view
-# (CLAUDE.md + the parallel culture.yaml + .claude/skills/ index).
-# Run from inside a Steward checkout — the command finds the agent-config
-# skill script via a walk-up from the current working directory.
-steward show ../culture
-steward show ../daria
-```
-
-`steward show` is a thin wrapper over the `agent-config` skill at
-`.claude/skills/agent-config/scripts/show.sh`. The skill remains the canonical
-implementation; the CLI is the typed entry point.
-
-See [`CLAUDE.md`](CLAUDE.md) for project-shape, build/test/publish details, and
-the skills convention.
-
-## License
-
-MIT — see [`LICENSE`](LICENSE).

steward_cli-0.3.0/docs/perfect-patient.md

@@ -1,35 +0,0 @@
-# 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.