@ancoleman/platform-engineering

---
name: platform-engineering
description: Design and implement Internal Developer Platforms (IDPs) with self-service capabilities, golden paths, and developer experience optimization. Covers platform strategy, IDP architecture (Backstage, Port), infrastructure orchestration (Crossplane), GitOps (Argo CD), and adoption patterns. Use when building developer platforms, improving DevEx, or establishing platform teams.
---

# Platform Engineering

## Purpose

Build Internal Developer Platforms (IDPs) that provide self-service infrastructure, reduce cognitive load, and accelerate developer productivity through golden paths and platform-as-product thinking.

Platform engineering represents the evolution beyond traditional DevOps, focusing on creating product-quality internal platforms that treat developers as customers. The discipline addresses the developer productivity crisis where engineers spend 30-40% of time on infrastructure and tooling instead of features.

## When to Use This Skill

Trigger this skill when:
- Building or improving an internal developer platform
- Designing a developer portal (Backstage, Port, or commercial IDP)
- Implementing golden paths and software templates
- Establishing or restructuring a platform engineering team
- Measuring and improving developer experience (DevEx)
- Integrating IDP with infrastructure, CI/CD, observability, or security tools
- Driving platform adoption across an engineering organization
- Assessing platform maturity and identifying capability gaps

## Core Concepts

### Platform as Product

Treat internal platforms with the same rigor as customer-facing products:

**Product Management Approach:**
- Define platform vision, strategy, and roadmap
- Identify developer "customers" and their pain points
- Measure success via adoption metrics, satisfaction surveys, and business impact
- Iterate based on feedback loops and usage analytics
- Balance new capabilities with platform reliability and support

**Key Differences from Traditional DevOps:**
- DevOps focuses on delivery pipelines; platform engineering builds comprehensive developer experiences
- Platform teams operate as product teams (product managers, UX designers, engineers)
- Success measured by developer productivity and satisfaction, not just infrastructure metrics
- Self-service is the primary interface, not ticket queues

### Internal Developer Platform (IDP) Architecture

**Three-Layer Architecture:**

**1. Developer Portal (Frontend)**
- Service catalog: Inventory of services with ownership, dependencies, health status
- Software templates: Project scaffolding with best practices baked in
- Documentation hub: Centralized, searchable, version-controlled docs
- Self-service workflows: Environment provisioning, deployments, access requests

**2. Platform Orchestration (Backend)**
- Infrastructure provisioning: Multi-cloud resource management
- Environment management: Dev, staging, production lifecycle
- Deployment automation: GitOps-based continuous delivery
- Configuration management: Separation of app and infrastructure concerns

**3. Integration Layer (Glue)**
- CI/CD integration: Pipeline visibility and triggering
- Observability: Metrics, logs, traces surfaced in portal
- Security: Vulnerability scanning, policy enforcement, secrets management
- FinOps: Cost visibility, budgets, optimization recommendations

For detailed architecture patterns and component breakdowns, see `references/idp-architecture.md`.

### Golden Paths and Scaffolding

**Golden Path Principle:**
Provide opinionated templates that handle 80% of use cases while allowing escape hatches for the remaining 20%.

**Template Components:**
- Repository structure and boilerplate code
- Infrastructure as code (Kubernetes manifests, Terraform)
- CI/CD pipeline configurations
- Observability instrumentation (metrics, logging, tracing)
- Security configurations (RBAC, network policies, secrets)
- Documentation templates (README, runbooks, architecture diagrams)

**Constraint Mechanisms:**
- Policy-as-code enforcement (OPA, Kyverno) for security and compliance
- Resource limits and quotas to prevent over-provisioning
- Required health checks and observability instrumentation
- Approved base images and dependency scanning

For template design patterns and examples, see `references/golden-paths.md`.

### Developer Experience (DevEx) Optimization

**Cognitive Load Reduction:**
- Abstract infrastructure complexity without hiding necessary details
- Provide sensible defaults with clear override mechanisms
- Use progressive disclosure (simple for common cases, advanced options available)
- Consolidate tooling (single developer portal vs. 15+ separate tools)

