refine(oss,foundry): distill code-review patterns

- oss:review complexity smell now also triggers on PY_LOC_DELTA >400 (header annotation; no split-request action)
- shepherd-reply-protocol: add `praise`/`learning` as valid Importance values in Part 2 inline suggestions table
- solution-architect: add LSP violation + ISP violation antipatterns (subclass NotImplementedError/cast-at-call-site; oversized Protocol/ABC)
- qa-specialist: add shell-injection conditional context row (os.system/subprocess — verify shell=False and list args)

Distilled from https://github.com/awesome-skills/code-review-skill (MIT). Challenger-reviewed; 3 proposals discarded (bulk python.md injection, pr-analyzer.py, language guides).

---
Co-authored-by: Claude Code <noreply@anthropic.com>

Author: Borda

README.md

@@ -2,6 +2,8 @@
 
 ![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg) [![Claude Code](https://img.shields.io/badge/Claude_Code-plugin-orange)](https://claude.ai/code) [![Codex CLI](https://img.shields.io/badge/Codex_CLI-config-green)](https://github.com/openai/codex)
 
+Specialist-agent infrastructure for Python/ML OSS — the scaffolding that lets you maintain at scale without becoming a full-time reviewer.
+
 **14 specialist agents · 20+ slash-command workflows · 5 domain plugins** — opinionated [Claude Code](https://claude.ai/code) + [Codex CLI](https://github.com/openai/codex) configuration for Python/ML OSS maintainers, version-controlled and self-calibrating.
 
 <details>
@@ -52,13 +54,10 @@ Things not possible with vanilla Claude Code:
 # Install Claude Code
 npm install -g @anthropic-ai/claude-code
 
-# 1. Clone (run from the directory that will CONTAIN the clone)
-git clone https://github.com/Borda/AI-Rig Borda-AI-Rig
-
-# 2. Register as a local marketplace
-claude plugin marketplace add ./Borda-AI-Rig
+# 1. Register from GitHub (no clone needed)
+claude plugin marketplace add Borda/AI-Rig
 
-# 3. Install all five plugins
+# 2. Install plugins — pick what you need
 claude plugin install foundry@borda-ai-rig   # base agents + audit, manage, calibrate, brainstorm, …
 claude plugin install oss@borda-ai-rig       # OSS workflow: analyse, review, resolve, release
 claude plugin install develop@borda-ai-rig   # development: feature, fix, refactor, plan, debug
@@ -70,19 +69,20 @@ claude plugin install codemap@borda-ai-rig   # structural index: import graph, b
 >
 > **Safe to install alongside any existing Claude Code setup.** Plugins live in a private cache (`~/.claude/plugins/cache/<plugin>/`) under their own namespace. Your existing `~/.claude/agents/`, `~/.claude/skills/`, and `settings.json` are never modified or overwritten — custom agents and skills you have created remain fully independent. See the [Claude Code plugin reference](https://code.claude.com/docs/en/plugins-reference) for details.
 
-**4. One-time settings merge** — run inside Claude Code:
+**3. One-time settings merge** — run inside Claude Code:
 
 ```text
-/foundry:init
+/foundry:setup
 ```
 
 OSS, develop, and research skills always use their plugin prefix (`/oss:review`, `/develop:fix`, `/research:run`). Safe to re-run.
 
 > [!IMPORTANT]
 >
-> **Codex CLI** — optional companion; the plugins install Claude Code agents and skills only:
+> **Codex CLI** — optional companion; requires a local clone (`.codex/` config is not a plugin):
 >
 > ```bash
+> git clone https://github.com/Borda/AI-Rig Borda-AI-Rig
 > npm install -g @openai/codex
 > cp -r Borda-AI-Rig/.codex/ ~/.codex/   # Codex agents and profiles
 > ```
@@ -126,6 +126,8 @@ Managing AI coding workflows for Python/ML OSS is complex — you need domain-aw
 - ML training and inference codebases needing GPU profiling and data pipeline validation
 - Multi-contributor projects with CI/CD, pre-commit hooks, and automated releases
 
+A typical maintainer morning — 15 issues, 3 PRs, a release due — handled in one session with four commands (see Daily OSS Workflow above).
+
 ## 💡 Design Principles
 
 - **Agents are roles, skills are workflows** — agents carry domain expertise, skills orchestrate multi-step processes
@@ -172,7 +174,7 @@ Agents and skills for [Claude Code](https://claude.ai/code) (Anthropic's AI codi
 
 Skills are multi-agent workflows invoked via slash commands. Each skill composes several agents in a defined topology.
 
-After running `/foundry:init`, foundry skills are available without a prefix. OSS, develop, and research skills always use their plugin prefix.
+After running `/foundry:setup`, foundry skills are available without a prefix. OSS, develop, and research skills always use their plugin prefix.
 
 | Skill                     | What It Does                                                                                                                                                                                                            |
 | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -443,19 +445,19 @@ AI-Rig/
 ### Upgrade
 
 ```bash
-cd Borda-AI-Rig && git pull
 claude plugin install foundry@borda-ai-rig   # reinstalls from updated source
 claude plugin install oss@borda-ai-rig
 claude plugin install develop@borda-ai-rig
 claude plugin install research@borda-ai-rig
 claude plugin install codemap@borda-ai-rig
 ```
 
-Re-run `/foundry:init` only if permissions or `enabledPlugins` changed. Re-run `/foundry:init` if you previously used the link mode — symlinks point to the old plugin cache after an upgrade.
+Re-run `/foundry:setup` only if permissions or `enabledPlugins` changed. Re-run `/foundry:setup` if you previously used the link mode — symlinks point to the old plugin cache after an upgrade.
 
 ### Session-only (no install, for development)
 
 ```bash
+git clone https://github.com/Borda/AI-Rig Borda-AI-Rig
 claude --plugin-dir ./Borda-AI-Rig/plugins/foundry
 ```
 
@@ -469,7 +471,7 @@ claude plugin uninstall research
 claude plugin uninstall codemap
 ```
 
-Settings added by `/foundry:init` remain in `~/.claude/settings.json`; remove manually if desired. If `/foundry:init` was run, symlinks in `~/.claude/agents/` and `~/.claude/skills/` also persist and will be broken after uninstall — remove with `rm ~/.claude/agents/<name>.md` and `rm -rf ~/.claude/skills/<name>` for each.
+Settings added by `/foundry:setup` remain in `~/.claude/settings.json`; remove manually if desired. If `/foundry:setup` was run, symlinks in `~/.claude/agents/` and `~/.claude/skills/` also persist and will be broken after uninstall — remove with `rm ~/.claude/agents/<name>.md` and `rm -rf ~/.claude/skills/<name>` for each.
 
 ______________________________________________________________________
 

plugins/codemap/skills/integration/SKILL.md

@@ -3,7 +3,7 @@ name: integration
 description: "Manage codemap integration — 'check' audits installation health (scan-query reachable, index fresh, injection present), 'init' onboards codemap by discovering skills/agents, recommending injection sites, and wiring them in."
 argument-hint: "check | init [--approve]  # --approve: non-interactive, auto-applies all High+Medium injection recommendations and installs post-commit hook"
 effort: medium
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion
 model: sonnet
 ---
 

plugins/develop/.claude-plugin/plugin.json

@@ -7,5 +7,5 @@
   "license": "MIT",
   "name": "develop",
   "repository": "https://github.com/Borda/AI-Rig",
-  "version": "0.7.4"
+  "version": "0.7.5"
 }

plugins/develop/skills/debug/SKILL.md

@@ -298,9 +298,9 @@ Evidence: <key signals>
 **Refinements**: N passes.
 ```
 
-**Follow-up gate (NEVER SKIP)** — Call `AskUserQuestion` tool — do NOT write options as plain text first. Map options directly into tool call arguments:
+**Follow-up gate (NEVER SKIP)** — Call `AskUserQuestion` tool — do NOT write options as plain text first. Substitute actual `$DIAG_FILE` path (from bash block above) into option (a) label before calling tool. Map options directly into tool call arguments:
 - question: "Proceed with fix?"
-- (a) label: `/develop:fix --diagnosis $DIAG_FILE` — description: proceed with fix using confirmed diagnosis
+- (a) label: `/develop:fix --diagnosis <DIAG_FILE>` (substitute resolved path, e.g. `/develop:fix --diagnosis .plans/active/debug_<slug>.md`) — description: proceed with fix using confirmed diagnosis
 - (b) label: `skip` — description: no action
 
 

plugins/foundry/.claude-plugin/plugin.json

@@ -15,5 +15,5 @@
   "license": "MIT",
   "name": "foundry",
   "repository": "https://github.com/Borda/AI-Rig",
-  "version": "0.23.0"
+  "version": "0.23.1"
 }

plugins/foundry/agents/creator.md

@@ -1,6 +1,6 @@
 ---
 name: creator
-description: 'Developer advocacy content specialist for outward-facing narrative artifacts — blog posts, Marp slide decks, social threads, talk abstracts, and lightning talk outlines. Imagines the ideal reader experience first, then works backwards to structure and form. Questions status-quo conventions before accepting them; pushes for genuinely fresh angles. Reads an approved outline file (.plans/content/<slug>-outline.md) produced by the /foundry:create skill and generates the complete content artifact in one autonomous pass. Applies a four-beat story arc (Problem → Journey → Insight → Action) calibrated to the target audience. NOT for in-code documentation (docstrings, API refs, README) — use foundry:doc-scribe. NOT for release notes or changelogs — use /oss:release (requires `oss` plugin). NOT for structured reference content (FAQs, comparison tables) — those are doc-scribe scope; redirect to foundry:doc-scribe. TRIGGER when: outline file at .plans/content/<slug>-outline.md approved; user asks to write a blog post, slide deck, social thread, talk abstract, or lightning talk outline; phrases: "write a blog post", "create slides", "draft a thread", "write a talk abstract", "write a CFP submission". SKIP: outline file not found (evaluated by dispatch-time caller before spawning creator; run /foundry:create first); code documentation task (use foundry:doc-scribe); release notes or changelogs (use /oss:release — requires `oss` plugin).'
+description: 'Developer advocacy content specialist for outward-facing narrative artifacts — blog posts, Marp slide decks, social threads, talk abstracts, and lightning talk outlines. Imagines the ideal reader experience first, then works backwards to structure and form. Questions status-quo conventions before accepting them; pushes for genuinely fresh angles. Reads an approved outline file (.plans/content/<slug>-outline.md) produced by the /foundry:create skill and generates the complete content artifact in one autonomous pass. Applies a four-beat story arc (Problem → Journey → Insight → Action) calibrated to the target audience. NOT for in-code documentation (docstrings, API refs, README) — use foundry:doc-scribe. NOT for release notes or changelogs — use /oss:release (requires `oss` plugin). NOT for structured reference content (FAQs, comparison tables, feature matrices, decision guides) — standalone reference artifacts route to foundry:doc-scribe; a blog post with an embedded comparison section is still creator scope (narrative arc, not standalone reference). TRIGGER when: outline file at .plans/content/<slug>-outline.md approved; user asks to write a blog post, slide deck, social thread, talk abstract, or lightning talk outline; phrases: "write a blog post", "create slides", "draft a thread", "write a talk abstract", "write a CFP submission". SKIP: outline file not found (evaluated by dispatch-time caller before spawning creator; run /foundry:create first); code documentation task (use foundry:doc-scribe); release notes or changelogs (use /oss:release — requires `oss` plugin); full artifact is structured reference format without narrative arc (use foundry:doc-scribe).'
 tools: Read, Write, Grep, Glob, AskUserQuestion
 model: sonnet
 color: purple

plugins/foundry/agents/doc-scribe.md

@@ -1,6 +1,6 @@
 ---
 name: doc-scribe
-description: 'Documentation specialist for writing docstrings, API references, and README files. Owns all FAQ and comparison-table reference content, including standalone FAQs. Use for auditing missing docstrings, writing Google-style docstrings from code, creating or updating README content, and finding doc/code inconsistencies. NOT for CHANGELOG entries or release notes (use oss:shepherd for lifecycle/format decisions, /oss:release skill for automated generation), NOT for release lifecycle README sections (version badges, PyPI install link) — use oss:shepherd, NOT for linting code examples (use foundry:linting-expert), NOT for implementation code (use foundry:sw-engineer), NOT for outward-facing narrative artifacts like blog posts, talk slides, or social threads — use foundry:creator. TRIGGER when: user asks for documentation — docstrings, README section, API reference, code comments; phrases: "write docs for", "add docstrings to", "update the README", "document this function", "add API reference". SKIP: documentation is one sentence (answer inline); user asking about existing docs read-only; implementation task (use foundry:sw-engineer).'
+description: 'Documentation specialist for writing docstrings, API references, and README files. Owns all FAQ and comparison-table reference content, including standalone FAQs. Use for auditing missing docstrings, writing Google-style docstrings from code, creating or updating README content, and finding doc/code inconsistencies. NOT for CHANGELOG entries or release notes (use oss:shepherd for lifecycle/format decisions, /oss:release skill for automated generation), NOT for release lifecycle README sections (version badges, PyPI install link) — use oss:shepherd, NOT for linting code examples (use foundry:linting-expert), NOT for implementation code (use foundry:sw-engineer), NOT for outward-facing narrative artifacts like blog posts, talk slides, or social threads — use foundry:creator. TRIGGER when: user asks for documentation — docstrings, README section, API reference, code comments; phrases: "write docs for", "add docstrings to", "update the README", "document this function", "add API reference", "write a FAQ", "create a comparison table", "write a feature matrix". SKIP: documentation is one sentence (answer inline); user asking about existing docs read-only; implementation task (use foundry:sw-engineer).'
 tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch, TaskCreate, TaskUpdate
 model: sonnet
 effort: medium
@@ -142,6 +142,7 @@ See **Prompt-Scope Gate** above for scope-filtering rules.
 
 - FAQ entries and comparison tables are doc-scribe scope — both standalone and co-located with API docs
 - NOT for outward-facing narrative artifacts (blog posts, talk abstracts, social threads) → route to `foundry:creator`
+- Exception: comparison sections embedded within narrative artifacts (blog posts, slide decks) are creator scope — doc-scribe handles only standalone reference documents
 
 </quality_checks>
 

plugins/foundry/agents/linting-expert.md

@@ -1,6 +1,6 @@
 ---
 name: linting-expert
-description: 'Static analysis and tooling specialist for Python. Use for configuring ruff rules, mypy strictness, pre-commit hooks, fixing lint/type violations, adding missing type annotations to Python source files, and defining the lint/type tool content of quality gates. Handles final code sanitization before handover. NOT for CI pipeline structure, runner strategy, or workflow topology (use oss:cicd-steward), NOT for writing test logic (use foundry:qa-specialist), NOT for implementation fixes beyond annotation/style (use foundry:sw-engineer), NOT for inline docstrings or API reference writing (use foundry:doc-scribe). TRIGGER when: after code edits when user asks "is this clean", "any lint issues", "check formatting", "check types"; linting or type errors visible in output; user pastes code with visible style violations and asks for review. SKIP: code is Python stdlib only with no project config; user explicitly said linting not needed; general code review (use foundry:sw-engineer).'
+description: 'Static analysis and tooling specialist for Python. Use for configuring ruff rules, mypy strictness, pre-commit hooks, fixing lint/type violations, adding missing type annotations to Python source files, and defining the lint/type tool content of quality gates. Handles final code sanitization before handover. NOT for CI pipeline structure, runner strategy, or workflow topology (use oss:cicd-steward), NOT for writing test logic (use foundry:qa-specialist), NOT for implementation fixes beyond annotation/style (use foundry:sw-engineer), NOT for inline docstrings or API reference writing (use foundry:doc-scribe). TRIGGER when: after code edits when user asks "is this clean", "any lint issues", "check formatting", "check types"; linting or type errors visible in output; user pastes code with visible style violations and asks for review; user asks to add type annotations to existing code ("add type hints", "annotate this module", "fix annotation errors"). SKIP: code is Python stdlib only with no project config; user explicitly said linting not needed; general code review (use foundry:sw-engineer).'
 tools: Read, Write, Edit, Bash, Grep, Glob, TaskCreate, TaskUpdate, WebFetch
 model: haiku
 effort: medium
@@ -375,6 +375,7 @@ Don't apply uniform hedge — produces systematic calibration bias. Only list Ga
 - CI quality-gate YAML (workflow steps for ruff + mypy) → `oss:cicd-steward` (requires `oss` plugin)
 - Test coverage gaps or edge-case matrices → `foundry:qa-specialist`
 - Type annotation patterns in ML/tensor code → `foundry:sw-engineer` or `foundry:perf-optimizer`
+- Standalone annotation task on existing code (no implementation changes) → linting-expert; annotations written alongside new implementation → `foundry:sw-engineer`
 
 **Incoming handovers**:
 

plugins/foundry/agents/qa-specialist.md

@@ -192,6 +192,7 @@ Never claim pattern exists without confirming via Grep/Glob first. Applies to al
 | File uploads or `open()` calls | Check for size limits and path traversal prevention |
 | External API calls (`requests.`, `httpx.`, `aiohttp.`, `fetch`) | Check timeout, retry, and error handling *[sw-engineer domain — flag as observation only]* |
 | New `import`/`from` packages | Verify package exists in `pyproject.toml` / `requirements*.txt` |
+| `os.system(`, `subprocess.*`, `shlex` | Check shell-injection: verify `shell=False` (or kwarg absent); args must be list, not f-string or concatenated string; `shlex.quote()` only valid when `shell=True` strictly unavoidable |
 
 **Domain-boundary rule**: rows tagged `[perf-optimizer domain]` or `[sw-engineer domain]` surface as observations, not qa defects. Don't count in coverage-gap totals; redirect substantive findings to owning agent.
 

plugins/foundry/agents/solution-architect.md

@@ -224,6 +224,8 @@ Every artifact written to file (`docs/adr/`, `docs/design/`, or user-specified p
 | Type-annotation circular import | Use `from __future__ import annotations` + `TYPE_CHECKING` guard: `if TYPE_CHECKING: from module import Type` — eliminates runtime import while preserving type checker support |
 | Destructive migration before consumer cutover | Use expand-contract: add new columns, deploy reader of new columns, then drop old columns in separate migration after all readers migrated |
 | Undocumented boundary placement | Write ADR before any restructure; must state ownership principle so future engineers don't re-create same ambiguity |
+| LSP violation | Subclass overrides with `NotImplementedError`/`pass` body or call sites use `isinstance`/cast before using base type → flatten hierarchy; prefer Protocol structural typing over ABC enforcement |
+| ISP violation | Protocol or ABC with >5 methods where callers use only a partial subset → split into focused protocols per usage cluster; Protocol over ABC for structural typing in Python |
 
 </antipatterns_to_flag>