Skill: `drone` — create / evoke / list named units that mix code with scoped worker intelligence

[OriNachum]

The ask

A skill, drone, with three verbs:

/drone create <name>    # the cortex authors a named drone, saved for future runs
/drone evoke  <name>    # run it — cheap, no authoring cost
/drone list             # what exists, what each does, and which are stale

A drone does small-smart tasks — explore, review, search — as a mix of
code and minor intelligence: deterministic logic for structure, traversal and
bookkeeping, with scoped calls to the worker where judgement is genuinely
needed.

This is the worker-harness caste from
#44 made into something
an operator uses, rather than an arm in an experiment.

Why this shape, and not a subagent

A subagent already exists and already explores, reviews and searches. The
difference is where the cost goes:

	authoring	each use	concurrency	drifts?
subagent	none	a full mind's turns, every time	1 (cortex)	no — re-reasons each run
drone	one cortex turn, once	code + tens of tokens	~9 (worker)	yes — this is the risk

A subagent re-derives its approach on every invocation. A drone pays that
once and then runs. The trade is the honest one: you buy speed and
repeatability with staleness risk.

The break-even, stated before anyone builds it

Authoring costs one cortex turn — measured on this rig at 5,000–14,265
completion tokens and 400–730 s. So:

• a task done once → a drone is pure loss;
• a task done 2–3 times → roughly break-even;
• a task done often, on a stable surface → the drone wins by a widening
  margin, and by ~9× again if it can fan out.

A drone is worth creating when the task recurs and the surface is stable.
That belongs in the skill's own guidance, because the failure mode is not a
crash — it is quietly spending a cortex turn to save nothing.

What a drone is on disk

Persistence is the whole point of create versus just doing the task, so the
artifact needs to be legible, reviewable and diffable — not a pickle.

.drones/<name>/
  manifest.json    name, one-line description (what `list` prints), purpose,
                   author model + date + commit, the surface it assumes, the
                   questions it asks the worker and their schemas
  drone.py         the code the cortex wrote
  README.md        what it does, when it is wrong, how to re-author it

The one-line description is required at create time, not optional
metadata. A drone whose description is absent or vague is one nobody will pick
from list, which makes it dead weight that still cost a cortex turn to
author.

Committed, not hidden. A drone is model-written code that will run again on
someone else's checkout; it gets the same review a script would. This follows
the repo's existing cite-don't-import posture for vendored skills — the
artifact is readable where it is used.

list — and why it is not just a directory listing

Without it a drone is undiscoverable, and the cost of that is specific: you
re-author one that already exists, at a cortex turn each time. The whole
economics above assume reuse, and nothing gets reused that nobody can find.

$ /drone list

name              does                                          authored     status
────────────────────────────────────────────────────────────────────────────────────
import-graph      maps imports for a package, flags cycles       12d ago      ok
convention-check  reviews a diff against this repo's CLI rules   3d ago       ok
find-callers      finds every call site of a symbol, ranked      41d ago      STALE
                  └ assumed `embodiment/cli/_commands/` — moved

Three jobs, and only the first is obvious:

1. Discovery — name plus a one-line description of what it does, so the
   answer to "is there already a drone for this?" is one cheap command rather
   than an authoring turn.
2. Staleness, surfaced before it misleads. list runs each drone's
   assumed-surface check and shows the result. This is the natural home for it:
   you see a drone is stale when you are choosing one, not after it has run
   and reported confidently on a surface that moved. A stale drone should be
   visible without being executed.
3. Provenance — when it was authored, by which model, against which commit.
   A drone is model-written code that will run on someone else's checkout; who
   wrote it and when is part of reading its output honestly.

Per this repo's agent-first rubric, list takes --json (as would every verb),
results go to stdout and diagnostics to stderr, and the verb needs an
explain/catalog.py entry if it lands as a CLI noun rather than only a skill.

The three failure modes to design against

