spec-agent-cli 0.1.0__py3-none-any.whl

spec_agent/__init__.py

@@ -0,0 +1,11 @@
+"""Spec Agent CLI package."""
+
+__all__ = ["main"]
+
+
+def __getattr__(name: str):
+    if name == "main":
+        from spec_agent.cli import main
+
+        return main
+    raise AttributeError(name)

spec_agent/__main__.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import sys
+
+from spec_agent.cli import main
+
+
+if __name__ == "__main__":
+    sys.exit(main())

spec_agent/cli.py

@@ -0,0 +1,70 @@
+"""Command-line interface for installing Spec Agent into repositories."""
+
+# spec: CLI-001, CLI-007, CLI-008
+
+from __future__ import annotations
+
+import sys
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+import typer
+
+from spec_agent.commands.init import cmd_init
+
+
+app = typer.Typer(
+    no_args_is_help=True,
+    add_completion=True,
+    help="Install the strict Spec Agent workflow into a repository.",
+)
+
+
+def _version_callback(value: bool) -> None:
+    if not value:
+        return
+    try:
+        current = version("spec-agent-cli")
+    except PackageNotFoundError:
+        current = "dev"
+    print(f"spec-agent {current}")
+    raise typer.Exit()
+
+
+@app.callback()
+def root(
+    show_version: bool = typer.Option(
+        False,
+        "--version",
+        help="Show the installed version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """Install and maintain Spec Agent project assets."""
+
+
+@app.command("init")
+def init_command(
+    repo: Path = typer.Option(Path("."), "--repo", help="Repository to initialize."),
+    check: bool = typer.Option(False, "--check", help="Report status; write nothing."),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Update locally changed managed skill files.",
+    ),
+) -> None:
+    """Install .agents/skills and scaffold missing specification files."""
+    raise typer.Exit(cmd_init(repo, check=check, force=force))
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        app(args=argv, prog_name="spec-agent")
+    except SystemExit as error:
+        return error.code if isinstance(error.code, int) else 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

spec_agent/commands/__init__.py

@@ -0,0 +1 @@
+"""Spec Agent command implementations."""

spec_agent/commands/init.py

@@ -0,0 +1,29 @@
+"""Implementation of ``spec-agent init``."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from spec_agent import installer
+
+
+def _print_rows(rows: list[tuple[str, str]]) -> None:
+    width = max((len(path) for path, _ in rows), default=0)
+    for path, status in rows:
+        print(f"  {path.ljust(width)}  {status}")
+
+
+def cmd_init(repo_root: Path, *, check: bool = False, force: bool = False) -> int:
+    root = repo_root.resolve()
+    if check:
+        rows = installer.check_status(root)
+        _print_rows(rows)
+        valid = {"up to date", "present"}
+        return 0 if all(status in valid for _, status in rows) else 1
+
+    rows = installer.install(root, force=force)
+    print(f"Spec Agent initialized in {root}")
+    _print_rows(rows)
+    print("")
+    print("Next: ask your agent to use spec-request-flow for a feature request.")
+    return 0 if all(status != installer.DAMAGED for _, status in rows) else 1

spec_agent/installer.py

@@ -0,0 +1,201 @@
+"""Safely install packaged Spec Agent assets into a repository."""
+
+# spec: CLI-002, CLI-003, CLI-004, CLI-005, CLI-006, CLI-007, CLI-008, CLI-009, CLI-010, CLI-011, SA-017, SA-018, SA-019
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from spec_agent import package_assets
+
+
+MARKER_START = "<!-- spec-agent:rules:start -->"
+MARKER_END = "<!-- spec-agent:rules:end -->"
+DAMAGED = "damaged markers — fix or remove the spec-agent:rules markers, then re-run"
+
+EMPTY_TIMELINE = """<!-- Generated from spec/evolution/events.jsonl by .agents/skills/spec-evolution/scripts/timeline.py; do not edit. -->
+# Specification Evolution Timeline
+
+## Mermaid
+
+```mermaid
+timeline
+  title Specification Evolution
+```
+"""
+
+EMPTY_TRACEABILITY = json.dumps(
+    {
+        "behaviors": {},
+        "schema_version": 1,
+        "source": "derived-from-code-backlinks",
+    },
+    indent=2,
+    sort_keys=True,
+) + "\n"
+
+
+def load_skill_files() -> dict[str, bytes]:
+    """Return every file from the three canonical skill directories."""
+    return package_assets.skill_files()
+
+
+def render_rules_block(body: str) -> str:
+    return f"{MARKER_START}\n{body.strip()}\n{MARKER_END}"
+
+
+def _find_block(text: str) -> tuple[int, int] | None:
+    starts = text.count(MARKER_START)
+    ends = text.count(MARKER_END)
+    if starts == 0 and ends == 0:
+        return None
+    if starts != 1 or ends != 1:
+        raise ValueError("unbalanced spec-agent rules markers")
+    start = text.find(MARKER_START)
+    end = text.find(MARKER_END)
+    if end < start:
+        raise ValueError("spec-agent rules end marker precedes start marker")
+    return start, end + len(MARKER_END)
+
+
+def _managed_file_status(path: Path, expected: bytes) -> str:
+    if not path.is_file():
+        return "missing"
+    return "up to date" if path.read_bytes() == expected else "outdated"
+
+
+def _rules_status(path: Path, block: str) -> str:
+    if not path.is_file():
+        return "missing"
+    text = path.read_text(encoding="utf-8")
+    try:
+        span = _find_block(text)
+    except ValueError:
+        return DAMAGED
+    if span is None:
+        return "missing"
+    return "up to date" if text[span[0] : span[1]] == block else "outdated"
+
+
+def _apply_managed_file(path: Path, expected: bytes, force: bool) -> str:
+    if not path.is_file():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(expected)
+        return "installed"
+    if path.read_bytes() == expected:
+        return "up to date"
+    if force:
+        path.write_bytes(expected)
+        return "updated"
+    return "outdated (--force to update)"
+
+
+def _apply_rules(path: Path, block: str) -> str:
+    if not path.is_file():
+        path.write_text(block + "\n", encoding="utf-8")
+        return "created"
+    text = path.read_text(encoding="utf-8")
+    try:
+        span = _find_block(text)
+    except ValueError:
+        return DAMAGED
+    if span is None:
+        updated = text.rstrip("\n") + ("\n\n" if text.strip() else "") + block + "\n"
+    else:
+        updated = text[: span[0]] + block + text[span[1] :]
+    if updated == text:
+        return "up to date"
+    path.write_text(updated, encoding="utf-8")
+    return "rules block added" if span is None else "updated"
+
+
+def _create_file(path: Path, content: str) -> str:
+    if path.exists():
+        return "present"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return "created"
+
+
+def _create_directory(path: Path) -> str:
+    if path.is_dir():
+        return "present"
+    path.mkdir(parents=True, exist_ok=True)
+    return "created"
+
+
+def _scaffold_items(repo_root: Path) -> list[tuple[str, str]]:
+    return [
+        ("SPEC.md", "present" if (repo_root / "SPEC.md").is_file() else "missing"),
+        (
+            "spec/features/",
+            "present" if (repo_root / "spec/features").is_dir() else "missing",
+        ),
+        (
+            "spec/evolution/events.jsonl",
+            "present"
+            if (repo_root / "spec/evolution/events.jsonl").is_file()
+            else "missing",
+        ),
+        (
+            "spec/evolution/timeline.md",
+            "present"
+            if (repo_root / "spec/evolution/timeline.md").is_file()
+            else "missing",
+        ),
+        (
+            "spec/traceability.json",
+            "present" if (repo_root / "spec/traceability.json").is_file() else "missing",
+        ),
+    ]
+
+
+def check_status(repo_root: Path) -> list[tuple[str, str]]:
+    """Report installation state without writing anything."""
+    root = repo_root.resolve()
+    rows = [
+        (
+            f".agents/skills/{relative}",
+            _managed_file_status(root / ".agents/skills" / relative, content),
+        )
+        for relative, content in sorted(load_skill_files().items())
+    ]
+    block = render_rules_block(package_assets.rules_text())
+    rows.append(("AGENTS.md", _rules_status(root / "AGENTS.md", block)))
+    rows.extend(_scaffold_items(root))
+    return rows
+
+
+def install(repo_root: Path, *, force: bool = False) -> list[tuple[str, str]]:
+    """Install agent assets and scaffold missing project-owned spec files."""
+    root = repo_root.resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    rows = [
+        (
+            f".agents/skills/{relative}",
+            _apply_managed_file(root / ".agents/skills" / relative, content, force),
+        )
+        for relative, content in sorted(load_skill_files().items())
+    ]
+    block = render_rules_block(package_assets.rules_text())
+    rows.append(("AGENTS.md", _apply_rules(root / "AGENTS.md", block)))
+    rows.extend(
+        [
+            ("SPEC.md", _create_file(root / "SPEC.md", package_assets.project_spec_template())),
+            ("spec/features/", _create_directory(root / "spec/features")),
+            (
+                "spec/evolution/events.jsonl",
+                _create_file(root / "spec/evolution/events.jsonl", ""),
+            ),
+            (
+                "spec/evolution/timeline.md",
+                _create_file(root / "spec/evolution/timeline.md", EMPTY_TIMELINE),
+            ),
+            (
+                "spec/traceability.json",
+                _create_file(root / "spec/traceability.json", EMPTY_TRACEABILITY),
+            ),
+        ]
+    )
+    return rows

spec_agent/package_assets.py

@@ -0,0 +1,56 @@
+"""Read canonical Spec Agent assets in source checkouts and built wheels."""
+
+from __future__ import annotations
+
+from importlib.resources import files
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+
+def _development_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def _embedded_root() -> Any:
+    return files("spec_agent").joinpath("resources")
+
+
+def skill_root() -> Any:
+    embedded = _embedded_root().joinpath("skills")
+    if embedded.is_dir():
+        return embedded
+    return _development_root() / ".agents/skills"
+
+
+def rules_text() -> str:
+    embedded = _embedded_root().joinpath("project-rules.md")
+    if embedded.is_file():
+        return embedded.read_text(encoding="utf-8")
+    return (_development_root() / "AGENTS.md").read_text(encoding="utf-8")
+
+
+def project_spec_template() -> str:
+    return (
+        skill_root()
+        .joinpath("spec-request-flow")
+        .joinpath("assets")
+        .joinpath("SPEC.template.md")
+        .read_text(encoding="utf-8")
+    )
+
+
+def skill_files() -> dict[str, bytes]:
+    result: dict[str, bytes] = {}
+
+    def visit(directory: Any, prefix: PurePosixPath) -> None:
+        for entry in sorted(directory.iterdir(), key=lambda item: item.name):
+            if entry.name == "__pycache__" or entry.name.endswith((".pyc", ".pyo")):
+                continue
+            relative = prefix / entry.name
+            if entry.is_dir():
+                visit(entry, relative)
+            elif entry.is_file():
+                result[str(relative)] = entry.read_bytes()
+
+    visit(skill_root(), PurePosixPath())
+    return result

spec_agent/resources/project-rules.md

@@ -0,0 +1,18 @@
+# Strict Spec Agent
+
+Read root `SPEC.md`, then load one discoverable skill from `.agents/skills/`.
+Feature packets contain product-only `spec.md` and `acceptance.md` files under
+`spec/features/<feature-slug>/`.
+
+| Situation | Load skill |
+|---|---|
+| Feature, fix, refactor, or behavior request | `spec-request-flow` |
+| Possible spec/code/backlink disagreement | `spec-drift-sync` |
+| Approved product change, rationale, or timeline | `spec-evolution` |
+
+`spec-request-flow` ends after explicit approval and the Code Agent handoff. It
+never writes implementation plans, code, tests, or engineering commands.
+
+Code backlinks use `spec: BEHAVIOR-ID`. `spec-drift-sync` observes them and may
+regenerate only non-normative `spec/traceability.json`; it never repairs code or
+specifications. Product decision history lives in `spec/evolution/events.jsonl`.

spec_agent/resources/skills/spec-drift-sync/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: spec-drift-sync
+description: Use when accepted specifications may disagree with implementations after refactors, merges, hotfixes, or code-only changes, or when backlinks, traceability, tests, or verification evidence may be missing or stale.
+---
+
+# Spec Drift Sync
+
+Act as a read-only observer of specification/code disagreement. Product specs
+remain normative; code, tests, Git history, and passing verification are evidence.
+
+<HARD-GATE>
+Do not edit specifications, code, tests, code backlinks, or verification state. Do not
+run an implementation or repair workflow. The only permitted write is regenerating the
+non-normative derived traceability index from backlinks that already exist in code.
+</HARD-GATE>
+
+## Detection
+
+1. Read root `SPEC.md`, both files in the affected feature packet, current code and
+   public behavior, existing `spec: BEHAVIOR-ID` backlinks, relevant Git changes, and
+   related product-decision history.
+2. Run `scripts/check.py check --repo REPOSITORY`. Use `--spec-root SPEC_SOURCE` only
+   for an intentionally scoped observation.
+3. Inspect meaning manually. A clean structural report proves identity consistency,
+   not semantic compliance.
+
+## Traceability refresh
+
+Run `scripts/check.py sync --repo REPOSITORY --output spec/traceability.json` to replace
+only the derived traceability index. It maps behavior IDs to existing code backlink
+locations. It must not be copied into `spec.md` or `acceptance.md`, treated as product
+authority, or edited to conceal missing links.
+
+## Evidence report
+
+For every finding report:
+
+- behavior ID and drift category;
+- normative product evidence with specification path and rule;
+- implementation evidence with code, interface, test, or Git location;
+- structural identity problem or semantic conflict;
+- observable impact and the authority decision required.
+
+Structural findings include `phantom`, `dead-ref`, `silent-implementation`, `unlinked`,
+and `stale-verification`. Semantic conflicts include code contradicting accepted
+behavior, obsolete or ambiguous product rules, and behavior without product authority.
+
+## Authority handoff
+
+Ask one product decision at a time and present viable outcomes with impact. Never
+silently promote observed code to intended behavior.
+
+- If intended product behavior changes, hand the decision to `spec-request-flow` for
+  clarification, both spec files, and approval.
+- If the approved product behavior remains correct, hand the evidence to a separate
+  Code Agent to plan engineering changes.
+- Use `spec-evolution` only to preserve an approved product authority decision.
+
+Stop after the evidence report and handoff. Do not apply the selected repair, add
+backlinks, execute tests, weaken the checker, or mark verification current.