Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 21 additions & 1 deletion .agents/skills/l-01-agent-lifecycles/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -281,6 +281,25 @@ For ordinary spawned seats, settings are the sole developer-controlled spend sur
`spawn_agent_session` callers declare role and level, never harness/model/effort or direct
launch/session spend controls.

### Hosted role dispatch is three explicit states

Every role that dispatches another hosted role uses one exact session id through all three states:

1. Call `spawn_agent_session` with `context` omitted and `submit=false`. Success is
`spawned-unbriefed`; it creates and binds the seat but assigns no work.
2. Call `hosted_session_readiness(session_id=<returned-id>, wait_seconds=<finite-bound>)`.
Only `status=ready` advances that exact seat to harness-ready. Spawned-only and not-ready seats
are **not active work** and receive no task instructions.
3. Post exactly one durable `operator_inbox_post` row addressed by that same `agent_id`, with
`message_kind="dispatch-brief"` and `deliver_to_hosted=true`. Treat the seat as briefed only when
that row reports both `deliveryState=delivered` and
`deliveryDetail=harness-log-confirmed`.

If step 3 fails, the original durable row stays pending on the original spawned session for the
standard injector/supervisor retry path. Never duplicate the row, append another visible draft,
or respawn merely because delivery is pending. Settings-owned `sessionCommands` remain launch
configuration; settings-owned `promptKeywords` ride the post-readiness dispatch brief exactly once.

## settings.json Orchestration Block

