feat(cli/agent-init): generated guidance must teach the Deno toolchain — 55 deno calls, 0 were deno doc/info/eval

[rickylabs]

Summary

netscript agent init generates agent guidance that teaches the NetScript surface but is nearly
silent on the Deno-native toolchain the runtime already ships. Wave 7 run 1 measured the
consequence: a frontier model made 55 deno invocations and zero of them were inspection
commands, then answered its "what is this package's public API?" questions by fetching raw source
over HTTP instead.

Deno now publishes a canonical agent primer at https://deno.com/agents.md, designed to be handed
to any coding agent ("Read deno.com/agents.md and set up Deno in this project"). The generated
AGENTS.md should reference it and teach the inspection verbs directly.

Evidence

Measured from the Wave 7 run 1 transcript (DeepSeek V4 Pro 0813, Claude Code, NetScript 0.0.6,
2h46m, product rickylabs/meridian-workflow-builder @ 3c185dc1):

Command	Invocations
deno task check	11
deno test	1
deno doc	0
deno info	0
deno eval	0
deno lint / deno fmt / deno outdated / deno add	0
total deno invocations	55

Against that: 40 curl fetches of raw package source from jsr.io across 6 packages, versus 15
greps of the installed offline corpus and 1 public-site fetch. deno doc answers precisely the
question those 40 curls were asking, and the framework's own contributor guidance says "deno doc
is your friend" — but nothing the agent is given at init says so.

Generated AGENTS.md in a fresh 0.0.6 scaffold mentions deno info once and never mentions
deno doc, deno eval, or deno.com/agents.md.

The same run also never ran deno task test (0 times) and shipped no failing-capable test.

Current surface

agent init writes root/app guidance, the offline docs corpus and MCP configuration. Its guidance is
NetScript-centric; the Deno layer beneath it is assumed rather than taught.

Target contract

Generated agent guidance should:

• link https://deno.com/agents.md as the canonical Deno primer, and state the one-line setup prompt;
• teach the inspection verbs before implementation: deno doc <module> and
  deno doc --filter <symbol> for a package's public surface, deno info for the graph,
  deno eval for a quick behavioural probe — explicitly as the alternative to reading source over
  HTTP;
• name the quality verbs the workspace already defines (deno task check, deno task test,
  deno lint, deno fmt) and state that a run is not finished until the test task has been run;
• point at the dependency verbs (deno outdated, deno why, deno add) rather than hand-edited
  imports.

Keep it short. This is a pointer surface, not a tutorial — the failure being fixed is discovery,
not depth.

Acceptance

• Generated AGENTS.md references deno.com/agents.md and the inspection verbs above
• A fresh scaffold's guidance names deno doc as the way to learn a package's public API
• Guidance states the test task must be run before a build is considered complete
• A measured unfamiliar-agent smoke shows non-zero deno doc usage, or an explicit recorded
  rejection — silence is a harness failure, not an agent failure
• No duplication of the netscript-deno-toolchain skill's content; the generated file links, the
  skill teaches

Boundaries

This is the generated consumer-facing guidance from agent init. It does not change the
repository's own AGENTS.md, the netscript-deno-toolchain skill, or the MCP corpus. Related but
distinct: #1201 (MCP serves generated export surfaces) — that makes the surface retrievable; this
makes an agent reach for it.

Provenance

Wave 7 run 1 (Arm C, NetScript 0.0.6 stable), evaluator pack at
agent-posts/wave-7/runs/workflow-builder-deepseek-v4-pro-0813-0.0.6/. Owner-directed 2026-08-17.

[rickylabs]

What the skill actually unlocks

Installed denoland/skills → deno (v1.0, MIT) and read it end to end. It is materially wider than
"deno doc exists", and several sections map onto failures this project has already paid for.

Directly answers run 1's largest waste

deno doc jsr:@std/path reads a package's public API from the terminal, by JSR specifier. Run 1
made 40 curl fetches of raw source from jsr.io across 6 packages to answer exactly that
question. One documented command replaces all forty.

Explains framework failures we previously mis-attributed

• Minimum dependency age. "Deno won't install a version published less than a day ago", override
  with --min-dep-age (minutes, ISO-8601 duration, cutoff date, or 0). Wave 6 pass 4 saw
  plugin doctor reject worker/saga contributions through minimum-dependency-age resolution and it
  was logged as a suspected doctor defect needing a controlled repro. This is the documented runtime
  behaviour behind it.
