local-agent-harness 0.1.0__tar.gz

local_agent_harness-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: local-agent-harness
+Version: 0.1.0
+Summary: Maturity-aware harness manager for local AI coding agents (Claude Code, Codex CLI, Copilot CLI, Cursor). Audit, init, and refresh AGENTS.md / GROUNDING.md / CI / sandbox at the right S0–S3 stage; ships an installable skill.
+Keywords: ai-agents,claude-code,codex-cli,copilot-cli,cursor,agents-md,harness,skill,ai-readiness
+Author: Grammy Jiang
+Author-email: Grammy Jiang <grammy.jiang@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Dist: typer>=0.12,<1
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.6 ; extra == 'dev'
+Requires-Dist: mypy>=1.10 ; extra == 'dev'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/grammy-jiang/local-agent-harness
+Project-URL: Repository, https://github.com/grammy-jiang/local-agent-harness
+Project-URL: Issues, https://github.com/grammy-jiang/local-agent-harness/issues
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# local-agent-harness
+
+Maturity-aware harness manager for local AI coding agents (Claude Code,
+Codex CLI, GitHub Copilot CLI, Cursor).
+
+`local-agent-harness` makes a repository ready for AI-agent-assisted
+development from two directions:
+
+1. **Make the agent work better.** Generate `AGENTS.md` / `GROUNDING.md`,
+   per-runtime overlays (`CLAUDE.md`, `.codex/config`,
+   `.github/copilot-cli.md`, `.cursor/rules`), tool DAGs, permission
+   ladders, governed memory, and cost/context budgets.
+2. **Make the repository ready.** Render sandbox/devcontainer,
+   `.pre-commit-config.yaml`, verify CI, governance CI, secrets/SAST/dep
+   scans, and a machine-readable AI-readiness score.
+
+The harness *evolves with the repo*. A blank S0 skeleton receives a
+minimal kit; a mature S3 codebase gets the full set of governance gates.
+
+## Install
+
+```bash
+pipx install local-agent-harness
+local-agent-harness setup        # install the bundled skill into ~/.claude, ~/.copilot, ~/.codex
+```
+
+`setup` only installs into agent skill roots whose parent directory
+already exists. Override with `--target PATH` (repeatable) to install
+into project-local locations like `.github/skills/`.
+
+## Usage
+
+```bash
+local-agent-harness assess                 # detect maturity stage + AI-readiness score
+local-agent-harness check                  # audit manifests for drift (read-only)
+local-agent-harness init  --runtime claude-code --runtime copilot-cli
+local-agent-harness refresh --apply        # rewrite stale manifests (backups written)
+local-agent-harness report --out .agent/readiness.md
+local-agent-harness validate               # regression + redaction smoke checks
+```
+
+Three modes:
+
+| Mode      | Writes? | Use when |
+|-----------|---------|----------|
+| `check`   | no      | Audit-only — CI gate or quick diagnosis. |
+| `init`    | yes     | Render *missing* manifests; never overwrites. |
+| `refresh` | yes (with `--apply`) | Back up + rewrite *stale or relaxed* manifests. |
+
+## Stages (S0 → S3)
+
+| Stage | Repo signal                                  | Default kit                           |
+|-------|----------------------------------------------|---------------------------------------|
+| S0    | empty / no source / no tests / no CI         | AGENTS.md, GROUNDING.md, plan.md      |
+| S1    | source + tests OR CI                         | + pre-commit, devcontainer, verify CI |
+| S2    | source + tests + CI                          | + governance CI, redaction smoke      |
+| S3    | + tags/releases                              | + readiness gate, no-regression check |
+
+## License
+
+MIT

local_agent_harness-0.1.0/README.md

