QuinotoSpec: Yggdrasil Edition

ESTADO: PRODUCCION / ESTABLE

Metodologia y sistema de configuracion de agentes para desarrollo asistido por IA. Flujo de trabajo "Proposal First" / "Context Slicing" para maximizar precision y minimizar alucinaciones.

Yggdrasil Edition - El arbol que conecta los 9 reinos del desarrollo asistido por IA. Ahora con The Tiwaz Rune: análisis formal de entropía de código.

Quick Start

# 1. Clonar el paquete
git clone https://github.com/Quinoto-Tech/QuinotoSpec.git
cd QuinotoSpec

# 2. Instalar para tu IDE
./install.sh --opencode --global    # OpenCode
./install.sh --cursor --global      # Cursor
./install.sh --cline --global       # Cline

# 3. En tu proyecto, ejecutar discovery
@quinotospec.discovery

# 4. Crear tu primera propuesta
@quinotospec.create-proposal

Tabla de Contenido

• El Problema
• Casos de Uso
• Por Qué QuinotoSpec
• Instalación
• Filosofía
• Flujo de Trabajo
  • 1. Discovery
  • 2. Propuesta Técnica
  • 3. Historias de Usuario
  • 4. Tareas Técnicas
  • 5. Implementación
• Workflows
• Skills
• Mapa de Dependencias Skills ↔ Workflows
• Reglas
• Estructura del Proyecto
• Solución de Problemas
• Licencia

---

El Problema

Cuando los agentes de IA operan sobre un códigobase sin estructura, ocurre lo inevitable:

Síntoma	Qué pasa	Impacto
Alucinaciones en cascada	El agente no tiene contexto delinear y "inventa" decisiones de diseño	Se implementa código que no resuelve el problema real
Contexto desbordado	Se carga todo el proyecto en el prompt, pero el agente no distingue lo relevante de lo accesorio	Tokens desperdiciados, respuestas difusas, inconsistencias
Cambios sin trazabilidad	Nadie sabe qué decidió el agente, por qué, ni qué afectó	Deuda técnica invisible que crece con cada iteración
Sobrescritura silenciosa	El agente reescribe archivos enteros sin preservar trabajo previo	Se pierden historias de usuario, tareas, acuerdos de producto
Onboarding ciego	Cada sesión arranca desde cero, sin memoria del proyecto	Repetición de errores, features inconsistentes, frustración

El resultado: promesas rotas, refactors que empeoran las cosas, y equipos que desconfían del agente porque "no sigue lo que se le pide".

La causa raíz no es el modelo — es la ausencia de un contrato estructurado entre humano y agente.

---

Casos de Uso

Proyecto nuevo con IA desde el día uno

Estás arrancando un proyecto y querés que el agente construya sobre fundamentos sólidos desde la primera línea de código. Ejecutás @quinotospec.discovery, el agente mapea el stack y genera los 8 archivos de contexto. A partir de ahí, cada propuesta, historia y tarea parte de una base documentada y validable — no de suposiciones.

Proyecto desde cero con scaffold automático

El directorio está vacío — ni una línea de código. Ejecutás @quinotospec.init, el agente detecta que no hay proyecto y lanza un wizard interactivo: ¿lenguaje? ¿framework? ¿testing? ¿base de datos? Elegís Python + FastAPI + Poetry + pytest + SQLite. El agente ejecuta poetry new, instala dependencias, crea .gitignore, README.md y la estructura .quinoto-spec/. También acepta --stack python:fastapi:poetry:pytest:sqlite para ir directo sin wizard.

Incorporación de un desarrollador al proyecto

Un nuevo miembro del equipo necesita entender el códigobase rápido. @quinotospec.onboard developer genera un documento de onboarding técnico: arquitectura, endpoints, deuda técnica, convenciones. El developer productivo en horas, no en semanas.

Migración o refactor de módulos críticos

Tenés un módulo con alta deuda técnica que necesita reescritura. En lugar de pedirle al agente "refactorea esto" y cruzar los dedos, creás una propuesta con @quinotospec.create-proposal, desglosás en historias de usuario, generás tareas atómicas, y el agente ejecuta una por una con contexto preciso. Si algo falla, hay rollback y changelog.

Proyecto multi-servicio con dependencias cruzadas

Tu proyecto tiene 3 servicios que se comunican entre sí. El contexto global es enorme y confuso. @quinotospec.stack-discovery consolida el discovery de todos los servicios, y @quinotospec.dependency-graph mapea las dependencias inter-servicio. El agente opera con claridad sobre qué afecta cada cambio.

Sprint con múltiples tareas paralelas

Tenés 15 tareas que necesitan avanzar en paralelo. @quinotospec.battle-frenzy lanza subagentes en paralelo, cada uno con su contexto aislado. Blood-Bond analiza tus patrones de trabajo y predice qué tarea deberías encarar después.

Auditoría de lo que hizo el agente

Necesitás saber qué cambió, por qué, y si cumple los criterios de aceptación. @quinotospec.review revisa branch/PR contra las historias de usuario. @quinotospec-metrics calcula compliance. El changelog se actualiza automáticamente — nunca se edita manualmente.

---

Por Qué QuinotoSpec

Proposal First, no Prompt First

La mayoría de los workflows con IA siguen el patrón "pedí, esperá, verificá". QuinotoSpec invierte el orden: primero se define qué se quiere (propuesta), después se ejecuta. Esto elimina el principal fuente de errores — la ambigüedad del prompt inicial.

Context Slicing, no Context Dumping

En lugar de cargar todo el proyecto en cada llamada al modelo, QuinotoSpec refina el contexto progresivamente:

