CLAUDE.md

Project Context

Turbocharge: Claude Code Plugin Blueprint

A Claude Code plugin that replaces ad-hoc agents, scattered skills, and custom commands with a single opinionated engineering pipeline. Also serves as a reference implementation for building Claude Code plugins.

What This Project Is

This is a plugin for Claude Code — not a standalone app. It consists of:

• 10 skills (SKILL.md files that define slash commands)
• 6 agents (markdown agent definitions dispatched by skills)
• 1 workflow (workflows/review-swarm.js, launched by /turbocharge:review when the user opts in). The directory copy leaves it out (Publishing Flow step 5)
• 2 hooks (SessionStart bootstrap + ATLAS pre-load; builder exit gate on SubagentStop and PreToolUse/SubagentHandback). Repo installs only: the directory copy ships no hooks since 3.5.8 (Publishing Flow step 5)
• A marketplace manifest for distribution

Architecture

Plugin Structure:
  skills/         → SKILL.md files (user-invocable slash commands)
  agents/         → Agent definitions (dispatched by skills, not invocable directly)
  hooks/          → hooks.json + content files (lifecycle automation)
  workflows/      → workflow scripts (launched by skills)
  .claude-plugin/ → plugin.json manifest + icon.png (plugin icon)

The Pipeline

brainstorm → story → plan → build → review → ship
                                  |               |
                                debug            wrap

Distribution

Source repo:  nicodiansk/turbocharge (this repo — single source of truth)
Install:      claude plugin marketplace add nicodiansk/turbocharge
              claude plugin install turbocharge@turbocharge
Update:       claude plugin update turbocharge@turbocharge
Local dev:    claude --plugin-dir /path/to/turbocharge
Directory:    claude.ai plugin directory listing "Turbocharge" (ours; submitted 2026-06-23,
              published 2026-09-24). Managed at claude.ai/directory/manage; tracks the trimmed `release`
              branch since 3.4.1 (Publishing Flow step 5).
              Each new version is scanned, then needs "Publish update" (a reviewer makes it live).
              Install id: turbocharge-nicodiansk@anthropic-plugin-directory (Claude Code's
              built-in marketplace; check the live version with `claude plugin list --available --json`)

Name history: 3.0.0 renamed the plugin to turboflow because another author's plugin named turbocharge is listed in the directory (turbocharge-aguerlain-lr). What 3.0.0 missed: our own listing already existed, and the directory tells same-named plugins apart by appending the publisher (turbocharge-nicodiansk). 3.2.0 restored turbocharge so the listing's users keep /turbocharge:. Never start a new directory submission. Never rename the plugin name: it sets every user's command namespace.

Domain Terms

Development Conventions

File Types

Skill Anatomy

Every skill MUST have:

1. YAML frontmatter with name, description
2. Clear instructions Claude can follow without ambiguity
3. A "Red Flags" section for anti-rationalization (build, review, debug at minimum)
4. Chain-forward: suggest the next skill in the pipeline

Agent Models

Sonnet minimum, never Haiku. Every agent (builders, reviewers, researchers, planners) runs Sonnet or higher. Turn count beats token price: a cheaper model that loops on misunderstandings costs more than one that gets it right the first time. Do not set model: haiku on any agent.

The planner is the one deliberate model: inherit: it rides the orchestrator's session model so architectural planning gets your strongest available model (Opus when you orchestrate on Opus, Sonnet otherwise) — never below the Sonnet floor in normal use, and portable to setups without Opus access. Every other agent hard-pins model: sonnet, the verifier included, and the review swarm's lens agents set model: 'sonnet' in the script.

No agent file pins Opus. Apart from the planner inheriting an Opus session, Opus appears in one place: build retries a stuck builder lane once with model: opus on the Agent call. Design or destructive questions go to the user, never to an Opus retry.

Release Naming