@@ -0,0 +1,61 @@
+# local-agent-harness
+
+Maturity-aware harness manager for local AI coding agents (Claude Code,
+Codex CLI, GitHub Copilot CLI, Cursor).
+
+`local-agent-harness` makes a repository ready for AI-agent-assisted
+development from two directions:
+
+1. **Make the agent work better.** Generate `AGENTS.md` / `GROUNDING.md`,
+   per-runtime overlays (`CLAUDE.md`, `.codex/config`,
+   `.github/copilot-cli.md`, `.cursor/rules`), tool DAGs, permission
+   ladders, governed memory, and cost/context budgets.
+2. **Make the repository ready.** Render sandbox/devcontainer,
+   `.pre-commit-config.yaml`, verify CI, governance CI, secrets/SAST/dep
+   scans, and a machine-readable AI-readiness score.
+
+The harness *evolves with the repo*. A blank S0 skeleton receives a
+minimal kit; a mature S3 codebase gets the full set of governance gates.
+
+## Install
+
+```bash
+pipx install local-agent-harness
+local-agent-harness setup        # install the bundled skill into ~/.claude, ~/.copilot, ~/.codex
+```
+
+`setup` only installs into agent skill roots whose parent directory
+already exists. Override with `--target PATH` (repeatable) to install
+into project-local locations like `.github/skills/`.
+
+## Usage
+
+```bash
+local-agent-harness assess                 # detect maturity stage + AI-readiness score
+local-agent-harness check                  # audit manifests for drift (read-only)
+local-agent-harness init  --runtime claude-code --runtime copilot-cli
+local-agent-harness refresh --apply        # rewrite stale manifests (backups written)
+local-agent-harness report --out .agent/readiness.md
+local-agent-harness validate               # regression + redaction smoke checks
+```
+
+Three modes:
+
+| Mode      | Writes? | Use when |
+|-----------|---------|----------|
+| `check`   | no      | Audit-only — CI gate or quick diagnosis. |
+| `init`    | yes     | Render *missing* manifests; never overwrites. |
+| `refresh` | yes (with `--apply`) | Back up + rewrite *stale or relaxed* manifests. |
+
+## Stages (S0 → S3)
+
+| Stage | Repo signal                                  | Default kit                           |
+|-------|----------------------------------------------|---------------------------------------|
+| S0    | empty / no source / no tests / no CI         | AGENTS.md, GROUNDING.md, plan.md      |
+| S1    | source + tests OR CI                         | + pre-commit, devcontainer, verify CI |
+| S2    | source + tests + CI                          | + governance CI, redaction smoke      |
+| S3    | + tags/releases                              | + readiness gate, no-regression check |
+
+## License
+
+MIT

