chore: adopt the AI-native SDLC playbook and repository policies

.claude/hooks/ruff.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# PostToolUse: reject an edit that leaves a Python file unformatted or failing ruff; exit 2 hands the message back to Claude.
+set -euo pipefail
+command -v jq > /dev/null || { echo "ruff hook: jq not found, skipping (nox -s lint still runs it)." >&2; exit 0; }
+file=$(jq -r '.tool_input.file_path // empty')
+case "$file" in
+  *.py) ;;
+  *) exit 0 ;;
+esac
+[ -f "$file" ] || exit 0
+if command -v ruff > /dev/null; then
+  ruff_cmd=(ruff)
+elif command -v uvx > /dev/null; then
+  ruff_cmd=(uvx --quiet ruff)
+else
+  echo "ruff hook: neither ruff nor uvx found, skipping (nox -s lint still runs it)." >&2
+  exit 0
+fi
+cd "${CLAUDE_PROJECT_DIR:-.}"
+if ! out=$("${ruff_cmd[@]}" format --check "$file" 2>&1); then
+  echo "ruff: $file is not formatted. Run 'nox -s format' (or 'ruff format $file') and re-check. $out" >&2
+  exit 2
+fi
+if ! out=$("${ruff_cmd[@]}" check "$file" 2>&1); then
+  echo "ruff check failed on $file: $out" >&2
+  exit 2
+fi

.claude/settings.json

@@ -0,0 +1,12 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          { "type": "command", "command": "\"${CLAUDE_PROJECT_DIR}\"/.claude/hooks/ruff.sh" }
+        ]
+      }
+    ]
+  }
+}

.claude/skills/ai-native-sdlc/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: ai-native-sdlc
+description: Entry point for the AI-native SDLC workflow (intent.md -> spec.md -> plan.md -> build -> verify -> review -> release). Use when starting any new feature, change or incident, when asked "where do we start", "what's the next step", or "which play should we run", or when deciding which sdlc-* skill applies to the current state of a change.
+---
+
+# AI-native SDLC
+
+Humans stay accountable for every judgment call. Claude does the drafting, checking and plumbing, and every stage leaves a committed Markdown artifact that the next stage consumes.
+
+## The artifact chain
+
+Each change gets a folder in the repo: `intent/<change-slug>/`.
+
+| Artifact | Written by | Approved by | Skill |
+|---|---|---|---|
+| `intent.md` | Originator + Claude | Maintainer | `sdlc-intent` |
+| `spec.md` | Claude, from the intent | Maintainer (area owners for flagged concerns) | `sdlc-spec` |
+| `plan.md` | Claude in plan mode | Engineer (tech lead if higher risk) | `sdlc-plan` |
+| code + tests | Claude, verified by its own feedback loop | Code owner at PR | `sdlc-feedback-loop`, `sdlc-pr-review` |
+| release | Maintainer, following `RELEASE.md` | Code owner on the release PR | none |
+
+## Pick the next step from what exists
+
+Look in `intent/<slug>/` and the repo, then route:
+
+1. No folder, only an idea or a ticket: `sdlc-intent`.
+2. `intent.md` approved, no `spec.md`: `sdlc-spec`.
+3. `spec.md` approved, no `plan.md`: `sdlc-plan`.
+4. `plan.md` approved: build. Use `sdlc-feedback-loop` so the session verifies its own work, and `sdlc-subagents` to parallelise.
+5. Diff ready: `sdlc-pr-review`.
+6. Releasing: follow `RELEASE.md`.
+
+Foundations that any stage leans on: `sdlc-claude-md` (shared context in `AGENTS.md`), `sdlc-policy-skill` (organization policy as skills).
+
+## Prerequisites
+
+`sdlc-spec` needs an approved `intent.md`; `sdlc-plan` works from a spec or, for small changes, a plain
+description; `sdlc-subagents` and `sdlc-pr-review` lean on `AGENTS.md`, `REVIEW.md` and the local CI commands in `AGENTS.md`. If a
+prerequisite is missing, say so and offer to run that skill first instead of working around it.
+
+## Ground rules for every stage
+
+- Put the artifact in the repo and name its author. Git history is the audit record.
+- One source of truth per artifact. If Jira, ServiceNow or a requirements tool already holds the record, either declare it authoritative and write outcomes back through MCP, or link both ways (record ID in the file, commit SHA in the record).
+- Advisory controls (skills, `CLAUDE.md`) get a deterministic backstop where the rule must always hold: a hook at the edit, a required check at the PR.
+- A human makes each accept or reject decision that moves an artifact to the next stage. Never mark one approved on their behalf.
+- Every play has a leading and a lagging indicator. Name them when you set the play up so the team can tell whether it worked.

