feat(skills): codemode — convert ideas and loose context into agent graphs

[drewstone]

Why

The graph layer shipped in 0.123.0 with zero consumers outside its own tests and examples — flagged in this week's drift audit as the classic speculative-abstraction profile. This skill is the adoption surface: give it to any agent (org skill dirs, or inline via profile.resources.skills — verified capless) and it becomes competent at turning an idea plus loose context into a runnable, auditable graph.

What the skill teaches

• Dialect routing first: static runGraph graph vs dynamic-workflows script vs no orchestration — with the measured basis (harness root ~11× router; live loop-vs-graph parity is still offline-only per feat(examples): P1 graph-vs-loop parity harness — offline-proven, live-ready wiring #710's own caveats).
• The contract compressed: P0 topology, profile-name-is-identity, versioned directives, deliverable-as-mission, one conserved pool.
• Budget from floors: perWorker defaults to pool/4; under the 31,211 pi floor that refuses every spawn — the five-of-six-below-floor live history is the citation.
• Evidence discipline: ledger outcomes, exhaustedEdges always (the error only throws on non-lifecycle no-winners), tokensKnown/usdKnown never read as zero.
• Eight potholes, each proven from source or live runs this week, with the preventing rule.

Self-improvement (IMPROVE.md + cases/)

The skill text is the optimizable surface, and everything needed already exists in agent-eval: skillOptOptimizationMethod literally requires a string surface; runImprovementLoop gates promotion on an enforced-disjoint holdout with autoOnPromote: 'pr'; deterministic scoring is a JudgeConfig closure over GraphResult.ledger + deliverable verdicts; ensembleJudge covers only what mechanics can't see. The loop owns exactly two closures and eight seeded cases (loose briefs on purpose — loose-context-in is the claim under test; three held out).

Found while auditing, filed separately

analyzes.over naming the root validates cleanly but can never fire (the root never settles as a worker) — silent-zero surface; issue to follow proposing validateGraph refuse it.

Docs-only PR: no src changes, no version bump required (verified against the check-version-bump gate's surface definition).

[tangletools]

✅ Auto-approved drewstone PR — e48794a7

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: drewstone_author · 2026-08-03T07:08:30Z}

[tangletools]

❌ Needs Work — e48794a7

Review health 100/100 · Reviewer score 41/100 · Confidence 65/100 · 15 findings (1 critical, 1 high, 5 medium, 8 low)

	glm	deepseek	deepseek-flash	aggregate
Readiness	41	69	41	41
Confidence	65	65	65	65
Correctness	41	69	41	41
Security	41	69	41	41
Testing	41	69	41	41
Architecture	41	69	41	41

Reviewer score is advisory once the run is complete and the verdict has no blockers.

Full multi-shot audit completed 1/1 planned shots over 10 changed files. Global verifier still owns final merge decision. | Full multi-shot audit completed 1/1 planned shots over 10 changed files. Global verifier still owns final merge decision. | Full multi-shot audit completed 1/1 planned shots over 10 changed files. Global verifier still owns final merge decision.

Blocking

🟣 CRITICAL SKILL.md description is 209 chars; repo gate enforces 96 — check:skills fails, verify:package fails, ci.yml:65 blocks merge — skills/codemode/SKILL.md

Frontmatter reads: description: "Convert an idea, workflow, or loose context into a runnable agent graph. Use for: author a graph, runGraph, orchestrate agents as code, turn this workflow into agents, multi-agent pipeline with an audit trail." — 209 chars. scripts/check-skills.mjs:8 sets maxDescriptionChars=96 and :60 errors above it. I ran node scripts/check-skills.mjs at HEAD: output codemode: description has 209 chars; max is 96, exit 1. With skills/codemode removed: skills valid: 368 description chars, exit 0. check:skills is in verify:package (package.json:138), which .github/workflows/ci.yml:65 runs on every PR. This is a verified, certain CI failure, not a style nit. Fix: cut to a single ≤96-char sentence matching the sibling-skill pattern (supervise=89, loop-writer=94, gene

🔴 HIGH SKILL.md description exceeds repo skill-check max; breaks CI verify:package — skills/codemode/SKILL.md

Frontmatter description is 209 chars. node scripts/check-skills.mjs (default root = repo skills/) prints 'codemode: description has 209 chars; max is 96' and exits 1 (verified: pnpm run check:skills exit 1). CI runs pnpm run verify:package (ci.yml:65) which chains pnpm run check:skills (package.json:138). This PR newly breaks the gate — the check passes for every other existing skill. Fix: trim the description to <=96 chars (the 'Use for:' keyword list is the excess).

Other

🟠 MEDIUM Broken reference: gepa-optimization-method doesn't exist — skills/codemode/IMPROVE.md

IMPROVE.md line 20 references gepa-optimization-method (kebab-case file) as an alternative to skillOptOptimizationMethod. The actual export is gepaOptimizationMethod (camelCase) defined in src/improvement/official-optimizers.ts:5 and imported at tests/profile-improvement-stack.test.ts:3. The kebab-case reference will not resolve for anyone trying to follow the IMPROVE.md instructions.

🟠 MEDIUM Broken reference: reflective-mutation.ts doesn't exist — skills/codemode/IMPROVE.md

IMPROVE.md line 20 references reflective-mutation.ts for trace-conditioned diffs. This file does not exist anywhere in the repo (glob search returns zero matches). Either the filename is wrong, or it describes a module not yet built. The rest of IMPROVE.md claims 'every step names the existing agent-eval primitive' — this one breaks that claim.

🟠 MEDIUM IMPROVE.md overclaims the case schema: only 3/8 cases carry floorTrap, 1/8 has edges, 0/8 have ledger outcomes — skills/codemode/IMPROVE.md

IMPROVE.md:27 states: 'cases/ seeds eight idea-briefs, each with expect: the edges a correct graph must have, ledger outcomes, whether analysts are warranted, and a floor-trap flag'. Reality, verified by grepping every case file: floorTrap appears only in review-pipeline.json(false), floor-trap-pi.json(true), unmeasured-harness.json(false) — 3/8. edges appears only in review-pipeline.json — 1/8. No case file carries concrete ledger-outcome values — 0/8. analyzesWarranted appears in 2/8. Impact: closure B in IMPROVE.md:18 ('score from GraphResult ... expected edges present with >0 traversals; ledger outcomes match the case's expectations') is specified against fields that don't exist in 5-7 of the 8 cases, so the deterministic scorer cannot be implemented as documented. Eval-valid

🟠 MEDIUM IMPROVE.md references agent-eval primitives by names that do not resolve — skills/codemode/IMPROVE.md

IMPROVE.md's contract is 'every step names the existing agent-eval primitive it composes', but several names are dead: (a) gepa-optimization-method — the exported symbol is gepaOptimizationMethod (imported at src/improvement/official-optimizers.ts:5); kebab-case never resolves in TS. (b) reflective-mutation.ts — no such file/symbol in repo or the generated API catalog (docs/api/primitive-catalog.md); the package's closest symbol is reflectiveGenerator. (c) autoOnPromote: 'pr' — no such option anywhere; catalog documents runImprovementLoop as 'optionally opens a PR' with an OpenAutoPrOptions type. (d) golden-matcher / completion-verifier — not present in the published API catalog. A future agent walking IMPROVE.md will fail at these. Fix: rename to the real symbols or cite t

🟠 MEDIUM MutableSurface citation is wrong module and likely wrong shape — skills/codemode/IMPROVE.md

Row claims MutableSurface = string at campaign/types.ts:210. In-repo, MutableSurface is imported from @tangle-network/agent-eval/contract (src/improvement/improve-types.ts:10-15), not campaign, and the API catalog describes it as tiered ('The mutable surface a proposer changes. Tiers...' with a tier-4 CodeSurface), not a plain string alias. If the type is a tagged union, 'read SKILL.md → string' is not a valid surface without wrapping, which undermines the row's 'skill text is first-class' premise. Fix: verify against the pinned agent-eval version and cite the real module/type, or soften to 'a string surface tier'.

🟡 LOW External package file paths written as if local — skills/codemode/IMPROVE.md

IMPROVE.md line 15 references campaign/types.ts:210 and line 19 references judge-panel.ts ensembleJudge. Neither file exists in this repo — they're in the external @tangle-network/agent-eval package. A reader in this repo will not find them. While cross-package references are acceptable in docs, they should be qualified with the package name to avoid dead-end searches.

🟡 LOW IMPROVE.md cites external file:line references that cannot be verified in-repo and will go stale — skills/codemode/IMPROVE.md

IMPROVE.md:15 pins MutableSurface = string to campaign/types.ts:210, and :19/:20/:23 reference judge-panel.ts, reflective-mutation.ts, search-ledger.ts as filenames. These are internal files of the external @tangle-network/agent-eval package (catalog dep, package.json:149), not present in this repo (no node_modules in worktree; repo grep finds MutableSurface only as an import, never defined locally; SearchLedger* classes exist only in docs/api/primitive-catalog.md). The exported symbols (MutableSurface, ensembleJudge, skillOptOptimizationMethod, SearchLedgerError) are all real and verified-usable, but pinning source filenames + line numbers inside another package is the textbook stale-reference pattern. Fix: cite the exported symbol name and its import path (`@tangle-networ

🟡 LOW 'Measured: ~11x a plain router loop' has no in-repo measurement — skills/codemode/SKILL.md

The dialect-table row asserts a measured cost ratio for a harness-driven root vs a plain router loop, but a repo-wide search (docs/, bench/, examples/, src/) finds only this sentence — no backing run or bench reference. 'Measured:' is a load-bearing provenance claim; without a cited run it should be softened or linked to the bench artifact.

🟡 LOW SKILL.md steers to a non-existent peer skill: dynamic-workflows (supervisor-lab) — skills/codemode/SKILL.md

Line 17 routes runtime-discovered topologies to 'the dynamic-workflows skill', and the 'Then consider' footer (line 94) repeats 'dynamic-workflows (supervisor-lab)'. Verified absent: there is no skills/dynamic-workflows/ in this repo, no SKILL.md named dynamic-workflows anywhere (find returns nothing), and docs/research/simplification-plan.md:173 explicitly states 'Decomposition + scoping skills don't exist in supervisor-lab (it has only authoring-agent-profiles)'. So both named peers are either external-and-unverifiable (authoring-agent-

🟡 LOW SKILL.md:18 asserts 'Measured: ~11×' cost ratio with no source anywhere in the repo — skills/codemode/SKILL.md

The dialect table's 'No orchestration at all' row says: 'Measured: a harness-driven root costs ~11× a plain router loop; composition must earn that'. A grep for '11x', '11×', 'router loop', 'harness-driven root' across all .md/.ts returns exactly one match — the claim itself. Unlike every other numeric claim in the skill (31211 floor, 5-of-6, 32 cap, quarter pool), this one has no grounding comment in code (compare src/runtime/supervise/budget-floor.ts:9-13 and src/mcp/tools/coordination.ts:43). The AGENTS.md Claim gate and the skill's own 'Read the evidence, or you shipped nothing' section both forbid exactly this: a load-bearing number with no check. Fix: either cite the measurement file/run (as budget-floor.ts does) or soften to 'composition must earn its cost — a harness-driven root re

🟡 LOW Missing trailing newlines in all 8 case JSON files — skills/codemode/cases/cap-as-stop-mistake.json

All 8 JSON case files under skills/codemode/cases/ end with } on the last line without a trailing newline. POSIX requires a trailing newline on text files; git will show \ No newline at end of file diffs and some JSON tools may warn. Applies to: cap-as-stop-mistake.json, floor-trap-pi.json, mission-in-deliverable.json, review-pipeline.json, runtime-discovered-fanout.json, single-agent-suffices.json, steer-heavy-drafting.json, unmeasured-harness.json.

🟡 LOW floor-trap-pi and single-agent-suffices are not cleanly discriminated by the skill text — skills/codemode/cases/floor-trap-pi.json

floor-trap-pi's brief ('have a pi agent write a one-line file') expects nodes: 1, while single-agent-suffices ('Summarize this document into five bullets') expects correctAnswerIsNoGraph. The skill's own dialect row says 'If one agent could produce bytes that pass it, you do not need a graph' (SKILL.md:20), so a correct author following the skill could legitimately answer 'no graph' for the one-line-file brief too — the only discriminator is the user's explicit 'have a pi agent' phrasing. A deterministic scorer keyed on nodes: 1 would grade that correct no-graph answer wrong, injecting noise into the improvement loop. Also note mustBudgetAtLeast 31211 matches the floor exactly while SKILL.md:41 recommends pi workers get >=60k (floor + headroom), so a 32k budget passes the case but vi

🟡 LOW Case JSONs have no trailing newline and no schema/validation test — skills/codemode/cases/review-pipeline.json

All 8 case files end with '\ No newline at end of file' (diff confirms) and their ad-hoc expect keys (nodes, floorTrap, mustBudgetAtLeast, correctAnswerIsDynamicWorkflow, wrongIfAnalystIsNode, ...) have no consumer in this PR and no test pinning them against the skill contract. The improvement-loop judge ('closure B') is deliberately caller-owned, so the shapes are unverified seed data; a small test asserting the case JSON schema (all 8 parse, keys well-formed, floor-trap number >= WORKER_TOKEN_FLOOR.pi) would harden the loop. Trivial fix: add trailing newlines.

---

_{tangletools · 2026-08-03T07:15:50Z · trace}

[tangletools]

❌ 2 Blocking Findings — e48794a7

Full multi-shot audit completed 1/1 planned shots over 10 changed files. Global verifier still owns final merge decision. | Full multi-shot audit completed 1/1 planned shots over 10 changed files. Global verifier still owns final merge decision. | Full multi-shot audit completed 1/1 planned shots over 10 changed files. Global verifier still owns final merge decision.

Full immutable report for this review: trace

Summary comment for this run: full summary

---

_{tangletools · 2026-08-03T07:15:50Z · immutable trace}

[tangletools]

🟢 Value Audit — sound

Verdict	sound
Concerns	1 (1 weak-concern)
Heuristic	0.0s
Duplication	0.0s
Interrogation	416.6s (2 bridge agents)
Total	416.6s

💰 Value — sound

Adds a teaching skill (SKILL.md + IMPROVE.md + 8 eval cases) that makes any agent competent at authoring agent graphs via the already-shipped but zero-consumer runGraph API — coherent, source-grounded, in-grain, no duplication found.

• What it does: Adds skills/codemode/: a 95-line SKILL.md that teaches the full graph-authoring contract (nodes/edges/deliverable/budget), dialect routing (static runGraph vs dynamic-workflows vs no orchestration), measured budget floors, evidence-discipline reads, and 8 proven potholes; plus IMPROVE.md mapping skill self-improvement onto existing agent-eval machinery; plus 8 seeded eval cases (loose briefs
• Goals it achieves: Create an adoption surface for the graph layer shipped in 0.123.0, which has zero consumers outside its own tests/examples (verified: docs/canonical-api.md has zero runGraph/graph mentions; only examples/graphs/ + generated API docs reference it). The skill is injectable into any agent via profile.resources.skills, turning intent+loose-context into a runnable, ledger-audited graph. Seconda
• Assessment: Sound and well-grounded. Every load-bearing claim checks out against source: WORKER_TOKEN_FLOOR.pi = 31_211 (budget-floor.ts:29); perWorker defaults to pool/4 (supervise.ts:1007-1012,1258); profile.name === node.id identity (graph.ts:265-271); GraphEdgeCapError throws only on no-winner non-lifecycle while exhaustedEdges stays observable (graph.ts:201-213); default traversal cap 32 (graph
• Better / existing approach: none — this is the right approach. Searched for an existing equivalent before answering: (1) no existing skill covers graph authoring — checked all 5 skills (build-with-agent-runtime's decision table maps needs to supervise/fanout/pipeline but has no runGraph row; loop-writer is the escape-hatch for when composition APIs can't express something; supervise is the runtime driver policy); (2) docs/ca
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 2
• Bridge warning: opencode/kimi-for-coding/k2p7: opencode: opencode error

🎯 Usefulness — sound

A densely source-grounded skill that becomes the adoption surface for the under-consumed 0.123.0 graph layer, filling a real gap no existing skill covers.

• Integration: Reachable two ways: as an org skill via the <name>/SKILL.md skill-dir convention probed at src/agent/surfaces.ts:157 (identical layout to the four sibling skills build-with-agent-runtime/loop-writer/supervise/generate-eval), and inline via profile.resources.skills (capless resource list, referenced across src/candidate-execution/profile.ts:291 and src/improvement/profile-surface.ts:229). Every
• Fit with existing patterns: Fills a genuine gap rather than competing. build-with-agent-runtime is the closest sibling but its entry-point table (skills/build-with-agent-runtime/SKILL.md:31-49) lists supervise/fanout/pipeline/panel/verify and omits runGraph/graph authoring entirely; its concern is 'don't duplicate infrastructure,' not 'how to author a graph.' The skill matches the repo's stated architecture (docs/research/si
• Real-world viability: Content is grounded in measured source, not invented. The 31,211 pi floor (src/runtime/supervise/budget-floor.ts:29), the below-floor child-budget history (docstring lines 9-13), the analyzes-over-root 'validates but never fires' behavior (src/runtime/supervise/graph.ts:264), and the 'only delegates caps refuse spawns' rule (graph.ts:205-211) are all verified in source. The 8 cases cover every doc
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 1

💰 Value Audit

🟡 Name 'codemode' collides with a historically-removed anti-pattern in this repo's active guardrail [maintenance] ``

docs/research/loop-facade-postmortem.md:82-97 records that an authorLoop "codemode" CODE seam was built in 0.88.0 and REMOVED in 0.89.0 for renaming existing substrate concepts and demoing only with fake agents — it is flagged as an active guardrail against speculative orchestration facades. This PR's 'codemode' is categorically different (a teaching SKILL over the already-shipped runGraph API, not a code wrapper; it adds no primitive and routes away from orchestration when unwarranted), so it

---

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 · 20260803T071640Z}