Discovery (global) → Proposal (iniciativa) → Delta Specs (incremental) → User History (valor) → Task (atómico)

En cada paso, el agente recibe menos contexto pero más preciso. Menos tokens, menos ruido, menos alucinaciones.

Delta Specs: Especificaciones Incrementales

QuinotoSpec usa delta specs para describir cambios al sistema. En lugar de reescribir la especificación completa cada vez:

• ADDED: Nuevos requerimientos que se agregan
• MODIFIED: Requerimientos existentes que cambian (con Was: y Reason:)
• REMOVED: Requerimientos que se eliminan (con Reason: y Migration:)
• RENAMED: Requerimientos renombrados

Al archivar una propuesta, el engine de merge aplica los deltas a specs/ — el source of truth canónico del sistema, organizado por dominio/servicio. Esto hace que QuinotoSpec funcione tanto en greenfield como en brownfield.

Trazabilidad por diseño

Cada cambio queda registrado en un changelog inmutable (regla #1: nunca editar manualmente). Cada tarea tiene un ID con prefijo registrado. Cada propuesta se archiva cuando se completa. No hay cambios fantasma.

Gobernanza, no solo ejecución

QuinotoSpec no es un archivo de prompts — es un sistema de reglas. 12 reglas estrictas que el agente debe cumplir, validables con @quinotospec-validate y /quinotospec-rules-enforce. Si un acuerdo de producto está vacío, el workflow se bloquea. Si un prefijo no está registrado, no se avanza.

Funciona con tu agente, no en lugar de tu agente

QuinotoSpec se instala en tu IDE (Cursor, OpenCode, Cline, o genérico) y opera sobre tu proyecto. No es un SaaS, no es un wrapper — es configuración + metodología + reglas que transforman cómo tu agente trabaja.

---

Instalación

# Clonar y dar permisos
chmod +x quinotospec-package/install.sh

# Ejecutar (modo interactivo)
./quinotospec-package/install.sh

# Instalación global (en ~/.config/)
./quinotospec-package/install.sh --opencode --global

El instalador pregunta la ruta de destino y el IDE:

Flag	IDE	Destino
--opencode	OpenCode	.opencode/ o ~/.config/opencode/ (global)
--cursor	Cursor	.cursor/ o ~/.config/cursor/ (global)
--global, --root	-	Instala en ~/.config/ ignorando el directorio del proyecto
(default)	Genérico	.agent/

Instalación Global

Para instalar una vez y disponible en todos tus proyectos:

# OpenCode global
./quinotospec-package/install.sh --opencode --global

# Cursor global
./quinotospec-package/install.sh --cursor --global

Esto crea la configuración en ~/.config/opencode/ o ~/.config/cursor/ según el IDE.

Dependencias

Dependencia	Requerido	Propósito
Bash 4.0+	Sí	Ejecutar instalador
Git	Sí	Control de versiones

---

Filosofía: "Proposal First" & "Context Slicing"

1. Proposal First: Antes de escribir código, escribe una propuesta. Evita código espagueti y asegura diseño aprobado.

2. Context Slicing: El contexto se refina progresivamente:

   • Discovery → Contexto Global (todo el proyecto)
   • Proposal → Contexto de la Iniciativa (solo lo relevante)
   • User Histories → Contexto del Valor (qué y para quién)
   • Task → Contexto Atómico (instrucciones precisas)

---

Flujo de Trabajo

Discovery → Propuesta → Historias de Usuario → Tareas → Implementación → Changelog → Archive

1. Discovery

Genera documentación del estado actual del proyecto.

@quinotospec.discovery                          # Discovery completo (8 archivos)
@quinotospec.stack-detect                       # Detectar stack tecnológico
@quinotospec.stack-discovery                    # Discovery multi-servicio
@quinotospec.refresh-discovery                  # Actualizar solo archivos cambiados

Output: .quinoto-spec/discovery/ (8 archivos Markdown).

2. Crear Propuesta Técnica

Define la solución a alto nivel.

@quinotospec.create-proposal

Output: .quinoto-spec/proposals/{slug}/proposal.md

3. Generar Historias de Usuario

Desglosa la propuesta en requerimientos de valor.

@quinotospec.create-user-stories --slug {SLUG}

Output: .quinoto-spec/proposals/{slug}/user-stories.md

4. Generar Tareas Técnicas

Convierte historias en pasos ejecutables.

@quinotospec.create-tasks --slug {SLUG}                    # Todas las historias
@quinotospec.create-tasks --slug {SLUG} --single {US_ID}  # Una historia

Output: .quinoto-spec/proposals/{slug}/{US_ID}_tasks.md

5. Implementación (Apply)

Ejecuta las tareas una por una.

@quinotospec.apply --task-id {TASK_ID}

Acciones: Lee contexto → Confirma branch → Implementa → Ejecuta tests → Actualiza changelog → Sugiere siguiente tarea.

---

Workflows

Workflow	Comando	Descripción
Discovery	@quinotospec.discovery	Genera 8 archivos de documentación del proyecto
Stack Detect	@quinotospec.stack-detect	Identifica stack tecnológico (lenguajes, frameworks, tests)
Stack Discovery	@quinotospec.stack-discovery	Discovery consolidado para proyectos multi-servicio
Refresh Discovery	@quinotospec.refresh-discovery	Actualiza solo archivos de discovery afectados
Create Proposal	@quinotospec.create-proposal	Crea propuesta técnica con prefijo único e idempotente
Create PRD	@quinotospec.create-prd	Crea un Pro