fn_registry/.claude/commands/autopilot.md

name, description

name	description
autopilot	Modo full-auto self-Q&A. Toma issue o flow con DoD definido, valida readiness, ejecuta hasta cerrarlo sin interaccion humana. Ante cada decision se autoformula la pregunta, se autoresponde con razonamiento explicito, y avanza. Spawnea subagentes. Para.

/autopilot — Modo autonomo end-to-end con self-Q&A

Ejecuta un issue o flow hasta cierre sin intervencion humana. Ante cada decision, Claude se formula la pregunta a si mismo y se la responde (self-Q&A) con razonamiento trazable, en vez de abortar. Auto-prefiere la opcion Recomendada cuando exista; cuando no, decide en base a evidencia del codigo, registry, y reglas. Cada Q&A queda persistido en task_runs.events_json[] para auditoria. Spawnea subagentes en paralelo y persiste estado en task_runs.

Diferencia con comandos relacionados:

Comando	Que hace
/autonomous-task <issue>	Wrapper directo de fn-orquestador (registry-bound, bucle 5 fases)
/fix-issue <issue>	Flujo guiado humano: rama + tasks + tests + version + close (pregunta cuando duda)
/flow run <NNNN>	Runner manual de flows (fase 2 — no implementado)
/autopilot <target>	Meta-dispatcher. Detecta issue vs flow, valida DoD, dispatch correcto, auto-defaults SIEMPRE

---

Sintaxis

/autopilot <NNNN>                  # issue NNNN (default si no hay prefijo)
/autopilot issue:<NNNN>            # issue NNNN explicito
/autopilot i:<NNNN>                # alias issue
/autopilot flow:<NNNN>             # flow NNNN
/autopilot f:<NNNN>                # alias flow
/autopilot check <target>          # solo audita DoD readiness, no ejecuta
/autopilot <target> --max-iterations N --max-minutes M
/autopilot <target> --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/<NNNN>-*.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/<NNNN>-*.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 <id> 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 al humano. En su lugar, self-Q&A loop: cuando surja una decision, Claude la formaliza como Question -> Options -> Reasoning -> Choice y persiste el bloque en task_runs.events_json[]. Ver seccion "Self-Q&A loop" mas abajo. Solo ABORTA con status=needs_human si la decision toca: (a) destructivo sin rollback (--force, git reset --hard, DROP TABLE), (b) credenciales/secrets, (c) paths protegidos, (d) contradice DoD explicito del issue. En esos casos, NUNCA self-answer — escala al humano.
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. Si no hay marcado, self-Q&A con justificacion.
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-<NNNN>-<slug>/ (rama auto/<NNNN>-<slug>) 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:

   git fetch origin master
   git -C <main_repo> rev-parse --is-clean        # tolerante: solo confirmar master rebased
   WT=worktrees/auto-<NNNN>-<slug>
   git worktree add -b auto/<NNNN>-<slug> "$WT" master
   cd "$WT"                                       # todo el trabajo posterior aqui
   

   Path del worktree:
   • Dentro del repo: worktrees/auto-<NNNN>-<slug>/ (gitignored). Permite que herramientas con FN_REGISTRY_ROOT apunten al worktree y no a master.
   • Alternativa /tmp/fn_autopilot_<NNNN>_<ts>/ 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/<NNNN>-<slug> existe pero el worktree no -> git worktree add "$WT" auto/<NNNN>-<slug>. Conflicto en rebase -> ABORT. Cierre exitoso: merge --no-ff a master desde el repo principal (git -C <main> merge --no-ff auto/<NNNN>-<slug>) solo tras tests verde + DoD 100%. Luego git worktree remove <WT> + git branch -d auto/<NNNN>-<slug>. 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 <target> 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, self_qa?}.

---

Self-Q&A loop (corazon del modo)

Cuando aparece una decision sin Recomendado explicito, NO abortar y NO preguntar al humano. Claude:

1. Formula la pregunta en una frase. Una sola pregunta por bloque, especifica, contestable.
2. Lista opciones (2-4). Misma forma que AskUserQuestion interno: label + description. Si solo hay una opcion viable, indicalo (Options: [A] only viable).
3. Razona en 1-3 lineas apoyandote en: registry (mcp__registry__fn_search), reglas (.claude/rules/), tests previos, archivos del repo, convenciones del proyecto.
4. Elige y marca confidence: high|med|low. Si low y la accion no es trivialmente reversible -> ABORT con status=needs_human y adjunta el bloque Q&A.
5. Persiste en events_json[] con shape:

   {
     "ts": "...",
     "agent": "autopilot",
     "action": "self_qa",
     "self_qa": {
       "question": "Crear el flag enabled=false o ya enabled=true?",
       "options": [
         {"label": "enabled=false", "rationale": "TBD doctrina (feature_flags.md): merge codigo terminado pero NO expuesto"},
         {"label": "enabled=true", "rationale": "feature ya tiene tests verde y DoD 100%"}
       ],
       "choice": "enabled=false",
       "confidence": "high",
       "reasoning": "feature_flags.md regla: 'cuando se activa: cambiar enabled:true y rellenar enabled_at'. Activar va en commit posterior."
     }
   }
   

6. Avanza sin esperar.

Tope de self-Q&A: --max-self-answers (default 20). Si se excede -> ABORT status=overdeliberating con dump de todas las Q&A. Una iteracion del bucle que necesita >5 Q&A es señal de DoD vago — abortar.

Cuando NO usar self-Q&A (ABORT en vez de auto-responder):

Caso	Razon
Destructivo sin rollback (git reset --hard, rm -rf fuera /tmp/, DROP TABLE, --no-verify, --force)	Coste de error infinito
Credenciales/tokens/secrets	Riesgo de exfiltracion
Paths protegidos (dev/autonomous_protected_paths.json)	Regla dura del orquestador
Contradiccion explicita con DoD del issue	DoD es contrato
Decision arquitectonica multi-app (renombrar tabla compartida, romper API publica)	Blast radius > 1 artefacto
confidence: low + accion no reversible	Self-Q&A no garantiza acierto sin oraculo

---

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-<NNNN>-<slug>/ 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/<NNNN>-<slug> worktrees/auto-<NNNN>-<slug> 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/<NNNN>-*.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-<NNNN>-<slug>/ desde master (regla dura 6) — incluso para flows que solo ejecutan funciones sin escribir codigo, asi los side-effects en dev/flows/<NNNN>-*.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: <id> -> ./fn run <id> [args].
4. Cada paso tipo cmd: <bash> -> 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/<NNNN>-<ts>.jsonl.
8. Si todos [ ] -> [x] -> commit en rama + merge --no-ff a master + /flow done <NNNN> + 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
self_qa:        7 (6 high / 1 med / 0 low)
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 <target>

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 <id>, spawn fn-constructor antes
--auto-apply-proposals	safe	Pasado a fn-orquestador en Path A
--max-self-answers N	20	Tope de bloques Self-Q&A por run. Excedido -> ABORT overdeliberating

---

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
overdeliberating	Excedido --max-self-answers	DoD probablemente vago — humano refina criterios
low_confidence_abort	Self-Q&A devolvio confidence: low en accion no reversible	Humano valida la decision concreta

---

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 al humano	Rompe el contrato autonomo — usa self-Q&A loop
Self-Q&A sin razonamiento explicito	Decision opaca, no auditable
Self-Q&A con confidence: high en accion destructiva sin oraculo	Confianza injustificada — escalar
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

# 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