Microservice Scaffolder

---
name: microservice-scaffolder
description: |
  Trigger when the user asks to create a new microservice, spin up a service
  repo, or scaffold a service within a monorepo. Phrases: "new service",
  "scaffold microservice", "new microservice", "service template".
allowed-tools:
  - Read
  - Write
  - Bash(pnpm add *)
  - Bash(mkdir *)
---

# Microservice Scaffolder

Scaffold a new service with the baseline plumbing in place: HTTP server,
health check, structured logging, graceful shutdown, Dockerfile, CI config,
readme. Minutes instead of days.

## Prerequisites

- Target runtime chosen (Node, Python, Go)
- Service mesh / deployment pattern decided (standalone, monorepo, k8s)

## Steps

1. **Ask for the essentials before scaffolding:**
   - Service name (kebab-case)
   - One-sentence purpose
   - Port (default 3000 + N)
   - Database required? (if yes: Postgres, Redis, etc.)

2. **Generate the directory structure:**
   ```
   services/<name>/
     src/
       index.ts        # entry, server start
       routes/         # HTTP handlers
       services/       # business logic
       lib/            # shared utils
     tests/
     Dockerfile
     package.json
     tsconfig.json
     README.md
     .env.example
   ```

3. **Write src/index.ts with the baseline plumbing:**
   - HTTP server (Fastify or Hono)
   - `/health` endpoint (returns 200 with uptime + version)
   - Structured logging (pino with request correlation)
   - SIGTERM handler with graceful shutdown
   - Env var validation at boot (fail-fast if required vars missing)

4. **Dockerfile multi-stage.** See docker-composer skill. Not the simplest
   thing to get right, but essential for production.

5. **CI config.** Add the new service to existing GitHub Actions workflow
   or create one. Typecheck + test + build.

6. **README with:**
   - What the service does (one paragraph)
   - How to run locally
   - Required env vars (link to .env.example)
   - Deploy path
   - Owner / contact

7. **Register in service inventory.** If your org has a service catalog
   (Backstage, internal wiki, README index), add the new service there.

## Baseline features every service needs

- Health endpoint
- Structured JSON logs to stdout
- Graceful shutdown on SIGTERM
- Env var validation at startup
- Dockerfile
- Test harness
- One passing test that imports the entry point

A service without these is a service that will page someone at 3am.

## Output

- Scaffolded service directory with all files populated
- Local dev runs via `pnpm dev` or equivalent
- `/health` returns 200 when running
- First passing test
- Service added to inventory / catalog