.claude/skills/sdlc-claude-md/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: sdlc-claude-md
+description: Create, trim or audit a repo's CLAUDE.md so it holds exactly what a new joiner needs on day one (commands, conventions, architecture, recurring mistakes, verification). Use when a repo has no CLAUDE.md, when it has grown stale or long, when Claude repeats a mistake, or when asked to "set up CLAUDE.md" or "update our CLAUDE.md".
+---
+
+# The CLAUDE.md
+
+`CLAUDE.md` is the context a new joiner would need, read by the agent at the start of every session. It is version controlled and reviewed like code. Keep it under a page: Claude reads all of it every session, and stale lines waste context.
+
+## Create
+
+1. Survey the repo: build files, `Makefile`/package scripts, CI config, README, directory layout, test setup.
+2. Draft with `/init` if available, or by hand, then cut it down to day-one essentials.
+3. Verify every command by running it (or asking the engineer). Never list a command you have not seen work, and note a healthy output for each.
+4. Ask the engineer who knows the codebase best for the "things Claude gets wrong" list; pull more from recent PR review comments and reverted changes.
+5. Place it at the repo root and commit, with code owners set so changes get reviewed.
+
+## Template
+
+```markdown
+# <Project>
+
+## Commands
+- Build: <cmd>
+- Test: <cmd> (unit), <cmd> (integration, needs ...)
+- Lint: <cmd> (runs in CI; fix before pushing)
+- Run: <cmd> (<what comes up, on which ports>)
+
+## Conventions
+- <language/framework versions>
+- <rules that matter: every endpoint needs a test, dates are ISO 8601, ...>
+
+## Architecture
+- <directory map, which component talks to which, hard limits (rate limits, ownership)>
+
+## Things Claude gets wrong
+- <each mistake the team has corrected twice>
+
+## Verifying your work
+- Build: <cmd> (must finish with "<healthy output>")
+- Test: <cmd> (all green; never skip or delete a failing test)
+- Lint: <cmd> (zero warnings)
+Run all three before reporting any task complete, and paste the output.
+If a test fails, fix the code, not the test.
+```
+
+If artifacts live in `intent/`, add a line saying `intent/` holds `intent.md`, `spec.md` and `plan.md` per change.
+
+## Audit an existing file
+
+- Remove anything stale, obvious from the code, or already enforced by CI or a hook.
+- Move multi-step procedures into a skill (`sdlc-policy-skill`); move must-always-hold rules behind a hook (`.claude/settings.json`) or a CI check.
+- Flag missing sections, unverifiable commands, and contradictions with `README` or CI.
+- Report the diff and why; do not silently drop lines someone may rely on.
+
+## Maintenance rule
+
+When Claude makes the same mistake twice, the correction goes into `CLAUDE.md` in the same PR. PR review should also flag changes that make `CLAUDE.md` outdated (`sdlc-pr-review`). Trimming changes agent behavior, so watch the next few PRs for regressions.
+
+## Measure
+
+- Leading: how often Claude repeats a mistake `CLAUDE.md` should have caught (track corrections in Git history).
+- Lagging: time to first merged PR for a new team member.

.claude/skills/sdlc-feedback-loop/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: sdlc-feedback-loop
+description: Give Claude a way to verify its own work (tests, build, lint, screenshot diff) and protect that check from being weakened. Use when starting implementation or a bug fix, when asked to "set up verification", "fix this bug test-first", or when Claude reports work done without proof; also for UI changes that need a visual check.
+---
+
+# Give Claude a feedback loop
+
+Always give the session a way to check its own work before a person sees it. A late signal (CI minutes later, a tester days later) turns the engineer into the bottleneck.
+
+## Set up
+
+1. Wrap verification in one command per concern that exits non-zero on failure (`make test`, `npm test`, `make lint`, `make build`). Create the targets if only a command sequence exists today.
+2. List them in `CLAUDE.md` (see `sdlc-claude-md`) with a sample of healthy output, plus the instruction: run the tests before reporting a task complete and show the output.
+3. State a quantifiable target for the task so Claude can check without asking: "all tests in X pass", "screenshot matches the attached mock", "the endpoint returns 200 with the new field". Take targets from `plan.md` Proof when it exists.
+4. For UI work, give Claude a browser or screenshot tool (e.g. via MCP) and the mock: implement, screenshot, compare, adjust. Two or three rounds is normal.
+
+## Bug fixes: failing test first
+
+1. Reproduce the bug as a test. Run it and confirm it fails for the reason expected.
+2. Commit that test.
+3. Only then fix the code, without editing the test. A test that existed before the fix, and that the agent could not rewrite, is proof the bug is gone.
+
+## Protect the loop
+
+An agent fixing code must not be able to weaken the check on that code. Either:
+
+- block edits to existing test files once the failing-test commit exists, with a `PreToolUse` hook (`sdlc-policy-skill` shows the pattern), or
+- check the diff in review: new regression tests are expected, but reject any change after the failing-test commit that weakens, skips or rewrites a test (`sdlc-pr-review`).
+
+## Report format
+
+When finishing, paste the literal output of the build, test and lint commands (or the screenshot diff). Evidence comes from the toolchain, not from the agent's summary.
+
+## Governance
+
+Verification before "done" and the block on editing tests are enforced as hooks where the organization wants them guaranteed. Evidence lives in the session transcript and in the PR's check run; the code owner reviews intent and risk because mechanical evidence is already attached.
+
+## Measure
+
+- Leading: first-pass CI success rate of agent-written changes.
+- Lagging: review time per PR (should fall) and change failure rate from the incident tracker.

