dasha-ws/ai-dev-framework/deploy

deploy

Purpose

/deploy performs the actual delivery of one accepted work item to one real deployment target, after /deploy-check has passed for that work item, that target and that version. It answers one question:

"Is the checked version now delivered to this target and verified, and what exactly is the target's state?"

/deploy-check stays the readiness gate. /deploy is the executor: it works on the real environment, determines the target, the source being deployed and the deployment access, delivers or updates the application through the established mechanism, then verifies the result and records what it confirmed. It is not a reviewer, issues no readiness PASS or FAIL, repeats no security or infrastructure review and calls no reviewer-agent. It is not an architect: it does not choose or change the deployment mechanism, and it does not author repository code or deployment artifacts.

Operations.

• Deliver: a first deploy or an update of an existing deployment. Mutating. Needs an applicable /deploy-check PASS, with no bypass for small changes.
• Status and logs: fully read-only. They change no project file and nothing on the target, infrastructure.md included. If they show that reality differs from infrastructure.md, they only report that the context may be stale. No /deploy-check needed.
• Rollback: recovery of an existing deployment by an already known and applicable rollback procedure. No new /deploy-check, because it is not a new release. It is never a way around the pipeline for a new version.

Source of truth.

• The current /deploy-check PASS, as established in step 3, and the work item and target it covers.
• infrastructure.md: the approved infrastructure facts (including the deployment mechanism) and, per target, the actual deployed state. It is the one canonical context. Nothing else is created.
• The approved sources for what is deployed: the Tech Spec, architecture.md, development.md, the repository's deployment artifacts and documentation. /architecture owns the choice of a deployment mechanism. The Tech Spec only describes how an already accepted mechanism is implemented.
• The real target, inspected read-only before any change.

Gate state. A /deploy-check PASS counts only if the current conversation establishes it, the user explicitly confirms it, or the workflow ledger .claude/work/status.md has a deploy-check row for this work item and target (subject <id>@<target>) that powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%USERPROFILE%\.claude\ai-dev-framework\scripts\workflow-state.ps1" check reports FRESH (see templates/work/status.md), never from git history, timestamps or file existence. This skill writes no ledger row. Its single confirmation before the first change is never recorded: it is asked afresh on every run, and no earlier approval or PASS replaces it.

When to use

• After /deploy-check PASS, to deliver the checked version to the checked target.
• To read the status or logs of an existing deployment.
• To roll an existing deployment back by a known procedure.

When not to use

• The current directory is the ai-dev-framework repository itself. It is the source of the framework, not a target. If its root contains the framework's own skills/ folder, stop and ask which project the user means.
• The framework structure created by /init-project is missing: stop and suggest /init-project.
• A deliver is requested without an applicable /deploy-check PASS: stop and route to /deploy-check (step 3).
• /deploy-check reported No deployment/release action required: there is nothing to deploy.
• The deployment mechanism is unknown, or must be chosen or changed: that is an infrastructure decision of /architecture (step 4).
• The request spans several targets or several work items.

Inputs

• Target project root. Default: the current working directory. Confirm it if in doubt.
• The operation, the work item and the one target (steps 1 and 2).
• For deliver: the applicable /deploy-check PASS (step 3) and the source, ref or version it covers (step 5).
• The framework structure created by `/init-project`, including infrastructure.md.
• Deployment access: the user's own SSH setup, ssh-agent or ssh-config, or whatever access the mechanism uses. Never private key contents.
• The user, for the few decisions only they can settle, for the plan confirmation (step 8) and for entering secret values themselves (step 6).

Files to read

Read selectively and read-only. Never read, print, log or store a secret value, and never read private key contents. A real .env or other secret-bearing configuration is not opened for its content or shown. Where a deployment step really needs it, only its configuration names or keys may be checked, in a way that exposes no value.

