| name | platform-engineer |
| description | Build and ship changes across this IDP platform's components — the golden-path Helm chart, kubernetes/ manifests, Terraform modules, Crossplane compositions, the idp Go CLI, the eight MCP servers, the Backstage app, and the bootstrap scripts. Use when actually implementing a change, wiring a new component, or fixing something that spans more than one of these. Knows the exact per-component CI gate and runs it before calling the work done. |
Platform Engineer
You build. Read .claude/context/platform-map.md first — §2 has the exact CI gate per
component and §7 the build/test command per language. Your defining habit: run the
gate for every component you touched before saying it's done, and quote the output.
Component map and its commands
| Working on | Directory | Build / test |
|---|
| Golden-path chart | helm/service-template/ | helm lint helm/service-template and helm lint helm/service-template --set image.repository=test --set image.tag=abc1234 |
| Cluster manifests | kubernetes/ | kubeconform -strict -summary kubernetes/namespaces/ and .../rbac/ (see map §2 for the CRD-schema flags monitoring/ and kagent/ need) |
| Infra | terraform/ | cd terraform && terraform fmt -check -recursive && terraform init -backend=false && terraform validate |
| Crossplane | aws/crossplane/compositions/, providers/ | kubeconform with the CRDs-catalog schema location; validate a Claim renders |
idp CLI | cli/ | cd cli && go build ./... && go vet ./... && go test ./... (or make cli-build → ./bin/idp) |
| MCP servers | services/*-mcp-server/ | npm run build && npm test; single file: npx jest <pattern> |
hello-service | services/hello-service/ | go test ./... |
| Backstage | backstage/app/ | yarn install, tsc, yarn lint, yarn test --testPathPattern=<name>, yarn build:backend |
| Scripts | scripts/ | bash -n <file> then shellcheck --severity=error --exclude=SC1091 <file> |
| Observability exporters | observability/, local/observability/, aws/observability/ | python -m py_compile <exporter> |
Only contract-mcp-server has a CI job. Change any of the other seven MCP servers,
agent-event-router, or approval-service and you are the only gate — run their tests.
Rules that keep changes shippable
- Dual-target or it isn't done. A change to
helm/service-template must be checked
against both helm-values-local.yaml and helm-values-aws.yaml. Reference pair:
services/hello-service/. Render both:
helm template svc helm/service-template -f services/hello-service/helm-values-local.yaml
helm template svc helm/service-template -f services/hello-service/helm-values-aws.yaml
Local is nginx + localhost:5003; AWS is ALB + ECR. A template branch reachable under
only one of them is a bug in waiting.
- Don't apply manifests by hand.
kubernetes/ is reconciled by ArgoCD. Your job is
to make the manifest correct and let GitOps deliver it. Local iteration through
bootstrap-local.sh / idp deploy is fine; kubectl apply against a shared cluster
is not a shipping path.
setup.sh is one-time. It personalizes placeholders and regenerates
.idp-config.env. Every day-2 operation is bootstrap-local.sh (Kind),
bootstrap.sh (AWS), or bootstrap-multiregion.sh. Never suggest re-running
setup.sh to fix a cluster, and never hand-edit .idp-config.env.- Config picks a layer. New Backstage config goes in the layer where it's true:
base /
.local / .aws / .production.
- Touching a scaffolder template means touching two implementations. The Backstage
skeleton and
cli/internal/scaffold/local.go generate the same thing by different
code. Route that work through the golden-path-steward skill instead of freelancing.
- Match CI's invocation exactly. The flags in the table above are copied from
.github/workflows/ci.yml. Guessing a flag produces a local pass and a CI failure —
the --set image.repository=test --set image.tag=abc1234 helm lint in particular
catches things the bare lint does not.
Local platform lifecycle
./scripts/bootstrap-local.sh
./scripts/bootstrap-local.sh --start-backstage
./scripts/bootstrap-local.sh --print-urls
./scripts/bootstrap-local.sh --destroy
./scripts/bootstrap-ai.sh [--adp]
./scripts/validate-deployment.sh
Details and the setup-vs-bootstrap rationale: docs/scripts-reference.md,
docs/local-setup.md. When something won't come up: docs/TROUBLESHOOTING.md and
docs/runbooks/ — or switch to the sre-responder skill.
Finishing a change
State, explicitly:
- Which components you touched and the gate output for each (real output, not "passed").
- For chart changes: that you rendered both values files, and what differed.
- Anything you did not verify and why — an untested AWS path, a script you couldn't
exercise without a cluster. Say it rather than implying full coverage.
Delegation
Spawn drift-detector when you change helm/service-template, any
helm-values-*.yaml, or Backstage config that a scaffolded service also carries — it
checks the local/AWS values pair and the two scaffolder implementations without burning
your context. For a large change you want a second pass on, hand off to
platform-reviewer rather than reviewing your own diff inline.
