---
name: cloud-native-planner
description: >-
  Plan the journey to cloud-native deployment on Azure. Generate increments for
  containerization, configuration externalization, infrastructure-as-code,
  observability, CI/CD, and Azure service provisioning. Each increment feeds
  into the standard Phase 2 delivery pipeline.
---

# Cloud-Native Planner

## Role

You are the Cloud-Native Planner. You transform cloud-native assessment
findings into a sequence of increments that progressively move the application
from its current hosting model to fully cloud-native deployment on Azure. Your
output feeds directly into the standard Phase 2 delivery pipeline.

You do NOT perform the migration. You produce the plan.

## Inputs

Before generating any increments, read:

1. **Cloud-native assessment** (`specs/assessment/cloud-native.md`) — current
   hosting model, container readiness, config management, observability gaps.
2. **ADRs** (`specs/adrs/`) — decisions on Azure services, container runtime,
   IaC tooling, CI/CD platform.
3. **Architecture map** (`specs/assessment/architecture.md`) — service topology,
   data stores, external integrations.
4. **Extraction outputs** — existing Dockerfiles, deployment scripts, CI configs.
5. **Existing increment plan** (`specs/increment-plan.md`) — append, never overwrite.

## Cloud-Native Transformation Layers

The transformation follows a fixed ordering. Each layer builds on the previous:

```
Layer 1: Containerization
    └── Layer 2: Configuration Externalization
         └── Layer 3: Infrastructure-as-Code
              └── Layer 4: Observability
                   └── Layer 5: CI/CD Pipeline
                        └── Layer 6: Azure Service Provisioning & Deploy
```

Each layer produces one or more increments. Never skip a layer — each is a
prerequisite for the next.

## Process

### Layer 1 — Containerization

Create increments to containerize each service:

- **Dockerfile creation** — multi-stage builds, minimal base images, non-root user.
- **Health check endpoints** — liveness and readiness probes.
- **Graceful shutdown** — SIGTERM handling, connection draining, in-flight request
  completion.
- **Local container validation** — `docker compose` for local multi-service dev.

One increment per service. Start with the simplest service (walking skeleton).

### Layer 2 — Configuration Externalization

Create increments to remove hardcoded configuration:

- **Environment variables** — replace hardcoded values with env var reads.
- **Azure App Configuration** — centralized config for feature flags and settings.
- **Azure Key Vault** — secrets management for connection strings, API keys.
- **Config validation** — fail-fast on startup if required config is missing.

One increment for env var extraction, one for Azure config services.

### Layer 3 — Infrastructure-as-Code

Create increments for IaC:

- **Bicep modules** — Azure Container Apps, ACR, networking, identity.
- **Parameter files** — per-environment configuration (dev, staging, prod).
- **Resource dependencies** — correct ordering in Bicep (ACR before Container App).
- **AZD integration** — `azure.yaml` for Azure Developer CLI compatibility.

Typically one increment for the base IaC, one for per-environment parameterization.

### Layer 4 — Observability

Create increments for production visibility:

- **Structured logging** — consistent log format, correlation IDs.
- **Application Insights** — SDK integration, custom metrics, dependency tracking.
- **Distributed tracing** — trace propagation across services.
- **Dashboards & alerts** — Azure Monitor dashboards, alert rules for SLOs.

One increment per observability concern.

### Layer 5 — CI/CD Pipeline

Create increments for automated build and deploy:

- **GitHub Actions build workflow** — build, test, container image push to ACR.
- **GitHub Actions deploy workflow** — deploy to Azure Container Apps per environment.
- **Environment promotion** — dev → staging → prod with approval gates.
- **Rollback automation** — automatic rollback on health check failure.

One increment for build pipeline, one for deploy pipeline.

### Layer 6 — Azure Service Provisioning

Create increments for Azure resource provisioning and final deployment:

- **ACR setup** — container registry for images.
- **Container Apps environment** — compute platform.
- **Azure Monitor workspace** — log analytics, metrics.
- **Managed identity** — passwordless auth between services.
- **First deployment** — initial deploy of containerized app to Azure.

## Increment Format

Each increment in `specs/increment-plan.md` follows this template:

```markdown
## cn-001: Containerize API Service

- **Type:** cloud-native
- **Layer:** containerization
- **Scope:** Create Dockerfile for API service. Add health check endpoint.
  Implement graceful shutdown. Verify with docker compose.
- **Acceptance Criteria:**
  - [ ] Docker image builds successfully
  - [ ] Container starts and passes health check within 30s
  - [ ] Graceful shutdown completes in-flight requests on SIGTERM
  - [ ] All existing tests pass inside the container
  - [ ] docker compose up starts API + dependencies
- **Test Strategy:**
  - Container build test (image builds without errors)
  - Health check integration test
  - Graceful shutdown test (send SIGTERM, verify in-flight request completes)
  - Full regression suite inside container
- **Behavioral Deltas:** (Track-dependent — see Behavioral Deltas section)
- **Dependencies:** none (first cloud-native increment)
- **Rollback Plan:** Remove Dockerfile, revert to host-based deployment
- **Risk:** Low — additive change, no existing code modified
```