local_agent_harness-0.1.0/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["uv_build>=0.10.12,<0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "local-agent-harness"
+version = "0.1.0"
+description = "Maturity-aware harness manager for local AI coding agents (Claude Code, Codex CLI, Copilot CLI, Cursor). Audit, init, and refresh AGENTS.md / GROUNDING.md / CI / sandbox at the right S0–S3 stage; ships an installable skill."
+readme = "README.md"
+license = "MIT"
+authors = [
+  {name = "Grammy Jiang", email = "grammy.jiang@gmail.com"}
+]
+requires-python = ">=3.11"
+keywords = [
+  "ai-agents",
+  "claude-code",
+  "codex-cli",
+  "copilot-cli",
+  "cursor",
+  "agents-md",
+  "harness",
+  "skill",
+  "ai-readiness"
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development",
+  "Topic :: Software Development :: Quality Assurance",
+  "Typing :: Typed"
+]
+dependencies = [
+  "typer>=0.12,<1"
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-cov>=5.0",
+  "ruff>=0.6",
+  "mypy>=1.10"
+]
+
+[project.scripts]
+local-agent-harness = "local_agent_harness.cli.app:app"
+
+[project.urls]
+Homepage = "https://github.com/grammy-jiang/local-agent-harness"
+Repository = "https://github.com/grammy-jiang/local-agent-harness"
+Issues = "https://github.com/grammy-jiang/local-agent-harness/issues"
+
+[tool.uv.build-backend]
+module-name = "local_agent_harness"
+module-root = "src"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+ignore = ["E701", "E731"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["E402"]
+"src/local_agent_harness/core/_paths.py" = ["E402"]
+"src/local_agent_harness/core/manifest_regression.py" = ["E402"]
+"src/local_agent_harness/core/diff_manifests.py" = ["E402"]
+"src/local_agent_harness/core/scaffold_manifests.py" = ["E402"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src/local_agent_harness"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

local_agent_harness-0.1.0/src/local_agent_harness/__init__.py

@@ -0,0 +1,4 @@
+"""local-agent-harness — maturity-aware harness manager."""
+from __future__ import annotations
+
+__version__ = "0.1.0"

local_agent_harness-0.1.0/src/local_agent_harness/__main__.py

@@ -0,0 +1,4 @@
+from local_agent_harness.cli.app import app
+
+if __name__ == "__main__":
+    app()

local_agent_harness-0.1.0/src/local_agent_harness/cli/app.py

@@ -0,0 +1,34 @@
+"""Typer entry point wiring all subcommands."""
+from __future__ import annotations
+
+import typer
+
+from . import (
+    cmd_assess,
+    cmd_check,
+    cmd_init,
+    cmd_refresh,
+    cmd_report,
+    cmd_setup,
+    cmd_validate,
+    cmd_version,
+)
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="Maturity-aware harness manager for local AI coding agents.",
+)
+
+app.command("setup", help="Install the bundled skill into agent skill directories.")(cmd_setup.run)
+app.command("assess", help="Detect maturity stage and AI-readiness score.")(cmd_assess.run)
+app.command("check", help="Audit harness manifests for drift (read-only).")(cmd_check.run)
+app.command("init", help="Render missing manifests at the appropriate stage.")(cmd_init.run)
+app.command("refresh", help="Back up + rewrite stale/relaxed manifests (with --apply).")(cmd_refresh.run)
+app.command("report", help="Write a machine-readable AI-readiness report.")(cmd_report.run)
+app.command("validate", help="Run manifest regression and redaction smoke checks.")(cmd_validate.run)
+app.command("version", help="Print version.")(cmd_version.run)
+
+
+if __name__ == "__main__":
+    app()

local_agent_harness-0.1.0/src/local_agent_harness/cli/cmd_assess.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from local_agent_harness.core import assess_repo
+
+
+def run(
+    repo: Path = typer.Option(Path("."), "--repo", help="Repository path."),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON instead of text."),
+) -> None:
+    repo = repo.resolve()
+    if not repo.exists():
+        typer.echo(f"error: {repo} does not exist", err=True)
+        raise typer.Exit(code=2)
+    result = assess_repo.detect(repo)
+    if json_output:
+        typer.echo(json.dumps(result, indent=2, sort_keys=True))
+        return
+    typer.echo(f"Repository: {repo}")
+    typer.echo(f"Stage:      {result['stage']}")
+    typer.echo(f"Total:      {result['total']} / 25")
+    for k, v in result["axes"].items():
+        typer.echo(f"  {k:16s} {v}/5")
+    if result["detected_runtimes"]:
+        typer.echo(f"Runtimes:   {', '.join(result['detected_runtimes'])}")
+    if result["missing_artifacts"]:
+        typer.echo("Missing:")
+        for m in result["missing_artifacts"]:
+            typer.echo(f"  - {m}")

local_agent_harness-0.1.0/src/local_agent_harness/cli/cmd_check.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from local_agent_harness.core import diff_manifests
+
+
+def run(
+    repo: Path = typer.Option(Path("."), "--repo", help="Repository path."),
+    stage: Optional[str] = typer.Option(None, "--stage", help="Override stage (S0|S1|S2|S3)."),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON."),
+) -> None:
+    repo = repo.resolve()
+    if not repo.exists():
+        typer.echo(f"error: {repo} does not exist", err=True)
+        raise typer.Exit(code=2)
+    result = diff_manifests.diff(repo, stage=stage)
+    if json_output:
+        import json
+        typer.echo(json.dumps(result, indent=2, sort_keys=True))
+    else:
+        diff_manifests._print_human(result)
+    if result.get("relaxed"):
+        raise typer.Exit(code=2)
+    if result.get("drift"):
+        raise typer.Exit(code=1)

local_agent_harness-0.1.0/src/local_agent_harness/cli/cmd_init.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Optional
+
+import typer
+
+from local_agent_harness.core import assess_repo, scaffold_manifests
+
+
+def run(
+    repo: Path = typer.Option(Path("."), "--repo", help="Repository path."),
+    stage: Optional[str] = typer.Option(None, "--stage", help="Override stage (S0|S1|S2|S3)."),
+    runtime: List[str] = typer.Option(
+        [], "--runtime", help="Runtime overlay(s) to render: claude-code|codex-cli|copilot-cli|cursor."
+    ),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Show what would be written."),
+) -> None:
+    repo = repo.resolve()
+    if not repo.exists():
+        typer.echo(f"error: {repo} does not exist", err=True)
+        raise typer.Exit(code=2)
+    if stage is None:
+        stage = assess_repo.detect(repo)["stage"]
+    rc = scaffold_manifests.cmd_init(repo, stage, list(runtime), dry_run)
+    raise typer.Exit(code=rc)

local_agent_harness-0.1.0/src/local_agent_harness/cli/cmd_refresh.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Optional
+
+import typer
+
+from local_agent_harness.core import assess_repo, scaffold_manifests
+
+
+def run(
+    repo: Path = typer.Option(Path("."), "--repo", help="Repository path."),
+    stage: Optional[str] = typer.Option(None, "--stage", help="Override stage (S0|S1|S2|S3)."),
+    runtime: List[str] = typer.Option([], "--runtime", help="Runtime overlay(s) to render."),
+    apply: bool = typer.Option(False, "--apply", help="Actually write changes (default is dry-run)."),
+) -> None:
+    repo = repo.resolve()
+    if not repo.exists():
+        typer.echo(f"error: {repo} does not exist", err=True)
+        raise typer.Exit(code=2)
+    if stage is None:
+        stage = assess_repo.detect(repo)["stage"]
+    rc = scaffold_manifests.cmd_refresh(repo, stage, list(runtime), apply, dry=not apply)
+    raise typer.Exit(code=rc)

local_agent_harness-0.1.0/src/local_agent_harness/cli/cmd_report.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from local_agent_harness.core import assess_repo, readiness_report
+
+
+def run(
+    repo: Path = typer.Option(Path("."), "--repo", help="Repository path."),
+    out: Optional[Path] = typer.Option(None, "--out", help="Write report to this path (default stdout)."),
+    check_no_regression: Optional[Path] = typer.Option(
+        None, "--check-no-regression",
+        help="Compare a fresh assessment against an existing readiness file; fail on per-axis regressions.",
+    ),
+) -> None:
+    repo = repo.resolve()
+    if not repo.exists():
+        typer.echo(f"error: {repo} does not exist", err=True)
+        raise typer.Exit(code=2)
+    result = assess_repo.detect(repo)
+
+    if check_no_regression:
+        prev_text = check_no_regression.read_text(encoding="utf-8")
+        prev = readiness_report.parse_machine_block(prev_text)
+        if prev is None:
+            typer.echo("error: previous readiness file has no machine block", err=True)
+            raise typer.Exit(code=2)
+        regressed = []
+        for axis, score in result["axes"].items():
+            old = int(prev.get(axis, 0))
+            if score < old:
+                regressed.append(f"{axis}: {old} -> {score}")
+        if regressed:
+            for line in regressed:
+                typer.echo(f"REGRESSION {line}", err=True)
+            raise typer.Exit(code=1)
+        typer.echo("OK no regression")
+        return
+
+    text = readiness_report.render_report(result, repo)
+    if out:
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(text, encoding="utf-8")
+        typer.echo(f"wrote {out}")
+    else:
+        typer.echo(text)

local_agent_harness-0.1.0/src/local_agent_harness/cli/cmd_setup.py

@@ -0,0 +1,92 @@
+"""Install the bundled `local-agent-harness` skill into agent skill directories.
+
+Default targets are the three known agent skill roots, but only those whose
+parent directory already exists on disk:
+
+* ``~/.claude/skills/local-agent-harness/``   (Claude Code)
+* ``~/.copilot/skills/local-agent-harness/``  (GitHub Copilot CLI)
+* ``~/.codex/skills/local-agent-harness/``    (Codex CLI)
+
+Use ``--target PATH`` (repeatable) to install elsewhere, e.g. into a
+project-local ``.github/skills/<name>/`` directory.
+"""
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import List
+
+import typer
+
+from local_agent_harness.core._paths import skill_data_root
+
+_SKILL_NAME = "local-agent-harness"
+
+
+def _default_targets() -> list[Path]:
+    """Return skill dirs whose *parent* (e.g. ~/.claude/skills) already exists.
+
+    Falls back to ``~/.claude/skills/<name>`` if none exist, so first-time
+    users on a fresh box still get a sensible default.
+    """
+    home = Path.home()
+    candidates = [
+        home / ".claude" / "skills",
+        home / ".copilot" / "skills",
+        home / ".codex" / "skills",
+    ]
+    existing = [p / _SKILL_NAME for p in candidates if p.is_dir()]
+    if existing:
+        return existing
+    return [candidates[0] / _SKILL_NAME]
+
+
+def _install(src: Path, dst: Path, *, symlink: bool, force: bool) -> str:
+    if dst.exists() or dst.is_symlink():
+        if not force:
+            return f"SKIP {dst} (exists; use --force to overwrite)"
+        if dst.is_symlink() or dst.is_file():
+            dst.unlink()
+        else:
+            shutil.rmtree(dst)
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    if symlink:
+        dst.symlink_to(src, target_is_directory=True)
+        return f"LINK {dst} -> {src}"
+    shutil.copytree(src, dst)
+    return f"COPY {dst}"
+
+
+def run(
+    target: List[Path] = typer.Option(
+        [],
+        "--target",
+        "-t",
+        help=(
+            "Destination directory for the skill (repeatable). "
+            "Defaults to the existing agent skill roots: "
+            "~/.claude/skills, ~/.copilot/skills, ~/.codex/skills."
+        ),
+    ),
+    symlink: bool = typer.Option(
+        False, "--symlink", help="Symlink instead of copying (good for development)."
+    ),
+    force: bool = typer.Option(
+        False, "--force", "-f", help="Overwrite the destination if it already exists."
+    ),
+    list_only: bool = typer.Option(
+        False, "--list", help="Print the resolved targets and exit without writing."
+    ),
+) -> None:
+    src = skill_data_root()
+    targets = [t.expanduser().resolve() for t in target] if target else _default_targets()
+
+    if list_only:
+        typer.echo(f"source: {src}")
+        for t in targets:
+            typer.echo(f"target: {t}")
+        return
+
+    for t in targets:
+        msg = _install(src, t, symlink=symlink, force=force)
+        typer.echo(msg)

local_agent_harness-0.1.0/src/local_agent_harness/cli/cmd_validate.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from local_agent_harness.core import manifest_regression, redaction_smoke
+
+
+def run(
+    repo: Path = typer.Option(Path("."), "--repo", help="Repository path."),
+) -> None:
+    repo = repo.resolve()
+    if not repo.exists():
+        typer.echo(f"error: {repo} does not exist", err=True)
+        raise typer.Exit(code=2)
+
+    typer.echo("== manifest regression ==")
+    results = manifest_regression.check(repo)
+    failed = 0
+    for name, ok, msg in results:
+        marker = "PASS" if ok else "FAIL"
+        typer.echo(f"  [{marker}] {name}: {msg}")
+        if not ok:
+            failed += 1
+
+    typer.echo("== redaction smoke ==")
+    findings = redaction_smoke.scan(repo)
+    for path, kind in findings:
+        typer.echo(f"  HIT {kind}: {path}")
+    logs_ok = redaction_smoke.check_logs_ignored(repo)
+    typer.echo(f"  .agent/.env in .gitignore: {'yes' if logs_ok else 'no'}")
+
+    if failed or findings or not logs_ok:
+        raise typer.Exit(code=1)
+    typer.echo("validate: OK")

local_agent_harness-0.1.0/src/local_agent_harness/cli/cmd_version.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import typer
+
+from local_agent_harness import __version__
+
+
+def run() -> None:
+    typer.echo(f"local-agent-harness {__version__}")

local_agent_harness-0.1.0/src/local_agent_harness/core/__init__.py

@@ -0,0 +1,4 @@
+"""Core library — pure functions implementing the harness operations.
+
+CLI commands in :mod:`local_agent_harness.cli` delegate to these modules.
+"""

local_agent_harness-0.1.0/src/local_agent_harness/core/_paths.py

@@ -0,0 +1,29 @@
+"""Locate packaged skill data (assets/, references/, SKILL.md).
+
+The package ships a copy of the skill under
+``local_agent_harness/skill_data/local-agent-harness/``. This module finds
+the assets directory whether installed as a wheel or used in editable mode.
+"""
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+
+_SKILL_NAME = "local-agent-harness"
+
+
+def skill_data_root() -> Path:
+    """Return the directory containing SKILL.md / assets/ / references/."""
+    ref = importlib.resources.files("local_agent_harness") / "skill_data" / _SKILL_NAME
+    p = Path(str(ref))
+    if not p.is_dir():
+        raise RuntimeError(f"skill_data not found at {p}")
+    return p
+
+
+def assets_dir() -> Path:
+    return skill_data_root() / "assets"
+
+
+def references_dir() -> Path:
+    return skill_data_root() / "references"