deploy-strategy

---
name: deploy-strategy
description: Use when a product is ready to ship, OR when the user directly asks how or where to deploy or to write a deploy runbook - chooses a deploy strategy with the owner in cost-and-consequence terms, then executes it into a repeatable runbook. Self-checks on disk for a fixed release version first — it warns and offers to fix it, it does not block.
---

## Overview

This is phase 8 of the SPP pipeline, but it can also be invoked standalone whenever a product is ready to ship or the owner directly asks how or where to deploy. The release is versioned, tagged, and described — now it has to actually go somewhere the owner's users can reach it. This is the one phase where SPP touches production, and the two steps are not equally weighted: choosing *how* to deploy this specific product is the real work; executing the choice is following a playbook.

Step 1 is deliberately not "pick a hosting provider." It's a decision about ongoing money and ongoing effort that the owner has to live with for the life of the product — same shape as `stack-selection` in phase 3, but now the stakes are real: this isn't a plan on paper, it's what happens when someone actually uses the thing. Options get framed the way `stack-selection` frames them — dollars, update effort, what breaks — never as infrastructure jargon on its own. Step 2 then executes against a reference playbook keyed to `product_type`, but "playbook" means reference material to draw on, not a rigid recipe to follow blind; the specific product still dictates specific choices within it.

Three invariants govern step 2 regardless of which playbook applies, and violating any of them is a defect, not a style preference: secrets never enter git, the deploy has to be repeatable from what's in the repo, and the must-scenarios get smoke-tested on production with evidence before the gate. That last one is the same verification discipline that has run through the whole pipeline — it doesn't stop at the branch boundary just because the target is now a live server instead of a laptop.

The phase's closing gate has two modes, and which one applies is a real decision, not a formality. **`executed`** is the mode described above: a real deploy, a production smoke test, evidence shown at the gate. **`deferred`** exists for exactly the case where the owner wants the strategy locked in and the runbook ready, but isn't deploying yet — a real, legitimate outcome, not a lesser one. Deferred does not require live evidence, because there is no live deployment yet to gather evidence from; what it does require is the same rigor in choosing and documenting the strategy as executed does. Whichever mode closes the gate gets written to `deploy_status` in state, and `post-release` (phase 9) reads it before deciding whether to treat the product as live.

## Process

### 0. Confirm the trigger and read state

This skill runs standalone: when a product is ready to ship, or when the owner directly asks how or where to deploy, or asks for a deploy runbook. No pipeline phase gate is required to start. If `docs/spp/pipeline-state.md` exists, read it for context and inputs:

- `product_type` and `stack` from the state file — what's being deployed and what it's built with.
- `docs/spp/00-idea-brief.md` — budget.
- The `jurisdiction` fields (`jurisdiction.users`, `jurisdiction.author`) from `pipeline-state.md`, filled by `product-discovery`, for data-residency constraints.

If the pipeline-state journal exists, write `current_phase: 8`, `phase_status: in_progress` on starting work. If it doesn't exist, skip the state update — this skill still runs standalone without it.

