egutierrez
7913116a8e
- .claude/agents/fn-analizador/SKILL.md - .claude/agents/fn-constructor/SKILL.md - .claude/agents/fn-executor/SKILL.md - .claude/agents/fn-mejorador/SKILL.md - .claude/agents/fn-orquestador/SKILL.md - .claude/agents/fn-recopilador/SKILL.md - .claude/commands/app.md - .claude/commands/compile.md - .claude/commands/cpp-app.md - .claude/commands/create_functions.md - ... Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
75 lines
3.5 KiB
Markdown
75 lines
3.5 KiB
Markdown
# 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/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.
|