feat(adoption): add roadmap examples and mcp ci

Author: juanklagos

.github/ISSUE_TEMPLATE/bug-report.md

@@ -0,0 +1,33 @@
+---
+name: Bug report
+about: Report a framework, script, docs, or MCP bug
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+## Area
+
+- [ ] Docs
+- [ ] Scripts
+- [ ] MCP
+- [ ] Validation / Gate
+- [ ] Example
+
+## Current behavior
+
+What happened?
+
+## Expected behavior
+
+What should have happened?
+
+## Reproduction
+
+Paste the exact command, prompt, or client setup used.
+
+## Environment
+
+- OS:
+- AI client:
+- Local or remote:

.github/ISSUE_TEMPLATE/use-case.md

@@ -0,0 +1,30 @@
+---
+name: Use case
+about: Share a real project or adoption scenario for the framework
+title: "[Use case] "
+labels: use-case
+assignees: ""
+---
+
+## Project type
+
+- [ ] New project
+- [ ] Existing project
+- [ ] Internal team workflow
+- [ ] MCP client integration
+
+## Short description
+
+Describe the project in plain language.
+
+## What you expected from the framework
+
+Describe the result you wanted to get.
+
+## Where friction appeared
+
+List the first confusing step, missing guide, or missing automation.
+
+## What would make this easier
+
+Be concrete.

.github/workflows/mcp.yml

@@ -0,0 +1,35 @@
+name: Validate MCP
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  mcp:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Build
+        run: npm run build
+
+      - name: MCP stdio smoke test
+        run: npm run mcp:smoke
+
+      - name: MCP HTTP smoke test
+        run: npm run mcp:http:smoke

README.es.md

@@ -56,6 +56,20 @@ npm run build
 3. Lee la guía de instalación:
 - [docs/es/33-guia-servidor-mcp.md](./docs/es/33-guia-servidor-mcp.md)
 
+## 🎬 Flujo rápido de adopción
+
+```mermaid
+flowchart LR
+  A["Describe el proyecto en lenguaje simple"] --> B["Crea la base SDD"]
+  B --> C["Aprueba la primera spec"]
+  C --> D["Alinea plan y tareas"]
+  D --> E["Valida + compuerta"]
+  E --> F["Implementa solo después de consentimiento explícito"]
+```
+
+Usa un ejemplo completo:
+- [examples/002-mcp-end-to-end/README.md](./examples/002-mcp-end-to-end/README.md)
+
 ## 🚨 Regla obligatoria antes de codificar
 
 Este template exige chequeos de política y compuerta:
@@ -157,6 +171,7 @@ Paquete obligatorio por feature:
 - Esenciales: [Estructura](./docs/es/01-estructura.md) · [Flujo](./docs/es/02-flujo-de-trabajo.md)
 - IA: [Agentes soportados](./docs/es/10-agentes-ia-soportados-y-prompts.md) · [Guía Lovable](./docs/es/17-trabajar-con-lovable.md)
 - MCP: [Guía del servidor MCP](./docs/es/33-guia-servidor-mcp.md)
+- Roadmap: [Roadmap público](./docs/es/35-roadmap-publico.md)
 - Calidad: [Checklists por etapa](./docs/es/21-checklists-calidad-por-etapa.md) · [ADR](./docs/es/24-decisiones-de-arquitectura.md)
 
 ---

README.md

@@ -56,6 +56,20 @@ npm run build
 3. Read the setup guide:
 - [docs/en/33-mcp-server-guide.md](./docs/en/33-mcp-server-guide.md)
 
+## 🎬 Fast Adoption Flow
+
+```mermaid
+flowchart LR
+  A["Describe project in plain language"] --> B["Create SDD base"]
+  B --> C["Approve first spec"]
+  C --> D["Align plan and tasks"]
+  D --> E["Validate + gate"]
+  E --> F["Implement only after explicit consent"]
+```
+
+Use a complete example:
+- [examples/002-mcp-end-to-end/README.md](./examples/002-mcp-end-to-end/README.md)
+
 ## 🚨 Mandatory Rule Before Coding
 
 This template enforces policy + gate checks:
@@ -157,6 +171,7 @@ Mandatory spec bundle (for each feature):
 - Essentials: [Structure](./docs/en/01-structure.md) · [Workflow](./docs/en/02-workflow.md)
 - AI: [Supported Agents](./docs/en/10-supported-ai-agents-and-prompts.md) · [Lovable Guide](./docs/en/17-working-with-lovable.md)
 - MCP: [MCP Server Guide](./docs/en/33-mcp-server-guide.md)
+- Roadmap: [Public Roadmap](./docs/en/35-public-roadmap.md)
 - Quality: [Stage Checklists](./docs/en/21-quality-checklists-by-stage.md) · [ADR](./docs/en/24-architecture-decisions.md)
 
 ---

docs/README.md

@@ -47,6 +47,7 @@ flowchart LR
 - Spec Kit integration: [EN](./en/08-github-spec-kit-integration.md) | [ES](./es/08-integracion-github-spec-kit.md)
 - MCP server guide: [EN](./en/33-mcp-server-guide.md) | [ES](./es/33-guia-servidor-mcp.md)
 - Launch kit: [EN](./en/34-launch-kit.md) | [ES](./es/34-kit-lanzamiento.md)
+- Public roadmap: [EN](./en/35-public-roadmap.md) | [ES](./es/35-roadmap-publico.md)
 - Continuous refinement: [EN](./en/11-continuous-refinement.md) | [ES](./es/11-refinamiento-continuo.md)
 - Quality checklists: [EN](./en/21-quality-checklists-by-stage.md) | [ES](./es/21-checklists-calidad-por-etapa.md)
 
