diff --git a/.claude/commands/autopilot.md b/.claude/commands/autopilot.md new file mode 100644 index 00000000..2064f3fc --- /dev/null +++ b/.claude/commands/autopilot.md @@ -0,0 +1,291 @@ +--- +name: autopilot +description: Modo full-auto. Toma issue o flow con DoD definido, valida readiness, ejecuta hasta cerrarlo sin interaccion humana. Auto-selecciona opciones Recomendadas. Spawnea subagentes. No pregunta. Para. +--- + +# /autopilot — Modo autonomo end-to-end + +Ejecuta un issue o flow **hasta cierre** sin intervencion humana. Auto-selecciona la opcion **Recomendada** en cualquier decision, spawnea subagentes en paralelo, y persiste estado en `task_runs`. **No usa `AskUserQuestion`**: si una decision no tiene Recomendado claro, ABORTA con razon antes de improvisar. + +Diferencia con comandos relacionados: + +| Comando | Que hace | +|---|---| +| `/autonomous-task ` | Wrapper directo de `fn-orquestador` (registry-bound, bucle 5 fases) | +| `/fix-issue ` | Flujo guiado humano: rama + tasks + tests + version + close (pregunta cuando duda) | +| `/flow run ` | Runner manual de flows (fase 2 — no implementado) | +| `/autopilot ` | **Meta-dispatcher**. Detecta issue vs flow, valida DoD, dispatch correcto, auto-defaults SIEMPRE | + +--- + +## Sintaxis + +``` +/autopilot # issue NNNN (default si no hay prefijo) +/autopilot issue: # issue NNNN explicito +/autopilot i: # alias issue +/autopilot flow: # flow NNNN +/autopilot f: # alias flow +/autopilot check # solo audita DoD readiness, no ejecuta +/autopilot --max-iterations N --max-minutes M +/autopilot --dry-run +``` + +Detector: +- `^\d{4}[a-z]?$` -> issue (sin prefijo = issue por defecto). +- `^(issue|i):\d{4}[a-z]?$` -> issue. +- `^(flow|f):\d{4}$` -> flow. +- Otra cosa -> ABORT con error de sintaxis. + +--- + +## Pre-flight: DoD readiness check (OBLIGATORIO) + +Sin DoD claro, autopilot no arranca. La verificacion es STOP-gate, no se rellena por inferencia. + +### Issue (`dev/issues/-*.md`) + +Lee el .md. Debe cumplir **todos** estos: + +1. Archivo existe en `dev/issues/` (no en `completed/`). +2. Frontmatter valido (`status`, `priority`). +3. **Al menos UNA** de: + - Seccion `## DoD` o `## Definition of Done` con >=1 bullet/checkbox concreto. + - Seccion `## Acceptance` con checkboxes `[ ]`. + - Seccion `## Tests` + `## Tareas` ambas no vacias. +4. Tipo soportado por `/autonomous-task` si va a delegar a orquestador (`feature_app_simple`, `bugfix_with_repro`, `refactor_safe`, `add_e2e_check`). Si no entra en estos, autopilot intenta ruta `/fix-issue` simplificada (registry-only changes sin rama). +5. **NO** contiene criterios no-verificables: "queda bonito", "es intuitivo", "UX mejor". Heuristica grep simple — si match -> warning + ABORT. + +Si falla -> ABORT con tabla: + +``` +=== autopilot check 0107c === +status: NOT READY +gaps: + - Sin seccion DoD/Acceptance/Tests + - Frontmatter sin priority +fix: + - Anadir `## DoD` con 3-5 bullets verificables programaticamente + - Anadir `priority: medium` al frontmatter +``` + +### Flow (`dev/flows/-*.md`) + +1. Archivo existe en `dev/flows/` (no en `completed/`). +2. Frontmatter valido. +3. Seccion `## Acceptance` con >=1 checkbox `[ ]` (o ya `[x]` — significa parcialmente progresado). +4. Seccion `## Flow` no vacia. +5. Pre-requisitos declarados (incluso si vacio explicito). +6. Tabla de funciones recomendadas presente — sin `FALTA: crear ` no resuelto (si hay `FALTA`, ABORT con lista de funciones a crear primero). + +Si `FALTA` esta presente: opcionalmente autopilot ofrece spawnear `fn-constructor` para cada FALTA — pero ESO solo si `--allow-construct-missing`. Por defecto ABORT y reportar. + +--- + +## Modo autonomo (reglas duras de comportamiento) + +Durante toda la ejecucion de `/autopilot`: + +1. **NO invocar `AskUserQuestion`** bajo ningun caso. Si surge una decision sin Recomendado obvio, ABORT con `status=needs_human` + razon. +2. **Auto-pick "Recommended"** en cualquier flag con opciones (mocks vs prod, default branch, etc.) — usar primer item etiquetado como recomendado en el archivo / convencion del proyecto. +3. **Acciones destructivas prohibidas sin flag explicito**: `git reset --hard`, `git push --force`, `rm -rf` fuera de `/tmp/`, `DROP TABLE`, `--no-verify`, `--force`. Si una accion las requiere -> ABORT. +4. **Hooks NO se saltan**. Si pre-commit falla, fix raiz; si excede scope, ABORT (NO `--no-verify`). +5. **Paths protegidos** de `dev/autonomous_protected_paths.json` se respetan exactamente. +6. **Rama dedicada + worktree aislado SIEMPRE — sin excepciones**. Autopilot opera en `worktrees/auto--/` (rama `auto/-`) para NO bloquear el working tree principal del humano. Aplica a issues, flows, registry-only y apps. Master NUNCA recibe commits directos en modo autopilot. Pre-flight obligatorio desde el working tree principal: + ```bash + git fetch origin master + git -C rev-parse --is-clean # tolerante: solo confirmar master rebased + WT=worktrees/auto-- + git worktree add -b auto/- "$WT" master + cd "$WT" # todo el trabajo posterior aqui + ``` + Path del worktree: + - **Dentro del repo**: `worktrees/auto--/` (gitignored). Permite que herramientas con `FN_REGISTRY_ROOT` apunten al worktree y no a master. + - Alternativa `/tmp/fn_autopilot__/` si la app necesita aislamiento total del filesystem del repo (raro). + Reanudacion idempotente: si el worktree ya existe -> `cd` a el + `git rebase master`. Si la rama `auto/-` existe pero el worktree no -> `git worktree add "$WT" auto/-`. Conflicto en rebase -> ABORT. + Cierre exitoso: merge `--no-ff` a master desde el repo principal (`git -C
merge --no-ff auto/-`) solo tras tests verde + DoD 100%. Luego `git worktree remove ` + `git branch -d auto/-`. + Cierre fallido: worktree y rama quedan vivos para inspeccion humana. Master intacto. + **Garantia**: el humano puede seguir editando en el repo principal mientras autopilot avanza — sin colisiones de checkout, sin index lockings, sin "uncommitted changes blocks branch switch". +7. **Watchdog**: si la metrica de progreso (`acceptance_done / acceptance_total` para flows; `tests_pass / tests_total` o `checks_pass / checks_total` para issues) NO sube en 3 iteraciones consecutivas -> ABORT con `status=stalled`. +8. **Timeout** default 60 min. Override con `--max-minutes`. +9. **Idempotencia**: re-lanzar `/autopilot ` sobre el mismo target reanuda desde el ultimo `task_run` exitoso (lookup por `issue_id` o `flow_id` en `task_runs`). +10. **No self-modification**: NUNCA tocar `.claude/agents/`, `.claude/commands/`, `.claude/rules/`, `.claude/scripts/`, `.claude/CLAUDE.md`. +11. **Trazabilidad**: cada decision se persiste en `task_runs.events_json[]` con `{ts, agent, action, evidence, diff_summary, auto_choice}`. + +--- + +## Dispatch logic + +### Path A: issue compatible con `fn-orquestador` + +Si el issue declara o se infiere tipo en `(feature_app_simple, bugfix_with_repro, refactor_safe, add_e2e_check)` Y toca apps/modules/framework: + +- Delega a `fn-orquestador` via `Agent(subagent_type="fn-orquestador", ...)` pasando: + - `issue_id`, `--auto-apply-proposals safe`, `--max-iterations`, `--max-minutes`, paths protegidos. +- Espera resultado, reenvia `task_run_id` + PR draft URL al humano. + +### Path B: issue registry-only (functions/types/docs/rules) + +- **Rama + worktree `worktrees/auto--/`** desde master actualizado (regla dura 6). Humano sigue trabajando en el repo principal en paralelo. +- Politica `apps_tbd.md` permite push directo a master para registry-only en modo humano, pero `/autopilot` NO lo usa: el aislamiento por rama+worktree es la garantia de rollback + paralelismo en modo autonomo. +- Plan inline con TaskCreate: + 1. Pre-flight worktree (`git fetch` + `git worktree add -b auto/- worktrees/auto-- master` + `cd` a el). + 2. Leer issue + extraer DoD. + 3. Search registry para piezas existentes (registry-first). + 4. Si falta funcion -> spawn `fn-constructor` paralelo. + 5. `fn index`. + 6. Tests (`go test`, `pytest`, `bash -n`, segun stack). + 7. Si toco modulos/framework -> `/version` correspondiente. + 8. Mover `dev/issues/-*.md` a `dev/issues/completed/`. + 9. Actualizar `dev/issues/README.md` (si existe). + 10. Commit atomico por bloque logico en la rama. + 11. Solo si TODOS los tests pasan + DoD 100%: merge `--no-ff` a master + push + delete rama. Si algo falla -> rama queda viva, master intacto. +- Verificacion final: DoD checkboxes -> todos marcados. + +### Path C: flow + +Runner inline (fase 2 manual, mientras `/flow run` no exista): + +1. **Rama + worktree `worktrees/auto-flow--/`** desde master (regla dura 6) — incluso para flows que solo ejecutan funciones sin escribir codigo, asi los side-effects en `dev/flows/-*.md` (checkboxes) y `dev/flows/runs/*.jsonl` se commitean en rama, no en master. Humano puede seguir editando el repo principal en paralelo. +2. Parsea `## Flow` del .md. +3. Cada paso tipo `function: ` -> `./fn run [args]`. +4. Cada paso tipo `cmd: ` -> Bash tool (con guardas destructivas). +5. Paso "MANUAL: ..." -> si tiene equivalente automatico (ej. "abrir Chrome y loguearse" vs `cdp_extract_recipe`) usa el automatico; si no tiene equivalente -> ABORT con `status=needs_human` y razon. +6. Tras cada paso, evalua `## Acceptance` checkboxes via heuristicas: + - "X runs en data_factory" -> `sqlite3` count. + - "DAG corre 2 veces consecutivas" -> consultar `dag_engine` logs. + - Otros -> dejar como `[ ]` y reportar. +7. Persiste run en `dev/flows/runs/-.jsonl`. +8. Si todos `[ ]` -> `[x]` -> commit en rama + merge `--no-ff` a master + `/flow done ` + delete rama. + +--- + +## Output canonico + +``` +=== /autopilot 0107c === +target: issue 0107c (refactor data_table) +path: B (registry-only) +status: done +iterations: 3 / 10 +duration: 18 min / 60 +dod_checks: 5/5 pass +proposals: 2 creadas, 1 auto-aplicada +agents_spawned: fn-constructor x2, fn-recopilador x1 +commits: 4 (3 feat + 1 refactor) +branch: master (registry-only, push directo) + +Trace: + 1. construir → ok (2 funciones nuevas, 1 split) + 2. tests → ok (43/43) + 3. version → /version modules/data_table major "..." + 4. close → mv to completed/, push + +Siguiente: ningun paso humano requerido. Verificar con: fn doctor modules +``` + +--- + +## Sub-comando: `/autopilot check ` + +Solo audita readiness — **no** ejecuta nada. + +``` +=== /autopilot check 0125 === +status: NOT READY +target: issue 0125 (skill-tree-dashboard-panel) +gaps: + - Sin seccion DoD/Acceptance + - Frontmatter sin priority +non_verifiable_criteria: + - "UX intuitiva" (linea 47) +fix: + - Anadir ## DoD con 3-5 bullets programaticamente verificables + - Reemplazar "UX intuitiva" por criterio medible +``` + +Si OK: + +``` +=== /autopilot check 0107c === +status: READY +target: issue 0107c (refactor data_table) +dod_items: 5 checkboxes +path_inferred: B (registry-only — modules/) +estimated_iter: 3-5 +``` + +--- + +## Flags + +| Flag | Default | Que hace | +|---|---|---| +| `--max-iterations N` | 10 | Tope de iteraciones del bucle | +| `--max-minutes M` | 60 | Timeout total | +| `--dry-run` | off | Plan + dispatch simulado, no aplica cambios | +| `--allow-construct-missing` | off | Si flow tiene `FALTA: crear `, spawn fn-constructor antes | +| `--auto-apply-proposals` | `safe` | Pasado a fn-orquestador en Path A | + +--- + +## Errores canonicos + +| Codigo | Significado | Accion | +|---|---|---| +| `NOT_READY` | DoD insuficiente | Humano edita .md y relanza | +| `needs_human` | Decision sin Recomendado | Humano resuelve y relanza | +| `stalled` | 3 iteraciones sin progreso | Humano revisa `events_json` | +| `timeout` | Excedido `--max-minutes` | Aumentar timeout o partir issue | +| `aborted_protected_path` | Cambio en path protegido | Humano revisa intent | +| `iterations_exhausted` | Excedido `--max-iterations` | Humano evalua si vale subir tope | +| `sandbox_breach` | Diff fuera del worktree | ABORT critico, audit | + +--- + +## Anti-patrones + +| Anti-patron | Por que es malo | +|---|---| +| `/autopilot` sin pre-check DoD | Trabajar sin criterio de exito = bucle infinito | +| Auto-relleno de DoD inventada | Criterios falsos -> falso "done" | +| Merge a master sin tests verde | Master no deployable | +| `AskUserQuestion` desde dentro | Rompe el contrato autonomo | +| Salto de hooks (`--no-verify`) | Encubre bugs reales | +| Tocar mas issues que el target | Scope creep silencioso | +| Borrar archivos sin backup en events_json | Pierde auditoria | + +--- + +## Relacion con otras reglas + +- [[autonomous_loop]] — politica del bucle (sandbox, paths protegidos, watchdog). +- [[apps_tbd]] — politica TBD por tipo de cambio. +- [[apps_subrepo]] — `git init` dentro de apps nuevas antes de limpiar worktree. +- [[feature_flags]] — codigo incompleto detras de flag OFF. +- [[registry_calls]] — invocaciones canonicas (MCP / fn run / heredoc). +- [[e2e_validation]] — `e2e_checks` consumidos por fn-analizador como gate de Path A. +- [[delegation]] — spawn fn-constructor antes que escribir inline. + +--- + +## Ejemplos + +```bash +# Issue registry-only con DoD claro +/autopilot 0107c +/autopilot i:0107c # equivalente con prefijo explicito + +# Issue app que requiere orquestador +/autopilot issue:0070 --max-iterations 15 --max-minutes 90 + +# Flow con piezas faltantes — autoriza creacion antes +/autopilot flow:0008 --allow-construct-missing + +# Solo audit, no ejecutar +/autopilot check 0125 +/autopilot check flow:0008 + +# Dry run +/autopilot 0107c --dry-run +```