🏭 foundry — Claude Code Plugin¶
OSS Claude Code config: 10 specialist agents, 11 skills, event-driven hooks, self-improvement loop for professional AI-assisted development.
OSS workflows: also install
ossplugin (/oss:review,/oss:release, ...). Development: installdevelop(/develop:feature,/develop:fix, ...). ML research: installresearch(/research:run,/research:topic, ...).
📋 Contents
- [What is foundry?](#what-is-foundry) - [Why foundry?](#why-foundry) - [Install](#install) - [Quick start](#quick-start) - [Skills reference](#skills-reference) - [`/foundry:setup`](#foundrysetup) - [`/foundry:audit`](#foundryaudit) - [`/foundry:calibrate`](#foundrycalibrate) - [`/foundry:manage`](#foundrymanage) - [`/foundry:brainstorm`](#foundrybrainstorm) - [`/foundry:investigate`](#foundryinvestigate) - [`/foundry:profile`](#foundryprofile) - [`/foundry:distill`](#foundrydistill) - [`/foundry:session`](#foundrysession) - [`/foundry:create`](#foundrycreate) - [`/foundry:humanizer`](#foundryhumanizer) - [Agents reference](#agents-reference) - [foundry:sw-engineer](#foundrysw-engineer) - [foundry:solution-architect](#foundrysolution-architect) - [foundry:qa-specialist](#foundryqa-specialist) - [foundry:linting-expert](#foundrylinting-expert) - [foundry:perf-optimizer](#foundryperf-optimizer) - [foundry:doc-scribe](#foundrydoc-scribe) - [foundry:web-explorer](#foundryweb-explorer) - [foundry:curator](#foundrycurator) - [foundry:challenger](#foundrychallenger) - [foundry:creator](#foundrycreator) - [Agent relationships](#agent-relationships) - [Rules installed](#rules-installed) - [Configuration](#configuration) - [Troubleshooting](#troubleshooting) - [Plugin structure](#plugin-structure) - [Upgrade](#upgrade) - [Uninstall](#uninstall) - [Development / testing](#development--testing) - [Contributing / feedback](#contributing--feedback)🤔 What is foundry?¶
foundry = base infrastructure plugin for Claude Code on Python/ML OSS projects. Gives Claude Code team of ten non-overlapping specialist agents — deep, calibrated domain knowledge each — plus skills for lifecycle management, accuracy benchmarking, feeding corrections back into instructions.
Without foundry: Claude Code = generalist. Helps with code but no release conventions, no routing enforcement to right specialist, no mechanism to measure or improve own accuracy over time. foundry packages all that infrastructure in one installable plugin.
🎯 Why foundry?¶
Without: one model handles architecture, implementation, docs, linting, testing, performance — no boundary enforcement. Corrections evaporate per session. No way to know if agent accuracy drifted.
With:
/foundry:auditcatches config drift before it becomes debugging session/foundry:calibratemeasures recall vs stated confidence — know exactly where agents fall short/foundry:managecreates, renames, deletes agents with full cross-reference propagation, one command/foundry:brainstormturns vague idea into approved spec before any code written/foundry:distillconverts accumulated corrections into durable rules + agent instruction updates- Hooks keep lint, task tracking, teammate quality gates running on every file save
Self-improvement loop — /foundry:audit catches structural drift; /foundry:calibrate catches behavioral drift; /foundry:distill surfaces patterns from corrections — closes feedback loop automatically.
📦 Install¶
Prerequisites: Claude Code with plugin support; jq on PATH; node on PATH (hooks need it).
Companion plugins for full workflow suite:
claude plugin install oss@borda-ai-rig
claude plugin install develop@borda-ai-rig
claude plugin install research@borda-ai-rig
One-time setup — run inside Claude Code after install:
Merges statusLine, permissions.allow, enabledPlugins into ~/.claude/settings.json; symlinks all rule files + TEAM_PROTOCOL.md into ~/.claude/. Idempotent — safe to re-run.
After any plugin upgrade, re-run /foundry:setup — auto-replaces stale foundry symlinks, removes rules gone from new version. No prompt for old-version symlinks.
⚡ Quick start¶
One command confirms everything works:
Expected: structured report of system config checks (hooks, settings.json, plugin integration, symlinks). Zero critical findings = ready.
Follow with:
Quick routing accuracy benchmark — measures whether Claude Code dispatches tasks to right agent. Expect routing accuracy ≥90%.
🔧 Skills reference¶
/foundry:setup¶
Post-install setup. Merges settings, creates symlinks. Run once after install, again after any upgrade.
What it does:
- Detects Python 3.10+ (
python/py -3/python3); installs~/.local/bin/pythonshim whenpythonabsent or resolves to Windows Store stub - Backs up
~/.claude/settings.jsonbefore touching - Merges
statusLine,permissions.allow,permissions.deny,enabledPlugins,advisorModel(copied from project.claude/settings.jsonwhen pinned) - Copies
permissions-guide.mdto.claude/(only if absent — preserves project-local edits) - Symlinks all
plugins/cc_foundry/rules/*.md+TEAM_PROTOCOL.mdinto~/.claude/; on upgrade, auto-replaces stale foundry symlinks, removes rules gone from current version` - Removes stale
hooksblock from settings if present (hooks now register via plugin manifest)
Hooks (hooks.json) register automatically when plugin enabled — /foundry:setup never touches them directly.
/foundry:audit¶
Full-sweep quality audit of .claude/ config + all plugins/*/ agent and skill files. Catches broken cross-references, inventory drift, model-tier mismatches, description overlap, doc staleness. Reports findings by severity; fix level chosen from always-fire follow-up gate after report. Adversarial mode challenges every claim via foundry:challenger + Codex.
/foundry:audit # full sweep, report only — gate offers fix options
/foundry:audit --upgrade # fetch latest Claude Code docs, apply improvements with A/B testing
/foundry:audit --adversarial # adversarial review with foundry:challenger + Codex
/foundry:audit --efficiency # cost and efficiency sweep: model tiers, effort levels, unbounded spawn patterns, token bloat, boilerplate duplication; outputs P1–4 plan + code-block extraction candidates; extraction gate offers EXTRACT / EXTRACT+RECOMMENDED / skip
# Tier 1 — group scopes
/foundry:audit agents # all agents
/foundry:audit skills # all skills
/foundry:audit rules # all rules
/foundry:audit communication # communication governance files
/foundry:audit setup # system config: settings.json, hooks, plugin integration
/foundry:audit plugin # foundry plugin integration checks only
/foundry:audit plugins # deep audit of all installed plugins
# Tier 2 — plugin name (shorthand for 'plugins <name>')
/foundry:audit oss # oss plugin agents + skills only
/foundry:audit foundry # foundry plugin only (same as 'plugins foundry')
/foundry:audit oss research # oss + research plugins
# Tier 3 — specific agent or skill name
/foundry:audit shepherd # single agent
/foundry:audit curator challenger # two agents
/foundry:audit review resolve # two skills
# Combine scope + flags
/foundry:audit oss --adversarial # oss plugin, adversarial review
/foundry:audit agents --adversarial # all agents, adversarial review
# Preserve key context across session compaction
/foundry:audit --keep "task-123, .reports/audit/2026-07-03T10-00-00Z"
fix and upgrade mutually exclusive — never combine.
Sweep checks (30 checks):
- Inventory drift: MEMORY.md roster vs files on disk
- Broken cross-references between agents and skills
- Hardcoded absolute user paths
- Model-tier appropriateness (reasoning vs execution roles)
- Agent description routing overlap (40%+ consecutive step overlap flagged)
- settings.json permissions vs Bash calls in skills
- Hook event names vs documented schema
- Claude Code docs freshness (spawns
foundry:web-explorerfor live docs) - Plugin integration correctness (codex plugin, foundry plugin)
- File length, heading hierarchy, LLM context minimality
- Config token overhead: total always-loaded config >100 KB, single rules file >10 KB (rules/ loads at session start; agents/skills lazy-loaded)
Outputs structured report. With fix level: delegates fixes to sub-agents (never edits inline), re-audits modified files to confirm fixes held. Convergence loop up to 5 passes.
/foundry:calibrate¶
Benchmarks agents and skills against synthetic problems with defined ground truth. Primary signal = calibration bias — gap between self-reported confidence and actual recall. Well-calibrated agent reports 0.9 when finds ~90% of issues.
/foundry:calibrate all --fast # quick benchmark across all modes (3 problems each)
/foundry:calibrate all --full # thorough benchmark (10 problems each)
/foundry:calibrate routing --fast # routing accuracy only — run after any agent description change
/foundry:calibrate agents --full --ab-test # agents + general-purpose baseline comparison
/foundry:calibrate all --fast --apply # benchmark then immediately apply improvement proposals
/foundry:calibrate --apply # apply proposals from the most recent past run
/foundry:calibrate foundry:sw-engineer --fast # single agent (tier 3 by full name)
# Tier 2 — plugin name
/foundry:calibrate oss --fast # all oss plugin agents + calibratable skills
/foundry:calibrate oss research --fast # oss + research plugins
# Tier 3 — specific agent or skill (bare name or plugin-prefixed)
/foundry:calibrate curator --fast # single agent by bare name
/foundry:calibrate curator shepherd # two agents (default --fast)
# Multiple targets
/foundry:calibrate agents skills --fast # agents + skills in one run
# Preserve key context across session compaction
/foundry:calibrate --keep "task-456, .reports/calibrate/2026-07-03T10-00-00Z"
Large fan-out gate: broad scopes (all, agents, skills, plugins, <plugin-name>) always confirm via AskUserQuestion before spawning — expand to dozens of agent/skill pipelines only inside Step 2, no exact count upfront. Narrow scopes (single agent/skill) confirm only when exact spawn count exceeds 50. --apply no longer bypasses gate alone; only --skip-gate does.
Thresholds:
- Routing accuracy: 90% (hard-problem accuracy: 80%)
- Recall per agent: 0.70 (below = instruction improvement needed)
- Calibration bias: within +/-0.15 (beyond = confidence decoupled from quality)
Modes:
agents— all specialist agentsskills—/foundry:auditand/oss:reviewrouting— orchestrator dispatch accuracy for synthetic task promptscommunication— team protocol compliance, file-handoff protocol violationsrules— rule adherence across global + path-scoped rule filesplugins/<plugin-name>— all agents + calibratable skills, one or all plugins<agent-name>/<skill-name>— single target, bare or plugin-prefixed nameall— all above
Results saved to .reports/calibrate/<timestamp>/<target>/. Improvement proposals written to proposal.md per target dir, applied with --apply.
Agents and skills modes use dual-source evaluation: Claude + Codex generate problems and score responses independently, Claude 51% tiebreaker.
/foundry:manage¶
Create, update, delete agents, skills, rules, hooks with full cross-reference propagation. Keeps MEMORY.md, README, settings.json in sync automatically.
/foundry:manage create agent security-auditor "Vulnerability scanning specialist for OWASP Top 10 and supply chain threats"
/foundry:manage create skill benchmark "Benchmark orchestrator for measuring performance across commits"
/foundry:manage create rule torch-patterns "PyTorch coding patterns — compile, AMP, distributed"
/foundry:manage update my-agent "add a section on error handling patterns"
/foundry:manage update my-agent new-agent-name # rename
/foundry:manage update my-agent docs/spec.md # apply spec file as change directive
/foundry:manage delete old-agent-name
/foundry:manage add perm "Bash(jq:*)" "Parse and filter JSON" "Extract fields from REST API responses"
/foundry:manage remove perm "Bash(jq:*)"
Create: fetches latest Claude Code agent/skill frontmatter schema, picks unused color, assigns model tier by role complexity, delegates content generation to foundry:curator. Checks overlap with existing agents first.
Update: auto-detects type from disk. Rename atomic (write-before-delete). Content edits delegated to foundry:curator (agents/skills) or foundry:sw-engineer (hooks). Propagates description changes to cross-references when more than 3 files affected.
Delete: removes file, cleans broken references across .claude/, updates MEMORY.md and README.
Permissions: add perm / remove perm update both settings.json and permissions-guide.md atomically — never one without other.
After any create or update: /foundry:calibrate routing --fast to confirm routing accuracy unaffected.
/foundry:brainstorm¶
Turns fuzzy idea into approved exploration tree, then spec, then ordered action plan. Nothing implemented until user approves design.
/foundry:brainstorm "add caching layer to the data pipeline"
/foundry:brainstorm "add caching layer to the data pipeline" --tight # fewer questions and operations
/foundry:brainstorm "add caching layer to the data pipeline" --deep # more exploration
/foundry:brainstorm "add caching layer to the data pipeline" --type workflow
/foundry:brainstorm breakdown .plans/blueprint/2026-04-01-caching-layer.md # tree -> spec
/foundry:brainstorm breakdown .plans/blueprint/2026-04-01-caching-layer-spec.md # spec -> action plan
# Preserve key context across session compaction
/foundry:brainstorm "add caching layer to the data pipeline" --keep "task-789, .plans/blueprint/2026-04-01-caching-layer.md"
Idea mode (default):
- Scans codebase for relevant existing code + constraints
- Asks up to 10 clarifying questions (5 with
--tight, 15 with--deep), one at a time - Presents 3-5 initial branches: core idea, tension resolved, what it trades away
- Interactive operations loop: deepen, reject, resolve, merge, add — up to 10 rounds
- Saves tree to
.plans/blueprint/YYYY-MM-DD-<slug>.mdwithStatus: tree - Live tree viewer at URL printed during Step 1 (serve project root with
python -m http.server 8000)
Breakdown mode (breakdown <file>):
Status: treefile: distillation questions, then section-by-section spec, savedStatus: draftStatus: draftfile: resolves blocking open questions, produces ordered action plan with tagged invocations
--type hint (application, workflow, utility, config, research) shapes question framing + codebase scan patterns in idea mode.
/foundry:investigate¶
Systematic diagnosis for unknown failures. Gathers signals, ranks hypotheses, probes top candidates, reports confirmed root cause + recommended next action.
/foundry:investigate "hooks not firing on Save"
/foundry:investigate "CI fails but passes locally"
/foundry:investigate "codex agent exits 127 on this machine"
/foundry:investigate "/calibrate times out every run"
/foundry:investigate "hooks not firing" --keep "task-999" # preserve across compaction
Covers: broken local setup, environment mismatches, tool misconfigurations, hook misbehavior, CI vs local divergence, permission errors, runtime anomalies.
Not for: known Python test failures with traceback (use /develop:debug); .claude/ config quality sweep (use /foundry:audit).
Workflow: parse symptom -> gather signals in parallel (tool versions, PATH, recent git changes, config state, logs) -> rank hypotheses -> optional Codex adversarial review for ambiguous cases -> probe top hypotheses -> report root cause + recommended next skill.
Output always includes: confirmed root cause (or narrowed suspects), key evidence, what was ruled out, single recommended next action.
Auto-invokes when (MAYBE): unknown failure, no Python traceback — hook not firing, CI passes locally but fails remotely, behavior inconsistent with config; "not working but config looks right", "hook not triggering", "why isn't X running".
/foundry:profile¶
Buckets session clock time from existing ~/.claude/logs/{timings,invocations}.jsonl into local-tool, agent-spawn, Skill, AskUserQuestion idle, main-loop reasoning residual. Pure log read — no instrumentation, no LLM calls, no skill edits.
/foundry:profile # last 24h, top 5 slowest calls
/foundry:profile --since 7d # last 7 days
/foundry:profile --session-id 9c1bded7 # drill one session
/foundry:profile --top-n 20 # 20 longest single calls
Covers: per-session breakdown (local% / agent% / skill% / reasoning% / idle), per-skill rollup (runs, total, mean, median, p90), top-N longest single calls, headline split over window.
Not for: token/cost accounting (model field null in current logs); per-line Python perf (use foundry:perf-optimizer); known failure diagnosis (use /foundry:investigate).
Reads JSONL logs foundry task-log.js hook already writes — answers "where did wall clock go in /oss:resolve?" and similar. Background agents (run_in_background=true) with spawn-only false-zero duration_ms recovered by joining matching started→completed pair in invocations.jsonl.
Auto-invokes when (MAYBE): user asks where wall-clock time goes, why skill slow, what dominates session runtime; "where does time go", "why so slow", "profile last session", "clock breakdown", "session timing".
/foundry:distill¶
Extracts patterns from work history + corrections, distills into durable improvements — new agent/skill suggestions, roster quality review, memory pruning, promoting lessons into rules, or analysing external plugins/agentic resources for adoption.
/foundry:distill # analyze project patterns, suggest new agents/skills
/foundry:distill review # review existing roster for quality and gaps (no new suggestions)
/foundry:distill prune # trim stale/redundant entries from all project MEMORY.md files
/foundry:distill prune --project # interactive picker: select which project(s) to prune
/foundry:distill memory # promote patterns from all projects into rules/agents/skills
/foundry:distill memory --project # interactive picker: select which project(s) to distill from
/foundry:distill "external https://..." # analyse external plugin/skill/agent resource, produce adoption proposal
/foundry:distill "external ./path/to/plugin" # same — local path or directory
/foundry:distill "I keep doing X manually" # use description as context for suggestions
/foundry:distill --keep "task-111" # preserve key context across compaction
--project triggers interactive project picker — lists all slugs under ~/.claude/projects/*/memory/ with MEMORY.md size in tokens; select one or more. Without --project, both modes run across all projects automatically. Both prune and memory run parallel across selected projects (one agent per project), then consolidate into single confirmation step. memory mode also enriches each project's feedback with project-level context (CLAUDE.md, recent git log, active plans) for better classification accuracy.
lessons mode = primary post-correction consolidation path. Reads .notes/lessons.md and feedback_*.md memory files, clusters by domain, classifies each entry as → rule, → agent update, → skill update, → already covered, or → too narrow, generates proposals. Before applying: conflict pre-check — greps each target file for section delta lands in, flags cross-proposal collisions with ⚠. Confirmed changes applied, followed by git diff gate — inspect or revert before committing.
external mode does fast + slow read of source (URL, file, directory), extracts mental model + standout implementation details, compares against live local setup, splits candidates into two groups: Align + improve (maps cleanly onto existing agents/skills/rules) and Differentiated highlights (novel, structurally different — interesting but larger work). Each candidate scored, assigned adoption lane: adopt-as-is / tweak / discuss / skip. When Group A thin or cumulative edit effort large, recommends installing source as standalone plugin with justification, not cherry-picking. Nothing written until confirmed.
After applying: run /foundry:setup to propagate new rule files to ~/.claude/.
Run monthly or after any correction burst.
/foundry:session¶
Parking lot for open-loop ideas + unanswered questions mid-session. Parks items automatically as they arise; three on-demand commands manage them.
/foundry:session resume # list all pending parked items for this project
/foundry:session archive <text> # fuzzy-match and close a parked item
/foundry:session summary # session digest: completed tasks, parked items, recent commits
Auto-invokes when: user asks "what was I working on", "any pending items", "remind me where we left off", "what did we defer" — resume mode only.
Items stored in project-scoped memory (~/.claude/projects/<slug>/memory/session-open-*.md). Items older than 14 days marked stale; older than 30 days deleted silently on resume.
Automatic parking (no command needed): new top-level request sent before answering Claude's prior clarifying question, or deferral like "let's come back to that" — Claude parks open item automatically so not lost to context compaction.
/foundry:create¶
Interactive outline co-creation for developer advocacy content. Collects format, audience profile, four-beat arc, voice/tone via structured questions; detects out-of-scope requests; surfaces editorial conflicts; writes approved outline for foundry:creator to execute.
/foundry:create "tracing Python microservices with OpenTelemetry"
/foundry:create "why your CI pipeline is lying to you"
/foundry:create # no topic — skill asks interactively
Supported formats: blog post, Marp slide deck (conference/meetup talk), social thread (Twitter/LinkedIn), talk abstract (CFP submission), lightning talk (5–10 min).
Out-of-scope detection: refuses FAQs, comparison tables, reference docs at Step 1, redirects to foundry:doc-scribe.
Editorial conflict detection: brief implies expert-level topic for beginner audience (or reverse) — skill surfaces mismatch explicitly before writing.
Writes .plans/content/<slug>-outline.md. Hand off to foundry:creator after approval:
Max 5 AskUserQuestion interactions for well-specified brief (format, audience, arc, voice). Skips interactive steps if all choices in initial brief.
/foundry:humanizer¶
Strips AI-writing tells from human-facing prose — docs, PR/commit bodies, reports, release notes, blog posts. Removes LLM-vocabulary clichés, banned constructions (rule-of-three triads, "not just X but Y"), formatting tells (title-case headings, em-dash overuse). Final pass — preserves meaning + structure; no rewrite from scratch.
/foundry:humanizer <text or file path> # humanize in place
/foundry:humanizer check <file> # report tells without editing
Primarily model-initiated self-review pass: foundry may invoke before finalizing substantial prose artifact drafted during task. Best-effort, not guaranteed intercept. Skips code, config, machine-parsed envelopes, inter-agent handover files.
🤖 Agents reference¶
All ten agents available by full plugin-prefixed name. In spawn directives and subagent_type values, always use full prefix (foundry:sw-engineer, not sw-engineer).
foundry:sw-engineer¶
Role: senior software engineer — writing/refactoring Python.
Use for: implementing features, fixing bugs, TDD/test-first, SOLID, type safety, production-quality Python for OSS libraries.
Model: opus
Not for: docstrings (foundry:doc-scribe), ruff/mypy config (foundry:linting-expert), system design (foundry:solution-architect), test quality analysis (foundry:qa-specialist), perf profiling (foundry:perf-optimizer), ML paper implementations (research:scientist), .claude/ config edits (foundry:curator), CI/CD pipeline config — GitHub Actions, pre-commit hooks, CI YAML (oss:cicd-steward — requires oss plugin).
Auto-invokes when: user asks to implement, build, write, modify, fix code across 3+ files; phrases: "implement", "build", "write the code for", "add feature", "fix this bug". Runs in isolated worktree.
Runs in isolated worktree by default — changes sandboxed until review.
foundry:solution-architect¶
Role: system design specialist — ADRs, API surface design, interface specs, migration plans, coupling analysis.
Use for: architectural trade-offs, public API contracts, deprecation strategies, assessing architectural feasibility of AI-generated hypotheses against codebase constraints.
Model: opus
Not for: implementation code (foundry:sw-engineer), release management (oss:shepherd), perf profiling or DataLoader throughput tuning (foundry:perf-optimizer).
Auto-invokes when (MAYBE): architecture questions involving 3+ components; "how should I structure this", "ADR for", "migration plan for". Not for simple design questions.
Produces documentation — ADRs, interface contracts, migration plans, component diagrams — not production code. Hands off to foundry:sw-engineer for execution. Spec with multiple unresolved decision branches: resolves one at a time via AskUserQuestion with recommended answer each, not one bulk ask.
foundry:qa-specialist¶
Role: QA specialist — writing, reviewing, fixing tests. Rigorous black-box end-user tester: public API surface only, expectations from docs/type hints — not implementation, tests represent realistic user workflows.
Use for: new pytest tests, public-API coverage gaps, edge-case matrices, fixing failing tests, integration test design. Auto-embeds OWASP Top 10 security review when task scope includes auth, payment flows, or PII — all modes.
Model: sonnet
Not for: linting, type checking, annotation fixes (foundry:linting-expert), production implementation (foundry:sw-engineer), slow test suite profiling (foundry:perf-optimizer), testing private/internal methods or mocking internals.
Auto-invokes when: user asks to write tests, assess coverage, define test strategy; "write tests for", "add unit tests", "test coverage for".
Writes deterministic, parametrized, behavior-focused tests. Progression: happy path → edge cases → error cases → boundary values → adversarial inputs. Applies public-API coverage checklist before done.
foundry:linting-expert¶
Role: static analysis + tooling specialist for Python.
Use for: ruff rules, mypy strictness, pre-commit hooks, fixing lint/type violations, missing type annotations, lint/type content of quality gates. Final code sanitization before handover.
Model: haiku (high-frequency, lightweight diagnostics)
Not for: CI pipeline structure or runner strategy (oss:cicd-steward), test logic (foundry:qa-specialist), implementation beyond annotation/style (foundry:sw-engineer), docstrings or API reference (foundry:doc-scribe).
Auto-invokes when: after code edits when user asks "is this clean", "any lint issues", "check formatting", "check types"; lint or type errors visible in output.
Always downstream of foundry:sw-engineer — never lints unimplemented code.
foundry:perf-optimizer¶
Role: performance engineer — profiling + optimizing CPU, GPU, memory, I/O bottlenecks.
Use for: profiling Python/ML workloads, DataLoader bottlenecks, mixed precision, vectorizing loops, PyTorch throughput tuning.
Model: opus
Not for: general refactoring (foundry:sw-engineer), architectural redesign (foundry:solution-architect), DataLoader correctness or reproducibility audits (research:data-steward — requires research plugin), doc writing (foundry:doc-scribe), annotation fixes (foundry:linting-expert).
Auto-invokes when: user asks to profile, benchmark, optimize Python/ML workload; mentions slow training, GPU underutilization, DataLoader bottleneck; phrases: "why is this slow", "profile this", "optimize training speed". Not for general code changes (foundry:sw-engineer).
Strictly profile-first: measure before change, change one thing, measure again. Optimization order: algorithm -> data structure -> I/O -> memory -> concurrency -> vectorization -> compute -> caching. Never GPU tuning before checking I/O.
foundry:doc-scribe¶
Role: documentation specialist — docstrings, API references, README files.
Use for: auditing missing docstrings, writing Google-style (Napoleon) docstrings from code, README content, doc/code inconsistencies.
Model: sonnet
Not for: CHANGELOG entries or release notes (oss:shepherd for lifecycle/format decisions, /oss:release for automated generation), linting code examples (foundry:linting-expert), implementation (foundry:sw-engineer), outward-facing narrative artifacts — blog posts, talk slides, social threads (foundry:creator).
Auto-invokes when: user asks for documentation; "write docs for", "add docstrings to", "update the README", "document this function".
Always downstream — documents finalized code, never shapes design. After foundry:doc-scribe produces content, follow with foundry:linting-expert to sanitize code examples.
foundry:web-explorer¶
Role: web fetch + content extraction specialist.
Use for: fetching live library docs, API references, changelogs, migration guides, package version lookups, GitHub release extraction. Used internally by /foundry:audit upgrade and /foundry:manage create.
Model: sonnet
Not for: code analysis or implementation (foundry:sw-engineer), ML paper analysis (research:scientist), README/docstring writing (foundry:doc-scribe), dependency upgrade lifecycle decisions (oss:shepherd), perf profiling or benchmarking recommendations (foundry:perf-optimizer).
Auto-invokes when: user asks about library docs, external API, URL content; "what does X docs say", "look up", "find the docs for", "latest version of"; user pastes URL + asks question about it.
Feeds research:scientist — fetches current docs + papers; scientist interprets.
foundry:curator¶
Role: quality guardian of Claude config markdown files — agents, skills, rules.
Use for: auditing .claude/ config files — verbosity creep, cross-agent duplication, broken cross-references, structural violations, outdated content, roster overlap. Used internally by /foundry:audit and /foundry:manage.
Model: opusplan
Not for: hook files (*.js) — belong to foundry:sw-engineer. Not for creating/scaffolding new agents or skills (/foundry:manage create). Not for routing new tasks to other agents.
Auto-invokes when (MAYBE): user explicitly references specific agent/skill config file by path; "audit this agent", "check this skill file", "is this config valid". Narrow trigger — see description.
Generally not invoked directly. /foundry:audit spawns it in batches across all config files; /foundry:manage delegates content generation + editing to it.
foundry:challenger¶
Role: adversarial reviewer — implementation plans, architecture proposals, significant code reviews.
Use for: red-teaming plan before committing, challenging architectural decisions before ship, adversarial code review on security-sensitive or irreversible ops. Every claim unproven until backed by evidence. Attacks across 6 dimensions (Assumptions, Missing Cases, Security Risks, Architectural Concerns, Complexity Creep, Root Cause) — drills to bedrock per standing challenge (keeps asking "why?" until root cause, not surface symptom). Mandatory refutation step keeps it objective: accepts refutation when evidence warrants.
When codex@openai-codex plugin installed, challenger auto-launches parallel Codex adversarial review track (same target, --scope auto), aggregates results — findings from both tracks reported together with convergence callouts where both flagged same area. Pass --no-codex in prompt to skip. Codex installed but parallel run fails: failure surfaced in report; results never silently dropped to Claude-only.
Model: opus
Not for: designing plans or ADRs (foundry:solution-architect), writing tests or coverage review (foundry:qa-specialist), config file quality review (foundry:curator).
Auto-invokes when: user asks to challenge, stress-test, critique design or plan; "challenge this", "what are the weaknesses", "devil's advocate", "poke holes in", "second opinion on".
Read-only — never writes or edits files. Runs by default in all /develop:* skills and /oss:review — skip with --no-challenge.
foundry:creator¶
Role: developer advocacy content specialist — outward-facing narrative artifacts.
Use for: complete blog posts, Marp slide decks, social threads, talk abstracts, lightning talk outlines in one autonomous pass. Imagines ideal reader experience first, works backwards to structure + form — questions status-quo conventions, pushes for fresh angles. Reads approved outline file (.plans/content/<slug>-outline.md) from /foundry:create. Applies four-beat story arc (Problem→Journey→Insight→Action) calibrated to target audience level.
Model: sonnet
Not for: in-code documentation, docstrings, API references (foundry:doc-scribe), release notes/changelogs (oss:shepherd — requires oss plugin), structured reference content — FAQs, comparison tables (redirect to foundry:doc-scribe).
Auto-invokes when: outline file .plans/content/<slug>-outline.md approved; user asks for blog post, Marp slide deck, social thread, talk abstract, lightning talk outline. Skip when: outline file not found (run /foundry:create first); code documentation (foundry:doc-scribe); release notes (oss:shepherd).
Always downstream of /foundry:create — reads approved outline, generates full artifact. Two-phase system: /foundry:create (interactive intake → outline) then foundry:creator (autonomous generation → artifact).
🔗 Agent relationships¶
Agents = directed pipeline, not flat pool:
foundry:linting-expertalways downstream offoundry:sw-engineer— never lints unimplemented codefoundry:doc-scribealways downstream — documents finalized code, never shapes designfoundry:qa-specialistruns parallel tofoundry:sw-engineerduring review, or downstream after implementationfoundry:challengeris pre-implementation — challenges plans + proposals before any code; use beforefoundry:sw-engineerfoundry:curatoris orthogonal — audits.claude/config files, not user codefoundry:web-explorerfeedsresearch:scientist— fetches current docs + papers; scientist interpretsfoundry:creatoralways downstream of/foundry:create— reads approved outline file; never generates without prior outline
Model tiering: reasoning agents (foundry:sw-engineer, foundry:perf-optimizer, foundry:solution-architect) use opus; adversarial reasoning (foundry:challenger) uses opus; plan-gated roles (foundry:curator) use opusplan; execution agents (foundry:doc-scribe, foundry:web-explorer, foundry:creator, foundry:qa-specialist) use sonnet; high-frequency diagnostics (foundry:linting-expert) use haiku.
📋 Rules installed¶
/foundry:setup symlinks all rule files from plugins/cc_foundry/rules/ into ~/.claude/rules/. Govern Claude behavior globally, all sessions after install.
Stub + on-demand split (token diet):
git-commit.md,debugging.md,external-data.md,artifact-lifecycle.md= thin always-loaded stubs with hard constraints only; full procedural bodies live inrules/_full/(resolved from plugin cache, NOT symlinked or injected), Read on demand at trigger point named in each stub — drafting commit, multi-file fix, multi-page fetch, defining new output dirs. Cuts ~6K tokens per-session injection, zero constraint loss.
| Rule file | Applies to | Governs |
|---|---|---|
communication.md |
all | Re: anchor format, progress narration, tone, output routing, breaking-findings format, terminal colors, confidence display |
quality-gates.md |
all | Confidence block format, Internal Quality Loop, link verification, output routing (long output to file) |
git-commit.md |
all | Commit message format, diff-gathering before writing, co-author trailers, branch + push safety |
claude-config.md |
all | Bash timeouts (3x P90), directory navigation rules, no hardcoded absolute paths |
artifact-lifecycle.md |
all | Canonical artifact layout (.plans/, .reports/, .temp/), run directory naming, TTL policy |
external-data.md |
all | Pagination rules: GitHub CLI, REST APIs, GraphQL, Cloud APIs — never work on partial result set |
foundry-config.md |
.claude/** |
Plan-mode gate before any .claude/ edit, post-edit checklist, XML tag conventions, distribution rules |
python-code.md |
**/*.py |
Google-style docstrings (no exceptions), deprecation version check before generating deprecation code |
testing.md |
tests/**/*.py, **/test_*.py |
pytest design: TDD process, fixture conventions, parametrization, what to test in priority order |
public-github.md |
all | Read-only policy on public GitHub — permitted reads vs permanently forbidden write operations |
⚙️ Configuration¶
settings.json keys merged by /foundry:setup¶
| Key | What it does |
|---|---|
statusLine.command |
Runs statusline.js — active agent count in Claude Code status bar |
permissions.allow |
Adds pre-approved Bash commands, git operations, WebFetch domains |
permissions.deny |
Adds permanently denied write operations (public GitHub mutations, destructive git) |
enabledPlugins["codex@openai-codex"] |
Enables Codex plugin for adversarial review in /foundry:calibrate and /foundry:audit |
advisorModel |
Copied from project .claude/settings.json when pinned — advisor tool uses chosen model |
Optional flags and knobs¶
--approve on /foundry:setup: skips all interactive prompts, auto-accepts recommended choices. For scripted or CI setups.
--skip-audit on /foundry:manage: skips trailing /foundry:audit validation step. Use inside audit-initiated fix sessions to avoid recursion.
Calibration pace: --fast (3 problems per target, default) vs --full (10 per target). --fast for routine checks after agent edits; --full for thorough benchmarks before releases or after major instruction changes.
Brainstorm ceremony: --tight (5/5/1 caps, well-scoped ideas), default (10/10/2), --deep (15/15/3, genuinely ambiguous problems).
Environment¶
No environment variables required. foundry reads ~/.claude/settings.json + plugin's installed cache path, both resolved automatically by /foundry:setup.
## 🔍 Troubleshooting
## 🔍 Troubleshooting **`/foundry:audit` reports broken symlinks (Check I3)** Symlinks in `~/.claude/rules/` point to previous plugin cache path after upgrade. Re-run `/foundry:setup` — Step 9 detects stale symlinks as conflicts, offers replacement. **Hooks not firing** Run `/foundry:investigate "hooks not firing on Save"`. Most common cause: `hooks` block still in `~/.claude/settings.json` from pre-plugin-migration install (hooks now register via plugin manifest, not `hooks` key). `/foundry:setup` Step 3 detects + removes stale block. **`/foundry:calibrate` times out** Each pipeline subagent has 10-minute hard cutoff (15 minutes when Codex active). Target consistently times out: run in isolation: `/foundry:calibrate foundry:sw-engineer --fast`. Persistent: `/foundry:investigate "/calibrate times out every run"`. **`/foundry:manage create` picks wrong model tier** Model tier chosen by role complexity at creation: `opusplan` for plan-gated quality review (e.g. `foundry:curator`), `opus` for complex reasoning (e.g. `foundry:sw-engineer`, `foundry:solution-architect`), `sonnet` for focused execution, `haiku` for high-frequency diagnostics. Fix after creation: `/foundry:manage update## 🏗️ Plugin structure
## 🏗️ Plugin structureplugins/cc_foundry/
├── .claude-plugin/
│ ├── plugin.json version + metadata
│ ├── permissions-allow.json allow-list merged by /foundry:setup
│ └── permissions-deny.json deny-list merged by /foundry:setup
├── agents/ 10 specialist agent files
├── skills/ 11 skill directories (audit, brainstorm, calibrate, create, distill, humanizer, investigate, manage, profile, session, setup)
├── rules/ 10 rule files symlinked to ~/.claude/rules/ by /foundry:setup
├── CLAUDE.src.md workflow rules; /foundry:setup Step 10 copies → ~/.claude/CLAUDE.md
├── TEAM_PROTOCOL.md AgentSpeak v2 inter-agent protocol
├── permissions-guide.md annotated allow/deny reference (copied to .claude/ by /foundry:setup)
└── hooks/
├── hooks.json hook registrations (${CLAUDE_PLUGIN_ROOT} paths)
├── task-log.js SubagentStart/Stop tracking to /tmp/claude-state-<session>/
├── statusline.js status bar agent counts
├── teammate-quality.js TaskCompleted/TeammateIdle teammate output quality gate
├── lint-on-save.js runs pre-commit after every Write/Edit; async + cross-session lock; 15s timeout; skips .temp/
├── artifact-guard.js PostToolUse Write/Edit on .reports/**/*.md, .temp/**/*.md; soft 10K-token cap + .temp/ ultra-caveman article-density heuristic; feedback only, never blocks
├── rtk-rewrite.js transparently rewrites CLI calls for token compression
├── agent-router.js PreToolUse Agent hook; 3-tier routing fallback (worktree → cache → local)
├── commit-guard.js PreToolUse Bash guard; git commit is prompt-discipline only, not hook-gated; git push --force blocked unconditionally on any branch, regular push gated by a sentinel requiring AskUserQuestion each time (no auto-arm)
├── sentinel-read-allow.js PreToolUse Bash; auto-allows blueprint idioms ($(cat "${TMPDIR:-/tmp}/…") sentinel reads, $(date -u +FMT) stamps, substitution-free `IFS= read -r VAR < sentinel` form) when every segment is read-only — kills "Contains expansion" prompts for pre-canned skill code; everything else falls through to normal permission checks; propagated to all sibling plugins
└── md-compress.js normalizes markdown whitespace/table-padding in place on Edit