Planner Skill

Generate staged project plans that break complex projects into manageable, resumable steps - from initial design through coding, testing, to cloud deployment.

Tip: For a complete overview of all available skills, see the root SKILL.md.

Greenfield vs Brownfield Detection

.do/app.yaml

.do/app.yaml

The AI assistant automatically detects the project state. Don't recreate valid artifacts. The critical validation gate is

doctl app dev build

Why Staged Deployment?

Complex App Platform deployments fail when executed monolithically:

1. Blind deployment fails - Deploying without infrastructure prep results in cryptic errors
2. Context is lost - Credentials, cluster IDs, and progress are forgotten between sessions
3. Debugging is harder - When everything deploys at once, it's unclear which component failed
4. Resumability is poor - Starting over wastes time; partial progress isn't tracked

Build Locally First

CRITICAL: Always validate builds locally before cloud deployment.

doctl app dev build                    # Build using local app spec
doctl app dev build --app <APP_ID>     # Build using existing deployed app
doctl app dev build --env-file .env    # Build with environment overrides

Full details: See build-local-first.md

Tier Classification

Detection from User Description

Decision Tree

Does user mention Kafka, OpenSearch, workers, or "event-driven"?
  YES → Tier 3 (Complex)
  NO → Does user mention database (PostgreSQL, MySQL, MongoDB)?
         YES → Tier 2 (Database-backed)
         NO → Tier 1 (Simple)

Detection from app.yaml (Fallback)

If

.do/app.yaml

• workers

  present → Tier 3

• databases

  with

  KAFKA

  or

  OPENSEARCH

  → Tier 3

• databases

  present → Tier 2
• Neither → Tier 1

Tier Structures

Tier 1: Simple (5 stages)

Criteria: Static sites, single service, no database

Plan/
├── 01-local-design.md
├── 02-local-coding.md
├── 03-local-testing.md
├── 04-cloud-deploy.md
└── 05-cloud-validate.md

Examples: Next.js static export, React SPA, Hugo site, Astro

Tier 2: Database-Backed (7 stages)

Criteria: 1-2 services, single database (PostgreSQL/MySQL)

Plan/
├── 01-local-design.md
├── 02-local-coding.md
├── 03-local-testing.md
├── 04-cloud-database.md
├── 05-cloud-config.md
├── 06-cloud-deploy.md
└── 07-cloud-validate.md

Examples: Rails + PostgreSQL, Django + MySQL, Node.js API + Postgres

Tier 3: Complex (9 stages)

Criteria: Multi-service, workers, Kafka/OpenSearch, VPC networking

Plan/
├── 01-local-design.md
├── 02-local-coding.md
├── 03-local-testing.md
├── 04-cloud-database-clusters.md
├── 05-cloud-config-users-topics.md
├── 06-cloud-debug-validation.md
├── 07-cloud-secrets-cicd.md
├── 08-cloud-deploy-production.md
└── 09-cloud-end-to-end.md

Examples: Event-driven microservices, ML pipelines, real-time analytics

CRITICAL: Tier 3 apps MUST use GitHub Actions for deployment

Tier 3 apps have

${SECRET_NAME}

placeholders only resolved by

digitalocean/app_action/deploy@v2

.

• Set

  deploy_on_push: false

  in

  .do/app.yaml

• Deploy via

  git push

  (triggers GitHub Actions), NOT

  doctl apps create

Stage Templates

Stage templates are provided in the

templates/

templates/local/

templates/tier-1-simple/

templates/tier-2-database/

templates/tier-3-complex/

Each stage file follows this structure:

# Stage N: [Stage Name]

**Status**: TODO
**Prerequisites**: Stage N-1 complete

## Tasks
- [ ] Task description
- [ ] Expected outcome

## Verification
[Commands to verify completion]

## Next Steps
Proceed to Stage N+1

Key validation gate: Stage 3 includes

doctl app dev build

Usage Examples

Example 1: Simple Static Site

User: "Deploy a Next.js static site"

1. Detect Tier 1 (no database)
2. Generate 5 stage files in Plan/
3. Return: "Created 5-stage plan. Start with Stage 1: Local Design."

Example 2: API with Database

User: "Node.js API with PostgreSQL"

1. Detect Tier 2 (PostgreSQL)
2. Generate 7 stage files in Plan/
3. Return: "Created 7-stage plan. Database cluster created in Stage 4."

Example 3: Event-Driven Microservices

User: "Event-driven app with Kafka and OpenSearch"

1. Detect Tier 3 (Kafka + OpenSearch)
2. Generate 9 stage files in Plan/
3. Return: "Created 9-stage plan with debug container validation."

Key Features

Session Resumability

• Stage files persist in git (status tracking only)
• All captured values stored in

  .env.secrets

  (gitignored)
• AI assistants read

  .env.secrets

  to resume from any stage

Artifact Storage

• Plan files contain status only, not secrets
• All IDs, passwords, URLs stored in

  .env.secrets

• See artifact-storage.md for philosophy

Pause Points

• Each stage ends with verification checklist
• Explicit "proceed to Stage N+1" guidance
• Troubleshooting sections for common failures

Reference Files

• build-local-first.md — Full

  doctl app dev build

  workflow
• artifact-storage.md — Storage philosophy, AI instructions

Integration with Other Skills

• ← designer: Uses

  .do/app.yaml

  for complexity detection if exists
• → deployment: Plan/ files provide context; Stage 7 creates GitHub Actions workflow
• → troubleshooting: Plan/ stages help identify where failure occurred
• → devcontainers: Local development setup for testing