SpecNative — cómo trabajar con este framework

Servidor MCP — v0.9

.specnative/specnative_mcp.py expone el repositorio como recursos, herramientas y prompts MCP. Se instala automáticamente con su propio venv. Soporta transporte stdio y SSE.

Configuración rápida — Claude Code

# Agregar desde la CLI (desde la raíz del proyecto)
claude mcp add specnative \
  "$(pwd)/.specnative/.venv/bin/python3" \
  "$(pwd)/.specnative/specnative_mcp.py" \
  -- --repo "$(pwd)"

Recursos

Herramientas — consulta

Herramientas — continuidad multi-agente

Herramientas — definición del proyecto

Herramientas — archetypes (v0.7)

Herramientas — templates (v0.7)

Prompts

Configuración completa para Claude Desktop, OpenCode, Codex y transporte SSE: .specnative/MCP.md

Estructura del repositorio

repo/
├── AGENTS.md              # Meta-índice: qué es SpecNative, referencia MCP — leer primero
├── spec-native/
│   ├── README.md          # Índice de navegación de la carpeta de contexto
│   ├── PRODUCT.md         # Problema, usuarios, objetivos (permanente)
│   ├── ARCHITECTURE.md    # Estructura del sistema y límites
│   ├── STACK.md           # Stack tecnológico y restricciones
│   ├── CONVENTIONS.md     # Reglas de código, naming, testing
│   ├── COMMANDS.md        # Comandos del proyecto (build, test, lint...)
│   ├── DECISIONS.md       # Decisiones persistentes y tradeoffs
│   ├── ROADMAP.md         # Dirección temporal, sin detalle de implementación
│   ├── TRACEABILITY.md    # Vínculos entre artefactos
│   ├── SESSION.md         # Estado activo de trabajo (continuidad multi-agente)
│   ├── specs/
│   │   └── <iniciativa>/SPEC.md
│   ├── spec-native/tasks/
│   │   └── <iniciativa>/TASKS.md
│   ├── backlog/           # Vistas derivadas de entrega; nunca editar el estado aquí
│   ├── spec-native/workflows/
│   │   ├── PLANNING.md
│   │   ├── IMPLEMENTATION.md
│   │   └── REVIEW.md
│   └── spec-native/pipelines/
│       ├── CI.md          # Gates de validación automatizados
│       └── CD.md          # Proceso de entrega y ambientes
├── .claude/commands/      # Slash commands: /spec-init /spec-update /spec-status /spec-handoff
├── codex.toml             # Comandos prompt para Codex CLI
├── opencode.json          # MCP + prompts para OpenCode
└── .specnative/
    ├── SCHEMA.md           # Contrato del framework (no contenido del proyecto)
    ├── MCP.md              # Configuración del servidor MCP por agente
    ├── specnative_mcp.py   # Servidor MCP (instalado automáticamente)
    ├── archetypes/         # Archetypes propios del equipo
    │   └── README.md
    └── templates/          # Spec templates + decision snippets
        ├── specs/          # Plantillas de spec (.md con front matter +++)
        └── decisions/      # Snippets de decisiones (.md con front matter +++)

Los archivos en MAYÚSCULAS son contexto para agentes. Los README.md son índices de navegación, no la fuente de verdad. Carga el mínimo contexto necesario para la tarea actual. SESSION.md persiste el estado activo entre agentes.

Ownership documental — una verdad por documento

Cada documento tiene un dominio semántico exclusivo. Nunca duplicar información entre archivos. Actualiza siempre la fuente de verdad, no un resumen paralelo.

Prueba de decisión — dónde escribir algo

Cómo generar el template completo

Sigue estos pasos en orden cuando ayudes a un usuario a crear un repositorio SpecNative desde cero. Cada paso puebla un documento con el alcance correcto.

1. Inicializar la estructura

   Ejecuta python3 install.py --target /ruta/al/repo --profile context o copia Template-Project-Agents-AI al repositorio destino. Esto crea todas las carpetas obligatorias y los archivos placeholder.

2. Completar spec-native/PRODUCT.md

   Problema (qué fricción existe y para quién), Usuarios (segmentos, necesidades, contexto), Objetivos (resultados medibles), No-objetivos (exclusiones explícitas), Valor diferencial (por qué esta solución merece existir).

3. Completar spec-native/ARCHITECTURE.md

   Módulos del sistema y sus responsabilidades, límites entre módulos y flujos de datos, restricciones arquitectónicas clave. Sin detalle de implementación.

4. Completar spec-native/STACK.md

   Lenguajes y runtimes con versiones exactas, frameworks y librerías, infraestructura y tooling, restricciones y tecnologías prohibidas.

5. Completar spec-native/CONVENTIONS.md

   Convenciones de naming (archivos, clases, variables), reglas de estilo y formato, enfoque de testing (unit / integración / e2e), convenciones de commits y PRs.

6. Completar spec-native/COMMANDS.md

   Solo comandos reales del proyecto: build, test, lint, run/start, migraciones y cualquier comando operativo específico del proyecto. Nunca incluir comandos del CLI del framework aquí.

7. Completar spec-native/ROADMAP.md

   Prioridades actuales en orden con justificación del ordenamiento. Horizonte temporal aproximado. Sin detalle de implementación ni contenido de spec.

