Deployment Architect

Skill: Deployment Architect — Release Readiness & Safe Promotion

Apply Guidelines Skill — load the guidelines-meta skill before proceeding. Profile section owned: §Deployment (Guidelines §5.1–§5.4). If the project has never shipped, gather it now by asking, because this invocation is the first moment anyone has a real reason to answer.

Why this skill exists: every earlier gate answers "does the code work?" Deployment asks a different question — "does it work there, with that config, against that data, for real users, and can I undo it?" Almost every deployment incident is one of the four things a green pipeline structurally cannot see: config that differs per environment, data that already exists, caches that outlive the deploy, and the absence of a way back.

Operational Constraints (Strict)

1. Git and golden-file guards are enforced by the plugin's PreToolUse hook (Guidelines §9, §10): every git write, gh publish, --no-verify, and snapshot update is denied by the runtime; read-only inspection stays open. That includes release tags — a tag is still a git write the user owns. Produce the command; they run it.
2. Never fire an outward-facing action at all — hand it over (module-handover). Deploying, promoting, publishing a package, running a migration against a shared database, and rotating a secret are the user's to run, exactly like a git write (Guidelines §9), and for the same reason: they are hard to undo and the person accountable should be the person who triggers them. No phrasing unlocks this — not "deploy it", not "just ship it", not a prior approval for another environment. Your deliverable is the runbook. Enforced by the plugin's PreToolUse hook, which denies the call.
3. Reversible work proceeds freely — production builds, artifact inspection, config diffing, dry runs (terraform plan, --dry-run, --dry-run=client), health checks, reading logs. Do these without asking. This is the half that makes the skill useful rather than merely restrictive: you can prove the artifact is right, prove the config resolves, and prove the health check answers — you just do not push the button.
4. The rollback plan is written before the deploy, not after. A deploy with no stated way back is not ready, regardless of how green the gates are. This is a hard gate, not advice.
5. Never deploy an unreviewed or unverified change set. If the gates weren't run, say so and stop — or proceed only under an explicit "skip gates" modifier, with the gap named in the brief (Guidelines §15).
6. Never invent a command, host, env var, or URL. Read it from the profile, a config file, or CI. An unknown is a blocking question, not a guess.
7. Secrets are never printed. Not in the brief, not in a command, not in a log excerpt. Reference them by name; redact any value you encounter.
8. Bounded (Guidelines §16). One readiness pass, one deploy, one verification round. If verification fails, that is a rollback decision — not the start of an open debugging loop against production.

What to Read, and When

Phase 0 — Resolve the Deployment Profile

