bchanot/claude
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
73e12be5f7
claude/skills/deploy/SKILL.md

22 KiB
Raw Blame History

name description allowed-tools
deploy Use when deploying a project via its per-project runbook — instantiates the delta since last deploy, hands off for out-of-band execution, resumes cold, learns from errors. Triggers: "deploy", "déploie", "run the deploy", "ship to prod", "deploy runbook".
Read
Write
Edit
Bash
Grep
Glob
AskUserQuestion

/deploy — per-project runbook, instantiated from the delta, resumed cold

Run a project's deploy from its committed runbook (.claude/deploy/PROCEDURE.md): instantiate only the steps the delta-since-last-deploy needs, hand the checklist to the user for out-of-band execution, then resume on their report — even in a different session with no conversation memory — and patch the runbook in place when a step fails.

Core principle — the disk is the only memory between the two moments. This skill runs in two moments split by a manual deploy you do not control. The report that closes it may land in a fresh session. So everything moment 3 needs lives on disk in .claude/deploy/, never in conversation context. Never reconstruct the deploy from memory, commit messages, or git describe.

Claude never runs the deploy. Prod commands run by hand, out-of-band. This skill only writes the checklist (NEXT.sh), reacts to the user's report, and records the outcome.

The two-moment contract — cold cross-session resume

This is the skill's defining form. No other skill resumes with the context gone.
Moment 1 (BEFORE) STEP 0–2: detect the delta, instantiate NEXT.sh, write the PENDING.json bridge, hand back.
the gap The user deploys by hand. May take minutes or days. May cross sessions.
Moment 2 (AFTER) STEP 3–5: on the user's report, react — mark success, or learn from a failure and re-hand-back.

How the wait is marked: a PENDING.json on disk with step_reached recorded IS the marker "a deploy is in flight, I am waiting for your report here." Its presence is the whole signal — no flag in memory, no open question in context. STATE.json is the deployed-up-to-here oracle; PENDING.json is the in-flight bridge that outlives the session.

How a cold resume detects + resumes (STEP 0): every invocation reads PENDING.json FIRST. Present ⇒ a deploy is mid-flight ⇒ jump straight to STEP 3 using the bridge's {base_sha, target_sha, delta, step_reached}. Do not recompute any of them — HEAD may have moved during the gap, so "current HEAD" is wrong; the bridge holds the truth captured at instantiation.

Read the JSON natively. Open PENDING.json / STATE.json with the Read tool and parse the fields directly. NO jq, NO shell JSON parsing — there is no jq dependency.

When to use / When NOT to use

Situation Skill
Run this project's deploy runbook, delta-instantiated, learning this skill
Project has no .claude/deploy/PROCEDURE.md yet this skill's bootstrap branch (see STEP 0)
Merge a branch + trigger CI deploy (gstack) /land-and-deploy
Configure deployment settings /setup-deploy
Document a release after shipping /document-release, /doc

Artifacts — .claude/deploy/ (five files)

File Committed? Role
PROCEDURE.md yes reference runbook — fixed shell + # @delta: steps; edited IN PLACE
INCIDENTS.md yes DEP-NNN ledger, append-only; read at instantiation for pre-warns
STATE.json yes deploy oracle — the SHA deployed up to here
PENDING.json no (gitignored) in-flight bridge; written at hand-back, deleted on success
NEXT.sh no (gitignored) instantiated checklist; run BY HAND, never bash NEXT.sh

Schemas (document of record — recover the shapes from here):

// STATE.json — overwritten each successful deploy (the diff oracle)
{ "deployed_sha": "<sha>", "deployed_at": "<ISO-8601>", "outcome": "ok", "tag": "deploy/<YYYY-MM-DD>" }

// PENDING.json — the cold-resume bridge; gitignored; deleted on success
{ "base_sha": "<deployed STATE sha>", "target_sha": "<HEAD at instantiation>",
  "delta": ["<path>", ...], "step_reached": "awaiting-user", "started_at": "<ISO-8601>",
  "runbook_rev": "<PROCEDURE.md commit sha>" }

