planner

# 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](../../SKILL.md).

---

## Greenfield vs Brownfield Detection

| Scenario | Detection | Behavior |
|----------|-----------|----------|
| **Greenfield** | No Dockerfiles, no `.do/app.yaml` | Create artifacts from scratch |
| **Brownfield** | Dockerfiles and/or `.do/app.yaml` exist | Review, validate, enhance existing |

The AI assistant automatically detects the project state. Don't recreate valid artifacts. The critical validation gate is `doctl app dev build` — if that passes, artifacts are correct.

---

## 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.

```bash
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
```

| Build Location | Feedback Time | Cost of Failure |
|----------------|---------------|-----------------|
| Cloud | 5-10 minutes | Wasted cycle, confusing logs |
| Local | 30-60 seconds | Immediate fix, clear errors |

**Full details**: See [build-local-first.md](reference/build-local-first.md)

---

## Tier Classification

### Detection from User Description

| User Mentions | Tier |
|--------------|------|
| "static", "frontend only", "no database", "SPA" | Tier 1 |
| "PostgreSQL", "MySQL", "database", "API + frontend" | Tier 2 |
| "Kafka", "OpenSearch", "workers", "event-driven", "microservices" | Tier 3 |

### 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` exists:
- `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/` directory:

| Directory | Purpose |
|-----------|---------|
| `templates/local/` | Local stages 1-3 (all tiers) |
| `templates/tier-1-simple/` | Tier 1 cloud stages |
| `templates/tier-2-database/` | Tier 2 cloud stages |
| `templates/tier-3-complex/` | Tier 3 cloud stages |

Each stage file follows this structure:

```markdown
# 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` and health check validation.

---

## 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](reference/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](reference/build-local-first.md)** — Full `doctl app dev build` workflow
- **[artifact-storage.md](reference/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