Machine/user overrides layer over the role-file defaults, in the **global agentic settings file**
Expand Down Expand Up @@ -337,7 +356,8 @@ per-harness via the effective registry (claude `--model`/`--effort`; a mapping-l
env-only; a session-vocabulary effort like claude's `ultracode` is delivered as a post-launch
`/effort` paste). Unknown effort values REFUSE at dispatch naming the harness's vocabulary — the
CLI would warn-and-silently-degrade. The free-form escape hatch (`launchArgs` verbatim argv,
`promptKeywords` riding the brief paste, `sessionCommands` pasted before the brief) is never
`promptKeywords` riding the post-readiness brief exactly once, `sessionCommands` applied during
fresh-session launch) is never
validated, only recorded in spawn provenance; `orchestration.harnesses` teaches the framework new
TUIs or pre-customizes builtin launches (manual: `docs/reference/harnesses.md`).
`orchestration.loops` (the three-party-loop knobs: per-level loop sets, round cap, reviewer
Expand Down
14 changes: 12 additions & 2 deletions .agents/skills/l-01-agent-lifecycles/roles/architect.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,16 @@ host harness rules.
Hat-collapse is allowed here because this is the owner/developer-facing seat. The same collapse is
not allowed in spawned role seats.

## Hosted Role Dispatch

Every horizontal expansion from this seat follows the shared three-state protocol in `../SKILL.md`:
`spawn_agent_session(context omitted, submit=false)` must return `spawned-unbriefed`; then
`hosted_session_readiness` must return `status=ready` for the exact returned session id; only then
post one exact-agent durable `dispatch-brief`. A spawned-only or not-ready orchestrator is not
active work. Count it briefed only from `deliveryState=delivered` plus
`deliveryDetail=harness-log-confirmed`; a failed delivery stays pending on the same row and session,
never a duplicate brief or automatic respawn.

## Design And Drawing Board

When the developer is still shaping the work, the architect wears `roles/designer.md` inline:
Expand Down Expand Up @@ -247,8 +257,8 @@ developer or the configured distinct decider; the architect does not approve its
| model | highest-reasoning | developer-facing architecture and ruling quality need the strongest model |
| effort | high | decision framing is not the place to economize |
| launchArgs | — | free-form escape: verbatim harness argv (settings-only; never validated, recorded in spawn provenance) |
| sessionCommands | — | free-form escape: lines pasted + submitted into the fresh session before the brief (settings-only; never validated) |
| promptKeywords | — | free-form escape: prepended as the first line of the dispatch brief paste (settings-only; never validated) |
| sessionCommands | — | settings-owned launch configuration: lines pasted + submitted during fresh-session launch (never validated; not brief delivery) |
| promptKeywords | — | settings-owned keywords prepended exactly once to the post-readiness dispatch brief (never validated) |
| tools | developer-facing owner surface | `read_ar_files` · onboarding · route indexes · `task_doc` · inbox · gates for developer hand-offs · `spawn_agent_session` |

Settings.json `orchestration.roles.architect` overrides these, and `orchestration.rolesPerLevel.<level>.architect` overrides per dispatch level (role-file defaults < settings < level override; spawn knobs manual: `docs/reference/harnesses.md`).
4 changes: 2 additions & 2 deletions .agents/skills/l-01-agent-lifecycles/roles/curator.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,8 +100,8 @@ verdict.
| model | mid-reasoning | precise onboarding edits and reference checking |
| effort | medium | scales with onboarding blast radius via settings |
| launchArgs | — | free-form escape: verbatim harness argv (settings-only; never validated, recorded in spawn provenance) |
| sessionCommands | — | free-form escape: lines pasted + submitted into the fresh session before the brief (settings-only; never validated) |
| promptKeywords | — | free-form escape: prepended as the first line of the dispatch brief paste (settings-only; never validated) |
| sessionCommands | — | settings-owned launch configuration: lines pasted + submitted during fresh-session launch (never validated; not brief delivery) |
| promptKeywords | — | settings-owned keywords prepended exactly once to the post-readiness dispatch brief (never validated) |
| tools | onboarding surface | native reads/edits in memory worktree · native reads in code worktree · c-05 workflow · local route indexes · shell checks · inbox |

Settings.json `orchestration.roles.curator` overrides these, and `orchestration.rolesPerLevel.<level>.curator` overrides per dispatch level (role-file defaults < settings < level override; spawn knobs manual: `docs/reference/harnesses.md`).
4 changes: 2 additions & 2 deletions .agents/skills/l-01-agent-lifecycles/roles/designer.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,8 +91,8 @@ absorbs architect, orchestrator, manager, worker, strategist, or reviewer work.
| model | high-reasoning | reframe + blast-radius reasoning wants a strong model |
| effort | high | design leverage justifies the thinking budget |
| launchArgs | — | free-form escape: verbatim harness argv (settings-only; never validated, recorded in spawn provenance) |
| sessionCommands | — | free-form escape: lines pasted + submitted into the fresh session before the brief (settings-only; never validated) |
| promptKeywords | — | free-form escape: prepended as the first line of the dispatch brief paste (settings-only; never validated) |
| sessionCommands | — | settings-owned launch configuration: lines pasted + submitted during fresh-session launch (never validated; not brief delivery) |
| promptKeywords | — | settings-owned keywords prepended exactly once to the post-readiness dispatch brief (never validated) |
| tools | bird's-eye toolkit | route indexes · onboarding · `grepai_search` · `cgc_*` · `read_ar_files` · `task_doc` · inbox |

Settings.json `orchestration.roles.designer` overrides these, and `orchestration.rolesPerLevel.<level>.designer` overrides per dispatch level (role-file defaults < settings < level override; spawn knobs manual: `docs/reference/harnesses.md`).
19 changes: 15 additions & 4 deletions .agents/skills/l-01-agent-lifecycles/roles/manager.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,16 @@ Roles expand horizontally into new chats; sub-agents drill vertically inside thi
bounded analysis or report checks. A spawned manager never absorbs architect, orchestrator,
strategist, reviewer, curator, or worker briefs.

## Hosted Role Dispatch

Every worker, reviewer, or curator dispatch below uses the shared three-state protocol in
`../SKILL.md`: call `spawn_agent_session` with `context` omitted and `submit=false`, retain the exact
`spawned-unbriefed` session id, and require `hosted_session_readiness(...)=status=ready` for that
same id before posting one exact-agent durable `dispatch-brief`. Spawned-only and not-ready seats
are not active work. Briefed means both `deliveryState=delivered` and
`deliveryDetail=harness-log-confirmed`. If delivery fails, keep the original row and session pending
for standard retry; never duplicate the brief or respawn merely because delivery is pending.

## Lens

- **Opening move:** on a developer-declared takeover, first run `../SKILL.md`'s
Expand Down Expand Up @@ -99,8 +109,9 @@ stops belong to the orchestrator via the system-specialist protocol.
fix rounds resume the SAME builder); **every round must shrink the finding set** — a
non-shrinking round escalates to the orchestrator immediately, with the full round history
attached, regardless of the count.
- `spawn_agent_session(worker)` — a **fresh session** on the leaf: the brief (compiled from
`../templates/worker-brief.md`) is pasted + submitted, with `env={"AR_SPAWN_ROLE": "worker"}` and
- `spawn_agent_session(worker)` — a **fresh session** on the leaf: after exact-session readiness,
one durable `dispatch-brief` compiled from `../templates/worker-brief.md` is delivered and proven,
with `env={"AR_SPAWN_ROLE": "worker"}` and
the **qualified** leaf key `<repository>/<master>/<docId>`; together they claim the worker's
`(leaf, role)` seat, and the worker edits inside the leaf worktrees the brief names.
- **Process and ack the worker's signals — passive contract.** A turn-report artifact is expected at
Expand Down Expand Up @@ -224,8 +235,8 @@ own lifecycle if you need its state).
| model | mid-reasoning | leaf review + coordination; strong but below the orchestrator |
| effort | medium | one master's scope, not the portfolio |
| launchArgs | — | free-form escape: verbatim harness argv (settings-only; never validated, recorded in spawn provenance) |
| sessionCommands | — | free-form escape: lines pasted + submitted into the fresh session before the brief (settings-only; never validated) |
| promptKeywords | — | free-form escape: prepended as the first line of the dispatch brief paste (settings-only; never validated) |
| sessionCommands | — | settings-owned launch configuration: lines pasted + submitted during fresh-session launch (never validated; not brief delivery) |
| promptKeywords | — | settings-owned keywords prepended exactly once to the post-readiness dispatch brief (never validated) |
| tools | coordination + review + leaf lifecycle | `task_doc` · `read_ar_files` · gates · `spawn_agent_session` · `session_retire` (your own master's worker/reviewer/curator seats only) · worktree lifecycle (start · closeout · integrate · finalize) · C-11/`c-09` · inbox |

Settings.json `orchestration.roles.manager` overrides these, and `orchestration.rolesPerLevel.<level>.manager` overrides per dispatch level (role-file defaults < settings < level override; spawn knobs manual: `docs/reference/harnesses.md`).
22 changes: 17 additions & 5 deletions .agents/skills/l-01-agent-lifecycles/roles/orchestrator.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,16 @@ architect or owning seat via the inbox. Roles expand horizontally into new chats
vertically inside this seat for bounded analysis. A spawned orchestrator never absorbs another
role brief and never performs architect/developer-facing hat-collapse.

## Hosted Role Dispatch

Every manager, strategist, reviewer, or system-specialist dispatch below means the complete shared
three-state protocol in `../SKILL.md`: spawn with `context` omitted and `submit=false` and retain the
exact `spawned-unbriefed` session id; require `hosted_session_readiness(...)=status=ready` for that
same id; then create one exact-agent durable `dispatch-brief`. Spawned-only and not-ready seats are
not active work. Briefed means both `deliveryState=delivered` and
`deliveryDetail=harness-log-confirmed`. A delivery failure remains pending on its original row and
session for standard retry; never duplicate its brief or respawn it merely for pending delivery.

## The Event Loop

**Opening move, every session — new or resumed** (resumption is the common case, not the
Expand Down Expand Up @@ -56,8 +66,9 @@ exception):

**Profile check (takeover).** Before heavy work in any job: if this session's harness/model/
effort is wrong for the run (resolved: role file < settings), spawn the right chair —
`spawn_agent_session` with `AR_SPAWN_ROLE=orchestrator` + a conversation-handover packet
(`../templates/conversation-handover-packet.md`) — and hand over; the architect still talks to the
`spawn_agent_session` with `AR_SPAWN_ROLE=orchestrator`, then deliver a conversation-handover packet
(`../templates/conversation-handover-packet.md`) as the post-readiness `dispatch-brief` — and hand
over; the architect still talks to the
developer, and backend orchestrator seats stay behind the relay.

Several jobs can be active across a day; the loop routes per event. The frame's phase axis stays
Expand Down Expand Up @@ -234,7 +245,8 @@ acceptable and recorded in durable notes.)
Dispatch independent ready masters in parallel by default up to
`orchestration.concurrency.maxParallelMasters`. Sequential execution is the exception and must
name a gate, a shared-file one-writer dependency, or an explicit ruling. For each ready master
(dependencies integrated into super), call `spawn_agent_session(manager)` with a brief compiled from
(dependencies integrated into super), run the three-state hosted-role dispatch for
`spawn_agent_session(manager)`, compiling its post-readiness `dispatch-brief` from
`../templates/manager-brief.md` (`env={"AR_SPAWN_ROLE": "manager"}`, the **qualified** leaf key
`<repository>/<master>/<docId>`; together the environment role and qualified leaf claim the
manager's `(leaf, role)` seat; the brief carries the load-bearing base fact: master branches off
Expand Down Expand Up @@ -444,8 +456,8 @@ task, fill small blanks, escalate real deltas).
| model | highest-reasoning | portfolio blast-radius judgment wants the strongest model |
| effort | high | the bird's-eye seat; not the place to economize |
| launchArgs | — | free-form escape: verbatim harness argv (settings-only; never validated, recorded in spawn provenance) |
| sessionCommands | — | free-form escape: lines pasted + submitted into the fresh session before the brief (settings-only; never validated) |
| promptKeywords | — | free-form escape: prepended as the first line of the dispatch brief paste (settings-only; never validated) |
| sessionCommands | — | settings-owned launch configuration: lines pasted + submitted during fresh-session launch (never validated; not brief delivery) |
| promptKeywords | — | settings-owned keywords prepended exactly once to the post-readiness dispatch brief (never validated) |
| tools | full bird's-eye + orchestration | route indexes · onboarding · `grepai_search` · `cgc_*` · `read_ar_files` · `task_doc` · gates · `spawn_agent_session` · `session_retire` (any seat, portfolio-wide) · worktree/C-11 |