• Lifecycle scripts do not run by default — deno approve-scripts, deno install --allow-scripts=npm:<pkg>. The skill names this as "a common surprise when a native addon looks
  broken after install".
• node_modules uses pnpm's isolated layout (real files under node_modules/.deno/, exposed by
  symlinks, so a package cannot import what it never declared), with {"nodeModulesLinker":"hoisted"}
  as the escape hatch for tools that need a flat tree.

A ready-made review rubric

The skill ships a "Reviewing Deno code" checklist that is directly usable as gate criteria:

• -A committed in a task where a scoped grant would work;
• deno.lock uncommitted, or CI running deno install instead of deno ci (which requires the
  lockfile, deletes node_modules, installs strictly from it, and fails when it is stale);
• inline jsr:/npm: specifiers in a project that has a package.json — use deno add so the
  version lives in one place;
• a specifier with no version constraint;
• dependencies or compiler options in deno.json when package.json / tsconfig.json exist;
• missing deno fmt --check, deno lint, deno check in CI.

Configuration doctrine a scaffold should not contradict

File	Holds
package.json	dependencies, scripts
tsconfig.json	TypeScript compiler options
deno.json	Deno config: fmt, lint, tasks, workspaces

Worth checking our generated scaffold against, since it emits all three.

Inspection and dependency verbs beyond doc

deno why <pkg> (why it is in the tree) · deno list (declared + resolved) · deno audit
(vulnerabilities) · deno info (module graph) · deno eval (behavioural probe) ·
deno task --filter '*' <task> (across workspace members) · deno bump-version patch (workspace-wide).

Security note worth propagating

dx (= deno x, the npx equivalent) runs with the sandbox disabled — treat it with the same
care as npx. Our own guidance recommends dx-style invocations in places without saying this.

Consequence for this issue

Deno's agents.md says to skip installing if an equivalent skill is already present — and NetScript
does ship netscript-deno-toolchain. Run 1 still made 55 deno invocations with zero
inspection commands. So the gap this issue closes is not missing content, it is a missing
pointer at init time: the generated guidance must name the skill (or deno.com/agents.md) and the
inspection verbs, so the agent reaches for them before reading source over HTTP.

Two candidates for the acceptance list, if we agree they belong:

• generated guidance names deno ci (not deno install) as the CI install command;
• the scaffold's own config placement is checked against the table above.

[rickylabs]

Decision: complete netscript-deno-toolchain, do not add a second skill

Owner direction 2026-08-17. Deno's own agents.md says to skip installing its skill when an
equivalent is already present, and ours is. Diffed the two.

Already covered well by .agents/skills/netscript-deno-toolchain (12.5 KB): deno doc (6
mentions), info, why, audit, ci, bump-version, publish, workspaces. No duplication needed.

Genuine gaps worth adding

Gap	Why it matters here
--minimum-dependency-age	Deno refuses any dependency published in the last ~24h. On a canary-first release workflow this bites on the day a version ships. The repo already works around it in the Quickstart and in init-agent.ts:315 — but the skill never mentions it, so an agent hitting the failure has no way to understand it. This is also the most likely explanation for the Wave 6 pass-4 plugin doctor rejection that was logged as a suspected defect awaiting a controlled repro.
deno approve-scripts / --allow-scripts	npm lifecycle scripts do not run by default; the documented symptom is "a native addon looks broken after install".
nodeModulesLinker: "hoisted"	Deno uses pnpm's isolated layout (real files in node_modules/.deno/, symlink-exposed, so a package cannot import what it never declared). Our scaffold emits node_modules; tools expecting a flat tree need the escape hatch.
Permission granularity	-S is --allow-sys, not --allow-run; every flag takes an allowlist (--allow-net=example.com:443); --deny-* always wins. Agents guess these constantly.
dx runs with the sandbox disabled	It is deno x / npx-equivalent. Security-relevant and currently unstated.
deno eval	The cheapest behavioural probe; run 1 used it 0 times while curling raw source 40 times.
deno list · deno bench · deno compile · deno init --lib · deno create	Completeness; low priority.

Net effect on this issue

Two deliverables, not one:

1. Complete netscript-deno-toolchain with the rows above — it stays the single canonical home.
2. agent init generated guidance points at it, plus deno.com/agents.md, and names the
   inspection verbs before implementation. That is the actual fix for the measured failure: run 1 had
   the skill available and still made 55 deno invocations with zero inspection commands.

Nothing is duplicated: the skill teaches, the generated file points.