specwarden 0.1.0__tar.gz

specwarden-0.1.0/.claude/skills/specwarden/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: specwarden
+description: Use when starting any non-trivial code change in this repo — refuses Edit/Write until a one-page spec is written; logs every accepted edit with a backlink. Activates on `/spec`, `/trace`, `/coverage`, `/spec-help`.
+---
+
+# specwarden
+
+> Every code change traces back to a written spec. Enforced by hooks, not vibes.
+
+## What this does
+
+specwarden enforces a spec-first discipline: before any Edit or Write tool call lands, a structured one-page spec must exist and be marked ready. The PreToolUse hook reads `.claude/specs/active` on every tool call; if no spec is active, the hook blocks the call and tells you why. This makes the discipline mechanical rather than voluntary.
+
+Once a spec is active, every edit is logged to `.claude/decisions/<spec-id>.md` with a timestamp and a reference back to the spec. When you commit, a `Spec: <id>` trailer is appended automatically (requires `specwarden git-hook install`). The result is a chain you can walk in either direction: from a commit to its spec, or from a spec to every file it touched.
+
+## Slash commands
+
+### `/spec <slug>`
+
+Creates a new spec file at `.claude/specs/<slug>.md` from the four-section template and writes the slug to `.claude/specs/active`. Until all four sections are filled in and you type `ready`, the PreToolUse hook blocks any Edit or Write call with a message indicating which sections are still empty.
+
+### `/trace [<commit>]`
+
+Prints the full chain for a given commit: commit SHA, the `Spec:` trailer, the spec file, and the corresponding decisions log. Defaults to HEAD when no commit is specified.
+
+### `/coverage [--last N]`
+
+Scans recent commits (all commits, or the last N if `--last N` is given) and reports how many carry a `Spec:` trailer. Output format: `covered/total commits have spec coverage (pct%)`, followed by a list of uncovered SHAs.
+
+### `/spec-help`
+
+Prints a one-page quick-reference card: the four slash commands, the spec template, the quick-fix escape hatch, and the path layout.
+
+## The four-section spec template
+
+```markdown
+# <Spec ID>: <Short Title>
+
+**Created:** <ISO timestamp>
+**Status:** active | completed | abandoned
+**Author:** <human name>
+
+## Assumptions
+What we are taking as given. If any of these turns out to be false, the spec is
+invalid and must be revised before more code lands.
+
+- Assumption 1
+- Assumption 2
+
+## Scope
+What this change is. Concrete, files-and-functions level if possible.
+
+- We will modify X
+- We will add Y
+- We will not touch Z
+
+## Non-goals
+What this change is explicitly not. The point of this section is to prevent
+scope creep mid-implementation.
+
+- We will not refactor adjacent module M
+- We will not change the public API of P
+
+## Success criteria
+How we will know we are done. Must be checkable.
+
+- [ ] Test T passes
+- [ ] Manual scenario S works
+- [ ] Documentation D is updated
+```
+
+## The discipline
+
+1. User describes a feature or fix.
+2. You invoke `/spec <slug>` and fill in all four sections in conversation. Push back on vague assumptions, surface trade-offs, propose non-goals to prevent scope creep.
+3. User reviews the spec and types `ready`.
+4. You proceed to edit. Each edit is appended to `.claude/decisions/<spec-id>.md` with a timestamp.
+5. When the work is done, run `specwarden done` from the terminal (or call the `mark_done` helper) to flip the spec status to `completed`.
+6. Commits made while the spec is active automatically carry a `Spec: <id>` trailer if `specwarden git-hook install` was run beforehand.
+
+The spec is not a bureaucratic artifact — it is the conversation record that prevents you and the human from talking past each other mid-implementation. Write it as if someone will read it six months from now to understand why a particular decision was made.
+
+## Quick-fix mode
+
+For edits where a full spec is genuine overhead — typo fixes, dependency version bumps, comment rewording — set `SPECWARDEN_QUICKFIX=1` in the environment before invoking Claude Code. The PreToolUse hook will allow Edit and Write calls without an active spec. The decisions log will not capture the edit. Use sparingly; the coverage report will mark these commits as uncovered.
+
+## Hook contract version
+
+This skill targets the Claude Code hook contract published in 2026-Q1:
+
+- `PreToolUse` returns `{"permissionDecision": "allow" | "deny" | "ask", "message": "..."}` over stdout.
+- `PostToolUse` returns nothing (exit 0); side effects happen on disk.
+- `SessionStart` writes a banner to stdout.
+
+If the hook contract changes in a later Claude Code release, this skill must be updated to match. The CI workflow at `.github/workflows/ci.yml` runs a weekly job that exercises the hook contract against the latest published Claude Code release to catch drift early.
+
+## Files this skill writes
+
+- `.claude/specs/<spec-id>.md` — the spec document, created by `/spec` or `specwarden new`.
+- `.claude/specs/active` — single line containing the currently active spec ID; read by the PreToolUse hook on every tool call.
+- `.claude/decisions/<spec-id>.md` — append-only log of every edit authorized under the spec.
+- `.claude/settings.json` — hook wiring; created once by `specwarden init` and not modified again by the skill.
+
+## Out of scope for v1
+
+The skill does not generate specs on behalf of the user. The human writes the spec; that is the forcing function. Auto-generated specs would remove the discipline the tool is designed to create. This is recorded in the project's own SPEC under "Non-goals" for v1.

