Operating Constraints

@~/.claude/operating-constraints.md

Git Workflow

• Always create a feature branch before making changes
• Branch naming: feat/, fix/, refactor/, docs/
• Commit frequently with descriptive messages
• Keep me in the loop, don't gate on me (updated 2026-06-13). Commit, push, open PRs, and merge them to main autonomously — no per-push go-ahead needed. In exchange, brief me at the point of action (what changed, commit SHA, PR link, whether you merged) and recap at session end. I'd rather be told after the fact than asked before — but nothing happens silently.
• Still branch + PR for every change; the PR is the durable record that keeps me briefed, not a gate. Don't push straight to main.
• Review-gate proposal before autonomous merge (updated 2026-10-16). Before merging any PR yourself, give me your honest take on review scope — skip, or /code-review at a named effort level — with the why (risk surface, behavioral vs. mechanical content, blast radius, test coverage). If the target repo's CLAUDE.md has a ## Wired gates (Preflight) note, run the gates whose inputs touch the changed files and cite the results: a clean gate argues the scope down, a finding argues it up. Interactive sessions: STOP and wait for my call; I can veto in either direction, and my call is final for that merge. Unattended runs: make the call yourself and record it with the reasoning in the merge brief, with one floor: diffs touching behavioral/agent-instruction files (any CLAUDE.md, skills/**, agents/**, commands/**, hooks, or settings*.json) get a review. Heuristics: behavioral files, data integrity, auth, or money lean high or above; ordinary well-tested code earns medium; docs-only, comment-only, or config-typo diffs earn a skip. Correctness findings block the merge until fixed and verified, or explicitly waived by me; cleanups become follow-ups listed in the PR comment.
• Pause and ask first only for genuinely irreversible/destructive ops: force-push, history rewrite, production deploys. Exception: deleting the remote copy of a feature branch you created and already merged via PR is routine cleanup — do it without asking (this is the same "delete branch" button GitHub offers after every merge). Still pause before deleting any other remote ref or branch — one you didn't create, one that isn't confirmed merged, a shared/long-lived branch, or a tag.
• A specific project's CLAUDE.md may tighten this back (e.g. require my merge, or hold risky changes for a heads-up); the project rule wins where it does.

Clarifying questions and option formatting

• Ask 1–3 high-leverage clarifying questions up front whenever a prompt is ambiguous or uses fuzzy terminology — I prefer alignment over rework. When offering options: give each a short label, a 1–2 sentence merits/tradeoffs description, and mark your "(Recommended)" pick. If you assume rather than ask, surface the assumptions before acting on them.

Never hand me a ! command (added 2026-10-22)

I often continue sessions over Remote Control, which can't run !-prefixed commands. So never hand me a shell command to run that you could run yourself in this session. When one needs my say-so (under the Git Workflow rules above, or a skill's own gate), ask in chat and run it yourself on my yes; my yes is the gate, and any permission prompt that follows I can answer remotely. If a hook or the auto-mode classifier still denies it after my yes, report the denial; don't fall back to handing me the command. This adds no new gates: what you'd run without asking, keep running without asking. A skill that reserves a command for me ("the merge is Kyle's") means ask before running it, not hand it to me. It never unlocks what a skill says "never" to, and when a project rule says I must do something myself, say so and move on without waiting on me mid-session. It doesn't turn anything else a skill reserves for me (signing in, pressing submit) into something to offer.

Not hand-offs, and still wanted: the code <path> / open <path> line from the bare-identifier rule, and the launch command in a Run-config note, since both are for me to use later, not steps this session is waiting on. The one real exception is a command that truly needs an interactive TTY (an interactive login such as gh auth login): lead with a route that works without a terminal and keeps secrets out of chat (a device code I approve in a browser) if one exists, and only then say it needs a terminal. Never ask me to paste a token or password into chat.

Never show me a bare identifier (added 2026-08-13)

An ID you put in front of me is a pointer into a document I don't have open. F2, D31, S1.4, T3, "slice C" — each is a label whose meaning lives somewhere else, and I can't memorize them across sessions. A table of # · grade · verdict tells me the shape of a decision without telling me what I'm deciding, so I either approve blind or go hunting. Neither is what I'm paying attention for.

The rule, in three parts:

