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)
• 5 agents (markdown agent definitions dispatched by skills)
• 1 hook (SessionStart bootstrap + ATLAS pre-load)
• 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)
  .claude-plugin/ → plugin.json manifest
  settings.json   → Plugin-scoped settings

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 `master`.
              Each new version is scanned, then needs "Publish update" (a reviewer makes it live).

Name history: 3.0.0–3.1.1 shipped as turboflow because we wrongly believed another author owned turbocharge in the directory; the listing was ours. 3.2.0 restored turbocharge. Never start a new directory submission. Never rename the plugin name: the listing and every install key off it.

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.

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"). The one allowed exception is the pre-existing setup skill's conflict-detection list, which names competing plugins functionally to warn about conflicts.

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

Publishing Flow

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

1. Bump version in .claude-plugin/plugin.json (the only place it lives)
2. Update CHANGELOG.md with the new entry
3. Commit + push to nicodiansk/turbocharge. Users pick it up via claude plugin update turbocharge@turbocharge.