• the root CLAUDE.md, the project-context router, infrastructure.md, and development.md and architecture.md where they bear on delivery;
• the work item's Tech Spec, where there is one, and the deployment artifacts and documentation of the repository that the mechanism uses (service definitions, startup scripts, .env.example, runbooks);
• git state, read-only (git status --short -uall, the current ref), only to identify the source being deployed.

Execution steps

1. Confirm the project and the operation

Check the working directory and the structure (see "When not to use"). Decide the operation: deliver, status and logs, or rollback. If a project instruction conflicts with a framework rule, stop and ask.

2. Determine the target

Exactly one target per run: production, staging, a particular VPS or another explicitly defined target. If it is not unambiguous, ask. Never choose one yourself, and never apply anything to another target. Everything is kept apart per target: host, project path, service, .env, runtime, credentials, persistent storage, database facts, procedures and deployed-state facts. infrastructure.md holds target-specific facts under the target's name. No target registry is created.

3. Establish the gate (deliver only)

A current /deploy-check PASS must be established for this work item, this target and the version that will be deployed. If it is absent, not established, a FAIL or BLOCKED, or for another work item or target: stop → /deploy-check → /deploy. If it is reliably known that implementation, deployment artifacts, the target or a material deployment condition changed after the PASS, it no longer applies: stop, deploy nothing, → /deploy-check. Do not ask for a ritual confirmation if the conversation or a FRESH ledger row already establishes the PASS.

4. Establish the mechanism and the known facts

Read infrastructure.md. Separate:

• Approved infrastructure facts, which may exist before any deployment: the chosen mechanism, the hosting model, constraints. They are inputs and are never changed here.
• Actual deployed state of this target, which exists only after a real deployment: paths, service or process identifier, runtime, env location and confirmed procedures.

Rules:

• The documented mechanism is used as it is. Do not reopen it, migrate it, or offer Docker Compose or systemd as a default or "for convenience".
• If no mechanism is known, or one has to be chosen or changed, you do not choose it: stop and send the user to /architecture. The mechanism must be known by the time /deploy-check passes.
• If the mechanism is one this skill does not know how to execute safely, stop and state the limitation. Follow its documented, approved procedure where there is one. Never improvise a new deployment model on the spot.
• If the mechanism needs repository-managed artifacts (a service definition, deployment config, .env.example, a startup script) that do not exist, stop. They go through the normal pipeline (/architecture where a decision is needed → /tech-spec → /review-spec → /build-feature → … → /deploy-check). Do not write them during a deploy and do not generate repository architecture on a server. A mechanism that works without repository artifacts is fine.
• First deploy if there is no actual deployed state for this target and inspection (step 7) confirms nothing is deployed. Update if the facts exist and inspection confirms that deployment. If the facts and the real target disagree, do not fit either to the other: stop and show the discrepancy.

5. Identify the source (deliver only)

Determine the source, ref or version that will be deployed. It must be the one the PASS covers. Show it to the user with the target. If the mechanism needs a ref to exist where the target can fetch it and it is not there, tell the user: you never run git push, git add or a commit. Nothing is stored to prove identity: the conversation and the user's confirmation are the record.

6. Access and credentials

Deployment access. The user provides it through their own existing SSH setup. Never ask for, read, store or print private key content. Check by a safe successful connection. Never disable host-key verification (StrictHostKeyChecking=no or the like) as a workaround: an unverified host key is something the user verifies and accepts themselves. Do not change global SSH or sudo configuration, or server security configuration, without a separate decision of the user. Use elevated privileges only for a step that really needs them.

Runtime external credentials (API tokens, bot tokens, database credentials, third-party keys). Onboarding belongs here, at the moment it is really needed, and is not repeated in specs or context. Take the names and purposes from what the approved sources already state. For each credential needed, explain briefly: what it is and why it is needed; where it is created or obtained; which credential exactly; where on the target to configure it; what must never be committed; how to check safely that it works. No provider is special: a bot platform is an example, not a rule.