Name releases by what they do, not after the source of inspiration. Never put competitor/plugin codenames (e.g. another plugin's brand) in commit messages, branch names, CHANGELOG entries, or PR titles/bodies. Continue the project's own lineage instead (e.g. "Lean Builder v3" → "Lean review pipeline"). Two exceptions: the pre-existing setup skill's conflict-detection list, which names competing plugins functionally to warn about conflicts, and NOTICE, which must name the project whose license it carries.

Third-Party Material

Text or code copied or adapted from another project keeps that project's license notice. NOTICE (shipped in both copies) holds the MIT notice for the parts of debug, ship and plan adapted from another plugin, and lists each file; add a file there when you copy or adapt more. Guarded by t_notice.sh.

Versioning

• Version lives only in .claude-plugin/plugin.json; marketplace.json carries none (plugin.json wins over the marketplace entry, and the docs say to set it in one place). Guarded by t_version_lockstep.sh
• Bump it every release — the claude.ai directory expects a new version for each update
• Use semver: patch for fixes, minor for new skills/features, major for breaking changes

Testing Locally

# Load plugin from local directory
claude --plugin-dir .

# Validate plugin structure
./scripts/validate.sh

# Behavioral evals (WSL2, Linux or macOS): WITH / W/OUT / Δ per family. Runs use the logged-in
# account: on a Max/Pro login they draw plan usage, not API billing. <max-cost-usd> caps the
# CLI's list-price estimate, i.e. how much usage a run may take
scripts/eval.sh <max-cost-usd> [--runs 1]

On macOS, cases that use git need a wrapper first on PATH: the eval sandbox denies stat on the real git binaries, so bare git falls to the broken /usr/bin/git stub (dogfood D15). Exec by full path still works:

mkdir -p ~/.cache/tc-eval-git
printf '#!/bin/sh\nexec /opt/homebrew/bin/git "$@"\n' > ~/.cache/tc-eval-git/git && chmod +x ~/.cache/tc-eval-git/git
PATH="$HOME/.cache/tc-eval-git:$PATH" scripts/eval.sh <max-cost-usd>

Publishing Flow

Single-repo as of v2.3.0. No cross-repo sync.

1. Run the evals: TC_EVAL_LABEL=<version> scripts/eval.sh <cap> (WSL2, Linux, or macOS with the git wrapper), commit evals/summary/<version>.md, and refresh README Measured from it
2. Bump version in .claude-plugin/plugin.json (the only place it lives)
3. Update CHANGELOG.md with the new entry
4. Commit + push to nicodiansk/turbocharge. Users pick it up via claude plugin update turbocharge@turbocharge.
5. Directory: the listing tracks a release branch, so merges to master don't create directory versions.
   • The portal switched from master to release with 3.4.1. Change the tracked branch on its Settings tab only when no publish request is waiting, because changing it cancels a waiting publish request.
   • To send a release to the directory: bash scripts/release.sh vX.Y.Z --push (repo scripts are mode 644; core.filemode is off). It builds a trimmed commit from the tag's plugin files (.claude-plugin/, agents/, hooks/, skills/, templates/, workflows/, README, LICENSE, NOTICE) and fast-forwards release to it; dev files (this CLAUDE.md, CHANGELOG, .github/, scripts/, evals/, images/, examples/) never reach the directory, whose scan flags them. A new top-level path must be added to SHIPPED in scripts/release.sh or to DEV_ONLY in t_release_tree.sh. The webhook scans release, and once it passes you click Publish update.
   • The directory copy differs from the tag in four ways. Every shipped markdown file goes through scripts/directory-filter.sh, which drops <!-- repo-only --> … <!-- /repo-only --> blocks and un-comments <!-- directory-only … --> blocks (hidden on GitHub). The whole hooks/ directory and the review workflow are left out (DIRECTORY_DROP: the directory copy ships no hooks, and review runs one code-reviewer). The manifests drop 2 hooks and 1 workflow. Ship is user-only (DIRECTORY_USER_ONLY: release.sh puts disable-model-invocation: true in its frontmatter), as in 2.8.1 and 3.3.0; repo installs keep the ship Claude can start (t_ship_menu.sh).
   • In skills and agents, use repo-only blocks around text that holds only for repo installs, and reword shared text so it's true in both copies. Avoid directory-only blocks there: repo installs read the raw file, so Claude would see the directory's alternative text as a comment.
   • Why: the scan holds a version for review when shipped text names a bundled image or font (UNREAD_ASSET_REFERENCED: icon.png in a file tree was enough), or reads as fetching code and running it (RUNTIME_FETCH_EXEC: cleared in 3.4.2 by moving the repo-marketplace install, CI note, project layout and ./scripts/… commands into repo-only blocks). Its policy also held 3.4.2 for "Update adds hooks" (the exit gate's two events, new since 2.8.1), which leaving the gate out cleared. "Uses a credential from the user's machine" (MCP_FORWARDS_CREDENTIAL_ENV) held 3.4.0 to 3.5.6. The card shows only .claude-plugin/plugin.json; the report behind it (the ListPluginSubmissionVersions response the Versions tab loads) names the pair in params: credential_at skills/debug/condition-based-waiting.md, env "pass sometimes," (the scan reads a password-store command such as pass starting a segment after a parenthesis as a secret being read), sender_at hooks/session-start.sh, pairing read+strong. The same rule matched scripts/validate.sh from 2.8.1 to 3.3.0 without the read+strong pairing, which didn't hold, and it names only the first match in path order. 3.5.0 to 3.5.6 changed other things on guesses (ship's gh api triage, the workflow's wording and then the workflow itself, the hook's CLAUDE.local.md read, ship user-only), and the hold stayed; 3.5.7 rewords the line, which cleared that hold: the scan passed on 2026-10-19. Read the report's params before changing anything for a hold. 3.5.4 was a test commit on release only (the live 2.8.1's tree with the version changed): the directory refused to fetch it ("Files in the repository the scanner won't accept"), though none of the listed kinds of file was in it, so nothing was scanned. A version held by policy is "not with Anthropic for review" (the portal); a Publish click records a request for the reviewer, and under this listing's setting a reviewer publishes every version, passing ones included. 3.5.7 then waited for a reviewer and was refused in 2026-11, first with LOCAL_CODE_NOT_CHECKED ("didn't confirm that it read the whole plugin") and then with LOCAL_CODE_HOOK_COMMAND: "The directory accepts command hooks only from Verified organizations … Remove every hook of type command, then push a new commit. Hooks of type prompt can stay." SessionStart takes only command and mcp_tool hooks, so the bootstrap can't become a prompt hook: the directory copy ships no hooks since 3.5.8. "Verified organization" is undocumented: Anthropic chooses them, there's no way to ask yet, and nothing ties it to a Team plan.
   • release.sh refuses a tree whose text names a bundled asset, pipes a download into a shell, keeps a marker, names a left-out file (by its name without the extension), reads as a password-store command, holds a hooks.json or a hook of type command, counts hooks, or still says 1 workflow (t_release_tree.sh, t_directory_copy.sh). The CHANGELOG stays on GitHub; the README links to it by URL.
   • Merges to master reach repo-marketplace installs (turbocharge@turbocharge) right away.
   • The live directory version shows in claude plugin list --available --json under turbocharge-nicodiansk.