Initial Deployment

The bridge from deploy-ready to running. Scaffolding wrote the deployment configs, environment parameterization, and CI — and stopped, by contract, at "the initial deployment is the user's step." This skill is that step, with the same character as scaffolding: real execution against live reality, empirical verification, honest notes, and checkpointed progress that never blindly re-provisions.

Three principles govern it:

1. The target is an input, never a decision. The architecture's ADRs and deployment view chose the cloud/platform and topology; this skill reads and executes them. Gaps (a region never stated, a service tier unnamed) are elicited — and flagged as candidate architecture amendments. The process is cloud-agnostic; the run is cloud-specific; CLI names, flags, and console steps are verified against live provider docs at run time — never recited from memory (they drift faster than generators do).
2. Money and credentials get gates. Provisioning creates billable resources: the deployment plan (what gets created, environments, rough cost class) is played back for one explicit confirmation before anything is created. Credentials stay in the user's hands: the skill preflights that the provider CLI is authenticated and blocks with instructions when it isn't — it never asks for, stores, or writes a credential or secret value anywhere (configs reference secret stores; values enter those stores through the provider's own mechanism, user-driven).
3. Deployed means demonstrated. The run ends with the system observed live: the skeleton's end-to-end path exercised against the deployed environment (closing the done-when's pending deployed half), CD proven by an actual pipeline-driven deploy, restore actually performed once — claims are exhibits, observations are evidence.

When to run

Recommended early — right after scaffolding, deploying the walking skeleton itself: that's the walking-skeleton philosophy (prove the system deploys before features pile on), and it makes every later feature continuously deployable. Running later, after features exist, is fully supported — the same process deploys whatever the repo currently holds, and Phase 8 is more valuable then (accumulated pending-environment NFRs finally become measurable). Say the trade-off plainly when features exist: this first push ships N features' worth of system at once, so a failure has many more candidate causes than an early skeleton deploy would — and the E2E exercise in Phase 6 covers the whole current suite accordingly.

Inputs

Defaults; user paths win; source-gated citation throughout.

