ai-playbook 1.0.0__tar.gz

ai_playbook-1.0.0/.ai-playbook.toml

@@ -0,0 +1,10 @@
+# AI Playbook adopter configuration.
+# Full reference: docs/cli-reference.md (deployed with the playbook).
+# Every key is optional — an empty file means a core-only deploy.
+
+# Adopter-local packs, deployed in declared order (last pack wins on collisions):
+# packs = [".ai-playbook/packs/<name>"]
+
+# Per-agent quality tier overrides ("production" or "prototype"):
+# [quality_tiers.agents]
+# docs-maintainer = "prototype"

ai_playbook-1.0.0/.deprecations.toml

@@ -0,0 +1,37 @@
+# Active deprecation registry — single source of truth for the deprecation
+# cycle defined in `docs/deprecation-policy.md`. Every entry in
+# `CHANGELOG.md § Deprecated` for a released version must have a row here
+# with the same id; pre-release activity may live only in `## [Unreleased]`
+# until the version ships.
+#
+# Schema:
+#   id                — kebab-case identifier (the deprecated surface).
+#   surface           — one of: cli-flag | cli-command | agent-id |
+#                       config-key | kb-path | deployment-layout | skill-op.
+#   added_version     — when the deprecation marker was added (X.Y.Z).
+#   removal_version   — the MAJOR release that removes it (X.0.0).
+#   reason            — one short sentence; the *why*, not the *what*.
+#   replacement       — id or path of the replacement surface, or "(removed)"
+#                       when the deprecated surface has no successor.
+#   status            — active | grace | removed (informational; the
+#                       contract test is driven by version comparisons).
+#
+# When a removal version ships, delete the row (do NOT keep historical
+# entries here — git history is the audit trail). When a deprecation is
+# rescinded, delete the row and note the rationale in CHANGELOG.md §
+# Changed for that release.
+#
+# Validated by `tests/acceptance/test_deprecations.py` — keep in sync with
+# `CHANGELOG.md § Deprecated` for the latest released section.
+
+# No active deprecations.
+# Example (do not uncomment — kept here as schema documentation):
+#
+# [[deprecations]]
+# id = "release-captain"
+# surface = "agent-id"
+# added_version = "1.5.0"
+# removal_version = "2.0.0"
+# reason = "Renamed to release-engineer to match the broader scope it actually owns."
+# replacement = "release-engineer"
+# status = "active"

ai_playbook-1.0.0/.github/CODEOWNERS

@@ -0,0 +1,3 @@
+# Default owner for everything in this repo.
+# Required reviewer when branch protection enforces Code Owner review.
+* @meenumathew

ai_playbook-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug Report
+about: Report a problem with the CLI, agents, or knowledge base
+title: ""
+labels: bug
+assignees: ""
+---
+
+## Describe the bug
+
+A clear description of what the problem is.
+
+## To reproduce
+
+1. Run `ai-playbook ...`
+2. Use agent `...`
+3. See error
+
+## Expected behavior
+
+What you expected to happen.
+
+## Environment
+
+- OS: [e.g. macOS 15, Ubuntu 24.04]
+- Python version: [e.g. 3.12.4]
+- AI tool: [e.g. Claude Code, Copilot, Kiro]
+- ai-playbook version: [e.g. 0.1.0]
+
+## Additional context
+
+Paste relevant error output, agent responses, or screenshots.

ai_playbook-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+What problem does this solve? What's the current limitation?
+
+## Proposed solution
+
+Describe what you'd like to happen.
+
+## Alternatives considered
+
+What other approaches did you consider?
+
+## Additional context
+
+Any examples, screenshots, or references that help explain the request.

ai_playbook-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+## Summary
+
+<!-- What changed and why? Keep it brief: 1-3 bullet points. -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation update
+- [ ] Agent behavior change
+- [ ] Knowledge base update
+- [ ] CLI change
+
+## Checklist
+
+- [ ] Tests pass (`uv run pytest tests/ -v`)
+- [ ] Lint clean (`uv run ruff check src/ tests/ evals/`)
+- [ ] Format clean (`uv run ruff format --check src/ tests/ evals/`)
+- [ ] Type check passes (`uv run pyright`)
+- [ ] Eval structure valid (`uv run python evals/run_eval.py check-structure`)
+- [ ] Updated evals if agent behavior changed
+- [ ] Updated docs if user-facing behavior changed
+
+## Test plan
+
+<!-- How can a reviewer verify this works? -->