Steps 1-3 below are **Step 1 — choose the strategy** (the phase's main value); steps 4-8 are **Step 2 — execute**.

### 0.5. Pre-deploy self-check

Run this before choosing a strategy. Check ON DISK:

- Is there a fixed release version? (`docs/spp/07-release-notes.md` exists with a
  semver version recorded.)
- If NO: warn the user — deploying without a fixed version means not knowing what
  exactly is being shipped. Offer to fix the version first via `release-fixation`.
  Proceed only on the user's explicit choice.
- If YES: proceed.

This reads the file directly, not pipeline-state.md.

### 1. Gather inputs

Collect what the decision depends on:

- `product_type` and `stack` — already in state, read them, don't re-ask.
- Budget — already in the brief, read it, don't re-ask.
- **The owner's existing accounts and infrastructure.** Ask this directly — do they already have a hosting account, a domain, a server, a cloud subscription they're paying for and want to reuse? **Assume nothing here.** Defaulting to "they probably have nothing" or "they probably already have a VPS" are both guesses that can send the whole recommendation sideways; ask instead of picking one.
- **Jurisdiction's data-residency requirements** — from `jurisdiction.users` and `jurisdiction.author` in `pipeline-state.md` (filled by `product-discovery`). Some jurisdictions require user data to stay hosted within the users' region; check before proposing options, not after the owner has already picked one that turns out to be non-compliant.

### 2. Propose 2-3 options in owner language

Draft two or three concrete deploy options for this `product_type` and `stack`. For each, and for the comparison between them, state the trade-off the way the owner experiences it, not the way an engineer would describe it:

- **$/month now, and $/month at scale** — what it costs at MVP-sized traffic, and what happens to the bill if usage grows.
- **Update complexity** — is shipping a change one command, or a multi-step ritual the owner has to remember or pay someone to do?
- **Vendor lock-in** — how hard is it to leave this option later if it stops working out?
- **What breaks under a traffic spike** — does it fall over, get expensive, or just work?

Technical terms are allowed, but exactly as in `stack-selection`: every one needs a consequence attached. "A managed platform with autoscaling" is not an option description; "handles a traffic spike automatically, costs more per request when it does" is.

### 3. Gate

Present the options and ask the owner to pick one. This is a decision about money and ongoing maintenance, not a technical one — no infrastructure jargon without a consequence attached, no diff, nothing that requires the owner to already know what the words mean. Alongside the strategy pick, ask the second question this gate actually decides: deploy it now, or lock in the plan and runbook and hold off on going live? Both are legitimate answers — don't frame deferring as the lesser or incomplete option. While the question is outstanding, `phase_status: gate_pending`.

- **On a pick:** write the chosen strategy to `deploy_target` in the state file, log the decision in the Decisions log (date, phase 8, the chosen deploy target, who picked it, and whether the owner wants to deploy now or defer).
- **On requested changes:** if the owner wants a trade-off explained differently, or their answer to step 1 (existing accounts, budget) changes, revise the options and re-ask.

Steps 4-5 below apply either way — the playbook and the invariants shape the runbook regardless of whether the deploy happens now. Step 6 and the gate in step 7 branch on the owner's answer: executed if deploying now, deferred if not.

### 4. Follow the reference playbook for this product_type

Use the playbook matching `product_type` as reference material — a set of options and considerations to draw on, not a script to execute verbatim. The specific product, stack, and owner's existing infrastructure from step 1 still shape the actual choices made within it.

- `web` → `references/web-apps.md`
- `package` → `references/packages-and-plugins.md`
- `tg-bot` → `references/telegram-bots.md`
- `mixed` → consult whichever playbooks match the components actually being deployed; a mixed product might need more than one.

### 5. Hold the invariants

These are non-negotiable regardless of which playbook applies. Violating any one of them is a defect:

- **Secrets never go in git.** Not in a config file, not in a comment, not in a "temporary" commit meant to be reverted later. Use the mechanism the chosen platform provides for secrets (environment variables, a secrets manager, platform-level config) and reference it in the runbook by description, never by value.
- **The deploy is repeatable.** A script or a config file in the repo has to be able to reproduce this deploy from scratch. A deploy that only exists as a sequence of manual clicks the agent remembers is not repeatable, and the owner can't reproduce it either.
- **After deploy, a mandatory smoke test of the must-scenarios on production, with evidence.** This is the same verification discipline that governs the rest of the pipeline, applied to the live product. Pull the must-scenario list from `docs/spp/02-mvp-scope.md` and confirm each one against the actual production deployment — not the dev environment, not a recollection of the acceptance demo. Capture what you observed (output, screenshot, response) as evidence; "I deployed it, it should work" does not satisfy this step.

**When an invariant genuinely doesn't apply, mark it N/A with a stated reason — never silently skip it.** A secretless static product (no backend, no API keys, no user data at rest) has nothing for the secrets invariant to protect; write "secrets: N/A, this product has no secrets" in the runbook rather than leaving the section blank or, worse, inventing a secrets story to fill it. The same applies to any invariant that assumes state this specific product doesn't have. N/A is a documented judgment call, not a loophole — it requires the actual justification, not just the label. **Under `deploy_status: deferred`, the production smoke test does not run now** — there's no live deployment yet to test against — it moves to the moment the deploy actually happens; the runbook says so explicitly rather than pretending the invariant was satisfied early.

### 6. Write the artifact

Write `docs/spp/08-deploy-runbook.md`. What it contains depends on which mode step 3 landed on:

**If `executed`** (deploying now):

- How the product is deployed — the mechanism, not a jargon dump.
- How to update it — the actual steps or command for shipping a future change.
- How to roll back — what to do if a deploy goes wrong.
- $/month — the actual figure at current scale, from the chosen option in step 2.
- Where secrets live — a description of the mechanism and location (a named environment variable in the hosting platform's config panel, for example), never the secret values themselves — or the N/A justification from step 5 if this product has none.

**If `deferred`** (strategy chosen, deploy postponed):

- The chosen strategy and why, same content as the `executed` runbook's deployment-mechanism section, but written as instructions to follow **when** the deploy happens, not a record of what already happened.
- The exact steps to execute at deploy time — this is the runbook the owner or agent follows later; it has to be complete enough to act on without re-deriving the decision.
- $/month, expected — the figure from step 2, labeled as an estimate for when the deploy happens, not a bill already being paid.
- Where secrets will live — the mechanism and location, same as `executed`, described in advance of there being any actual secret value yet — or the N/A justification from step 5.
- **An explicit note that the production smoke test has not run and moves to actual-deploy time.** State this plainly; do not let the absence of a smoke test read as an oversight rather than a deliberate consequence of deferring.

### 7. Gate

The question and what it accepts depend on the mode from step 3:

**If `executed`:** ask the owner **"Product is live at [address/command] — production scenarios verified, here's the evidence — accept?"** Show the smoke-test evidence from step 5, not just the claim that it was done. On acceptance, write `deploy_status: executed` to state.

**If `deferred`:** ask the owner **"Strategy chosen, runbook ready — deploy is postponed for now. Accept the plan as-is?"** This gate requires no live evidence — there is nothing live yet to show evidence of — but it does require the runbook to be genuinely complete and actionable, not a placeholder for future work. On acceptance, write `deploy_status: deferred` to state.

<HARD-GATE>Do not present a `deferred` runbook as if it were `executed`, and do not ask the `executed` gate question ("product is live") when no deploy has actually happened. The gate question and the state written must match the actual mode chosen in step 3 — conflating them means the owner accepts a claim about production that isn't true.</HARD-GATE>

While either question is outstanding, `phase_status: gate_pending`.

- **On acceptance (either mode):** set `phase_status: approved`, log the decision in the Decisions log (date, phase 8, the mode, deploy accepted or deferred, the live address if executed, who accepted it).
- **On requested changes:** if `executed` and a must-scenario failed the smoke test, or the owner spots something wrong once they look at the live product — fix it, redeploy, re-run the smoke test, and re-ask. Do not soften the gate to "should be fine now" — re-verify with fresh evidence. If `deferred` and the owner wants the runbook adjusted, or actually wants to deploy now after all, revise accordingly (a `deferred` gate can flip to `executed` mid-conversation if the owner changes their mind — go back to step 4's playbook and step 5's live smoke-test requirement in that case) and re-ask.

### 8. Hand off

This skill's job ends at a release that's either deployed-and-verified (`executed`) or strategy-locked-and-documented (`deferred`). Do not start monitoring or feedback-loop setup yourself. Hand off `deploy_status` along with everything else — `post-release` reads it to decide whether the product is actually live. The explicit next-step transition for the owner is in the closing **Next step** section of this file.

## Red Flags

| Thought | Reality |
|---|---|
| "They're probably a solo hobbyist with nothing set up, I'll just recommend the free tier" | Existing accounts and infrastructure must be asked about, never assumed. Guessing wrong here means recommending a redundant new account, missing a compliance-relevant constraint the owner's current setup already handles, or ignoring money they're already spending. |
| "I'll drop the API key straight into the config file, it's just for now" | Secrets never go in git, full stop — there is no "just for now" exception. Use the platform's secrets mechanism and reference it in the runbook by description, not by value. |
| "I clicked through the hosting dashboard to set this up, it's live, good enough" | The deploy has to be repeatable from a script or config in the repo. A sequence of manual clicks that only exists in the agent's memory can't be reproduced by the owner or by the agent itself next time — that's a defect, not a shortcut. |
| "The acceptance demo already showed this works, I don't need to re-test on prod" | The smoke test after deploy is mandatory and separate from the acceptance demo — a working branch and a working production deployment are different claims. Verify the actual must-scenarios against the actual live deployment, with evidence, before the gate. |
| "I'll describe the options as 'serverless vs a VPS with a reverse proxy'" | Every option must be phrased in $/month, update effort, lock-in, and spike behavior — the same owner-consequence discipline as `stack-selection`. Infrastructure jargon without an attached consequence tells a non-developer nothing they can decide on. |
| "The playbook says to use provider X, so that's what we're using" | The reference playbooks are material to draw on, not a rigid recipe — the actual choice still depends on this product's stack, budget, and the owner's existing infrastructure from step 1. Following a playbook blindly can contradict what step 1 already established. |
| "We're deferring, but I'll phrase the gate as 'product is live' so the owner feels progress" | The gate question must match `deploy_status`. Asking "is it live" when nothing is deployed makes the owner accept a false claim about production — that's the exact dishonesty the verification discipline elsewhere in this pipeline exists to prevent. |
| "This product has secrets somewhere probably, I'll just write something plausible for the runbook's secrets section" | N/A requires a real, stated reason ("this product has no secrets") — never a filled-in placeholder to make the section look complete. If you're not sure whether the product has secrets, that's a reason to check, not a reason to guess and write it down. |
| "Deferred means we skip the smoke test entirely, no need to mention it again" | Deferred moves the smoke test to actual-deploy time — it doesn't cancel it. The runbook has to say so explicitly, so a future reader (owner or agent) knows the test is still owed, not silently waived. |

## Next step

When this stage is complete, tell the user in their own language that:
- this stage is done;
- the next logical step is the `post-release` skill;
- they should start it in a fresh chat so that skill gets clean context.

Do not auto-invoke the next skill. The user drives the transition — offer, do not proceed.

• SKILL.md 17 KB
• references/packages-and-plugins.md 7 KB
• references/telegram-bots.md 7 KB
• references/web-apps.md 7 KB