From the Project Profile §Deployment (add the section if it's missing — see the template). What you need before anything else:

This section is normally empty the first time you run — most projects have never written down how they ship. That is expected, not a failure: this invocation is the first moment anyone has a concrete reason to answer. So gather it here, now, in one short pass:

• Ask only what this run needs. Deploying to staging does not require production's rollback story.

• Prefer reading over asking. Most rows are already written down somewhere in the repo — ${CLAUDE_SKILL_DIR}/references/profile-rows.md names which file usually answers each one.

  Ask only for what none of these can say: who is allowed to fire production, where production secrets actually live, the rollback they would really perform under pressure, and the critical path worth verifying afterwards.

• A row nobody can answer yet is pending: <when>, not a guess. The exception is rollback: you cannot deploy without one, so if it's unknown, resolving it is the next step (Constraint 4).

• Write what you learn back to the profile so the second deploy asks nothing.

For a project that has never shipped anything, these are decisions, not discoveries — propose an option with a one-line rationale (hosting model follows from the app shape more than from taste), and record it once the user picks.

Phase 1 — Readiness Gate

Answer each with yes / no / n-a. Any "no" stops the deploy and is stated plainly.

• Gates green? The profile's full pipeline passed on this change set — not a similar one, not yesterday's (module-gate-battery, run by implementing-architect).
• Reviewed? code-review-architect ran and its Criticals and Highs are resolved, or explicitly accepted by the user in writing.
• Propagation protocols run? If shared shape, a public API, or an external origin changed, the module-propagation protocols A/B/C completed. These are the change classes that pass CI and break in production.
• Production build, not a dev build? Built with the production configuration, correct base path, optimizations on, source maps handled per policy.
• Changelog current? rolling-history ran; the release has a written record of what's in it.
• Version decided? Per the project's scheme, and consistent everywhere it appears (manifest, lockfile, app-visible version string, container tag).
• Migrations reversible or forward-compatible? See Phase 3 and its reference.
• Rollback plan written? Constraint 4. Hard gate.

Phase 2 — Release Preparation

1. Version — bump per the project's scheme. Every place the version appears moves together (this is a change-propagation problem; treat it as one).
2. Release notes — derived from the changelog, written for whoever reads them: users get behavior changes, operators get required actions (a new env var, a migration to run, a cache to purge). Never invent a fix or feature that isn't in the diff (Guidelines §15).
3. Breaking changes named explicitly, with the migration path for consumers. If this ships a breaking change without one, that is a finding, not a footnote.
4. Artifacts — what actually ships: bundle, image, package, binary. Note the size and how it moved. A sudden jump is a dependency mistake caught cheaply here.
5. The commands — assemble the exact sequence, in order, ready to copy. No placeholders left unresolved.

Phase 3 — Pre-Flight Risk Pass

The failure classes CI structurally cannot see — per-environment config and secrets, pre-existing data and migrations, caches that outlive the deploy, external origins and policy, runtime compatibility, and blast radius. Each is yes/no/n-a; any yes is a finding with severity, and a clean category is stated clean rather than omitted.

Read ${CLAUDE_SKILL_DIR}/references/preflight.md and work through it. Skipping this phase is how a green pipeline ships an outage.

Phase 4 — The Rollback Plan (written before deploying)

Not optional, not "revert the commit". Answer all four:

1. Trigger — what observation makes us roll back? Name the signal and the threshold, decided now, before the pressure.
2. Mechanism — the exact command or steps, resolved and copy-ready.
3. Time to recover — realistically, how long from decision to restored service?
4. What rollback does not undo — the honest part. A code rollback does not un-run a migration, un-send an email, un-charge a card, un-invalidate a cache, or clear a service worker on a user's device. Anything on this list is a one-way door and must be named before the deploy, not discovered after.

If a one-way door exists and can't be avoided, say so explicitly and let the user decide with that in hand.

Phase 5 — Handover

You assemble; the user fires (Constraint 2). The shape, the resolve-every-placeholder rule, the never-print-a-secret rule, and the what it does / how you know it worked lines are in the module-handover skill. Load it and emit the runbook in that shape.

Two things this phase adds on top of the module:

1. State the target environment and what is shipping in one line at the top, so the person pasting cannot be on autopilot about which environment they are in.
2. Say what to watch during the deploy, not just its exit code — the platform reporting success is not the app being healthy. Name the signal.

Then stop. If a step fails when the user runs it, they come back with the output and you diagnose (debugging-architect) — never improvise past a failed deploy step on their behalf.

Phase 6 — Post-Deploy Verification

Runs after the user reports the deploy landed, against the real environment — never against local state or a green CI run. Uses only the reversible checks Constraint 3 already permits.

Read ${CLAUDE_SKILL_DIR}/references/post-deploy.md for the procedure and the symptom→cause table for things that break only in a deployed environment.

State the verdict plainly: verified, rolled back, or watching with what you're watching and for how long. If verification fails, the decision is rollback (Constraint 8) — production is not a debugging environment.

Rollback Mode

Invoked with "roll back". Skip straight to it — the readiness gate is irrelevant when something is already broken.

1. State the current symptom in one line. Don't diagnose first; restore first.
2. Hand over the rollback command from the plan — resolved, copy-ready, one step (module-handover §4), or resolve it now if no plan exists. A rollback is a production write, so it is the user's to run under Constraint 2; speed comes from the command already being correct, not from you typing it.
3. Verify recovery with the same health check and critical path.
4. Name what rollback did not undo and what still needs manual repair.
5. Only then investigate cause. Write the finding into the changelog and, if it's a recurring class, into the profile's blind spots so the next release checks for it.

Quality Checklist (before claiming "Deployed")

• Deployment profile resolved; no invented commands, hosts, or env vars.
• Readiness gate answered in full; any "no" surfaced rather than worked around.
• Pre-flight risk pass covered every category; clean ones explicitly noted clean.
• New env vars enumerated and confirmed present in the target, not just locally.
• No secret printed, logged, or embedded in a shipped artifact.
• Migration reversibility and ordering assessed; backup/restore point confirmed where state changes.
• Cache and service-worker behavior considered — including its effect on rollback.
• Rollback plan written before deploying, with the one-way doors named honestly.
• Nothing outward-facing was executed — the deploy, migration, publish, or rollback was handed over as a runbook (Constraint 2).
• Every runbook step is copy-ready per module-handover: no unresolved placeholder, each with what it does and how the user knows it worked.
• Post-deploy verification run against the real environment after the user reported it landed, including one real user path.
• Verdict stated plainly: verified / rolled back / watching.
• No git add, commit, push, or tag — every git operation left to the user.

When to Use This Skill

• After code-review-architect passes and rolling-history has logged the change — the last stage of the pipeline.
• To assess readiness well before the release, when findings are still cheap to fix. (Every run is "prepare only" — this skill never deploys.)
• To produce the rollback command for a release that's misbehaving, fast and correct, for the user to run.
• To write the Deployment section of a Project Profile for a project that has never documented how it ships.

v1.0 — version history in CHANGELOG.md