step_reached = where the next NEXT.sh must start: "awaiting-user" = run from the top. A numeric X is used transiently within a learn to regenerate from step X; persisted on disk it is always "awaiting-user" — STEP 4 resets to awaiting-user at re-hand-back, and the runbook_rev staleness guard is the real cold-resume regenerate trigger. runbook_rev = the commit sha of PROCEDURE.md at instantiation; a mismatch versus the live runbook means NEXT.sh is stale and must be regenerated.

@delta: grammar (PROCEDURE.md)

A directive sits on the comment line above the step it governs; patterns are matched against the delta file list. Un-annotated step = fixed, always emitted verbatim.

Directive Meaning Instantiation
# @delta:<kind> glob=<pat>:each per-file command repeat the command once per matching delta file (file substituted in)
# @delta:<kind> glob=<pat>:list one command, many inputs emit the command once; list matching files as # VERIFY: items
# @delta:<kind> when=<pat,...> conditional include the step only if the delta intersects a pattern

<kind> is a human label. <pat> is a git-pathspec / shell glob; when= comma-separates alternatives. Zero matches → omit that step. Both :each and :list are first-class (e.g. apply each new migration with its own command vs. one migration up that lists which migrations to verify).

STEP 0 — PRE-FLIGHT + RESUME BRANCH