Settings.json `orchestration.roles.orchestrator` overrides these, and `orchestration.rolesPerLevel.<level>.orchestrator` overrides per dispatch level (role-file defaults < settings < level override; spawn knobs manual: `docs/reference/harnesses.md`).
4 changes: 2 additions & 2 deletions .agents/skills/l-01-agent-lifecycles/roles/reviewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -180,8 +180,8 @@ integrated on super.
| model | high-reasoning | adversarial review wants a strong, skeptical model |
| effort | high | the last line of defense before a handover; do not economize |
| launchArgs | — | free-form escape: verbatim harness argv (settings-only; never validated, recorded in spawn provenance) |
| sessionCommands | — | free-form escape: lines pasted + submitted into the fresh session before the brief (settings-only; never validated) |
| promptKeywords | — | free-form escape: prepended as the first line of the dispatch brief paste (settings-only; never validated) |
| sessionCommands | — | settings-owned launch configuration: lines pasted + submitted during fresh-session launch (never validated; not brief delivery) |
| promptKeywords | — | settings-owned keywords prepended exactly once to the post-readiness dispatch brief (never validated) |
| tools | review surface | `read_ar_files` · `memory_quality_check` · `drift_check` · `grepai_search` · `cgc_*` · `system/tools.md` checks · report templates · inbox |

