Quickstart Guide
Go from idea to shipped feature in minutes, not days.
What is One Shot Ship?
One Shot Ship gives Claude Code a squad of AI specialists instead of one general assistant. Each command activates experts who follow battle-tested workflows with built-in quality guardrails.
Instead of "vibe coding" where you hope the AI gets it right, OSS enforces:
- ✓Test-Driven Development — Tests written first, always
- ✓Safe Git practices — Never pushes to main, always uses PRs
- ✓Domain expertise — TypeScript, React, Python specialists know their craft
- ✓Your workflow — Adapts to your branching strategy, test framework, CI
Installation
Set up the plugin in Claude Code with these four steps:
1. Add the marketplace
plugin marketplace add 501336north/one-shot-ship-plugin
2. Install the plugin
When prompted, select "Install for you (user scope)"
3. Enable auto-update
Third-party marketplaces have auto-update disabled by default. Enable it to receive updates automatically:
- Run
/pluginto open the plugin manager - Go to the Marketplaces tab
- Select the One Shot Ship marketplace
- Click Enable auto-update
4. Restart Claude Code
Close and reopen Claude Code to load the plugin.
Getting Started
After installing the plugin, authenticate with your OSS account:
/oss:login
This connects Claude Code to your subscription and enables all commands.
Working with an existing codebase?
If you're adding One Shot Ship to an existing project, run the onboard command once first. It analyzes your codebase and generates context that makes all other commands smarter.
/oss:onboard
This only needs to run once. Re-run after major refactors or architecture changes.
The Core Workflow
Four commands take you from idea to production:
/oss:ideate
Transform a vague idea into a concrete, actionable design. Claude asks clarifying questions, explores trade-offs, and produces a clear specification.
/oss:plan
Generate a TDD implementation plan with tasks, test cases, and sequencing. Every task starts with a failing test.
/oss:build
Execute the plan with strict RED-GREEN-REFACTOR discipline. Writes test, sees it fail, writes minimal code to pass, refactors.
/oss:ship
Quality check, commit with conventional message, create PR. Optionally auto-merge with --merge flag.
Your First Feature
Let's build something. Start with an idea:
Claude will ask questions like:
- • Should it persist the preference (localStorage, database)?
- • Should it respect system preference initially?
- • What components need to support dark mode?
Once you've refined the design, plan the implementation:
This creates a task list with test-first approach. Then build it:
Watch as Claude writes tests first, implements minimal code, and refactors. When complete, ship it:
The TDD Cycle
For granular control, use the London TDD commands directly:
/oss:red
Write a failing test first. Design the interface through mock expectations. The test must fail before proceeding.
/oss:green
Write the minimum code to make the test pass. No gold-plating, no extra features. Just enough to satisfy the test.
/oss:refactor
Clean up the code while keeping tests green. Remove duplication, improve names, restructure — but don't change behavior.
Why London-Style TDD?
OSS uses London (Outside-In) TDD, not Chicago (Inside-Out). The difference matters:
London (OSS uses this)
- • Start at system boundaries
- • Design interfaces through mocks
- • Mock all collaborators
- • Behavior verification
Chicago
- • Start at lowest level
- • Discover design as you go
- • Minimal mocking
- • State verification
London TDD produces cleaner interfaces, faster tests, and better separation of concerns. It's how world-class teams ship reliable software.
Key Commands
| Command | Purpose |
|---|---|
| /oss:quick | Fast-track small tasks with TDD guarantees |
| /oss:review | Multi-perspective code review |
| /oss:test | Run comprehensive E2E tests |
| /oss:debug | Systematic debugging workflow |
| /oss:audit | Security vulnerability scanning |
| /oss:deploy | Deploy to production with checks |
| /oss:monitor | Watch production health |
| /oss:rollback | Emergency rollback to previous version |
Tips for Success
Trust the process
TDD feels slow at first. It's not. You're trading debugging time later for clarity now. The tests are the specification.
Start with /oss:ideate
Don't skip straight to building. The ideate phase catches ambiguity and edge cases before you write any code.
Use /oss:quick for small stuff
Bug fixes and minor features don't need the full workflow./oss:quick "fix the typo in header" gets it done fast.
Let Claude ask questions
The AI will ask for clarification. This is a feature, not a bug. Better to clarify now than refactor later.
Need Help?
We're here to help you ship with confidence.