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
6 changes: 5 additions & 1 deletion skills/delegate-kit/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ Clarify the requested result, constraints and acceptance checks. Consider substa

Parallel writers need disjoint ownership and stable interfaces. Coupled changes have one owner or proceed sequentially. Choose worker count from ready outcomes and integration capacity; there is no default cap of one. Honor explicit user and host limits. Do independent work while workers run; avoid duplicating their investigation.

Choose worker count for quality and elapsed time within explicit cost and capacity limits, not a default of one. Parallelize distinct ready outcomes with clear ownership; keep coupled work under one owner or staged dependencies. State the count and each worker's distinct value.

## Prepare and dispatch

Use [brief-template.md](references/brief-template.md): outcome, necessary facts, scope, workspace, constraints, checks and authorized finishing actions. Workers should begin from the brief and repository without the parent's full conversation. `when` and coordination instructions belong to you; profile `instructions` and the brief go to the worker.
Expand All @@ -34,9 +36,11 @@ Prepare with the saved session, stable task ID, selected profile and brief. The

`run` starts a CLI supervisor or returns the verified native/Paseo invocation. A bridge invocation is preparation, not an agent: call the actual host tool once and attach its returned ID. If dispatch outcome is uncertain, reconcile with the host before another call. Record correlated completion/permission events. Unique Claude native definitions must be discovered by that host; otherwise use CLI. Never rewrite a shared role when switching presets.

Status reporting is on by default. Read [observability.md](references/observability.md) and announce planned profiles/executors. Combine immediate preparation and dispatch into one runtime-backed launch update; report prepared separately only on delay, failure or user action. Prepared is not running.

## Await and verify results

