docs(capabilities): create 'agents' group + tag audit_dod_schema

New capability group page docs/capabilities/agents.md consolidating:
- agent_launch_worktree_go_infra
- agent_cleanup_worktree_go_infra
- audit_dod_schema_go_infra (added 'agents' tag to its frontmatter)

3 functions = minimum for a capability group page. Adds row to
docs/capabilities/INDEX.md. End-to-end example shows the launch ->
work -> cleanup -> dod-audit cycle that agent_runner_api (0113)
will orchestrate.
This commit is contained in:
2026-05-18 18:24:17 +02:00
parent 1b6d7940da
commit 3efc7ede29
3 changed files with 76 additions and 1 deletions
+1
View File
@@ -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
+74
View File
@@ -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/<pid>, 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/<NNNN>.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 <branch> 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.