speckit-specops 0.1.0__tar.gz

speckit_specops-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Packaging / distribution
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+pip-wheel-metadata/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / coverage / type-check caches
+.pytest_cache/
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.mypy_cache/
+.ruff_cache/
+
+# Environment files
+.env
+.env.*
+
+# Editors / IDEs
+.idea/
+.vscode/
+
+# macOS
+.DS_Store
+
+# Claude Code local settings
+.claude/settings.local.json

speckit_specops-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paulo Segundo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

speckit_specops-0.1.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: speckit-specops
+Version: 0.1.0
+Summary: A Spec-Driven Development (SDD) process enforcement CLI extending Speckit
+Author-email: Paulo Segundo <paulosegundo@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: gitpython>=3.1.40
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SpecOps CLI
+
+[![CI](https://github.com/paulo2nd/specops/actions/workflows/ci.yml/badge.svg)](https://github.com/paulo2nd/specops/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/speckit-specops.svg)](https://pypi.org/project/speckit-specops/)
+[![Python](https://img.shields.io/pypi/pyversions/speckit-specops.svg)](https://pypi.org/project/speckit-specops/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**SpecOps turns [GitHub Speckit](https://github.com/vgrecov/speckit)'s
+spec-driven workflow into an enforced, auditable process.** It layers an
+agent-guided *atomic development* methodology on top of any Speckit repository —
+a physical state ledger, machine-collected evidence, and token-optimized review —
+**without replacing or forking a single Speckit file.**
+
+> Speckit gives your agents great artifacts (spec → plan → tasks → implement).
+> SpecOps makes sure they actually follow them: state is on disk and
+> Git-verifiable, evidence is collected by tooling instead of claimed by the
+> agent, and review rejects as cheaply as possible.
+
+## Why SpecOps?
+
+Spec-driven development with AI agents has three recurring failure modes.
+SpecOps addresses each one:
+
+| Problem | Without SpecOps | With SpecOps |
+|---|---|---|
+| **Agents hallucinate progress** | "Done ✅" with no proof | Every task is closed with machine-collected evidence (test output, commit hashes, diffs) recorded in the ledger |
+| **State lives in the chat** | Lost on context reset; not auditable | State is a physical `status.yaml` ledger, Git-verifiable and recovery-safe |
+| **Reviews are slow and expensive** | Agent reads the whole repo | `/specops-review` rejects cheapest-first (reconcile → lint/test → out-of-plan files) before reading any code |
+
+## What it adds to Speckit
+
+- **📒 Physical state ledger (Repo-as-State).** A structured `status.yaml`
+  tracks phase, tasks, evidence, and review cycles. Mutated only through
+  `specops` commands — never hand-edited, never held in agent memory.
+- **🔬 Automated evidence collection.** `complete-task --auto` runs your test
+  command, harvests commits and diffs, and records them as typed evidence. A
+  task cannot be `DONE` without proof.
+- **🔁 A phase state machine wired into the prompts.** `specops init` injects
+  directives into the specify, plan, tasks, and implement prompts so the ledger
+  is created and phases advance automatically — the human never runs the
+  bookkeeping by hand.
+- **✂️ Token-optimized surgical review.** The installed `/specops-review`
+  command reviews only in-scope files and stops at the first cheap rejection.
+- **📐 Empirical verification & gates.** `specops consistency` and
+  `specops reconcile` are exit-code gates you can drop into CI or agent prompts.
+- **➕ Additive and reversible.** Everything is delivered through
+  marker-delimited blocks. Uninstalling restores your Speckit files
+  byte-for-byte.
+
+## Install
+
+```bash
+pip install speckit-specops
+```
+
+Installs the `specops` command. Requires Python ≥ 3.10 and Git ≥ 2.30. No
+network I/O after install.
+
+## Quick Start
+
+```bash
+# In a Speckit-initialized repository:
+specops init          # inject directives, install /specops-review, create specops.json
+```
+
+That's it. From here you drive Speckit as usual (`/speckit.specify`,
+`/speckit.plan`, `/speckit.tasks`, `/speckit.implement`) and the injected
+directives take care of the ledger and phase transitions. Check state anytime:
+
+```bash
+specops status show
+```
+
+## How it works
+
+SpecOps rides the Speckit lifecycle. Once `specops init` has run, the injected
+directives drive the ledger at each stage seam:
+
+| Speckit stage | What SpecOps does |
+|---|---|
+| **specify** | Marks the repo as SpecOps-managed (informational; no ledger yet) |
+| **plan** | Enforces empirical path verification and the `consistency` gate |
+| **tasks** | Creates the ledger (`status init-spec`), advances the phase to `TASKS`, and requires `[SC-xxx]` coverage tags on every task |
+| **implement** | Opens `IMPLEMENT`, runs the evidence-backed ledger loop, then opens `REVIEW` |
+| **review** | `/specops-review` validates the diff and records `APPROVED` / `REJECTED` |
+
+The phase machine is `SPECIFY → PLAN → TASKS → IMPLEMENT → REVIEW → DONE`.
+If SpecOps is not installed, the Speckit prompts still work standalone — the
+directives degrade to no-ops.
+
+## Command reference
+
+### `specops init [--non-interactive]`
+
+Prepares a Speckit repository in one run: validates (or offers to create) a Git
+repo, detects Speckit, resolves prompt targets from Speckit's integration
+manifests (works with any recorded agent layout — Claude skills, GitHub
+Copilot, etc.), creates/merge-preserves `specops.json`, installs
+`/specops-review`, and injects the directive blocks into the specify, plan,
+tasks, and implement prompts (additive, idempotent, byte-identical restore on
+removal). `--non-interactive` declines all prompts (CI-safe).
+
+> **Speckit upgrade note**: a Speckit upgrade may rewrite prompt files and
+> remove the injected blocks. Just re-run `specops init` to re-inject.
+
+### `specops status show`
+
+Read-only. Prints ledger state: feature, branch, phase, active task, task counts
+(pending / in progress / done / orphaned), and the review-cycle history.
+
+### `specops status init-spec [<name>]`
+
+Creates `<feature_dir>/status.yaml` from the packaged scaffold, syncing task IDs
+from `tasks.md`. Usually run for you by the tasks directive.
+
+### `specops status start-task <task-id>`
+
+Marks the task `IN_PROGRESS` and records `started_commit = HEAD`. Enforces the
+single-active-task rule.
+
+### `specops status complete-task <task-id> [--auto | --evidence "CLASS:summary"]`
+
+Marks the task `DONE` with exactly one evidence source:
+
+- `--auto`: runs `test_command`; on success, harvests `started_commit..HEAD`
+  commits + diff as `TEST_REPORT`/`CODE_DIFF` evidence.
+- `--evidence "CLASS:summary"`: caller-supplied, with `CLASS` in
+  `CLI_LOG | TEST_REPORT | SCREENSHOT_PATH | CODE_DIFF`.
+
+### `specops status transition-phase <phase> [-r APPROVED|REJECTED]`
+
+Advances the phase one step forward. Two transitions require `-r`:
+
+```bash
+specops status transition-phase DONE -r APPROVED      # approved → close the feature
+specops status transition-phase IMPLEMENT -r REJECTED # rejected → send back for rework
+```
+
+Entering `DONE` requires the latest review cycle to be `APPROVED`.
+
+### `specops reconcile`
+
+Read-only gate. Verifies every ledger commit hash is reachable from `HEAD` and
+every `DONE` task has commits and evidence. Exit 1 on any divergence.
+
+```bash
+specops reconcile || exit 1   # preflight before review
+```
+
+### `specops consistency`
+
+Read-only gate. Verifies every `SC-\d+` in the spec has ≥ 1 task with a matching
+`[SC-xxx]` tag, and every `plan.md` path declaration carries a valid action
+suffix (`(create)`/`(modify)`/`(remove)`). Exit 1 on violation.
+
+### `specops --version`
+
+Prints the version and exits. Works anywhere.
+
+## Configuration — `specops.json`
+
+| Key | Purpose | Default |
+|---|---|---|
+| `test_command` | Command run by `complete-task --auto` | `pytest` |
+| `lint_command` | Command referenced by the review prompt | `""` |
+| `skills_dir` | Directory the review prompt loads skills from | `.specify/skills` |
+
+Unknown keys are preserved on re-init.
+
+## The `/specops-review` command
+
+Installed by `specops init` (the name follows the layout's separator, e.g.
+`/specops-review` for Claude skills). Not a CLI command — a packaged prompt that
+drives the review agent cheapest-rejection-first:
+
+1. Load skills from `skills_dir`.
+2. `specops reconcile` — abort immediately on failure.
+3. `lint_command` + `test_command` — reject on failure.
+4. `git status --porcelain` — reject any out-of-plan file without reading code.
+5. Surgical diff review of in-scope files only.
+6. Write `revisions/revision-X.md` and record the `APPROVED`/`REJECTED` outcome.
+
+## Language policy
+
+All SpecOps operational output (CLI messages, injected assets) is in English.
+Your prose (`spec.md`, `plan.md`, task descriptions) may be in **any language** —
+SpecOps parses only structural tokens (`SC-\d+`, `T\d+`, action suffixes), never
+content.
+
+## Supported Speckit layouts
+
+SpecOps resolves prompt targets at runtime from
+`.specify/integrations/<agent>.manifest.json`. Any Speckit integration with a
+recorded manifest is supported; unknown layouts fail closed. Tested with
+Speckit ≥ 0.12 (Claude skills mode, separator `-`).
+
+## Uninstall
+
+Remove the appended block from each prompt file, then delete `specops.json` and
+the installed review command. No other files are written; the restore is
+byte-identical.
+
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup,
+the quality gates, and project principles. SpecOps is at `0.x`; the CLI surface
+and ledger format may still change before `1.0` (see [CHANGELOG.md](CHANGELOG.md)).
+
+## License
+
+[MIT](LICENSE) © Paulo Segundo

speckit_specops-0.1.0/README.md

@@ -0,0 +1,211 @@
+# SpecOps CLI
+
+[![CI](https://github.com/paulo2nd/specops/actions/workflows/ci.yml/badge.svg)](https://github.com/paulo2nd/specops/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/speckit-specops.svg)](https://pypi.org/project/speckit-specops/)
+[![Python](https://img.shields.io/pypi/pyversions/speckit-specops.svg)](https://pypi.org/project/speckit-specops/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**SpecOps turns [GitHub Speckit](https://github.com/vgrecov/speckit)'s
+spec-driven workflow into an enforced, auditable process.** It layers an
+agent-guided *atomic development* methodology on top of any Speckit repository —
+a physical state ledger, machine-collected evidence, and token-optimized review —
+**without replacing or forking a single Speckit file.**
+
+> Speckit gives your agents great artifacts (spec → plan → tasks → implement).
+> SpecOps makes sure they actually follow them: state is on disk and
+> Git-verifiable, evidence is collected by tooling instead of claimed by the
+> agent, and review rejects as cheaply as possible.
+
+## Why SpecOps?
+
+Spec-driven development with AI agents has three recurring failure modes.
+SpecOps addresses each one:
+
+| Problem | Without SpecOps | With SpecOps |
+|---|---|---|
+| **Agents hallucinate progress** | "Done ✅" with no proof | Every task is closed with machine-collected evidence (test output, commit hashes, diffs) recorded in the ledger |
+| **State lives in the chat** | Lost on context reset; not auditable | State is a physical `status.yaml` ledger, Git-verifiable and recovery-safe |
+| **Reviews are slow and expensive** | Agent reads the whole repo | `/specops-review` rejects cheapest-first (reconcile → lint/test → out-of-plan files) before reading any code |
+
+## What it adds to Speckit
+
+- **📒 Physical state ledger (Repo-as-State).** A structured `status.yaml`
+  tracks phase, tasks, evidence, and review cycles. Mutated only through
+  `specops` commands — never hand-edited, never held in agent memory.
+- **🔬 Automated evidence collection.** `complete-task --auto` runs your test
+  command, harvests commits and diffs, and records them as typed evidence. A
+  task cannot be `DONE` without proof.
+- **🔁 A phase state machine wired into the prompts.** `specops init` injects
+  directives into the specify, plan, tasks, and implement prompts so the ledger
+  is created and phases advance automatically — the human never runs the
+  bookkeeping by hand.
+- **✂️ Token-optimized surgical review.** The installed `/specops-review`
+  command reviews only in-scope files and stops at the first cheap rejection.
+- **📐 Empirical verification & gates.** `specops consistency` and
+  `specops reconcile` are exit-code gates you can drop into CI or agent prompts.
+- **➕ Additive and reversible.** Everything is delivered through
+  marker-delimited blocks. Uninstalling restores your Speckit files
+  byte-for-byte.
+
+## Install
+
+```bash
+pip install speckit-specops
+```
+
+Installs the `specops` command. Requires Python ≥ 3.10 and Git ≥ 2.30. No
+network I/O after install.
+
+## Quick Start
+
+```bash
+# In a Speckit-initialized repository:
+specops init          # inject directives, install /specops-review, create specops.json
+```
+
+That's it. From here you drive Speckit as usual (`/speckit.specify`,
+`/speckit.plan`, `/speckit.tasks`, `/speckit.implement`) and the injected
+directives take care of the ledger and phase transitions. Check state anytime:
+
+```bash
+specops status show
+```
+
+## How it works
+
+SpecOps rides the Speckit lifecycle. Once `specops init` has run, the injected
+directives drive the ledger at each stage seam:
+
+| Speckit stage | What SpecOps does |
+|---|---|
+| **specify** | Marks the repo as SpecOps-managed (informational; no ledger yet) |
+| **plan** | Enforces empirical path verification and the `consistency` gate |
+| **tasks** | Creates the ledger (`status init-spec`), advances the phase to `TASKS`, and requires `[SC-xxx]` coverage tags on every task |
+| **implement** | Opens `IMPLEMENT`, runs the evidence-backed ledger loop, then opens `REVIEW` |
+| **review** | `/specops-review` validates the diff and records `APPROVED` / `REJECTED` |
+
+The phase machine is `SPECIFY → PLAN → TASKS → IMPLEMENT → REVIEW → DONE`.
+If SpecOps is not installed, the Speckit prompts still work standalone — the
+directives degrade to no-ops.
+
+## Command reference
+
+### `specops init [--non-interactive]`
+
+Prepares a Speckit repository in one run: validates (or offers to create) a Git
+repo, detects Speckit, resolves prompt targets from Speckit's integration
+manifests (works with any recorded agent layout — Claude skills, GitHub
+Copilot, etc.), creates/merge-preserves `specops.json`, installs
+`/specops-review`, and injects the directive blocks into the specify, plan,
+tasks, and implement prompts (additive, idempotent, byte-identical restore on
+removal). `--non-interactive` declines all prompts (CI-safe).
+
+> **Speckit upgrade note**: a Speckit upgrade may rewrite prompt files and
+> remove the injected blocks. Just re-run `specops init` to re-inject.
+
+### `specops status show`
+
+Read-only. Prints ledger state: feature, branch, phase, active task, task counts
+(pending / in progress / done / orphaned), and the review-cycle history.
+
+### `specops status init-spec [<name>]`
+
+Creates `<feature_dir>/status.yaml` from the packaged scaffold, syncing task IDs
+from `tasks.md`. Usually run for you by the tasks directive.
+
+### `specops status start-task <task-id>`
+
+Marks the task `IN_PROGRESS` and records `started_commit = HEAD`. Enforces the
+single-active-task rule.
+
+### `specops status complete-task <task-id> [--auto | --evidence "CLASS:summary"]`
+
+Marks the task `DONE` with exactly one evidence source:
+
+- `--auto`: runs `test_command`; on success, harvests `started_commit..HEAD`
+  commits + diff as `TEST_REPORT`/`CODE_DIFF` evidence.
+- `--evidence "CLASS:summary"`: caller-supplied, with `CLASS` in
+  `CLI_LOG | TEST_REPORT | SCREENSHOT_PATH | CODE_DIFF`.
+
+### `specops status transition-phase <phase> [-r APPROVED|REJECTED]`
+
+Advances the phase one step forward. Two transitions require `-r`:
+
+```bash
+specops status transition-phase DONE -r APPROVED      # approved → close the feature
+specops status transition-phase IMPLEMENT -r REJECTED # rejected → send back for rework
+```
+
+Entering `DONE` requires the latest review cycle to be `APPROVED`.
+
+### `specops reconcile`
+
+Read-only gate. Verifies every ledger commit hash is reachable from `HEAD` and
+every `DONE` task has commits and evidence. Exit 1 on any divergence.
+
+```bash
+specops reconcile || exit 1   # preflight before review
+```
+
+### `specops consistency`
+
+Read-only gate. Verifies every `SC-\d+` in the spec has ≥ 1 task with a matching
+`[SC-xxx]` tag, and every `plan.md` path declaration carries a valid action
+suffix (`(create)`/`(modify)`/`(remove)`). Exit 1 on violation.
+
+### `specops --version`
+
+Prints the version and exits. Works anywhere.
+
+## Configuration — `specops.json`
+
+| Key | Purpose | Default |
+|---|---|---|
+| `test_command` | Command run by `complete-task --auto` | `pytest` |
+| `lint_command` | Command referenced by the review prompt | `""` |
+| `skills_dir` | Directory the review prompt loads skills from | `.specify/skills` |
+
+Unknown keys are preserved on re-init.
+
+## The `/specops-review` command
+
+Installed by `specops init` (the name follows the layout's separator, e.g.
+`/specops-review` for Claude skills). Not a CLI command — a packaged prompt that
+drives the review agent cheapest-rejection-first:
+
+1. Load skills from `skills_dir`.
+2. `specops reconcile` — abort immediately on failure.
+3. `lint_command` + `test_command` — reject on failure.
+4. `git status --porcelain` — reject any out-of-plan file without reading code.
+5. Surgical diff review of in-scope files only.
+6. Write `revisions/revision-X.md` and record the `APPROVED`/`REJECTED` outcome.
+
+## Language policy
+
+All SpecOps operational output (CLI messages, injected assets) is in English.
+Your prose (`spec.md`, `plan.md`, task descriptions) may be in **any language** —
+SpecOps parses only structural tokens (`SC-\d+`, `T\d+`, action suffixes), never
+content.
+
+## Supported Speckit layouts
+
+SpecOps resolves prompt targets at runtime from
+`.specify/integrations/<agent>.manifest.json`. Any Speckit integration with a
+recorded manifest is supported; unknown layouts fail closed. Tested with
+Speckit ≥ 0.12 (Claude skills mode, separator `-`).
+
+## Uninstall
+
+Remove the appended block from each prompt file, then delete `specops.json` and
+the installed review command. No other files are written; the restore is
+byte-identical.
+
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup,
+the quality gates, and project principles. SpecOps is at `0.x`; the CLI surface
+and ledger format may still change before `1.0` (see [CHANGELOG.md](CHANGELOG.md)).
+
+## License
+
+[MIT](LICENSE) © Paulo Segundo

speckit_specops-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "speckit-specops"
+version = "0.1.0"
+description = "A Spec-Driven Development (SDD) process enforcement CLI extending Speckit"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Paulo Segundo", email = "paulosegundo@gmail.com" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "typer>=0.9.0",
+    "pyyaml>=6.0",
+    "gitpython>=3.1.40",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.4.0",
+    "mypy>=1.10.0",
+    "pytest-cov>=5.0",
+    "types-PyYAML>=6.0",
+]
+
+[project.scripts]
+specops = "specops.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/specops"]
+
+[tool.hatch.build]
+include = [
+    "src/specops/**",
+]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]
+ignore = []
+
+[tool.mypy]
+python_version = "3.10"
+disallow_untyped_defs = true
+warn_unused_ignores = true
+check_untyped_defs = true
+exclude = ["tests/"]
+
+[[tool.mypy.overrides]]
+module = "git.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+addopts = "--cov=specops --cov-report=term-missing --cov-fail-under=85"
+testpaths = ["tests"]

speckit_specops-0.1.0/src/specops/__init__.py

@@ -0,0 +1,6 @@
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("specops-cli")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0.dev0"