deploy-setup

Deploy this setup into a project

You are installing guardrails into someone else's working project. The failure mode is not "install too little" — it is destroying a config that took them months. Eight such incidents are documented publicly; in one, an installer removed an MCP server and reduced four custom agents to stubs, losing ~600 lines while reporting "preserving configuration".

Read docs/instruction-mechanics.md if you have not. It explains why these specific hooks exist. Do not install mechanisms you cannot explain to the user.

Hard rules

1. Never write before showing a plan and getting a yes. Not a flag, not a default — a stop.
2. Never overwrite an existing CLAUDE.md. Append inside a marked block, or write alongside. Same for any file the user already has.
3. Never edit their settings.json if the plugin path is available. Hooks ride in hooks/hooks.json inside the plugin. That file is the whole reason this bundle is a plugin.
4. Install the smallest thing that solves their stated problem. A profile is a starting point, not a target to fill.
5. Never claim it works until you have run tests/run-all.sh and shown the output.

Phase 0 — snapshot

Before touching anything:

• if the project is a git repo with a clean tree, note the current SHA so the user can revert with one command; if the tree is dirty, say so and ask whether to continue
• if .claude/ exists, copy it to .claude.backup-<timestamp>/

Claude Code keeps its own timestamped backups of settings.json, but only the last five — a multi-step install can push the pre-install state out of the window. Do not rely on it.

Phase 1 — read the project

Do this with your own tools; there is no detector script and there should not be.

• stack and package manager: lock files are a 1:1 signal, package.json / pyproject.toml / Cargo.toml / go.mod for the rest
• monorepo markers (nx.json, turbo.json, pnpm-workspace.yaml) — these can coexist, do not stop at the first
• existing agent config: CLAUDE.md, AGENTS.md, .cursorrules, .claude/settings.json, .claude/hooks/, installed plugins
• dependencies the hooks need: python3 must exist. Check it. A hook whose interpreter is missing is not an error — it is silently treated as absent, so a guard you install would quietly guard nothing.
• if .claude/skills/config-audit/ is present, running its audit-config.py gives you a fast structured read of what is already there

Report what you found in three or four lines. Do not narrate the whole repo.

Phase 2 — ask

At most three questions. Lead with the profile; it frames everything else.

Profile	Hooks	For
core	scope-lock, claim-guard trio, stop-evaluator, bash-validator	the default — three mechanisms, no opinions
core + git	above + branch and checkout guards	teams with a branch discipline worth enforcing
full	above + telemetry, reminders, staleness, prompt classifier	mature repos with docs to keep fresh

Anything past core is opinionated and imposes the author's workflow. Say that out loud rather than letting them discover it.

Second question, only if their answer to the first leaves it open: do they want a CONTRACT.md with a writable-path allowlist. This is the mechanism for "stop inventing files I did not ask for". If yes, you need the list of paths, and that requires knowing what they are building — ask.

If AskUserQuestion is unavailable (you are running as a subagent, or in a harness without it), fall back to a numbered list in plain text and wait. Never guess an answer to skip the stop.

Phase 3 — show the plan

A three-column list, no prose:

CREATE   .claude/scope-lock.json          allowlist for writable paths
CREATE   CONTRACT.md                      human-readable contract
APPEND   CLAUDE.md                        5 lines, inside <!-- setup:begin --> markers
LINK     ~/.claude/skills/claude-code-setup   plugin (carries the hooks)
UNTOUCHED .claude/settings.json           your hooks and permissions stay as they are

Then wait. If they change anything, redo the plan — do not patch it verbally.

Phase 4 — write

Only what the approved plan lists.

• Hooks: the plugin carries them. Either the repo is already loaded as a plugin, or place/symlink it into ~/.claude/skills/<name>/ so it loads as a skills-directory plugin on the next session. No settings.json edit.
• CLAUDE.md: if absent, write a short one — hard rules, stack, commands, nothing else. If present, append inside <!-- claude-code-setup:begin --> / <!-- claude-code-setup:end --> markers so a future run updates only that block and leaves their prose alone. Do not write a repository overview: measured to add cost without improving outcomes (docs/instruction-mechanics.md §4).
• .claude/scope-lock.json: only if they asked for it. Without this file the hook is inert, which is the correct default.
• .gitignore: append the runtime-state lines listed in the README.
• Manifest: write .claude/.setup-manifest.json — bundle version, the tag or SHA installed, the list of files created or modified, and the backup path. Without it there is no honest update and no rollback.

Phase 5 — verify, then report

Run tests/run-all.sh and show the user the real output.

Then state, per hook, whether it is active and what will trip it. If something is installed but cannot fire in their setup, say so plainly — a guard believed to be working while it is not is worse than no guard.

Finally: one paragraph on what changes for them tomorrow, and the exact command to undo everything (git revert, or restore the backup directory).

Updating an existing install

Read .claude/.setup-manifest.json first. Compare the recorded version with this one. Show a diff of what would change; never overwrite files the user has edited since install — the manifest's checksums tell you which those are. If a file drifted, show both versions and ask.

What this skill must never do

• pull main instead of a pinned tag — a future compromise of the source would then propagate into every project this was ever run in
• install hooks the user did not see in the plan
• write to ~/.claude/settings.json (their global config, shared with every other project)
• report success without test output