4-Agent Dev Team with Claude Code

Orchestrate a Planner, Coder, Tester, and Reviewer pipeline in Claude Code.

Introduction

30 Second Summary

Ever wished you could hand off a feature request before bed and wake up to a tested, reviewed implementation? Most developers spend their days context-switching between planning, coding, testing, and reviewing. Each switch costs focus.

In this project, you will build a 4-agent pipeline inside Claude Code that turns a one-line feature request into a fully implemented, tested, and reviewed feature branch.

What You'll Build

A subagent orchestration system with four specialist agents (Planner, Coder, Tester, Reviewer) that communicate through file-based handoffs in a shared pipeline folder.

By the end of this project, you'll have:

A working 4-agent pipeline (Planner, Coder, Tester, Reviewer) that processes feature requests end-to-end inside Claude Code.
A cost-efficient model routing strategy that sends expensive reasoning to Opus and cheaper execution to Sonnet.
A single /ship command that orchestrates all four agents sequentially with file-based handoffs.
Secret Mission: Add auto-cleanup between runs and a conditional retry loop when the Reviewer returns a NEEDS WORK verdict.

Are there any prerequisites?

You need Claude Code installed in your terminal and an active Claude Pro (or Max) plan. You also need an existing codebase with a git repository to run the pipeline against.

Set Up Your Project Structure

Every agent in your pipeline needs to know where to find its instructions and where to drop its output. Claude Code uses a .claude/ directory at your project root for agent definitions and commands.

You'll also create a .pipeline/ folder for ephemeral handoff files that agents pass between each other. This step sets up the skeleton so the rest of the project has a clean home.

In this step, get ready to:

Verify Claude Code model access works in your project.
Create the agent, command, and pipeline directories.
Check out a feature branch for the pipeline work.

Verify your Claude Code model access

Your pipeline routes expensive reasoning tasks to Opus and cheaper execution tasks to Sonnet. Before building anything, you need to confirm that both models are available in your Claude Code session.

Press Cmd+Space (macOS) or the Windows key (Windows) to open your search bar.
Type Terminal and press Enter to open it.
Navigate to your existing project's root directory by running:

cd ~/path/to/your/project

Start a Claude Code session by running:

claude

You should see the Claude Code interface load with a prompt ready for input.

Open the model picker by typing this inside your Claude Code session:

/model

You should see a list of available model aliases including opus, sonnet, haiku, and fable.

Why does model access matter here?

Your pipeline assigns specific models to specific agents. The Planner and Reviewer use opus for deep reasoning. The Coder and Tester use sonnet for cost-efficient execution. If a model is unavailable, the corresponding agent will fall back to a default and produce weaker output.

✔️ I see opus, sonnet, haiku, and fable

Your model access is confirmed. Press Escape to dismiss the picker without switching models.

ⓧ I don't see opus in the list

Opus may be restricted by your organization's settings or your plan. Confirm you have a Claude Pro or Max subscription at anthropic.com/pricing.

If you're on a team plan, ask your admin to check the model allowlist. Opus must be enabled for the Planner and Reviewer agents to use their intended model.

Exit the Claude Code session by typing:

/exit

Create the folder structure

Your pipeline needs three directories, each with a distinct responsibility. Agent definitions live in .claude/agents/, the orchestrator command lives in .claude/commands/, and ephemeral handoff files live in .pipeline/.

Create all three directories by running these commands:

mkdir -p .claude/agents
mkdir -p .claude/commands
mkdir -p .pipeline

What do these directories do?

.claude/agents/ holds one Markdown file per subagent. Claude Code reads these at session start to register your agents.

.claude/commands/ holds command files that you invoke with a / prefix in Claude Code. Your /ship orchestrator will live here.

.pipeline/ is where agents write their output for the next agent to read. These files are ephemeral and should never be committed to version control.

Confirm the directories exist by running:

ls -la .claude/agents .claude/commands .pipeline

You should see all three directories listed in the output.

Add .pipeline/ to your .gitignore by running:

echo ".pipeline/" >> .gitignore

Why gitignore the pipeline folder?

The .pipeline/ folder contains handoff files from a specific pipeline run. These are unique to each feature request and have no value in version control. Committing them would pollute your Git history with throwaway context.

Verify the gitignore entry was added by running:

cat .gitignore

You should see .pipeline/ as the last line in the file.

Don't see .pipeline/ in .gitignore?

If the file is empty or missing the entry, make sure you used >> (append) and not > (overwrite). Using a single > would replace your entire .gitignore with just that one line.

help me fix my .gitignore

Create a feature branch for this work

Keeping your pipeline setup on a dedicated branch means you can merge it cleanly once everything works.

Create and switch to a new branch by running:

git checkout -b setup-agent-pipeline

Confirm you are on the new branch by running:

git branch

You should see * setup-agent-pipeline highlighted in the output, confirming you are on the new branch.

Seeing an error about uncommitted changes?

If Git refuses to switch branches, you may have uncommitted changes in your working directory. Commit or stash them first with git stash, then try the checkout again.

help me resolve my git branch issue

Your project skeleton is ready. Next up, you'll create the Planner agent that turns feature requests into implementation specs.

Create the Planner Agent

Your folder structure is ready. Now it's time to create the first specialist in your pipeline.

The Planner is the agent that kicks off every feature request. Its job is to read your codebase, understand existing patterns, and produce a detailed spec that downstream agents can follow without guessing. It never writes implementation code.

In this step, get ready to:

Understand the Planner agent's role and constraints.
Create the Planner agent definition file with YAML frontmatter and a system prompt.
Validate that the Planner appears in Claude Code's agent library.

Understand the Planner's role

Every pipeline needs a starting point that sets the quality ceiling for everything downstream. The Planner fills that role.

Why does the Planner run on Opus?

The Planner runs on Opus because planning quality determines how well the Coder, Tester, and Reviewer perform. A vague spec produces vague code. By spending stronger reasoning at the planning stage, every downstream agent receives clear, unambiguous instructions.

The Planner is also structurally constrained. It has no Edit or Bash tools. It can only read your codebase and write a spec file. This prevents it from drifting into implementation work.

Create the Planner agent definition file

Claude Code subagents are defined as Markdown files with YAML frontmatter. The frontmatter configures the agent's metadata (name, tools, model) and the Markdown body becomes the system prompt.

Create a new file at .claude/agents/planner.md and add the following content:

---
name: planner
description: Turns a feature request into an implementation spec. Use as the first stage of the feature pipeline.
tools: Read, Grep, Glob, Write
model: opus
---

You are a planning specialist. You do NOT write implementation code.

Given a feature request:

1. Read the relevant parts of the codebase to understand current patterns.
2. Write a spec to .pipeline/spec.md containing:
   - Files to create or modify, with exact paths.
   - The interface or function signatures needed.
   - Edge cases the implementation must handle.
   - Which existing patterns to follow (name the file to copy from).
3. Flag anything ambiguous as an OPEN QUESTION at the top of the spec.

Keep the spec tight. The Coder reads this and nothing else, so leave no gaps and invent no requirements that were not asked for.

What does this file do?

The YAML frontmatter between the --- lines configures how Claude Code loads this agent:

name: planner registers the agent under this identifier (must be lowercase with hyphens).
tools: Read, Grep, Glob, Write grants read access to explore your code plus Write to output the spec file. No Edit or Bash means it cannot modify existing files or run commands.
model: opus routes this agent to Opus for strongest reasoning.

The body below the frontmatter is the system prompt. It tells the agent exactly what to produce (a spec at .pipeline/spec.md) and what to flag (OPEN QUESTIONS for anything ambiguous).

Save planner.md.
Confirm the file exists by running:

ls .claude/agents/

You should see planner.md listed in the output.

Don't see planner.md?

Make sure you saved the file inside .claude/agents/ and not in .claude/commands/ or the project root.
Check that the folder name is .claude with a leading dot. Folders starting with a dot are hidden by default in most file browsers.

Still stuck? Help me find where my planner.md file ended up.

✔️ Awesome, I've got everything!

Great. Make sure you've saved your file before moving on.

ⓧ I'd like to double check the full code

Here is the complete planner.md file for comparison:

---
name: planner
description: Turns a feature request into an implementation spec. Use as the first stage of the feature pipeline.
tools: Read, Grep, Glob, Write
model: opus
---

You are a planning specialist. You do NOT write implementation code.

Given a feature request:

1. Read the relevant parts of the codebase to understand current patterns.
2. Write a spec to .pipeline/spec.md containing:
   - Files to create or modify, with exact paths.
   - The interface or function signatures needed.
   - Edge cases the implementation must handle.
   - Which existing patterns to follow (name the file to copy from).
3. Flag anything ambiguous as an OPEN QUESTION at the top of the spec.

Keep the spec tight. The Coder reads this and nothing else, so leave no gaps and invent no requirements that were not asked for.

Validate the Planner in Claude Code

Subagents are loaded when a Claude Code session starts. To confirm the Planner registered correctly, you need to start a fresh session and check the agent library.

Start a new Claude Code session by running:

claude

Once the session is active, run the following command inside it:

/agents

Switch to the Library tab.
Confirm you see planner listed with its description: "Turns a feature request into an implementation spec."
Press Esc to close the agents interface, then type /exit to end the session.

Why start a new session?

Claude Code loads subagent definitions at session start. If you add or edit a subagent file directly on disk, you must restart your session for it to appear. Subagents created through the /agents interface take effect immediately, but since you created the file manually, a fresh session is required.

Make sure you started a new session after saving the file. Running /agents in a session that was already open before you created the file will not show it.
Check your YAML frontmatter for syntax errors. The --- delimiters must be on their own lines with no leading spaces.
Confirm the file is at .claude/agents/planner.md relative to your project root (the directory where you ran claude).

Need more help? My planner agent isn't appearing in the /agents Library tab after restarting my session.

Your first specialist is live. Next, you'll create the Coder agent that reads the Planner's spec and turns it into working code.

Create the Coder Agent

Your Planner agent is ready to produce specs. Now you need a specialist that takes those specs and turns them into working code.

The Coder agent reads .pipeline/spec.md and implements exactly what it describes. It does not plan, does not review, and does not add unrequested features. It runs on Sonnet because implementation against a clear spec does not need Opus-level reasoning.

In this step, get ready to:

Understand the Coder agent's role and constraints.
Create the coder.md agent definition file.
Validate the Coder agent in Claude Code.

Understand the Coder's role in the pipeline

Each agent in the pipeline has a strict boundary. The Coder's boundary is implementation only.

Why isolate implementation from planning?

When a single agent plans and codes at the same time, it tends to drift from the spec. It "improves" things nobody asked for, or quietly changes the plan mid-implementation.

By splitting planning and coding into separate context windows, the Coder can only see the spec file. It has no memory of the original request, so it cannot reinterpret requirements on the fly.

Opus is the strongest reasoning model, but it is also the most expensive in token usage. A clear spec eliminates ambiguity, so the Coder does not need deep reasoning. Sonnet handles straightforward implementation at lower cost.

This means roughly 70% of your pipeline's token spend goes to the cheaper Sonnet model (Coder + Tester), while Opus handles only the stages that require judgment (Planner + Reviewer).

Create the Coder agent definition

The Coder follows the same file format as the Planner: YAML frontmatter for configuration and a Markdown body for the system prompt.

Create the file .claude/agents/coder.md by running this command:

touch .claude/agents/coder.md

Open .claude/agents/coder.md in your editor and paste the following content:

---
name: coder
description: Implements the spec at .pipeline/spec.md. Use as the second stage of the feature pipeline, after the planner.
tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
---

You are an implementation specialist.

1. Read .pipeline/spec.md in full. If it has OPEN QUESTIONS, stop and surface them instead of guessing.
2. Implement exactly what the spec describes. Follow the patterns it names. Do not add features it did not ask for.
3. Write a short summary to .pipeline/changes.md: which files changed, what each change does, and anything the Tester should focus on.

You write code that matches the repo. You do not refactor unrelated code or improve things outside the spec's scope.

What does this agent definition do?

name: coder sets the unique identifier Claude Code uses to find and invoke this agent.
tools: Read, Write, Edit, Grep, Glob, Bash grants the Coder full file access plus shell commands. It needs Write and Edit to modify your codebase, and Bash to run formatters or build tools.
model: sonnet routes this agent to the cheaper, faster model since it follows a clear spec.
The system prompt instructs the agent to stop on open questions rather than guess, and to output a handoff file at .pipeline/changes.md for the next agent in the chain.

Save .claude/agents/coder.md.
Confirm the file exists by running:

ls .claude/agents/

You should see both planner.md and coder.md listed.

Only see planner.md?

Make sure you created the file inside .claude/agents/ (not .claude/commands/ or the project root). Check the path with ls .claude/agents/coder.md to see if the file landed in the right spot.

help me find where my coder.md file ended up

✔️ Awesome, I've got everything!

Great. Make sure you have saved the file before moving on.

ⓧ I'd like to double check the full code

Here is the complete .claude/agents/coder.md file:

---
name: coder
description: Implements the spec at .pipeline/spec.md. Use as the second stage of the feature pipeline, after the planner.
tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
---

You are an implementation specialist.

1. Read .pipeline/spec.md in full. If it has OPEN QUESTIONS, stop and surface them instead of guessing.
2. Implement exactly what the spec describes. Follow the patterns it names. Do not add features it did not ask for.
3. Write a short summary to .pipeline/changes.md: which files changed, what each change does, and anything the Tester should focus on.

You write code that matches the repo. You do not refactor unrelated code or improve things outside the spec's scope.

Validate the Coder agent in Claude Code

Subagents are loaded when a Claude Code session starts. You need to start a fresh session to pick up the new file.

Start a new Claude Code session by running:

claude

Once the session is active, run /agents to open the agent management interface.
Switch to the Library tab.
Confirm that coder appears in the list alongside planner.

What should I see?

The Library tab shows all available subagents. You should see both planner and coder listed as project-scoped agents, along with their descriptions from the YAML frontmatter.

If you were already in a Claude Code session when you created the file, the agent will not appear until you restart. Exit with /exit and start a new session with claude.

Also check that the YAML frontmatter starts with --- on the very first line of the file. Any leading whitespace or blank lines before the frontmatter will prevent Claude Code from parsing the agent definition.

help me debug why my coder subagent is not appearing in the Library tab

Your Coder is ready to receive specs and produce implementations. Next up, you will create the Tester and Reviewer agents to complete the pipeline's quality gates.

Create the Tester and Reviewer Agents

Your Planner and Coder agents are ready to go. The Planner produces a spec, and the Coder turns that spec into working code. But working code is not the same as correct code.

In this step, you will build the two agents that close the loop: a Tester that verifies the implementation and a Reviewer that delivers a final quality verdict. Together, these four agents form a complete plan-code-test-review pipeline.

In this step, get ready to:

Create the Tester agent that writes and runs tests against the Coder's output.
Create the Reviewer agent that delivers a read-only quality verdict.
Verify all four agents appear in Claude Code's agent library.

Create the Tester agent

The Tester reads .pipeline/changes.md (produced by the Coder), writes tests that match your repo's existing test framework, runs them, and reports results to .pipeline/test-results.md. It runs on sonnet and has Bash access so it can execute your test suite.

Why doesn't the Tester fix failing code?

