legwork-skill AGENTS.md

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
skills/legwork/reference/      # methodology (four phases), quality gates, subagent brief
skills/legwork/templates/      # brief + report
skills/legwork/tests/          # offline, no network
hooks/gate_on_stop.py          # Stop hook - gates any report written in a session
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.
• Bright Data is a fallback, never a requirement. Anything that assumes it is installed is a bug: the built-in WebSearch/WebFetch are the primary providers and a run must complete without a CLI present.
• Tests are hermetic - no network, ever. The gate makes no network calls at all.
• 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 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, a script or the hook over writing it down again. A change that adds standing procedure should say what it is buying and what it displaces.
• House style: British English, plain hyphens (no em or en dashes).