# ADR-0002 — La metodología es agnóstica del asistente de IA

- **Estado:** aceptado
- **Fecha:** 2026-07-03
- **Decide:** lead / arquitecto de la metodología

## Contexto

Las skills están hoy empaquetadas como **skills de Claude Code** (`SKILL.md` en
`.claude/skills/`). Pero los equipos usan asistentes distintos: una organización usa
**GitHub Copilot** (nadie usa Claude), otra usa **Claude Code**. Si atamos la
metodología a un asistente, dejamos afuera a media empresa — y contradecimos el
principio rector "sin importar la herramienta de abajo" ([Art. 2](../MANIFIESTO.md#art-2)), que ya aplicamos a
las herramientas de spec (OpenSpec/Swagger/yml). Falta aplicarlo **una capa más
arriba**: el asistente de IA.

## Decisión

Aplicamos el mismo principio al asistente. Una "skill" se separa en tres capas:

1. **Contenido portable** — la lógica de interrogación, el formato, los cortes. Se
   escribe **una sola vez**, neutral al asistente. Es la fuente de verdad.
2. **Acciones deterministas = CLI `dai`** — todo lo mecánico (crear rama,
   generar `implements.yaml`, calcular `ac_hash`, indexar cobertura) vive en el
   **CLI**, no en la inteligencia del asistente. `dai link-us ABC-###` anda igual
   con Claude, con Copilot, o sin ningún asistente. Es la forma más agnóstica de
   garantizar comportamiento determinista: el asistente solo lo **invoca**.
3. **Adaptadores por asistente (delgados, generados)** — de la Capa 1 se emiten los
   wrappers finos de cada asistente:
   - **Claude Code** → `SKILL.md` en `.claude/skills/`.
   - **Copilot** → `.github/prompts/*.prompt.md` + `.github/copilot-instructions.md`
     (este último auto-inyecta el manifiesto en cada chat del repo).

El instalador elige el target: `dai init --for claude` | `--for copilot` | `--for both`.
Mismo método, misma CLI, distinto wrapper. **`--for` es aditivo, no destructivo**: los
adaptadores coexisten en el mismo repo (viven en carpetas distintas —
`.claude/skills/` y `.github/prompts/`— y no se pisan). Un equipo mixto (unos con
Copilot, otros con Claude) versiona los dos y cada quien usa el suyo. Como lo mecánico
vive en el CLI, el **output es idéntico** sin importar qué asistente lo disparó: misma
rama, mismo `implements.yaml`, mismo `ac_hash`. El repo queda consistente aunque el
equipo esté mezclado.

| Capacidad | Naturaleza | Claude Code | Copilot |
|---|---|---|---|
| `grill-intent`, `grill-user-story` | interrogación (prompt puro) | `SKILL.md` | `*.prompt.md` |
| `link-us`, `ac-hash`, `coverage` | acción mecánica | wrapper → `dai <cmd>` | prompt/CLI → `dai <cmd>` |
| el manifiesto y las reglas | contexto siempre presente | `CLAUDE.md` / `project.md` | `.github/copilot-instructions.md` |

## Consecuencias

- ✅ La misma metodología corre en una organización con Copilot y en una factory con
  Claude — "un protocolo, distinta plomería" aplicado al asistente.
- ✅ Lo mecánico se vuelve **más confiable**: un CLI determinista no alucina.
- ✅ Los docs (`MANIFIESTO`, `METODOLOGIA`, guías, glosario) ya eran 100% agnósticos:
  la dualidad solo toca la capa `skills/`.
- ⚠️ Hay que **construir el CLI `dai`** con los subcomandos mecánicos (hoy esa lógica
  está descrita dentro de las skills de Claude). Es trabajo nuevo.
- ⚠️ Las capacidades de agente difieren: los prompts puros portan limpio; las
  acciones se apoyan en el CLI. Copilot en modo agente puede correr el CLI; en modo
  chat, el dev lo corre a mano.
- ⚠️ **Límite de superficie de Copilot (verificado):** los `.github/prompts/*.prompt.md`
  se invocan **solo en VS Code / Visual Studio / JetBrains** (o, como custom agents, en
  el **Copilot CLI**). **No** en la app standalone de Copilot ni en el chat de
  github.com. Claude, en cambio, lee `~/.claude/skills/` tanto en **Claude Code** como
  en **Claude Desktop**. Consecuencia: el analista funcional "sin IDE" cierra con Claude
  Desktop; con Copilot necesita VS Code o el Copilot CLI. Es un límite de Copilot, no de
  dai — el CLI `dai` corre igual en cualquier terminal.
- ⚠️ Los wrappers se **generan**, no se mantienen a mano — si no, se desincronizan (la misma
  regla de oro del link).

**Estado de implementación:** `dai init` es un **scaffolder interactivo** (estilo
`create-vue`): pregunta asistente (`--for claude|copilot|both`) y gestor
(`--pm md|clickup|jira`), genera los adaptadores (`.claude/skills/` + `CLAUDE.md`;
`.github/prompts/*.prompt.md` + `.github/copilot-instructions.md`, transformando los
`SKILL.md` con `cli/lib/bootstrap.mjs`), deja un `.env` configurado, y cierra con
próximos pasos. **OpenSpec:** se detecta; si falta, se **ofrece instalarlo**
(`npm i -g @fission-ai/openspec@latest` + `openspec init`) — no se bundlea (Art. 2).
Con flags o sin TTY corre no-interactivo (defaults `both`/`md`, OpenSpec solo con `--openspec`).

## Alternativas consideradas

- **Mantener skills separadas por asistente a mano** — descartado: desincronización garantizada
  al primer cambio (viola Art. 9/Art. 10 aplicados al propio paquete).
- **Atarse solo a Claude** — descartado: deja afuera a la organización que usa
  Copilot, que es justo uno de los dos casos que el método debe soportar.
- **Meter toda la lógica mecánica en el asistente (sin CLI)** — descartado: no es
  portable y es menos confiable (el asistente puede alucinar un paso determinista).