release: prepare v1.4.0

Author: juanklagos

CHANGELOG.md

@@ -6,6 +6,41 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [v1.4.0] — 2026-03-19
+
+### Added
+- Exact sidecar-mode prompts to keep advanced projects clean and avoid copying the full framework repository:
+  - `docs/en/49-spec-sidecar-prompts.md`
+  - `docs/es/49-prompts-sidecar-spec.md`
+
+### Changed
+- The professional default architecture is now explicit:
+  - project code stays in the project root
+  - SDD artifacts stay in `./spec/`
+  - full template copy is only for explicit standalone mode
+- `sdd-core` now resolves SDD roots automatically for both:
+  - classic root layout
+  - compact `spec/` sidecar layout
+- `sdd-mcp` resources and tools now work correctly with sidecar projects created under `./www/<project-name>/`.
+- `scripts/create-www-project.sh` now invokes nested scripts through `bash` for reliable execution from MCP/Node-driven flows.
+- GitMCP docs now use local relative links compatible with offline markdown link checks.
+
+### Fixed
+- MCP integration test updated for sidecar workspace outputs (`projectRoot` + `sddRoot` + `layout`).
+- Local link-check failures caused by absolute filesystem links in:
+  - `docs/en/47-free-external-mcp-options.md`
+  - `docs/en/48-how-to-connect-this-repo-with-gitmcp.md`
+  - `docs/es/47-opciones-gratis-mcp-externo.md`
+  - `docs/es/48-como-conectar-este-repo-con-gitmcp.md`
+
+### Verified
+- `npm run typecheck`
+- `npm run build`
+- `npm run mcp:test`
+- `./scripts/validate-sdd.sh . --strict`
+- `./scripts/check-sdd-policy.sh .`
+- `./scripts/check-sdd-gate.sh .`
+
 ## [v1.3.1] — 2026-03-18
 
 ### Added

README.es.md

@@ -211,6 +211,7 @@ Paquete obligatorio por feature:
 - MCP Ejemplos por cliente: [Guía visual](./docs/es/45-ejemplos-visuales-clientes-mcp-facil.md)
 - MCP Opciones externas gratis: [Guía](./docs/es/47-opciones-gratis-mcp-externo.md)
 - MCP Conexión GitMCP: [Paso a paso](./docs/es/48-como-conectar-este-repo-con-gitmcp.md)
+- Prompts sidecar: [Prompts exactos para modo `spec/`](./docs/es/49-prompts-sidecar-spec.md)
 - Setup MCP: [Guía del servidor](./docs/es/33-guia-servidor-mcp.md)
 - Resultado por comando: [Referencia](./docs/es/40-referencia-resultados-comandos.md)
 - Setup clientes: [Recetas](./docs/es/36-recetas-setup-clientes.md)

README.md

@@ -211,6 +211,7 @@ Mandatory spec bundle (for each feature):
 - MCP Client Examples: [Visual Guide](./docs/en/45-client-visual-examples-for-easy-mcp.md)
 - MCP Free External Options: [Guide](./docs/en/47-free-external-mcp-options.md)
 - MCP GitMCP Connection: [Step-by-step](./docs/en/48-how-to-connect-this-repo-with-gitmcp.md)
+- Sidecar Prompts: [Exact prompts for `spec/` mode](./docs/en/49-spec-sidecar-prompts.md)
 - MCP Setup: [Server Guide](./docs/en/33-mcp-server-guide.md)
 - MCP Results: [Command Reference](./docs/en/40-command-results-reference.md)
 - Client Setup: [Recipes](./docs/en/36-client-setup-recipes.md)

docs/README.md

@@ -50,6 +50,7 @@ flowchart LR
 - Client visual examples: [EN](./en/45-client-visual-examples-for-easy-mcp.md) | [ES](./es/45-ejemplos-visuales-clientes-mcp-facil.md)
 - Free external MCP options: [EN](./en/47-free-external-mcp-options.md) | [ES](./es/47-opciones-gratis-mcp-externo.md)
 - GitMCP connection guide: [EN](./en/48-how-to-connect-this-repo-with-gitmcp.md) | [ES](./es/48-como-conectar-este-repo-con-gitmcp.md)
+- Spec sidecar prompts: [EN](./en/49-spec-sidecar-prompts.md) | [ES](./es/49-prompts-sidecar-spec.md)
 - MCP complete reference: [EN](./en/41-complete-mcp-reference.md) | [ES](./es/41-referencia-completa-mcp.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)
