agentsquire 0.2.2__tar.gz → 0.3.0__tar.gz

{agentsquire-0.2.2 → agentsquire-0.3.0}/.gitignore

@@ -10,3 +10,7 @@ checkouts/
 # Local scratch / dev notes (never committed, never published)
 bugs.md
 feedback.md
+
+# specflo local state: the active-project pointer is per-clone session state,
+# not shared config. The durable record lives under docs/projects/.
+.specflo/

{agentsquire-0.2.2 → agentsquire-0.3.0}/CHANGELOG.md

@@ -8,6 +8,39 @@ The version is declared in two places that are kept in sync by the release
 tooling: `__version__` in `src/agentsquire/__init__.py` and `version` in
 `pyproject.toml`.
 
+## [0.3.0]
+
+### Added
+- **agentsquire now ships its own runnable CLI, `squire` (long alias
+  `agentsquire`).** It dogfoods the library's consumer contract end to end,
+  carrying one bundled skill, mounting the ready-made skills group, emitting the
+  proactive staleness notice, and serving its own reference docs.
+  - `squire skills install|status|update|uninstall` - the standard group,
+    mounted the production way at user scope by default, operating on
+    agentsquire's one bundled skill.
+  - `squire guide [TOPIC]` - with no argument lists the reference topics (api,
+    harnesses, integration); with a topic, pages that canonical doc as raw
+    markdown. An unknown topic is a clean, non-zero error naming the valid
+    topics.
+  - `squire --version` prints the installed agentsquire version; `squire --help`
+    and `agentsquire --help` are identical below the usage line.
+  - A proactive staleness notice on stderr points at `squire skills update` when
+    an installed copy is out of date; suppressed under CI or
+    `AGENTSQUIRE_NO_UPDATE_CHECK`, and it never changes stdout or the exit code.
+- **`developing-with-agentsquire` bundled skill.** agentsquire carries one Agent
+  Skill as package data and marks itself skill-carrying under the
+  `agentsquire.skills` entry-point group - the same contract it documents for
+  consumers.
+- **The three reference docs are force-included into the wheel.** `docs/api.md`,
+  `docs/harnesses.md`, and `README.md` are packaged under `agentsquire/_docs/`
+  (as `api.md`, `harnesses.md`, `integration.md`) so `guide` has one
+  authoritative source that works from an installed wheel, with no committed
+  in-package duplicate.
+- **README Installation section.** Documents `pip install agentsquire`,
+  installing from a source clone, and - for developers building on agentsquire -
+  how to install the bundled `developing-with-agentsquire` skill and reference
+  docs into their own harness (`squire skills install`, `squire guide`).
+
 ## [0.2.2]
 
 ### Changed