**Key Metrics:**

**DORA Metrics:**
- Deployment frequency (how often code reaches production)
- Lead time for changes (commit to production duration)
- Mean time to recovery (MTTR for incidents)
- Change failure rate (percentage of deployments causing incidents)

**SPACE Framework:**
- Satisfaction: Developer happiness via surveys and NPS
- Performance: Throughput and efficiency of work completed
- Activity: Code commits, PRs, deployments (context, not raw counts)
- Communication: Collaboration quality, discoverability
- Efficiency: Minimize interruptions, reduce toil

**Platform-Specific Metrics:**
- Platform adoption rate (percentage of teams using platform)
- Self-service rate (actions completed without platform team tickets)
- Onboarding time (new developer to first production deployment)
- Template usage (which golden paths are adopted)
- Support ticket volume and resolution time

## Platform Maturity Assessment

Assess current platform capabilities using a 5-level maturity model:

**Level 0: Ad-Hoc** - Manual provisioning, no standardization
**Level 1: Basic Automation** - Some IaC and CI/CD, limited self-service
**Level 2: Paved Paths** - Golden path templates, early portal, limited coverage
**Level 3: Self-Service Platform** - Comprehensive portal, 80%+ self-service
**Level 4: Product-Driven Platform** - Data-driven, product team structure, FinOps integration
**Level 5: AI-Augmented Platform** - AI-assisted troubleshooting, predictive optimization

For detailed assessment framework, gap analysis, and improvement roadmap, see `references/maturity-model.md`.

## Decision Frameworks

### Build vs. Buy IDP

**Choose Open Source (Backstage) when:**
- Large enterprise (1000+ engineers)
- Dedicated platform team available (5-10 engineers)
- Deep customization required
- Open-source ecosystem preferred
- Long-term investment (3+ year horizon)

**Choose Commercial IDP (Port, Humanitec, Cortex) when:**
- Mid-size organization (100-1000 engineers)
- Faster time-to-value needed (3-6 months vs. 6-12 months)
- Prefer managed solution with vendor support
- Limited platform engineering resources (<5 engineers)
- Standard use cases (web apps, microservices, CI/CD)

**Choose Hybrid Approach when:**
- Large organization needing both flexibility and speed
- Complex infrastructure requiring orchestration backend
- Want best-in-class portal + orchestration components
- Willing to integrate multiple systems (e.g., Backstage + Humanitec)

For complete decision tree, selection criteria, and ROI calculations, see `references/decision-frameworks.md`.

### Golden Path Design: Flexibility vs. Standardization

**Spectrum of Control:**

**High Standardization (Regulated Industries):**
- Limited technology choices, mandatory templates
- Policy enforcement via admission controllers (OPA, Kyverno)
- Escape hatches require approval process

**Balanced Approach (Recommended for Most):**
- Recommended golden paths (easy, well-documented, supported)
- Alternatives allowed with documentation
- Soft enforcement (defaults + education, not hard blocks)
- Clear ownership for deviations ("deviate and own")

**High Flexibility (Innovative Organizations):**
- Golden paths as suggestions (not requirements)
- Minimal policy enforcement (only critical security)
- "Build it, run it" ownership model

For detailed guidance on choosing the right balance and enforcement strategies, see `references/decision-frameworks.md`.

### Platform Team Structure

**Centralized Model:**
- Single platform team (5-20 engineers) serving entire organization
- Best for: Small to mid-size orgs (100-500 engineers)

**Federated Model:**
- Central team (5-10 engineers) + embedded engineers (1-2 per business unit)
- Best for: Large orgs (500-2000+ engineers), multiple business units

**Hub-and-Spoke Model:**
- Central "hub" team (3-5 engineers) + "spoke" teams contributing plugins
- Best for: Organizations with strong open-source culture

For team sizing, roles, responsibilities, and governance models, see `references/decision-frameworks.md`.

## Tool Recommendations

### Developer Portals

**Backstage** (Open Source, CNCF)
- Trust Score: 78.7/100, 8,876 code snippets
- Software catalog, scaffolder, TechDocs, plugin ecosystem
- Recommended for: Enterprises with platform teams

