Skip to content

AI_START_HERE.md

Latest commit

 

History

History
302 lines (227 loc) · 10.7 KB

AI_START_HERE.md

File metadata and controls

302 lines (227 loc) · 10.7 KB

🤖 AI Start Here / Inicio IA aquí

Important

EN: This template exists to make SDD easy. The AI must guide the user step by step, not skip stages, and keep traceability. ES: Este template existe para volver SDD fácil. La IA debe guiar paso a paso, no saltar etapas y mantener trazabilidad.

Base repository / Repositorio base:

1) What this is / Qué es esto

EN (Problem): Most teams jump to code and lose context, decisions, and quality. EN (Solution): This template enforces a clear flow: idea -> spec -> plan -> tasks -> implement -> validate -> logbook.

ES (Problema): Muchos equipos saltan directo al código y pierden contexto, decisiones y calidad. ES (Solución): Este template impone un flujo claro: idea -> spec -> plan -> tasks -> implementar -> validar -> bitácora.

2) Hard rule / Regla dura

EN: No implementation before:

  1. spec.md is approved
  2. plan.md is consistent with spec.md

ES: No hay implementación antes de:

  1. spec.md aprobada
  2. plan.md consistente con spec.md
  • EN: Creating the SDD base (idea/spec/plan/tasks/bitacora) does not require execution consent.
  • EN: Ask and record user consent only when implementation is going to start.
  • ES: Crear la base SDD (idea/spec/plan/tasks/bitacora) no requiere consentimiento de ejecución.
  • ES: Pide y registra consentimiento del usuario solo cuando vaya a iniciar implementación.

