The Main Workflow
This is the happy path for building anything new. You don't always need every step — for a small change to something that already exists, jump straight to /soloship:plan. For a brand-new idea, start at the top.
Should you build this at all? YC-style forcing questions that challenge whether the thing is worth building — and if so, using what and how. Earliest stage: before you've committed to anything.
Skip if: You already know you want to build it, or you're adding a feature to something that already exists.
Figure out what you want and why. Talks through the idea before any code gets written. Helps you spot whether there's a simpler version that solves the same problem.
Skip if: You already ran /office-hours (it covers the same ground), or you already know exactly what to build.
Before writing the plan, mock it up. Looking at it makes problems obvious that you'd miss in conversation. Use Stitch, Figma, even pen and paper.
The "design inspiration folder" trick
- Make a folder in your project:
docs/design-inspiration/ - Go to Pinterest and search for what you're building — e.g. "business dashboard design", "onboarding screen", "pricing page".
- Screenshot the ones you like and drag them into that folder.
- When you run
/soloship:plan, say "make it look like the design inspiration photos indocs/design-inspiration/". Claude will look at the images and match the vibe.
Stress-test the idea before planning. Asks the hard questions: edge cases, hidden assumptions, what happens when things go wrong. Refuses to move on until you and the AI clearly agree on what's being built.
Skip if: The change is small and obvious. Use for anything non-trivial.
Write the step-by-step plan. Lists which files will change, what decisions are being made, and why. Searches your past solutions first so you don't repeat yourself.
This is the deliverable from planning mode. The plan file gets saved so you (or a fresh AI session) can follow it later.
Build it. Reads the plan, sets up a working branch, and writes the code step by step.
Ship it carefully. Full deploy pipeline: review the diff, run tests, update the changelog, create a clean commit, push, open a pull request, verify it's live.
For emergency hotfixes, use /soloship:shipfast instead — see "When Things Go Wrong" below.
Off the Main Path
Situational commands. Use them when the situation calls for it — skip them otherwise.
Starting a Project
Quick briefing on a codebase. Reads the project docs and recent history so you (or a fresh Claude session) know what you're walking into.
Use when: Opening a project for the first time, or coming back after a break.
Deep investigation of an existing codebase. Maps the architecture, scores the quality, lists what needs attention.
Use when: You inherited a project, or you want a checkup on what's there.
Configure project governance — the rules, docs, and safety hooks tailored to this specific project.
Use when: After an audit, or when setting up a brand-new project.
Nailing Down What to Build
Write a formal spec with clear acceptance criteria. Defines exactly what "done" looks like.
Use when: The feature is too complex for a quick plan, or you want a record of what was agreed on before any code gets written.
When Things Go Wrong
Systematic debugging. Investigates the root cause before suggesting any fix — no guessing, no "try this and see." Iron rule: no fix lands until the actual cause is found.
Use when: Something's broken, an error appeared, or behavior changed and you don't know why.
Emergency deploy. Minimum safety checks, maximum speed: lint, test, build, commit, push, deploy. Skips the deeper review.
Use when: Production is broken, you already fixed it locally, and you need it live now. Not for normal work — use /soloship:shipthorough for that.
npx soloship rollback in your terminal. Details in the Terminal Commands section below.
Getting a Second Opinion
Multi-perspective review. For plans: runs engineering, product, and design lenses over the plan. For code: structural + adversarial + design checks. Catches things one perspective alone would miss.
Use when: Before shipping anything significant. Or when something feels off and you can't put your finger on it.
Visual design audit. Catches spacing issues, weak hierarchy, and the generic "AI slop" look that makes sites feel templated.
Use when: Your site works but looks "off" and you want a designer's eye on it.
Finishing a Branch
You're done coding, tests pass, and now you need to decide what to do with the branch — merge it, open a pull request, or just clean it up. Walks you through the options instead of assuming you want the full ship pipeline.
Use when: Implementation is complete but you're not ready to commit to /soloship:shipthorough yet. Good middle ground.
Tidying Up
Maintenance for the project's knowledge files. Deduplicates saved solutions, prunes stale references, archives old plans, and rebuilds the index of past learnings.
Use when: The docs/ folder has grown messy, or every few weeks as housekeeping.
Power Tools (Bonus Commands)
These slash commands aren't part of Soloship itself — they come from other plugins installed alongside it (gstack, Compound Engineering, Impeccable). They work the same way: just type them in Claude Code. Use them when you want more horsepower than the main workflow gives you.
Reviewing a Plan Before You Build
After /soloship:plan writes a plan file, run one of these to pressure-test it.
Runs all four reviews in sequence (engineering, CEO, design, developer experience) and auto-decides on minor issues. Only stops to ask you about the close calls and taste decisions.
Use when: You have a plan and you want it fully reviewed without answering 30 questions.
Engineering manager's critique. Walks through architecture, data flow, edge cases, and test coverage. Catches problems before they become bugs.
Use when: You want to make sure the plan is technically sound before any code gets written.
CEO/founder critique. Pushes you to think bigger, question the premise, find the 10-star version of what you're building.
Use when: You suspect the plan is too small, too safe, or solving the wrong problem.
Designer's eye on the plan. Rates each design dimension 0–10 and tells you what would make it a 10.
Use when: The plan has UI in it and you want a designer's perspective before building.
Advanced Implementation
Alternatives to the default /soloship-implement when you want a different execution strategy.
Runs a plan in controlled batches with check-ins between each batch. You review progress, give feedback, then it continues. Slower and more careful than the default.
Use when: The plan is risky or complex and you want to inspect work in chunks rather than at the end.
Each task in the plan gets its own fresh AI subagent, with a code review between tasks. Lets independent pieces move in parallel without polluting one big conversation.
Use when: The plan has multiple independent tasks that don't depend on each other — faster than doing them all in one long session.
Sets up an isolated worktree — a separate copy of your project the AI can experiment in without touching your main workspace. Think of it like a sandbox attached to the same project.
Use when: Starting risky feature work, or when you want to keep your main workspace clean while the AI explores in parallel.
Visual Design Help
Builds your project a full design system — typography, colors, spacing, motion — and saves it as DESIGN.md. Generates font and color preview pages.
Use when: Starting a new project's UI with no design system yet.
Generates multiple design variants side-by-side so you can pick what you like. Like trying on five outfits instead of describing what you want.
Use when: You don't know what you want yet and need to see options.
Turns an approved mockup into production-quality HTML/CSS. The handoff from design to real code.
Use when: You've approved a design (from /design-shotgun, Figma, or a plan) and want it implemented.
Visual audit of your live site. Like /soloship:design-review but pointed at a running URL instead of code.
Use when: The site is deployed and you want a designer's eye on what's actually live.
Testing & Quality
Tests your site like a real user — clicks things, fills forms, finds bugs — and fixes them. Each fix gets its own clean commit.
Use when: A feature is "done" and you want to make sure it actually works end-to-end.
Same as /qa but report-only — finds the bugs, doesn't touch the code. You decide what to fix.
Use when: You want to know what's broken before deciding how to handle it.
Drives a headless browser to take screenshots, click around, and verify state. The building block under /qa.
Use when: You want Claude to actually look at your site instead of guessing.
Performance check. Tracks page load times, Core Web Vitals, and bundle sizes. Compares before/after so you spot regressions.
Use when: The site feels slow, or before/after a big change.
Chief Security Officer mode. Audits secrets, dependencies, CI/CD pipelines, AI/LLM-specific risks, and OWASP Top 10.
Use when: Before launching anything that handles auth, payments, or user data.
Pre-merge code review. Looks at the diff against the main branch for SQL issues, trust boundaries, and structural problems.
Use when: You're about to merge a branch and want one more pass.
Terminal Commands
Run these in your terminal (the black window for typing commands directly), not inside Claude Code. They manage Soloship itself.
First-time setup. Adds Soloship's guardrails, rules, and safety hooks to the current project. Run once per project.
Refresh hooks, rules, and CI configuration to match the latest Soloship version. Safe to run anytime.
Health check. Looks at your Claude Code setup and tells you if anything Soloship expects is missing or out of date.
Undo everything the AI did in the current session. Your pre-session work stays intact. Your panic button when something went sideways.
What's Always On
Once npx soloship init runs in a project, several things happen automatically — no command needed from you:
- ✓ Security scans run when files change, catching leaked passwords or risky code.
- ✓ Snapshots of your work get taken before risky AI changes, so
rollbackcan rescue you. - ✓ Architecture rules (the "fitness functions") check that big changes don't sneak in unnoticed.
- ✓ Plans, decisions, and learnings get saved to
docs/so nothing gets lost between sessions.
The slash commands above are your workflow. The safety net is always running underneath.
- → Building something new? Start at step 1 of the Main Workflow.
- → Something's broken? Use
/soloship:debug. - → You don't know which command to use? Just ask Claude — describe what you're trying to do and it'll pick the right one.