Add tooling-harness-orchestration: the catalog has no skill for the harness-native orchestration surface #1325

New issue

Closed

opened 2026-08-27 09:51:25 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

2026-08-27 09:51:25 +00:00

Owner

Outcome

Add one skill under .agents/skills/ covering the orchestration surface the
Claude Code harness now ships, with the estate-specific rules that have to ride
along with it. Nothing in the catalog covers it today.

The gap, checked two ways

.agents/skills/ carries 18 entries. None is about harness orchestration.
The nearest name, tooling-agent-workflows, is the five-tier information
model for documenting agent-facing CLI commands, which is a different subject
and will not fire on these triggers.
A grep across .agents/ for SendMessage, subagent, orchestrat,
fan-out, and multi-agent returns six files, all of them incidental
mentions inside unrelated composed skills. No skill owns the topic.

One modality proves nothing, which is why both are recorded here.

The surface to cover

Verified present in a live session on this host by loading each tool schema.

Agent - subagent spawn, the registered agent types, fork inheriting
parent context, isolation: "worktree" and what it actually costs, background
execution and completion notification.
Workflow - deterministic multi-agent scripts. pipeline() versus
parallel() and when a barrier is genuinely justified, budget, schema-forced
structured output, resume by runId. Carries an explicit user-opt-in gate that
the skill must state rather than bury.
Monitor - streamed events from a long-running script or a WebSocket. The
coverage rule matters most: a filter that greps only the success marker stays
silent through a crashloop, and silence reads identical to still-running.
Bash with run_in_background - the one-notification case, and why an
unbounded tail -f is the wrong tool for it.
SendMessage and ListAgents - cross-session and cross-machine agent
messaging, name-as-address, notify_when_idle.
ScheduleWakeup, CronCreate, TaskStop, TaskOutput, PushNotification.
RemoteTrigger - cloud routines, webhook triggers, and list_runs plus
get_run_log as the debugging path.

The estate rules that must ride along

A skill that teaches only the tool surface would be worse than none, because it
would read as license. Four rules, each of which I confirmed against the tool
contracts rather than assuming.

None of this is durable. CronCreate writes nothing to disk and dies with
the session. Recurring jobs auto-expire after seven days. Workflow resume is
same-session only. Ward's dispatch is durable, with issue-backed reservations
and restart reconciliation. Never build durable dispatch on harness cron, and
never describe a harness schedule as a replacement for one.
Messaging carries no authority. Asking a peer to do what your own session
denied is cross-session permission laundering, prohibited by the tool contract
itself. This is the same shape as the boundary model: a seat that defers a
boundary does not acquire it by asking a seat that holds it.
It is one harness. This entire surface is Claude Code. The roster runs
seats on codex, openhands, goose, holmesgpt, plandex, hermes, anythingllm,
mixpost, penpot, and discord. Anything built on it is unavailable to those
seats by construction.
Checkpoint discipline does not relax inside a subagent. The native
checkpoint rule binds work a subagent produced exactly as it binds the parent,
and a fan-out that leaves findings only in a transcript has lost them.

Shape

One skill, tooling-harness-orchestration, matching the tooling- prefix
category in categories.yaml. Body stays
short and routes to references/ files, the way tooling-agent-workflows
already does, so the per-file documentation caps are met without compressing the
content.

The description needs real trigger coverage. Candidate triggers: orchestration,
subagent, fan out, parallel agents, background task, monitor a log, schedule a
task, cron, cross-session, message another agent, workflow script.

Acceptance criteria

.agents/skills/tooling-harness-orchestration/SKILL.md exists with valid
frontmatter and a description carrying the triggers above.
Every tool in the surface list is covered or explicitly scoped out.
All four estate rules appear, and the durability rule states plainly that
harness scheduling is not a substitute for Ward dispatch.
check-skills, check-composed-skills, documentation-layout,
dead-cross-links, and the rest of the catalog suite pass.
docs/FEATURES.md is updated only if this counts as a new significant
capability rather than one more catalog skill. Author's call, and the
default is no entry.

Boundaries

Not a Ward replacement, and the skill must not read as one. Scored against
Ward's own docs/FEATURES.md,
this surface overlaps one clause of one of six capability groups: the
authenticated-messaging half of authority-free collaboration. Governed
commands and audit, isolated least-access execution, fixed roles and landing
workflows, and durable dispatch and recovery are untouched.
Do not propose Ward deletions from this issue. If the overlap is worth acting
on, that is a separate build-versus-buy decision with its own evidence.