Read .claude/deploy/PENDING.json first (it is the only memory between runs).

  • PENDING.json present → RESUME. A deploy is in flight. Parse its {base_sha, target_sha, delta, step_reached} and jump to STEP 3. Announce: "A deploy started <started_at> is awaiting your report (target <target_sha>)." Do not recompute the delta, re-read HEAD, or re-instantiate from scratch — the bridge is authoritative.
    • Staleness guard: if NEXT.sh is absent OR runbook_rev ≠ the live runbook commit (git log -1 --format=%H -- .claude/deploy/PROCEDURE.md), the on-disk NEXT.sh is stale or missing (a patch landed, or a cold resume without regeneration) — regenerate it from step_reached (STEP 2's expansion) before reacting.
  • PENDING.json absent + PROCEDURE.md absent → BOOTSTRAP. No runbook yet: interview the project and scaffold an annotated PROCEDURE.md (or adopt one the user pastes), then continue at STEP 1. (See STEP 0-B below.)
  • PENDING.json absent + PROCEDURE.md present → FRESH. Continue to STEP 1.

First-deploy / fresh detection is file existence only. Never git describe (it errors when no deploy/* tag exists and is not the detection path).

STEP 0-B — BOOTSTRAP (no runbook yet)

Entered from STEP 0 when both PENDING.json and PROCEDURE.md are absent. Author a runbook, seed the incident ledger, commit both, then proceed to STEP 1.

AskUserQuestion — choose path:

"No runbook found in .claude/deploy/PROCEDURE.md. How do you want to create it?

A — Paste: share an existing runbook (paste text, file path, or URL). I adopt it verbatim and propose @delta: annotations for migration, build, and dep steps.

B — Scaffold: I detect deploy artifacts in this repo, ask a few questions, and fill the standard template."

Path A — Paste (adopt existing runbook)

  1. Receive the runbook (paste, path → Read, or URL). Accept as-is.
  2. Prepend the standard header: 
    #!/usr/bin/env bash
# === deploy runbook (reference) — NOT run directly. Instantiated to NEXT.sh per delta. ===
# Fixed steps run every deploy; annotated steps (@delta lines) re-instantiate from the delta.
# @config push_deploy_tags=false
  3. Scan for migration, rebuild, and dependency steps; propose @delta: annotations inline:
    • Migration steps (psql -f, migrate up, supabase migration) → # @delta:migrations glob=supabase/migrations/*.sql:list
    • Build/restart steps (docker compose, make build, image push) → # @delta:rebuild when=docker-compose*.yml,Dockerfile,Dockerfile.*
    • Dep-install steps (npm ci, pip install -r, bundle install) → # @delta:deps when=package.json,*lock*,requirements.txt,pyproject.toml
  4. Present the annotated draft; invite corrections before the gate.

→ [GATE] below.

Path B — Scaffold (detect + interview)

Detect artifacts (Glob / Read only — never shell find /):

Check If found Step emitted
supabase/migrations/*.sql yes migration step with :list annotation
docker-compose*.yml or Dockerfile yes rebuild step with when= annotation
package.json or *lock* yes deps step with when=package.json,*lock*
requirements.txt or pyproject.toml yes deps step with when=requirements.txt,pyproject.toml
.env* (not .env.example) yes add # NOTE: inject env vars to smoke-test step

Interview (AskUserQuestion — one prompt, all fields):

Field Prompt Default / placeholder
SSH host "SSH host or deploy target?" keep as $DEPLOY_HOST if blank
Backup command "Backup command before migrations?" pg_dump "$DB" > ~/backups/pre-deploy-$(date +%F-%H%M).sql
Health-check URL "Health-check URL (expects HTTP 200)?" https://$DEPLOY_HOST/health
Rollback note "One-line rollback note (optional)?" omit if blank
Push deploy tags "push_deploy_tags? (true / false)" false

Using templates/deploy/PROCEDURE.md as base, populate fields from interview answers + detected artifacts:

  • Substitute $DEPLOY_HOST with the supplied host (keep literal $DEPLOY_HOST if none given).
  • Include only the annotated steps whose artifact was detected; keep all fixed steps.
  • Set # @config push_deploy_tags=<answer> in the header.
  • Append the rollback note as # ROLLBACK: <note> at the end if provided.

→ [GATE] below.

[GATE] — approve PROCEDURE.md draft (all / edit / skip-all)

Present the full draft PROCEDURE.md.

  • all → approve: write files and commit (see below).
  • edit → revise the listed steps or annotations, re-present.
  • skip-all → abort bootstrap: write nothing, stop. Re-invoke /deploy when ready.

On approve — write + seed + commit:

  1. Write .claude/deploy/PROCEDURE.md (Write tool — the approved draft).
  2. Seed .claude/deploy/INCIDENTS.md from templates/deploy/INCIDENTS.md (Write tool).
  3. Ensure the target project's .gitignore contains .claude/deploy/NEXT.sh and .claude/deploy/PENDING.json (append both if missing — these are the transient artifacts that must not be committed).
  4. Check that .claude/deploy/ is NOT git-ignored: git check-ignore -q .claude/deploy/PROCEDURE.md (rc 0 = ignored). If ignored — e.g. the project has .claude/ in its .gitignore wholesale — ABORT bootstrap: warn the user that the runbook/oracle/ledger cannot be committed, and tell them to un-ignore .claude/deploy/ (e.g. add !.claude/deploy/ after the .claude/ rule). Do NOT commit anything further.
  5. Commit via the allowlist helper: 
    bash lib/deploy-commit.sh commit \
  "feat(deploy): bootstrap runbook" \
  .claude/deploy/PROCEDURE.md .claude/deploy/INCIDENTS.md
    Return codes: 0 committed · 1 no-op (investigate — both files should be new) · 3 unsafe git state (STOP, tell user) · 4 out-of-scope path · 5 a passed path is git-ignored (won't persist) — STOP, fix the target's .gitignore · 2 usage error OR not a git repo.

On rc=0: continue to STEP 1. STATE.json absent → first deploy → STEP 1 sets base_sha: null and the full runbook fires (every fixed step and every detected @delta: step instantiates). Correct and expected — no special handling needed.

STEP 1 — DELTA

Set the base, compute the changed-file list, capture the target.

  • STATE.json absent → FIRST DEPLOY. No base (PENDING.json.base_sha: null). The full runbook fires: delta = the entire tracked tree (git ls-files), so every fixed step and every applicable @delta: step instantiates.
  • STATE.json present → read deployed_sha as base, then: 
    git diff --name-only <base_sha> HEAD     # two explicit endpoints, no dots
    This is the literal tree difference deployed→HEAD. Never git rev-list ancestry (phantom deltas after a rebase) and never three-dot <base>...HEAD (merge-base undercounts).
  • target = git rev-parse HEAD — the SHA this deploy carries to prod.

STEP 2 — INSTANTIATE + [GATE] + HAND BACK

Build NEXT.sh (the recipe — it IS this shape):

  1. Walk PROCEDURE.md in order. For each step:
    • un-annotated (fixed) → emit verbatim;
    • @delta:…:each → emit the command once per matching delta file, file substituted; zero matches → omit;
    • @delta:…:list → if any delta file matches, emit the command once and list the matches as # VERIFY: items; zero matches → omit;
    • @delta:…when= → emit verbatim only if the delta intersects a pattern.
  2. Read INCIDENTS.md; for each DEP-NNN whose step matches an emitted step, prepend # PRE-WARN: DEP-NNN <one-line summary> above it.
  3. Keep every # VERIFY: gate. Header the file: "Run by hand, step by step. Never bash NEXT.sh unattended."
  4. Write .claude/deploy/NEXT.sh.

[GATE] — present NEXT.sh → all / edit / skip-all.

  • all → proceed. edit → revise the listed steps, re-present.
  • skip-all → abort: write no PENDING.json, discard the draft NEXT.sh, stop.

On approve: write .claude/deploy/PENDING.json:

{ "base_sha": "<STEP 1 base>", "target_sha": "<STEP 1 target>",
  "delta": [<STEP 1 file list>], "step_reached": "awaiting-user",
  "started_at": "<now, ISO-8601>",
  "runbook_rev": "<git log -1 --format=%H -- .claude/deploy/PROCEDURE.md>" }

Then HAND BACK (AskUserQuestion): "Run NEXT.sh step by step against prod. Report back: Deployed OK / Failed at step X: / Not yet." Then stop — control is the user's; PENDING.json on disk now marks the wait.

STEP 3 — RESUME / REACT

Entry point on the user's report — reached inline after STEP 2, or cold via STEP 0 in a later session. Branch on the report:

  • "Deployed OK" → STEP 5.
  • "Failed at step X: " → STEP 4.
  • "Not yet" → restate what is pending (step_reached, target, the command to run) and stop. PENDING.json stays; the wait continues.

STEP 4 — LEARN + [GATE] + ATOMIC COMMIT

Diagnose the root cause of the step-X failure, then draft a coupled pair:

  • (a) an in-place patch to step X in PROCEDURE.md so the next run cannot repeat the failure;
  • (b) an append to INCIDENTS.md — a new DEP-NNN (next = grep '^## DEP-' INCIDENTS.md | max+1) with date, step, error verbatim, root cause, and fix.

[GATE] — all / pick <IDs> / edit <ID> / skip-all (significant edit — it changes a prod path).

  • Coupling invariant: the patch and the incident are one unit — never commit one without the other. pick <IDs> / edit <ID> apply only when diagnosis yields multiple incidents (several failing steps); each selected incident still commits its own patch+append together.
  • skip-all → leave PENDING.json as-is, stop, nothing learned (the deploy stays failed-and-pending).

On approve — one ATOMIC commit of both files:

bash lib/deploy-commit.sh commit \
  "docs(deploy): patch <step> — recovered from <err>" \
  .claude/deploy/PROCEDURE.md .claude/deploy/INCIDENTS.md

Return codes: 0 committed (short-hash on stdout) · 1 nothing staged — you wrote neither file · 3 unsafe git state (detached/merge/rebase — STOP, tell the user) · 4 out-of-scope path (you passed a non-.claude/deploy/ path — fix the call) · 5 a passed path is git-ignored (won't persist) — STOP, fix the target's .gitignore · 2 usage error OR not a git repo. The helper commits whatever subset actually changed; patch+incident coupling is Claude-discipline, not helper-enforced.

This commit IS the resolution — the commit that introduces DEP-NNN is its fix (patch + incident committed atomically). Recover later via git log -S '<DEP-NNN>' -- .claude/deploy/INCIDENTS.md. No backfill needed.

Then:

  1. Bump PENDING.json.runbook_rev to git rev-parse HEAD (full sha — not the helper's short-hash stdout); keep step_reached = X.
  2. Regenerate NEXT.sh from step_reached against the PATCHED runbook (steps X…end — X+1…end never ran). This is NOT replaying one step: the bumped runbook_rev is exactly the staleness trigger — runbook changed ⇒ prior NEXT.sh is stale ⇒ regenerate.
  3. Re-present via STEP 2's [GATE] + hand-back (the regenerated NEXT.sh; PENDING.json keeps base/target/delta, step_reached back to awaiting-user).

STEP 5 — MARK (success)

The deploy succeeded. Lay the oracle and close out.

  1. Read # @config push_deploy_tags= from the PROCEDURE.md header (default false). Pick date = today (YYYY-MM-DD); if deploy/<date> exists, suffix -N.
  2. Write .claude/deploy/STATE.json (overwrite): 
    { "deployed_sha": "<PENDING.target_sha>", "deployed_at": "<now ISO-8601>",
  "outcome": "ok", "tag": "deploy/<date>" }
    deployed_sha = PENDING.target_sha, NOT current HEAD — HEAD may have moved during the gap; the bridge's target is the deployed truth.
  3. git tag -a deploy/<date> <PENDING.target_sha> -m "<summary>".
  4. If push_deploy_tags=true → git push origin deploy/<date> — best-effort, non-fatal: a push failure logs a warning, never blocks the mark (the tag is a bookmark; STATE.json is the oracle).
  5. Commit the oracle: 
    bash lib/deploy-commit.sh commit "chore(deploy): mark <date> @ <short>" \
  .claude/deploy/STATE.json
  6. Delete .claude/deploy/PENDING.json and .claude/deploy/NEXT.sh — the deploy is no longer in flight; the bridge is consumed.
  7. Report: deployed SHA, tag (+ push result), state committed, any DEP-NNN learned this deploy. Then offer to capitalize per CLAUDE.md (recurring failure pattern → learnings.md; deploy verdict → evals.md), gated, never silent.

Rules

  • PENDING.json is the only memory across the gap. Read it first, every run.
  • On RESUME, never recompute {base, target, delta} — the bridge is authoritative.
  • deployed_sha is PENDING.target_sha, never live HEAD.
  • Delta is git diff --name-only <base> HEAD (two endpoints). No rev-list, no three-dot, no date ranges.
  • First-deploy / fresh detection is file existence only — never git describe.
  • Claude never executes the deploy. NEXT.sh is hand-run; # VERIFY: gates stay.
  • Patch + incident commit atomically, one deploy-commit.sh call, both files.
  • A learn bumps runbook_rev and regenerates NEXT.sh from step_reached; it never replays a single step.
  • Tag push is best-effort; STATE.json is the oracle.
  • JSON is read natively (Read tool), never parsed with jq/shell.
  • STATE.json written only on confirmed success (STEP 5). A failed/partial deploy leaves the oracle untouched, PENDING.json alive — fail closed, resume later.

Common mistakes

Mistake Fix
On resume, recomputing delta from current HEAD HEAD moved during the gap. Use PENDING.json.{base,target,delta} verbatim.
git describe to detect first deploy Errors with no tag. Detect by STATE.json / PENDING.json existence.
git rev-list or three-dot for the delta Phantom/undercounted deltas. Two-dot <base> HEAD only.
bash NEXT.sh to "just run it" Claude never deploys. Hand back; user runs by hand with # VERIFY: gates.
Committing the patch without the incident (or vice versa) Coupling invariant. One atomic deploy-commit.sh call, both files.
Replaying only the failed step after a patch Steps X…end never ran. Regenerate NEXT.sh from step_reached.
Writing STATE.json before the user confirms success Oracle marks success only. Failed deploy leaves it untouched.
Setting deployed_sha to HEAD at MARK time Use PENDING.target_sha — the SHA actually deployed.
Parsing the JSON bridges with jq Read them natively. No jq dependency.
Deleting PENDING.json before STEP 5 The bridge is the resume marker — delete it only on confirmed success.

Red flags — STOP

  • About to recompute the delta or re-read HEAD while a PENDING.json exists.
  • About to run git describe, git rev-list, or a three-dot diff for the delta.
  • About to bash NEXT.sh or run any prod command yourself.
  • About to commit PROCEDURE.md without INCIDENTS.md in the same call.
  • About to write STATE.json before the user reported "Deployed OK".
  • About to replay one failed step instead of regenerating from step_reached.

Note on this skill (authoring)

Shaped via superpowers:writing-skills. The cold cross-session resume is the novel form (design §10): the disk alone must carry the deploy across the out-of-band gap, so PENDING.json's presence marks the wait and STEP 0 resumes from it without conversation memory — the audit-delta "state file is the only memory between runs" convention, extended to a mid-flow pause. The forms here match the failure modes the design identified: discipline failures (recompute-on-resume, run-the-deploy, advance-the-oracle-early) get the rationalization table + red flags; the shape of NEXT.sh and the schemas get positive recipes; the patch↔incident omission is a structural atomic-commit requirement. Pressure-scenario baseline testing per the writing-skills Iron Law is a follow-up — the failure modes were taken from the design spec, not a fresh RED run.