These are what the issue is really about; the verbs are easy.

1. Staleness — the drone that is confidently out of date

Code written against a codebase encodes assumptions that expire. A review
drone authored today may check a convention that changed next month, and it will
keep passing, authoritatively, on a check that no longer means anything.

This is the exact defect class this repo has spent a cycle on — a guard that
holds on the axis its author considered. corrections.md §3 is "tests that
passed while the thing they tested was broken."

Proposed mitigations, none free:

• manifest.json records the surface it assumed (paths, conventions,
  versions) and evoke re-checks those before running. A drone whose
  assumptions no longer hold refuses rather than reporting.
• Record the authoring date and the commit; surface both in every drone's
  output, so a reader can weigh it.
• /drone evoke <name> --reauthor when the check fails, rather than a silent
  best-effort run.

A drone that cannot detect its own obsolescence should not be shipped.

2. The scoped call that is not scoped

The whole efficiency claim rests on the worker being asked narrow typed
questions. Nothing stops an authoring cortex from writing a drone that asks the
worker "review this file" — at which point it is a slow subagent with extra
steps and a schema nobody validated.

So the manifest declares the questions and their answer schemas, and evoke
reports call-acceptance rate. #33
measured 17 of 23 worker calls refused on a shape error; a drone whose calls
are mostly refused would run to completion and report confidently on nothing.
Interface failure and task failure must never share a number.

3. It runs model-written code

create writes code and evoke executes it — arbitrarily, later, possibly by
someone who did not author it. This is the one part with a real blast radius.

Not embodiment's to invent: shell-cli owns the tool surface and the approval
policy, and this repo's C2 discipline is to state the threat model rather
than let a name imply a sandbox. Options, needing a decision rather than a
default:

• run in the network-less workspace jail challenge_coding.py already uses
  (strong, and awkward for a drone whose whole job is reading the repo);
• run in-process under the host's existing approval policy (weak, but honest and
  consistent with how skills already work);
• declare capabilities in the manifest and let the host enforce them.

I would not pick this in the issue. It is the one question that should be
answered before a line is written.

What create actually does

1. Take the name and the task description.
2. Explore the surface the task touches — this is the expensive part and the
   reason a drone is worth more than a script.
3. Decide the split: what compiles into code, what stays a scoped question.
4. Write drone.py, declare every worker question and schema in the manifest.
5. Prove it runs — a smoke invocation before it is saved. An unsaved failure
   is cheap; a saved broken drone is a trap.
6. Record the assumed surface for the staleness check.

Step 5 is not optional. K1's pin in this cycle built problems with
statement="" and grade=lambda _raw: {} and passed for an entire task while
the rung could not be dialled — well-shaped is not runnable, and a drone
saved without being run is exactly that failure with a friendlier name.

Open questions

1. Repo-scoped or user-scoped? .drones/ in the repo (shared, committed,
   reviewable) versus ~/.drones/ (personal, portable across repos). The
   explore/search cases argue repo; a review drone encoding personal
   standards argues user. Possibly both, with the eidetic scope/visibility
   convention as precedent.