If not aligned, refine docs first:

  • spec.md
  • plan.md
  • tasks.md
  • history.md
  • bitacora/*

2.1) Execution workspace / Espacio de ejecución

  • EN: For real projects, default to a compact spec/ sidecar inside the project and keep code in the project root.
  • ES: Para proyectos reales, usa por defecto un sidecar compacto spec/ dentro del proyecto y mantén el código en la raíz.
  • EN: Do not clone or copy the full framework repository into the target project unless the user explicitly asks for that mode.
  • ES: No clones ni copies el repositorio completo del framework dentro del proyecto destino salvo que el usuario pida explícitamente ese modo.
  • EN: Use www/<project-name>/ only when the project itself should live inside this template repository.
  • ES: Usa www/<nombre-proyecto>/ solo cuando el proyecto deba vivir dentro de este repositorio template.
  • EN: The user may choose another target path.
  • ES: El usuario puede elegir otra ruta destino.
  • EN: If the runnable project lives inside this repository, keep it under www/.
  • ES: Si el proyecto ejecutable vive dentro de este repositorio, mantenlo dentro de www/.

Create clean internal workspace:

./scripts/create-www-project.sh my-project codex

Default behavior:

  • EN: creates a clean project root and installs the compact spec/ sidecar by default.
  • ES: crea una raíz de proyecto limpia e instala por defecto el sidecar compacto spec/.

External target path:

./scripts/install-spec-sidecar.sh /absolute/path/to/project --profile=recommended

Full standalone workspace only when explicitly requested:

./scripts/init-project.sh /absolute/path/to/project --profile=full

Optional minimal sidecar:

./scripts/create-www-project.sh my-project codex --minimal-template

2.2) Easy MCP mode / Modo fácil MCP

  • EN: If the client supports MCP, prefer an easy teaching style first and treat commands like /start-project and /create-spec login as friendly aliases.
  • ES: Si el cliente soporta MCP, prefiere primero un estilo didáctico y trata comandos como /start-project y /create-spec login como alias amigables.
  • EN: Always explain 4 things before or after each action: what you will do, which files you will touch, what the user will have at the end, and what the next step is.
  • ES: Siempre explica 4 cosas antes o después de cada acción: qué vas a hacer, qué archivos tocarás, qué tendrá el usuario al final y cuál es el siguiente paso.

Primary easy MCP guide:

3) First reading order / Orden inicial de lectura

  1. template-context/core-instructions/AGENT_OPERATING_SYSTEM.md
  2. sdd.policy.yaml
  3. INSTRUCTIONS.md
  4. idea/IDEA_GENERAL.md
  5. specs/INDEX.md
  6. latest file in bitacora/handoffs/ (if exists)

4) Copy/paste prompts (easy mode) / Prompts copiar/pegar (modo fácil)

A. New project / Proyecto nuevo

EN:
Using https://github.com/juanklagos/spec-driven-development-template, create everything needed to execute my project end-to-end.
My project is: [describe your project in plain language].
Do not clone or copy the full repository into my project unless I explicitly ask for a full standalone workspace.
Install only the compact `spec/` sidecar by default, then define the idea, create the first spec, and guide me step by step.
Before execution/implementation starts, ask for my approval and record it.
Do not skip idea, spec, plan, tasks, validation, and logbook.

ES:
Usando https://github.com/juanklagos/spec-driven-development-template, crea todo lo necesario para ejecutar mi proyecto de inicio a fin.
Mi proyecto es: [explica tu proyecto en lenguaje simple].
No clones ni copies el repositorio completo dentro de mi proyecto salvo que yo pida un workspace standalone completo.
Instala solo el sidecar compacto `spec/` por defecto, luego define la idea, crea la primera spec y guíame paso a paso.
Antes de iniciar ejecución/implementación, pide mi aprobación y regístrala.
No omitas idea, spec, plan, tasks, validación y bitácora.

B. Existing project / Proyecto existente

EN:
Using https://github.com/juanklagos/spec-driven-development-template, adapt my existing project without breaking current behavior.
Project path: [PROJECT_PATH].
Do not copy the full template. Install only the `spec/` sidecar, integrate idea/specs/bitacora there, create the first spec based on existing behavior, and leave full traceability.
Guide me in simple language.

ES:
Usando https://github.com/juanklagos/spec-driven-development-template, adapta mi proyecto existente sin romper el comportamiento actual.
Ruta del proyecto: [RUTA_PROYECTO].
No copies el template completo. Instala solo el sidecar `spec/`, integra allí idea/specs/bitacora, crea la primera spec basada en el comportamiento existente y deja trazabilidad completa.
Guíame con lenguaje simple.

C. Session close / Cierre de sesión

EN:
Before closing, run validation and give me: what was done, what is pending, risks, and the next exact step.
Update INDEX, history, and PROJECT_LOG if needed.

ES:
Antes de cerrar, ejecuta validación y dame: qué se hizo, qué falta, riesgos y próximo paso exacto.
Actualiza INDEX, history y PROJECT_LOG si aplica.

5) Prompts by user level / Prompts por nivel de usuario

Level 1 (Beginner) / Nivel 1 (Principiante)

EN:
Act as an SDD guide for non-technical users.
Ask one short question at a time.
Use plain language, no jargon.
Do not write code yet.

ES:
Actúa como guía SDD para usuarios no técnicos.
Haz una pregunta corta por vez.
Usa lenguaje simple, sin jerga.
No escribas código todavía.

Level 2 (Intermediate) / Nivel 2 (Intermedio)

EN:
Read idea, INDEX, and latest handoff.
Choose one active spec and propose a 5-step session plan.
Implement only in-scope tasks.
End with validation + next step.

ES:
Lee idea, INDEX y último handoff.
Elige una spec activa y propone plan de sesión de 5 pasos.
Implementa solo tareas dentro de alcance.
Cierra con validación + próximo paso.

Level 3 (Advanced) / Nivel 3 (Avanzado)

EN:
Operate in Spec Kit-first mode with strict SDD gate.
Use: constitution -> specify -> plan -> tasks -> implement.
Block implementation if spec approval or plan consistency is missing.
Return objective, changes, validation, risks, and next step.

ES:
Opera en modo Spec Kit-first con compuerta SDD estricta.
Usa: constitution -> specify -> plan -> tasks -> implement.
Bloquea implementación si falta aprobación de spec o consistencia del plan.
Entrega objetivo, cambios, validación, riesgos y próximo paso.

6) Tips to write better prompts / Tips para escribir mejores prompts

Use this structure / Usa esta estructura

1) Context: what project and what goal
2) Current state: new project or existing project
3) Constraints: do not break behavior, simple language, no skipped phases
4) Deliverable: exact files/outputs expected
5) Closure: validation + next step

Good vs bad prompt / Prompt bueno vs malo

Bad / Malo

Help me with SDD.

Good / Bueno

Using this template repo, adapt my existing project at [PATH].
Create idea/specs/bitacora, draft the first approved-ready spec,
and give me the next exact step. Use beginner-friendly language.

Practical tips / Consejos prácticos

  • EN: Keep prompts concrete: goal + path + expected output.
  • ES: Mantén prompts concretos: objetivo + ruta + salida esperada.
  • EN: Ask the AI to confirm the active spec before coding.
  • ES: Pide a la IA confirmar la spec activa antes de programar.
  • EN: End every session with one clear next step.
  • ES: Cierra cada sesión con un próximo paso claro.

7) Optional command flow (for technical users) / Flujo de comandos opcional (usuarios técnicos)

/speckit.constitution
/speckit.specify
/speckit.plan
/speckit.tasks
/speckit.implement

Local validation:

# compact sidecar inside a real project
./spec/scripts/validate-sdd.sh . --strict
./spec/scripts/check-sdd-policy.sh .
./spec/scripts/check-sdd-gate.sh .

# full standalone workspace
./scripts/validate-sdd.sh . --strict
./scripts/check-sdd-policy.sh .
./scripts/check-sdd-gate.sh .

8) Visual map / Mapa visual

flowchart LR
  A["Idea"] --> B["Spec approved"]
  B --> C["Plan aligned"]
  C --> D["Tasks prioritized"]
  D --> E["Implementation"]
  E --> F["Validation"]
  F --> G["Logbook + next step"]
Loading

9) Related guides / Guías relacionadas

  • Prompt matrix: EN | ES
  • Validated prompt bank: EN | ES
  • Prompts by template feature: EN | ES
  • 3-level route: EN | ES

10) Minimum expected outcome / Resultado mínimo esperado

  • EN: one clear idea, one active spec, one updated log entry, one exact next step.
  • ES: una idea clara, una spec activa, una entrada de bitácora actualizada, un próximo paso exacto.