agentleFS
kchojnkchojn/claude-code-tradecraft/CLAUDE.md

claude-code-tradecraft

CLAUDE.md1 starsChanged 6 days agoMITView on GitHub

Prompt files for Claude Code, packaged as the tradecraft plugin (its own marketplace is claude-code-tradecraft). There is nothing to build, lint, or unit test. skills/<name>/SKILL.md are the slash commands, agents/*.md are subagent definitions, docs/ holds the sourced rules they are written against plus the flowcharts the README embeds, and prompts/ holds standalone prompts to paste into a session. The plugin does not load prompts/, and its files are exempt from the sourcing rule; prompts/README.md indexes them. Three layers, each checked…

  • Commits and pushes

The file

We split this CLAUDE.md into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Commit scopes are the skill names: feat(pr-review), fix(pr-review-watch), feat(lead), docs(readme).

    line 16
  2. Very specific:

    Every user-visible change adds a line under ## [Unreleased] in CHANGELOG.md.

    line 34

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

Prompt files for Claude Code, packaged as the tradecraft plugin (its own marketplace is claude-code-tradecraft). There is nothing to build, lint, or unit test. skills/<name>/SKILL.md are the slash commands, agents/*.md are subagent definitions, docs/ holds the sourced rules they are written against plus the flowcharts the README embeds, and prompts/ holds standalone prompts to paste into a session. The plugin does not load prompts/, and its files are exempt from the sourcing rule; prompts/README.md indexes them.

Working with the files

  • Install: /plugin install tradecraft --marketplace kchojn/claude-code-tradecraft. The installed plugin is a copy, so an edit here does nothing in an installed session. /tradecraft:pr-review-watch runs the installed plugin's /tradecraft:pr-review, not the one in the working tree.
  • Development loop: claude --plugin-dir /path/to/clone loads the working tree as the plugin.
  • The only test is a real run: /tradecraft:lead <task>, /tradecraft:pr-review <pr> (dry-run by default: prints findings and dropped candidates, touches nothing on GitHub), /tradecraft:pr-review-watch. Headless: claude -p "/tradecraft:pr-review <url>".
  • Watcher state lives in ~/.cache/pr-review-watch/ (the lock directory and one result file per PR head); clone roots in ~/.config/pr-review-watch/roots.
  • Frontmatter is the contract. Agents use name, description, model, effort, tools, disallowedTools, omitClaudeMd, maxTurns. Skills use description, argument-hint, disable-model-invocation. Unknown fields are ignored silently, so a typo turns a rule off with no warning. An agent description is a routing rule: open with "Use for" or "Use when".
  • Commit scopes are the skill names: feat(pr-review), fix(pr-review-watch), feat(lead), docs(readme). PRs land by squash merge, so the PR title is the commit.
  • ASCII only, no em dashes anywhere, including inside the prompts and the flowcharts.

How the pieces fit

Three layers, each checked against the one below it.

  1. agents/ fixes the roster and the model routing. scout (haiku) and qa-runner (haiku) never write or review code; implementer (sonnet) writes from a spec; reviewer (sonnet, high) finds or verifies defects read-only; deep-reasoner (opus) designs and debugs; oracle (fable) is a one-shot read-only decision call: a major design, a question deep-reasoner could not settle, or an escalation. Skills name agents and never pass model, except model: opus to retry a failed implementer phase; the frontmatter decides. scout, reviewer, and qa-runner set omitClaudeMd: true, so a brief must restate any rule they have to follow.
  2. skills/ are orchestrators that share one vocabulary. A brief is Goal, Inputs, Constraints, Permissions, Done when, Expected output. A report opens with DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED. A failed phase retries on the same or a stronger model, goes to oracle once after two failures or when deep-reasoner reaches no conclusion, then to Codex, called directly through the plugin's companion script, when a verdict stays disputed. Parallel briefs to one agent type open with identical text so they share a prompt cache. /tradecraft:pr-review adds a finder and verifier split (recall-biased finder, precision-biased verifier that must cite file:line), verdicts CONFIRMED | PLAUSIBLE | REFUTED, and keeps confidence (does the defect exist) apart from severity (does it block). /tradecraft:pr-review-watch is a scheduler only. It runs one claude -p "/tradecraft:pr-review <url> --publish" process per PR, because a subagent cannot spawn subagents, and it runs three at a time.
  3. docs/ holds the rules with their sources. orchestration-best-practices.md governs /tradecraft:lead and the agents; pr-review-research.md governs /tradecraft:pr-review and /tradecraft:pr-review-watch; lead-review.md maps each practice to the line in skills/lead/SKILL.md that implements it.

Changing a skill

  • Every rule traces to a cited source or a recorded run, or is listed as unmeasured in docs/pr-review-research.md section 17. Add the rule to the matching docs/ file with its source first, then change the command. A lesson from a real run goes in as a numbered section; pr-review-research.md sections 7 to 10, 15, and 16 show the shape.
  • A change to /tradecraft:lead means updating the table in docs/lead-review.md.
  • A change to a flow means editing docs/<name>-flow.html (hand-written HTML with an inline SVG) and re-exporting docs/<name>-flow.svg.
  • The Codex escalation sentence is duplicated in the lead and pr-review skills. Change it in both.
  • The README flow paragraphs restate rules from the skills. A rule change updates the README.
  • Every user-visible change adds a line under ## [Unreleased] in CHANGELOG.md.
  • /tradecraft:pr-review sections refer to each other by number. Keep the numbers stable or fix every reference.
  • /tradecraft:pr-review-watch must stay model-invocable: /loop fires a skill only without disable-model-invocation.

Releasing

A merge to main that leaves entries under ## [Unreleased] gets a release in the same session, without asking. A merge that adds no changelog entry gets none.

  1. Pick the version from the entries. ### Added or ### Changed bumps minor; ### Fixed alone bumps patch. Before 1.0 a breaking change (a renamed command, agent or state path) also bumps minor and its line says so.
  2. On a chore/release-vX.Y.Z branch: move the entries to ## [X.Y.Z] - YYYY-MM-DD, add its compare link at the foot of CHANGELOG.md and repoint the [Unreleased] link, and set version in .claude-plugin/plugin.json. Commit as chore(release): vX.Y.Z, open a PR, squash-merge it.
  3. Tag the squash commit vX.Y.Z (annotated) and push the tag. Create the GitHub release from the changelog section: gh release create vX.Y.Z --title vX.Y.Z --notes-file <section>.

The marketplace entry has no version, so /plugin update follows main; the tag and release serve readers and the changelog links.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.