feat(skills): build-with-agent-runtime — the canonical create→run→optimize→observe spine

[drewstone]

What

Adds build-with-agent-runtime — the spine skill that routes an agent through the full genome → run → optimize → observe seam on @tangle-network/agent-runtime. None of the existing four skills span the whole lifecycle as one seam; this is the entry the others point back to.

It is anchored on docs/canonical-api.md (merged in #283) as the verified source of truth, and carries no frozen API snippets — the barrel moves (./loops is a back-compat alias of ./runtime) and the agent-eval pin drifts, so freezing signatures guarantees rot. Instead it ships:

• a load order → docs/canonical-api.md (§2 decision table, §3 signatures, §4 recipe, §5/§6 the atom + two-substrate map) + grep src/runtime/index.ts (the live barrel) + bench/HARNESS.md, with "re-verify against source; code wins; fix the map the same turn."
• a decision table by altitude (define a genome → AgentProfile/AgentSurfaces; personify → definePersona; run → runPersonified/loopUntil/fanout; strategy → runAgentic/defineStrategy; benchmark → runBenchmark/ADAPTERS; optimize → improvementDriver/selfImprove; gate → defaultProductionGate/promotionGate; flywheel → runStrategyEvolution; observe → composeRuntimeHooks; ship → withTangleIntelligence). Each row cites one docs/canonical-api.md §, not a snippet.
• the do-NOT-reinvent guardrails for the exact traps (runConversation≈loopUntil, "skill optimizer"≈improvementDriver, "profile-seam"≈AgentProfile, new Sandbox-loop≈openSandboxRun, Promise.all-vote≈fanout, per-step tally≈createWaterfallCollector, own bootstrap≈pairedLift/promotionGate).
• the end-to-end recipe pointing at docs/canonical-api.md §4, the two-substrate when-which, and the one-line Intelligence-SDK hook (withTangleIntelligence(agent, { project, effort }), effort ∈ off|eco|standard|thorough|max).

Retargeted (not deleted — they hold load-bearing gotchas)

• agent-runtime-adoption — added a top pointer to the spine + docs/canonical-api.md; fixed stale API refs from the gen-6 consolidation (feat(runtime): gen-6 architecture consolidation — one recursive agent tree, observable + deep-cleaned #165): createRefineDriver/createFanoutVoteDriver (removed → refine/loopUntil, sample/fanout), createSandboxPlanner (removed → inject a TopologyPlanner into createDriver), loopCampaignDispatch (removed → loopDispatch). Verified each against src/runtime/index.ts. The fail-loud / {0,0}-cell / planner-envelope gotchas are preserved.
• loop-writer — added the same top pointer; fixed the one createFanoutVoteDriver table ref → fanout/sample.
• generate-eval — left untouched (narrow eval-task-authoring skill, no runtime API refs, not part of the spine).

Placement / symlink note (action needed in dotfiles, not this repo)

The skill is authored in agent-runtime/skills/ so it ships to npm consumers via package.json files: [..., "skills"]. For local-session use it also needs to be wired into the Claude/Codex skill dirs. I created the local symlink:

~/code/dotfiles/claude/skills/build-with-agent-runtime -> ~/code/agent-runtime/skills/build-with-agent-runtime

install.sh already auto-discovers any directory under dotfiles/claude/skills/*/ and re-links it into ~/.claude/skills/, ~/.codex/skills/, and (for the Pi subset) ~/.pi/agent/skills/ — so no install.sh edit is required; the symlink is enough. install.sh was not run (per instructions). To make this durable across machines, commit that symlink in the dotfiles repo (separate PR).

Verification

• Frontmatter description = 29 words (≤40), trigger-phrase-led, per _common.md.
• No ASCII boxes, no phase-numbering theatre, cites _common.md for shared rules, has a dispatch-at-end line.
• Branch merges clean into origin/main (git merge-tree). Only the 3 skill files are in this PR — unrelated in-flight working-tree changes in src//bench/ were left untouched.

[tangletools]

✅ Auto-approved PR — e0bc2701

Blanket team auto-approval is enabled for this reviewer service.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: blanket_auto_approve · 2026-06-14T00:58:03Z}

[tangletools]

🟡 Value Audit — sound-with-nits

Verdict	sound-with-nits
Concerns	4 (4 weak-concern)
Heuristic	0.0s
Duplication	0.0s
Interrogation	189.5s (2 bridge agents)
Total	189.5s

💰 Value — sound-with-nits

Adds a new canonical spine skill that routes agents through the full agent-runtime lifecycle and retargets two existing skills to remove stale gen-6 API names; coherent and useful, with minor doc-consistency nits.

• What it does: Commit e0bc270 adds skills/build-with-agent-runtime/SKILL.md, a new agent skill that serves as the single entry point for the genome→run→optimize→observe lifecycle on @tangle-network/agent-runtime. It gives a load order (docs/canonical-api.md → live barrel grep → bench/HARNESS.md), an altitude-based decision table that cites canonical-api sections, do-not-reinvent guardrails, an end-to-end recipe,
• Goals it achieves: The change aims to (a) give agents one canonical skill that spans the whole lifecycle instead of forcing them to choose among narrower skills, (b) stop repeated reinvention of loops, drivers, optimizers, and observation wrappers by pointing to canonical primitives, (c) keep the skill docs from rotting by anchoring them to docs/canonical-api.md and live source rather than frozen snippets, and (d) a
• Assessment: Good change, built in the grain of the codebase. Skills are the standard packaging for agent-facing guidance here; the new skill builds directly on docs/canonical-api.md and the live exports in src/runtime/index.ts (fanout, loopUntil, runAgentic, runBenchmark, promotionGate, runStrategyEvolution, etc., lines 102–260). Retargeting agent-runtime-adoption makes sense because it still holds deep, load
• Better / existing approach: none — this is the right approach. I searched skills/* and found no existing skill that already spans the full lifecycle. Consolidating the spine into agent-runtime-adoption would make that file too broad and would lose the specialized gotchas it now preserves; keeping a spine skill plus retargeted specialist skills is the clean architecture. docs/canonical-api.md already contains the decision tab

🎯 Usefulness — sound-with-nits

A coherent, useful spine skill that anchors the full genome→run→optimize→observe lifecycle on live source/docs; two small doc inaccuracies should be cleaned up before merge.

• Integration: The skill is packaged for distribution via package.json:90 ("files": ["dist", "README.md", "skills"]) and is already cross-referenced by the retargeted agent-runtime-adoption skill (skills/agent-runtime-adoption/SKILL.md:46). No runtime caller is expected for a documentation skill; it is consumed by name when installed into a skill directory, matching how the existing skills/ entries are treated
• Fit with existing patterns: It fits the codebase's grain. It anchors on docs/canonical-api.md rather than freezing snippets, and its decision table maps 1-to-1 to actual exports such as src/runtime/index.ts:102-260 (fanout/loopUntil/panel/verify/pipeline/runPersonified/definePersona), :182 (promotionGate), :206 (runBenchmark), :245 (defineStrategy/runAgentic), :277 (runStrategyEvolution), :369 (createWaterfallCollector), and
• Real-world viability: It will hold up under realistic use because it deliberately refuses to freeze API signatures and instructs readers to re-verify against the live barrels. The main risks are doc-level: (1) skills/build-with-agent-runtime/SKILL.md:140 references skills/_common.md, which does not exist, and (2) skills/loop-writer/SKILL.md:148-149 claims bench/src/observe-steer-workspace-loop.mts is deleted, but the f

💰 Value Audit

🟡 Dangling reference to skills/_common.md [maintenance] ``

skills/build-with-agent-runtime/SKILL.md:140 says 'See _common.md for shared conventions (frontmatter, fail-loud, no AI attribution)', but no skills/_common.md exists in this checkout (searched with Glob). This should be created or removed before merge so the skill does not point to a missing file.

🟡 canonical-api.md §7 still says Intelligence SDK is branch-only while the new skill says it is live [maintenance] ``

skills/build-with-agent-runtime/SKILL.md:73 and :124–129 claim withTangleIntelligence is live on main and that docs/canonical-api.md §7's 'branch-only' note is stale. However, docs/canonical-api.md:953–956 still states the Intelligence SDK ships on branch feat/intelligence-sdk-observe and is not on main. The skill's own rule at build-with-agent-runtime/SKILL.md:42–44 says source wins and the map should be fixed in the same turn; leaving canonical-api.md stale creates a self-contradiction in the

🎯 Usefulness Audit

🟡 Missing _common.md reference in new skill [ergonomics] ``

skills/build-with-agent-runtime/SKILL.md:140 says 'See _common.md for shared conventions (frontmatter, fail-loud, no AI attribution)', but no skills/_common.md exists in the repo. Either add the shared conventions file or remove the reference before merge.

🟡 loop-writer skill falsely claims a bench file is deleted [integration] ``

skills/loop-writer/SKILL.md:148-149 states that bench/src/observe-steer-workspace-loop.mts 'used mock executors and is deleted — the live proof is the only valid one', but bench/src/observe-steer-workspace-loop.mts:1 still exists and is a runnable local closed-loop proof. Update the prose or actually delete the file so users are not misled about which proof command is current.

---

What this audit checks

It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.

Pass	What it asks
Heuristic	Vague title? Whitespace-only or cruft-bearing diff? (content signals only)
Duplication	Do added function/class names already exist elsewhere in the repo?
Value Audit	What does it do? What goal does it achieve? Is it good? Better architecture or already-exists?
Usefulness Audit	Does it integrate and fit? Will it hold up in real use and actually get used?

Findings are concerns, not blocks — the human reviewer decides what to do with them.

_{value-audit · 20260614T010314Z}