legwork-skill: Instructions file for Claude Code

AGENTS.md

Guidance for AI agents (and people) working in this repository.

What this is

legwork - a decision-research skill for AI coding agents. It produces cited findings where every claim states how well it is supported, judges a source by whether it suits the claim it backs, and refuses to ship a finding it cannot support. It follows the Agent Skills layout (skills/<name>/SKILL.md) and ships as a Claude Code plugin.

Layout

.claude-plugin/plugin.json     # plugin manifest
skills/legwork/SKILL.md        # the skill (agent-facing instructions)
skills/legwork/scripts/        # python, standard library only
                              #   fetch.py     free direct page fetch, returns text
                              #   platforms.py ten free platform APIs, no key
                              #   search.py    many wordings across Google and Exa in one call
skills/legwork/reference/      # methodology (four phases), quality gates, subagent brief
skills/legwork/templates/      # brief + report
skills/legwork/tests/          # offline, no network
evals/                         # behaviour evals + the baseline protocol
install.sh / install-codex.sh  # local symlink installers (Claude / Codex)
docs/design-notes.md           # why the skill is shaped the way it is

Conventions

• Standard library only. No requirements.txt, no virtualenv. This is load-bearing: it is what lets the same paths work across Claude, Codex and plugin installs. CI asserts it, so an added third-party import fails the build rather than quietly breaking the install story.
• Python floor is 3.9. Every script carries from __future__ import annotations so PEP 604 syntax parses there.
• SKILL.md references scripts via ${CLAUDE_SKILL_DIR} (the skill's own directory), which Claude Code substitutes for personal, project and plugin installs alike. install.sh therefore symlinks the whole skill directory into ~/.claude/skills/ with no rewrite. install-codex.sh rewrites the variable, since Codex does not substitute it.
• TypeSafe's Jev is optional, like Bright Data: fetch.py --relevant does nothing without a key (TYPESAFE_API_KEY, or ~/.dbhq/legwork/typesafe-api-key - the DBHQ convention for skill credentials), a failed call never fails a fetch, and in search.py it only orders leads, all or nothing, and never drops one, and in fetch.py it is called only when --find missed - ranking every page would print more text than the whole-page reads it replaces.
• Every search provider is optional. search.py uses Bright Data and Exa when each is available and says which it skipped and why; with neither it exits 4 and the run searches with the built-in WebSearch/WebFetch, so a run still completes with no CLI and no keys. Anything that assumes a provider is installed or funded is a bug. Exa's key is EXA_API_KEY, or ~/.dbhq/legwork/exa-api-key.
• Tests are hermetic - no network, ever. The gate makes no network calls at all. fetch.py, platforms.py and bd_search.py do reach the network in production, so their tests patch urlopen and subprocess.run and assert the mapping - which flag becomes which CLI argument, which field becomes which column. A test that needs a socket is a test that will be skipped, and a skipped test is not a gate.
• A retrieval script and the fetch log are one pipeline. Every source kind platforms.py emits must be one sources.py log --kind accepts; _assert_vocabulary_agrees pins it. A kind only one of them knows fails at the far end of a long run, which is the worst place to find it.
• Corroboration must be counted on the layer the pipeline does not amplify. Gather deliberately fans out to find more sources per finding, so a source count measures our own effort. Independence groups reached from different search angles is the real signal. A change that makes corroboration rise with breadth has broken the check, whatever the tests say.
• The index is keyed on the folder, never the topic. Topics get reworded between runs; the folder is stamped once and never moves. Upserting on the folder is what makes a refresh update its row in place instead of leaving two rows competing to describe one report. For the same reason the index header is identified by position, not by a cell reading "Topic" - a run whose topic is worded like a column heading is still a run.
• A search snippet is not an opened page. A row logged via=websearch is a lead. Every other transport returns the page or the record itself, api included - a registry's own JSON is the record, not a snippet about it. The gate treats a citation resting only on snippet rows as unopened: ignored at quick, which is snippet-first by design, a warning at standard, an error at deep. Measured on a run filed on 2026-08-16, 18 of its 29 cited sources were search results nobody opened, and it passed.
• A blank matrix cell is never acceptable. [unknown] records that the question was asked and came back empty; a blank records nothing and reads as a confident "no". Table cells are not sentences, so no other layer of the gate can see inside them.
• The platform is not the party. party_of treats multi-tenant hosts as what they are: two orgs on one code host are two voices, three unrelated papers on one preprint server are three, and evidence read from disk is always one. A change that makes tenancy raise corroboration for sources found down a single angle has broken the check - test_party_tenancy.py pins both directions.
• A run that fails its gate is never filed. finish.py gates before it writes to the index, because the index is what a later session trusts instead of searching again. Filing a failed run launders a conclusion the evidence does not support.
• Prose is a cost, not a free win. The measured constraint on this skill is instruction density, not mechanism count: adherence collapses well before the number of rules legwork already carries, and the observed failure mode is an agent reporting compliance it did not achieve. Prefer moving a rule into the gate or a script over writing it down again. A change that adds standing procedure should say what it is buying and what it displaces.
• Each rule is stated once. SKILL.md holds the rule, in the order a run meets it; reference/methodology.md holds only the detail behind it and does not restate it; the templates and the subagent brief point at SKILL.md rather than paraphrasing it. A rule written in several places drifts: by September 2026 the answer-in-chat rule said three different things in four files, and a fix to the blocked-page ladder had reached two of the four places it was written. A change to a rule changes that one place, and a grep for the rule's key phrase should find it once.
• House style: British English, plain hyphens (no em or en dashes).