SpecNative — cómo trabajar con este framework

Servidor MCP — v0.4

tools/specnative_mcp.py expone el repositorio como recursos, herramientas y prompts MCP para que cualquier agente compatible (Claude Desktop, Claude Code, OpenCode) trabaje en modo spec-first sin navegar manualmente el árbol de archivos. Requiere: pip install mcp.

Configuración rápida — Claude Code

# Agregar desde la CLI
claude mcp add specnative \
  python3 .specnative/specnative_mcp.py \
  -- --repo /ruta/a/tu/proyecto

# O agregar a .claude/mcp_settings.json
{
  "mcpServers": {
    "specnative": {
      "command": "python3",
      "args": [
        ".specnative/specnative_mcp.py",
        "--repo", "/ruta/a/tu/proyecto"
      ]
    }
  }
}

Recursos

Herramientas

Prompts

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

Estructura del repositorio

repo/
├── AGENTS.md              # Contrato operativo para agentes — leer primero
├── README.md              # Índice de navegación
├── agents/
│   ├── README.md          # Índice 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 de versión
│   ├── CONVENTIONS.md     # Reglas de código, naming, testing
│   ├── COMMANDS.md        # Comandos del proyecto (build, test, lint...)
│   ├── SPEC.md            # Spec activa (o entrada a specs/)
│   ├── DECISIONS.md       # Decisiones persistentes y tradeoffs
│   ├── ROADMAP.md         # Dirección temporal, sin detalle de implementación
│   ├── TRACEABILITY.md    # Vínculos entre artefactos
│   └── specs/
│       └── <iniciativa>/
│           └── SPEC.md
├── tasks/
│   └── <iniciativa>/
│       └── TASKS.md
├── workflows/
│   ├── PLANNING.md
│   ├── IMPLEMENTATION.md
│   └── REVIEW.md
├── pipelines/
│   ├── CI.md              # Gates de validación automatizados
│   └── CD.md              # Proceso de entrega y ambientes
└── .specnative/
    ├── SCHEMA.md           # Contrato del framework (no contenido del proyecto)
    └── CLI.md              # Referencia del CLI

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. No ingieras todo el repositorio.

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 minimal o copia Template-Project-Agents-AI al repositorio destino. Esto crea todas las carpetas obligatorias y los archivos placeholder.

2. Completar agents/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 agents/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 agents/STACK.md

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

5. Completar agents/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 agents/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 agents/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 agents/SPEC.md (o agents/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 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 agents/DECISIONS.md

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

11. Completar pipelines/CI.md y 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 agents/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 agents/ROADMAP.md

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

3. Leer agents/PRODUCT.md y contexto técnico relevante

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

4. Leer agents/DECISIONS.md

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

5. Revisar o crear un SPEC.md

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

6. Derivar o leer tareas en tasks/

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

7. Implementar siguiendo workflows/IMPLEMENTATION.md

   Verificar los gates de CI de 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 (agents/SPEC.md o agents/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 (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"
owner          = "nombre-equipo"
dependencies   = []
expected_files = ["src/ejemplo.py"]
close_criteria = "Condición observable de cierre"
validation     = ["pytest tests/ejemplo_test.py"]
```

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 specnative.py status

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

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

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

# Instalar en repositorio existente
python3 specnative.py install \
  --target /ruta/al/repo \
  --profile minimal \
  --include-examples \
  --branch specnative/install-v0.3.1

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 minimal --include-examples