Skip to content

LiorCohen/sdd / plugin/fullstack-typescript/skills/orchestrators/local-env-orchestration

local-env-orchestration

Verified

Orchestrates local Kubernetes development environment management.

Local Environment Orchestration

Manage local Kubernetes development environments for SDD projects.

Input

Invoked by sdd-run.md with:

  • action β€” The local-env action to perform
  • args β€” Remaining arguments after the action

Prerequisites

  • Docker installed and running
  • kubectl installed
  • helm installed
  • One of the following cluster providers:
    • kind (brew install kind) - recommended
    • minikube (brew install minikube)
    • Docker Desktop with Kubernetes enabled

Actions

ActionDescription
createCreate cluster + install infra
destroyDelete cluster entirely
startResume stopped cluster
stopPause cluster (preserves state)
statusShow cluster and workload status
deploySet up databases, run migrations, deploy helm charts
undeployRemove helm deployments (databases persist)
forwardManage port forwards
infraInstall/reinstall observability infrastructure

No Arguments

When invoked without an action, display usage:

⚠ Missing required action argument.

USAGE:
  /sdd-run local-env <action> [args] [options]

ACTIONS:
  create     Create local k8s cluster + install infra
  destroy    Delete cluster entirely                      πŸ”΄ destructive
  start      Resume stopped cluster
  stop       Pause cluster (preserves state)
  status     Show cluster and workload status
  deploy     Set up databases, run migrations, deploy helm charts
  undeploy   Remove helm deployments                      🟑 caution
  forward    Manage port forwards (start|stop|list)
  infra      Install/reinstall observability infrastructure

EXAMPLES:
  /sdd-run local-env create
  /sdd-run local-env deploy
  /sdd-run local-env forward start
  /sdd-run local-env status

Action Details

create

/sdd-run local-env create [--name=cluster-name] [--provider=kind|minikube|docker-desktop] [--skip-infra]

Creates a local k8s cluster and installs the observability stack (Victoria Metrics + Victoria Logs).

Options:

  • --name: Cluster name (default: sdd-local)
  • --provider: Cluster provider (default: auto-detected)
    • kind: Kubernetes IN Docker (fast, lightweight)
    • minikube: Full-featured local k8s
    • docker-desktop: Uses Docker Desktop's built-in Kubernetes
  • --skip-infra: Skip installing observability stack

Implementation:

<plugin-root>/fullstack-typescript/system/system-run.sh local-env create [--name=cluster-name] [--provider=kind|minikube|docker-desktop] [--skip-infra]

destroy

/sdd-run local-env destroy [--name=cluster-name]

Completely removes the local cluster (not available for docker-desktop).

Implementation:

<plugin-root>/fullstack-typescript/system/system-run.sh local-env destroy [--name=cluster-name]

start / stop

/sdd-run local-env start [--name=cluster-name]
/sdd-run local-env stop [--name=cluster-name]

Pause and resume the cluster. State is preserved when stopped.

Implementation:

<plugin-root>/fullstack-typescript/system/system-run.sh local-env start [--name=cluster-name]
<plugin-root>/fullstack-typescript/system/system-run.sh local-env stop [--name=cluster-name]

status

/sdd-run local-env status [--name=cluster-name]

Shows cluster status, node health, and deployed workloads.

Implementation:

<plugin-root>/fullstack-typescript/system/system-run.sh local-env status [--name=cluster-name]

deploy

/sdd-run local-env deploy [chart-name] [--namespace=<app-name>] [--skip-db] [--skip-migrate] [--exclude=name,...]

Deploys the full application stack in order:

  1. Databases - Sets up PostgreSQL instances for each type: database component
  2. Migrations - Runs database migrations
  3. Helm charts - Deploys application charts from components/helm_charts/

Options:

  • --namespace: Override namespace (default: app name from sdd-settings.yaml)
  • --skip-db: Skip database setup (useful for redeploying apps only)
  • --skip-migrate: Skip running migrations
  • --exclude: Comma-separated list of charts to skip (for hybrid development)

Implementation:

<plugin-root>/fullstack-typescript/system/system-run.sh local-env deploy [chart-name] [--namespace=<app-name>] [--skip-db] [--skip-migrate] [--exclude=name,...]

undeploy

/sdd-run local-env undeploy [chart-name] [--namespace=<app-name>]

Removes deployed applications (keeps infrastructure).

Implementation:

<plugin-root>/fullstack-typescript/system/system-run.sh local-env undeploy [chart-name] [--namespace=<app-name>]

forward

/sdd-run local-env forward [start|stop|list] [--namespace=<app-name>]

Manages port forwards for local access to services.

Implementation:

<plugin-root>/fullstack-typescript/system/system-run.sh local-env forward [start|stop|list] [--namespace=<app-name>]

infra

/sdd-run local-env infra [--reinstall]

Install or reinstall the observability infrastructure stack.

Implementation:

<plugin-root>/fullstack-typescript/system/system-run.sh local-env infra [--reinstall]

Architecture

Cluster Providers

ProviderBest ForCreate TimeNotes
kindCI/CD, disposable clusters~30 secondsDefault, recommended
minikubeFeature-rich local dev~60 secondsSupports addons
docker-desktopSimple local devAlready runningUses existing cluster

Auto-detection order:

  1. If Docker Desktop k8s is running β†’ docker-desktop
  2. If minikube is installed β†’ minikube
  3. Default β†’ kind

Infrastructure Stack

The telemetry namespace contains:

  • Victoria Metrics: Metrics collection and storage
  • Victoria Logs: Log aggregation
  • Log Collector: DaemonSet collecting logs from all pods

Namespace Layout

NamespaceContents
telemetryObservability stack
<app-name>Application deployments (from sdd-settings.yaml name field)

Integration with Settings

The deploy action reads sdd/sdd-settings.yaml (delegate to the techpack-settings skill for the settings schema β€” it returns the project name, component list with types, and per-component settings) to:

  1. Get the app name (used as the Kubernetes namespace)
  2. Find all type: database components to set up
  3. Find all type: helm components to deploy

Hybrid Development

Run most services in k8s while developing one locally:

# Deploy everything except the service you're working on
/sdd-run local-env deploy --exclude=main-server-api

# Start port forwards so your local service can reach k8s
/sdd-run local-env forward start

# Run your service locally
cd components/servers/main-server
npm run dev

Your local service connects to:

  • Databases: via port-forwarded PostgreSQL (localhost:5432)
  • Other APIs: via port-forwarded services (localhost:8080+)
  • Telemetry: Victoria Metrics at localhost:9090

Troubleshooting

Cluster won't start

# Check Docker is running
docker ps

# Check kind clusters
kind get clusters

# Delete and recreate
/sdd-run local-env destroy
/sdd-run local-env create

Pods not starting

# Check pod status
kubectl get pods -A

# Check pod logs
kubectl logs <pod-name> -n <namespace>

# Describe pod for events
kubectl describe pod <pod-name> -n <namespace>

Port forward not working

# List active forwards
/sdd-run local-env forward list

# Stop all and restart
/sdd-run local-env forward stop
/sdd-run local-env forward start

Output

Returns the system CLI output for the requested action.

writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path β€” even casually (like "the xlsx in my downloads") β€” and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall