TL;DR — AI coding agents move fast, but they don't naturally slow down when a problem calls for a more careful plan. SpecDevShip wraps a 19-skill spec-driven workflow around your agent: it triages every request, decides whether it's small ("light tier") or genuinely risky ("full tier"), investigates bugs before proposing fixes, and locks approved decisions so they can't be quietly rewritten mid-build. Read on for how each piece works — or skip straight to the free field guide below.
Key takeaways:
- Vibe-coding trades a paper trail for velocity — and the paper trail is what you actually need three weeks later.
- A tier decision made explicitly, every time, keeps small changes small and catches big changes before they sneak through as small ones.
- Bugs get a cited, verified root cause before any fix is proposed — never a guess dressed up as a diagnosis.
- Once you approve a spec document, it stays approved — no silent mid-implementation rewrites.
- The whole workflow is agent-agnostic; it currently ships as the Claude Code Edition, with more agent editions coming as free updates.
You open a fresh session, type a sentence describing what you want, and thirty seconds later there's working code on your screen. It's a genuinely great feeling — for about a week. Then you notice the same app has three different naming conventions, a "temp-fix-2" folder nobody remembers the context for, and a bug that took an hour to fix because the agent guessed at a cause instead of finding one. You didn't lose momentum. You lost the thread.
This is the quiet cost of vibe-coding with an AI agent: velocity without a system. Today's AI coding agents are extraordinarily capable, but capability isn't the same as discipline, and discipline is usually the first thing to go when you're moving fast solo, with no teammate around to ask "wait, did we already decide this?"
The problem isn't the AI. It's the missing workflow.
Professional software teams don't wing it, even when they move fast. They scope an idea before building it. They decide up front whether a change is a small tweak or something that needs real design thought. They diagnose a bug before proposing a fix. They keep a record of decisions so nobody re-litigates them by accident three weeks later.
None of that goes away just because your "team" is now you and an AI agent. If anything, it matters more — because an AI agent will happily generate a confident, plausible-sounding plan for the wrong problem, at the same speed it would generate the right one. Without a workflow wrapped around it, an agent optimizes for "produce something that looks done," not "produce the right thing, in a way you can trust and revisit."
What a spec-driven workflow actually buys you
"Spec-driven development" sounds like paperwork. In practice, for solo builders, it buys you three very concrete things:
A paper trail you can actually trust. When a decision is written down and explicitly approved — not just implied by a chat scrolling past — you can come back to it in three months and know it was a deliberate choice, not a guess that happened to compile.
A brake pedal for AI over-engineering. Left alone, an AI agent doesn't reliably distinguish between "add a button" and "redesign the data model." A workflow that forces a tier decision up front — is this small, or does it actually need real requirements and architecture? — keeps small changes small and flags big changes before they quietly become big changes mid-implementation.
Root causes instead of guesses. "It's probably a race condition" is not a diagnosis, it's a shrug with technical vocabulary. A workflow that separates investigation from fixing means the agent has to find the actual cause, cite it, and get your sign-off before a single line of the fix gets written.
Meet SpecDevShip: 19 skills, one disciplined workflow
SpecDevShip is a skill pack for AI coding agents — 19 purpose-built skills that turn "describe what you want" into an actual spec-driven pipeline, from a raw idea to a shipped, documented change. It's currently shipping as a Claude Code Edition (more agent editions are on the way — see "Built once, works everywhere your agent runs" below), and it hands off between stages automatically, the way a good teammate would. Here's the whole pipeline at a glance:
flowchart TD
idea(["idea"]) --> analysis["idea-analysis<br/>product.md check, then<br/>build, investigate, analyze, or<br/>set creative direction first?<br/>plan mode — wait for go-ahead"]
idea -. "any time" .-> handoff["handoff<br/>export context to a<br/>new session/agent"]
analysis -->|"bug, unknown cause"| investigate["investigate"]
investigate --> findings["./investigations/<name>/findings.md"]
findings --> back1["back to idea-analysis —<br/>scopes the fix into its own<br/>./spec/<name>/ folder"]
back1 --> tier{"Tier?"}
analysis -->|"existing app/design/art/product,<br/>understand it first"| explore["app-analysis /<br/>design-analysis /<br/>art-analysis /<br/>product-analysis"]
explore --> findings2["./analysis/<name>/<br/>*-findings.md, art-bible.md, product.md"]
findings2 --> back2["back to idea-analysis —<br/>scopes the work (Design-First)<br/>into its own ./spec/<name>/ folder"]
back2 --> tier
analysis -->|"need to originate new<br/>design/art direction"| direct["design-direction /<br/>art-direction<br/>(pre-production)"]
direct --> predocs["./pre-production/<name>/<br/>design-system.md, art-bible.md"]
predocs --> back3["back to idea-analysis —<br/>scopes the work into its own<br/>./spec/<name>/ folder"]
back3 --> tier
analysis -->|"genuinely new product,<br/>no product.md yet"| proddir["product-design<br/>(dialogue, not delegated<br/>autonomy)"]
proddir --> proddoc["./spec/<founding>/product.md"]
proddoc --> back4["back to idea-analysis —<br/>continues scoping with<br/>product.md in hand"]
back4 --> tier
analysis -->|"clear feature or fix"| tier
tier -->|"Light — default"| plan["spec-plan<br/>implementation_plan.md<br/>draft → approve"]
tier -->|"Full — rare"| fulltier{"Requirements-First or<br/>Design-First?"}
req["spec-requirements"]
fulltier -->|"blank slate"| req
fulltier -->|"existing app/design/art<br/>to ground it in"| explore2["app-analysis /<br/>design-analysis /<br/>art-analysis /<br/>product-analysis<br/>(if not already run)"]
explore2 --> req
subgraph full["Full tier — new app / major architecture"]
direction LR
req --> tech["spec-tech"] --> design["spec-design"] --> tasks["spec-tasks"]
end
tasks -. "spec-sync after edits" .-> sync(("sync"))
plan --> implement["implement-tasks<br/>implement → verify → check off → commit"]
full -->|"plan approved"| implement
implement --> wrap["wrap-up<br/>walkthrough.md, README,<br/>CHANGELOG under Unreleased"]
wrap --> release["prepare-release — on request<br/>semver bump, cuts Unreleased into a version,<br/>RELEASE_NOTES.md"]
It starts with triage, not code
Every piece of work enters through Idea Analysis. Before anything gets built, it checks whether this is a routine feature, a bug with an unknown cause, or a request to understand something that already exists — and whether the product it belongs to even has a clear, written identity yet. Nothing gets built on a foundation nobody agreed to.
Two tiers, so small stuff stays small
Most of what you build in a day is genuinely simple — a new endpoint, a UI tweak, a refactor. SpecDevShip calls this light tier: one plan document, a focused verification script, done. Only work that's actually new-app-scale or introduces real architectural risk gets bumped to full tier, with proper EARS-format requirements, a tech-stack decision, an architecture doc, and a numbered task checklist.
| Light tier (most work) | Full tier (rare) | |
|---|---|---|
| When | Most features, fixes, UI work, refactors | New app, or a feature that introduces real new architecture/technical risk |
| Docs | implementation_plan.md |
requirements.md → tech.md → design.md → tasks.md |
| Tests | Focused regression script + manual verification | Coverage-targeted automated test suite |
You don't have to remember to make this call yourself — the workflow makes it explicitly, with its reasoning shown, every time.
Investigate before you fix
Bug reports don't skip straight to a patch. The Investigate skill restates the symptom, follows the evidence through the actual codebase, and cites the root cause by file and line before any fix is proposed — with a Mermaid diagram if the cause is a chain of interacting steps, not a wall of prose. Only then does the fix get its own properly scoped spec.
Reverse-engineer before you extend
Redesigning something that already exists — an old app, a competitor, a Figma file someone handed you — is a different problem than building from nothing. SpecDevShip's analysis skills (app, design, art, and product analysis) extract what actually exists — behavior, visual system, art direction, even the product's own stated identity — before a single new requirement gets written, so your "redesign" is grounded in reality instead of a half-remembered impression of the old app.
Product, design, and art direction as real roles
Two skills act like hired specialists rather than autopilot: Product Design runs a structured interview to turn a raw idea into a real product concept — problem, audience, value proposition, non-goals — through dialogue, not a document dropped on you unasked. Design Direction and Art Direction work the opposite way: pitch 2–3 real directions, get your explicit pick, then run with full creative autonomy to a finished design system or art bible. Different jobs need different collaboration models; SpecDevShip doesn't flatten them into one generic "AI does everything" mode.
Approval gates that actually hold
Every spec document carries a draft / approved status. Once you approve something, SpecDevShip won't quietly edit it out from under you — not as a "quick fix," not mid-implementation. Changing an approved decision requires a real, visible request and your explicit agreement to reopen it. That's the difference between a tool that assists you and a tool that argues with your future self.
What's in the box
Nineteen skills covering the full lifecycle: intake and tier decisioning, root-cause investigation, four flavors of existing-material analysis, product/design/art origination, the full light- and full-tier spec pipelines, implementation with per-task commits, wrap-up documentation, spec-sync drift checking, and release prep with automatic semver detection from your commit history. Every skill hands off to the next one explicitly — you're never left wondering what happens after a document gets approved.
Built once, works everywhere your agent runs
The workflow itself — the tier decision, the investigation discipline, the approval gates — isn't tied to any one AI coding agent. The Claude Code Edition is the first implementation, available now. Editions for other AI coding agents are planned, and they'll ship as free updates to the same Skill Pack, not as separate purchases.
Who this is for
If you're a solo developer or indie hacker shipping real products with an AI coding agent — not a weekend toy, something you'll still be maintaining in a year — this is built for exactly that. It's overkill for a one-off script. It's the thing that keeps a growing codebase from turning into an archaeology dig six months in.
Get the free field guide
We wrote a short, practical eBook walking through the whole workflow in more depth — the tier decision framework, the investigate-before-you-fix discipline, and how the approval gates actually work day to day. It's free. Grab your copy →
If you want the full 19-skill pack installed and ready to go in your own project, that's available separately as a one-time purchase.