Imported from e-burgos/crypto-trader (sdd/skills/sdd-data-schemas/SKILL.md). Install upstream with npx skills add e-burgos/crypto-trader --skill sdd-data-schemas. Copyright stays with the author.

Skill: sdd-data-schemas

⛔ LECTURA OBLIGATORIA para cualquier agente que escriba en un registro SDD. Este skill cubre el contenido de los archivos. Para rutas y naming ver sdd-file-structure.

🤖 Fuente de verdad de máquina: cada registro tiene un JSON Schema estricto en sdd/schemas/*.schema.json (additionalProperties: false) y declara $schema. Si este documento y el schema difieren, gana el schema. Después de escribir cualquier registro: pnpm sdd:validate. Si tocaste tasks: pnpm sdd:rebuild-tasks-index.

0. Reglas globales antes de leer cualquier schema

App-keys válidos

Agregar nuevas apps/libs según monorepo.apps y monorepo.libs de sdd/global.json. Ambos son mapas nombre -> descripción; el visor de pnpm sdd:docs descubre el contexto de cada subproyecto a partir de ellos, así que una lib ausente del mapa no aparece listada.

1. sdd/specs/index.json — Registro de specs

Responsable: quien crea la spec (append-only, nunca editar entradas existentes).

SpecEntry — campos

{
  "id": "spec-[gh-user]-[NNN]-[slug]",
  "author": "[gh-user]",
  "slug": "[slug]",
  "folder": "sdd/specs/spec-[gh-user]-[NNN]-[slug]",
  "file": "sdd/specs/spec-[gh-user]-[NNN]-[slug]/spec-[gh-user]-[NNN]-[slug].spec.md",
  "module": "[nombre-módulo]",
  "app": "apps/[nombre-app]",
  "status": "draft | in-progress | completed | cancelled",
  "title": "Título legible (máx 80 chars)",
  "created_at": "YYYY-MM-DD",
  "completed_at": "YYYY-MM-DD | null",
  "depends_on": ["spec-[gh-user]-[NNN]-[slug]"]
}

Reglas de SpecEntry

• id = nombre exacto de la carpeta bajo sdd/specs/
• [NNN] = contador personal del dev (001, 002…). No global.
• depends_on = array vacío [] si no hay dependencias
• status nace "draft" (spec escrita o en escritura, sin ciclo abierto — desde v0.11.0; harness add spec la crea así y registra el módulo en pending_modules de sdd/global.json). El sdd-orchestrator la pasa a "in-progress" al crear cycle-01 de esa spec. Índices previos a v0.11.0 tienen "in-progress" para specs sin ciclo — el validador sugiere la migración, nunca reescribe datos.
• completed_at = null mientras status es draft o in-progress
• Registrar ANTES de crear los archivos del ciclo

2. sdd/global.json — Estado general del monorepo

Responsable: sdd-orchestrator (al iniciar ciclo) + sdd-reviewer (al cerrar ciclo).

Estructura top-level

{
  "$schema": "./schemas/global.schema.json",
  "project": "[nombre-del-proyecto]",
  "description": "...",
  "version": "1.0.0",
  "completed_modules": [],
  "in_progress_modules": [],
  "pending_modules": [],
  "monorepo": {
    "tool": "Nx",
    "package_manager": "pnpm",
    "apps": {},
    "libs": {}
  }
}

⚠️ Ya no existe current_cycle global — la numeración de ciclos es per-spec (cycles/cycle-XX).

ModuleEntry — campos

{
  "module": "[nombre-módulo]",
  "spec": "spec-[gh-user]-[NNN]-[slug]",
  "apps": ["apps/[nombre-app]"],
  "cycles_completed": 1,
  "completed_at": "YYYY-MM-DD",
  "description": "Qué hace este módulo (1-2 oraciones)"
}

• apps es siempre array (aunque el módulo toque una sola app).
• cycles_completed = cantidad de ciclos de ESA spec con status: "completed".
• completed_at y description son obligatorios solo en completed_modules.

Ciclo de vida de un módulo en global.json

pending_modules → in_progress_modules → completed_modules

⛔ Regla de concurrencia: un ciclo activo por spec. Varios devs pueden tener módulos en in_progress_modules a la vez (modelo multi-developer), pero una misma spec nunca tiene dos ciclos abiertos.

3. sdd/api.json — Registro de endpoints

Responsable: sdd-architect (status: defined) → sdd-implementor-back (status: implemented) → sdd-reviewer.

Estructura

{
  "_comment": "...",
  "_schema": { ... },
  "[app-key]": {
    "endpoints": [ EndpointEntry ]
  }
}

EndpointEntry — campos

{
  "id": "EP-[NNN]",
  "method": "GET | POST | PUT | PATCH | DELETE",
  "path": "/ruta/del/endpoint/{param}",
  "module": "[nombre-módulo]",
  "spec": "sdd/specs/spec-[gh-user]-[NNN]-[slug]",
  "status": "defined | implemented | updated | deprecated",
  "created_in_cycle": 1,
  "updated_in_cycle": null,
  "description": "Qué hace el endpoint",
  "path_params": ["param1"],
  "required_headers": ["Authorization", "Content-Type"],
  "request_body": {},
  "responses": {
    "200": "descripción de la respuesta OK",
    "400": "descripción del error"
  },
  "changelog": []
}

Reglas de EndpointEntry

4. sdd/schema.json — Registro de tablas de BD

Responsable: sdd-architect (diseño) + sdd-implementor-back (migración) + sdd-reviewer.

Estructura

{
  "_comment": "...",
  "_schema": { ... },
  "[app-key]": {
    "tables": {
      "[nombre_tabla]": TableEntry
    }
  }
}

Solo apps backend tienen tablas. Apps frontend no tienen entradas en schema.json.

TableEntry — campos

{
  "module": "[nombre-módulo]",
  "spec": "sdd/specs/spec-[gh-user]-[NNN]-[slug]",
  "status": "defined | migrated | updated | deprecated",
  "created_in_cycle": 1,
  "updated_in_cycle": null,
  "migration_file": "V1__create_[tabla].sql",
  "columns": {
    "[nombre_columna]": {
      "type": "CHAR(36) | VARCHAR(255) | BIGINT | TEXT | DATETIME | BOOLEAN | DECIMAL(10,2)",
      "constraints": ["PRIMARY KEY", "NOT NULL", "UNIQUE", "AUTO_INCREMENT"],
      "notes": "Descripción del propósito de la columna"
    }
  },
  "indexes": [
    { "name": "idx_[tabla]_[campo]", "columns": ["campo1"], "unique": false }
  ],
  "changelog": []
}

Reglas de TableEntry

ColumnEntry — constraints válidos

"PRIMARY KEY"  "NOT NULL"  "UNIQUE"  "AUTO_INCREMENT"
"DEFAULT 'valor'"  "REFERENCES tabla(col)"

5. sdd/components.json — Registro de componentes frontend

Responsable: sdd-architect (status: defined) → sdd-implementor-front (status: implemented) → sdd-reviewer.

Estructura

{
  "_comment": "...",
  "_schema": { ... },
  "[app-key]": {
    "components": [ ComponentEntry ]
  }
}

Solo apps frontend tienen componentes. Usar "apps/example-app" como app-key para apps frontend.

ComponentEntry — campos

{
  "id": "COMP-[NNN]",
  "name": "NombreComponente",
  "type": "page | component | hook | layout",
  "module": "[nombre-módulo]",
  "spec": "sdd/specs/spec-[gh-user]-[NNN]-[slug]",
  "path": "src/pages/[modulo]/NombreComponente.tsx",
  "status": "defined | implemented | updated | deprecated",
  "created_in_cycle": 1,
  "updated_in_cycle": null,
  "description": "Qué hace el componente",
  "consumes": ["EP-001"],
  "created_at": "YYYY-MM-DD",
  "changelog": []
}

Reglas de ComponentEntry

6. Tasks — per-cycle tasks.json + índice sdd/tasks.json

⛔ Las tasks canónicas viven en sdd/specs/{spec-id}/cycles/cycle-[XX]/tasks.json (uno por ciclo). sdd/tasks.json es solo un índice liviano derivado — nunca editar detalle de tasks ahí. Schemas: sdd/schemas/cycle-tasks.schema.json y sdd/schemas/tasks-index.schema.json.

6a. cycles/cycle-[XX]/tasks.json — archivo canónico del ciclo

Responsable: sdd-planner (crea) → sdd-implementor-* (status por task) → sdd-reviewer (cierre).

{
  "$schema": "../../../../schemas/cycle-tasks.schema.json",
  "spec": "spec-[gh-user]-[NNN]-[slug]",
  "cycle": 1,
  "module": "[nombre-módulo]",
  "apps": ["apps/[nombre-app]"],
  "flow": "full",
  "user_stories_generated": true,
  "prerequisites": { "tasks_generated": true },
  "tasks": [ TaskEntry ]
}

• flow: "reduced" = ciclo de refactor estructural sin HUs (las tasks pueden tener user_stories: []).
• Cada developer/implementador solo escribe en el archivo de SU ciclo → sin merge conflicts entre specs.

6b. sdd/tasks.json — índice (generado)

Responsable: sdd-orchestrator (alta de ciclo) + sdd-reviewer (cierre). Se regenera con pnpm sdd:rebuild-tasks-index.

{
  "$schema": "./schemas/tasks-index.schema.json",
  "sdd_version": "4.0",
  "specs": {
    "[spec-id]": {
      "cycles": {
        "cycle-[XX]": {
          "file": "sdd/specs/[spec-id]/cycles/cycle-[XX]/tasks.json",
          "module": "[nombre-módulo]",
          "apps": ["apps/[nombre-app]"],
          "status": "in-progress | completed",
          "tasks_total": 10,
          "tasks_done": 10
        }
      }
    }
  }
}

El índice nunca es fuente de verdad: si difiere de los per-cycle, regenerarlo. pnpm sdd:validate falla si el índice está desactualizado.

TaskEntry — campos

{
  "id": "TASK-[NNN]",
  "title": "Título conciso de la task",
  "user_stories": ["HU-01", "HU-02"],
  "estimation_hours": 2,
  "story_points": 3,
  "depends_on": ["TASK-[NNN]"],
  "status": "pending | in-progress | done | skipped",
  "files": ["apps/[app]/src/ruta/Archivo.java"],
  "usage": {
    "tokens_in": 42000,
    "tokens_out": 8000,
    "duration_minutes": 25,
    "provider_model": "copilot/claude-sonnet",
    "effort": "medium",
    "agent": "implementor-back",
    "approx": true,
    "source": "declared-estimate",
    "recorded_at": "YYYY-MM-DD"
  }
}

⛔ TODOS los campos de TaskEntry son obligatorios excepto usage (additionalProperties: false en el schema). Una task sin estimation_hours o story_points no pasa pnpm sdd:validate. usage es opcional en el schema para que los registros escritos antes de v0.9.0 sigan validando, pero desde v0.11.0 el protocolo lo exige: ver §8.1. provider_model es el nombre vigente del campo (proveedor/modelo); model_tier es el alias legacy pre-0.11 — se sigue leyendo, ya no se escribe. Cuando el harness reporta el consumo del subagente que ejecutó la task (agent-usage-notification, ej. Claude Code Agent), quien recibe la notificación (típicamente el orquestador) vuelca ese número exacto acá — tokens_total + split 85/15 documentado en tokens_in/tokens_out, approx: false.

Reglas de TaskEntry

Escala de Story Points recomendada

Una task > 8h debe dividirse en subtasks.

7. sdd/fixes.json — Registro global de fixes

Responsable: sdd-orchestrator (FIX GATE) + sdd-reviewer (cierre).

Estructura

{
  "$schema": "./schemas/fixes.schema.json",
  "_description": "...",
  "_version": "3.0.0",
  "_convention": "...",
  "_keywords": ["[FIX]", "[BUGFIX]", "[HOTFIX]", "[IMPROVEMENT]"],
  "fixes": [ FixEntry ]
}

FixEntry — campos

{
  "id": "FIX-[gh-user]-[seq] | FIX-[gh-user]-[spec-NNN]-[seq]",
  "author": "[gh-user]",
  "spec_id": "spec-[gh-user]-[NNN]-[slug] | null",
  "fix_document": "sdd/fixes/fix-[gh-user]-[seq].md | sdd/specs/{spec-id}/fixes/fix-[...].md",
  "type": "HOTFIX | BUGFIX | FIX | IMPROVEMENT",
  "severity": "critical | high | medium | low",
  "created_at": "YYYY-MM-DD",
  "resolved_at": "YYYY-MM-DD | null",
  "validated_at": "YYYY-MM-DD | null",
  "title": "Título del fix (máx 120 chars)",
  "estimation_hours": 1.5,
  "description": "Explicación detallada del problema y la solución",
  "justification": "Why this cannot wait for a full SDD cycle",
  "related_modules": ["[módulo o app afectada]"],
  "affected_files": ["path/to/file1.ts", "path/to/file2.java"],
  "test_reference": "referencia al test que valida el fix | null",
  "status": "pending | in-progress | implemented | validated | absorbed",
  "cycle": "cycle-[XX] | null",
  "usage": {
    "tokens_in": 15000,
    "tokens_out": 3000,
    "provider_model": "claude/sonnet",
    "effort": "medium",
    "agent": "implementor-back",
    "approx": false,
    "source": "session-report",
    "recorded_at": "YYYY-MM-DD"
  }
}

Ciclo de vida del status

pending → in-progress → implemented (dev) → validated | absorbed (sdd-reviewer al cerrar el ciclo)

• implemented exige resolved_at (validado por pnpm sdd:validate)
• validated = el Reviewer confirmó el fix; absorbed = la solución se formaliza en la próxima spec
• usage — obligatorio al resolver (mismos campos que TaskEntry, ver §8.1). Lo registra quien resuelve el fix, no el reviewer que lo absorbe. Si participó más de un agente, cada uno va en usage.by_agent[] y el nivel superior (tokens_in/tokens_out) es la suma

Convención de ID de fix

• spec_id: null → fix repo-level → archivo en sdd/fixes/
• spec_id: "spec-..." → fix spec-scoped → archivo en sdd/specs/{spec-id}/fixes/
• [seq] = número correlativo dentro de su scope (001, 002…)

8. sdd/specs/{spec-id}/cycles/cycle-[XX]/cycle.json — Estado del ciclo

Responsable: sdd-orchestrator (al iniciar, status: "in-progress") → sdd-reviewer (al cerrar, status: "completed").

Al INICIAR el ciclo (sdd-orchestrator)

{
  "$schema": "../../../../schemas/cycle.schema.json",
  "cycle": 1,
  "module": "[nombre-módulo]",
  "spec": "spec-[gh-user]-[NNN]-[slug]",
  "apps": ["apps/[nombre-app]"],
  "phase": "[nombre-fase]",
  "status": "in-progress",
  "started_at": "YYYY-MM-DD",
  "completed_at": null,
  "documents": {
    "brief": "sdd/specs/{spec-id}/cycles/cycle-[XX]/brief.yaml",
    "functional": "sdd/specs/{spec-id}/cycles/cycle-[XX]/functional.md",
    "planner": "sdd/specs/{spec-id}/cycles/cycle-[XX]/planner.md",
    "architect": "sdd/specs/{spec-id}/cycles/cycle-[XX]/architect.md",
    "tasks": "sdd/specs/{spec-id}/cycles/cycle-[XX]/tasks.json"
  },
  "artifacts": [],
  "metrics": {
    "tasks_total": 0,
    "tasks_completed": 0,
    "story_points": 0,
    "files_created": [],
    "files_modified": [],
    "files_deleted": [],
    "usage": { "tokens_in": 0, "tokens_out": 0, "by_agent": [] }
  },
  "tables_created": [],
  "endpoints_implemented": [],
  "components_created": [],
  "issues_found": [],
  "reviewer_report": null
}

• apps es siempre array. Campos opcionales: phase, flow ("reduced" para refactors sin HUs), objectives.
• En documents solo se listan archivos que existen (un ciclo flow: "reduced" puede omitir functional/planner/architect).
• metrics no nace null desde v0.11.0: el orquestador lo crea con contadores en 0 y usage.by_agent: [] al abrir el ciclo — es el receptáculo donde cada agente (functional, planner, architect, cada task, el propio orquestador) hace push de su entrada al cerrar su unidad de trabajo. tokens_in/tokens_out son obligatorios dentro de usage por schema, por eso arrancan en 0; el reviewer los recalcula como suma de by_agent al cerrar (§8.1).

Al CERRAR el ciclo (sdd-reviewer)

{
  "cycle": 1,
  "module": "[nombre-módulo]",
  "spec": "spec-[gh-user]-[NNN]-[slug]",
  "app": "apps/[nombre-app]",
  "phase": "[nombre-fase]",
  "status": "completed",
  "started_at": "YYYY-MM-DD",
  "completed_at": "YYYY-MM-DD",
  "documents": { ... },
  "artifacts": ["sdd/specs/{spec-id}/cycles/cycle-[XX]/artifacts/diagrama.png"],
  "metrics": {
    "tasks_total": 8,
    "tasks_completed": 7,
    "tasks_skipped": 1,
    "story_points": 13,
    "files_created": ["apps/.../Archivo.java"],
    "files_modified": ["apps/.../OtroArchivo.java"],
    "files_deleted": [],
    "usage": {
      "tokens_in": 480000,
      "tokens_out": 62000,
      "duration_minutes": 190,
      "approx": true,
      "source": "declared-estimate",
      "by_agent": [
        { "agent": "functional", "provider_model": "claude/sonnet", "effort": "medium", "tokens_in": 30000, "tokens_out": 4000, "approx": false, "source": "session-report", "recorded_at": "YYYY-MM-DD" },
        { "agent": "implementor-back", "label": "TASK-001", "provider_model": "copilot/claude-sonnet", "effort": "medium", "tokens_in": 420000, "tokens_out": 55000, "approx": true, "source": "declared-estimate", "recorded_at": "YYYY-MM-DD" },
        { "agent": "reviewer", "provider_model": "claude/opus", "effort": "high", "tokens_in": 30000, "tokens_out": 3000, "approx": false, "source": "session-report", "recorded_at": "YYYY-MM-DD" }
      ],
      "by_tier": {
        "claude/sonnet": { "tokens_in": 30000, "tokens_out": 4000, "approx": false, "source": "session-report" },
        "copilot/claude-sonnet": { "tokens_in": 420000, "tokens_out": 55000, "approx": true, "source": "declared-estimate" },
        "claude/opus": { "tokens_in": 30000, "tokens_out": 3000, "approx": false, "source": "session-report" }
      }
    }
  },
  "tables_created": ["nombre_tabla"],
  "endpoints_implemented": ["EP-001"],
  "components_created": ["COMP-001"],
  "issues_found": ["Descripción de issue encontrado y cómo se resolvió"],
  "reviewer_report": {
    "approved": true,
    "date": "YYYY-MM-DD",
    "ca_results": {
      "CA-001": "PASS | FAIL — descripción"
    },
    "tests": {
      "NombreTest": "N/N PASS"
    },
    "notes": "Resumen del ciclo"
  }
}

Reglas de cycle.json

• cycle.json DEBE CREARSE antes de que cualquier agente implementador escriba código
• status: "in-progress" → creado por sdd-orchestrator
• status: "completed" → solo el sdd-reviewer puede setearlo
• artifacts: [] → listar solo archivos de soporte del ciclo, no los archivos implementados
• tables_created → nombres de tabla (coinciden con keys en sdd/schema.json)
• endpoints_implemented → IDs de EP (coinciden con id en sdd/api.json)
• components_created → IDs de COMP (coinciden con id en sdd/components.json)
• tasks_skipped → tasks cerradas como skipped (resueltas / no aplican). Ausente se lee como 0. En un ciclo completed, tasks_completed + tasks_skipped debe igualar tasks_total

8.1 Telemetría de uso (usage) — OBLIGATORIA al cerrar

Alimenta el dashboard de Costos del visor SDD, que compara la estimación tradicional (horas × tarifa) contra el costo real del modo agéntico. Sin telemetría, el ahorro que justifica la metodología no tiene evidencia.

El bloque usage vive en tres lugares:

Quien ejecuta registra; nadie reconstruye al final. functional, planner y architect no tienen fila propia en tasks.json — al terminar su documento hacen push de su entrada en cycle.json → metrics.usage.by_agent[] (el orquestador ya creó metrics con by_agent: [] al abrir el ciclo, ver §8). by_agent es la fuente de verdad: una entrada por unidad de trabajo (cada task, cada documento, la coordinación del orquestador, la revisión del reviewer). by_tier se deriva de by_agent agrupando por provider_model — nunca se llena a mano por separado. El reviewer, al cerrar, verifica que by_agent tenga una entrada por task done

• una por documento + orquestador + reviewer, deriva by_tier, y solo entonces suma tokens_in/tokens_out de nivel superior. Su propia estimación cubre únicamente lo que ninguna unidad registró. Una suma que mezcla medido con estimado queda approx: true en esa entrada de by_tier: un total es tan honesto como su parte más floja.

Campos

La regla que reemplaza al "ante la duda, omitir"

Nunca se omite la telemetría por no tener un contador exacto. El modelo siempre se conoce —es el que estás usando— y el orden de magnitud del consumo también. Los arneses sin contador por sesión (GitHub Copilot, Antigravity) registran una estimación declarada:

"usage": { "tokens_in": 480000, "tokens_out": 62000, "provider_model": "copilot/claude-sonnet", "effort": "medium", "agent": "implementor-back", "approx": true, "source": "declared-estimate", "recorded_at": "YYYY-MM-DD" }

/stats (Gemini CLI) y el reporte de uso de la sesión (Claude Code) son comandos del cliente: un agente no puede ejecutarlos. Pedíselos al dev si querés el número medido; si no están a mano, registrá la estimación y seguí — un ciclo cerrado sin usage es un cierre incompleto.

En Claude Code, cuando un agente dispara un subagente con la tool Agent, la notificación de cierre trae el conteo exacto (agent-usage-notification) — quien la recibe (orquestador o reviewer) lo vuelca directo en tasks[].usage y en by_agent, sin pedirle nada al dev.

Lo único prohibido es inventar un número preciso y presentarlo como medido: approx: false sin contador detrás (y approx: false combinado con source: declared-estimate es un error del validador, no un warning). pnpm sdd:validate marca error si un ciclo completed (o un fix resuelto) desde el 2026-09-02 no tiene usage con proveedor/modelo y tokens; warning si by_agent falta o sum(by_agent) ≠ by_tier. Registros anteriores a esa fecha solo generan warning.

9. Valores de status por registro

* updated se puede repetir múltiples veces (con nuevo updated_in_cycle y entrada en changelog).

** done y skipped son ambos terminales: una task skipped está resuelta (no aplica), no pendiente. El ciclo cierra cuando tasks_completed + tasks_skipped == tasks_total, y el visor la cuenta como resuelta en el progreso.

10. Convenciones de IDs

11. Anti-patrones frecuentes (EVITAR)

12. Regla de sincronización entre registros

Cuando el sdd-reviewer cierra un ciclo, todos estos archivos deben actualizarse en la misma operación:

cycle.json                        → status: "completed", completed_at, metrics, reviewer_report
global.json                       → mover módulo de in_progress a completed
specs/index.json                  → status: "completed" + completed_at (si era el último ciclo de la spec)
api.json                          → status: "implemented" en endpoints del ciclo
schema.json                       → status: "migrated" en tablas del ciclo
components.json                   → status: "implemented" en componentes del ciclo
cycles/cycle-XX/tasks.json        → status: "done" en todas las tasks del ciclo
sdd/tasks.json                    → regenerar: pnpm sdd:rebuild-tasks-index
context/[apps|libs|tools]/[nombre]/updates/YYYY-MM-DD-[spec-id]-cycle-[XX].md
                                  → fragmento aditivo con el delta del ciclo (mecanismo 🧩;
                                    los archivos base solo los toca la consolidación)

⛔ Si cycle.json queda en status: "completed" sin que los demás registros estén actualizados, el sistema SDD pierde consistencia. El sdd-reviewer es responsable de la sincronización completa. El cierre no es válido hasta que pnpm sdd:validate esté en verde.

13. Skills relacionados