.claude/skills/sdlc-intent/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: sdlc-intent
+description: Turn an idea, ticket, pain point or incident into a committed intent.md proto-spec by interviewing the originator. Use when someone describes a problem or wants a new feature and there is no intent.md yet, when asked to "capture intent", "write up this idea", or "start a new change".
+---
+
+# Capture as intent.md
+
+`intent.md` is a short proto-spec in the originator's own terms: what is wanted, why, and under which constraints. It is human readable and machine actionable, and it kicks off the rest of the chain.
+
+## Steps
+
+1. Let the originator describe the problem in their own words. No formal language needed. If the source is a ticket or incident, read it (via MCP or the pasted text) and start from there.
+2. Interview until the idea is concrete, asking what an analyst would: who is affected, what they cannot do today, what better looks like, what is out of scope, which systems are touched, which constraints apply (security, compliance, existing auth), how success is observed. Ask a few questions at a time, not a form.
+3. Check for an agreed template (`intent/TEMPLATE.md` or an organization skill) and use it. Otherwise use the template below.
+4. Write the draft to `intent/<change-slug>/intent.md` (kebab-case slug, create the folder).
+5. Read it back and have the originator correct anything misunderstood. Do not invent answers: unresolved items go under Open questions.
+6. Commit when the originator is satisfied (follow the repo's commit conventions). The product owner picks it up from there and decides accept or close.
+
+## Template
+
+```markdown
+# Intent: <short title>
+Author: <name, team>. Status: draft.
+
+## Problem
+<what cannot be done today, who feels it, evidence>
+
+## Proposed outcome
+<what better looks like, in the originator's words>
+
+## Affected users and systems
+<people, services, data>
+
+## Constraints
+<security, compliance, auth, performance, deadlines>
+
+## Open questions
+<anything unanswered, with who might know>
+```
+
+## Rules
+
+- Stay in the problem space. No design, no implementation, no file names.
+- If the originator is not a Git user, commit through the version-control connector on their behalf and record them as author in the header.
+- Track an incident-sourced intent the same way, and say in the header that it came from monitoring (`Author: monitoring agent`) so the product owner knows to review harder.
+
+## Measure
+
+- Leading: time from first conversation to a committed `intent.md` (Git timestamps).
+- Lagging: share of intents the product owner accepts into design instead of closing, and how many edits `intent.md` receives after the first `spec.md` commit.
+
+Next step once accepted: `sdlc-spec`.

.claude/skills/sdlc-plan/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: sdlc-plan
+description: Produce and commit a plan.md before any code is written, working in plan mode from the approved spec.md and intent.md. Use when starting implementation of a change, when asked to "plan this", "make an implementation plan", or before editing code for a change that has an intent/spec; also use to keep plan.md in sync when implementation departs from it.
+---
+
+# Plan mode as the default starting point
+
+Work starts with a written, reviewable plan. Plan mode lets Claude read the codebase without changing anything, so course corrections are edits to a document.
+
+## Steps
+
+1. Work in plan mode (Shift+Tab, or start the session with `--permission-mode plan`). Do not edit files until the engineer accepts the plan.
+2. Read `intent/<slug>/intent.md`, `spec.md` (the requirement numbers R1.. and concerns), `CLAUDE.md` and the code the change touches. If a spec exists, a plan without it is a smell; if neither exists, ask whether to run `sdlc-intent` / `sdlc-spec` first or to plan from a plain description.
+3. Draft the plan using the template below.
+4. Let the engineer interrogate it. Be ready to answer: what could this break, which step is riskiest, which alternatives were rejected and why.
+5. Iterate until someone who never saw the conversation could implement the change from the plan alone.
+6. Commit the approved plan as `intent/<slug>/plan.md`. Then implement; with a solid plan this is often one pass.
+7. If implementation departs from the plan, update `plan.md` in the same commit. Consider a hook that flags source changes with no matching plan update.
+
+## Template
+
+```markdown
+# Plan: <title> (from intent.md and spec.md)
+
+## Files that change
+<paths, marking new files>
+
+## Order of work
+1. <step> (R1, R2).
+2. <step> (R4).
+
+## Risks
+<what could break; cite spec concerns by number>
+
+## Proof
+<which tests or checks cover which requirements, and how UI changes are verified>
+```
+
+## Rules
+
+- Cite requirement numbers on every step and every proof line so a reviewer can check the plan against the spec line by line.
+- The Proof section must be executable by Claude (tests, build, screenshot compare); see `sdlc-feedback-loop`.
+- Independent steps (different files) can run in parallel sessions; mark them so `sdlc-subagents` can split the work.
+- Plans for changes the organization classes as higher risk go to a tech lead or architect before acceptance.
+- Existing records (Jira, requirements tools) stay authoritative when the organization says so: note the record ID in the plan header, and write outcomes back through the connector. Otherwise link both ways.
+
+## Auto mode
+
+Once guardrails mature (a tuned `CLAUDE.md`, policy skills, blocking hooks, a test suite Claude can run), routine work with a tight spec and a small blast radius can run in auto mode after the plan is approved. The plan is still reviewed first.
+
+## Measure
+
+- Leading: share of changes that merge from the first implementation pass; time from plan approval to merged PR.
+- Lagging: rework cycles per change; how often the merged diff still matches `plan.md`.

.claude/skills/sdlc-policy-skill/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: sdlc-policy-skill
+description: Write a Claude skill that encodes an organization policy or standard (security, API design, brand, compliance, UX), with a trigger test and a deterministic backstop. Use when asked to "turn this policy into a skill", "encode our standard", "make Claude follow our X guidelines", or when a rule is enforced inconsistently today.
+---
+
+# Skills as institutional knowledge
+
+A skill makes institutional knowledge operational: explicit, version controlled, applied broadly, updated centrally. It is an advisory control. Write one for knowledge that must be applied consistently; keep general project context in `CLAUDE.md` and one-off instructions in a prompt.
+
+## Decide where it belongs
+
+| Knowledge | Home |
+|---|---|
+| Conventions every session needs (commands, layout) | `CLAUDE.md` |
+| A policy with an owner, applied when a certain task happens | **a skill** |
+| A rule that must hold with no exceptions | skill + hook (+ required CI check) |
+| A recurring job needing its own context and tools | subagent (`sdlc-subagents`) |
+
+## Steps
+
+1. Pick one policy that is enforced inconsistently today. Get its written source of truth and its named owner.
+2. Create `.claude/skills/<name>/SKILL.md` (ships with the repo) or put it in a plugin for organization-wide distribution.
+3. Frontmatter: `name`, and a `description` that says what the skill does and exactly when to trigger (task types, file types, verbs users would say). The description decides whether it ever loads.
+4. Body: numbered, testable rules in imperative form; cite the policy section each rule comes from; name any script to run and require its output in the summary.
+5. Test triggering: ask Claude for the relevant task in 4-5 different phrasings, including ones that never mention the policy, and confirm the skill loads each time. Tighten the description until it does.
+6. Have the policy owner sign off. Policy changes become skill changes, reviewed like code; engineers pick up the new version in their next session.
+7. Back it up (below).
+
+## Template
+
+```markdown
+---
+name: <kebab-name>
+description: <What it enforces>. Use whenever <task types and triggers>.
+---
+# <Title>
+When you <do the task>:
+1. <Rule>. (Policy §x.y)
+2. <Rule>.
+Run <script> and include its output in your summary.
+```
+
+## Add a deterministic backstop for must-hold rules
+
+- **Hook at the edit**: a `PostToolUse` hook (matcher `Edit|Write`) that runs the same script the skill names, only for the files that changed. Exit code 2 feeds the script's message back to Claude so it fixes the line. Keep build-phase hooks fast and scoped; heavy checks belong at commit or PR.
+- **Required check at the PR**: run the same script in CI as a required status check. It also catches changes that bypassed the hook (a shell command rewriting a file, a different tool).
+- A hook that asks a human for approval is a gate, not a guardrail; keep those at release, not mid-build.
+
+## Measure
+
+- Leading: time from policy owner approving a change to the updated skill merging.
+- Lagging: PR review findings that cite the policy. They should trend to zero; if not, the skill is not triggering or has drifted from the official text.