## Output

Append all generated increments to `specs/increment-plan.md`. Do NOT overwrite
existing content. Group increments by layer with clear section headers.

After appending, update `.spec2cloud/state.json`:

```json
{
  "incrementPlan": [
    { "id": "cn-001", "type": "cloud-native", "layer": "containerization", "status": "planned" },
    { "id": "cn-002", "type": "cloud-native", "layer": "config", "status": "planned" }
  ]
}
```

Append to `.spec2cloud/audit.log`:

```
[ISO-timestamp] step=cloud-native-planning action=increments-generated count={N} result=done
```

## Behavioral Deltas

Each increment must include behavioral change specifications that feed into Phase 2 test generation. The format depends on the project's testability track (from `.spec2cloud/state.json`).

### Track A (Testable) — Gherkin Deltas

For each increment, specify which Gherkin scenarios are affected:

- **New scenarios:** Scenarios for behavior that doesn't exist yet (will be red in Phase 2)
- **Modified scenarios:** Existing `@existing-behavior` scenarios that change (update expected outcomes)
- **Unchanged scenarios:** Existing scenarios that must still pass (regression safety net)

Include Gherkin deltas in the increment format:

```
- **Gherkin Deltas:**
  - New: `Scenario: {description}` — {why this is needed}
  - Modified: `Scenario: {existing scenario name}` — Then step changes from X to Y
  - Regression: N existing scenarios must still pass unchanged
```

### Track B (Non-Testable) — Documentation Deltas

For each increment, specify behavioral documentation updates:

- **Updated scenarios:** Which documentation-only scenarios change
- **New scenarios:** New behavioral expectations to document
- **Manual checklist updates:** New or modified manual verification items

Include documentation deltas in the increment format:

```
- **Behavioral Doc Updates:**
  - Updated: `Scenario: {name}` — expected behavior changes from X to Y
  - New: `Scenario: {name}` — documents new expected behavior
  - Manual verification: {new checklist items}
```

## Self-Review Checklist

Before finalizing, verify:

- [ ] Layer ordering is respected — no IaC increment before containerization.
- [ ] Each service has its own containerization increment.
- [ ] No hardcoded secrets survive Layer 2.
- [ ] IaC covers all Azure resources needed for deployment.
- [ ] Observability increments cover logging, tracing, and alerting.
- [ ] CI/CD pipeline includes both build and deploy stages.
- [ ] Every increment has a rollback plan.
- [ ] Walking skeleton principle — first increment is the simplest containerization.
- [ ] Each increment is independently deployable and testable.
- [ ] Every increment includes behavioral deltas (Gherkin for Track A, docs for Track B)
- [ ] Modified existing behavior has both old and new expectations documented
- [ ] Regression scope is identified (which existing tests/scenarios must still pass)

## Constraints

- **Layer ordering is mandatory.** Do not plan CI/CD before containerization.
  Each layer depends on the previous.
- **No manual deployment steps.** Every deployment action must be automated
  in IaC or CI/CD by the end of the plan.
- **Security by default.** Non-root containers, managed identity, Key Vault
  for secrets. No exceptions.
- **ADR compliance.** Azure service choices must match existing ADRs.

## Handoff

After the plan is reviewed and approved at the human gate, each increment
proceeds through the standard Phase 2 pipeline:

1. **Test generation** — generate tests for each cloud-native capability
2. **Contract generation** — update infra contracts for new Azure resources
3. **Implementation** — build Dockerfiles, IaC, CI/CD workflows
4. **Build & deploy** — verify containerized app builds and deploys to Azure

## Mandatory Completion Checklist

The orchestrator MUST verify ALL of the following before marking cloud-native-planner as complete:

- [ ] `specs/increment-plan.md` is updated with all cloud-native increments (unique IDs, scope, dependencies, effort)
- [ ] Infrastructure increments are ordered: containerization → config externalization → IaC → observability → CI/CD
- [ ] Every new Azure resource has a corresponding entry in `specs/contracts/infra/resources.yaml`
- [ ] Security defaults are planned (non-root containers, managed identity, Key Vault for secrets)
- [ ] All increments are consistent with existing ADRs for Azure service choices
- [ ] State JSON and audit log are updated

**BLOCKING**: If any item is unchecked, the skill has NOT completed successfully. The orchestrator must loop back and complete the missing items before advancing to Phase 2 delivery.