Skip to content

openspec.md

Latest commit

 

History

History
191 lines (148 loc) · 6.31 KB

openspec.md

File metadata and controls

191 lines (148 loc) · 6.31 KB
Raw

OpenSpec y artefactos

OpenSpec es la memoria compartible del workflow. Sin OpenSpec, todo depende de la conversacion; con OpenSpec, el estado vive en archivos versionables.

El orquestador actual usa openspec como modo operativo para cambios SDD. Algunos skills conservan compatibilidad con modo none, pero este bundle esta pensado para persistir artefactos en el repo.

Estructura

openspec/
  config.yaml
  specs/
    {domain}/
      spec.md
  changes/
    archive/
    {change-name}/
      state.yaml
      exploration.md
      proposal.md
      proposal-lite.md
      design.md
      tasks.md
      apply-progress.md
      verify-report.md
      archive-report.md
      specs/
        {domain}/
          spec.md

openspec/config.yaml

Guarda contexto del proyecto:

Area Ejemplos
Stack Lenguajes, frameworks, package managers, arquitectura detectada.
Comandos Install, build, test, lint, format, typecheck.
Testing Runner, capas disponibles, coverage, Strict TDD.
Reglas Normas por fase: proposal, specs, design, tasks, apply, verify, archive.
Foundation Docs de producto, baseline tecnico, roadmap y preguntas abiertas.

sdd-init lo crea. sdd-foundation lo completa cuando el proyecto esta vacio.

Specs principales vs specs delta

Tipo Ruta Que significa
Spec principal openspec/specs/{domain}/spec.md Comportamiento vigente del sistema.
Spec delta openspec/changes/{change-name}/specs/{domain}/spec.md Cambio propuesto sobre ese comportamiento.

Durante sdd-spec no se escribe directamente en openspec/specs/. Tanto las modificaciones sobre dominios existentes como las capacidades nuevas viven primero en openspec/changes/{change-name}/specs/.... Para capacidades nuevas, esa spec change-local es temporal por diseno: sdd-archive es la unica fase que la promociona a openspec/specs/{domain}/spec.md.

Formato de delta

Una delta spec usa tres secciones:

## ADDED Requirements

## MODIFIED Requirements

## REMOVED Requirements

La regla critica esta en MODIFIED: copiar el requisito completo desde la spec principal, con todos sus escenarios, y despues editar. Si solo copias el escenario cambiado, al archivar puedes perder el resto. Esto no es un detalle menor: es una fuga de contrato.

Ciclo de artefactos

Fase Artefacto
Explore exploration.md
Propose proposal.md o proposal-lite.md (solo en lite mode)
Spec specs/{domain}/spec.md dentro del cambio
Design design.md
Tasks tasks.md
Apply apply-progress.md y estados [ ] / [~] / [x] en tasks.md
Verify verify-report.md
Archive archive-report.md, specs principales actualizadas y carpeta movida

Ademas, cada fase que persiste artefactos debe leer, fusionar y actualizar openspec/changes/{change-name}/state.yaml. La recuperacion depende de ese archivo; no es un detalle opcional.

change:
  name: add-export-csv
  mode: standard
  current_phase: apply

approvals:
  - id: delivery-strategy-001
    gate: delivery-strategy
    decision: ask-on-risk
    source: vscode/askQuestions
    accepted_at: 2026-06-10T10:30:00+02:00

runtime:
  skill_registry_fingerprint: sha256:abc123
  last_skill_resolution: injected
  last_session_summary: .ospec/session/add-export-csv/session-summary.md
  compaction_safe: true

Assumption Ledger

Ademas de approvals:, state.yaml puede tener un bloque assumptions: que registra las micro-decisiones que un agente de fase resuelve por su cuenta sin bloquear (ver openspec/specs/assumption-ledger/spec.md). Cada entrada trae id (formato {phase}-{seq}, unicidad garantizada por el orquestador al persistir), phase, statement, reversibility (low | high) y basis. Solo una decision con impacto en comportamiento observable o contrato publico bloquea con question_gate; una decision interna nunca bloquea la fase, sin importar su reversibility.

assumptions:
  - id: sdd-design-001
    phase: sdd-design
    statement: "Use camelCase for the internal cache key."
    reversibility: high
    basis: "Matches existing cache-key convention in scripts/lib/cache.js."
    recorded_at: "2026-07-02T00:00:00Z"
    status: unresolved        # unresolved | confirmed | corrected | promoted

sdd-verify re-presenta cada entrada unresolved como checklist (Step 2a, Assumption Reconciliation Pre-flight) ofreciendo confirm, correct o promote-to-clarification (esta ultima solo marca status: promoted; nunca auto-dispara sdd-clarify). Las entradas reversibility: low que quedan sin resolver escalan a WARNING en verify-report.md; las reversibility: high no escalan.

Archivo

Al cerrar un cambio:

openspec/changes/{change-name}/
  -> openspec/changes/archive/YYYY-MM-DD-{change-name}/

Antes de mover, sdd-archive debe validar el cierre:

  • FAIL bloquea el archive.
  • PASS WITH WARNINGS solo puede pasar si los riesgos quedan aceptados de forma explicita o convertidos en follow-up.

Si el cambio tiene delta specs, despues sincroniza specs:

Delta Accion sobre spec principal
ADDED Anadir requisito.
MODIFIED Reemplazar requisito completo por la version nueva.
REMOVED Eliminar requisito indicado con motivo.

El archivo es auditoria. No se borra y no se reescribe a ciegas.

Foundation docs

Para proyectos desde cero, el contexto que todavia no existe en codigo vive en:

docs/
  product/
    brief.md
    functional-scope.md
    glossary.md
  architecture/
    technical-baseline.md
    decisions/
      README.md
  roadmap.md
  references/
    raw/
      README.md
    processed/
      README.md

La regla es sencilla: fuentes crudas en raw/, resumen util y trazable en processed/. No enterramos incertidumbre. Si algo no se sabe, se marca como Unknown o TBD y se formula la siguiente pregunta.

Recuperacion

Si una conversacion se pierde o se compacta, se recupera leyendo:

openspec/config.yaml
openspec/changes/*/state.yaml
openspec/changes/{change-name}/proposal.md o proposal-lite.md
openspec/changes/{change-name}/specs/**
openspec/changes/{change-name}/design.md
openspec/changes/{change-name}/tasks.md
openspec/changes/{change-name}/apply-progress.md

Este es el punto: el proceso no depende de que el modelo "recuerde". Depende de archivos.