If the Tester could fix its own failures, it would become both implementer and tester. That defeats the separation of concerns. A failing test pauses the pipeline and surfaces the problem for the Reviewer to judge.

This constraint keeps each agent honest. The Tester can only verify, never patch.

Create the Tester agent definition by adding a new file at .claude/agents/tester.md with this content:

---
name: tester
description: Writes and runs tests for changes described in .pipeline/changes.md. Third stage of the feature pipeline.
tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
---

You are a test specialist.

1. Read .pipeline/changes.md to see what was built and where.
2. Read the changed files and the spec at .pipeline/spec.md.
3. Write tests covering:
   - The happy path.
   - The edge cases the spec named.
   - At least one failure case.
   Match the repo's existing test framework and conventions.
4. Run the tests. If any fail, write the failures to .pipeline/test-results.md and STOP. Do not fix the code yourself.
5. If all pass, note that in .pipeline/test-results.md.

You test behavior, not implementation details. A failing test means the pipeline pauses for the Reviewer, not that you patch around it.

What does this agent definition do?

The YAML frontmatter configures the agent's identity and capabilities. tools: Read, Write, Edit, Grep, Glob, Bash gives the Tester everything it needs to explore code, write test files, and execute them.

The Markdown body is the system prompt. It constrains the Tester to a strict workflow: read the changes, write tests, run them, and report. The explicit "Do not fix the code yourself" instruction prevents scope creep.

Save tester.md in the .claude/agents/ directory.
Confirm the file exists by running:

ls .claude/agents/

You should see planner.md, coder.md, and tester.md listed.

Don't see tester.md?

Make sure you saved the file inside .claude/agents/ and not in the project root. The filename must be tester.md (lowercase).

Help me find where my tester.md file ended up.

Create the Reviewer agent

The Reviewer is the final quality gate. It reads everything in .pipeline/, runs git diff to see actual changes, and writes a verdict to .pipeline/review.md. It runs on opus for the strongest judgment.

Why is the Reviewer read-only?

The Reviewer has no Write or Edit tools. It cannot paper over problems by silently fixing them. It can only judge. This is a structural guarantee enforced by the tools field in the frontmatter.

The Bash tool is included so the Reviewer can run git diff to inspect changes. It is not for editing files.

Create the Reviewer agent definition by adding a new file at .claude/agents/reviewer.md with this content:

---
name: reviewer
description: Final review of the full pipeline output. Fourth and last stage before human sign-off.
tools: Read, Grep, Glob, Bash
model: opus
---

You are a senior reviewer. You are read-only. You do not edit code.

1. Read the spec, the changes summary, and the test results from .pipeline/.
2. Run git diff to see the actual changes.
3. Assess:
   - Does the code match the spec?
   - Are the tests meaningful or superficial?
   - Any security, performance, or correctness issues?
4. Write a verdict to .pipeline/review.md:
   VERDICT: SHIP / NEEDS WORK / BLOCK
   For NEEDS WORK or BLOCK, list exactly what to fix and where.

Be the last line of defense. If the tests are green but the code is wrong, say BLOCK. Green tests are not the same as correct behavior.

What does this agent definition do?

Notice the tools field: Read, Grep, Glob, Bash. Compare this to the Coder's tools which include Write and Edit. By omitting those two tools, the Reviewer physically cannot modify files.

The model: opus setting routes to the strongest reasoning model for judgment calls. Planning and reviewing are where quality matters most, so both the Planner and Reviewer use Opus.

Save reviewer.md in the .claude/agents/ directory.
Confirm all four agent files exist by running:

ls .claude/agents/

You should see planner.md, coder.md, tester.md, and reviewer.md listed.

Don't see all four files?

Double-check you are running ls from your project root directory. The .claude folder is hidden by default. If you are using a file explorer, make sure hidden files are visible.

Help me find my missing agent files.

Validate all four agents in Claude Code

