nick-saban

Sets up and audits the Claude Code harness for a project: CLAUDE.md, .claude/rules, skills, subagents, settings.json permissions, hooks, verification loop. Commands: kickoff (scaffold new setup), chec

SKILL.md

GitHub

Nick Saban

A playbook is the durable, repo-wide agent operating system: CLAUDE.md, .claude/rules/, .claude/skills/, .claude/agents/, .claude/settings.json permissions, hooks, and the verification loop. This skill builds one, scores one, and fixes what it finds — plus a separate, lighter-weight pair of commands for contracting and checking one specific change.

kickoff · check-playbook · scouting-report · adjust · drill · decline · gameplan · watch-film

Doctrine

Five beliefs every command holds. They're short on purpose — read them every time, and load a reference file when you need the procedure behind one.

  1. The lowest sufficient rung. Every requirement in a playbook belongs on exactly one rung of the enforcement ladder — prose, scoped rule, skill, hook, permission, CI gate, or test — and it belongs on the lowest one that actually holds. Prose is cheap to write and easy to ignore. A failing test cannot be ignored. Moving a requirement down the ladder isn't extra rigor for its own sake — it's closing the gap between what you told the agent and what actually happens.
  2. Detected, never asserted. Nothing in this system marks itself done. adjust and drill change the repo; they never touch a finding's status. Only the next check-playbook gets to close a finding, by observing that whatever it was detecting no longer happens. The principle applies recursively to this skill's own claims — if this skill asserted its own fixes worked, it would be exactly the kind of unverified completion claim it exists to catch.
  3. A finding you can't write a consequence for isn't a finding. "This is bad practice" is an opinion. "This means formatting drifts across sessions because nothing runs the formatter" is a finding. If you can't name the concrete way this bites the user, don't raise it — or keep digging until you can.
  4. Declined is a first-class answer. Some standing risks are deliberate trade-offs the user already made with full knowledge. Recording that once, by signal, with a reason, is a legitimate outcome — not a failure to fully "fix" the repo. A system that re-flags a decision every single pass trains people to stop reading it.
  5. Context is a budget. Every line in CLAUDE.md is paid for on every single session, forever. Deleting a line that isn't earning its keep is a fix in its own right, not a smaller version of a fix.

Setup

Read .claude/nick-saban/registry.json once, at the start of the turn, if it exists. Don't re-read it between commands in the same turn — nothing in this skill mutates it mid-command except the command that's actually running.

Commands

Command Category Description Reads Writes Reference
kickoff Set up Scaffold a playbook for a project that has none repo probe CLAUDE.md, .claude/**, audits/001.json references/kickoff.md
check-playbook Assess Inspect and score the existing playbook source, prior record, waived audits/NNN.json, registry.json references/check-playbook.md
scouting-report Assess Scorecard, delta since last pass, open backlog, orders registry, records, orders — references/scouting-report.md
adjust Resolve Restructure the instruction layer record @ rungs prose/scoped-rule/skill CLAUDE.md, .claude/rules/, .claude/agents/ references/adjust.md
drill Resolve Convert advisory prose into executable enforcement record @ rungs hook/permission/ci/test .claude/hooks/, settings.json, CI references/drill.md
drill permissions Resolve Establish or harden the whole permission surface as one package live surface + baseline + any findings .claude/hooks/, settings.json references/drill.md
decline Resolve Record a finding as a deliberate, accepted choice, or revoke one (undecline) record waived.json, registry.json references/decline.md
gameplan Contract Write a work order with acceptance criteria bound to real commands repo, verificationSurface orders/<slug>.md references/gameplan.md
watch-film Contract Check a diff against its work order order, git diff order frontmatter, orders/<slug>.attest-N.json references/watch-film.md

Routing

Classify the intent first, because some of these routes must not write anything and others do.

  1. No argument, or an orientation request — help, what next, what should I do, where do I stand, how's my setup → load references/routing.md and present its evidence-based menu. Read-only. Recommending a command is the deliverable; running it is not. Stop after the recommendation and wait.
  2. Explicit or clearly implied command → load its reference file and follow it exactly, including its "stops at" boundary.
  3. An assessment request — audit, score, check, inspect my setup, "tell me what's actually wrong here" → check-playbook, which writes an audit record. The distinction from rule 1 is asking what is wrong (assess, writes) versus asking what to do (orient, reads). When a request could honestly be read either way, take the read-only route and offer the audit as the recommendation.
  4. Aliases — route silently, no need to mention the alias resolved: init / setup / scaffold → kickoff · check / score / status → check-playbook · prove → watch-film · order / brief → gameplan · accept / ignore / waive → decline · undecline / revoke / unwaive → decline (its Revocation section).
  5. drill permissions (also harden, lock down permissions, set up permissions) → drill in permission scope. It works the entire permission surface as one package and does not require existing findings — it's the right route for initial setup as well as hardening.
  6. commands (also menu, list commands, what can you do) → read-only. Show the eight commands, one line each: the name and when you'd reach for it, in the user's words ("before building a change: write down what done means"), not the Description column above. Then the standard Next block, picked by references/routing.md's rules. Writes nothing.
  7. Genuinely ambiguous — ask once, then proceed: verify could mean check-playbook (verify the setup) or watch-film (verify a change). fix could mean adjust (rewrite the text) or drill (make it enforced). review could mean either playbook command or a different skill entirely (see the boundary sentence in this skill's description). One short clarifying question, then go.

Output contract — every command, no exceptions

Two rules govern what the user actually reads.

1. Never end without telling the user what to do next. Every command's final block is a ### Next, and it always contains a recommendation, not a menu. The user should never have to ask "so what do I do now?" — if they do, the command failed regardless of how good its analysis was.

### Next

**Do this:** `<exact command to type>`
<one line on why — drawn from what this run actually found, not what the command does in general>

**Instead, if <specific condition>:** `<alternative command>`

<Only when a decision genuinely belongs to the user and blocks progress:>
**Need from you:** <the one question, with the options>

Rules on that block:

  • Name the exact invocation, including arguments — drill HN-013, not "run drill."
  • The reason cites this run's evidence. "HN-013 is the only high-severity finding open and every guard in the repo routes around it" — not "drill converts prose into enforcement."
  • Two options maximum. If three feel necessary, you haven't decided, and deciding is the job.
  • State the pick. "You could adjust or drill" is not a recommendation. Choose one, say why, and let the user overrule it.
  • When there is genuinely nothing to do, say that outright and say what would change it: "Nothing open. Next check-playbook is worth running after your next config change."
  • A recommendation is never permission. Rule 1 above still holds — recommending check-playbook and then running it in the same turn is the exact bug this contract exists to prevent.

2. Never reproduce reference-file text in the response. These files direct your behavior; they are not content to relay. The user gets the decision, the evidence, the proposed change, how it'll be verified, and the Next block. Not the doctrine, not the phase list, not the command table — that table appears only on an explicit commands request.

State

State lives in the user's project at .claude/nick-saban/, committed to the repo, one instance per project — two repos share nothing. It is state, not source: no command inspects, scores, or raises a finding about anything under that path; commands only read and write it exactly per their declared Reads/Writes above.

Full schema, the closed detector registry, the enforcement-ladder rung enum, and the write rules that keep the record trustworthy across passes: references/state.md. Read it before running kickoff or check-playbook for the first time in a session — those are the two commands whose correctness depends on getting the schema exactly right.