• Architecture — docs/architecture.md: the deployment view and the ADRs naming the target platform, topology, environments, and data stores (cite them). Cross-cutting concepts for the security/observability posture the deployment must honor.
• The repo — the deployment artifacts scaffolding wrote (Dockerfiles, service configs, IaC skeleton, environment parameterization, CI config) and docs/scaffold-notes.md (what's pending, exact commands, versions).
• The plan — docs/implementation-plan.md: the walking skeleton's done-when (its deployed half is this skill's to close).
• Acceptance reports — docs/features/*/acceptance-report.md (when features exist): the pending-environment NFR items now measurable.
• SRS — docs/srs.md, light touch: NFRs constraining the deployment itself (residency, availability topology, compliance), cited by ID.
• RTM: no writes. Deployment realizes infrastructure, not requirements. Pending-environment measurements are recorded in deployment-notes; formally updating acceptance reports and the RTM stays acceptance-verification's jurisdiction (re-run it now that the environment exists).

Outputs

1. The running system — provisioned environments, deployed build, CD wired so the pipeline ships future merges per the architecture's cadence.
2. docs/deployment-notes.md — the project-owned record: what was provisioned (with provider identifiers), environment URLs, the exact deploy/rollback commands, secret-store locations (never values), pending- environment measurement results, costs observed/expected, deviations from the deployment view (and their reasons).
3. Closed pending items — the skeleton done-when's deployed half demonstrated; pending-environment NFRs measured, with a recommendation to re-run acceptance-verification for formal verdicts.
4. One narrow write into docs/scaffold-notes.md — scaffolding's artifact, and the only foreign document this skill touches: the pending marker it left ("deployed half: pending initial deployment") is closed in place, with date and evidence. Nothing else in that file is edited — the marker was written to be closed by exactly this run; every other record of this deployment lives in deployment-notes.

Workflow

Phase 0 — Resume check (always first)

Read references/deployment-guide.md (Checkpointing). Look for docs/.deployment-progress.md and live signs of partial provisioning. Partial → never blindly re-provision: summarize what exists (verified against the provider, not just the tracker), confirm, resume idempotently at the first pending step. Provisioning found that the tracker can't account for → stop and ask; this skill never assumes ownership of infrastructure it can't explain.

Phase 1 — Ingest and confirm the deployment plan (the money gate)

Extract the deployment contract: target platform (ADR-cited), topology per the deployment view, environments to create, stores to provision, domain/TLS expectations, CD trigger (merge? tag?). Elicit only genuine gaps (region, tier/size — flag architecture-level gaps as candidate amendments). Play back the deployment plan: what gets created where, the rough cost class, what the first deployed artifact will be — and get explicit confirmation. Nothing billable exists before this nod.

Phase 2 — Preflight (credentials and tools)

Provider CLI present and authenticated as the user — if not, a blocking ask with pointers to the provider's current auth setup (verified against live docs), then re-check. Required tools at needed versions. The skill never touches credential values; authentication is the user's, session-ambient.

Phase 3 — Provision

Execute the repo's deployment artifacts per environment, in dependency order (network/foundation → stores → services), checkpointing each unit. Live-verify CLI specifics before first use. Deviations between the deployment view and provider reality are handled conform-or-escalate: trivial realization details → do and record; topology-changing → architecture amendment path.

Phase 4 — Configuration and secrets, made real

First ask how deployed configuration is supplied on this platform: plain platform config for everything, the secret store for everything, or the split (non-secrets in config vars, secrets in the store — the templates' secret markers are the divide). Recommend the split, honestly: secret stores usually charge per secret or per access and add rotation/audit machinery LOG_LEVEL doesn't need, while plain config vars for genuinely sensitive values give up the audit trail. The user's answer wins; record it in deployment-notes so re-runs and future operators know how the project is wired.

Then reconcile before deploying: union the deployable units' config templates and compare against what the target environment actually has. Anything missing blocks the deploy — with the exact list and the provider-native steps to set each one. This turns the worst deployment failure mode (green pipeline, dead service, confusing boot logs) into a pre-flight message.

Then make them real per the chosen mechanism: create the entries/references, wire the services to read them, and hand the user the exact provider-native steps to enter each value out-of-band. Verify wiring with a non-secret canary first. No value ever appears in a file, a note, chat, or a shell history this skill writes.

Phase 5 — CD: the pipeline ships

Extend the green CI to actual delivery per the architecture's cadence: deploy-on-merge to the lower environment, promotion per the deployment view (tag/manual gate to prod as specified). The proof is empirical: a real pipeline run observed deploying.

Phase 6 — Deploy and close the skeleton's done-when

Ship the current build through the pipeline. Then exercise whatever end-to-end suite the repo currently holds against the deployed environment: always the skeleton's path — the same test, live — and, when features have extended the suite, the feature E2E paths too (point the suite at the deployed URL where the harness supports it; otherwise the documented smoke equivalent, said plainly). State the skeleton result against the plan's done-when wording: its deployed half, finally demonstrated (record it in deployment-notes and scaffold-notes' pending item). A red in a feature's E2E path is a deployment finding, not a skeleton failure — report it, and route a genuine feature failure in the live environment to acceptance-verification (re-run it there); this skill measures, the auditor rules.

Phase 7 — Minimum operations (folded in, not deferred)

Read references/operations-minimum.md. A deploy without eyes is negligent: uptime check on each public surface, error alerting wired to a channel the user actually reads, logs reachable, backups configured and restore performed once (a backup never restored is a hope), TLS/domain per the architecture. Fuller day-2 operations remain a later concern; this floor is not optional.

Phase 8 — Pending-environment NFRs

From the acceptance reports' pending-environment lists (when present): run the measurements now possible against the real environment (response-time bounds, availability probes as feasible), record results in deployment-notes with environment context, and recommend re-running acceptance-verification for the formal verdict/RTM updates — jurisdiction stays with the auditor.

Phase 9 — Verify and deliver

Read references/verification.md — everything demonstrated live. Then deliver: URLs per environment, the exact deploy and rollback commands, what it costs (observed/expected), what's pending (items genuinely deferred), and the handoff: the loop continues with every future feature now continuously deployable; recommend acceptance-verification re-runs for the measured NFRs.

Scope boundaries

Does not: choose or change the platform/topology (architecture's job — gaps go back as amendments); handle credential or secret values; build features or fix code; perform full day-2 operations (the minimum floor only); write the RTM; write any other skill's artifacts beyond closing scaffold-notes' own pending marker (Outputs 4).

What good looks like

• Everything created traces to the deployment view/ADRs; every deviation is recorded with its reason — or escalated.
• The confirmation gate preceded every billable creation; the user was never surprised by a resource or a bill.
• The skeleton's done-when reads fully closed — local half (scaffolding) and deployed half (here), both demonstrated.
• Restore was performed, not assumed. Alerting reached the human once, as a test.
• deployment-notes lets a cold session (or a human) operate the deployment: URLs, commands, rollback, secret locations — no tribal knowledge.
• A revoked credential or missing tool produced a clear blocking ask — never a workaround, never a stored secret.