OpenSpec: Spec-Driven Development for Platform Engineering with AI Agents

npm install -g @fission-ai/openspec@latest

openspec --version

mi-plataforma/
├── .openspec/
│   ├── config.yaml                    # Configuracion del proyecto
│   ├── active/                        # Cambios en curso
│   │   └── add-storage-module/
│   │       ├── proposal.md            # Que se va a construir y por que
│   │       ├── specs/                 # Especificaciones tecnicas detalladas
│   │       │   └── storage-account.md
│   │       ├── design.md              # Decisiones de diseno
│   │       └── tasks.md               # Lista de tareas atomicas
│   └── archive/                       # Cambios completados (historial)
│       └── 2026-04-15-vpc-module/
│           ├── proposal.md
│           ├── specs/
│           ├── design.md
│           └── tasks.md
├── terraform/
└── k8s/

# .openspec/config.yaml
project:
  name: "acme-platform"
  description: "Plataforma multi-tenant sobre Azure con Terraform y ArgoCD"

schema: spec-driven          # spec-driven | minimalist | event-driven

paths:
  active: ".openspec/active"
  archive: ".openspec/archive"
  specs: "specs"

conventions:
  naming: kebab-case         # Nombres de carpetas de cambios
  language: es               # Idioma de las specs generadas
  require_design: true       # Forzar design.md en cada cambio
  require_tasks: true        # Forzar tasks.md con lista atomica

validation:
  max_tasks_per_spec: 15     # Evitar specs demasiado grandes
  require_acceptance_criteria: true

# .openspec/active/add-storage-module/proposal.md

## Propuesta: Modulo Storage Account Azure

### Contexto
El equipo de datos necesita un Storage Account con blob containers
para el pipeline de ingest. Actualmente se crean manualmente.

### Requisitos
- Replicacion GRS (geo-redundant)
- Soft-delete habilitado (30 dias)
- Private Endpoint en la subnet de datos
- Tags obligatorios: Owner, Project, Environment, CostCenter
- HTTPS-only, TLS 1.2 minimo

### Criterios de aceptacion
- [ ] terraform validate pasa sin errores
- [ ] terraform plan no muestra "forces replacement"
- [ ] Cumple security-baseline.md

# Navega a la raiz de tu proyecto
cd ~/projects/acme-platform

# Inicializa OpenSpec con el esquema por defecto (spec-driven)
openspec init

# Resultado:
# Created .openspec/config.yaml
# Created .openspec/active/
# Created .openspec/archive/
# OpenSpec initialized with schema: spec-driven

/opsx:propose Crear modulo Terraform para Azure Storage Account con Private Endpoint y soft-delete

# Ejecuta las tareas definidas en la spec
/opsx:apply crear-modulo-terraform-storage

# Una vez completado y validado, archiva
/opsx:archive crear-modulo-terraform-storage

# Instalar spec-gen
npm install -g spec-gen

# Analizar el codebase existente
spec-gen analyze ./terraform/modules/

# Generar specs a partir del codigo actual
spec-gen generate --output .openspec/archive/baseline/

# Resultado:
# Analyzed 12 Terraform modules
# Generated 12 spec files in .openspec/archive/baseline/specs/
# Generated design.md with architectural decisions
# Generated tasks.md with current implementation status

# .github/workflows/spec-drift.yaml
name: Spec Drift Detection
on:
  pull_request:
    paths:
      - 'terraform/**'
      - 'k8s/**'

jobs:
  spec-drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install spec-gen
        run: npm install -g spec-gen

      - name: Detect spec drift
        run: |
          spec-gen analyze ./terraform/modules/ --compare .openspec/archive/baseline/
          if [ $? -ne 0 ]; then
            echo "::error::Spec drift detected. Run 'spec-gen analyze' locally and update specs."
            exit 1
          fi

      - name: Verify active spec exists for changes
        run: |
          CHANGED_MODULES=$(git diff --name-only origin/main -- terraform/ | head -20)
          if [ -n "$CHANGED_MODULES" ] && [ -z "$(ls .openspec/active/ 2>/dev/null)" ]; then
            echo "::error::Terraform changes detected without an active OpenSpec proposal."
            echo "Run '/opsx:propose' before making infrastructure changes."
            exit 1
          fi

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: openspec-check
        name: Verify OpenSpec proposal exists
        entry: bash -c 'if git diff --cached --name-only | grep -q "terraform/\|k8s/"; then ls .openspec/active/*/proposal.md >/dev/null 2>&1 || (echo "ERROR: No active OpenSpec proposal found for IaC changes. Run /opsx:propose first." && exit 1); fi'
        language: system
        pass_filenames: false