**Port** (Commercial)
- Managed platform, modern UI/UX, faster time-to-value
- Recommended for: Mid-size orgs (100-1000 engineers)

**Cortex** (Commercial SaaS)
- Enterprise IDP, compliance focus, engineering standards enforcement
- Recommended for: Regulated industries

### Platform Orchestration

**Crossplane** (Open Source, CNCF)
- Trust Score: 67.4/100, universal control plane for multi-cloud
- Kubernetes-native declarative infrastructure
- Recommended for: Multi-cloud abstractions

**Humanitec** (Commercial)
- Platform Orchestrator backend, environment and deployment management
- Recommended for: Complex infrastructure, complements portals

**Terraform Cloud** (Commercial)
- Mature IaC orchestration, workspace management
- Recommended for: Terraform-heavy organizations

### GitOps Continuous Delivery

**Argo CD** (Open Source, CNCF) - **RECOMMENDED**
- Trust Score: 91.8/100 (HIGHEST)
- Declarative GitOps for Kubernetes, multi-cluster management
- Industry-leading documentation and community

**Flux** (Open Source, CNCF)
- Toolkit approach, Kubernetes-native
- Good for: GitOps-native operations

For detailed tool comparisons, integration patterns, and selection criteria, see `references/tool-recommendations.md`.

## Implementation Guides

### Bootstrapping a Platform

**Foundation Phase (Months 1-3):**
1. Define platform vision and form platform team (3-5 members)
2. Interview developers to identify pain points
3. Set up developer portal (Backstage or commercial)
4. Create initial service catalog and first golden path template

**Pilot Phase (Months 4-6):**
1. Select 2-3 pilot teams for white-glove onboarding
2. Rapid iteration based on feedback
3. Expand to 3-5 golden path templates
4. Integrate key tools (CI/CD, monitoring, secrets)

**Expansion Phase (Months 7-12):**
1. Scale to 20-50% of engineering teams
2. Build self-service documentation and training
3. Establish platform SLOs and on-call rotation
4. Internal evangelization (demos, champions program)

**Maturity Phase (Year 2+):**
1. 80%+ adoption across organization
2. Platform team operates as product team
3. Continuous improvement via metrics and feedback
4. AI-assisted capabilities, policy-as-code expansion

For detailed implementation steps and bootstrapping code, see `references/implementation-backstage.md`.

### Creating Golden Path Templates

**Template Design Process:**
1. Identify most common use case (web app, API, data pipeline)
2. Define opinionated choices (language, framework, deployment pattern)
3. Create repository structure and infrastructure manifests
4. Configure CI/CD pipeline with security scanning
5. Instrument observability and document usage
6. Test with pilot team before broad rollout

**Template Categories:**
- Full-stack web application (backend API + frontend + database)
- Data pipeline (ETL/ELT with orchestration)
- Machine learning service (model serving, monitoring)
- Event-driven microservice (message broker integration)
- Scheduled job (cron jobs, batch processing)

For template examples, scaffolding code, and customization patterns, see `references/golden-paths.md` and `examples/` directory.

### Driving Platform Adoption

**Evangelization Strategies:**
- Showcase pilot team successes (internal blog posts, demos)
- Lunch-and-learns on platform capabilities
- Internal champions program (power users helping peers)
- Office hours and Slack/Teams support channels

**Incentive Alignment:**
- Make platform easier than alternatives (golden paths are "paved roads")
- Integrate with workflows developers already use
- Provide immediate value (faster onboarding, better visibility)
- Celebrate early adopters, showcase their successes

For adoption metrics, tracking dashboards, and success patterns, see `references/maturity-model.md`.

## Quick Reference

### Platform Engineering Checklist

**Strategy and Vision:**
- [ ] Platform vision and charter documented
- [ ] Platform team formed with clear roles
- [ ] Developer pain points identified via interviews
- [ ] Success metrics defined (DORA, SPACE, adoption)