Settings.json `orchestration.roles.reviewer` overrides these, and `orchestration.rolesPerLevel.<level>.reviewer` overrides per dispatch level (role-file defaults < settings < level override; spawn knobs manual: `docs/reference/harnesses.md`).
4 changes: 2 additions & 2 deletions .agents/skills/l-01-agent-lifecycles/roles/strategist.md
Original file line number Diff line number Diff line change
Expand Up @@ -197,8 +197,8 @@ Everything else — `task_doc`, `worktree_*`, `lifecycle_*`, `gate_*`, `spawn_ag
| model | highest-reasoning | whole-portfolio dependency + blast-radius reasoning wants the strongest model |
| effort | high | the sprint plan parameterizes every downstream loop; not the place to economize |
| launchArgs | — | free-form escape: verbatim harness argv (settings-only; never validated, recorded in spawn provenance) |
| sessionCommands | — | free-form escape: lines pasted + submitted into the fresh session before the brief (settings-only; never validated) |
| promptKeywords | — | free-form escape: prepended as the first line of the dispatch brief paste (settings-only; never validated) |
| sessionCommands | — | settings-owned launch configuration: lines pasted + submitted during fresh-session launch (never validated; not brief delivery) |
| promptKeywords | — | settings-owned keywords prepended exactly once to the post-readiness dispatch brief (never validated) |
| tools | read-only analysis surface | `read_ar_files` · `grepai_*` · `cgc_*` · `context_packet` · `drift_check` · notes-draft write · inbox |

Settings.json `orchestration.roles.strategist` overrides these, and `orchestration.rolesPerLevel.<level>.strategist` overrides per dispatch level (role-file defaults < settings < level override; spawn knobs manual: `docs/reference/harnesses.md`).
Original file line number Diff line number Diff line change
Expand Up @@ -93,8 +93,8 @@ The orchestrator owns the final decision: fixable-in-session -> order a targeted
| model | fable | system diagnosis and report synthesis |
| effort | high | degradation triage is high-impact |
| launchArgs | — | free-form escape: verbatim harness argv (settings-only; never validated, recorded in spawn provenance) |
| sessionCommands | — | free-form escape: lines pasted + submitted into the fresh session before the brief (settings-only; never validated) |
| promptKeywords | — | free-form escape: prepended as the first line of the dispatch brief paste |
| sessionCommands | — | settings-owned launch configuration: lines pasted + submitted during fresh-session launch (never validated; not brief delivery) |
| promptKeywords | — | settings-owned keywords prepended exactly once to the post-readiness dispatch brief (never validated) |
| tools | provider diagnostics + native reads + inbox | provider_status · provider_diagnostics · provider_watchers when explicitly ordered · logs/metrics reads · inbox |

Settings.json `orchestration.roles.system-specialist` overrides these, and
Expand Down
4 changes: 2 additions & 2 deletions .agents/skills/l-01-agent-lifecycles/roles/worker.md
Original file line number Diff line number Diff line change
Expand Up @@ -147,8 +147,8 @@ leaf well, ask when the leaf itself is in question" default.
| model | mid-reasoning | competent implementer on a scoped leaf |
| effort | medium | scales with leaf difficulty via settings |
| launchArgs | — | free-form escape: verbatim harness argv (settings-only; never validated, recorded in spawn provenance) |
| sessionCommands | — | free-form escape: lines pasted + submitted into the fresh session before the brief (settings-only; never validated) |
| promptKeywords | — | free-form escape: prepended as the first line of the dispatch brief paste (settings-only; never validated) |
| sessionCommands | — | settings-owned launch configuration: lines pasted + submitted during fresh-session launch (never validated; not brief delivery) |
| promptKeywords | — | settings-owned keywords prepended exactly once to the post-readiness dispatch brief (never validated) |
| tools | build surface | native edit · read-only AR retrieval · prescribed checks · inbox |

Settings.json `orchestration.roles.worker` overrides these, and `orchestration.rolesPerLevel.<level>.worker` overrides per dispatch level (role-file defaults < settings < level override; spawn knobs manual: `docs/reference/harnesses.md`).
Loading
Loading