foreman
CLAUDE.md1 starsChanged 12 days agoMITView on GitHub
This file stacks on top of the workspace root at C:\Code\GitHub\: - Root CLAUDE.md -- voice, rules, routing map, references, skills, slash commands, conventions. - Root MEMORY.md -- live facts across repos. - Root STATUS.md -- live PR/CI/security dashboard. - .claude/resources/ -- deep reference for collaboration, workflow, git, OSS, debugging, voice. Read those first. The guidance below only adds repo-specific context -- it does not override anything in the root. Claude Code plugin (foreman) that splits a task into subtasks,…
- Installs packages
The file
We split this CLAUDE.md into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 84
Every PR updates CHANGELOG.md under a concrete version and bumps both manifests when it releases.
- Very specific: line 85
No en or em dashes anywhere.
≈ “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.
Files
CLAUDE.md
This file stacks on top of the workspace root at
C:\Code\GitHub\:
- Root
CLAUDE.md-- voice, rules, routing map, references, skills, slash commands, conventions.- Root
MEMORY.md-- live facts across repos.- Root
STATUS.md-- live PR/CI/security dashboard..claude/resources/-- deep reference for collaboration, workflow, git, OSS, debugging, voice.Read those first. The guidance below only adds repo-specific context -- it does not override anything in the root.
Project
Claude Code plugin (foreman) that splits a task into subtasks, routes each to a predefined agent type and picks the model (haiku, sonnet, opus, fable) by the kind of work, then runs the subtasks in dependency waves and verifies once. A second skill scaffolds new agents and agent plugins and lints agent files. Public since 2026-11-11; the repo is its own plugin marketplace.
Install: /plugin marketplace add Sagargupta16/foreman then /plugin install foreman@foreman, or claude --plugin-dir . from a clone.
Stack
- Language: Python 3.12+ standard library (plan checker, scaffolder, repo gate)
- Framework: none at runtime; Markdown skills and agents, JSON routing and templates
- Package manager: none required;
pip install -r requirements-dev.txtfor ruff - Deploy target: GitHub repo as its own plugin marketplace (
.claude-plugin/marketplace.json,source: "./")
Run
python skills/dispatch/scripts/plan.py templates
python skills/dispatch/scripts/plan.py routes
python skills/dispatch/scripts/plan.py new feature --task "..."
python skills/dispatch/scripts/plan.py check examples/feature-plan.json
python skills/dispatch/scripts/plan.py workflow examples/feature-plan.json --out .scratch/feature.js
node tests/workflow_harness.mjs .scratch/feature.js build-api # run it against mocks; build-api fails once
python skills/dispatch/scripts/plan.py log plan-with-results.json --log .scratch/runs.jsonl
python skills/dispatch/scripts/plan.py stats --log .scratch/runs.jsonl
python skills/new-agent/scripts/scaffold.py agent NAME --kind review --dest .scratch/agents
python skills/new-agent/scripts/scaffold.py plugin NAME --dest .scratch/NAME --agent a:implement --skill
python skills/new-agent/scripts/scaffold.py lint agents
python scripts/how_it_works_svg.py # redraw the README figure in docs/how-it-works/Test
python scripts/check.py
python -m pytest -q
ruff check .
ruff format --check .
npx -y @sagargupta1610/skillcheck@0.2.5 lint skills
claude plugin validate .
claude plugin eval . --scaffold --allow-tools Bash Write Edit # real models, costs tokens, run on requestEntry points
skills/dispatch/SKILL.md-- the foreman procedure (/foreman:dispatch)skills/dispatch/routing.json-- kind to agent, model, effort, tool profile; the one source of truthskills/dispatch/templates/*.json-- task templatesskills/dispatch/scripts/plan.py-- plan checker (FM001-FM016), run log and stats with tune hints, plan-to-Workflow compilertests/workflow_harness.mjs-- runs a compiled Workflow offline against mockagent()/parallel(); pytest drives itskills/new-agent/SKILL.md-- agent and plugin scaffolding (/foreman:new-agent)skills/new-agent/scripts/scaffold.py-- agent, plugin, register, lint (FA001-FA010)agents/*.md-- the ten agent typeshooks/hooks.json,hooks/capture.py-- the optional SubagentStop hook that records agent runs (plugin optioncapture_runs, off by default)
Gotchas
- The capture hook was built against real payloads on Claude Code 2.1.322 (2026-11-12): SubagentStop carries
agent_type,agent_transcript_pathandeffort.level; the agent transcript writes one line per content block with the samemessage.idandusage, so usage is counted once per id; thetokensit stores equals thetotalTokensthe Agent tool reports. The subtask id comes fromagent-<id>.meta.jsonbeside the transcript (description,requestShape), a file seen on 2.1.322 and not documented, with the brief'sid:line as fallback: coordinators write free-form briefs, so the brief alone gave no id in a live run. Replay a saved payload to test it:CLAUDE_PLUGIN_OPTION_CAPTURE_RUNS=true FOREMAN_CAPTURE_LOG=<file> python hooks/capture.py < payload.json. In aclaude -p --plugin-dir .run, turn the option on with--settingsholding{"pluginConfigs": {"foreman@inline": {"options": {"capture_runs": true}}}}. ratesin routing.json are Anthropic list prices read on the date inrates.read. Re-read https://platform.claude.com/docs/en/about-claude/pricing before changing them, and bump the date.- The README figure (
docs/how-it-works/*.svg) is drawn from data written intoscripts/how_it_works_svg.py(SUBTASKS,TIMES, the lane agent lists). A change torouting.json, the agent roster orexamples/feature-plan.jsonneeds the same change there and a rerun; never hand-edit the SVGs. Check them with svg-forge'svalidate_svg.py --strict-contrast(one--themeper half) and look atframes.pysheets: 0 errors and 0 warnings on all four files on 2026-11-11. - An agent's
model,effortandtoolsmust equal its routing.json kind and profile;scripts/check.py(FC009) fails otherwise. Change routing.json and the agent file together. - Plugin agents ignore
permissionMode,hooks,mcpServersandinitialPrompt;claude plugin validatedoes not warn about them (measured 2.1.312),scaffold.py lintdoes (FA005). - The Agent tool's per-call
modelbeats the agent file'smodel; dispatch relies on that to route per subtask. claude plugin validate .warns that this CLAUDE.md is not loaded as plugin context. Expected: it is for repo sessions, not plugin users. It also prints a plugin directory warning for the missing icon (ICON_MISSING), so--strictfails on those two; the plain run passing with exactly those two warnings is the gate (2026-11-10).- Templates under
skills/new-agent/assets/usestring.Template(${name}); a literal$must be$$. - The Workflow script template lives in a Python string in plan.py (
WORKFLOW_JS):\\nthere becomes\nin JS. Workflow scripts may not callDate.now(),Math.random()or arglessnew Date()(a test checks it). - dispatch has
model: sonnetin its frontmatter: the coordinator turn runs on Sonnet whatever the session model is. That holds for one turn only, and subagents start in the background everywhere unless the call asks to wait (sub-agents docs, read 2026-11-11). Inclaude -pand the Agent SDK the Agent tool hasrun_in_background, and dispatch sets it tofalseso the wave returns in the same turn: a 0.3.0 run inclaude -p(2.1.322) left it unset, all three agents went to the background and the turns after the wave ran on Opus; the 0.3.1 run on the same version kept both waves in the foreground and every coordinator turn on Sonnet. Interactive terminal, VS Code and desktop sessions have no such parameter unlessCLAUDE_CODE_FORK_SUBAGENT=0, so there wave results arrive in later turns on the session's model. - Fable is the top of the ladder and the route for
solveonly (foreman:specialist).max_topin routing.json caps Fable subtasks per plan (FM015). Reruns go effort first (apartialbelow high reruns at high on the same model), then one tier up. - Live test runs (
claude -p --plugin-dir .) need the demo repo OUTSIDE this folder: files under a loaded plugin dir count as sensitive, so every agent edit there is denied in-pmode (2026-11-04). The 2026-11-04 run used a two-package demo repo atC:/Code/worktrees/foreman-demo(4 haiku subtasks, 4/4 verified, 0.92 USD, 0.90 of it the Opus main session). From the Desktop app,claude -phas to run in a terminal tab (Desktop-managed Bedrock credentials refuse a Bash child). With foreman also installed at user scope, pass--settingswith{"enabledPlugins": {"foreman@foreman": false}}so the--plugin-dircopy is the only one loaded (theinitevent lists it by path). A task of a few small edits is done inline with no agents; end the prompt with "Use subagents for the parts." to exercise a wave.
Repo-specific rules
- Written for public release: no personal names in skill or agent bodies ("the user"), no home paths. Author and owner fields are the exception.
- Skill frontmatter:
nameequals the folder,descriptionis a>-block with "Use when" triggers and no unquoted:. - Every PR updates CHANGELOG.md under a concrete version and bumps both manifests when it releases.
- No en or em dashes anywhere;
scripts/check.pyfails on them.
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
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.

