SSD — Shippable States Development para Claude Code
AlexHorovitz/skills
Metodologia SSD: mantenha seu código sempre em estado de produção
Ver no GitHubSkill chain que implementa Shippable States Development (SSD), uma metodologia de engenharia pragmática para manter software pronto para produção em todas as fases. Coordena design, build, review e deploy mantendo a invariante: se não pode ser enviado agora, não está pronto.
Instalação
npx convez-ai AlexHorovitz/skills1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Desenvolvimento coordenado de features em ciclos curtos
- Garantir que código está sempre deployável
- Organizar sprints com design, build, review e deploy contínuos
Veredito

Skill maduro que implementa uma metodologia bem-documentada para ciclos de desenvolvimento curtos e código sempre pronto para produção. Excelente para equipes pequenas que precisam de disciplina sem overhead burocrático, com artefatos SSD auditáveis no próprio repositório.
README
A tradução para o português deste README ainda está na fila.
InsanelyGreat's SSD — Claude Code Skills
Library version: see VERSION · changelog in CHANGELOG.md
A free-for-personal-use skill set for Claude Code that implements Shippable States Development (SSD) — a pragmatic engineering discipline for solo developers and small teams, originated by Alex Horovitz and published at insanelygreat.com. Platform-adaptive: web, iOS, Android, macOS, and headless.
Core invariant: If you can't ship it right now, you don't have a product — you have a construction site.
Dogfood. As of v1.19.0 (per ADR-0008) this repo tracks its own SSD artifacts under .ssd/features/ — briefs, architect specs, coder-status reports, and code-reviews for every epic shipped in v1.5.0+. Read the history of how the methodology was built using the methodology itself. The epics so far:
ssd-skill-upgrades— 9-iteration epic implementing v1.5–v1.14 (5 ADRs: iterations,current.ymlsplit, rails, profiles, gate execution).parallel-features— concurrent feature workstreams (3 iterations, v1.15–v1.17; ADR-0007).ssd-commit-split— the selective-commit convention that makes this very list visible (2 iterations, v1.18–v1.19; ADR-0008).ssd-profile-audit— made the sub-skills profile-aware on substance not tone (v1.20; ADR-0010). Later removed wholesale by SSD 2.0 — see below; the dogfood record keeps the reversal honest.ssd-upgrade—/ssd upgrade: detect SSD convention drift and migrate a project forward idempotently (4 iterations, v1.21–v1.24; ADR-0013).ssd-skill-chapter-split— split thessd/SKILL.mdmonolith into a thin spine + on-demand chapters (v1.25; the ADR-0012 2.0 prerequisite P1).ssd-2.0-cuts— SSD 2.0, the subtractive milestone (ADR-0012, greenlit viassd-2.0-greenlight). Three iterations: (A) remove thedeveloper_profile/teaching_modeconcept library-wide — BREAKING, v2.0.0; (B) collapse to one surface, progressively disclosed — v2.1.0; (C) the/ssd upgradedeprecation path via theobsoleted_inmanifest field — v2.2.0.
Methodology
This repository is the official Claude Code skill implementation of Shippable States Development. The canonical methodology pages are:
- 📘 Shippable States Development (SSD) — the methodology in full
- 📗 The InsanelyGreat Guide — practical implementation
- 📙 Agile² — companion manifesto on process-as-tool
- 📕 Solo Developer's Engineering Manifesto
- 📒 The Ratchet Principle: Code Quality Without a QA Team
If this skill set has helped you ship better software, a star on this repo and a link back to insanelygreat.com keeps the methodology discoverable.
Verify your installed version matches the guide at insanelygreat.com/guide.html:
cat ~/.claude/skills/VERSION
What Is SSD?
InsanelyGreat's SSD keeps software in a deployable, production-ready state at all times. It synthesizes continuous deployment, trunk-based development, and feature flags into a workflow a single developer can actually maintain — amplified by Claude Code at every step.
Five principles:
- Constant Production Parity — Deploy "Hello World" on Day 1. Deployment is never "the hard part."
- The Shippable State Invariant — Every session ends with passing tests and nothing broken.
- Feature Flags Over Feature Branches — All work on main, behind flags, off by default.
- The Ratchet Principle — Forward progress only. No WIP commits, no "fix tomorrow."
- Scope Flexibility Is a Feature — Cutting scope is engineering judgment, not failure.
Where to Start
Step 1: /ssd-init once per project. First-run housekeeping — creates the .ssd/ working
directory (gitignored), writes .ssd/project.yml with your stack/framework/platform, creates
docs/decisions/ + docs/runbooks/ + docs/architecture/, and runs SSD prerequisite checks
(CI/CD, test harness, feature-flag system, deployed hello-world). Idempotent — safe to re-run.
/ssd phases refuse to proceed until init has run.
Step 2: /ssd every session. Since v2.1, SSD has one surface, progressively disclosed
(ADR-0012 Pillar 3). The everyday path is the bare
command — it reads your project state and proposes the next action, naming the explicit step it takes
so you never have to memorize the verb set.
/ssd-init ← first time only (prerequisite to all /ssd phases)
/ssd ← auto-detect state and propose the next action (the path you use)
/ssd start ← bootstrap a new project (Walking Skeleton) when there's no state to detect yet
The full verb set (feature, design, gate, milestone, verify, ship, audit, upgrade)
stays a first-class escape hatch — every phase is still directly invokable. The command path is a
thin alias that lowers into the conversational path, not a co-equal surface. See
The Meta-Skill below for the full set.
Skill Taxonomy
| Type | Skills | When you invoke directly |
|---|---|---|
| Bootstrap | ssd-init | Once, at project start (or when .ssd/ has drifted) |
| Orchestrator | .ssd | Always — start here after init |
| Domain | architect, coder, systems-designer, refactor | When working outside the SSD workflow |
| Review | code-reviewer, codebase-skeptic, software-standards | On-demand or via SSD |
| Reference | methodology | When you want to understand SSD doctrine |
Skills
/ssd-init — Project Bootstrap
Run once per project (idempotent; safe to re-run). Creates .ssd/ (gitignored working directory),
.ssd/project.yml (detected stack/framework/platform), .ssd/current.yml (active workstreams),
docs/decisions/ / docs/runbooks/ / docs/architecture/ (committed decision records), and reports
SSD prerequisite status (CI/CD, tests, flags, deploy).
/ssd — The Meta-Skill
The orchestrator. Sequences the right sub-skills for each development phase. Requires ssd-init to
have run. The bare /ssd auto-detects state and proposes the next action; the explicit verbs below
are the escape hatch when you want to force a specific phase.
/ssd — Auto-detect state and propose the next action (the everyday path)
/ssd start — New project or major feature: Walking Skeleton setup
/ssd feature — Active development: design → build → review → deploy loop
/ssd design — Bundled architect + systems-designer pass (single invocation)
/ssd milestone — Post-sprint consolidation: deep audit + targeted refactor
/ssd verify — Remediation verification (mandatory after milestone refactors)
/ssd gate — Shippable state check only (code-reviewer + methodology rules)
/ssd ship — Deploy readiness check only (systems-designer checklist)
/ssd audit — Adversarial comparative review (nuclear option)
/ssd upgrade — (v1.21+) report/migrate SSD convention drift (--apply · --adopt)
Parallel workstreams (v1.16+, ADR-0007) — manage more than one feature at once:
/ssd feature new <slug> — scaffold a new workstream: branch + (optional) worktree + brief + state entry
/ssd switch <slug> — pause the current workstream (capture a handoff note), resume the target
/ssd worktree <slug> … — explicit git-worktree lifecycle (add | remove) for a workstream
Sub-Skills
| Skill | Role |
|---|---|
/ssd-init | First-run housekeeping: creates .ssd/ tree, writes project.yml, runs prerequisite checks (prerequisite to all /ssd phases) |
/architect | Design: models, services, API contracts. Platform-adaptive (web, iOS, Android, macOS, headless) |
/systems-designer | Production readiness: reliability, observability, deployment safety |
/coder | Implementation from spec (Python, TypeScript, Swift, Ruby, Java, C#, PHP, Go, Rust, C/C++, Obj-C) |
/code-reviewer | PR gate: BLOCKER/MAJOR findings block merge |
/codebase-skeptic | Deep architectural critique through 10 expert lenses |
/software-standards | Adversarial comparative audit |
/refactor | Post-ship targeted improvement |
/methodology | SSD methodology reference + /methodology score self-adherence metric |
Installation
Clone the repo into your Claude Code skills directory:
git clone https://github.com/AlexHorovitz/skills ~/.claude/skills
Then, from your project root, run the bootstrap once:
/ssd-init
After that, invoke any SSD phase:
/ssd feature
/ssd milestone
/ssd gate
Or call a sub-skill directly when working outside the SSD workflow:
/coder
/code-reviewer
/codebase-skeptic
GitHub Issue Tracking (optional)
SSD can mirror workstream state to GitHub issues so teammates, reviewers, and future-you see live
progress without a local checkout (ADR-0014).
It is opt-in and one-way — local .ssd/ is always the source of truth; SSD never reads issue
state back to mutate a workstream.
The convention:
| Maps to | Label | Title | |
|---|---|---|---|
| An ADR | an epic issue | ssd:epic | [ADR-NNNN] <decision title> |
| A workstream | a feature issue, linked to its epic | ssd:feature + one ssd:phase/<phase> | <slug>[#<iter>]: <one-line> |
On each phase advance the orchestrator ensures the epic + feature issues exist, swaps the
ssd:phase/* label, and refreshes a machine-managed body block. On done it closes the feature
issue; the epic closes once its last child closes and no further iteration is planned.
Enable it in .ssd/project.yml:
integrations:
- type: github
enabled: true
issue_tracking: on # default off → feature dormant, zero network calls
auto_close: false # default false → prompt once before closing; true → close automatically
Requires the gh CLI, authenticated. With the toggle off or gh unavailable, the mirror is a silent
no-op (best-effort — a sync failure never blocks SSD work). The mechanism is
methodology/issue-sync.sh.
Hard Rules
- No merge without a clean
/ssd gate— No BLOCKER or MAJOR findings. No exceptions. - No incomplete work on main without a feature flag — WIP commits on main are banned.
- Tests must pass before and after every change — "I'll fix the tests tomorrow" is not a shippable state.
- Refactor only after shipping — Separate PRs, never mixed with feature work.
- Deploy beats perfection — Reduce scope rather than delay a deploy.
- Production parity from day one — If you haven't deployed to production yet, that is your next task.
Contributing
Contributions are welcome. All content in this repo is Markdown — there is no code to compile or test suite to run. The bar for a good contribution is whether Claude follows the guidance accurately and produces better outcomes than it would without it.
What to contribute
- Fixes — Incorrect advice, outdated API references, broken examples, typos
- Additions — Missing patterns, platforms, or frameworks that belong in an existing guide
- New platform guides — A new
architect/subdirectory for a platform not yet covered (e.g.,watchOS,tvOS,embedded,visionOS) - New framework guides — A new
architect/web/frameworks/file for a web framework not yet covered (e.g.,sveltekit,remix,nestjs). Copyarchitect/web/frameworks/TEMPLATE.mdand fill in each section to ensure structural parity with existing guides - New skills — A complete
SKILL.mdfor a workflow not yet covered
What not to contribute
- Promotional content, vendor recommendations without technical rationale
- Vague or aspirational guidance ("always write clean code") without actionable specifics
- Anything that contradicts the SSD core invariant (shippable state at all times)
How to submit
- Fork the repo
- Make your changes on a branch
- Open a pull request with a clear description of what changed and why
Writing style
These files are read by Claude, not rendered as a website. Write for clarity and precision over prose elegance.
- Be specific. "Use PostgreSQL" is better than "use a relational database."
- Give the rule, then the rationale. State the decision first, explain why second.
- Include the counter-case. Every "always do X" is more useful when paired with "except when Y."
- Concrete examples over abstractions. A short code block or table beats three paragraphs.
- Match the existing tone. Direct, opinionated, no hedging.
File structure conventions
Each skill or guide follows this pattern:
skill-name/
└── SKILL.md — the skill itself (invoked by /skill-name in Claude Code)
architect/
└── platform/
└── GUIDE.md — platform-specific reference, loaded by the architect skill
SKILL.md and GUIDE.md files begin with a one-line license reference: <!-- License: See /LICENSE -->. The full license terms live in the LICENSE file at the repository root.
Skill Hygiene Contract
Every skill in this directory MUST conform to these conventions. Skills that violate them are flagged
by the skill linter (when present) and block /ssd start in strict mode.
File structure:
SKILL.mdbegins with# Skill Nameas the first line. The license pointer (<!-- License: See /LICENSE -->) and**Version:** X.Y.Zfollow the title, not precede it. License is a single-line pointer — not an inlined 13-line preamble.- Skills whose
SKILL.mdexceeds 400 lines MUST split intoSKILL.md(philosophy + workflow + pointers) plus one or morereferences/*.md(or topically-named sibling files) with detailed patterns, checklists, and examples. - Every
SKILL.mdends with a## Changelogsection. Each version bump adds a dated entry describing what changed and why.
Interface discipline:
- Every skill's
## Interfacetable declares explicit input/output paths (e.g.,.ssd/features/<slug>/01-architect.md) — not just downstream skill names. - Every primary output artifact has YAML frontmatter conforming to the shared schema documented in
ssd/chapters/state.md§ "Structured Output Requirements." - Every skill's Purpose contains a "When NOT to use" clause disambiguating it from any overlapping
skill (see
ssd/chapters/skills.md§ "Resolving Skill Overlap").
Header / license ordering:
- Title-first:
# Skill Nameis line 1. - Metadata block follows: license pointer, version.
- Content follows metadata.
Future work:
- Contract tests (
skills/tests/): fixtures that assert each skill produces output conforming to its declared frontmatter schema and required sections. Tests contract, not quality. Not yet implemented — intended layer for preventing silent skill regressions. - Cross-skill schema contracts: shared JSON Schema files that both producer and consumer skills
reference. E.g.,
code-reviewer.output.frontmatter ⊇ {finding_counts, gate_pass}.
License
© 2026 Alex Horovitz. Shareware license — free for personal and internal organizational use. See LICENSE for details.
If SSD saved you a death march or helped your team ship with less stress, consider a small donation: venmo.com/alex-horovitz · $20 suggested · entirely optional