Skip to content

AGENTS.md

Latest commit

 

History

History
244 lines (174 loc) · 10.4 KB

AGENTS.md

File metadata and controls

244 lines (174 loc) · 10.4 KB

🤖 Instructions for any Artificial Intelligence tool / Instrucciones para cualquier herramienta de Inteligencia Artificial

📌 Mandatory repository rule / Regla obligatoria del repositorio

Cloning is optional. The mandatory requirement is to work with this repository template and guides as the primary reference.

Clonar es opcional. Lo obligatorio es trabajar con este template y sus guías como referencia principal.

Default target-project rule / Regla por defecto para proyecto destino:

  • EN: Do not clone or copy this full repository into the user's project unless the user explicitly asks for a full standalone workspace.
  • ES: No clones ni copies este repositorio completo dentro del proyecto del usuario salvo que el usuario pida explícitamente un workspace standalone completo.
  • EN: For real projects, install only the compact spec/ sidecar and keep project code in the project root.
  • ES: Para proyectos reales, instala solo el sidecar compacto spec/ y mantén el código del proyecto en la raíz del proyecto.

Quick start for AI tools / Inicio rápido para herramientas de IA:

  • AGENT_OPERATING_SYSTEM.md
  • sdd.policy.yaml
  • INSTRUCTIONS.md
  • AI_START_HERE.md
  • template-context/README.md
  • template-context/01-PURPOSE.md
  • template-context/02-AI-OPERATING-RULES.md
  • template-context/03-FAST-ENTRY-FLOWS.md
  • template-context/04-ANTI-MISUSE.md
  • template-context/05-SDD-EXECUTION-GATE.md
  • template-context/06-AI-RULES-MATRIX.md
  • template-context/07-AI-HANDOFF-CHECKLIST.md
  • docs/es/10-agentes-ia-soportados-y-prompts.md
  • docs/en/10-supported-ai-agents-and-prompts.md

🧭 Repository context lock / Bloqueo de contexto del repositorio

  • EN: Treat this repository as a starter template, not as a single in-progress product.
  • ES: Trata este repositorio como un template de arranque, no como un único producto en desarrollo.

Before implementation tasks, explicitly determine:

  1. If the task is template maintenance or target project execution.
  2. The real target project path when execution is for a user project.
  3. The active specification in that target project.
  4. Default to the compact spec/ sidecar for target projects.
  5. Use www/<project-name>/ only as the clean container when the target project should live inside this repository.
  6. If the target project lives inside this repository, keep it under www/ to avoid mixing framework and product work.

📚 Mandatory reading order / Orden obligatorio de lectura

  1. idea/IDEA_GENERAL.md
  2. specs/INDEX.md
  3. Latest handoff file in bitacora/handoffs/ / último archivo de bitacora/handoffs/
  4. Reusable templates in templates/ / plantillas reutilizables en templates/
  5. Optional packs and quality evidence (playbooks/, quality/) when needed

🔧 Mandatory workflow / Flujo obligatorio

  1. Confirm the target project path.
    • recommended clean workspace inside this template: ./scripts/create-www-project.sh <project-name> <assistant>
    • recommended external target path: ./scripts/install-spec-sidecar.sh /absolute/path/to/project
    • full standalone workspace only when explicitly requested: ./scripts/init-project.sh /absolute/path/to/project --profile=full
  2. Work from one active specification.
  3. Record explicit user consent before execution/implementation starts on an approved spec:
    • sidecar mode: ./spec/scripts/confirm-user-consent.sh "User approved scope X"
    • standalone full mode: ./scripts/confirm-user-consent.sh "User approved scope X"
  4. If GitHub Spec Kit is available, use:
    • /speckit.constitution
    • /speckit.specify
    • /speckit.plan
    • /speckit.tasks
    • /speckit.implement
  5. Keep specs/ and bitacora/ updated at session end.
  6. Run validation before finishing.
    • sidecar mode: ./spec/scripts/validate-sdd.sh . --strict
    • standalone full mode: ./scripts/validate-sdd.sh . --strict
  7. Run policy check before finishing.
    • sidecar mode: ./spec/scripts/check-sdd-policy.sh .
    • standalone full mode: ./scripts/check-sdd-policy.sh .
  8. Run gate check before finishing.
    • sidecar mode: ./spec/scripts/check-sdd-gate.sh .
    • standalone full mode: ./scripts/check-sdd-gate.sh .
  9. Optional, if available: run new-spec.sh, score-spec.sh, generate-roadmap.sh, generate-status.sh, and legacy-discovery.sh for stronger consistency.

Optional modules are accelerators, not blockers. If they are not used, keep core consistency with idea/, specs/, and bitacora/.

🔁 Mandatory refinement protocol / Protocolo obligatorio de refinamiento

If idea, scope, priority, or requirements change:

  1. Update the active specification.
  2. Add an entry in history.md.
  3. Update specs/INDEX.md if status or priority changes.
  4. Register the change in bitacora/.

Do not continue implementation until documentation is aligned.

No continúes implementación hasta que la documentación quede alineada.

🧭 Required reference / Referencia obligatoria

Read and apply:

  • docs/es/10-agentes-ia-soportados-y-prompts.md or
  • docs/en/10-supported-ai-agents-and-prompts.md