**IDP Foundation:**
- [ ] Developer portal deployed (Backstage, Port, or commercial)
- [ ] Service catalog established (ownership, dependencies, health)
- [ ] First golden path template created and validated
- [ ] Documentation hub accessible to all engineers

**Self-Service Capabilities:**
- [ ] Environment provisioning (dev, staging, production)
- [ ] Deployment automation (GitOps with Argo CD or Flux)
- [ ] CI/CD integration visible in portal
- [ ] Observability dashboards per-service

**Security and Compliance:**
- [ ] Policy-as-code enforcement (OPA, Kyverno)
- [ ] Secrets management integrated (Vault, cloud providers)
- [ ] Vulnerability scanning in pipelines
- [ ] RBAC and access controls configured

**Operations and Support:**
- [ ] Platform SLOs defined and monitored
- [ ] Support channels established (Slack, office hours)
- [ ] Incident response playbooks documented
- [ ] Feedback loops and usage analytics in place

### Common Pitfalls

**Building Too Much Upfront:**
- Start small (1 golden path, pilot team) and iterate
- Avoid "boil the ocean" syndrome

**Ignoring Developer Feedback:**
- Establish continuous feedback loops, not just quarterly surveys

**Over-Standardization:**
- Provide clear escape hatches for advanced use cases

**Under-Measuring Success:**
- Track DORA metrics, satisfaction surveys, self-service rates

**Treating Platform as IT Project:**
- Platform engineering is product development, not infrastructure provisioning
- Requires product managers, UX designers, customer focus

## Integration with Other Skills

**Related Skills:**

- `kubernetes-operations`: Cluster operations, namespace management, RBAC, network policies
- `infrastructure-as-code`: Terraform, Pulumi for infrastructure provisioning integrated with platform
- `gitops-workflows`: GitOps principles, Argo CD / Flux implementation patterns
- `building-ci-pipelines`: CI/CD pipeline design integrated into platform templates
- `security-hardening`: Security best practices enforced through golden paths
- `secret-management`: Secrets management integrated into platform (Vault, cloud providers)
- `observability`: Monitoring, logging, tracing integrated into developer portal

**Cross-Skill Workflows:**

**Platform Bootstrapping:**
1. Use `infrastructure-as-code` to provision platform infrastructure
2. Use `kubernetes-operations` to configure clusters
3. Deploy developer portal (Backstage) on platform infrastructure
4. Integrate `gitops-workflows` (Argo CD) for continuous delivery
5. Add `observability` integrations (Prometheus, Grafana plugins)

**Golden Path Creation:**
1. Design template based on common use case
2. Use `building-ci-pipelines` patterns for CI/CD configuration
3. Apply `security-hardening` best practices (SAST, container scanning)
4. Integrate `secret-management` (Vault, encrypted configs)
5. Add `observability` instrumentation (metrics, logging, tracing)

## Example Use Cases

### Use Case 1: E-Commerce Platform Team

**Context:** 300-engineer e-commerce company, microservices architecture, manual provisioning causing bottlenecks.

**Approach:** Deploy Backstage, create 3 golden paths, integrate Argo CD, pilot with 3 teams, expand to 20 teams over 6 months.

**Results:** Onboarding time 2 days → 2 hours, deployment frequency 2x/week → 10x/day, developer NPS +35.

### Use Case 2: Financial Services Platform

**Context:** 1500-engineer bank, strict compliance, legacy infrastructure, fragmented tooling.

**Approach:** Adopt Port (commercial), high standardization golden paths, OPA Gatekeeper, federated model, Terraform Cloud.

**Results:** Compliance audit prep 3 weeks → 3 days, infrastructure drift incidents 90% reduction, per-service cost attribution.

### Use Case 3: Startup Platform

**Context:** 50-engineer startup, rapid growth, need fast developer onboarding.

**Approach:** Lightweight Backstage (2 engineers), 2 golden paths, GitHub Actions, PaaS infrastructure (Fly.io), documentation focus.

**Results:** New engineer to production 1 day (vs. 2 weeks), 100% self-service, 2 engineers supporting 50 developers.

For code examples and template structures, see `examples/` directory.