fn_registry/docs/capabilities/agents.md

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

package main

import (
    "fmt"
    "log"

    "fn-registry/functions/infra"
)

func main() {
    cfg := infra.WorktreeLaunchConfig{
        RepoRoot:      "$HOME/fn_registry",
        Branch:        "auto/0115-worktree-launcher-fn",
        WorktreePath:  "$HOME/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/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.