Turbo

A composable dev process for agentic coding harnesses, packaged as modular skills. Turbo has sibling editions for Claude Code and Codex.

The Claude Code edition is production-tested. The Codex edition is currently experimental: the skill set has reached parity, but it has seen less real-world use.

TL;DR — Three steps to ship:

1. Plan — Run /turboplan (or enter raw plan mode) and describe what you want to build
2. Implement — Run /implement-plan on the plan, or /implement for ad-hoc changes
3. Finalize — /finalize runs tests, code polishing, commit, and PR. It kicks in automatically once a plan file's steps are done; when no plan file governs the work, /implement offers it alongside a lighter pass or stopping. Run it yourself if you built by hand.

This loop is the core. Two more pipelines run alongside it for work that does not fit the loop: /audit for project-wide health checks and /onboard for ramping up on new projects. Beyond the four pipelines, Turbo ships 70+ skills for debugging, reviewing, dependency upgrades, and self-improvement that makes each session teach the next. See the prompt examples for how they look in practice, or read on for the full picture.

Quick Start

Prerequisites

Pick your edition: claude/SETUP.md for Claude Code, codex/SETUP.md for Codex. Both editions work best with their respective Max-tier plans (pipeline workflows are context-heavy). Additional tools are installed during setup.

External services: The Claude edition benefits from ChatGPT Plus or higher for Codex peer review. The Codex edition benefits from Claude Code access for Claude peer review. ChatGPT Pro or Business is useful for /consult-oracle, where Pro models are the only ones that reliably solve very hard problems. /peer-review and /consult-oracle are designed as swappable puzzle pieces, so if you don't have access, replace them with alternatives that work for you.

Automatic Setup (Recommended)

In Claude Code or Codex, prompt:

Walk me through the Turbo setup. Read SETUP.md from the tobihagemann/turbo repo and follow the guide for your edition.

The agent reads the root SETUP.md, picks the file that matches its harness (claude/SETUP.md or codex/SETUP.md), clones the repo, installs skills, configures the environment, and walks you through each step interactively.

Updating

Run /update-turbo (Claude Code) or $update-turbo (Codex) to update all skills. It fetches the latest update instructions from GitHub, builds a changelog, handles conflict detection for customized skills, and manages exclusions.

Editions

claude/   # Claude Code edition
codex/    # Codex edition

Each edition is a self-contained tree with its own SETUP.md, UPDATE.md, MIGRATION.md, ADDITIONS.md, SKILL-CONVENTIONS.md, and skills/. The root-level files are short routers that point at the per-edition versions.

What Is This?

Turbo covers the full dev lifecycle. Five ideas shape its design:

1. Standardized process. Skills capture dev workflows so you can run them directly instead of prompting from scratch. /turboplan analyzes complexity and routes to the right mode. /finalize runs your entire post-implementation QA in one command. /investigate follows a structured root cause analysis cycle. The skill is the prompt.
2. Layered design. Skills compose other skills to any depth. /review-code security runs a single-concern scan. /review-code with no argument runs all six types in parallel. /polish-code loops stage → format → lint → test → review → evaluate → apply → smoke test until stable. /finalize wraps the whole pipeline with self-improvement and commit. /audit fans out to all analysis skills in parallel, evaluates the combined findings, and produces a health report. Each pipeline composes with a natural, predictable interface. See The Turboplan Pipeline and The Finalize Pipeline for worked examples.
3. Swappable by design. Every skill owns one concern and communicates through standard interfaces. Replace any piece with your own and the pipeline adapts. See The Puzzle Piece Philosophy for details.
4. Works out of the box. Install the skills and the full workflow is ready. Dependencies are standard dev tooling (GitHub CLI, Codex) that most teams already have.
5. Just skills. No framework, no custom runtime, no new memory system. Skills are plain markdown that use the harness's native primitives (git, filesystem, built-in tools). Remove an independent skill and the rest still work.