# Generar tests a partir de la spec activa
spec-gen test --spec .openspec/active/add-storage-module/

# Resultado: genera tests que validan los criterios de aceptacion
# - test_storage_replication_is_grs.py
# - test_storage_soft_delete_enabled.py
# - test_storage_private_endpoint.py
# - test_storage_tls_minimum.py

# .openspec/config.yaml - esquema personalizado
schema: custom

custom_schema:
  proposal:
    required_sections:
      - context
      - requirements
      - security_impact        # Seccion obligatoria para Platform Eng
      - tenant_impact           # Impacto en tenants de la plataforma
      - cost_estimation         # Estimacion de costes cloud
      - acceptance_criteria
      - rollback_plan           # Plan de rollback obligatorio

  specs:
    templates:
      - terraform-module.md
      - k8s-manifest.md
      - network-policy.md

  design:
    required_sections:
      - architecture_decision
      - alternatives_evaluated
      - security_review
      - compliance_checklist    # GDPR, SOC2, ISO27001

  tasks:
    max_items: 15
    require_estimation: true    # Cada tarea con estimacion de tiempo
    require_owner: true         # Asignar responsable por tarea

// Configuracion MCP para OpenCode/Claude Code
// .mcp.json o mcp_servers en config
{
  "mcpServers": {
    "spec-gen": {
      "command": "spec-gen",
      "args": ["mcp-server"],
      "env": {
        "SPEC_ROOT": ".openspec",
        "LLM_PROVIDER": "anthropic"
      }
    }
  }
}

# .openspec/active/add-storage-module/design.md

## Decision: Usar Private Endpoint en vez de Service Endpoint

### Contexto
Azure ofrece dos mecanismos de conectividad privada para Storage:
Service Endpoints (gratuitos, subnet-level) y Private Endpoints
(coste por hora, IP privada dedicada).

### Decision
Private Endpoint.

### Justificacion
- Service Endpoints no proporcionan IP privada (el trafico sale por backbone Azure pero la resolucion DNS sigue siendo publica)
- Private Endpoint permite DNS resolution privada end-to-end
- Requerido por la politica de seguridad SOC2-CC6.1

### Alternativas descartadas
- Service Endpoint: no cumple requisito de DNS privado
- VNet Integration: no disponible para Storage Account

# Agente 1: trabajando en el modulo de storage
git worktree add ../platform-storage feature/add-storage-module
cd ../platform-storage
# /opsx:apply add-storage-module

# Agente 2: trabajando en network policies (en paralelo)
git worktree add ../platform-network feature/update-network-policies
cd ../platform-network
# /opsx:apply update-network-policies

# Cada agente tiene su propia spec activa y su propio worktree
# Sin conflictos de merge hasta el PR

// .opencode/skills/openspec-sdd.json
{
  "name": "openspec-sdd",
  "trigger": "opsx",
  "description": "Activa el flujo Spec-Driven Development con OpenSpec",
  "instruction": "Al detectar el directorio .openspec/ o recibir el trigger 'opsx':\n1. Lee .openspec/config.yaml para entender el esquema activo\n2. Si el usuario pide un cambio de infraestructura, SIEMPRE ejecuta /opsx:propose primero\n3. NO generes codigo hasta que la spec este revisada y aprobada\n4. Usa /opsx:apply solo despues de confirmacion explicita\n5. Archiva con /opsx:archive al completar",
  "context_files": [".openspec/config.yaml"]
}

# Clonar el skill a tu directorio de skills
mkdir -p .opencode/skills/
curl -o .opencode/skills/openspec-sdd.json \
  https://raw.githubusercontent.com/awesome-opencode/awesome-opencode/main/skills/openspec-sdd.json

{
  "agent": {
    "nv-orchestrator": {
      "mode": "primary",
      "model": "claude-3-5-sonnet-20241022",
      "prompt": "REGLA CRITICA: Si el usuario pide un cambio en terraform/ o k8s/, verifica que exista un directorio en .openspec/active/ con una proposal.md aprobada. Si NO existe, ejecuta /opsx:propose primero. NUNCA delegues a nv-code sin una spec activa. Esta regla no tiene excepciones.",
      "constraints": {
        "require_active_spec_for": ["terraform/**", "k8s/**", "helm/**"]
      }
    }
  }
}