Subagents are loaded at session start. If you created these files while a Claude Code session was running, you need to restart the session for Claude Code to pick them up.

Start a fresh Claude Code session by running:

claude

Run /agents inside the session.
Switch to the Library tab.
Confirm all four agents appear: planner, coder, tester, and reviewer.
Exit the session with /exit.

Don't see all four agents in the Library tab?

Make sure you restarted the session after creating the files. Subagents created directly on disk are not loaded until the next session starts.

Also check that each file has valid YAML frontmatter with the --- delimiters at the top. A missing closing --- breaks the agent definition.

Help me debug why my agents aren't showing up.

✔️ Awesome, I've got everything!

All four agents are visible in the Library tab. Your pipeline roster is complete.

ⓧ I'd like to double check the full code

Here is the full content for both files created in this step:

---
name: tester
description: Writes and runs tests for changes described in .pipeline/changes.md. Third stage of the feature pipeline.
tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
---

You are a test specialist.

1. Read .pipeline/changes.md to see what was built and where.
2. Read the changed files and the spec at .pipeline/spec.md.
3. Write tests covering:
   - The happy path.
   - The edge cases the spec named.
   - At least one failure case.
   Match the repo's existing test framework and conventions.
4. Run the tests. If any fail, write the failures to .pipeline/test-results.md and STOP. Do not fix the code yourself.
5. If all pass, note that in .pipeline/test-results.md.

You test behavior, not implementation details. A failing test means the pipeline pauses for the Reviewer, not that you patch around it.

---
name: reviewer
description: Final review of the full pipeline output. Fourth and last stage before human sign-off.
tools: Read, Grep, Glob, Bash
model: opus
---

You are a senior reviewer. You are read-only. You do not edit code.

1. Read the spec, the changes summary, and the test results from .pipeline/.
2. Run git diff to see the actual changes.
3. Assess:
   - Does the code match the spec?
   - Are the tests meaningful or superficial?
   - Any security, performance, or correctness issues?
4. Write a verdict to .pipeline/review.md:
   VERDICT: SHIP / NEEDS WORK / BLOCK
   For NEEDS WORK or BLOCK, list exactly what to fix and where.

Be the last line of defense. If the tests are green but the code is wrong, say BLOCK. Green tests are not the same as correct behavior.

Your four-agent roster is complete. You have a Planner that specs, a Coder that implements, a Tester that verifies, and a Reviewer that judges. Next up, you will wire them together with a single command that chains all four agents into one automated pipeline.

Wire the Orchestrator and Run the Pipeline

You have four specialist agents ready to go. Each one knows its job, has its tools, and runs on the right model.

The missing piece is a conductor. Right now, you would have to manually delegate to each agent in sequence, check the handoff file, then delegate to the next. The orchestrator command automates that entire chain into a single invocation.

In this step, get ready to:

Create the /ship orchestrator command that chains all four agents.
Run the full pipeline on your codebase with a real feature request.
Review the handoff files and the Reviewer's verdict.

Create the orchestrator command

A custom command in Claude Code is a Markdown file inside .claude/commands/. When you type /ship in a session, Claude reads the file and follows its instructions. The special $ARGUMENTS token passes whatever text you type after the command name into the prompt.

Create the file .claude/commands/ship.md with the following content:

Run the full feature pipeline for: $ARGUMENTS

Execute these stages in order. Do not skip ahead. After each stage, confirm the handoff file exists before starting the next.

1. Delegate to the planner subagent with the feature request above. Wait for .pipeline/spec.md.
2. If the spec has OPEN QUESTIONS, stop and show them to me. Otherwise delegate to the coder subagent. Wait for .pipeline/changes.md.
3. Delegate to the tester subagent. Wait for .pipeline/test-results.md. If tests failed, stop and show me the failures.
4. Delegate to the reviewer subagent. Show me .pipeline/review.md.

Report the final verdict. Do not merge anything. Leave the branch for my morning review.