The one thing beyond skills is each edition's ADDITIONS.md (e.g. claude/ADDITIONS.md), a small set of behavioral rules added to your harness's instruction file during setup. The most important one is Skill Loading: without it, the agent tends to skip reloading skills it has already seen in a session, which causes it to silently drop steps in nested pipelines like /finalize. The additions are kept in sync by /update-turbo. See claude/docs/skill-loading-reasoning.md for the full rationale (Claude-specific failure modes and mitigations; the Codex edition adapts the same rules in codex/ADDITIONS.md).

The other core piece is /self-improve, which makes the whole system compound: it routes each session's lessons back into your project's instructions, memory, and skills. See Self-Improvement below.

Works Best With

Turbo amplifies your existing process. It shines when your project has the right infrastructure in place:

• Tests — The /polish-code loop inside /finalize runs your test suite and reviews coverage gaps. Without tests, there's no safety net. If your project has none, /smoke-test can fill the gap by launching your app and verifying changes manually in the same loop, but real tests are always better. See Browser and UI Testing for the tools behind that verification.
• Linters and formatters — The /polish-code loop runs your formatter and linter before code review. If you don't have one, style issues slip through.
• Pre-commit hooks — When /finalize commits, it triggers any pre-commit hooks you have configured and fixes hook failures before retrying. If your project uses tools like husky, lint-staged, or pre-commit, Turbo works with them automatically.
• Existing analysis tools — Skills like /find-dead-code and /assess-technical-debt lean on integrated tools (knip, vulture, periphery, lizard, jscpd) when your project already has them.
• Dependencies — GitHub CLI powers PR and issue operations. The Claude edition uses Codex for peer review; the Codex edition uses Claude for peer review. Everything works without peer review, but the full pipeline is better with it. See the edition setup guides for details.

Who It's For

Turbo is for experienced developers who want to move faster without sacrificing quality. That said, beginners are welcome too. Turbo is a great way to learn how a professional dev workflow looks. Just don't blindly trust outputs. Review what Claude produces, understand why it made those choices, and build your own judgment alongside it.

If your plan is vague, your architecture is unclear, and you skip every review finding, Turbo won't save you. Garbage in, garbage out.

The Puzzle Piece Philosophy

Every skill is a self-contained piece. Pipeline skills like /finalize and /audit compose them into workflows, but each piece works independently too.

Want to swap a piece? For example:

