agentic-team-templates 0.3.0

package/templates/platform-engineering/.cursorrules/overview.md

@@ -0,0 +1,215 @@
+# Platform Engineering Overview
+
+Staff-level guidelines for building and operating internal developer platforms, infrastructure automation, and reliability engineering.
+
+## Scope
+
+This template applies to:
+
+- Infrastructure as Code (Terraform, Pulumi, AWS CDK, Crossplane)
+- Kubernetes and container orchestration
+- CI/CD pipelines and GitOps workflows
+- Internal Developer Platforms (IDPs)
+- Observability systems (metrics, logs, traces)
+- Service mesh and networking
+- Security and compliance automation
+- Cost optimization and FinOps
+
+## Core Principles
+
+### 1. Platform as Product
+
+Your internal customers are developers. Treat the platform like a product:
+
+- Understand user needs through research and feedback
+- Prioritize features based on impact
+- Measure adoption and satisfaction
+- Iterate based on real usage data
+- Market capabilities and provide excellent documentation
+
+### 2. Self-Service First
+
+Enable teams to move fast without becoming a bottleneck:
+
+- Automate everything that can be automated
+- Provide golden paths with sensible defaults
+- Build guardrails, not gates
+- Reduce time-to-first-deployment to minutes, not days
+- Scale through automation, not headcount
+
+### 3. Reliability Engineering
+
+Define SLOs, measure SLIs, maintain error budgets:
+
+- Every service needs defined reliability targets
+- Measure what matters to users (latency, availability, correctness)
+- Use error budgets to balance reliability and velocity
+- Automate incident response where possible
+- Conduct blameless postmortems
+
+### 4. Security by Default
+
+Bake security into the golden path:
+
+- Shift left on security scanning
+- Policy as code for compliance
+- Zero trust networking
+- Secrets management as a platform capability
+- Supply chain security (signed images, SBOMs)
+
+### 5. Cost Consciousness
+
+FinOps is everyone's responsibility:
+
+- Tag all resources for cost attribution
+- Provide cost visibility per team/service
+- Right-size infrastructure automatically
+- Clean up unused resources
+- Use spot/preemptible instances where appropriate
+
+## Project Structure
+
+```
+platform/
+├── terraform/                  # Infrastructure as Code
+│   ├── modules/               # Reusable modules
+│   │   ├── networking/
+│   │   ├── compute/
+│   │   ├── data/
+│   │   └── security/
+│   ├── environments/          # Environment configurations
+│   │   ├── dev/
+│   │   ├── staging/
+│   │   └── production/
+│   └── tests/                 # Infrastructure tests
+│
+├── kubernetes/                 # Kubernetes configurations
+│   ├── base/                  # Base manifests (Kustomize)
+│   ├── overlays/              # Environment overlays
+│   │   ├── dev/
+│   │   ├── staging/
+│   │   └── production/
+│   └── charts/                # Helm charts
+│
+├── gitops/                     # GitOps repository
+│   ├── apps/                  # Application definitions
+│   ├── infrastructure/        # Infrastructure apps
+│   └── clusters/              # Cluster configurations
+│
+├── pipelines/                  # CI/CD definitions
+│   ├── .github/workflows/     # GitHub Actions
+│   └── templates/             # Reusable pipeline templates
+│
+├── policies/                   # Policy as Code
+│   ├── opa/                   # Open Policy Agent
+│   └── kyverno/               # Kyverno policies
+│
+├── observability/              # Monitoring configurations
+│   ├── dashboards/            # Grafana dashboards
+│   ├── alerts/                # Alert definitions
+│   └── slos/                  # SLO definitions
+│
+└── docs/                       # Platform documentation
+    ├── runbooks/              # Operational runbooks
+    ├── adrs/                  # Architecture Decision Records
+    └── guides/                # User guides
+```
+
+## Technology Stack
+
+| Layer | Primary | Alternatives |
+|-------|---------|--------------|
+| IaC | Terraform | Pulumi, AWS CDK, Crossplane |
+| Container Orchestration | Kubernetes (EKS/GKE/AKS) | ECS, Nomad |
+| GitOps | Argo CD | Flux, Jenkins X |
+| CI/CD | GitHub Actions | GitLab CI, Tekton, CircleCI |
+| Metrics | Prometheus + Grafana | Datadog, New Relic |
+| Logging | Loki | Elasticsearch, Splunk |
+| Tracing | Tempo/Jaeger | Zipkin, X-Ray |
+| Service Mesh | Istio | Linkerd, Cilium |
+| Policy Engine | OPA/Gatekeeper | Kyverno, Kubewarden |
+| Secrets | HashiCorp Vault | AWS Secrets Manager, SOPS |
+| IDP | Backstage | Port, Cortex |
+
+## Staff Engineer Responsibilities
+
+### Technical Leadership
+
+- Define and evolve platform architecture
+- Make build vs. buy decisions
+- Establish standards and best practices
+- Mentor engineers across teams
+- Drive technical initiatives
+
+### Cross-Team Enablement
+
+- Understand needs across engineering teams
+- Design solutions that scale across the organization
+- Remove friction from the developer experience
+- Build reusable components and patterns
+- Document and communicate platform capabilities
+
+### Operational Excellence
+
+- Define and maintain SLOs for platform services
+- Reduce toil through automation
+- Establish incident response procedures
+- Conduct architecture reviews
+- Plan capacity and scaling strategies
+
+### Strategic Thinking
+
+- Align platform roadmap with business goals
+- Evaluate emerging technologies
+- Plan migration and upgrade paths
+- Balance short-term needs with long-term vision
+- Manage technical debt
+
+## Definition of Done
+
+### Infrastructure Change
+
+- [ ] IaC passes linting and validation
+- [ ] Plan reviewed and approved
+- [ ] Changes tested in non-production first
+- [ ] Rollback procedure documented
+- [ ] Monitoring/alerting in place
+- [ ] Runbook updated
+- [ ] Cost impact assessed
+- [ ] Security review completed
+
+### Platform Feature
+
+- [ ] Self-service capable (no manual intervention)
+- [ ] Documentation complete (how-to, troubleshooting)
+- [ ] Integrated into golden path
+- [ ] Metrics exposed for SLOs
+- [ ] Tested with real workloads
+- [ ] Feedback collected from users
+- [ ] Support runbook created
+
+## Anti-Patterns to Avoid
+
+### "We'll Automate It Later"
+
+❌ **Wrong**: Manual processes that "work for now"
+
+✅ **Right**: Automate from the start; manual doesn't scale
+
+### "Just File a Ticket"
+
+❌ **Wrong**: Platform team as a ticket-processing queue
+
+✅ **Right**: Self-service automation; handle platform, not tickets
+
+### "One Size Fits All"
+
+❌ **Wrong**: Forcing every team into identical workflows
+
+✅ **Right**: Provide guardrails with flexibility for legitimate needs
+
+### "Complexity as a Feature"
+
+❌ **Wrong**: Over-engineered solutions for simple problems
+
+✅ **Right**: Right-size solutions; complexity has ongoing costs