2. Does evoke allow escalation? A drone that hits a case it cannot decide
   could return "I cannot" (clean, and the self-grading router
   #44 wants) or escalate
   to the cortex (useful, and reintroduces the cost it exists to avoid).
3. Should create be allowed to author a code-drone — pure code, zero
   worker calls — when the task turns out to need no judgement at all? That is
   the cheapest possible outcome and the skill should probably prefer it.
4. Is this a skill or a CLI verb? A skill is prompt-shaped and authoring is
   genuinely a prompt-shaped act; but evoke is mechanical and would be better
   as embodiment drone evoke <name> so a script or CI can call it without a
   mind in the loop.

Honest status

The design this implements has not been validated.
#44 proposes measuring
whether the harness tier beats a flat cortex, and that experiment has not run.
Building the skill first is a reasonable bet — it is useful even if the
architecture question resolves the other way, since a saved explore/search drone
pays for itself on repetition alone — but it should be built as opt-in and
off, consistent with the standing rule that a measured failure mode never
ships as default behaviour, and its unmeasured mirror image should not either.

• embodiment (Claude)

[OriNachum]

Closing result — the tier ships opt-in and off, and its economics claim is half measured, half failed

Cycle on PR #49. Details in
docs/live-test-results/drone-economics.md.

The verb surface

drone create / evoke / list, plus a drone overview. Every verb takes --json,
results to stdout and diagnostics to stderr, and explain/catalog.py covers the
surface so the agent-first rubric gate passes.

Safeguards, each asserted by test rather than intended:

• Smoke before save. create stages → smokes → saves. A drone that fails its smoke
  invocation is never written. This is not theoretical: the cortex's first authoring
  attempt was refused by that gate, because the authoring prompt stated the wrong return
  contract. A well-shaped artifact that has never executed is a trap with a friendly name.
• Opt-in and off. A fresh checkout with no explicit opt-in evokes nothing.
• Staleness refusal. list re-checks each drone's assumed surface; a drone whose
  assumptions no longer hold refuses rather than reports.
• A content-hashed audit trail. Every evocation — including refusals and failures —
  records name, drone source hash, capability set and call-acceptance.
• No escalation in v1. An undecidable case returns "I cannot" and the record shows
  the refusal.

The threat model is stated, not implied

evoke imports and runs model-written Python in-process, with no sandbox. Per this
repo's C2 constraint that is stated in the README, in explain drone, in drone overview and in every generated drone README — never left for a reader to infer
from the word "drone".

One correction landed there during the cycle: the generated README first said the audit
trail was "the containment story". It is not. It is what you get instead of
containment — traceability, not tamper-proofing. Git history and review are the
integrity boundary.

The economics claim: measured on both sides for the first time

	measured	target
cortex calls, second evocation	0	0	PASS
completion tokens, second evocation	1,532	≤ 239	FAIL
ratio of authoring cost	32.0%	≤ 5%	FAIL

Authoring: 4,785 completion tokens over 199.3 s, one cortex turn, streamed. Second
evocation: 3 scoped worker calls, all accepted, correct answer.

Zero cortex calls is structural, not lucky — a drone's only outward seam reaches the
worker the host wires and nothing else, and there is no escalation path in v1. That half
cannot fail without the design changing.

The token half fails for one identifiable reason: 511 completion tokens per scoped
call against ~15 for the same class of call with thinking off. WorkerSeam takes no
thinking/extra-body parameter, so nothing downstream can send chat_template_kwargs and
the mode is whatever the server defaults to. The first attempt made it maximally visible:
at max_tokens=256 the call spent all 256 tokens thinking and emitted no content —
issue #32's exact shape, reproduced in a second lane.

Why this is published as a failure rather than fixed

With thinking off the cost target clears comfortably — ≈45 tokens, 0.94%. That
arithmetic is a cost projection and nothing more. Disabling reasoning on a reasoning
model is a quality decision wearing a configuration flag, and the consequence is
unmeasured here: t8's "106 of 106 answered" measured that an answer came back in the
declared shape, not that it was right, and the width rung kept acceptance out of its
numerator on purpose. No measurement in this cycle graded correctness.

So meeting the number by removing the model's reasoning would be optimising the metric
rather than the outcome — the failure this repo has recorded under other names. The
honest remedy is to make the mode controllable and pinned, then measure cost and
quality at both settings on a task whose answers can be graded. Recorded as what is
owed; deliberately not done here, because fixing it changes the transport the width rung
was measured on.

The demonstration

.drones/index-gaps/ — authored by the cortex for a task this repo genuinely needed
twice: finding results documents missing from the index. On the measured run it found
3, correctly. 38 lines, stdlib only.

• embodiment (Claude)