8. Crear spec-native/specs/<iniciativa>/SPEC.md

   ID, estado, owner, fechas de creación y actualización. Resumen, problema, objetivo. Alcance (incluye / excluye). Requisitos funcionales y no funcionales. Criterios de aceptación (Dado / Cuando / Entonces). Dependencias y riesgos. Plan de ejecución. Plan de validación.

9. Derivar spec-native/tasks/<iniciativa>/TASKS.md

   Una tarea por unidad implementable. Cada tarea: ID, estado, owner, dependencias, archivos esperados, criterio observable de cierre, comando de validación.

10. Registrar decisiones en spec-native/DECISIONS.md

    Solo tradeoffs persistentes que las próximas iniciativas deben respetar. Formato: DEC-XXXX, fecha, estado, contexto, decisión, consecuencias, reemplaza.

11. Completar spec-native/pipelines/CI.md y spec-native/pipelines/CD.md

    CI: plataforma, triggers, gates obligatorios y opcionales, política de fallo. CD: ambientes, proceso de release, gates de promoción, proceso de rollback.

12. Actualizar spec-native/TRACEABILITY.md al cerrar la iniciativa

    Vincular spec → tareas → decisiones → artefactos principales → evidencia de validación. Actualizar al cierre, no durante la ejecución.

Flujo de trabajo del agente (de AGENTS.md)

1. Leer el README.md de la carpeta actual

   Punto de entrada de navegación en cualquier directorio.

2. Revisar spec-native/ROADMAP.md

   Confirmar que la iniciativa es coherente con la dirección actual del proyecto antes de crear una spec.

3. Leer spec-native/PRODUCT.md y contexto técnico relevante

   Cargar el mínimo contexto: ARCHITECTURE.md, STACK.md, CONVENTIONS.md según sea necesario.

4. Leer spec-native/DECISIONS.md

   Respetar los tradeoffs persistentes que condicionan el diseño actual.

5. Revisar o crear un SPEC.md

   Usar spec-native/SPEC.md para specs únicas activas; spec-native/specs/<iniciativa>/SPEC.md para proyectos más grandes.

6. Derivar o leer tareas en spec-native/tasks/

   Seguir spec-native/workflows/PLANNING.md para convertir la spec en lista ejecutable de tareas.

7. Implementar siguiendo spec-native/workflows/IMPLEMENTATION.md

   Verificar los gates de CI de spec-native/pipelines/CI.md antes de considerar el trabajo completo.

8. Registrar tradeoffs persistentes en DECISIONS.md

   Solo si la decisión debe sobrevivir más allá de la iniciativa actual.

9. Actualizar TRACEABILITY.md al cerrar la iniciativa

   Vincular todos los artefactos relacionados. No durante la ejecución — solo al cierre.

Estados obligatorios

Specs

Tareas

Decisiones

Metadata TOML opcional

Los bloques TOML son opcionales. El contrato base es documental — los documentos son válidos sin TOML. Agrega bloques TOML cuando quieras que los comandos validate, status y export del CLI funcionen automáticamente. Coloca el bloque cerca del inicio del archivo.

Cabecera de spec (spec-native/SPEC.md o spec-native/specs/**/SPEC.md)

```toml
artifact_type = "spec"
id            = "SPEC-0001"
state         = "draft"
owner         = "nombre-equipo"
created_at    = "YYYY-MM-DD"
updated_at    = "YYYY-MM-DD"
replaces      = "none"
related_tasks       = ["TASK-0001"]
related_decisions   = ["DEC-0001"]
artifacts           = ["src/ejemplo/*"]
validation          = ["pytest", "revisión manual"]
```

Cabecera de archivo de tareas (spec-native/tasks/**/TASKS.md)

```toml
artifact_type = "task_file"
initiative    = "nombre-iniciativa"
spec_id       = "SPEC-0001"
owner         = "nombre-equipo"
state         = "todo"
```

Bloque de tarea individual

```toml
id             = "TASK-0001"
title          = "Título de la tarea"
state          = "todo"
priority       = "p2"
owner          = "nombre-equipo"
labels         = []
dependencies   = []
expected_files = ["src/ejemplo.py"]
close_criteria = "Condición observable de cierre"
validation     = ["pytest tests/ejemplo_test.py"]
completion_evidence = []  # obligatorio y no vacío cuando state = "done"
```

Referencia del CLI

tools/specnative.py vive en el repositorio SpecNative Development, no en el proyecto adoptante. Invócalo apuntando a la raíz del proyecto.

# Ver estado de specs y tareas
python3 tools/specnative.py status

# Validar archivos obligatorios y consistencia TOML
python3 tools/specnative.py validate

# Exportar índice completo
python3 tools/specnative.py export-index --output exports/index.json

# Exportar matriz de trazabilidad
python3 tools/specnative.py export-traceability --output exports/trazabilidad.json

# Instalar en repositorio existente
curl -sSL https://github.com/rafex/SpecNative-Development/releases/latest/download/install.py \
  | python3 - --target /ruta/al/repo --profile team

Instalador standalone

install.py inicializa SpecNative desde un release de GitHub sin dependencias más allá de la biblioteca estándar de Python.

# Descargar y ejecutar directamente
curl -sSL https://github.com/rafex/SpecNative-Development/releases/latest/download/install.py \
  | python3 - --target /ruta/al/repo

# O descargar primero y luego ejecutar
python3 install.py --target /ruta/al/repo --profile platform --include-examples