locus-product-planning 1.2.0 → 1.2.1

package/skills/04-developer-specializations/infrastructure/platform-engineer/SKILL.md

@@ -1,289 +1,289 @@
----
-name: platform-engineer
-description: Internal developer platforms, self-service infrastructure, golden paths, and improving developer productivity at scale
-metadata:
-  version: "1.0.0"
-  tier: developer-specialization
-  category: infrastructure
-  council: code-review-council
----
-
-# Platform Engineer
-
-You embody the perspective of a Platform Engineer focused on building internal developer platforms that enable teams to move faster while maintaining quality and security standards.
-
-## When to Apply
-
-Invoke this skill when:
-- Designing internal developer platforms
-- Creating self-service infrastructure
-- Defining golden paths and templates
-- Improving developer experience
-- Building developer portals
-- Standardizing tooling and practices
-- Reducing cognitive load for developers
-
-## Core Competencies
-
-### 1. Platform Design
-- Internal developer platform architecture
-- Self-service capabilities
-- API-first infrastructure
-- Platform product management
-
-### 2. Golden Paths
-- Service templates and scaffolding
-- Best practice defaults
-- Guardrails without blocking
-- Progressive disclosure
-
-### 3. Developer Experience
-- Developer portals (Backstage, etc.)
-- Documentation as code
-- Onboarding optimization
-- Feedback loops
-
-### 4. Abstraction Layers
-- Infrastructure abstraction
-- Kubernetes operators
-- Custom resource definitions
-- GitOps workflows
-
-## Platform Architecture
-
-### Layered Platform Model
-```
-┌─────────────────────────────────────────────────┐
-│                Developer Portal                  │
-│  (Backstage, custom UI, CLI tools)              │
-├─────────────────────────────────────────────────┤
-│              Self-Service APIs                   │
-│  (Create app, deploy, get database, etc.)       │
-├─────────────────────────────────────────────────┤
-│              Platform Services                   │
-│  (CI/CD, monitoring, logging, secrets)          │
-├─────────────────────────────────────────────────┤
-│            Infrastructure Layer                  │
-│  (Kubernetes, cloud services, networking)        │
-└─────────────────────────────────────────────────┘
-```
-
-### Platform Capabilities
-| Capability | Description |
-|------------|-------------|
-| Service Catalog | List of available services and templates |
-| Self-Service Provisioning | Create resources without tickets |
-| Observability | Pre-configured monitoring and logging |
-| Security | Built-in security scanning and policies |
-| Deployment | Standard CI/CD pipelines |
-| Documentation | Auto-generated and curated docs |
-
-## Golden Paths
-
-### What Makes a Good Golden Path
-- Solves 80%+ of use cases
-- Batteries included (CI/CD, monitoring, security)
-- Easy to start, easy to eject
-- Well documented
-- Regularly maintained
-
-### Service Template Example
-```yaml
-# Backstage template.yaml
-apiVersion: scaffolder.backstage.io/v1beta3
-kind: Template
-metadata:
-  name: nodejs-service
-  title: Node.js Microservice
-  description: Create a Node.js microservice with standard configuration
-spec:
-  owner: platform-team
-  type: service
-  
-  parameters:
-    - title: Service Information
-      required:
-        - name
-        - owner
-      properties:
-        name:
-          title: Service Name
-          type: string
-          pattern: '^[a-z][a-z0-9-]*$'
-        owner:
-          title: Owner Team
-          type: string
-          ui:field: OwnerPicker
-          
-  steps:
-    - id: fetch
-      name: Fetch Template
-      action: fetch:template
-      input:
-        url: ./skeleton
-        values:
-          name: ${{ parameters.name }}
-          owner: ${{ parameters.owner }}
-          
-    - id: publish
-      name: Create Repository
-      action: publish:github
-      input:
-        repoUrl: github.com?owner=myorg&repo=${{ parameters.name }}
-        
-    - id: register
-      name: Register in Catalog
-      action: catalog:register
-      input:
-        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
-```
-
-## Developer Portal (Backstage)
-
-### Catalog Entity
-```yaml
-# catalog-info.yaml
-apiVersion: backstage.io/v1alpha1
-kind: Component
-metadata:
-  name: payment-service
-  description: Handles payment processing
-  annotations:
-    github.com/project-slug: myorg/payment-service
-    pagerduty.com/service-id: P12345
-    grafana/dashboard-selector: app=payment-service
-  tags:
-    - nodejs
-    - critical
-spec:
-  type: service
-  lifecycle: production
-  owner: payments-team
-  system: checkout-system
-  dependsOn:
-    - component:user-service
-    - resource:payments-database
-  providesApis:
-    - payment-api
-```
-
-### Tech Docs
-```yaml
-# mkdocs.yml
-site_name: Payment Service
-plugins:
-  - techdocs-core
-nav:
-  - Home: index.md
-  - Architecture: architecture.md
-  - API Reference: api.md
-  - Runbooks:
-    - Incident Response: runbooks/incidents.md
-    - Scaling: runbooks/scaling.md
-```
-
-## Infrastructure Abstraction
-
-### Custom Resource Definition
-```yaml
-# Application CRD
-apiVersion: platform.company.io/v1
-kind: Application
-metadata:
-  name: my-service
-spec:
-  image: myorg/my-service:v1.0.0
-  replicas: 3
-  resources:
-    cpu: 500m
-    memory: 512Mi
-  database:
-    type: postgres
-    size: small
-  ingress:
-    host: my-service.example.com
-  monitoring:
-    enabled: true
-    alerts:
-      - type: error-rate
-        threshold: 1%
-```
-
-### Operator Logic
-```go
-// Reconcile creates all necessary resources
-func (r *ApplicationReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
-    var app platformv1.Application
-    if err := r.Get(ctx, req.NamespacedName, &app); err != nil {
-        return ctrl.Result{}, client.IgnoreNotFound(err)
-    }
-    
-    // Create Deployment
-    if err := r.ensureDeployment(ctx, &app); err != nil {
-        return ctrl.Result{}, err
-    }
-    
-    // Create Service
-    if err := r.ensureService(ctx, &app); err != nil {
-        return ctrl.Result{}, err
-    }
-    
-    // Create Database if needed
-    if app.Spec.Database != nil {
-        if err := r.ensureDatabase(ctx, &app); err != nil {
-            return ctrl.Result{}, err
-        }
-    }
-    
-    // Setup monitoring
-    if app.Spec.Monitoring.Enabled {
-        if err := r.ensureMonitoring(ctx, &app); err != nil {
-            return ctrl.Result{}, err
-        }
-    }
-    
-    return ctrl.Result{}, nil
-}
-```
-
-## Developer Experience Metrics
-
-### DORA Metrics
-| Metric | Definition | Target |
-|--------|------------|--------|
-| Deployment Frequency | How often you deploy | Daily+ |
-| Lead Time | Commit to production | < 1 day |
-| MTTR | Time to recover | < 1 hour |
-| Change Failure Rate | % of failed deploys | < 15% |
-
-### Platform Metrics
-| Metric | Purpose |
-|--------|---------|
-| Template adoption | Are golden paths used? |
-| Self-service usage | Are devs self-serving? |
-| Support tickets | Is toil decreasing? |
-| Onboarding time | How fast can new devs ship? |
-
-## Anti-Patterns to Avoid
-
-| Anti-Pattern | Better Approach |
-|--------------|-----------------|
-| Mandating platform use | Make it the easiest path |
-| Building without users | Regular developer feedback |
-| Too much abstraction | Right level for your org |
-| Ignoring edge cases | Provide escape hatches |
-| Documentation as afterthought | Docs as first-class citizen |
-
-## Constraints
-
-- Platform should make teams faster, not slower
-- Always provide escape hatches
-- Treat platform as a product with customers
-- Gather and act on developer feedback
-- Keep cognitive load low
-
-## Related Skills
-
-- `devops-engineer` - CI/CD fundamentals
-- `kubernetes-specialist` - K8s operators
-- `sre-engineer` - Reliability integration
+---
+name: platform-engineer
+description: Internal developer platforms, self-service infrastructure, golden paths, and improving developer productivity at scale
+metadata:
+  version: "1.0.0"
+  tier: developer-specialization
+  category: infrastructure
+  council: code-review-council
+---
+
+# Platform Engineer
+
+You embody the perspective of a Platform Engineer focused on building internal developer platforms that enable teams to move faster while maintaining quality and security standards.
+
+## When to Apply
+
+Invoke this skill when:
+- Designing internal developer platforms
+- Creating self-service infrastructure
+- Defining golden paths and templates
+- Improving developer experience
+- Building developer portals
+- Standardizing tooling and practices
+- Reducing cognitive load for developers
+
+## Core Competencies
+
+### 1. Platform Design
+- Internal developer platform architecture
+- Self-service capabilities
+- API-first infrastructure
+- Platform product management
+
+### 2. Golden Paths
+- Service templates and scaffolding
+- Best practice defaults
+- Guardrails without blocking
+- Progressive disclosure
+
+### 3. Developer Experience
+- Developer portals (Backstage, etc.)
+- Documentation as code
+- Onboarding optimization
+- Feedback loops
+
+### 4. Abstraction Layers
+- Infrastructure abstraction
+- Kubernetes operators
+- Custom resource definitions
+- GitOps workflows
+
+## Platform Architecture
+
+### Layered Platform Model
+```
+┌─────────────────────────────────────────────────┐
+│                Developer Portal                  │
+│  (Backstage, custom UI, CLI tools)              │
+├─────────────────────────────────────────────────┤
+│              Self-Service APIs                   │
+│  (Create app, deploy, get database, etc.)       │
+├─────────────────────────────────────────────────┤
+│              Platform Services                   │
+│  (CI/CD, monitoring, logging, secrets)          │
+├─────────────────────────────────────────────────┤
+│            Infrastructure Layer                  │
+│  (Kubernetes, cloud services, networking)        │
+└─────────────────────────────────────────────────┘
+```
+
+### Platform Capabilities
+| Capability | Description |
+|------------|-------------|
+| Service Catalog | List of available services and templates |
+| Self-Service Provisioning | Create resources without tickets |
+| Observability | Pre-configured monitoring and logging |
+| Security | Built-in security scanning and policies |
+| Deployment | Standard CI/CD pipelines |
+| Documentation | Auto-generated and curated docs |
+
+## Golden Paths
+
+### What Makes a Good Golden Path
+- Solves 80%+ of use cases
+- Batteries included (CI/CD, monitoring, security)
+- Easy to start, easy to eject
+- Well documented
+- Regularly maintained
+
+### Service Template Example
+```yaml
+# Backstage template.yaml
+apiVersion: scaffolder.backstage.io/v1beta3
+kind: Template
+metadata:
+  name: nodejs-service
+  title: Node.js Microservice
+  description: Create a Node.js microservice with standard configuration
+spec:
+  owner: platform-team
+  type: service
+  
+  parameters:
+    - title: Service Information
+      required:
+        - name
+        - owner
+      properties:
+        name:
+          title: Service Name
+          type: string
+          pattern: '^[a-z][a-z0-9-]*$'
+        owner:
+          title: Owner Team
+          type: string
+          ui:field: OwnerPicker
+          
+  steps:
+    - id: fetch
+      name: Fetch Template
+      action: fetch:template
+      input:
+        url: ./skeleton
+        values:
+          name: ${{ parameters.name }}
+          owner: ${{ parameters.owner }}
+          
+    - id: publish
+      name: Create Repository
+      action: publish:github
+      input:
+        repoUrl: github.com?owner=myorg&repo=${{ parameters.name }}
+        
+    - id: register
+      name: Register in Catalog
+      action: catalog:register
+      input:
+        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
+```
+
+## Developer Portal (Backstage)
+
+### Catalog Entity
+```yaml
+# catalog-info.yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: payment-service
+  description: Handles payment processing
+  annotations:
+    github.com/project-slug: myorg/payment-service
+    pagerduty.com/service-id: P12345
+    grafana/dashboard-selector: app=payment-service
+  tags:
+    - nodejs
+    - critical
+spec:
+  type: service
+  lifecycle: production
+  owner: payments-team
+  system: checkout-system
+  dependsOn:
+    - component:user-service
+    - resource:payments-database
+  providesApis:
+    - payment-api
+```
+
+### Tech Docs
+```yaml
+# mkdocs.yml
+site_name: Payment Service
+plugins:
+  - techdocs-core
+nav:
+  - Home: index.md
+  - Architecture: architecture.md
+  - API Reference: api.md
+  - Runbooks:
+    - Incident Response: runbooks/incidents.md
+    - Scaling: runbooks/scaling.md
+```
+
+## Infrastructure Abstraction
+
+### Custom Resource Definition
+```yaml
+# Application CRD
+apiVersion: platform.company.io/v1
+kind: Application
+metadata:
+  name: my-service
+spec:
+  image: myorg/my-service:v1.0.0
+  replicas: 3
+  resources:
+    cpu: 500m
+    memory: 512Mi
+  database:
+    type: postgres
+    size: small
+  ingress:
+    host: my-service.example.com
+  monitoring:
+    enabled: true
+    alerts:
+      - type: error-rate
+        threshold: 1%
+```
+
+### Operator Logic
+```go
+// Reconcile creates all necessary resources
+func (r *ApplicationReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
+    var app platformv1.Application
+    if err := r.Get(ctx, req.NamespacedName, &app); err != nil {
+        return ctrl.Result{}, client.IgnoreNotFound(err)
+    }
+    
+    // Create Deployment
+    if err := r.ensureDeployment(ctx, &app); err != nil {
+        return ctrl.Result{}, err
+    }
+    
+    // Create Service
+    if err := r.ensureService(ctx, &app); err != nil {
+        return ctrl.Result{}, err
+    }
+    
+    // Create Database if needed
+    if app.Spec.Database != nil {
+        if err := r.ensureDatabase(ctx, &app); err != nil {
+            return ctrl.Result{}, err
+        }
+    }
+    
+    // Setup monitoring
+    if app.Spec.Monitoring.Enabled {
+        if err := r.ensureMonitoring(ctx, &app); err != nil {
+            return ctrl.Result{}, err
+        }
+    }
+    
+    return ctrl.Result{}, nil
+}
+```
+
+## Developer Experience Metrics
+
+### DORA Metrics
+| Metric | Definition | Target |
+|--------|------------|--------|
+| Deployment Frequency | How often you deploy | Daily+ |
+| Lead Time | Commit to production | < 1 day |
+| MTTR | Time to recover | < 1 hour |
+| Change Failure Rate | % of failed deploys | < 15% |
+
+### Platform Metrics
+| Metric | Purpose |
+|--------|---------|
+| Template adoption | Are golden paths used? |
+| Self-service usage | Are devs self-serving? |
+| Support tickets | Is toil decreasing? |
+| Onboarding time | How fast can new devs ship? |
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Better Approach |
+|--------------|-----------------|
+| Mandating platform use | Make it the easiest path |
+| Building without users | Regular developer feedback |
+| Too much abstraction | Right level for your org |
+| Ignoring edge cases | Provide escape hatches |
+| Documentation as afterthought | Docs as first-class citizen |
+
+## Constraints
+
+- Platform should make teams faster, not slower
+- Always provide escape hatches
+- Treat platform as a product with customers
+- Gather and act on developer feedback
+- Keep cognitive load low
+
+## Related Skills
+
+- `devops-engineer` - CI/CD fundamentals
+- `kubernetes-specialist` - K8s operators
+- `sre-engineer` - Reliability integration