ai_playbook-1.0.0/.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns:
+          - "*"
+    commit-message:
+      prefix: chore
+      include: scope
+
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: chore
+      include: scope

ai_playbook-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,217 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docs-quality:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+        with:
+          enable-cache: true
+
+      - name: Install Vale
+        run: |
+          set -euo pipefail
+          mkdir -p "$RUNNER_TEMP/bin"
+          GOBIN="$RUNNER_TEMP/bin" go install github.com/errata-ai/vale/v3/cmd/vale@v3.9.6
+          echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
+
+      - name: Documentation lint
+        run: make docs-lint
+
+  validate:
+    # Matrix scope is event-aware to keep push CI fast without losing coverage:
+    #   - pull_request OR push to main    → full matrix (2 OS × 3 Python = 6 jobs)
+    #   - push to a feature branch        → ubuntu × py3.12 only (1 job)
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 35
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ${{ fromJSON((github.event_name == 'pull_request' || github.ref == 'refs/heads/main') && '["ubuntu-latest", "macos-latest"]' || '["ubuntu-latest"]') }}
+        python-version: ${{ fromJSON((github.event_name == 'pull_request' || github.ref == 'refs/heads/main') && '["3.12", "3.13", "3.14"]' || '["3.12"]') }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Format check
+        run: make format-check
+
+      - name: Lint
+        run: make lint
+
+      - name: ShellCheck harness scripts
+        run: uvx pre-commit==4.3.0 run shellcheck --all-files
+
+      - name: Lint GitHub workflows (actionlint)
+        # OS/Python-independent — run once, not across the matrix.
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        run: uvx pre-commit==4.3.0 run actionlint --all-files
+
+      - name: Type check
+        run: make typecheck
+
+      - name: Run tests with coverage
+        # Direct invocation (not `make test`): Codecov needs --cov-report=xml,
+        # which the local target intentionally omits.
+        run: uv run pytest -q --cov=src --cov-report=xml --cov-fail-under=95
+
+      - name: Upload coverage to Codecov
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+
+      - name: Architecture enforcement
+        run: uv run pytest tests/unit/test_architecture.py -v
+
+      - name: Size budget — CLAUDE.md
+        run: make claude-md-size
+
+      - name: Size budget — agent files
+        run: make agent-size
+
+      - name: KB frontmatter contract
+        # OS/Python-independent content check — run once, not across the matrix.
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        run: make kb-frontmatter
+
+      - name: Check eval structure
+        run: make eval-structure
+
+      - name: Calibrate structural evals
+        run: make eval-calibrate
+
+      - name: Validate eval samples
+        run: make eval-validate
+
+      - name: Secret scan
+        run: |
+          # Mirrors the shipped local hook coverage so contributors cannot
+          # bypass secret scanning by skipping local pre-commit installation.
+          uvx pre-commit==4.3.0 run detect-private-key --all-files
+          uvx pre-commit==4.3.0 run gitleaks --all-files
+
+      - name: Dependency vulnerability scan
+        run: |
+          # Backs the security.md § Dependencies & Supply Chain claim that
+          # dependency scanning runs in CI. `--strict` fails the run on any
+          # known-vulnerable dependency. `pip-audit` is pinned (same rule as
+          # Actions): a floating `uvx pip-audit` would let upstream changes
+          # silently alter the build's security posture.
+          uv export --no-hashes --no-dev --no-emit-project > /tmp/runtime-requirements.txt
+          uvx pip-audit==2.10.0 --strict --requirement /tmp/runtime-requirements.txt
+
+      - name: Static security scan (Bandit)
+        run: |
+          # Bandit catches Python-specific security smells: hardcoded
+          # passwords, weak crypto, unsafe `subprocess`/`eval`, `assert` in
+          # production paths, etc. Severity floor is medium; confidence
+          # floor is medium to avoid noise from style-level findings.
+          #
+          # `src/` is scanned strictly. `tests/` and `evals/` are scanned
+          # with B101 (assert_used) skipped — pytest depends on `assert`,
+          # so flagging it would be noise; everything else still applies.
+          uvx bandit==1.9.4 -r src/ -ll -ii
+          uvx bandit==1.9.4 -r tests/ evals/ -ll -ii --skip B101
+
+      - name: Smoke-test console script (source)
+        run: |
+          set -euo pipefail
+          uv run ai-playbook list >/dev/null
+          for tool in claude copilot cursor kiro; do
+            tmpdir="$(mktemp -d)"
+            uv run ai-playbook deploy --agent all --tool "$tool" -t "$tmpdir" --no-mcp >/dev/null
+          done
+
+      - name: Build wheel and smoke-test installed artifact
+        run: |
+          set -euo pipefail
+          uv build
+          uvx twine==6.2.0 check dist/*
+          # Install the built wheel into a clean venv so we exercise what users get.
+          venv="$(mktemp -d)/venv"
+          uv venv "$venv"
+          # shellcheck disable=SC1091
+          source "$venv/bin/activate"
+          uv pip install dist/*.whl
+          ai-playbook list >/dev/null
+          for tool in claude copilot cursor kiro; do
+            tmpdir="$(mktemp -d)"
+            ai-playbook deploy --agent all --tool "$tool" -t "$tmpdir" --no-mcp >/dev/null
+            ai-playbook doctor --tool "$tool" -t "$tmpdir" >/dev/null
+          done
+          deactivate
+
+  commit-hygiene:
+    # Teach-back / Conventional Commit trailer is enforced locally by the
+    # `commit-msg` hook (harness/check-teachback.sh). GitHub does not run
+    # commit-msg hooks, so this job backstops it: a contributor who skips hook
+    # install or commits with `--no-verify` cannot land non-trivial commits
+    # without the trailer. PR-only — main's pre-re-init history is squashed and
+    # exempt (see CONTRIBUTING.md § Git History).
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout (full history for the PR range)
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Teach-back trailer on PR commits
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          set -euo pipefail
+          # Reuse the exact script the local commit-msg hook runs, so CI and
+          # local stay in lockstep. Validate every non-merge commit the PR adds;
+          # merge commits carry no Conventional Commit subject and are skipped.
+          fail=0
+          for sha in $(git rev-list --no-merges "${BASE_SHA}..${HEAD_SHA}"); do
+            msg="$(mktemp)"
+            git log -1 --format=%B "$sha" > "$msg"
+            if ! harness/check-teachback.sh "$msg"; then
+              echo "::error::commit ${sha} failed the Teach-back / Conventional Commit check"
+              fail=1
+            fi
+          done
+          exit "$fail"

ai_playbook-1.0.0/.github/workflows/codeql.yml

@@ -0,0 +1,48 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * 1"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: codeql-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      security-events: write
+      packages: read
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [python, actions]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@458d36d7d4f47d0dd16ca424c1d3cda0060f1360 # v3
+        with:
+          languages: ${{ matrix.language }}
+          queries: security-and-quality
+
+      - name: Perform CodeQL analysis
+        uses: github/codeql-action/analyze@458d36d7d4f47d0dd16ca424c1d3cda0060f1360 # v3
+        with:
+          category: /language:${{ matrix.language }}

ai_playbook-1.0.0/.github/workflows/eval-drift.yml

@@ -0,0 +1,137 @@
+name: Eval drift
+
+on:
+  # Opt-in only. This job calls the Anthropic API (billable, needs the
+  # ANTHROPIC_API_KEY secret), so it does not run on a schedule by default —
+  # trigger it manually from the Actions tab when you want a drift check.
+  # To restore automatic weekly runs, uncomment the schedule below once a key
+  # is configured.
+  workflow_dispatch:
+  # schedule:
+  #   - cron: "0 6 * * 1"   # Mondays 06:00 UTC — semantic drift detection
+
+permissions:
+  contents: read
+
+concurrency:
+  group: eval-drift-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  judge:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Dependency vulnerability scan
+        run: |
+          # The push/PR validation suite does not run pip-audit; this opt-in
+          # job does, so a manual drift run also surfaces any vulnerable dep
+          # that has landed on main since the last release.
+          uv export --no-hashes --no-dev --no-emit-project > /tmp/runtime-requirements.txt
+          uvx pip-audit==2.10.0 --strict --requirement /tmp/runtime-requirements.txt
+
+      - name: Check committed baselines
+        run: uv run python evals/run_eval.py validate-samples
+
+      - name: Check for ANTHROPIC_API_KEY
+        id: secret
+        run: |
+          # Detect-only — do NOT inject the secret into env here. The judge
+          # step below is the single point that touches ANTHROPIC_API_KEY,
+          # narrowing the surface that matters for secret-exfil review.
+          if [ -z "${HAS_KEY}" ]; then
+            echo "available=false" >> "$GITHUB_OUTPUT"
+            echo "::error::ANTHROPIC_API_KEY secret not set — eval-drift cannot run the semantic judge."
+            exit 1
+          else
+            echo "available=true" >> "$GITHUB_OUTPUT"
+          fi
+        env:
+          HAS_KEY: ${{ secrets.ANTHROPIC_API_KEY != '' && '1' || '' }}
+
+      - name: Run LLM judge on committed baselines
+        if: steps.secret.outputs.available == 'true'
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          # Iterate samples but skip README.md — the README documents the
+          # convention; only files named `<agent>.md` are baselines, and each
+          # must match an `evals/<agent>-expected.md` rubric.
+          samples=()
+          for path in evals/samples/*.md; do
+            [ "$(basename "$path")" = "README.md" ] && continue
+            samples+=("$path")
+          done
+          fail=0
+          mkdir -p judge-output
+          for sample in "${samples[@]}"; do
+            agent="$(basename "$sample" .md)"
+            echo "::group::judge $agent"
+            # Tee per-agent verdicts to files so the artifact upload below
+            # makes drift trendable across runs instead of buried in
+            # job logs. pipefail (set above) preserves the judge exit code.
+            if ! uv run python evals/run_eval.py judge "$agent" "$sample" 2>&1 \
+                | tee "judge-output/${agent}.txt"; then
+              fail=1
+            fi
+            echo "::endgroup::"
+          done
+          # Adversarial baselines (curated hostile-input handling) must
+          # PASS the judge, exactly like the standard baselines above.
+          for sample in evals/samples/adversarial/*.md; do
+            name="$(basename "$sample" .md)"
+            [ "$name" = "README" ] && continue
+            echo "::group::judge $name (adversarial)"
+            if ! uv run python evals/run_eval.py judge "$name" "$sample" 2>&1 \
+                | tee "judge-output/${name}.txt"; then
+              fail=1
+            fi
+            echo "::endgroup::"
+          done
+          # Negative controls are deliberately-flawed outputs: the judge
+          # must FAIL them. A pass here means the judge has gone lenient
+          # (or the rubric eroded) — the one drift direction the positive
+          # baselines above cannot detect. Exit code is inverted.
+          for sample in evals/samples/negative/*.md; do
+            name="$(basename "$sample" .md)"
+            [ "$name" = "README" ] && continue
+            echo "::group::judge $name (negative control — must fail)"
+            if uv run python evals/run_eval.py judge "$name" "$sample" 2>&1 \
+                | tee "judge-output/negative-${name}.txt"; then
+              echo "::error::negative control '${name}' PASSED the judge — leniency drift or rubric erosion; investigate before trusting this week's green verdicts"
+              fail=1
+            fi
+            echo "::endgroup::"
+          done
+          exit "$fail"
+
+      - name: Upload judge verdicts
+        if: always() && steps.secret.outputs.available == 'true'
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: judge-verdicts-${{ github.run_id }}
+          path: judge-output/
+          retention-days: 90
+          if-no-files-found: ignore

ai_playbook-1.0.0/.github/workflows/link-check.yml

@@ -0,0 +1,33 @@
+# Weekly external link check.
+#
+# The pre-commit lychee hook runs `--offline` (internal cross-references only)
+# so commits stay fast and network-independent. Nothing else validates the
+# external URLs in docs, so dead links rot silently. This workflow runs the
+# same config online once a week; a failure shows up as a red scheduled run
+# for maintainers to triage. Non-blocking by design — it gates no PR.
+
+name: Link check (external)
+
+on:
+  schedule:
+    - cron: "0 6 * * 1" # Mondays 06:00 UTC, alongside the other weekly scans
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  linkcheck:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+
+      - name: Check external links
+        uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2.8.0
+        with:
+          args: --config .lychee.toml --no-progress './**/*.md'

ai_playbook-1.0.0/.github/workflows/mutation.yml

@@ -0,0 +1,63 @@
+name: Mutation testing
+
+on:
+  pull_request:
+    paths:
+      - "src/deploy_ai_playbook/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - "mutation-baseline.json"
+      - "tools/check-mutation-baseline.py"
+      - ".github/workflows/mutation.yml"
+  schedule:
+    # Mondays 07:00 UTC. Runs after eval drift to keep expensive checks separate.
+    - cron: "0 7 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: mutation-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  mutation:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run mutation tests
+        run: uv run mutmut run --max-children 4
+
+      - name: Export mutation stats
+        run: uv run mutmut export-cicd-stats
+
+      - name: Check mutation baseline
+        run: uv run python tools/check-mutation-baseline.py mutants/mutmut-cicd-stats.json mutation-baseline.json
+
+      - name: Print mutation stats
+        if: always()
+        run: |
+          if [ -f mutants/mutmut-cicd-stats.json ]; then
+            cat mutants/mutmut-cicd-stats.json
+          fi