Ownership

Filed from the Portfolio Director seat. A skill is doctrine rather than running
software, so this is not a boundary-build-foundational-software handoff and
does not need the platform seat.

The companion issue in this repository correcting AGENTS.md:214, which
currently declares this surface does not exist.

## Outcome Add one skill under `.agents/skills/` covering the orchestration surface the Claude Code harness now ships, with the estate-specific rules that have to ride along with it. Nothing in the catalog covers it today. ## The gap, checked two ways * `.agents/skills/` carries 18 entries. None is about harness orchestration. The nearest name, `tooling-agent-workflows`, is the five-tier information model for documenting agent-facing CLI commands, which is a different subject and will not fire on these triggers. * A grep across `.agents/` for `SendMessage`, `subagent`, `orchestrat`, `fan-out`, and `multi-agent` returns six files, all of them incidental mentions inside unrelated composed skills. No skill owns the topic. One modality proves nothing, which is why both are recorded here. ## The surface to cover Verified present in a live session on this host by loading each tool schema. * **`Agent`** - subagent spawn, the registered agent types, `fork` inheriting parent context, `isolation: "worktree"` and what it actually costs, background execution and completion notification. * **`Workflow`** - deterministic multi-agent scripts. `pipeline()` versus `parallel()` and when a barrier is genuinely justified, `budget`, schema-forced structured output, resume by `runId`. Carries an explicit user-opt-in gate that the skill must state rather than bury. * **`Monitor`** - streamed events from a long-running script or a WebSocket. The coverage rule matters most: a filter that greps only the success marker stays silent through a crashloop, and silence reads identical to still-running. * **`Bash` with `run_in_background`** - the one-notification case, and why an unbounded `tail -f` is the wrong tool for it. * **`SendMessage` and `ListAgents`** - cross-session and cross-machine agent messaging, name-as-address, `notify_when_idle`. * **`ScheduleWakeup`, `CronCreate`, `TaskStop`, `TaskOutput`, `PushNotification`**. * **`RemoteTrigger`** - cloud routines, webhook triggers, and `list_runs` plus `get_run_log` as the debugging path. ## The estate rules that must ride along A skill that teaches only the tool surface would be worse than none, because it would read as license. Four rules, each of which I confirmed against the tool contracts rather than assuming. * **None of this is durable.** `CronCreate` writes nothing to disk and dies with the session. Recurring jobs auto-expire after seven days. `Workflow` resume is same-session only. Ward's dispatch is durable, with issue-backed reservations and restart reconciliation. Never build durable dispatch on harness cron, and never describe a harness schedule as a replacement for one. * **Messaging carries no authority.** Asking a peer to do what your own session denied is cross-session permission laundering, prohibited by the tool contract itself. This is the same shape as the boundary model: a seat that defers a boundary does not acquire it by asking a seat that holds it. * **It is one harness.** This entire surface is Claude Code. The roster runs seats on codex, openhands, goose, holmesgpt, plandex, hermes, anythingllm, mixpost, penpot, and discord. Anything built on it is unavailable to those seats by construction. * **Checkpoint discipline does not relax inside a subagent.** The native checkpoint rule binds work a subagent produced exactly as it binds the parent, and a fan-out that leaves findings only in a transcript has lost them. ## Shape One skill, `tooling-harness-orchestration`, matching the `tooling-` prefix category in [`categories.yaml`](.agents/skills/categories.yaml). Body stays short and routes to `references/` files, the way `tooling-agent-workflows` already does, so the per-file documentation caps are met without compressing the content. The description needs real trigger coverage. Candidate triggers: orchestration, subagent, fan out, parallel agents, background task, monitor a log, schedule a task, cron, cross-session, message another agent, workflow script. ## Acceptance criteria - [ ] `.agents/skills/tooling-harness-orchestration/SKILL.md` exists with valid frontmatter and a description carrying the triggers above. - [ ] Every tool in the surface list is covered or explicitly scoped out. - [ ] All four estate rules appear, and the durability rule states plainly that harness scheduling is not a substitute for Ward dispatch. - [ ] `check-skills`, `check-composed-skills`, `documentation-layout`, `dead-cross-links`, and the rest of the catalog suite pass. - [ ] `docs/FEATURES.md` is updated only if this counts as a new significant capability rather than one more catalog skill. Author's call, and the default is no entry. ## Boundaries * **Not a Ward replacement, and the skill must not read as one.** Scored against Ward's own [`docs/FEATURES.md`](https://github.com/coilyco-flight-deck/ward/blob/main/docs/FEATURES.md), this surface overlaps one clause of one of six capability groups: the authenticated-messaging half of authority-free collaboration. Governed commands and audit, isolated least-access execution, fixed roles and landing workflows, and durable dispatch and recovery are untouched. * Do not propose Ward deletions from this issue. If the overlap is worth acting on, that is a separate build-versus-buy decision with its own evidence. ## Ownership Filed from the Portfolio Director seat. A skill is doctrine rather than running software, so this is not a `boundary-build-foundational-software` handoff and does not need the platform seat. ## Related * The companion issue in this repository correcting `AGENTS.md:214`, which currently declares this surface does not exist.