and the refinement guide:

  • docs/es/11-refinamiento-continuo.md or
  • docs/en/11-continuous-refinement.md

For local desktop execution guidance (Codex desktop, Claude desktop, similar tools), read:

  • docs/es/16-guia-herramientas-desktop-local.md or
  • docs/en/16-local-desktop-tools-guide.md

For Lovable execution workflow after refined specs, read:

  • docs/es/17-trabajar-con-lovable.md or
  • docs/en/17-working-with-lovable.md

For operator level (beginner/intermediate/advanced), use:

  • docs/es/18-ruta-completa-3-niveles.md / docs/en/18-complete-3-level-path.md
  • docs/es/13-guia-rapida-no-programadores.md / docs/en/13-quick-guide-non-programmers.md
  • docs/es/14-guia-intermedia.md / docs/en/14-intermediate-guide.md
  • docs/es/15-guia-avanzada.md / docs/en/15-advanced-guide.md

✅ Final requirement / Requisito final

No implementation without specification, refinement trace, and logbook updates.

No hay implementación sin especificación, traza de refinamiento y actualización de bitácora.

⭐ Uso explícito del repositorio base

Usa siempre este repositorio como referencia principal:

  • https://github.com/juanklagos/spec-driven-development-template

🆕 Caso 1: crear un proyecto nuevo desde esta base

Prompt sugerido para la IA:

Usando https://github.com/juanklagos/spec-driven-development-template crea un proyecto nuevo para [OBJETIVO].
No clones ni copies el repositorio completo dentro de mi proyecto salvo que yo lo pida.
Instala solo la carpeta compacta `spec/` y guíame paso a paso para definir idea, primera spec y bitácora.
No saltes pasos.

♻️ Caso 2: adaptar un proyecto existente usando esta base

Prompt sugerido para la IA:

Usando https://github.com/juanklagos/spec-driven-development-template y su guía, adapta este proyecto existente: [RUTA_DEL_PROYECTO].
No copies el template completo. Integra solo el sidecar `spec/`, mantén el código actual en la raíz, crea la primera spec basada en lo que ya existe y deja trazabilidad completa.

✅ Resultado mínimo esperado

  • Proyecto creado o adaptado con estructura estándar.
  • Primera especificación creada.
  • Bitácora inicial registrada.
  • Próximo paso claro para continuar.

⭐ Explicit base repository usage

Always use this repository as the primary reference:

  • https://github.com/juanklagos/spec-driven-development-template

🆕 Case 1: create a new project from this base

Suggested prompt for the Artificial Intelligence assistant:

Using https://github.com/juanklagos/spec-driven-development-template create a new project for [GOAL].
Do not clone or copy the full repository into my project unless I explicitly ask for that mode.
Install only the compact `spec/` sidecar and guide me step by step to define idea, first specification, and logbook.
Do not skip steps.

♻️ Case 2: adapt an existing project using this base

Suggested prompt for the Artificial Intelligence assistant:

Using https://github.com/juanklagos/spec-driven-development-template and its guide, adapt this existing project: [PROJECT_PATH].
Do not copy the full template. Install only the `spec/` sidecar, keep current code in the project root, create the first specification based on existing behavior, and leave complete traceability.

✅ Minimum expected outcome

  • Project created or adapted with standard structure.
  • First specification created.
  • Initial logbook entry recorded.
  • Clear next step to continue.

🌐 Bilingual support / Soporte bilingüe

  • EN: This repository is designed to be used in English and Spanish.
  • ES: Este repositorio está diseñado para usarse en inglés y español.
  • EN: Keep instructions simple, direct, and copy/paste-ready.
  • ES: Mantén instrucciones simples, directas y listas para copiar/pegar.

🗣️ Prompt base / Base prompt

EN: Using https://github.com/juanklagos/spec-driven-development-template, guide me step by step with SDD for my project.
My project is: [describe project in plain language].
Do not clone the full repository into my project unless I explicitly ask for a standalone workspace.
Install only the `spec/` sidecar by default.
Do not skip idea, spec, plan, tasks, logbook, and validation.

ES: Usando https://github.com/juanklagos/spec-driven-development-template, guíame paso a paso con SDD para mi proyecto.
Mi proyecto es: [explica el proyecto en lenguaje simple].
No clones el repositorio completo dentro de mi proyecto salvo que yo pida un workspace standalone.
Instala solo el sidecar `spec/` por defecto.
No omitas idea, spec, plan, tasks, bitácora y validación.

💡 Tips / Consejos

  • EN: Ask the AI to confirm the active spec before coding.
  • ES: Pide a la IA confirmar la spec activa antes de programar.
  • EN: Keep one clear next step at the end of each session.
  • ES: Deja un próximo paso claro al final de cada sesión.
  • EN: Prefer simple language and concrete deliverables.
  • ES: Prefiere lenguaje simple y entregables concretos.

📊 Visual flow / Flujo visual

flowchart LR
  A["EN: Idea / ES: Idea"] --> B["EN: Approved spec / ES: Spec aprobada"]
  B --> C["EN: Aligned plan / ES: Plan alineado"]
  C --> D["EN: Prioritized tasks / ES: Tareas priorizadas"]
  D --> E["EN: Implementation / ES: Implementación"]
  E --> F["EN: Validation + logbook / ES: Validación + bitácora"]
Loading