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:
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user