Use host completion notifications or runtime `wait`. Read the compact result by default; full private logs are diagnostic artifacts. No log-summarizer model or periodic LLM heartbeat is needed. After each bounded wait, check runtime health or query the saved host agent without sending a prompt. A wait timeout does not stop the worker or authorize a duplicate. An attention alert requires diagnosis of process/turn progress; continue waiting only with a concrete reason, or stop/recover a confirmed stall. See [lifecycle and recovery](references/routing.md#lifecycle-and-recovery). Intervene for a blocker, permission request, user correction, explicit failure, breached limit or data risk.
Use host completion notifications or runtime `watch`; use `wait` for one run. Read compact results; reserve `watch --full` and logs for diagnosis. Report meaningful transitions as one-line rows. On an unchanged 60-second timeout, send at most one aggregate heartbeat if otherwise silent; do not repeat the roster or models. No log-summarizer model is needed. Check runtime health or query the saved host agent without prompting. A timeout neither stops the worker nor authorizes a duplicate. Diagnose attention alerts; keep waiting only for a concrete reason, or recover a confirmed stall. See [lifecycle and recovery](references/routing.md#lifecycle-and-recovery). Intervene for blockers, permission requests, corrections, failures, breached limits or data risk.

Transport acknowledgement, terminal turn, valid result and coordinator acceptance are separate. Compare evidence against acceptance checks, run relevant checks the adapter could not perform, and accept only completed work. Explain unverified claims. Runtime `accept` refuses incomplete required review sets; it records your judgment, not proof that tests passed.

Expand Down
12 changes: 6 additions & 6 deletions skills/delegate-kit/references/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,18 @@

| Path | Implemented | Automated evidence | Local evidence | Live model call |
|---|---|---|---|---|
| Codex CLI | fresh, result, exact resume, cancellation | legacy + v2 fake CLI tests | 0.153.4 | 2026-09-16: Sol fix + exact resume, Luna independent review + cancellation; isolated fixture, low reasoning |
| Codex CLI | fresh, result, exact resume, cancellation | legacy fake CLI supervisor; v2 preset/lease/observability fixtures | 0.153.4 | 2026-09-16: Sol fix + exact resume, Luna independent review + cancellation; isolated fixture, low reasoning |
| Claude CLI | fresh, result, exact resume | adapter + supervisor fixtures | help/version 2.1.268 | not run |
| Gemini CLI | fresh, result, exact resume | adapter + supervisor fixtures | help/version 0.36.0 | not run |
| OpenCode | permissions, provider/model, exact resume | legacy permission/adapter fixtures | help/version 1.18.23 | not run |
| Pi | official RPC via installed SDK, isolated settings, exact resume | SDK/protocol + fake process tests | not installed | not run |
| OMP | RPC v2 negotiation/chunks, terminal result, resume | protocol + fake CLI tests | 18.1.17 ready/state handshake, no prompt | not run |
| Native Codex/Claude | prepare, exact invocation, unique definitions, attach/events | bridge fixtures | tool/schema-dependent; no agent dispatched | not run |
| Paseo | materialized create/follow-up settings, daemon/workspace lease | bridge fixtures | no daemon/tools available | not run |
| Pi | official RPC via installed SDK, isolated settings, exact resume | adapter/runtime code review only in this repository | not installed | not run |
| OMP | RPC v2 negotiation/chunks, terminal result, resume | adapter/runtime code review only in this repository | 18.1.17 ready/state handshake, no prompt | not run |
| Native Codex/Claude | prepare, exact invocation, unique definitions, attach/events | observability metadata fixture only | tool/schema-dependent; no agent dispatched | not run |
| Paseo | materialized create/follow-up settings, daemon/workspace lease | preset validation and code review only | no daemon/tools available | not run |

Native writers require verified host enforcement of the reserved worktree binding. Hosts that cannot establish it must use an explicitly selected CLI route.

Native Pi/OMP and a dedicated T3 bridge are not implemented. A direct CLI does not become a Paseo UI agent. Desktop/cloud chats need actual shell and host tools. [Adapter contracts, official sources and limitations](providers.md).
Native Pi/OMP and a dedicated T3 bridge are not implemented; Pi and OMP use the explicit CLI/RPC transport. A direct CLI does not become a Paseo UI agent. Desktop/cloud chats need actual shell and host tools. [Adapter contracts, official sources and limitations](providers.md).

Worktrees coordinate writers, not all filesystem permissions. Read-only tool controls differ by executor. Pi/OMP writers deliberately exclude shell and internal delegation; the coordinator performs command checks and authorized commits. Runtime usage is null when unavailable, not zero. The runtime counts its own reservations/continuations and known legacy work; it cannot account for arbitrary agents launched outside it. No savings or model-quality percentage is promised.

Expand Down
4 changes: 2 additions & 2 deletions skills/delegate-kit/references/hosts.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,6 @@ Use actual `list_providers`, `list_models`, `inspect_provider` results, not Pase

Create/select the workspace through Paseo first. Pass `--workspace FILE` containing `owner: "paseo"`, its `id`, `daemon`, and optional `remote: true`; `--cwd` is a daemon path and is not checked locally. The runtime materializes `create_agent` with `provider: harness/model`, workspaceId, settings.modeId and optional thinkingOptionId, and notifyOnFinish. It never requires a Paseo profile. Invoke in the parent agent context on the saved daemon so Paseo owns the parent-child relationship.

Attach with both `--host-agent` and `--workspace-id`. Follow-up uses `send_agent_prompt` with the saved agentId and daemon. Notifications trigger result ingestion. Workspace creation/archive stay with Paseo; preserve changes and references before archiving. A direct Pi/OMP CLI is not automatically visible in Paseo UI. No live Paseo daemon or tool schema was available for this implementation; the bridge is contract-tested against the official documented tool surface and requires current-host verification before use.
Attach with both `--host-agent` and `--workspace-id`. Follow-up uses `send_agent_prompt` with the saved agentId and daemon. Notifications trigger result ingestion. Workspace creation/archive stay with Paseo; preserve changes and references before archiving. A direct Pi/OMP CLI is not automatically visible in Paseo UI. No live Paseo daemon or tool schema was available for this implementation; the bridge was reviewed against the official documented tool surface and requires current-host verification before use.

Sources checked 2026-09-16: [Paseo skill and tool contract](https://github.com/getpaseo/paseo/blob/main/skills/paseo/SKILL.md), [Paseo orchestration](https://paseo.sh/docs/orchestration). Local Desktop/cloud chats without shell and corresponding host tools cannot execute this bridge.
Sources checked 2026-09-16: [Paseo skill and tool contract](https://github.com/getpaseo/paseo/blob/main/skills/paseo/SKILL.md), [Paseo orchestration](https://paseo.sh/docs/orchestration). The bridge was reviewed against that documented surface but is not contract-tested by a complete repository fixture suite. Local Desktop/cloud chats without shell and corresponding host tools cannot execute this bridge.
3 changes: 2 additions & 1 deletion skills/delegate-kit/references/migration.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,12 @@ For assignments that intentionally depended on the parent, supply a decisions fi
```json
{
"parents": { "gpt": "codex", "claude": "claude" },
"authors": { "gpt": "codex", "claude": "claude" },
"default_preset": "gpt"
}
```

For auto/native family assignments, a matching explicit parent determines the original harness. Multiple harnesses in one family require that choice rather than selecting the first backend. These mappings are explicit user decisions; team names themselves have no routing meaning. A missing default remains unset. If other ambiguities remain, use conversational setup to construct and validate the intended complete v2 JSON from the dry-run output. Keep the original legacy file unchanged as evidence; the automatic converter deliberately refuses to invent missing models or translate preferences into specialties.
For auto/native family assignments, a matching explicit parent determines the original harness. Legacy reviewer/verifier backend maps also require `authors.PRESET`, because duo routing may deliberately choose a different family from the author. Multiple harnesses in one family require an explicit choice rather than selecting the first backend. These mappings are explicit user decisions; team names themselves have no routing meaning. A missing default remains unset. If other ambiguities remain, use conversational setup to construct and validate the intended complete v2 JSON from the dry-run output. Keep the original legacy file unchanged as evidence; the automatic converter deliberately refuses to invent missing models or translate preferences into specialties.

After user authorization, `migrate --apply --decisions FILE` backs up the exact old config, saves complete presets atomically per file, and records `migration-v2.json`. It refuses existing destinations/settings instead of overwriting them. A completed migration is idempotent and preserves later v2 edits. If a process crashes during a multi-file apply before the journal is saved, rerun dry-run and inspect the backup/proposed files; an existing destination is a recovery diagnostic, never permission to overwrite.

Expand Down
42 changes: 42 additions & 0 deletions skills/delegate-kit/references/observability.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# Team status reporting

This protocol is active for every delegated task; the user does not enable it with a command or preset field. Runtime state is the source of truth. Use `overview --session HOST:ID --task TASK` to confirm launch state, then retain its cursor and use compact `watch --session HOST:ID --task TASK --after CURSOR --timeout-ms 60000` while agents remain active. Use `watch --full` only for diagnosis.

## Low-noise policy

1. Before preparation, state the planned count by role/profile and requested executor.
2. When dispatch immediately follows preparation, omit a separate prepared message and send one launch update after actual dispatch. Surface prepared reservations separately only when dispatch waits, fails or needs user action.
3. Show the full active roster once after launch. After that, show only rows whose meaningful state changed. Repeat the full roster only after a material team change such as adding, replacing or removing an agent.
4. On an unchanged one-minute timeout, send at most one aggregate one-line heartbeat while work remains active, and only if no other meaningful commentary was sent during that interval. Never repeat agent rows, task descriptions or models in an unchanged heartbeat.
5. Report attention immediately. Before final handoff, report completion, acceptance and any failed, blocked or unverified run.

The timeout performs no model call, but tool output and commentary still occupy coordinator context. Compact watch results and deduplicated messages therefore matter. Do not narrate every poll or streaming-progress update.

## One-line interface

Use one line per displayed agent, localized to the user's language:

```text
🟢 Implementer — implementer-api — работает
🟢 Implementer — implementer-ui — работает
🟡 Researcher — research-auth — завершён, ожидает интеграции
🔴 Reviewer — reviewer-hard — требует внимания
```

Use the assigned short outcome instead of the profile when it is already known and fits on one line. Otherwise the stable profile is the task label. Show requested models in the initial plan/launch update and again only when identity changes or is relevant to a problem. Call a model runtime-confirmed only when `actual_model` is present.

Indicator semantics:

- 🟢 active work with confirmed execution, or accepted completion;
- 🟡 reserved, starting, cancelling, or completed but not yet accepted/integrated;
- 🔴 permission, orphaned, blocked, failed, timeout, or any health state requiring attention.

For an unchanged timeout use only the aggregate row, for example:

```text
🟢 Delegate Kit — 4 агента — работают 3, завершён 1, проблем 0
```

Use lifecycle terms precisely: `prepared` is reserved and `starting` is dispatching. Count an agent as started only when `execution_started` is true; for host routes that requires attach, and for CLI routes it requires a spawned executor process. `running` without that evidence is not yet working. `permission` needs user action, and `finished` is completed but not coordinator acceptance. A continuation replaces its earlier attempt in agent counts; `summary.attempts` in the full overview retains the audit total. The stage follows confirmed active work, while reserved later roles remain visible without advancing it.

`watch` is event-driven over meaningful lifecycle, health, identity and acceptance changes. It intentionally ignores heartbeat-file churn and streaming token output. Its timeout is a liveness cadence, not evidence of worker progress and not permission to retry.
2 changes: 1 addition & 1 deletion skills/delegate-kit/references/omp-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,6 @@ After sign-in, use `omp models openrouter --json` or the model picker to choose

Check effective config on both hosts and compare only non-secret managed settings. Launch RPC in an isolated temporary cwd with the same worker overrides; negotiate protocol v2, get_state, select the exact already configured model, disable retry/compaction and get_state again, then close stdin. Do not send prompt. This checks startup and the protocol, not provider authentication or generated results.

Local CLI status checks and supervisor heartbeats call no model. The coordinator does spend tokens when it receives a tool result: prefer a bounded long CLI wait (for example 300000 ms when the host tool supports it) over one-minute status conversations. Internal health checks still return early for completion or required attention. Host tool execution limits may shorten a wait; native/Paseo state checks require the host bridge and may wake the coordinator. This setup does not claim zero total coordination overhead.
Local CLI status checks, `overview`, `watch` and supervisor heartbeats call no model. Follow the default low-noise observability protocol: use compact `watch` with a bounded 60000 ms timeout. If it times out unchanged while work remains active, send at most one aggregate one-line heartbeat and only when no other meaningful commentary was sent during that interval; do not repeat the roster or models. Use `--full` only for diagnosis. A different user-visible cadence requires the user's explicit preference. Internal health checks still return early for completion or required attention. Host tool execution limits may shorten a wait; native/Paseo state checks require the host bridge and may wake the coordinator. This setup does not claim zero total coordination overhead.

Sources: [official installation](https://github.com/can1357/oh-my-pi#install), installed 18.1.17 `--help`, `auth-broker list --json`, `config` help, and [RPC contract](https://github.com/can1357/oh-my-pi/blob/main/docs/rpc.md).
Loading
Loading