@@ -70,8 +71,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/47`
-- ES docs list: `docs/es/00` to `docs/es/47`
+- EN docs list: `docs/en/00` to `docs/en/49`
+- ES docs list: `docs/es/00` to `docs/es/49`
 
 ## Documentation audits / Auditorías de documentación
 - EN: [32-documentation-audit-2026-03-14](./en/32-documentation-audit-2026-03-14.md)

docs/en/47-free-external-mcp-options.md

@@ -90,4 +90,4 @@ If you need the AI to guide the real SDD workflow and work with project files, y
 
 ## Next guide
 
-If you want the exact step-by-step connection flow for this repository, continue with [How to Connect This Repository with GitMCP](/Users/juanklagos/www/cucutadev/spec-driven-development-template/docs/en/48-how-to-connect-this-repo-with-gitmcp.md).
+If you want the exact step-by-step connection flow for this repository, continue with [How to Connect This Repository with GitMCP](./48-how-to-connect-this-repo-with-gitmcp.md).

docs/en/48-how-to-connect-this-repo-with-gitmcp.md

@@ -190,7 +190,7 @@ Purpose:
 
 ## Related guides
 
-- [Easy MCP Guide](/Users/juanklagos/www/cucutadev/spec-driven-development-template/docs/en/43-easy-mcp-guide.md)
-- [Hosted MCP Onboarding Model](/Users/juanklagos/www/cucutadev/spec-driven-development-template/docs/en/44-hosted-mcp-onboarding-model.md)
-- [Free External MCP Options](/Users/juanklagos/www/cucutadev/spec-driven-development-template/docs/en/47-free-external-mcp-options.md)
-- [Project Organization Map](/Users/juanklagos/www/cucutadev/spec-driven-development-template/docs/en/42-project-organization-map.md)
+- [Easy MCP Guide](./43-easy-mcp-guide.md)
+- [Hosted MCP Onboarding Model](./44-hosted-mcp-onboarding-model.md)
+- [Free External MCP Options](./47-free-external-mcp-options.md)
+- [Project Organization Map](./42-project-organization-map.md)

docs/en/49-spec-sidecar-prompts.md

@@ -0,0 +1,128 @@
+# Spec Sidecar Prompts
+
+## Purpose
+
+Use these prompts when you want an AI to use this framework without cloning or copying the full repository into your project.
+
+The rule is simple:
+
+- project code stays in the project root
+- SDD artifacts stay in `./spec/`
+- the full framework repository is only copied when you explicitly ask for standalone mode
+
+## Simple mental model
+
+```mermaid
+flowchart LR
+  A["Project root"] --> B["app code"]
+  A --> C["spec/"]
+  C --> D["idea/"]
+  C --> E["specs/"]
+  C --> F["bitacora/"]
+  C --> G["scripts/"]
+```
+
+## Exact prompt for a new project
+
+```text
+Use https://github.com/juanklagos/spec-driven-development-template as the main reference for my project.
+
+Do not clone or copy the full repository into my project.
+Create only the compact `spec/` sidecar inside the project.
+Keep my runnable project code in the project root.
+
+If the project is new, create a clean project root first and then install `spec/`.
+If needed, use GitHub Spec Kit in the project root, but keep the SDD operating system inside `./spec/`.
+
+Then guide me step by step:
+1. define the idea
+2. create the first spec
+3. explain what files were created
+4. explain the next step
+
+Do not write implementation code yet.
+Do not use standalone full-template mode unless I explicitly ask for it.
+```
+
+## Exact prompt for an existing project
+
+```text
+Use https://github.com/juanklagos/spec-driven-development-template as the main reference for this existing project: [PROJECT_PATH].
+
+Do not clone or copy the full repository into the project.
+Install only the compact `spec/` sidecar.
+Keep the current project code in the project root.
+
+Adapt the project to SDD by creating:
+- `spec/idea/`
+- `spec/specs/`
+- `spec/bitacora/`
+- `spec/scripts/`
+
+Create the first spec based on the current project behavior.
+Explain each step in simple language.
+Tell me what files were created or updated.
+
+Do not write implementation code yet.
+Do not use full standalone mode unless I explicitly ask for it.
+```
+
+## Exact prompt for Codex, Claude, Cursor, or similar
+
+```text
+Work in sidecar mode.
+
+Use https://github.com/juanklagos/spec-driven-development-template as the framework reference.
+Do not clone or copy the full repository into my project unless I explicitly ask for standalone mode.
+Install and use only the compact `spec/` sidecar by default.
+
+The project root is for app code.
+The `spec/` folder is for the SDD operating system.
+
+Before changing files, explain:
+1. what you are going to do
+2. which files you will create or update
+3. what I will have at the end
+4. what the next step is
+
+Do not implement code until the active spec is approved and the plan is aligned.
+```
+
+## What the AI should create
+
+After a correct sidecar installation, the user should expect this structure:
+
+```mermaid
+flowchart TD
+  A["my-project/"] --> B["app files"]
+  A --> C["spec/"]
+  C --> D["idea/IDEA_GENERAL.md"]
+  C --> E["specs/INDEX.md"]
+  C --> F["specs/_template/"]
+  C --> G["bitacora/"]
+  C --> H["scripts/"]
+  C --> I["AGENTS.md + AI_START_HERE.md + INSTRUCTIONS.md"]
+```
+
+## What the AI should not do
+
+The AI should not:
+
+- clone the whole repository into the project root
+- copy `docs/`, `packages/`, `www/`, and every framework file into an advanced project
+- mix framework maintenance files with product code
+- start implementation before the first spec is clear
+
+## Shortest prompt possible
+
+```text
+Use this SDD framework in sidecar mode.
+Do not copy the full repository.
+Install only `./spec/`, keep app code in the project root, create the first spec, and guide me step by step.
+```
+
+## Related guides
+
+- [Project Organization Map](./42-project-organization-map.md)
+- [Easy MCP Guide](./43-easy-mcp-guide.md)
+- [How to Connect This Repository with GitMCP](./48-how-to-connect-this-repo-with-gitmcp.md)

docs/es/47-opciones-gratis-mcp-externo.md

@@ -90,4 +90,4 @@ Si necesitas que la IA guíe el flujo real de SDD y trabaje con archivos del pro
 
 ## Siguiente guía
 
-Si quieres el flujo exacto paso a paso para conectar este repositorio, sigue con [Cómo conectar este repositorio con GitMCP](/Users/juanklagos/www/cucutadev/spec-driven-development-template/docs/es/48-como-conectar-este-repo-con-gitmcp.md).
+Si quieres el flujo exacto paso a paso para conectar este repositorio, sigue con [Cómo conectar este repositorio con GitMCP](./48-como-conectar-este-repo-con-gitmcp.md).

docs/es/48-como-conectar-este-repo-con-gitmcp.md

@@ -190,7 +190,7 @@ Propósito:
 
 ## Guías relacionadas
 
-- [Guía fácil de MCP](/Users/juanklagos/www/cucutadev/spec-driven-development-template/docs/es/43-guia-mcp-facil.md)
-- [Modelo de onboarding MCP alojado](/Users/juanklagos/www/cucutadev/spec-driven-development-template/docs/es/44-modelo-onboarding-mcp-alojado.md)
-- [Opciones gratis de MCP externo](/Users/juanklagos/www/cucutadev/spec-driven-development-template/docs/es/47-opciones-gratis-mcp-externo.md)
-- [Mapa de organización del proyecto](/Users/juanklagos/www/cucutadev/spec-driven-development-template/docs/es/42-mapa-organizacion-proyecto.md)
+- [Guía fácil de MCP](./43-guia-mcp-facil.md)
+- [Modelo de onboarding MCP alojado](./44-modelo-onboarding-mcp-alojado.md)
+- [Opciones gratis de MCP externo](./47-opciones-gratis-mcp-externo.md)
+- [Mapa de organización del proyecto](./42-mapa-organizacion-proyecto.md)

docs/es/49-prompts-sidecar-spec.md

@@ -0,0 +1,128 @@
+# Prompts para sidecar `spec/`
+
+## Propósito
+
+Usa estos prompts cuando quieres que una IA use este framework sin clonar ni copiar el repositorio completo dentro de tu proyecto.
+
+La regla es simple:
+
+- el código del proyecto vive en la raíz del proyecto
+- los artefactos SDD viven en `./spec/`
+- el framework completo solo se copia si tú pides explícitamente el modo standalone
+
+## Modelo mental simple
+
+```mermaid
+flowchart LR
+  A["Raíz del proyecto"] --> B["código de la app"]
+  A --> C["spec/"]
+  C --> D["idea/"]
+  C --> E["specs/"]
+  C --> F["bitacora/"]
+  C --> G["scripts/"]
+```
+
+## Prompt exacto para un proyecto nuevo
+
+```text
+Usa https://github.com/juanklagos/spec-driven-development-template como referencia principal para mi proyecto.
+
+No clones ni copies el repositorio completo dentro de mi proyecto.
+Crea solo el sidecar compacto `spec/` dentro del proyecto.
+Mantén el código ejecutable del proyecto en la raíz del proyecto.
+
+Si el proyecto es nuevo, crea primero una raíz limpia del proyecto y luego instala `spec/`.
+Si hace falta, usa GitHub Spec Kit en la raíz del proyecto, pero mantén el sistema operativo SDD dentro de `./spec/`.
+
+Luego guíame paso a paso:
+1. define la idea
+2. crea la primera spec
+3. explícame qué archivos fueron creados
+4. explícame cuál es el siguiente paso
+
+No escribas código de implementación todavía.
+No uses el modo full standalone a menos que yo lo pida explícitamente.
+```
+
+## Prompt exacto para un proyecto existente
+
+```text
+Usa https://github.com/juanklagos/spec-driven-development-template como referencia principal para este proyecto existente: [RUTA_DEL_PROYECTO].
+
+No clones ni copies el repositorio completo dentro del proyecto.
+Instala solo el sidecar compacto `spec/`.
+Mantén el código actual del proyecto en la raíz del proyecto.
+
+Adapta el proyecto a SDD creando:
+- `spec/idea/`
+- `spec/specs/`
+- `spec/bitacora/`
+- `spec/scripts/`
+
+Crea la primera spec con base en el comportamiento actual del proyecto.
+Explícame cada paso con lenguaje simple.
+Dime qué archivos fueron creados o actualizados.
+
+No escribas código de implementación todavía.
+No uses el modo full standalone a menos que yo lo pida explícitamente.
+```
+
+## Prompt exacto para Codex, Claude, Cursor o similar
+
+```text
+Trabaja en modo sidecar.
+
+Usa https://github.com/juanklagos/spec-driven-development-template como referencia del framework.
+No clones ni copies el repositorio completo dentro de mi proyecto a menos que yo pida explícitamente el modo standalone.
+Instala y usa solo el sidecar compacto `spec/` por defecto.
+
+La raíz del proyecto es para el código de la app.
+La carpeta `spec/` es para el sistema operativo SDD.
+
+Antes de cambiar archivos, explícame:
+1. qué vas a hacer
+2. qué archivos vas a crear o actualizar
+3. qué voy a tener al final
+4. cuál es el siguiente paso
+
+No implementes código hasta que la spec activa esté aprobada y el plan esté alineado.
+```
+
+## Qué debería crear la IA
+
+Después de una instalación correcta del sidecar, el usuario debería esperar esta estructura:
+
+```mermaid
+flowchart TD
+  A["mi-proyecto/"] --> B["archivos de la app"]
+  A --> C["spec/"]
+  C --> D["idea/IDEA_GENERAL.md"]
+  C --> E["specs/INDEX.md"]
+  C --> F["specs/_template/"]
+  C --> G["bitacora/"]
+  C --> H["scripts/"]
+  C --> I["AGENTS.md + AI_START_HERE.md + INSTRUCTIONS.md"]
+```
+
+## Qué no debería hacer la IA
+
+La IA no debería:
+
+- clonar el repositorio completo dentro de la raíz del proyecto
+- copiar `docs/`, `packages/`, `www/` y todos los archivos del framework dentro de un proyecto avanzado
+- mezclar archivos de mantenimiento del framework con el código del producto
+- empezar implementación antes de que la primera spec esté clara
+
+## El prompt más corto posible
+
+```text
+Usa este framework SDD en modo sidecar.
+No copies el repositorio completo.
+Instala solo `./spec/`, deja el código de la app en la raíz del proyecto, crea la primera spec y guíame paso a paso.
+```
+
+## Guías relacionadas
+
+- [Mapa de organización del proyecto](./42-mapa-organizacion-proyecto.md)
+- [Guía fácil de MCP](./43-guia-mcp-facil.md)
+- [Cómo conectar este repositorio con GitMCP](./48-como-conectar-este-repo-con-gitmcp.md)