diff --git a/docs/capabilities/INDEX.md b/docs/capabilities/INDEX.md index 5514c27c..14274418 100644 --- a/docs/capabilities/INDEX.md +++ b/docs/capabilities/INDEX.md @@ -38,6 +38,7 @@ Indice de grupos de capacidades del registry. Cada grupo agrupa >=3 funciones qu | [validator](validator.md) | 6 | Funciones que verifican datos/config contra reglas. Pre-flight de sinks y gates en DAGs | | [navegator](navegator.md) | 4 | Automatización de browser via CDP + AX tree + LLM: obtener, limpiar, chunkear AX tree y llamar a Claude CLI | | [cpp-dashboard-viz](cpp-dashboard-viz.md) | 10 | Primitivas C++ ImGui para dashboards: kpi_card, sparkline, line/bar/scatter/pie/heatmap/histogram, panel containers | +| [agents](agents.md) | 3 | Orquestar agentes Claude headless en git worktrees: launch, cleanup, DoD evidence schema audit | ## Como anadir grupo diff --git a/docs/capabilities/agents.md b/docs/capabilities/agents.md new file mode 100644 index 00000000..1673c9b6 --- /dev/null +++ b/docs/capabilities/agents.md @@ -0,0 +1,74 @@ +# Capability group: agents + +Funciones para orquestar agentes Claude headless en git worktrees con DoD (Definition of Done) evidence schema. + +Cubre el ciclo de vida completo de un run autonomo: crear sandbox (worktree + rama), lanzar `claude -p` headless, redirigir logs, hacer cleanup ordenado tras terminar/abortar, y auditar el frontmatter `dod_evidence_schema` que valida que cada run dejo evidencia trazable. + +## Funciones + +| ID | Firma corta | Que hace | +|---|---|---| +| `agent_launch_worktree_go_infra` | `AgentLaunchWorktree(cfg) WorktreeLaunchResult` | crear worktree + spawn claude headless en background | +| `agent_cleanup_worktree_go_infra` | `AgentCleanupWorktree(repo, branch, path, pid) error` | kill PID + remove worktree + delete branch (best-effort) | +| `audit_dod_schema_go_infra` | `AuditDodSchema(issuesDir, flowsDir) Report` | escanea `.md` y valida bloque `dod_evidence_schema` del frontmatter | + +## Ejemplo canonico end-to-end + +```go +package main + +import ( + "fmt" + "log" + + "fn-registry/functions/infra" +) + +func main() { + cfg := infra.WorktreeLaunchConfig{ + RepoRoot: "/home/lucas/fn_registry", + Branch: "auto/0115-worktree-launcher-fn", + WorktreePath: "/home/lucas/fn_registry/worktrees/0115-worktree-launcher-fn", + Prompt: "Implement issue 0115 — worktree launcher Go function", + LogPath: "/tmp/claude-0115.log", + SkipPerms: true, + ResetIfExists: true, + } + + res := infra.AgentLaunchWorktree(cfg) + if res.Error != "" { + log.Fatal(res.Error) + } + fmt.Printf("claude PID=%d log=%s\n", res.PID, res.LogPath) + + // ... agente trabaja, tail del log, polling /proc/, etc ... + + // Cleanup tras terminar/abortar + if err := infra.AgentCleanupWorktree(cfg.RepoRoot, cfg.Branch, cfg.WorktreePath, res.PID); err != nil { + log.Printf("partial cleanup: %v", err) + } + + // Validar DoD del issue antes de cerrarlo + report, _ := infra.AuditDodSchema("/home/lucas/fn_registry/dev/issues", "") + fmt.Printf("dod: %d items, %d invalid\n", report.TotalItems, report.InvalidItems) +} +``` + +## Fronteras + +- **NO maneja merge a master** — eso es responsabilidad de `apps/agent_runner_api` (issue 0113). +- **NO persiste runs** — la tabla `agent_runs.db` vive en `agent_runner_api`, no aqui. +- **NO valida DoD** — `audit_dod_schema_go_infra` solo lee `dod_evidence_schema` y comprueba que cada item tenga id/kind/expected validos. La evidencia real (screenshots, logs, urls) se valida en otra capa. +- **NO genera el prompt** — el caller compone el prompt antes de pasarlo. Para integraciones con `dev/issues/.md`, usar funciones de `dev/` directamente. +- **NO maneja Windows**: `agent_cleanup_worktree` usa `syscall.Kill` (Linux/Darwin). En Windows compila pero el kill no hace nada — documentado en `agent_cleanup_worktree.md`. + +## Prerequisitos + +- `git` >= 2.5 (worktrees). +- Rama `master` (no `main`) en el repo principal — `AgentLaunchWorktree` hace `git worktree add ... -b master`. +- Opcional: binario `claude` en PATH. Si falta, la funcion hace fallback a un `echo` stub que termina inmediatamente — util para tests CI, no para produccion. + +## Notas + +- Las dos funciones operativas (`launch`/`cleanup`) son simetricas — siempre que se llame a una se debe llamar a la otra. `agent_runner_api` lo encadena en un defer. +- `audit_dod_schema` se invoca tambien desde `fn doctor dod` (issue 0114) — la dependencia es bidireccional logicamente, pero del registry no hay imports entre ellas. diff --git a/functions/infra/audit_dod_schema.md b/functions/infra/audit_dod_schema.md index 3f23c9a2..e29f4a32 100644 --- a/functions/infra/audit_dod_schema.md +++ b/functions/infra/audit_dod_schema.md @@ -7,7 +7,7 @@ version: "1.0.0" purity: impure signature: "func AuditDodSchema(issuesDir, flowsDir string) (DodSchemaReport, error)" description: "Escanea dev/issues/ y dev/flows/ (incluidos subdirectorios completed/) y para cada .md parsea el bloque dod_evidence_schema del frontmatter YAML. Valida que cada item tenga id unico, kind in {screenshot,log,url,cmd}, expected no vacio y required bool (default true). Read-only: no modifica nada. Devuelve un DodSchemaReport con files (uno por archivo con items o errores), totales y conteo de items invalidos. Tolerante a frontmatter ausente o malformed — registra el error en el archivo afectado y continua." -tags: [doctor, dod, evidence, frontmatter, taxonomy, validator] +tags: [agents, doctor, dod, evidence, frontmatter, taxonomy, validator] uses_functions: [] uses_types: [] returns: []