(MOT-4221) harness: mechanics reference skill

[rohitg00]

What

A harness/reference skill (skills/reference.md): the mechanics reference for the harness, complementing the conduct playbooks in #558. It documents:

• The turn lifecycle: send (merge/queue behavior, message-queued, idempotency dedupe), context assembly (mode paragraph, identity precedence, system_prompt_strategy, pre-generate hook mutations), generation and dispatch (fail-closed function policy, pre/post-trigger hooks), the durable loop (queued harness::turn steps, transient resumes, validation retries), parking and function::resolve, terminal statuses.
• The full function surface: public (send, spawn, status, stop), trigger-target (react), and every internal id with what it does.
• Published trigger types: turn-started, turn-completed (payload fields including the terminal: false armed-wake continuation semantics), message-queued, and the five hook points with chain order, timeouts, and on_error defaults.
• How a session registers triggers and what fires back: the three reaction forms (plain notify wakes the registering agent; react-spawn with the session_id delivery-back semantics; react-call with the discarded-result caveat), joins, once defaults, and the built-in loop breakers.
• The sub-agent lifecycle: fire-and-forget spawn, session naming and the resume trap, policy inheritance (subset-only, parentless read-only baseline), the embedded child identity and its system_prompt escape hatch, [child-failure] delivery, stop cascade.

Every fact is source-verified against current main: functions/mod.rs (ids, descriptions), types/turn.rs (statuses), events.rs (event payloads, binding configs, deny_unknown_fields), hooks/mod.rs (chain semantics, failure policies), subagent.rs (identity, policy subset).

Why

The playbooks say what an agent SHOULD do; nothing said what the machine DOES. Questions like "how do I attach a trigger to a session", "what exactly fires when a turn ends", and "what does a spawned child inherit" had no single answer short of reading five source files. This is that answer, served through the same directory::skills::get surface as every other worker doc.

Scope

One new file, no code changes, no overlap with #558's files, so the two merge in any order. Follow-ups after both land: pin this doc's invariants in prompt/tests.rs and add the overview pointer in skills/SKILL.md.

Linear

Closes MOT-4221. Part of MOT-4157.

Added after review

Two further sections: the dependency mesh (exactly which session-manager, context-manager, llm-router, queue, and state functions the harness calls per turn, verified by grepping the client modules; plus the optional policy siblings that extend a turn via hooks) and the discovery-and-lifecycle surface (engine catalog functions, worker-manager lifecycle ops with the yes:true convention, the directory worker as the docs-and-registry layer, and the composed find-judge-install-verify-call flow).

Reworked to the no-duplication norm

Skills must not restate the API reference; per-function prose belongs in function metadata and surface questions get the API link (https://workers.iii.dev/workers/harness.md). This doc now carries only what schemas cannot express: the turn lifecycle, event delivery semantics (including terminal: false), the three reaction forms and their session_id delivery rules, joins and loop breakers, the sub-agent lifecycle, and a slimmed dependency-mesh section describing roles instead of enumerating sibling function ids. The function-surface catalog and the discovery/worker-lifecycle walkthrough were removed.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
workers	Ready	Preview, Comment	Jul 24, 2026 3:02pm
workers-tech-spec	Ready	Preview, Comment	Jul 24, 2026 3:02pm

[coderabbitai]

Warning

Review limit reached

@rohitg00, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 48 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: cacb4dc7-5ef2-47fd-91a3-8c0298ea3b73

📥 Commits

Reviewing files that changed from the base of the PR and between d3c2e19 and 62a6e3f.

📒 Files selected for processing (1)

• harness/skills/reference.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch harness-reference-skill

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

skill-check — worker

0 verified, 48 skipped (no docs/).

Layer	Result
structure	✓
vale	✓
ai	✓
render	✓

Four for four. Nicely done.