specwarden-0.1.0/.claude/skills/specwarden/scripts/activate_spec.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+"""Slash command shim for activating a spec — delegates to `specwarden activate`."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 1:
+        print("usage: activate_spec <spec-id>", file=sys.stderr)
+        return 2
+    return subprocess.call(["specwarden", "activate", argv[0]])
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

specwarden-0.1.0/.claude/skills/specwarden/scripts/coverage.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+"""Slash command shim for /coverage — delegates to `specwarden coverage`."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+
+def main(argv: list[str]) -> int:
+    return subprocess.call(["specwarden", "coverage", *argv])
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

specwarden-0.1.0/.claude/skills/specwarden/scripts/new_spec.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+"""Slash command shim for /spec — delegates to `specwarden new`."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 1:
+        print("usage: /spec <slug>", file=sys.stderr)
+        return 2
+    title = " ".join(argv)
+    return subprocess.call(["specwarden", "new", title, "--author", "claude"])
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

specwarden-0.1.0/.claude/skills/specwarden/scripts/trace.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+"""Slash command shim for /trace — delegates to `specwarden trace`."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+
+def main(argv: list[str]) -> int:
+    args = argv if argv else ["HEAD"]
+    return subprocess.call(["specwarden", "trace", *args])
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

specwarden-0.1.0/.claude/skills/specwarden/templates/decision_entry.md.template

@@ -0,0 +1,5 @@
+## {iso_timestamp}
+- File: {file_path}
+- Lines: {line_range}
+- Summary: {summary}
+- Tool: {tool}

specwarden-0.1.0/.claude/skills/specwarden/templates/spec.md.template

@@ -0,0 +1,25 @@
+# {spec_id}: {title}
+
+**Created:** {created}
+**Status:** active
+**Author:** {author}
+
+## Assumptions
+What we are taking as given. If any of these turns out to be false, the spec is invalid and must be revised before more code lands.
+
+- TODO
+
+## Scope
+What this change is. Concrete, files-and-functions level if possible.
+
+- TODO
+
+## Non-goals
+What this change is explicitly not. The point of this section is to prevent scope creep mid-implementation.
+
+- TODO
+
+## Success criteria
+How we will know we are done. Must be checkable.
+
+- [ ] TODO

specwarden-0.1.0/.claude/specs/2026-05-28_v1-audit-nits-cli-wrapper-tests-and-caveman-cleanup.md