@@ -56,8 +57,8 @@ flowchart LR
 - Validated prompt bank: [EN](./en/26-validated-prompt-bank.md) | [ES](./es/26-banco-prompts-validados.md)
 
 ## Full index / Índice completo
-- EN docs list: `docs/en/00` to `docs/en/34`
-- ES docs list: `docs/es/00` to `docs/es/34`
+- EN docs list: `docs/en/00` to `docs/en/35`
+- ES docs list: `docs/es/00` to `docs/es/35`
 
 ## Documentation audits / Auditorías de documentación
 - EN: [32-documentation-audit-2026-03-14](./en/32-documentation-audit-2026-03-14.md)

docs/en/09-release-checklist.md

@@ -51,6 +51,12 @@ Use this list before publishing on GitHub.
 - [ ] New users can follow the guide without extra context.
 - [ ] Scripts run correctly.
 - [ ] Repository metadata is complete.
+- [ ] `npm run typecheck` passes.
+- [ ] `npm run build` passes.
+- [ ] `npm run mcp:smoke` passes.
+- [ ] `npm run mcp:http:smoke` passes.
+- [ ] MCP docs and copy/paste configs are aligned with the current release.
+- [ ] Release tag/version/changelog are aligned.
 
 ## 💡 Quick tips
 

docs/en/35-public-roadmap.md

@@ -0,0 +1,54 @@
+# Public Roadmap
+
+## Purpose
+
+This roadmap makes the next product steps explicit so users know where the framework is going.
+
+## Current state
+
+Released:
+- `v1.1.0`
+
+Now available:
+- SDD framework with multi-agent policy
+- runnable project isolation in `./www/<project-name>/`
+- typed `sdd-core`
+- local `sdd-mcp`
+- `stdio` + `Streamable HTTP`
+- MCP tools, resources, prompts, and smoke tests
+
+## v1.2.0
+
+Focus: stronger adoption and testability.
+
+Planned:
+- fixture-based MCP integration tests
+- one fully documented end-to-end example for a new project
+- one fully documented end-to-end example for adapting an existing project
+- more explicit README visual onboarding
+- issue templates for adoption requests and use-case feedback
+
+## v1.3.0
+
+Focus: operator experience across AI clients.
+
+Planned:
+- tested setup guides with screenshots for Cursor, Claude Code, and Codex
+- stricter MCP contracts and richer resource coverage
+- release automation improvements
+- better project status and roadmap generation outputs
+
+## v2.0.0
+
+Focus: framework standardization.
+
+Planned:
+- clearer packaging/version strategy for `@sdd/sdd-core` and `@sdd/sdd-mcp`
+- optional publishable MCP package workflow
+- governance model for community contributions
+- showcase of real projects using the framework
+
+## Notes
+
+- GitHub Spec Kit remains the primary external reference and operating guide.
+- New features should continue reducing user friction, not increasing setup complexity.

docs/es/09-release-checklist.md

@@ -85,6 +85,12 @@ git push origin v1.0.0
 - [ ] Cualquier persona puede seguir la guía sin pedir contexto adicional.
 - [ ] La plantilla se puede inicializar con `scripts/init-project.sh`.
 - [ ] La plantilla se puede inicializar con `scripts/init-project-with-spec-kit.sh`.
+- [ ] `npm run typecheck` pasa.
+- [ ] `npm run build` pasa.
+- [ ] `npm run mcp:smoke` pasa.
+- [ ] `npm run mcp:http:smoke` pasa.
+- [ ] La documentación MCP y las configuraciones copy/paste coinciden con la release actual.
+- [ ] Tag, versión y changelog están alineados.
 
 ## 💡 Tips rápidos
 

docs/es/35-roadmap-publico.md

@@ -0,0 +1,54 @@
+# Roadmap público
+
+## Propósito
+
+Este roadmap hace explícitos los siguientes pasos del producto para que los usuarios sepan hacia dónde va el framework.
+
+## Estado actual
+
+Release publicada:
+- `v1.1.0`
+
+Disponible hoy:
+- framework SDD con política multi-agente
+- aislamiento de proyectos ejecutables en `./www/<project-name>/`
+- `sdd-core` tipado
+- `sdd-mcp` local
+- `stdio` + `Streamable HTTP`
+- tools, resources, prompts y smoke tests MCP
+
+## v1.2.0
+
+Enfoque: adopción y testabilidad más fuertes.
+
+Planeado:
+- tests de integración MCP basados en fixtures
+- un ejemplo completamente documentado end-to-end para proyecto nuevo
+- un ejemplo completamente documentado end-to-end para adaptar un proyecto existente
+- onboarding visual más explícito en el README
+- issue templates para adopción y feedback de casos de uso
+
+## v1.3.0
+
+Enfoque: experiencia del operador entre distintos clientes IA.
+
+Planeado:
+- guías validadas con capturas para Cursor, Claude Code y Codex
+- contratos MCP más estrictos y mayor cobertura de resources
+- mejoras en automatización de releases
+- mejores salidas para status y roadmap del proyecto
+
+## v2.0.0
+
+Enfoque: estandarización del framework.
+
+Planeado:
+- estrategia de empaquetado/versionado más clara para `@sdd/sdd-core` y `@sdd/sdd-mcp`
+- flujo opcional para publicar el paquete MCP
+- modelo de gobernanza para contribuciones de comunidad
+- showcase de proyectos reales usando el framework
+
+## Notas
+
+- GitHub Spec Kit sigue siendo la referencia externa y guía operativa principal.
+- Las nuevas features deben seguir reduciendo fricción al usuario, no aumentar complejidad de setup.