Skip to content

skill · phase: deployment

Deployment Phase

Purpose

Prepare and execute the release. Ensure all preceding phases are complete, all gates pass, and the deployment itself is safe and reversible.

Entry Criteria

  • All preceding required phases have status complete in .aidlc/state/<instance>/
  • Testing phase complete with all tests passing
  • The review findings file has no open critical security finding (the adversarial review's security dimension is the sign-off; no template configures a separate security review phase)
  • The instance is claimed by this session

Entering in a fresh session

Start deployment in a fresh session. This phase has the most to gain from it of any in the lifecycle: it averages 395k tokens per unit of work and is the single most expensive phase — ahead of implementation — not because it does more, but because it runs last and inherits every phase before it.

Read only:

  • instance.yaml and the phase-*.yaml files — what is complete, and what this phase must assert
  • test-results.md — the pass/fail record the release depends on
  • the review findings file — the security sign-off named in the entry criteria above
  • tasks.md — deferred tasks belong in the deployment record

Not requirements.md, not design.md, not code-complete.md. The release is prepared from what the preceding phases concluded, and each of those conclusions is already a compact artifact. Read one of them only if a specific question sends you there. See The context rule in aidlc-overview.

Required Artifacts

The artifacts your template's deployment phase declares in required_artifacts — deployment-record.md for every built-in template. Read phase-deployment.yaml in the instance state dir if unsure. Whatever the filename, the content is the release plan, rollback strategy, and deployment checklist.

Instructions

{{glossary:gate}} {{glossary:artifact}}

  1. Load guidance. Read the always-read guidance layers from .aidlc/guidance/index.yaml — see The always-read rule in aidlc-overview for which layers those are and when to reach for the full lessons.md.
  2. Validate readiness. Check the phase state files: every preceding required phase must be complete (all required artifacts complete). If any gate fails, address the gap before proceeding. (CLI shortcut: aidlc gate <instance> deployment — the phase name is the second argument, not the first.)
  3. Write release plan. Document in the phase's required artifact (see Required Artifacts above):
    • What is being deployed (version, changes summary)
    • Target environment(s)
    • Deployment steps in order
    • Rollback procedure
    • Monitoring and verification steps post-deploy
  4. Update the affected topic page in docs/. If this instance changed how a documented topic behaves — its interface, its failure modes, or the reason it is built the way it is — update that topic's page before releasing, and say in the deployment artifact which page you touched or that none applied. The manifest at docs/index.yaml maps each topic to the code it documents, so start there to find the page. A design reason bought with a bugfix belongs in the page's "why" section: the knowledge graph records what the code looks like and cannot afford to record why, so a reason that lives nowhere else is one the next agent will simplify away. This is a checklist step, not a gate — no phase is blocked on it.
  5. Pre-deployment checks. Verify:
    • CI pipeline passes
    • No critical findings open from adversarial reviews
    • Dependencies are pinned and audited
  6. Execute deployment. Follow the release plan step by step.
  7. Verify. Confirm the deployment succeeded using the monitoring steps.

Exit Criteria

  • Every artifact the template's deployment phase requires exists, with release plan and rollback strategy
  • Deployment executed successfully (or plan approved for manual execution)
  • Post-deployment verification confirms expected behavior

Security Confirmation

Deployment is inherently sensitive. You MUST:

  1. Confirm the target environment with the user (production vs. staging vs. dev)
  2. Present the full list of changes being deployed
  3. Confirm rollback procedure exists and is tested
  4. Wait for explicit user approval before executing any deployment command
  5. If deploying to production, require additional confirmation stating the environment name

Never deploy without explicit user confirmation. If the user cancels, halt and log the cancellation.

Guidance

{{guidance:secure-defaults}}

Completion

When exit criteria are met, update phase-deployment.yaml status to complete and append a transition record to transitions.log.

Then check for the completion moment: derive the instance's applicable phases (template × scope). If deployment is the last applicable phase, or the next phase is maintenance (maintenance-terminal templates complete on maintenance entry, since maintenance is open-ended), this transition completes the instance — run the aidlc-retrospective skill now, before any completion cleanup (worktree removal, claim release), and fire the on-instance-complete event.