Imported from Maikel-js/ProjectManager (.ia/AGENTS.md). Install upstream with npx skills add Maikel-js/ProjectManager --skill .ia. Copyright stays with the author.

AGENTS.md — Flujo de Trabajo con IA basado en Reportes

Este repositorio sigue un flujo de trabajo estructurado en 5 fases para cualquier tarea delegada a la IA. El objetivo es minimizar tokens, garantizar confirmación humana y dejar bitácora auditable en Obsidian.

Principios obligatorios

1. Codebase Memory MCP es la fuente de verdad para lectura de código.

   • Toda búsqueda de código, función, clase, ruta, caller o callee debe pasar por MCP.
   • Prohibido lanzar agentes (task tool) para exploración del repo.
   • Prohibido grep/find/cat raw cuando MCP pueda responder.
   • Fallback a read/grep solo si MCP devuelve "no results" o el scope es trivial (un único archivo conocido).

2. rtk es el proxy canónico para toda ejecución de comandos.

   • Builds, tests, lint, typecheck, logs, git, github: siempre vía rtk <subcomando>.
   • Ver subcomandos disponibles con rtk --help.
   • Comandos canónicos de verificación: rtk test, rtk lint, rtk typecheck, rtk build.

3. Sin micro-reportes en chat durante la ejecución.

   • La IA trabaja concentrada; solo sale a chat para: plan, gate, bloqueos, verificaciones fallidas y reporte final.

4. Aprobación humana explícita antes de cada ejecución.

   • tras plan (fase 2)
   • tras reporte final (fase 5) si el usuario quiere commitiar

5. Verificaciones automáticas obligatorias antes de entregar el reporte final.

Arquitectura del flujo

FASE 1  Objetivo (usuario)
   │
   ▼
FASE 2  Planificación (IA via memory MCP, sin escribir código)
   │   → entrega plan + archivos estimados + riesgos + preguntas
   │   → HARD-STOP esperando aprobación
   ▼
FASE 3  Gate (usuario aprueba / ajusta / cancela)
   │
   ▼
FASE 4  Ejecución (IA via memory MCP + rtk)
   │   → persiste hallazgos en memoria MCP
   │   → si imprevisto grande → vuelve al gate
   ▼
FASE 4.5 Verificación obligatoria (rtk test | lint | typecheck | build)
   │   → FAIL → vuelve al gate con propuesta correctiva
   ▼
FASE 5  Reporte final en .ia/reports/ (IA escribe + actualiza index)
        → entrega resumen en chat, espera visto bueno del usuario

FASE 1 — Definición del Objetivo (usuario)

El usuario entrega al inicio del chat un bloque con esta forma exacta (ver .ia/templates/objetivo.md):

## Objetivo
<descripción clara y medible>

## Criterios de éxito
- [ ] criterio 1
- [ ] criterio 2

## Alcance y restricciones
- Stack / herramientas obligatorias:
- Archivos prohibidos:
- Convenciones:

FASE 2 — Planificación (IA)

Reglas

• Lecturas obligatorias via MCP, sin agentes:

• Prohibido en esta fase:
  • lanzar agentes (task tool)
  • grep/find/cat raw
  • ejecutar builds/tests
  • write/edit cualquier archivo

Entrega esperada al usuario

# Plan — <objetivo corto>

## Resumen ejecutivo
<1-2 párrafos>

## Pasos
1. ...
2. ...

## Archivos estimados
- crear: ...
- modificar: ...
- eliminar: ...

## Verificaciones planeadas
- rtk test
- rtk lint
- rtk typecheck
- rtk build

## Riesgos / preguntas
- R1: ...
- P1: ¿...?

## ¿Aprobado? (procede | ajustar X | cancelar)

HARD-STOP. La IA no avanza hasta recibir respuesta.

FASE 3 — Gate

FASE 4 — Ejecución

Reglas