What does this command do?

Each numbered step delegates to one of your four subagents in sequence. The command enforces a strict order: Planner, then Coder, then Tester, then Reviewer.

Between each stage, Claude confirms the handoff file exists before proceeding. This prevents downstream agents from running on stale or missing data.

The pipeline halts early in three situations: the Planner flags OPEN QUESTIONS, tests fail, or the Reviewer issues a BLOCK verdict. It never merges code automatically.

Save .claude/commands/ship.md.
Confirm the file exists by running:

ls .claude/commands/

You should see ship.md listed in the output.

Don't see ship.md?

Make sure you created the file inside .claude/commands/ (not .claude/agents/). Commands and agents live in separate directories.

Also check the filename is exactly ship.md with no extra extension or uppercase letters.

help me troubleshoot why my ship.md file isn't appearing in .claude/commands/

Claude Code also supports a newer format called skills (.claude/skills/NAME/SKILL.md). Both formats create a /name slash command and work identically. Commands are simpler for single-file definitions like this orchestrator.

✔️ Awesome, I've got everything!

Great. Double check you saved the file before moving on.

ⓧ I'd like to double check the full code

Run the full feature pipeline for: $ARGUMENTS

Execute these stages in order. Do not skip ahead. After each stage, confirm the handoff file exists before starting the next.

1. Delegate to the planner subagent with the feature request above. Wait for .pipeline/spec.md.
2. If the spec has OPEN QUESTIONS, stop and show them to me. Otherwise delegate to the coder subagent. Wait for .pipeline/changes.md.
3. Delegate to the tester subagent. Wait for .pipeline/test-results.md. If tests failed, stop and show me the failures.
4. Delegate to the reviewer subagent. Show me .pipeline/review.md.

Report the final verdict. Do not merge anything. Leave the branch for my morning review.

Test the pipeline with a feature request

The orchestrator is wired. Time to run it against your real codebase and watch all four agents work in sequence.

What makes a good first feature request?

Pick something small and bounded. A single new endpoint, a utility function, or a configuration option. Avoid large refactors or multi-file rewrites for your first run.

The goal is to see the full pipeline flow, not to ship your biggest feature on the first try.

Start a new Claude Code session by running:

claude

Why a fresh session?

Subagents and commands are loaded at session start. Since you just created ship.md, you need a fresh session for Claude Code to pick it up.

Run the pipeline by typing the /ship command followed by your feature request. Here is an example:

/ship add a health check endpoint at GET /health that returns 200 OK with a JSON body containing status and timestamp

What happens next?

Claude delegates to the Planner (running on Opus), which reads your codebase and writes .pipeline/spec.md. Then the Coder (Sonnet) implements the spec and writes .pipeline/changes.md. The Tester (Sonnet) writes and runs tests, recording results to .pipeline/test-results.md. Finally, the Reviewer (Opus) reads everything and writes a verdict to .pipeline/review.md.

This may take a few minutes depending on codebase size. Claude Code will show you progress as each agent completes its stage.

Watch for each agent to complete in sequence. Claude will ask permission to use various tools. Grant the permissions as prompted.
If the Planner flags OPEN QUESTIONS, the pipeline stops and shows them to you. Answer the questions, then re-run /ship with a more specific feature request.

Pipeline stuck or erroring out?

If an agent fails to produce its handoff file, the session may have hit a context limit. Try a smaller feature request to reduce the amount of code each agent processes.

If you see permission errors, make sure you are granting tool permissions when Claude asks. Each subagent needs its tools approved on first use.

help me debug why my /ship pipeline is failing or stuck

Review the pipeline output

Once the pipeline finishes, four handoff files now exist in your .pipeline/ folder. Each one captures the work of a single agent.

Read the Reviewer's verdict by running:

cat .pipeline/review.md

You should see a verdict line: VERDICT: SHIP, VERDICT: NEEDS WORK, or VERDICT: BLOCK.