• Replace /consult-oracle with your own setup (it's macOS-only and has a cookies workaround)
• Replace /commit-rules or /changelog-rules with your team's conventions. The pipeline adapts.
• Replace /code-style with your team's style guide. The built-in one teaches general principles rather than opinionated rules, so it's a natural swap point.

Skills communicate through standard interfaces: git staging area, PR state, and file conventions.

Sponsorship

If Turbo has helped you ship faster and you're so inclined, I'd greatly appreciate it if you'd consider sponsoring my open source work.

The Turboplan Pipeline

Claude Code's built-in plan mode tends to produce plans that miss existing patterns, skip edge cases, or propose approaches that don't hold up under scrutiny, and it can feel too restrictive for iterative planning. Turbo replaces it with /turboplan as a universal entry point: whether your task is a single-session change or a multi-subsystem project, you start there. It analyzes the task, routes it through the right pipeline, and produces plans that survive contact with reality, with no need for plan mode to be active. Direct work chains through /discuss-change and /implement to /finalize; plan-mode work halts once for a fresh /implement-plan session, and spec-mode projects halt again after /pick-next-shell before implementation.

/turboplan has three modes, named by what each one produces. Its complexity analysis recommends a mode, then you confirm the route:

• Direct mode — Clear scope, with any remaining decisions small enough to settle in conversation. Hands off to /discuss-change, which escalates open product decisions, agrees the implementation shape with you, then runs /implement, which loads /code-style plus any task-specific skills, applies the change, previews any UI/UX change for you to try, and offers /finalize, a lighter pass, or stopping. No plan file is written.
• Plan mode — Single-session change whose approach warrants writing down before implementing. Runs /draft-plan (survey + consult skills/docs + escalate + discuss + draft) → /refine-plan → /self-improve. Halts after self-improve; you run /implement-plan in a fresh session.
• Spec mode — Multi-subsystem project with architectural decisions. Routes to /draft-spec for a guided spec discussion, then /refine-plan to iteratively review and revise the spec, then /draft-shells to decompose the spec into shells with YAML frontmatter, then /refine-plan to review and revise the shells, then to compound planning learnings before context is cleared. Halts after self-improve; you run in fresh sessions to plan each shell, then to implement it.

Every sub-skill works standalone too. Run /draft-plan directly if you want to draft a plan without the rest of the pipeline. Run /refine-plan on a plan you wrote yourself. Run /implement-plan in a fresh session on any plan file. Run /draft-spec to write a spec without committing to the full pipeline.

Shells and the Spec-Mode Flow

In spec mode, /draft-shells decomposes the spec into shells: structured decomposition artifacts that capture the wiring invariants (Produces, Consumes, Covers spec requirements) and high-level Implementation Steps. Shells lock in the decomposition — what each session builds, what it depends on, what spec requirements it covers — without committing to concrete file paths. /refine-plan reviews and tightens the shells until stable.

You then drive implementation one shell at a time. /pick-next-shell picks the next shell whose dependencies are satisfied and chains into /expand-shell, which adds a fresh pattern survey and concrete references against the current codebase, then refine → self-improve → halt. You run /implement-plan in a fresh session. Each implementation session gets fresh pattern surveys, so decisions from earlier sessions naturally inform later ones.

The Finalize Pipeline

/finalize is the QA and commit side of the loop. Run it when you're done implementing, or let /implement / /implement-plan chain into it automatically once a plan file's steps are done. Without a plan file, /implement asks first, offering /simplify-all as a lighter pass or stopping instead. One command runs tests, iterative code polishing, documentation cleanup, changelog updates, self-improvement, and commit.

/finalize runs through these phases automatically:

1. Polish Code — Iterative loop: stage → format → lint → test → review → evaluate → apply → smoke test → re-run until stable
2. Simplify Docs — Strip unnecessary comments and documentation noise from the changed files
3. Update Changelog — Add entries to the Unreleased section of CHANGELOG.md (skipped if no changelog exists)
4. Self-Improve — Extract learnings, route to CLAUDE.md / AGENTS.md / memory / skills
5. Ship It — Branch if needed, commit, push, create or update PR

Self-Improvement

/self-improve makes each session teach the next. Run it anytime before ending your session (it's also part of /finalize Phase 4). It scans the conversation for corrections, repeated guidance, failure modes, and preferences, then routes each lesson to the right place: project CLAUDE.md/AGENTS.md, auto memory, or existing/new skills. Over time, Turbo gets better at your specific project.

/note-improvement captures improvement opportunities that surface during work but fall out of scope: review findings you skipped, refactoring ideas, missing tests, and deliberate simplifications that accept a known ceiling. They're tracked in .turbo/improvements.md (gitignored, so they don't clutter the repo), each tagged direct, investigate, or plan for later routing.

When you're ready to act, /implement-improvements validates each entry against the current codebase, drops stale ones, and runs one lane per session:

• direct → /implement for a clear-scope fix
• investigate → /investigate, then /implement
• plan → /turboplan

Out-of-Loop Pipelines

Two pipelines run alongside the main loop rather than inside it. They share the same composition style as the plan-implement-finalize core.

Project-Wide Audit

/audit fans out to all analysis skills in parallel (correctness, security, API usage, consistency, simplicity, test coverage, dependencies, tooling, dead code, agentic setup), evaluates the combined findings, and produces a health report at .turbo/audit.md with a dashboard and an interactive HTML version. Run it to assess codebase health before a major release, after onboarding to a new project, or on a regular cadence.

/audit is analysis-only: it produces the report and stops there. When you're ready to act on findings, use /apply-findings or address them manually.

Developer Onboarding

/onboard generates a comprehensive onboarding guide for new developers joining a project. It composes /map-codebase (architecture), /review-tooling (development workflow), and /review-agentic-setup (AI coding infrastructure) with inline agents for prerequisites, troubleshooting, and next steps (top GitHub issues). The result is .turbo/onboarding.md with an interactive HTML version.

The guide covers both traditional onboarding (setup, build commands, tooling) and agentic onboarding (what CLAUDE.md/AGENTS.md cover, installed skills, MCP servers, Claude Code vs Codex CLI compatibility). If a threat model exists, security considerations are included too.

/map-codebase also works standalone when you just need the architecture report without the full onboarding guide.

Browser and UI Testing

/smoke-test and /exploratory-test (Claude) / $smoke-test and $exploratory-test (Codex) automate manual testing — the kind of hands-on verification you'd normally do yourself. The underlying tools differ per edition:

For changes where you want to judge the feel yourself, /preview / $preview stands up the live app and hands it to you to try a UI/UX change firsthand, then waits for your verdict before continuing. /implement runs it automatically before /finalize when a change touches a user-facing surface, and you can run it standalone any time you want to poke at the running app.

Claude Code:

• /agent-browser skill — Browser automation with the most control for web app testing.
• claude-in-chrome MCP — Built-in Claude Code browser automation using your real Chrome browser. Falls back to this when /agent-browser is not installed.
• computer-use MCP — Built-in Claude Code screen control for native app and UI testing on macOS.

Codex:

• browser-use@openai-bundled plugin — Browser automation for web app testing. Bundled in Codex's openai-bundled marketplace.
• computer-use@openai-bundled plugin — Screen control for native app and UI testing on macOS. Bundled in Codex's openai-bundled marketplace.

Prompt Examples

These are prompts you can type directly into Claude Code or Codex (use $skill-name in Codex). Skill names work as natural words in your sentences.

# Planning a change (single entry — /turboplan routes based on complexity)
/turboplan add a caching layer to the image pipeline  ← plan mode → draft → refine → halt; run /implement-plan after
/turboplan build a notification system with backend, API, and UI  ← spec mode → spec → shells → halt
/survey-patterns  ← pattern-ground an approach without drafting a plan
/implement-plan  ← execute the latest plan in .turbo/plans/ in a fresh session

# Continuing a spec-mode project
/pick-next-shell  ← pick next shell → expand → refine → halt; run /implement-plan after

# Investigating bugs
tests are failing in the auth module, can you please /investigate?
/investigate the app crashes when i click "save" after editing a profile

# Reviewing code
/review-code
/review-pr for PR #42

# Auditing project health
/audit
read @.turbo/audit.md and /apply-findings  ← follow-up session

# Onboarding to a new project
/onboard
/map-codebase  ← architecture report only

# Resolving PR feedback
/resolve-pr-comments

# Updating dependencies
/update-dependencies

# Working through the improvements backlog
the error messages in this module are inconsistent, /note-improvement
/implement-improvements  ← dedicated session

# Testing manually
/smoke-test
/exploratory-test
/preview  ← stand up the app so you can try a UI change yourself

# Picking the next issue to work on
/pick-next-issue

# Filing an issue
/create-issue for the flaky upload test

# Extracting session learnings
/self-improve

# Saving session state before compacting
/create-handoff

# Creating a new skill
/create-skill for a skill that <description>

All Skills

For the full skill listing with descriptions and dependencies, see the per-edition index:

• Claude Code — claude/SKILL-INDEX.md (/skill-name invocations)
• Codex — codex/SKILL-INDEX.md ($skill-name invocations)

License

Distributed under the MIT License. See the LICENSE file for details.