# Spec-Driven Development (Spec Kit)

Este proyecto usa [GitHub Spec Kit](https://github.com/github/spec-kit) con integración **Cursor Agent** (`cursor-agent`).

## Estructura

| Ruta | Propósito |
|------|-----------|
| `.specify/memory/constitution.md` | Principios del proyecto (v1.1 — monorepo Laravel + Angular) |
| `.specify/templates/` | Plantillas spec, plan, tasks |
| `.specify/scripts/powershell/` | Scripts de automatización (Windows) |
| `specs/001-chatbot-pdf-extractor/` | **Baseline brownfield** del producto actual |
| `.cursor/skills/speckit-*` | Skills invocables en Cursor |
| `.cursor/rules/specify-rules.mdc` | Regla always-on para el agente |
| `.cursor/specs/proyecto-base.yml` | Referencia técnica YAML (legacy; sincronizar con specs) |

## Flujo para una feature nueva

```mermaid
flowchart LR
  constitution["/speckit-constitution"]
  specify["/speckit-specify"]
  clarify["/speckit-clarify opcional"]
  plan["/speckit-plan"]
  tasks["/speckit-tasks"]
  analyze["/speckit-analyze opcional"]
  implement["/speckit-implement"]
  constitution --> specify
  specify --> clarify
  clarify --> plan
  plan --> tasks
  tasks --> analyze
  analyze --> implement
```

1. **Constitution** — reglas no negociables (ya inicializada).
2. **Specify** — describe QUÉ quieres (sin stack). Crea `specs/002-mi-feature/spec.md`.
3. **Clarify** — preguntas estructuradas antes del plan (recomendado).
4. **Plan** — stack, arquitectura, contratos API (Backend + Frontend) → `plan.md`, `contracts/`, `data-model.md`.
5. **Tasks** — lista ordenada con rutas `app/...` y `ChatFront/...` → `tasks.md`.
6. **Analyze** — revisión cruzada spec/plan/tasks.
7. **Implement** — el agente ejecuta `tasks.md`.

## Comandos Cursor disponibles

| Skill | Uso |
|-------|-----|
| `speckit-constitution` | Crear/actualizar constitución |
| `speckit-specify` | Nueva especificación funcional |
| `speckit-clarify` | Aclarar requisitos |
| `speckit-plan` | Plan de implementación |
| `speckit-tasks` | Desglose de tareas |
| `speckit-implement` | Ejecutar implementación |
| `speckit-analyze` | Análisis de consistencia |
| `speckit-checklist` | Checklists de calidad |
| `speckit-git-feature` | Rama git para feature (extensión git) |

Invocación en Cursor: `/speckit-specify`, `/speckit-plan`, etc.

## Baseline vs features nuevas

- **`specs/001-chatbot-pdf-extractor/`** documenta el producto **ya construido**.
- Cada cambio significativo debe usar **`002-`, `003-`…** vía `/speckit-specify`.
- No editar el baseline sin acuerdo; preferir specs incrementales.

## Herramientas CLI

```powershell
# Instalar (una vez)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.8.13

# Inicializar en proyecto existente (ya hecho)
specify init . --force --integration cursor-agent --script ps --ignore-agent-tools

# Ver integración
specify integration list
specify version
```

En Windows, si `specify` falla por Unicode:

```powershell
$env:PYTHONUTF8="1"
$env:PYTHONIOENCODING="utf-8"
```

## Referencias

- [Spec Kit README](https://github.com/github/spec-kit/blob/main/README.md)
- [Guía spec-driven](https://github.com/github/spec-kit/blob/main/spec-driven.md)
- [Integraciones](https://github.com/github/spec-kit/blob/main/docs/reference/integrations.md)