coilyco-ops referenced this issue from a commit

2026-08-27 10:03:13 +00:00

feat(skills): add tooling-agent-orchestration carrying Ward and o2r patterns

coilyco-ops referenced this issue from a pull request that will close it,

2026-08-27 10:03:53 +00:00

feat(skills): add tooling-agent-orchestration carrying Ward and o2r patterns #1326

coilyco-ops commented

2026-08-27 10:04:59 +00:00

Author

Owner

Scope widened, name changed, PR open

Kai's direction after this was filed: Ward is being archived this week, and the skill should carry an inventory of every orchestration pattern that o2r and Ward formalized rather than only the current harness surface.

That changes what this issue is. It was a convenience skill for tools nobody had documented. It is now the surviving record of two subsystems, and the deadline is the archival rather than the backlog.

Renamed to tooling-agent-orchestration. The original name scoped it to one harness, and the harness surface is now one of four references rather than the subject. Same tooling- prefix category, so the admission story is unchanged.

What landed in PR #1326

27 Ward patterns, read from coilyco-flight-deck/ward at 040f159. Admission and identity, state and recovery, authority, evidence, serialized mutation.
25 o2r patterns, read from coilyco-flight-deck/otel-a2a-relay at 8b96ed1, which was already archived. Sessions and identity, the channel coordination protocol, trust and admission, activity as traces.
The harness surface, mapped to which pattern each tool can carry.
What does not transfer, which is the reference most likely to be needed and least likely to be read.

Both source repositories are named with their exact revisions in the skill, so a later reader can check it rather than trust it.

The four estate rules from the original scope

All four survived into the skill unchanged: nothing here is durable, messaging carries no authority, it is one harness, and checkpoint discipline does not relax inside a subagent. The durability rule is now the opening line of the does-not-transfer reference rather than a footnote, because Ward's departure is exactly what makes it easy to get wrong.

Still open, separately

#1324 is unaffected. AGENTS.md:214 still declares that no agent-to-agent channel exists, and its ward#104 citation still does not resolve. That fix wants the answer to the citation question first.

## Scope widened, name changed, PR open Kai's direction after this was filed: **Ward is being archived this week**, and the skill should carry an inventory of every orchestration pattern that o2r and Ward formalized rather than only the current harness surface. That changes what this issue is. It was a convenience skill for tools nobody had documented. It is now the surviving record of two subsystems, and the deadline is the archival rather than the backlog. **Renamed to `tooling-agent-orchestration`.** The original name scoped it to one harness, and the harness surface is now one of four references rather than the subject. Same `tooling-` prefix category, so the admission story is unchanged. ## What landed in PR #1326 * **27 Ward patterns**, read from `coilyco-flight-deck/ward` at `040f159`. Admission and identity, state and recovery, authority, evidence, serialized mutation. * **25 o2r patterns**, read from `coilyco-flight-deck/otel-a2a-relay` at `8b96ed1`, which was already archived. Sessions and identity, the channel coordination protocol, trust and admission, activity as traces. * **The harness surface**, mapped to which pattern each tool can carry. * **What does not transfer**, which is the reference most likely to be needed and least likely to be read. Both source repositories are named with their exact revisions in the skill, so a later reader can check it rather than trust it. ## The four estate rules from the original scope All four survived into the skill unchanged: nothing here is durable, messaging carries no authority, it is one harness, and checkpoint discipline does not relax inside a subagent. The durability rule is now the opening line of the `does-not-transfer` reference rather than a footnote, because Ward's departure is exactly what makes it easy to get wrong. ## Still open, separately #1324 is unaffected. `AGENTS.md:214` still declares that no agent-to-agent channel exists, and its `ward#104` citation still does not resolve. That fix wants the answer to the citation question first.