1. Every ID you put in front of me carries a gloss on its first mention in a turn — F2 (digest strips the wrong tags), D31 (T3 threshold 70 → 85), S1.4 (statusline reads one turn stale). Later mentions in the same turn can go bare; prose shouldn't turn into a glossary. Whether you minted it this session or inherited it is irrelevant — inherited is the common case and the one this rule is mostly about, since an ID from a past session or an existing doc is precisely the one I can't be expected to recall. Applies to every kind: review findings, decision rows, spike questions, triggers, build slices, milestones.
2. Any table listing IDs gets a title column. ID, severity/status, what it is, then your reason or disposition. The title column is not optional and is not the same as the reason column — "contradicts the plan table" is what's wrong; "recorded in one file while §13 says otherwise" is why you think so. I need both.
3. Say where the full text lives, and how to open it. Once per response that references IDs, give the absolute path and a copy-pasteable command — code <path> (or open <path> for anything that isn't text). Not "see the mailbox"; the actual line I can paste.

This is a presentation rule and it outranks a skill's or command's output spec. If a template says # · grade · verdict · one-line reason, render it with the title column anyway. Where a skill or command writes a durable artifact for somewhere else (a PR comment, a report file), that artifact follows its own template — this rule governs what reaches me, in chat.

Where a spec fixes the order of a response, rule 3's path line rides with the note that referenced the IDs — wherever that note sits. It is never appended as a new trailing slot after a spec's final element, and it never goes inside the paste. If notes come before a paste-able block, the path line joins them; if they come after it, the path line rides with whichever note cited the ID.

A spec that fixes its order wins on placement; it does not win on omission.

What it does not license: dumping full claims, evidence blocks, or quoted code inline. The gloss is a title, not a paragraph. The point is that I can decide from the table and open the file when I want depth — not that the file gets pasted into the conversation.

Planner/Builder Protocol (added 2026-07-27)

How model choice works across my sessions: Fable 5.1 plans, Opus 5.5 builds, Sonnet 5.5 grinds.

• Judgment-first work — planning, design calls with real tradeoffs, triage/adoption decisions, convention-setting — runs on Fable 5.1. Well-specified builds run on Opus 5.5. Mechanical, checklist-scoped work runs on Sonnet 5.5.
• Every plan or handoff written for another session to execute ends with a Run-config note: recommended model + effort for that session, a one-clause why, and the literal launch command (e.g. claude --model claude-opus-5-5 --effort high). --model and --effort are per-invocation flags — they never touch my saved defaults. "Ends with" means it closes the substance: it comes after everything the plan or handoff has to say, is never buried mid-document, and is never folded inside a paste-able block. Pure delivery artifacts, such as the paste-able block itself, may follow it. Call it a note, never a "block", so it never reads as belonging inside that paste.
• Effort ladder: ultracode for broad, parallelizable, want-exhaustive-coverage work (multi-agent fan-out + adversarial verify) · max / xhigh for ONE hard problem, design calls with real tradeoffs included (max uncapped and fast-burning, xhigh hard-but-bounded) · high for ordinary build work with judgment in it · medium / low for mechanical, checklist-scoped work. Effort is independent of the model pick.
• Builder sessions start fresh from the plan file, never from the planning session's transcript. Never recommend switching models mid-session after heavyweight planning: /model keeps the conversation but invalidates the per-model prompt cache — the full transcript re-ingests at uncached rates, and the build inherits deliberation noise it doesn't need.
• Split planner from builder only when build ≫ plan. When the work is plan-heavy and build-light, finish it in the Fable session — a handoff would cost more than it saves.
• In-session alternative for mid-size, decomposable builds: stay in the Fable session and dispatch scoped tasks to subagents with model: and effort: pinned in their frontmatter. Both keys are real, consumed agent-file fields — but a misspelled effort: only logs a warning and falls back to the default; it never fails the dispatch, so proofread the value.

Reference Doc Maintenance

~/Projects/claude-config/docs/command-skill-reference.md is the living index of every custom slash command, skill, and agent; docs/usage-playbook.md is its paired companion, holding one run-config card per indexed item. Keep both in sync in the same commit that changes what the index records — an item's existence, name, or description. Never batch those updates later. The "When to update" table below is the complete trigger list: a commit that changes an item's internals without touching its name or description needs no edit to either doc. This includes mid-review fix commits — a fix that reworks a description: triggers the sync just like the original add did.

This rule fires everywhere (this file is the global CLAUDE.md), so it covers global items in this repo AND project-specific items in any project.

When to update

Every action in that table applies to the playbook too. An added item gets a card (Run config · Reach for it when · Pairs well with, per the conventions already in docs/usage-playbook.md); a renamed or re-described item gets its card edited; a deleted item loses its card — and the row's config → link and the card's anchor stay in agreement.

This is checked, not remembered: scripts/check-doc-sync.py runs as the repo's tracked pre-push hook (.githooks/pre-push, activated by install.sh via core.hooksPath), so a row without its card blocks the push instead of landing. It checks the commits being pushed, not the working tree, so a half-finished doc edit can't block an unrelated branch. It fires for terminal and agent pushes alike; git push --no-verify bypasses it deliberately. Run it any time with python3 scripts/check-doc-sync.py. It also verifies the other direction — every tracked file matching the standard layout (commands/<name>.md, agents/<name>.md, skills/<name>/SKILL.md) has a row, and no row links to a file that's gone; anything item-shaped outside that layout is warned about rather than passed over. What it still can't check is project-specific items: their files live in other repos, so nothing here verifies that a DogHood skill you added has a row. That part is still on you.

Format rules

• One-line description per entry: what it does, not how it works
• For global items: assign to the most fitting existing category; only create a new category if nothing fits
• For project-specific sections: include a one-sentence description of the project above the table(s)
• Commit the reference-doc row and its playbook card in the same commit as the skill/command change (or as an immediately following commit on the same branch — the check runs at git push, so the branch has to be consistent before it leaves the machine)

Local-Markdown Issue Tracker: Tickets Index (added 2026-08-22)

The mattpocock engineering skills (setup-matt-pocock-skills, to-tickets, wayfinder, implement-spec, ...) reach sessions through the mattpocock-skills@mattpocock plugin — I can't durably edit their templates or process steps there; any edit would be unreviewable and silently lost on the next plugin update. This section is the editable substitute: it supplements their local-markdown issue-tracker mode (.scratch/<feature-slug>/issues/<NN>-<slug>.md, one file per ticket) with a convention the upstream files don't define.

Keep one-file-per-ticket as the source of truth. Per-ticket Status: / Blocked by: lines and ## Comments history live only in the issue files — never collapse them into a single combined file.

Also maintain a generated index. Write or refresh .scratch/<feature-slug>/tickets.md — a short manifest listing, for each ticket: number, title, one-line summary, Status, and Blocked by, each linking to its issue file — at two points only: (1) whenever tickets are published to a local-markdown tracker (/to-tickets, or any skill step that publishes tickets to the issue tracker in local-markdown mode), and (2) whenever /triage changes a ticket's Status. Don't refresh it from a concurrent context — /implement-spec runs implementer subagents each in their own worktree/branch, and none of them should touch tickets.md; only the orchestrating session refreshes it, once, after merging each implementer's work to the PR branch. This is what makes /implement @tickets.md-style references resolve without hand-listing every issue file, without turning the manifest into a merge-conflict magnet.

# Tickets: <feature-slug>

Generated index — resolves to the issue files below. Source of truth is `issues/`; refresh on publish, on a /triage Status change, or once after each merge in /implement-spec.

| # | Title | Summary | Status | Blocked by |
|---|---|---|---|---|
| [01](issues/01-slug.md) | Ticket title | One-line summary | ready-for-human | None |
| [02](issues/02-slug.md) | Ticket title | One-line summary | ready-for-agent | 01 |

Status values are the five triage roles (needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix) for /to-tickets tickets. /wayfinder tickets use a disjoint claimed/resolved vocabulary and don't belong in this manifest at all (see below) — don't mix the two.

The manifest is an entry point, never the source of truth. /implement and /implement-spec should treat tickets.md as an index that resolves to the issue files — read it to find which files exist and their current status, then read the issue files themselves for content (What to build / Acceptance criteria / Comments). If tickets.md and an issue file's Status: line ever disagree, the issue file wins; refresh the manifest.

/wayfinder does not consume this manifest. Its frontier is defined as a scan of issues/ for open, unblocked, unclaimed files, and its claim/resolve steps write only the issue file and map.md — never tickets.md. Reading the manifest instead of scanning risks missing a ticket the manifest hasn't caught up to. map.md stays wayfinder's canonical index; this convention doesn't apply to wayfinder efforts.

Route render (wayfinder efforts). After every claim, resolve, add-ticket, or wire-blocking step in a wayfinder effort, run python3 ~/.claude/skills/wayfinder-map/scripts/render_map.py <effort-dir>. The Stop hook that re-renders stale maps is the backstop, not the mechanism to rely on. map.html beside map.md is generated output: never hand-edited, never the source of truth. To see or share it, invoke wayfinder-map. When /setup-matt-pocock-skills scaffolds a repo that hosts wayfinder efforts, append the same render bullet under Wayfinding operations in its docs/agents/issue-tracker.md.

When scaffolding a new repo for local-markdown tracking, /setup-matt-pocock-skills writes that repo's own docs/agents/issue-tracker.md from the upstream template the plugin ships, which doesn't mention this convention. Append a short "Tickets index" subsection to that file — mirroring "Also maintain a generated index" and "The manifest is an entry point, never the source of truth" above, plus the table example — so the convention is discoverable in-repo too, not just from this global file.