@@ -0,0 +1,91 @@
+# 2026-05-28_v1-audit-nits-cli-wrapper-tests-and-caveman-cleanup: v1 audit nits CLI wrapper tests and Caveman cleanup
+
+**Created:** 2026-05-28T18:44:06+00:00
+**Status:** completed
+**Author:** Amey Ambade
+
+## Assumptions
+
+- `.claude/internal/V1_AUDIT.md` is still the authoritative pre-launch
+  audit. It flags exactly two non-blocking nits:
+  (a) `coverage` and `trace` CLI wrappers in `src/specwarden/cli.py`
+  lack direct CLI-layer tests (existing coverage is module-level);
+  (b) the Caveman section in `docs/COMPARISONS.md` was written from
+  the SPEC's secondhand reference, not from the Caveman repo.
+- The current test suite is 63 passing under
+  `PYTHONPATH=src .venv/bin/python -m pytest -q`. Adding tests must
+  keep that count monotonic and the ruff check clean.
+- The Python 3.14 / hatchling editable-install `.pth` quirk is a
+  separate, pre-existing issue (documented in WORKLOG and
+  NEXT_SESSION). Not in scope here; CLI invocation uses the
+  documented `PYTHONPATH=src python -m specwarden.cli` fallback.
+
+## Scope
+
+- `tests/test_cli.py`: add two new tests at the bottom of the file,
+  next to the existing CliRunner tests.
+  - `test_coverage_reports_against_real_commits` — initializes a
+    real git repo under `tmp_path`, makes two commits (one with a
+    `Spec: <id>` trailer, one without), invokes
+    `app, ["coverage", "--last", "10", "--root", str(tmp_path)]`,
+    asserts exit code 0 and that stdout contains the
+    `"N/M commits have spec coverage"` line plus the uncovered SHA
+    prefix.
+  - `test_trace_with_active_spec_succeeds` — initializes a real git
+    repo, runs `specwarden init` + `new` + `activate` via the CLI to
+    produce a real spec file, writes a decisions-log entry for that
+    spec, makes a commit whose message body carries
+    `Spec: <spec-id>`, invokes
+    `app, ["trace", "HEAD", "--root", str(tmp_path)]`, asserts exit
+    code 0 and that stdout contains the spec id and the `---`
+    separators emitted by `trace_commit`.
+- `docs/COMPARISONS.md`: rewrite only the Caveman section
+  (`## Caveman` through the section break before
+  `## Summary table`). Replace specific reception claims ("5K+ stars
+  quickly", "10K upvotes on r/ClaudeAI") with neutral structural
+  language. Keep the "what shares" / "what differs" / "when to use
+  both" subsection structure. Update the Summary-table row for
+  Caveman only if a column claim no longer holds; if it still holds
+  structurally, leave the row alone.
+- `.claude/internal/V1_AUDIT.md`: tick both nits closed in the
+  "Remaining work" column for DoD #1 row and in the post-launch
+  notes if present.
+- `.claude/internal/WORKLOG.md`: append a single new entry
+  documenting the change and the spec ID.
+- One commit, conventional-commit format
+  (`test(cli): ...` or `chore: close v1 audit nits ...`), with a
+  `Spec: 2026-05-28_v1-audit-nits-cli-wrapper-tests-and-caveman-cleanup`
+  trailer in the body.
+
+## Non-goals
+
+- Not fixing the Python 3.14 / hatchling editable-install `.pth`
+  quirk. That is a separate issue and deserves its own spec.
+- Not adding tests for any command other than `coverage` and
+  `trace`. The audit named exactly those two.
+- Not running the Caveman repo through a fact-finding fetch.
+  The user explicitly chose "Replace the secondhand claims with
+  neutral language" over the verify-and-correct option.
+- Not changing the comparison structure or summary table for
+  GitHub Spec Kit, CLAUDE.md, Cursor, or MCP. Only the Caveman
+  section is in scope.
+- Not bumping the package version. This is launch-prep polish, not
+  a release.
+
+## Success criteria
+
+- [ ] `PYTHONPATH=src .venv/bin/python -m pytest -q` reports
+      65 passed (was 63).
+- [ ] `uv run ruff check .` is clean.
+- [ ] `uv run ruff format --check .` is clean.
+- [ ] `docs/COMPARISONS.md` Caveman section contains no specific
+      star count or upvote claim. The "what shares" / "what
+      differs" framing remains intact.
+- [ ] `.claude/internal/V1_AUDIT.md` shows both nits resolved.
+- [ ] One git commit lands with the `Spec:` trailer pointing at
+      this spec id. `git log -1 --format=%B | grep -F 'Spec: 2026-05-28_v1-audit-nits-cli-wrapper-tests-and-caveman-cleanup'`
+      returns a match.
+- [ ] Spec marked done via
+      `python -m specwarden.cli done --root .` after the commit
+      lands. `.claude/specs/active` removed; the spec file's
+      status frontmatter reads `completed`.

specwarden-0.1.0/.env.eval.example

@@ -0,0 +1,11 @@
+# Copy this file to .env.eval and fill in your key.
+# .env.eval is gitignored via the .env.* rule in .gitignore.
+#
+# Required for `python evals/run_eval.py` when invoking `claude --bare`,
+# which strips OAuth/keychain auth and reads only ANTHROPIC_API_KEY.
+#
+# Get a key at https://console.anthropic.com/settings/keys.
+# Billing for the eval run hits your Anthropic API account, not your
+# Claude Code subscription.
+
+ANTHROPIC_API_KEY=sk-ant-your-key-here

specwarden-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+      - run: pip install -e '.[dev]'
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: pytest --cov=specwarden --cov-report=term-missing

specwarden-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,61 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "[0-9]+.[0-9]+.[0-9]+"
+      - "[0-9]+.[0-9]+.[0-9]+rc[0-9]+"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+      - run: pip install -e '.[dev]'
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: pytest --cov=specwarden --cov-report=term-missing
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          # Trusted Publisher: no `password` field needed.
+          # PyPI verifies the OIDC token from GitHub against the
+          # publisher config at https://pypi.org/manage/account/publishing/

specwarden-0.1.0/.gitignore

@@ -0,0 +1,70 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtualenvs
+.venv/
+venv/
+env/
+ENV/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.tox/
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*~
+
+# Internal tracking — not part of the published artifact
+.claude/internal/
+
+# OMC state
+.omc/
+
+# Claude Code local settings (per-machine permission cache)
+.claude/settings.local.json
+
+# uv lockfile (project uses pip via pyproject.toml; uv lockfile is generated by side-tooling)
+uv.lock
+
+# Eval artifacts that should not be committed wholesale
+evals/results/_local/
+evals/.cache/
+
+# Local secrets
+.env
+.env.*
+!.env.example
+!.env.*.example
+
+# Launch-prep notes (personal; not part of public repo)
+.claude/GIF_RECORDING.md
+.claude/launch.md
+.claude/medium-post.md

specwarden-0.1.0/CLAUDE.md

@@ -0,0 +1,103 @@
+# specwarden — working notes
+
+This file is the standing context for anyone (human or agent) working on this repo.
+Read it before touching code. Update it when conventions change.
+
+## What we are building
+
+`specwarden` is a Claude Code skill plus a set of lifecycle hooks that gate
+filesystem edits behind a written spec. It also ships a Python CLI and an
+eval suite. The full requirements live in `SPEC_specwarden.md` at the repo
+root — that file is the single source of truth for v1 scope.
+
+If anything here drifts from `SPEC_specwarden.md`, the SPEC wins.
+
+## Working directories
+
+| Path | Purpose |
+| --- | --- |
+| `SPEC_specwarden.md` | Authoritative spec for v1. Treat as read-only unless the user changes scope. |
+| `docs/superpowers/plans/` | Implementation plan(s). The active one is `2026-05-07-specwarden-v1.md`. |
+| `.claude/skills/specwarden/` | The published skill artifact (SKILL.md, scripts, templates). Ships with the package. |
+| `.claude/internal/` | Tracking notes for this build. Gitignored. Worklog, project context, feature specs go here. |
+| `src/specwarden/` | Python CLI package. `pipx install specwarden` installs the entry point. |
+| `hooks/` | Standalone hook scripts copied into the user repo by `specwarden init`. |
+| `evals/` | Three-arm benchmark. Fixtures, runner, results. |
+| `examples/` | Reference projects that show specwarden in use. |
+| `docs/` | Public-facing markdown docs. |
+
+## Conventions
+
+- Python 3.10+. Use `from __future__ import annotations` and standard library
+  where possible. Third-party deps: `typer`, `pytest`. Add more only with a
+  reason recorded in the plan.
+- Tests live next to code under `tests/<module>/test_<thing>.py`. Use `pytest`,
+  not `unittest`. Aim for one assertion per test where practical.
+- Format with `ruff format`. Lint with `ruff check`. Both run in CI.
+- Markdown is written for engineers reading on a laptop. No marketing tone,
+  no superlatives, no AI tells. Headings are sentence case.
+- Commits follow Conventional Commits (`feat:`, `fix:`, `docs:`, `test:`,
+  `chore:`, `refactor:`). Subject under 72 chars. No emoji in commits or docs.
+  Do not tag releases with a `v` prefix.
+- Every commit that lands real code should carry a `Spec: <spec-id>` trailer.
+  The CLI is responsible for keeping that easy.
+- Keep files small and focused. Split when one file owns more than one job.
+
+## Spec → decisions → commit chain
+
+This is the discipline the project itself tries to enforce, so we eat our own
+dog food while building it:
+
+1. Before touching code for a new chunk of work, write a spec under
+   `.claude/specs/` (use the four-section template once it exists).
+2. Set the active spec in `.claude/specs/active`.
+3. Make changes. Each edit gets logged to `.claude/decisions/<spec-id>.md`.
+4. Commit with a `Spec: <spec-id>` trailer.
+
+For the bootstrap phase we may write specs by hand because the tooling does
+not exist yet. Once the CLI lands (Phase 1 complete), switch to the tooling.
+
+## How to run things
+
+```bash
+# Install the package in editable mode for local work
+pipx install -e .
+
+# Run tests
+pytest
+
+# Lint and format
+ruff check .
+ruff format .
+
+# Run the eval (slow, costs API tokens)
+make eval
+```
+
+Until `pyproject.toml` is in place, only the planning files exist. See the
+implementation plan for the bootstrap order.
+
+## Things to watch out for
+
+- The Claude Code hook contract (JSON shape, `permissionDecision` values) is
+  the integration surface with the host tool. Pin the hook version we target
+  in `SKILL.md` and add a CI test that exercises it.
+- The `.claude/specs/active` file is the synchronization point between hooks
+  and the CLI. Treat it as a single line, no trailing whitespace, no BOM.
+- The eval suite uses `claude` headless mode. Document the exact CLI flags
+  used so the benchmark is reproducible.
+- Do not auto-generate specs. The whole product loses its meaning if specs
+  are produced by the same agent the spec is supposed to constrain.
+
+## Out of scope (do not build)
+
+See the SPEC's "Non-goals" section. Short list: no web UI, no Jira-style
+project management, no team features, no AI-generated specs, no external
+tracker integrations, no per-language templates.
+
+## Where to write progress
+
+- Plan progress: tick boxes in `docs/superpowers/plans/2026-05-07-specwarden-v1.md`.
+- Session log: `.claude/internal/WORKLOG.md` (append at end of each session).
+- Cross-session state: `.claude/internal/PROJECT_CONTEXT.md`.
+- Per-feature notes: `.claude/internal/FEATURE_SPECS.md`.

specwarden-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amey Ambade
+
+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.

specwarden-0.1.0/Makefile

@@ -0,0 +1,18 @@
+.PHONY: test lint fmt eval install-dev
+
+install-dev:
+	pip install -e '.[dev]'
+
+test:
+	pytest
+
+lint:
+	ruff check .
+	ruff format --check .
+
+fmt:
+	ruff check --fix .
+	ruff format .
+
+eval:
+	python evals/run_eval.py