Versión actual: v2.1.0 (2026-07-09) — ver CHANGELOG.md · RELEASE-NOTES.md
Repositorio de especificaciones de agentes para Spec-Driven Development (SDD). Su objetivo es construir la capa de fundación del spec de cualquier proyecto —de código (cualquier tecnología) o creativo (novela, serie de imágenes, guion…)— con igualdad semántica: que los términos del usuario sean exactamente los que la IA asimila como propios.
- Automatizada — INICIAR.md: instalas los comandos una vez y luego escribes
/iniciar(empezar/retomar),/retomar(continuar) o/ayuda(guía para usuarios) en tu herramienta (Claude Code, Cursor, Codex, OpenCode, VSCode). Sin pegar nada.- Manual — EMPEZAR-AQUI.md: copiar y pegar un prompt. Sirve en cualquier chat, incluso sin acceso a archivos (Claude.ai, ChatGPT web).
¿Dudas o pocos conocimientos? Escribe
/ayudao abre AYUDA.md: la guía paso a paso para usuarios.El resto de este README es la documentación completa.
Clona el repositorio y entra en la carpeta:
git clone https://github.com/oscarescalando/specfounder.git
cd specfounder¿Prefieres no usar Git? Descarga el proyecto como ZIP desde GitHub y descomprímelo. El sistema funciona igual: lo que importa es tener los archivos de
specfounder-v2/y los comandos accesibles desde tu herramienta.
Después, instala los comandos (ver INICIAR.md) o usa el arranque manual (EMPEZAR-AQUI.md).
Contiene dos generaciones del agente:
| Qué es | Estado | |
|---|---|---|
SPEC-FOUNDER-AGENT.md |
SpecFounder v1.0 — prompt monolítico original. Atado a OpenSpec y a Claude Code. | Legacy / referencia |
specfounder-v2/ |
SpecFounder v2.0 — sistema multi-agente, multi-metodología, multi-herramienta, con memoria persistente. | Recomendado |
Todo el contenido está en español por consistencia del repo.
- Memoria persistente. La sesión guarda su estado en
.specfounder/tras cada respuesta. Si el aplicativo se cierra o la comunicación falla, se retoma exactamente donde quedó, con un resumen de lo realizado y sin repetir preguntas. - Agnóstico de dominio. No solo genera código. Eliges el propósito del spec: software (sistema, app, API, web) o creativo (novela/libro, serie de imágenes, guion de video, o cualquier otra estructura). Las 6 secciones se adaptan al dominio; el método SDD es el mismo.
- Agnóstico de tecnología. En el lado código no está casado con ningún stack (no es "solo para Laravel"): sirve para cualquier lenguaje/framework.
- Multi-metodología. En dominios de código eliges el destino: OpenSpec, GitHub Spec-Kit o SDD genérico. En dominios creativos la salida es una Biblia en Markdown. La entrevista es la misma; solo cambia cómo se emite el resultado.
- Nuevo vs existente. Se declara explícitamente el modo; en proyectos existentes el agente explora el material (código o manuscrito/biblia) antes de preguntar.
- Multi-herramienta. No está casado con Claude Code: hay guías para Codex, OpenCode, Cursor y Antigravity, además de un monolito portable que funciona en cualquier chat/CLI.
- Mapeo agéntico de sistemas existentes (v2.1). En proyectos con código,
sf-mapinventaría el repo, lanza exploradores en paralelo por dimensión y produce unSYSTEM-MAP.mdcon evidencia (archivo:línea); las inferencias pasan por verificación adversarial (sf-verify) y la entrevista confirma por lotes lo ya respondido — una sesión brownfield baja de ~40 a ~12-15 turnos. - Arquitectura honesta con el harness. Lo interactivo (entrevista, visión, glosario) lo conduce el hilo principal con "sombreros"; los sub-agentes hacen solo el trabajo batch (explorar, verificar, emitir) — que es donde el aislamiento de contexto ahorra tokens de verdad.
La sesión la conduce el hilo principal de la conversación (una entrevista es interactiva; ningún sub-agente puede conversar con el usuario). Los sub-agentes existen solo para el trabajo batch, donde el contexto aislado ahorra tokens y mejora la lectura:
Hilo principal (coordinator — dueño del estado y del checkpoint)
│ sombreros interactivos:
│ Generador de Visión → en proyectos nuevos, construye o valida la Visión (Sección 1)
│ Entrevistador → grill-me, una pregunta por turno + confirmación por lotes en brownfield
│ Glosarista → CONTEXT/CANON canónico, detecta contradicciones al momento
│ Arquitecto/ADR → detecta ADRs (3 criterios) y propone arquitectura
│
└─ sub-agentes batch (contexto aislado, modelo por rol):
sf-explorer (×N en paralelo) → sf-map: leen el código por dimensiones → SYSTEM-MAP.md con evidencia
sf-verifier → sf-verify: intenta refutar inferencias y contradicciones del spec
sf-emitter → sf-emit: compila el spec al formato literal del destino + handoff
Cuando la herramienta no soporta sub-agentes, todo se colapsa en specfounder-v2/monolith/specfounder-v2.monolith.md (mismo comportamiento; la exploración corre por etapas en el propio hilo).
.
├── INICIAR.md ← ▶️ arranque automatizado (instalas /iniciar, /retomar, /ayuda)
├── EMPEZAR-AQUI.md ← 🚀 arranque manual (copiar y pegar; se regenera desde el monolito)
├── AYUDA.md ← ❓ guía para usuarios (la presenta /ayuda)
├── README.md ← este archivo
├── CLAUDE.md ← guía para trabajar en este repo con Claude Code
├── SPEC-FOUNDER-AGENT.md ← v1 (legacy)
├── scripts/
│ ├── install-claude-code.sh ← instalador de comandos+agentes+skills en un proyecto
│ └── build-empezar-aqui.sh ← regenera EMPEZAR-AQUI.md desde el monolito canónico
├── evals/ ← escenarios dorados para evaluar cambios al sistema
└── specfounder-v2/
├── core/coordinator.md ← núcleo de la sesión (hilo principal)
├── agents/ ← sombreros: vision-generator, interviewer, glossarist, architect-adr
│ sub-agentes: explorer, verifier, emitter
├── domains/ ← perfiles: _spine, software, novela, serie-imagenes, guion-video, _custom
├── monolith/ ← prompt portable todo-en-uno (fuente canónica del prompt)
├── comandos/ ← archivos /iniciar listos para copiar por herramienta
├── methodologies/ ← openspec, github-spec-kit, generic-sdd, creative-bible (formatos literales + handoff)
├── skills/ ← sf-domain, sf-vision, sf-map, sf-verify, sf-checkpoint, sf-resume,
│ sf-glossary-sync, sf-explore (alias), sf-emit, sf-validate, sf-plan, sf-drift
├── persistence/ ← STATE-SCHEMA.md + templates (session, journal, spec, system-map, context)
├── integrations/ ← claude-code, codex, opencode, cursor, antigravity
└── RENDIMIENTO.md ← estrategia de eficiencia de tokens (exploración aislada + lotes + journal)
En la raíz del proyecto objetivo (no en este repo) se crea:
.specfounder/
├── session.md ← CURSOR: en qué pregunta vamos y qué sigue (pequeño, se reescribe entero)
├── journal.md ← HISTÓRICO: una línea por decisión/evento (solo-append, nunca se condensa)
├── SPEC.draft.md ← spec vivo (se consolida al cerrar cada sección)
├── CONTEXT.draft.md ← glosario vivo (se actualiza al aparecer cada término)
├── SYSTEM-MAP.md ← (modo existente) mapa del sistema con evidencia archivo:línea
└── adr/ ← ADRs borrador
- Checkpoint: tras cada respuesta y antes de la siguiente pregunta: una línea al journal (append), drafts según el tipo de dato, y reescritura del
session.mdmínimo con la "Siguiente acción" exacta. Barato por estructura, no por instrucción. - Resume: al reactivarse, detecta
session.md, lo carga junto con la cola del journal, muestra un resumen del avance y retoma en la "Siguiente acción", sin re-preguntar.
Detalle completo del esquema y los protocolos: specfounder-v2/persistence/STATE-SCHEMA.md.
¿Versionar
.specfounder/en git? Es una decisión que el agente te pregunta al crear el directorio: versionarlo hace que la sesión sobreviva a cambios de máquina y sea compartible en equipo (recomendado en equipos); ignorarlo deja el progreso local. Los artefactos finales (los que emite el Adaptador) sí se versionan siempre.
SDD no es solo para programar. La metodología (entrevista grill-me, glosario/canon, igualdad semántica, checkpoint, Visión) es universal; lo que cambia entre dominios es cómo se nombran las 6 secciones, qué es el glosario y cómo se emite el resultado. SpecFounder lo resuelve con perfiles de dominio sobre una espina universal de 6 ranuras.
Lo primero que pregunta una sesión nueva es el dominio:
| Ranura universal | software |
novela |
serie-imagenes |
guion-video |
|---|---|---|---|---|
| 1 Visión | Visión del producto | Premisa y tema | Concepto visual | Logline |
| 2 Actores | Usuarios | Personajes y facciones | Sujetos consistentes | Personajes y voces |
| 3 Elementos | Funcionalidades | Tramas y subtramas | Rasgos recurrentes | Beats / mensajes |
| 4 Estructura/Flujo | Flujos de usuario | Estructura narrativa | Línea de la serie | Fraccionamiento por partes |
| 5 Forma | Arquitectura | Mundo y escenarios | Guía de estilo visual | Formato y producción |
| 6 Restricciones | No funcionales | Tono, estilo, formato | Restricciones de producción | Restricciones |
| **Glosario = ** | términos del dominio | biblia (personajes, lugares, reglas) | model-sheet en palabras | términos recurrentes |
| Salida | OpenSpec / Spec-Kit / genérico | Biblia (BIBLE.md+CANON.md) |
Biblia | Biblia |
¿Otro propósito (curso, podcast, juego, campaña…)? El perfil custom deriva las 6 ranuras al vuelo y las confirma contigo — son infinitas posibilidades. El glosario/canon es lo que evita redefinir la estructura en cada pieza (cada capítulo, imagen o parte hereda el marco fijo).
Detalle: specfounder-v2/domains/ · espina universal en _spine.md · salida creativa en methodologies/creative-bible.md · skill sf-domain.
La Visión del producto es el "Norte" del proyecto. El problema: el usuario rara vez la tiene redactada con precisión y suele pedirle a una IA que actúe como experto para crearla. SpecFounder v2 integra ese paso al flujo.
Al iniciar un proyecto nuevo, antes de la entrevista, el agente ofrece dos caminos:
- Construirla — el usuario escribe libremente su idea; el agente redacta mínimo 3 alternativas de Visión (con ángulos distintos), explica el porqué de cada una, recomienda una, y deja elegir, fusionar o anexar algo extra.
- Aportarla — el usuario pega una Visión que ya tiene y el agente la valida para continuar.
Lineamientos (normativa inviolable): toda Visión responde ¿por qué existe?, ¿qué problema resuelve? y ¿cuál es su esencia única?, en máximo 2 párrafos. Un texto más amplio no se considera una buena Visión. La Visión queda en SPEC.draft.md §1 y cubre la mayor parte de la Sección 1; la entrevista solo confirma lo que falte (p. ej. el usuario principal).
Detalle: agents/vision-generator.md · skill sf-vision.
Cada guía indica exactamente dónde colocar los prompts:
| Herramienta | Modo | Guía |
|---|---|---|
| Claude Code | Hilo principal + sub-agentes batch (instalador: ./scripts/install-claude-code.sh) |
integrations/claude-code.md |
| Codex | Monolito vía AGENTS.md |
integrations/codex.md |
| OpenCode | Multi-agente o monolito | integrations/opencode.md |
| Cursor | Monolito vía .cursor/rules/ |
integrations/cursor.md |
| Antigravity | Monolito vía reglas del workspace | integrations/antigravity.md |
| Cualquier chat/CLI | Pega el monolito como system prompt | — |
- Instala SpecFounder v2 en tu herramienta (tabla de arriba). Atajos: INICIAR.md (comando
/iniciar) o EMPEZAR-AQUI.md (copiar y pegar). - Activa el agente en la raíz del proyecto a especificar (
/iniciar, o pegando el prompt del monolito). - Responde la selección inicial (una pregunta a la vez):
- Dominio: código o creativo, y el subtipo (software · novela · serie-imagenes · guion-video · custom).
- Metodología (solo si es código): OpenSpec · Spec-Kit · SDD genérico.
- Modo: proyecto nuevo · nuevo con material (ya tienes escrito qué construir — p. ej. un microservicio con sus APIs documentadas;
sf-brieflo organiza y solo pregunta lo que falte) · existente · re-spec parcial · glosario urgente.
- (Proyecto existente) el agente mapea el material con
sf-map: inventario + exploradores en paralelo →SYSTEM-MAP.mdcon evidencia; las inferencias pasan porsf-verify. En la entrevista, cada sección arranca confirmando por lotes lo ya respondido. - (Proyecto nuevo) el agente lanza el Generador de Visión: eliges entre construir la Visión (3+ alternativas + recomendación) o aportar la tuya. La Visión final (≤ 2 párrafos) fija la Sección 1.
- Entrevista grill-me por las secciones restantes (con el vocabulario del dominio). Una pregunta por turno, siempre con recomendación. Captura además criterios de éxito medibles, fuera de alcance y prioridades P1/P2/P3. El glosario/canon y las decisiones irreversibles se construyen en paralelo.
- Si se corta la sesión: vuelve a activar el agente (o usa la skill
sf-resume). Verás el resumen y continuarás donde quedaste. - Cierre:
sf-verifyhace la pasada anti-contradicciones y revisas SPEC/Biblia + glosario + decisiones. - Emisión: el Adaptador genera los artefactos con el formato literal del destino,
sf-validatelos comprueba (incluyeopenspec validatesi aplica) y entrega el handoff con el siguiente paso concreto (/speckit.plan,/opsx:propose, osf-planen SDD genérico).
Escribes /retomar (o reactivas el agente / usas la skill sf-resume)
→ detecta .specfounder/session.md
→ muestra: progreso por sección, glosario, ADRs, última decisión, ramas abiertas
→ "Retomo aquí: S2.Q3 — ¿…? ¿Continuamos?"
→ continúas sin repetir nada
- Visión — qué es, para quién, qué problema resuelve, criterios de éxito medibles, fuera de alcance y supuestos.
- Usuarios — roles concretos con acciones concretas.
- Funcionalidades — comportamiento observable por módulo, con prioridad P1/P2/P3 (P1 = MVP).
- Flujos — pasos exactos, happy path + error path (materia prima de los escenarios Given/When/Then del destino).
- Arquitectura — estructura técnica (decisiones grandes → ADR).
- No Funcionales — concurrencia, seguridad, offline, i18n, SLAs, hosting.
CONTEXT.md (glosario / canon) y las decisiones irreversibles (ADRs) se construyen en paralelo. Una decisión se registra solo si es difícil de revertir, sorprendente sin contexto y tiene un trade-off real. En dominios creativos, las 6 secciones cambian de nombre (ver tabla de Dominios).
Dominio: software · proyecto nuevo · ruta "construir la Visión".
🧑 Usuario: Quiero una app para que equipos pequeños registren sus gastos
compartidos y sepan quién le debe a quién.
🤖 SpecFounder (Generador de Visión):
Cuéntame tu idea con tus palabras: ¿qué te molesta hoy de cómo se hace,
y para quién es? No te preocupes por la forma, yo la redacto.
🧑 Usuario: Los grupos usan hojas de cálculo y se vuelve un lío; nadie
sabe el saldo real y siempre hay discusiones al cerrar cuentas.
🤖 SpecFounder: Tengo 3 alternativas de Visión (máx. 2 párrafos cada una):
Alternativa 1 — centrada en el problema
"Saldar cuentas entre amigos hoy depende de hojas de cálculo frágiles y
de la memoria de cada quien, lo que genera saldos opacos y discusiones.
[Producto] reemplaza ese caos por un registro compartido en tiempo real
donde cada gasto queda claro y el saldo de quién-debe-a-quién es siempre
exacto y visible para todo el grupo."
_Por qué esta_: ataca directo el dolor (opacidad y fricción social).
Alternativa 2 — centrada en el usuario/impacto
"[Producto] le da a los grupos pequeños la tranquilidad de gastar juntos
sin llevar la cuenta mentalmente: registra el gasto en segundos y olvídate;
el saldo se calcula solo. Menos planillas, menos discusiones, más confianza."
_Por qué esta_: vende el beneficio emocional (tranquilidad), no la mecánica.
Alternativa 3 — centrada en la esencia diferenciadora
"A diferencia de las hojas de cálculo y las apps bancarias, [Producto] se
enfoca en una sola cosa hecha impecable: el saldo neto de un grupo, siempre
correcto y en tiempo real, con la mínima fricción para registrar un gasto."
_Por qué esta_: posiciona el foco como ventaja frente a alternativas.
Mi recomendación: la 1 — nombra el problema y la esencia (saldo exacto y
visible), que es lo que más repetiste.
¿Cuál eliges (1, 2, 3), combino alguna, o quieres anexar algo extra?
🧑 Usuario: La 1, pero añade que funciona aunque no todos tengan la app.
🤖 SpecFounder: Visión final (guardada en SPEC.draft.md §1):
"Saldar cuentas entre amigos hoy depende de hojas de cálculo frágiles…
…exacto y visible para todo el grupo, incluso cuando no todos los miembros
usan la app (se les puede incluir como participantes sin cuenta)."
✅ Cumple la normativa (2 párrafos, responde por qué/problema/esencia).
Checkpoint hecho. Continúo con la Sección 2 (Usuarios). ¿Listo?
Dominio: software · OpenSpec · proyecto nuevo. Se muestran turnos clave; cada ↳ es un checkpoint en .specfounder/.
1. Dominio → "Código → software" ↳ domain=software
2. Metodología → "OpenSpec" ↳ methodology=openspec
3. Modo → "Nuevo" ↳ phase=vision
4. Visión → (Ejemplo A) → Visión fijada ↳ s1=completa, vision_mode=generada
5. Sección 2 (Usuarios)
🤖 ¿Cuántos tipos de usuario distintos hay?
Mi recomendación: 2 — Miembro y Organizador del grupo.
🧑 Sí, esos dos. ↳ S2.Q1 ✅
🤖 Capté el término "grupo". ¿Es lo mismo que "organización"?
🧑 Es lo mismo. Usemos "grupo". ↳ CANON: Grupo (_Evitar_: organización)
… (resto de S2) … ↳ s2=completa
6. Sección 3 (Funcionalidades) … 4 (Flujos) … 5 (Arquitectura)
🤖 ¿Backend propio o servicio externo?
Mi recomendación: BaaS (p. ej. Supabase) para llegar a v1 rápido.
🧑 De acuerdo. ↳ ADR-0001 (difícil de revertir)
… 6 (No Funcionales) … ↳ s3..s6=completa
7. — se cae la sesión / cierro el editor —
🔄 Reactivo el agente:
"Sesión recuperada — App de gastos (OpenSpec · nuevo).
✅ Secciones 1–5 · ⏳ Sección 6 en curso · CANON: 6 términos · 1 ADR.
▶️ Retomo: S6.Q3 — ¿Debe funcionar offline? ¿Continuamos?"
🧑 Sí, lectura offline. ↳ s6=completa
8. Cierre → muestra SPEC + CANON + ADR para revisión.
9. Emisión (OpenSpec):
openspec/project.md (visión + glosario + stack)
openspec/specs/… (capabilities por módulo)
openspec/changes/… (primer cambio propuesto)
+ bloque de handoff. ↳ phase=emitido
Para un dominio creativo el flujo es idéntico, pero el paso 1 sería "Creativo → novela", no se pregunta metodología, las secciones usan vocabulario narrativo, y el paso 9 emite
BIBLE.md+CANON.mden lugar deopenspec/.
SpecFounder es eficiente por diseño, con tres palancas en orden de impacto (detalle en specfounder-v2/RENDIMIENTO.md):
- Exploración en contexto aislado — en modo existente, el código crudo lo leen los exploradores de
sf-mapen sus propias ventanas; al hilo de la entrevista solo llega elSYSTEM-MAP.mddestilado. Sin esto, cada archivo leído se re-procesaría en los ~40 turnos siguientes: es el mayor ahorro del sistema. - Confirmación por lotes — menos turnos: en brownfield, cada sección arranca con UN turno que confirma lo mapeado (con evidencia) en vez de re-preguntarlo. De ~40 turnos a ~12-15.
- Checkpoint estructuralmente barato —
journal.mdsolo-append (una línea por decisión) +session.mdmínimo que se reescribe entero (~30 líneas) +SPEC.draft.mdconsolidado por sección. Barato por diseño, no por pedirle al modelo que "edite con cuidado".
El modelo por rol aplica donde de verdad se puede: los sub-agentes (sf-explorer → sonnet, sf-emitter → haiku, /ayuda → haiku); el hilo de la entrevista usa el modelo de la sesión (elige uno de máximo razonamiento para specs complejos, equilibrio para el resto).
Lo que nunca se sacrifica por eficiencia: una pregunta de descubrimiento por turno, checkpoint antes de cada pregunta, igualdad semántica, evidencia en el mapa, Visión ≤ 2 párrafos y los 3 criterios de ADR.
- Una sola pregunta de descubrimiento por turno. (La confirmación por lotes es UN turno con UNA pregunta sobre hechos ya mapeados con evidencia; no agrupa descubrimiento.)
- No avanzar de sección con ramas abiertas.
- No inventar decisiones técnicas: siempre recomendación + confirmación.
- No usar lenguaje del usuario sin verificarlo contra el glosario.
- Ante contradicción, detenerse y resolverla.
- CONTEXT es un glosario puro (sin implementación ni decisiones técnicas).
- Nunca formular una pregunta sin checkpoint del turno anterior.
- Nunca asumir dominio, metodología ni modo: se eligen al inicio o se leen del
session.mdal retomar. - Toda afirmación tomada del material existente lleva evidencia (
archivo:línea); sin evidencia es[inferido]y se verifica o se pregunta.
El spec de v1 (SPEC.md + CONTEXT.md) equivale a la salida del adaptador SDD genérico de v2. Para migrarlo a OpenSpec o Spec-Kit, ejecuta una sesión en modo re-spec parcial eligiendo la nueva metodología; el Adaptador reestructura sin reescribir el contenido.
El proyecto sigue SemVer y documenta cada versión en CHANGELOG.md (histórico, más reciente arriba) y RELEASE-NOTES.md (última versión). La versión vigente se muestra al inicio de este README.
Cada versión se etiqueta con un tag (vX.Y.Z) y agrupa los cambios por tipo de Conventional Commit (feat, fix, docs, refactor, perf, chore…). Para que las entradas salgan limpias, escribe los commits en ese formato (tipo: descripción).
Publicado bajo la Licencia MIT — uso libre (usar, modificar, distribuir, incluso comercial) siempre que se conserve el aviso de copyright y la atribución al autor. Ver LICENSE.
© 2026 Ing. Oscar Lobo