{agentsquire-0.2.2 → agentsquire-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentsquire
-Version: 0.2.2
+Version: 0.3.0
 Summary: Let a Python package carry its own agent integrations and install them into whatever agent harness is present.
 Author: TacoTakumi
 License-Expression: MIT
@@ -42,6 +42,42 @@ is by marker directory; every operation is local (no network in any verb). Each
 harness's directories, scopes, and behaviour are recorded in
 [docs/harnesses.md](docs/harnesses.md).
 
+## Installation
+
+    pip install agentsquire
+
+This installs the library and its own CLI, `squire` (aliased `agentsquire`). As
+a consumer you normally add `agentsquire` to your package's dependencies rather
+than having users install it directly - it rides in your wheel, and your users
+only ever see your tool.
+
+agentsquire dogfoods its own contract: it carries the
+`developing-with-agentsquire` skill and its reference docs as package data. When
+you build an app on agentsquire, install that skill into your own agent harness
+so the harness has the integration know-how on hand while it works:
+
+    squire skills install
+
+That copies `developing-with-agentsquire` (how to ship skills, mount the group,
+and wire the staleness hook) into every detected harness. The same reference
+docs are served at the terminal from the installed wheel - no checkout needed:
+
+    squire guide              # topics: api, harnesses, integration
+    squire guide api          # the Python API reference
+    squire guide integration  # this consumer integration guide
+
+### From source
+
+Clone the repository and install it into your environment:
+
+    git clone https://github.com/TacoTakumi/AgentSquire.git
+    cd AgentSquire
+    pip install .
+
+Add `-e` (`pip install -e .`) for an editable install if you plan to work on
+agentsquire itself. The repo uses [uv](https://docs.astral.sh/uv/): `uv sync`
+provisions a dev environment and `uv run pytest` runs the test suite.
+
 ## Consumer integration guide
 
 ### 1. Ship skills as package data

{agentsquire-0.2.2 → agentsquire-0.3.0}/README.md

@@ -18,6 +18,42 @@ is by marker directory; every operation is local (no network in any verb). Each
 harness's directories, scopes, and behaviour are recorded in
 [docs/harnesses.md](docs/harnesses.md).
 
+## Installation
+
+    pip install agentsquire
+
+This installs the library and its own CLI, `squire` (aliased `agentsquire`). As
+a consumer you normally add `agentsquire` to your package's dependencies rather
+than having users install it directly - it rides in your wheel, and your users
+only ever see your tool.
+
+agentsquire dogfoods its own contract: it carries the
+`developing-with-agentsquire` skill and its reference docs as package data. When
+you build an app on agentsquire, install that skill into your own agent harness
+so the harness has the integration know-how on hand while it works:
+
+    squire skills install
+
+That copies `developing-with-agentsquire` (how to ship skills, mount the group,
+and wire the staleness hook) into every detected harness. The same reference
+docs are served at the terminal from the installed wheel - no checkout needed:
+
+    squire guide              # topics: api, harnesses, integration
+    squire guide api          # the Python API reference
+    squire guide integration  # this consumer integration guide
+
+### From source
+
+Clone the repository and install it into your environment:
+
+    git clone https://github.com/TacoTakumi/AgentSquire.git
+    cd AgentSquire
+    pip install .
+
+Add `-e` (`pip install -e .`) for an editable install if you plan to work on
+agentsquire itself. The repo uses [uv](https://docs.astral.sh/uv/): `uv sync`
+provisions a dev environment and `uv run pytest` runs the test suite.
+
 ## Consumer integration guide
 
 ### 1. Ship skills as package data

{agentsquire-0.2.2 → agentsquire-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentsquire"
-version = "0.2.2"
+version = "0.3.0"
 description = "Let a Python package carry its own agent integrations and install them into whatever agent harness is present."
 readme = "README.md"
 license = "MIT"
@@ -30,6 +30,16 @@ dependencies = [
     "click",
 ]
 
+[project.scripts]
+squire = "agentsquire.console:main"
+agentsquire = "agentsquire.console:main"
+
+# agentsquire dogfoods its own consumer contract: it carries one bundled skill
+# (developing-with-agentsquire) and marks itself skill-carrying under the same
+# entry-point group it tells consumers to use. Nothing reads this at launch.
+[project.entry-points."agentsquire.skills"]
+agentsquire = "agentsquire"
+
 [dependency-groups]
 dev = [
     "build",
@@ -53,6 +63,15 @@ include = [
     "/docs/harnesses.md",
 ]
 
+# Force-include the three canonical docs into the wheel so `guide` has a single
+# authoritative source with no hand-maintained in-package duplicate. The sources
+# live only under docs/ and README.md; nothing is committed under the package.
+# README.md becomes the `integration` topic.
+[tool.hatch.build.targets.wheel.force-include]
+"docs/api.md" = "agentsquire/_docs/api.md"
+"docs/harnesses.md" = "agentsquire/_docs/harnesses.md"
+"README.md" = "agentsquire/_docs/integration.md"
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["src"]

{agentsquire-0.2.2 → agentsquire-0.3.0}/src/agentsquire/__init__.py

@@ -6,7 +6,7 @@ enumerate skills from a source, detect harnesses, then install / status /
 update / uninstall. See docs/api.md for the reference.
 """
 
-__version__ = "0.2.2"
+__version__ = "0.3.0"
 
 from agentsquire.harnesses import (
     CLAUDE_CODE,

agentsquire-0.3.0/src/agentsquire/console.py

@@ -0,0 +1,90 @@
+"""The ``squire`` root CLI - agentsquire's own runnable executable.
+
+``squire`` (and its long alias ``agentsquire``) is itself an agentsquire
+consumer: it carries one bundled skill (developing-with-agentsquire), mounts the
+skills subcommand group and a ``guide`` command, and emits the proactive
+staleness notice. This module is that root command group; the two console
+scripts in ``[project.scripts]`` both point here.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import version
+from importlib.resources import files as resource_files
+from pathlib import Path
+
+import click
+
+import agentsquire
+from agentsquire import BundledPackageDataSource, check_stale
+from agentsquire.cli import skills_command_group
+
+# The installed agentsquire version, and the single source of truth for
+# ``--version`` (equals agentsquire.__version__, kept in sync by release tooling).
+_VERSION = version("agentsquire")
+
+# The `guide` topics, one per canonical doc. Content is force-included into the
+# wheel under agentsquire/_docs/<topic>.md (see pyproject); nothing is committed
+# under the package, so a source checkout falls back to the repo docs/ + README.
+_GUIDE_TOPICS = ("api", "harnesses", "integration")
+_GUIDE_SOURCE_FALLBACK = {
+    "api": ("docs", "api.md"),
+    "harnesses": ("docs", "harnesses.md"),
+    "integration": ("README.md",),
+}
+
+
+def _read_guide_doc(topic: str) -> str | None:
+    """Content for a guide topic: the packaged agentsquire/_docs/<topic>.md when
+    installed from a wheel, else the repo docs/ + README in a source checkout."""
+    packaged = resource_files("agentsquire") / "_docs" / f"{topic}.md"
+    if packaged.is_file():
+        return packaged.read_text(encoding="utf-8")
+    # Source checkout: <repo>/src/agentsquire/__init__.py -> repo root is parents[2].
+    repo_root = Path(agentsquire.__file__).resolve().parents[2]
+    fallback = repo_root.joinpath(*_GUIDE_SOURCE_FALLBACK[topic])
+    if fallback.is_file():
+        return fallback.read_text(encoding="utf-8")
+    return None
+
+
+@click.group()
+@click.version_option(version=_VERSION, prog_name="squire", message="%(version)s")
+def main() -> None:
+    """squire - install agentsquire's own agent skills into your harness."""
+    # Proactive skill-staleness notice, wired the production way (no home=/
+    # project=, so the real roots resolve). Safe by design: notice-only on
+    # stderr, never prompts, never mutates, never changes the exit code.
+    check_stale(
+        BundledPackageDataSource("agentsquire"),
+        prog_name="squire",
+        update_command="squire skills update",
+    )
+
+
+@main.command()
+@click.argument("topic", required=False)
+def guide(topic: str | None) -> None:
+    """Show agentsquire's reference docs. Run with no TOPIC to list them."""
+    if topic is None:
+        click.echo("Available guide topics:")
+        for name in _GUIDE_TOPICS:
+            click.echo(f"  {name}")
+        return
+    if topic not in _GUIDE_TOPICS:
+        raise click.BadParameter(
+            f"unknown topic {topic!r}. Available topics: "
+            f"{', '.join(_GUIDE_TOPICS)}.",
+            param_hint="TOPIC",
+        )
+    content = _read_guide_doc(topic)
+    if content is None:
+        raise click.ClickException(f"the {topic!r} guide doc is not available.")
+    # Raw markdown via click.echo (no pager) for deterministic, capturable output.
+    click.echo(content)
+
+
+# Dogfood the ready-made group agentsquire publishes: mount it the production
+# way (no home=/project=), so each invocation resolves the real roots. Tests
+# redirect those roots with AGENTSQUIRE_HOME / AGENTSQUIRE_PROJECT.
+main.add_command(skills_command_group("agentsquire", default_scope="user"))

agentsquire-0.3.0/src/agentsquire/skills/developing-with-agentsquire/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: developing-with-agentsquire
+description: "Use when building a Python CLI that carries its own Agent Skills with agentsquire - wiring the skills subcommand group, the staleness notice, console entry points, and package-data layout into a consumer package."
+---
+
+# Developing with agentsquire
+
+agentsquire lets your Python package carry its own Agent Skills and install them
+into whatever agent harness is present (Claude Code, pi, Hermes, opencode). Your
+users only ever run your tool - `your-cli skills install` - never a second CLI.
+
+Add `agentsquire` as a plain dependency, then wire the four points below. This is
+a checklist, not the reference: run `squire guide` (topics `api`, `harnesses`,
+`integration`) or read `docs/api.md` for full signatures and behaviour.
+
+## 1. Ship skills as package data
+
+Lay each skill out as a directory with a `SKILL.md` (agentskills.io format)
+under a `skills/` resource inside your importable package:
+
+```
+your_pkg/
+    __init__.py
+    skills/
+        my-skill/
+            SKILL.md
+```
+
+The skills ride inside your wheel, so no source checkout is needed at run time.
+hatchling includes package data by default; setuptools needs
+`include-package-data`. This skills-as-package-data layout is what
+`BundledPackageDataSource("your_pkg")` reads from.
+
+## 2. Mount the skills subcommand group
+
+`skills_command_group` returns a click group with `install`, `status`, `update`,
+and `uninstall` subcommands, parameterized by your package name and default
+scope. Mount it on your root group:
+
+```python
+from agentsquire.cli import skills_command_group
+
+cli.add_command(skills_command_group("your_pkg", default_scope="user"))
+```
+
+For typer, mount onto `typer.main.get_command(app)`. Every subcommand takes
+`--scope user|project` and `--harness NAME`. Choose `user` scope for
+general-purpose tools, `project` for repo-specific skills.
+
+## 3. Expose a console entry point
+
+Give your CLI a `[project.scripts]` console entry in `pyproject.toml` so users
+invoke it by name:
+
+```toml
+[project.scripts]
+your-cli = "your_pkg.console:main"
+```
+
+## 4. Surface updates proactively (optional)
+
+Call the `check_stale` hook at your entry point. When an installed skill has a
+newer shipped copy it prints one advisory line on stderr and nothing else - it
+never prompts, never writes stdout, never changes your exit code:
+
+```python
+from agentsquire import BundledPackageDataSource, check_stale
+
+def main():
+    check_stale(
+        BundledPackageDataSource("your_pkg"),
+        prog_name="your-cli",
+        update_command="your-cli skills update",
+    )
+    # ... rest of your entry point
+```
+
+Suppressed when `CI` or `AGENTSQUIRE_NO_UPDATE_CHECK` is set to any non-empty
+value.
+
+## 5. Mark the package as skill-carrying (optional)
+
+One pyproject line registers your package under the `agentsquire.skills`
+entry-point marker. Nothing reads it today; it is reserved for a future
+environment-wide listing and changes no behaviour:
+
+```toml
+[project.entry-points."agentsquire.skills"]
+your_pkg = "your_pkg"
+```
+
+## The provenance and update model
+
+Installs are plain copies - no symlinks, no lockfile - so an installed skill
+survives upgrade or removal of your package. Each installed `SKILL.md` carries a
+provenance stamp in its frontmatter `metadata.agentsquire` map (installer,
+versions, source package, content hash). Staleness detection is a local hash
+compare: `status` classifies each skill as not-installed, up-to-date,
+update-available, or locally-modified, and `update` refreshes only the stale
+ones. User-modified installs and pre-existing symlinks are reported and skipped,
+never clobbered. See `squire guide integration` for the full model.

agentsquire-0.3.0/tests/test_bundled_skill.py

@@ -0,0 +1,73 @@
+"""T-01 / REQ-11..13: the one bundled skill is a valid, wheel-shipped skill
+whose body covers every agentsquire wiring point and points at the reference."""
+
+import subprocess
+import sys
+import zipfile
+from pathlib import Path
+
+import pytest
+
+from agentsquire.skills import load_skill, validate_skill_dir
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SKILL_DIR = REPO_ROOT / "src" / "agentsquire" / "skills" / "developing-with-agentsquire"
+SKILL_MD = SKILL_DIR / "SKILL.md"
+
+# REQ-13: the body must cover each wiring point. Grep-checkable tokens, one per
+# point the consumer guide names.
+WIRING_TOKENS = [
+    "package data",          # skills-as-package-data layout
+    "skills_command_group",  # the mount call
+    "check_stale",           # the staleness notice hook
+    "[project.scripts]",     # console entry
+    "agentsquire.skills",    # entry-point marker
+    "provenance",            # provenance/update (staleness) model
+    "staleness",
+]
+# ...and it must point at the full reference rather than duplicate it.
+DOCS_POINTER_TOKENS = ["squire guide", "docs/"]
+
+
+def test_skill_dir_is_structurally_valid():
+    # REQ-11: validate_skill_dir reports no violations.
+    assert validate_skill_dir(SKILL_DIR) == []
+
+
+def test_frontmatter_name_matches_directory():
+    # REQ-11: frontmatter name is developing-with-agentsquire.
+    assert load_skill(SKILL_DIR).name == "developing-with-agentsquire"
+
+
+def test_body_covers_every_wiring_point():
+    # REQ-13: token checklist over the body.
+    body = SKILL_MD.read_text()
+    missing = [token for token in WIRING_TOKENS if token not in body]
+    assert not missing, f"SKILL.md body is missing wiring tokens: {missing}"
+
+
+def test_body_points_to_guide_or_docs():
+    # REQ-13: a pointer to the full reference, not a duplicate of it.
+    body = SKILL_MD.read_text()
+    assert any(token in body for token in DOCS_POINTER_TOKENS)
+
+
+@pytest.fixture(scope="module")
+def wheel_record(tmp_path_factory):
+    """Build the real agentsquire wheel and return its RECORD text (REQ-12)."""
+    outdir = tmp_path_factory.mktemp("dist")
+    subprocess.run(
+        [sys.executable, "-m", "build", "--wheel", "--no-isolation", "--outdir", str(outdir)],
+        cwd=REPO_ROOT,
+        check=True,
+        capture_output=True,
+    )
+    wheel = next(outdir.glob("*.whl"))
+    with zipfile.ZipFile(wheel) as zf:
+        record_name = next(n for n in zf.namelist() if n.endswith(".dist-info/RECORD"))
+        return zf.read(record_name).decode()
+
+
+def test_bundled_skill_ships_in_the_wheel(wheel_record):
+    # REQ-12: the skill's SKILL.md is listed in the built wheel's RECORD.
+    assert "agentsquire/skills/developing-with-agentsquire/SKILL.md" in wheel_record

agentsquire-0.3.0/tests/test_console.py

@@ -0,0 +1,51 @@
+"""T-02 / REQ-01..03: the squire root CLI, its agentsquire alias, and --version."""
+
+from importlib.metadata import entry_points, version
+
+import agentsquire
+from agentsquire.console import main
+from click.testing import CliRunner
+
+
+def test_help_exits_zero_and_renders_the_root_group():
+    # REQ-01: `squire --help` exits 0 and prints the root command group.
+    result = CliRunner().invoke(main, ["--help"])
+    assert result.exit_code == 0
+    assert result.output.startswith("Usage:")
+    assert "install agentsquire's own agent skills" in result.output
+
+
+def test_version_prints_the_installed_agentsquire_version():
+    # REQ-03: `squire --version` prints exactly importlib.metadata.version('agentsquire').
+    result = CliRunner().invoke(main, ["--version"])
+    assert result.exit_code == 0
+    assert result.output.strip() == version("agentsquire")
+
+
+def test_reported_version_equals_dunder_version():
+    # REQ-03: the two declared version sources agree.
+    assert version("agentsquire") == agentsquire.__version__
+
+
+def test_both_console_scripts_resolve_to_the_same_callable():
+    # REQ-01/REQ-02: squire and its agentsquire alias are the identical CLI.
+    scripts = {
+        ep.name: ep.value
+        for ep in entry_points(group="console_scripts")
+        if ep.name in ("squire", "agentsquire")
+    }
+    assert scripts == {
+        "squire": "agentsquire.console:main",
+        "agentsquire": "agentsquire.console:main",
+    }
+
+
+def test_alias_help_is_identical_below_the_usage_line():
+    # REQ-02: `agentsquire --help` is the same root-group help as `squire --help`;
+    # the two invocations differ only in the program name on the Usage line.
+    runner = CliRunner()
+    squire = runner.invoke(main, ["--help"], prog_name="squire").output.splitlines()
+    alias = runner.invoke(main, ["--help"], prog_name="agentsquire").output.splitlines()
+    assert squire[0].startswith("Usage: squire")
+    assert alias[0].startswith("Usage: agentsquire")
+    assert squire[1:] == alias[1:]

agentsquire-0.3.0/tests/test_console_skills.py

@@ -0,0 +1,81 @@
+"""T-03 / REQ-04, REQ-05, REQ-11, REQ-01: the squire CLI mounts the skills group
+and installs its one bundled skill into a detected harness end-to-end.
+
+The group is wired the production way (no home=/project=); these CLI-level tests
+redirect the roots with AGENTSQUIRE_HOME / AGENTSQUIRE_PROJECT (0.2.0 overrides)
+rather than monkeypatching Path.home / chdir."""
+
+import agentsquire
+from agentsquire.console import main
+from agentsquire.stamping import read_stamp
+from click.testing import CliRunner
+
+SKILL = "developing-with-agentsquire"
+
+
+def invoke(*args, **env):
+    return CliRunner().invoke(main, list(args), env=env, catch_exceptions=False)
+
+
+def fixture_roots(tmp_path):
+    """A home carrying the Claude Code marker, and an empty project dir."""
+    home = tmp_path / "home"
+    project = tmp_path / "project"
+    (home / ".claude").mkdir(parents=True)
+    project.mkdir()
+    return home, project
+
+
+def test_skills_help_lists_exactly_the_four_verbs():
+    # REQ-04: the mounted group exposes exactly install/status/update/uninstall.
+    skills_group = main.commands["skills"]
+    assert sorted(skills_group.commands) == ["install", "status", "uninstall", "update"]
+
+    result = invoke("skills", "--help")
+    assert result.exit_code == 0
+    for verb in ("install", "status", "update", "uninstall"):
+        assert verb in result.output
+
+
+def test_install_help_shows_scope_default_user_and_harness():
+    # REQ-04: install exposes --scope (shown default user) and --harness.
+    result = invoke("skills", "install", "--help")
+    assert result.exit_code == 0
+    assert "--scope" in result.output
+    assert "[default: user]" in result.output
+    assert "--harness" in result.output
+
+
+def test_install_writes_stamped_skill_then_reports_up_to_date(tmp_path):
+    # REQ-05/REQ-11: install writes the one bundled skill into the user-scope
+    # Claude Code dir with an agentsquire provenance stamp, idempotently.
+    home, project = fixture_roots(tmp_path)
+    env = {"AGENTSQUIRE_HOME": str(home), "AGENTSQUIRE_PROJECT": str(project)}
+
+    first = invoke("skills", "install", **env)
+    assert first.exit_code == 0, first.output
+
+    installed = home / ".claude" / "skills" / SKILL / "SKILL.md"
+    assert installed.is_file()
+    stamp = read_stamp(installed.read_text())
+    assert stamp is not None
+    assert stamp["installer"] == "agentsquire"
+    assert stamp["source_package"] == "agentsquire"
+    assert stamp["installer_version"] == agentsquire.__version__
+
+    second = invoke("skills", "install", **env)
+    assert second.exit_code == 0, second.output
+    assert "up-to-date" in second.output
+
+
+def test_status_lists_exactly_the_one_bundled_skill(tmp_path):
+    # REQ-11: status over the user scope names exactly developing-with-agentsquire.
+    home, project = fixture_roots(tmp_path)
+    env = {"AGENTSQUIRE_HOME": str(home), "AGENTSQUIRE_PROJECT": str(project)}
+
+    result = invoke("skills", "status", "--scope", "user", **env)
+    assert result.exit_code == 0, result.output
+
+    lines = [line for line in result.output.splitlines() if line.strip()]
+    assert len(lines) == 1
+    assert SKILL in lines[0]

agentsquire-0.3.0/tests/test_console_staleness.py

@@ -0,0 +1,120 @@
+"""T-04 / REQ-06: the squire root callback wires check_stale, so any subcommand
+emits exactly one stderr update notice - naming 'squire skills update' - without
+touching stdout or the exit code, and the suppression env vars silence it.
+
+The hook is wired the production way (no home=/project=); these tests redirect
+the roots with AGENTSQUIRE_HOME / AGENTSQUIRE_PROJECT."""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from agentsquire.console import main
+from agentsquire.harnesses import CLAUDE_CODE
+from agentsquire.sources import DirectorySource
+from agentsquire.verbs import install
+from click.testing import CliRunner
+
+SKILL = "developing-with-agentsquire"
+SRC = Path(__file__).parent.parent / "src"
+
+
+def stale_home(tmp_path):
+    """Home + project fixtures with an installed-but-stale developing-with-agentsquire.
+
+    An 'old' copy (content differing from the real bundled skill) is installed
+    with a correct stamp, so status against BundledPackageDataSource('agentsquire')
+    - the source the console wires - classifies it UPDATE_AVAILABLE."""
+    home = tmp_path / "home"
+    project = tmp_path / "project"
+    (home / ".claude").mkdir(parents=True)
+    project.mkdir()
+
+    bundle = tmp_path / "old-bundle"
+    old = bundle / SKILL
+    old.mkdir(parents=True)
+    (old / "SKILL.md").write_text(
+        f"---\nname: {SKILL}\ndescription: An older bundled copy.\n---\n\nold body\n"
+    )
+    install(
+        DirectorySource(bundle), CLAUDE_CODE, scope="user",
+        home=home, project=project,
+        source_package="agentsquire", source_version="0.0.1",
+    )
+    return home, project
+
+
+def env_for(home, project, **extra):
+    return {"AGENTSQUIRE_HOME": str(home), "AGENTSQUIRE_PROJECT": str(project), **extra}
+
+
+def run(home, project, **extra_env):
+    return CliRunner().invoke(
+        main, ["skills", "status", "--scope", "user"],
+        env=env_for(home, project, **extra_env), catch_exceptions=False,
+    )
+
+
+def test_stale_install_emits_exactly_one_update_notice_on_stderr(tmp_path):
+    home, project = stale_home(tmp_path)
+
+    result = run(home, project)
+
+    assert result.exit_code == 0
+    notices = result.stderr.splitlines()
+    assert len(notices) == 1
+    assert "squire skills update" in notices[0]
+    assert SKILL in notices[0]
+
+
+def test_notice_is_stderr_only_and_leaves_stdout_intact(tmp_path):
+    home, project = stale_home(tmp_path)
+
+    result = run(home, project)
+
+    # stdout is exactly the subcommand's own output; the notice never leaks in.
+    assert "a skills update is available" not in result.stdout
+    assert SKILL in result.stdout
+
+
+def test_ci_env_suppresses_the_notice(tmp_path):
+    home, project = stale_home(tmp_path)
+
+    result = run(home, project, CI="1")
+
+    assert result.exit_code == 0
+    assert result.stderr == ""
+
+
+def test_no_update_check_env_suppresses_the_notice(tmp_path):
+    home, project = stale_home(tmp_path)
+
+    result = run(home, project, AGENTSQUIRE_NO_UPDATE_CHECK="1")
+
+    assert result.exit_code == 0
+    assert result.stderr == ""
+
+
+def test_real_entry_point_keeps_stdout_stderr_and_exit_code_separate(tmp_path):
+    # Strongest evidence: the wired callback fires before dispatch in a real
+    # process, the notice lands on stderr, and stdout/exit code are untouched.
+    home, project = stale_home(tmp_path)
+    env = {k: v for k, v in os.environ.items() if k not in ("CI", "AGENTSQUIRE_NO_UPDATE_CHECK")}
+    env.update({
+        "PYTHONPATH": str(SRC),
+        "AGENTSQUIRE_HOME": str(home),
+        "AGENTSQUIRE_PROJECT": str(project),
+    })
+
+    proc = subprocess.run(
+        [sys.executable, "-c",
+         "import sys; sys.argv = ['squire', 'skills', 'status', '--scope', 'user'];"
+         " from agentsquire.console import main; main()"],
+        stdin=subprocess.DEVNULL, capture_output=True, timeout=60, env=env,
+    )
+
+    assert proc.returncode == 0
+    assert SKILL.encode() in proc.stdout
+    assert b"squire skills update" in proc.stderr
+    assert b"a skills update is available" not in proc.stdout

agentsquire-0.3.0/tests/test_guide.py

@@ -0,0 +1,116 @@
+"""T-06 / REQ-08, REQ-09, REQ-10, REQ-01: the `squire guide` command.
+
+Bare `guide` lists the topics; `guide <topic>` pages the canonical doc via
+click.echo; an unknown topic is a clean non-zero error naming the valid topics.
+Content resolves from the packaged agentsquire/_docs (so it works from an
+installed wheel), falling back to the repo docs/ + README only in a source
+checkout. The wheel-resolution claim is proved by build-and-install, following
+the tests/test_bundled_source.py pattern.
+"""
+
+import subprocess
+import sys
+from pathlib import Path
+
+from agentsquire.console import main
+from click.testing import CliRunner
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+
+# Topic -> a heading known to appear only in that topic's canonical source.
+TOPIC_HEADINGS = {
+    "api": "# AgentSquire Python API reference",
+    "harnesses": "# Harness reference",
+    "integration": "## Consumer integration guide",
+}
+
+
+def invoke(*args):
+    # Suppress the root staleness notice so guide output is deterministic.
+    return CliRunner().invoke(
+        main, list(args), env={"AGENTSQUIRE_NO_UPDATE_CHECK": "1"}
+    )
+
+
+def test_root_help_lists_the_guide_command():
+    # REQ-01: guide is mounted on the root group alongside skills.
+    result = invoke("--help")
+    assert result.exit_code == 0
+    assert "guide" in result.output
+
+
+def test_bare_guide_lists_the_three_topics():
+    # REQ-08: no argument -> exit 0, listing api, harnesses, integration.
+    result = invoke("guide")
+    assert result.exit_code == 0
+    for topic in TOPIC_HEADINGS:
+        assert topic in result.output
+
+
+def test_guide_topic_pages_its_canonical_doc():
+    # REQ-09: each topic prints its own doc's known heading.
+    for topic, heading in TOPIC_HEADINGS.items():
+        result = invoke("guide", topic)
+        assert result.exit_code == 0, result.output
+        assert heading in result.output
+
+
+def test_unknown_topic_is_a_clean_error_naming_valid_topics():
+    # REQ-09: a bogus topic exits non-zero and names the valid topics.
+    result = invoke("guide", "bogus")
+    assert result.exit_code != 0
+    for topic in TOPIC_HEADINGS:
+        assert topic in result.output
+
+
+def test_guide_resolves_from_the_installed_wheel(tmp_path):
+    """REQ-10: with only the built wheel on the path (no repo checkout),
+    `squire guide api` still prints api.md content - proving it resolves from
+    the packaged agentsquire/_docs, not the source tree."""
+    outdir = tmp_path / "dist"
+    subprocess.run(
+        [
+            sys.executable, "-m", "build", "--wheel", "--no-isolation",
+            "--outdir", str(outdir),
+        ],
+        cwd=PROJECT_ROOT,
+        check=True,
+        capture_output=True,
+    )
+    wheel = next(outdir.glob("*.whl"))
+
+    site = tmp_path / "site"
+    subprocess.run(
+        [
+            sys.executable, "-m", "pip", "install",
+            "--no-deps", "--no-index", "--target", str(site), str(wheel),
+        ],
+        check=True,
+        capture_output=True,
+    )
+
+    # Runner asserts agentsquire imports from the wheel-only site (not the
+    # editable source install), then runs `guide api`. Running outside the repo
+    # with PYTHONPATH=site means the source-checkout fallback cannot reach the
+    # repo docs/, so a printed heading can only come from the packaged _docs.
+    runner = tmp_path / "run_guide.py"
+    runner.write_text(
+        "import sys\n"
+        "import agentsquire\n"
+        "assert agentsquire.__file__.startswith(sys.argv[1]), agentsquire.__file__\n"
+        "from agentsquire.console import main\n"
+        "main(args=sys.argv[2:], prog_name='squire', standalone_mode=False)\n"
+    )
+    result = subprocess.run(
+        [sys.executable, str(runner), str(site), "guide", "api"],
+        cwd=tmp_path,
+        env={
+            "PYTHONPATH": str(site),
+            "AGENTSQUIRE_NO_UPDATE_CHECK": "1",
+            "PATH": "/usr/bin:/bin",
+        },
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    assert TOPIC_HEADINGS["api"] in result.stdout

agentsquire-0.3.0/tests/test_guide_packaging.py

@@ -0,0 +1,77 @@
+"""T-05 / REQ-07, REQ-10: the wheel force-includes the three canonical docs.
+
+The `guide` command needs a single authoritative source for its pages with no
+hand-maintained in-package duplicate. The build force-includes docs/api.md,
+docs/harnesses.md, and README.md into the wheel under agentsquire/_docs/, and the
+package source commits no copy of them. Verified by build-and-install, following
+the tests/test_bundled_source.py pattern.
+"""
+
+import subprocess
+import sys
+import zipfile
+from pathlib import Path
+
+import pytest
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+
+# Force-include maps the three sources to these packaged paths.
+PACKAGED_DOCS = {
+    "agentsquire/_docs/api.md": PROJECT_ROOT / "docs" / "api.md",
+    "agentsquire/_docs/harnesses.md": PROJECT_ROOT / "docs" / "harnesses.md",
+    "agentsquire/_docs/integration.md": PROJECT_ROOT / "README.md",
+}
+
+
+@pytest.fixture(scope="module")
+def built_wheel(tmp_path_factory):
+    """Build the agentsquire wheel into a temp dir and hand back its path."""
+    outdir = tmp_path_factory.mktemp("dist")
+    subprocess.run(
+        [
+            sys.executable, "-m", "build", "--wheel", "--no-isolation",
+            "--outdir", str(outdir),
+        ],
+        cwd=PROJECT_ROOT,
+        check=True,
+        capture_output=True,
+    )
+    return next(outdir.glob("*.whl"))
+
+
+def _record_paths(wheel: Path) -> set[str]:
+    """The path column of the wheel's dist-info RECORD."""
+    with zipfile.ZipFile(wheel) as zf:
+        record = next(n for n in zf.namelist() if n.endswith(".dist-info/RECORD"))
+        text = zf.read(record).decode()
+    return {line.split(",", 1)[0] for line in text.splitlines() if line}
+
+
+def test_wheel_record_lists_the_three_packaged_docs(built_wheel):
+    paths = _record_paths(built_wheel)
+    for packaged in PACKAGED_DOCS:
+        assert packaged in paths, f"{packaged} missing from wheel RECORD"
+
+
+def test_packaged_docs_carry_their_source_bytes(built_wheel):
+    with zipfile.ZipFile(built_wheel) as zf:
+        for packaged, source in PACKAGED_DOCS.items():
+            assert zf.read(packaged).decode() == source.read_text()
+
+
+def test_no_canonical_doc_is_committed_under_the_package_source():
+    out = subprocess.run(
+        ["git", "ls-files", "src/agentsquire"],
+        cwd=PROJECT_ROOT,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    tracked = out.stdout.splitlines()
+    offenders = [
+        p for p in tracked
+        if Path(p).name in {"api.md", "harnesses.md", "integration.md"}
+        or "/_docs/" in p
+    ]
+    assert offenders == [], f"canonical docs must live in docs/ only, not: {offenders}"