Subagent Scope Guard
If you were dispatched as a subagent to execute a specific delegated task,
skip this skill's full orchestration workflow. Execute only the assigned
task, report result (DONE / DONE_WITH_CONCERNS / BLOCKED), and return.
Skill: Agent Runs Board (SE-349)
Fuente de verdad: docs/specs/SE-349-agent-runs-ledger.spec.md
Cuándo usar
- Estás lanzando un run autónomo (overnight-sprint, code-improvement-loop,
tech-research-agent, agent-task, SDD) y debes registrarlo en el ledger.
- Quieres saber en qué columna está cada run o qué necesita atención.
- Un PR de un run falla CI o recibe
changes_requested y necesitas localizar
el run que lo posee.
Paths autoritativos (lee ANTES de actuar)
Modelo mental
El estado de display NUNCA se almacena. El ledger solo guarda hechos
durables (activity_state, is_terminated, hechos de PR). El estado visible
(working, needs_input, ci_failed, changes_requested, merge_conflict, approved,
review_pending, pr_open, draft, merged, terminated, idle) se deriva en
lectura por precedencia. Si no ves una columna, no es que el run esté roto:
es que sus hechos no la producen todavía.
Flujo de registro (obligatorio al lanzar un run)
# 1. Nace el run → devuelve run_id
R=$(bash scripts/savia-runs.sh start <mode> <agent> "<task>" \
--project <proyecto> --branch <rama agent/*>)
# mode ∈ overnight|improve|research|agent-task|sdd
# 2. A medida que avanza
bash scripts/savia-runs.sh state "$R" active # trabajando
bash scripts/savia-runs.sh state "$R" waiting_input # esperando input
bash scripts/savia-runs.sh state "$R" blocked # bloqueado (permiso)
# 3. Cuando hay PR
bash scripts/savia-runs.sh pr "$R" <number> \
--state open --ci passing --review requested --mergeable true
# 4. Cuando el PR se resuelve → actualiza hechos, no fuerces
bash scripts/savia-runs.sh pr "$R" <number> --state merged --ci passing --review approved
Guardrail de terminación (NO lo esquives)
finish se niega si el run posee un PR open|draft vivo. Es deliberado:
un run cuyo PR sigue vivo (CI pendiente, review, mergeable) no está muerto.
Camino correcto:
- Resuelve el PR (merge/close) y actualiza
pr --state merged|closed.
- O desposee explícitamente:
bash scripts/savia-runs.sh pr "$R" clear.
- Entonces:
bash scripts/savia-runs.sh finish "$R".
--force es último recurso documentado, no atajo de rutina.
Lectura del board
bash scripts/savia-runs.sh status # board derivado (Working/Needs you/...)
bash scripts/savia-runs.sh status --json # machine-readable
bash scripts/savia-runs.sh list --json # tabla con derived_status
bash scripts/savia-runs.sh list --mode overnight
bash scripts/savia-runs.sh show "$R" # hechos + derivado + traza de precedencia
Qué significa cada columna
| Columna |
Significado |
Acción esperada |
| WORKING |
run activo sin señales de bloqueo |
observar |
| NEEDS YOU |
needs_input, ci_failed, changes_requested, merge_conflict, blocked |
aquí está el trabajo: input, fix CI, resolver cambios o conflicto |
| IN REVIEW |
PR abierto/draft esperando review |
revisar o esperar revisores |
| READY TO MERGE |
PR aprobado y mergeable |
merge humano |
| DONE |
PR merged |
archivar |
| TERMINATED |
run terminado sin merge |
revisar por qué |
Reglas de datos (CRIT-001)
- Todo es local (
data/agent-runs-ledger.jsonl, gitignored). Cero red,
cero telemetría a proveedor (AO usa PostHog cloud — SE-349 lo rechaza).
- NO escribas el ledger a mano; usa el CLI (upsert por
run_id).
- N3+ no sale del workspace; el ledger es dato operativo interno.
Referencia rápida del CLI
savia-runs.sh init # asegura ledger
savia-runs.sh start <mode> <agent> <task> [--project P] [--branch B] [--url U]
savia-runs.sh state <run_id> <spawning|active|waiting_input|blocked|exited>
savia-runs.sh pr <run_id> <number> [--state open|draft|merged|closed]
[--ci passing|failing|pending|unknown]
[--review none|requested|changes_requested|approved]
[--mergeable true|false|unknown] [--url U]
savia-runs.sh pr <run_id> clear # desposee el PR
savia-runs.sh finish <run_id> [--force] # guardrail de terminación
savia-runs.sh status [--json] # board derivado
savia-runs.sh list [--mode M] [--json] # tabla con derived_status
savia-runs.sh show <run_id> # hechos + traza
savia-runs.sh reset # dev/test: vacía ledger
1---2layer: peripheral3name: agent-runs-board4description: "Usar cuando se lanza, supervisa o consulta un run autónomo (overnight-sprint, code-improvement-loop, tech-research-agent, SDD) y se necesita el ledger operativo con estado derivado. Triggers: 'registra el run', 'board de runs', 'estado del run', 'savia-runs', '¿en qué columna está mi run?', 'ci_failed', 'needs_input', 'merge_conflict'."5metadata:6 source: https://skillmd.com/skills/gonzalezpazmonica/agent-runs-board7 # --- metadata.savia.* (SE-333) ---8 savia.agent: dev-orchestrator9 savia.category: pm-operations10 savia.context: fork11 savia.loop_level: L0 # L0=draft | L1=report-only | L2=assisted | L3=unattended — ver docs/rules/domain/loop-phasing.md12 savia.maturity: stable13 savia.priority: medium14 savia.summary: "Ledger operativo de runs autónomos (SE-349): hechos durables + estado derivado en lectura + board Working/Needs you/In review/Ready to merge/Done. Guardrail: un run con PR vivo no es terminable."15 savia.tags: "autonomous, observability, ledger, board, se-349"16---1718## Subagent Scope Guard1920> If you were dispatched as a subagent to execute a specific delegated task,21> **skip this skill's full orchestration workflow**. Execute only the assigned22> task, report result (DONE / DONE_WITH_CONCERNS / BLOCKED), and return.2324# Skill: Agent Runs Board (SE-349)2526> Fuente de verdad: `docs/specs/SE-349-agent-runs-ledger.spec.md`2728## Cuándo usar2930- Estás lanzando un run autónomo (overnight-sprint, code-improvement-loop,31 tech-research-agent, agent-task, SDD) y debes **registrarlo** en el ledger.32- Quieres saber **en qué columna está** cada run o **qué necesita atención**.33- Un PR de un run falla CI o recibe `changes_requested` y necesitas localizar34 el run que lo posee.3536## Paths autoritativos (lee ANTES de actuar)3738| Recurso | Path |39|---|---|40| Script CLI | `scripts/savia-runs.sh` |41| Spec | `docs/specs/SE-349-agent-runs-ledger.spec.md` |42| Ledger (datos) | `data/agent-runs-ledger.jsonl` (gitignored) |43| Inspiración | https://github.com/Untrivial-ai/agent-orchestrator (`docs/architecture.md`) |4445## Modelo mental4647**El estado de display NUNCA se almacena.** El ledger solo guarda hechos48durables (`activity_state`, `is_terminated`, hechos de PR). El estado visible49(working, needs_input, ci_failed, changes_requested, merge_conflict, approved,50review_pending, pr_open, draft, merged, terminated, idle) se **deriva en51lectura** por precedencia. Si no ves una columna, no es que el run esté roto:52es que sus hechos no la producen todavía.5354## Flujo de registro (obligatorio al lanzar un run)5556```bash57# 1. Nace el run → devuelve run_id58R=$(bash scripts/savia-runs.sh start <mode> <agent> "<task>" \59 --project <proyecto> --branch <rama agent/*>)60# mode ∈ overnight|improve|research|agent-task|sdd6162# 2. A medida que avanza63bash scripts/savia-runs.sh state "$R" active # trabajando64bash scripts/savia-runs.sh state "$R" waiting_input # esperando input65bash scripts/savia-runs.sh state "$R" blocked # bloqueado (permiso)6667# 3. Cuando hay PR68bash scripts/savia-runs.sh pr "$R" <number> \69 --state open --ci passing --review requested --mergeable true7071# 4. Cuando el PR se resuelve → actualiza hechos, no fuerces72bash scripts/savia-runs.sh pr "$R" <number> --state merged --ci passing --review approved73```7475## Guardrail de terminación (NO lo esquives)7677`finish` **se niega** si el run posee un PR `open|draft` vivo. Es deliberado:78un run cuyo PR sigue vivo (CI pendiente, review, mergeable) **no está muerto**.79Camino correcto:80811. Resuelve el PR (merge/close) y actualiza `pr --state merged|closed`.822. O desposee explícitamente: `bash scripts/savia-runs.sh pr "$R" clear`.833. Entonces: `bash scripts/savia-runs.sh finish "$R"`.8485`--force` es último recurso documentado, no atajo de rutina.8687## Lectura del board8889```bash90bash scripts/savia-runs.sh status # board derivado (Working/Needs you/...)91bash scripts/savia-runs.sh status --json # machine-readable92bash scripts/savia-runs.sh list --json # tabla con derived_status93bash scripts/savia-runs.sh list --mode overnight94bash scripts/savia-runs.sh show "$R" # hechos + derivado + traza de precedencia95```9697### Qué significa cada columna9899| Columna | Significado | Acción esperada |100|---|---|---|101| WORKING | run activo sin señales de bloqueo | observar |102| NEEDS YOU | `needs_input`, `ci_failed`, `changes_requested`, `merge_conflict`, `blocked` | **aquí está el trabajo**: input, fix CI, resolver cambios o conflicto |103| IN REVIEW | PR abierto/draft esperando review | revisar o esperar revisores |104| READY TO MERGE | PR aprobado y mergeable | merge humano |105| DONE | PR merged | archivar |106| TERMINATED | run terminado sin merge | revisar por qué |107108## Reglas de datos (CRIT-001)109110- Todo es **local** (`data/agent-runs-ledger.jsonl`, gitignored). Cero red,111 cero telemetría a proveedor (AO usa PostHog cloud — SE-349 lo rechaza).112- NO escribas el ledger a mano; usa el CLI (upsert por `run_id`).113- N3+ no sale del workspace; el ledger es dato operativo interno.114115## Referencia rápida del CLI116117```118savia-runs.sh init # asegura ledger119savia-runs.sh start <mode> <agent> <task> [--project P] [--branch B] [--url U]120savia-runs.sh state <run_id> <spawning|active|waiting_input|blocked|exited>121savia-runs.sh pr <run_id> <number> [--state open|draft|merged|closed]122 [--ci passing|failing|pending|unknown]123 [--review none|requested|changes_requested|approved]124 [--mergeable true|false|unknown] [--url U]125savia-runs.sh pr <run_id> clear # desposee el PR126savia-runs.sh finish <run_id> [--force] # guardrail de terminación127savia-runs.sh status [--json] # board derivado128savia-runs.sh list [--mode M] [--json] # tabla con derived_status129savia-runs.sh show <run_id> # hechos + traza130savia-runs.sh reset # dev/test: vacía ledger131```