Check that all four handoff files exist by running:

ls .pipeline/

You should see spec.md, changes.md, test-results.md, and review.md listed.

Read each file to understand how context flowed between agents:

cat .pipeline/spec.md
cat .pipeline/changes.md
cat .pipeline/test-results.md

What should I look for in the output?

The spec should list exact file paths and function signatures. No vague descriptions.
The changes summary should match what the spec asked for. No unrequested features.
The test results should cover happy path, edge cases, and at least one failure case.
The review should reference specific lines or patterns, not generic praise.

SHIP means the code is ready to merge after your own review.
NEEDS WORK means there are specific issues to fix. The Reviewer lists them.
BLOCK means a fundamental problem was found. The implementation may need rethinking.

A BLOCK on your first run is not unusual. Read the Reviewer's feedback in .pipeline/review.md. It often highlights a mismatch between the spec and the implementation, or a security concern the Tester missed.

This is the system working as designed. The Reviewer is your last line of defense. You can refine your feature request and re-run /ship once you understand what went wrong.

help me understand why my Reviewer returned a BLOCK verdict and what to do next

Secret mission

Add Auto-Cleanup and Retry Logic

Your pipeline runs once and stops. But what happens when the Reviewer says NEEDS WORK? Right now, you read the feedback and manually re-run the Coder yourself. Add an auto-cleanup mechanism and a conditional retry loop so the pipeline can self-correct before surfacing issues to you.

Clean Up Your Resources

This project runs entirely locally, so there are no ongoing costs. The only expense is Claude Code usage on your Pro plan during pipeline runs, which is included in your subscription.

Decide whether to keep your resources running, pause them to come back later, or delete them entirely.

Resources you used:

.claude/agents/ directory containing 4 agent definition files (planner, coder, tester, reviewer).
.claude/commands/ directory containing the ship.md orchestrator command.
.pipeline/ directory containing ephemeral handoff files (gitignored).
setup-agent-pipeline git branch.

Keep everything running

No action needed. Choose this if you want to keep using the pipeline on your codebase.

Commit .claude/agents/ and .claude/commands/ to your repo so your team can use the pipeline.
The .pipeline/ folder stays gitignored. It cleans itself automatically at the start of each /ship run.
Merge your setup-agent-pipeline branch when you're ready to make the pipeline part of your main codebase.

Pause - I'll come back to this later

There are no running processes or cloud resources to pause. All pipeline files are static configuration that sits on disk.

Your agent definitions and orchestrator command remain in place until you return.
To free up space in the .pipeline/ folder, delete its contents by running:

rm -f .pipeline/*

When you come back, the next /ship run will regenerate these files automatically.

Delete - I don't want to use this again

Remove all project resources and start fresh. This deletes the agent definitions, orchestrator command, and handoff files.

Delete the agent definitions, orchestrator command, and pipeline folder by running:

rm -rf .claude/agents/
rm -rf .claude/commands/
rm -rf .pipeline/

If the .claude/ directory is now empty, remove it too:

rmdir .claude/ 2>/dev/null

Remove the .pipeline/ entry from your .gitignore if you added it solely for this project.
Switch back to your main branch and delete the feature branch:

git checkout main
git branch -D setup-agent-pipeline

That's a Wrap!

Nice work! You just built a fully autonomous development pipeline that plans, codes, tests, and reviews features while you step away from the keyboard.

You've learned how to:

Build a 4-agent specialist pipeline (Planner, Coder, Tester, Reviewer) with isolated context windows and strict role boundaries.
Create a cost-efficient model routing strategy that sends expensive reasoning to Opus and routine execution to Sonnet.
Wire a single /ship orchestrator command that chains all four agents via file-based handoffs in the .pipeline/ folder.
Secret Mission: Added auto-cleanup between runs and a conditional retry loop that feeds reviewer feedback back to the Coder when the verdict is NEEDS WORK.

Ready to quiz yourself?