1. Lecturas: exclusivamente via mcp_codebase-memory.*. La IA no despliega agentes.
2. Comandos: rtk <sub> para build, run, log, test, lint, typecheck, git, gh, etc.
3. Escritura: mínima e indispensable, agrupada.
4. Persistencia en memoria MCP al cerrar la fase 4:
   • hallazgos relevantes (con qualified names)
   • decisiones tomadas y su justificación
   • archivos modificados (ruta + qualified name + líneas)
   • comandos rtk ejecutados y resultado
5. Silencio operativo: no imprimir logs largos ni diffs en chat.
6. Si aparece un imprevisto que cambie scope/archivos estimados → volver al gate, no improvisar.

FASE 4.5 — Verificación obligatoria

Orden canónico (omitir el que no aplique al stack):

rtk test
rtk lint
rtk typecheck
rtk build

• PASS global → avanza a fase 5.
• FAIL en cualquiera → la IA no avanza; vuelve al gate con propuesta correctiva (no reescribe a ciegas).

FASE 5 — Reporte final en Obsidian

Ruta del archivo

.ia/reports/YYYY-MM-DD_HH-MM_<slug>.md

<slug> = kebab-case del objetivo, máx 40 chars.

Contenido (ver .ia/templates/reporte.md)

---
date: YYYY-MM-DD
time: HH:MM
status: completed | partial | failed
objective: "<título corto>"
tags: [tipo: feature|refactor|bug|chore, area, stack]
files_modified: N
---

# <Objetivo>

## Resumen ejecutivo
<2-4 párrafos con lo esencial>

## Resultado vs criterios
| # | Criterio | Estado | Evidencia |
|---|---|---|---|
| 1 | ... | ✅ | archivo:line + comando |

## Cómo se hizo
1. Paso → resultado
2. ...

## Archivos modificados
- `src/foo.ts:10-45` — añadida función `bar()`
- `tests/foo.test.ts:1-30` — nuevo test
- `package.json` — dep `x`

## Comandos ejecutados (todos vía rtk)
- `rtk test` → green
- `rtk lint` → 0 warnings
- `rtk typecheck` → ok
- `rtk build` → ok

## Decisiones y tradeoffs
- ...

## Pendientes / follow-ups
- [ ] ...

## Verificación de seguridad
- [ ] Sin secretos en código
- [ ] Sin cambios fuera de scope
- [ ] Cambios verificables vía `rtk grep` / git

Índice — .ia/reports/index.md

Actualizar insertando al inicio:

# Índice de reportes
- [[YYYY-MM-DD_HH-MM_<slug>]] — <emoji estado> <tipo> — #<tags>

Cierre en chat

La IA entrega al usuario:

• resumen corto (1-3 párrafos)
• enlace al archivo .ia/reports/...md
• si el usuario quiere commitiar, la IA pide confirmación explícita antes de tocar git.

Estructura del directorio .ia/

ProjectManager/
└── .ia/
    ├── AGENTS.md                # este archivo — reglas persistentes del flujo
    ├── reports/
    │   ├── index.md             # índice general con wikilinks
    │   └── YYYY-MM-DD_HH-MM_<slug>.md
    └── templates/
        ├── objetivo.md          # plantilla fase 1
        └── reporte.md           # plantilla fase 5

Contrato IA ↔ usuario

Recordatorios para futuras sesiones

• Ante cualquier objetivo nuevo, leer este archivo primero y obedecer las fases.
• Ante duda sobre si usar MCP o read: usar MCP.
• Ante duda sobre si usar comando raw o rtk: usar rtk.
• Ante duda sobre si ejecutar o esperar gate: esperar gate.
• Reportes siempre en markdown estándar + tags (frontmatter) + wikilinks [[...]].
• Después de cada fix, ejecutar el proyecto (pnpm run dev o rtk dev) para verificar que arranca sin errores.
• Nunca commitiar sin aprobación explícita del usuario.