Build end-to-end apps from a plain-English description. PM → Architect → Frontend → Backend → DevOps → QA → Reviewer → Tech Writer, all running sequentially over your existing Claude Code skill ecosystem (gsd, brainiac, predator, code-tester, problem-solver). Ships to a private GitHub repo.
OSBuilder is a Claude Code skill. You describe what you want; OSBuilder runs a virtual studio sequentially (never parallel — multi-agent is an explicit anti-feature) and delivers a working, version-controlled app.
curl -fsSL https://raw.githubusercontent.com/opencdlee-dotcom/osbuilder/main/install.sh | shReplaces nothing existing on your machine. Drops ~/.claude/skills/osbuilder/
in place and you're ready to run /osbuilder in any Claude Code session.
For users whose security policy disallows curl ... | sh:
git clone https://github.com/opencdlee-dotcom/osbuilder.git ~/osbuilder-src
cd ~/osbuilder-src && ./install.shSame destination (~/.claude/skills/osbuilder/); same idempotent installer.
OSBuilder narrates progress as a virtual studio. Each "role" is a sequential delegation to your existing skill ecosystem — never parallel, never multi-agent.
| Stage | Role | What you'll see in the terminal | Delegates to |
|---|---|---|---|
| 1. Intake | PM | PM is gathering requirements... ✓ |
/gsd:spec-phase |
| 2. Research | Architect | Architect chose Next.js because… |
/brainiac + references/stack-menu.md |
| 3. Scaffold | DevOps | DevOps is setting up Docker Compose… |
scripts/scaffold_dispatch.py |
| 4. Plan | Architect | Architect is planning phase 1… |
/gsd:new-project --auto + /gsd:plan-phase |
| 5. Build | Frontend / Backend / DevOps | Frontend dev is building the homepage… |
/gsd:execute-phase |
| 6. Verify | QA + Reviewer | QA is trying to break the app on purpose… / Reviewer is reading the code for problems… |
/code-tester + /gsd:verify-work + /predator + /gsd:code-review |
| 7. Heal | Debug-cap (silent unless broken) | Hit retry cap on validation; escalating to /problem-solver… |
/gsd:debug + /problem-solver |
| 8. Ship | DevOps | DevOps is pushing to GitHub… |
gh repo create --private |
The 8th narration role — Tech Writer — runs as part of stage 8 alongside
DevOps, humanizing the auto-generated README and clone-and-run runbook before
the repo is pushed (/gsd:docs-update + /humanizer).
Every line you see in the terminal is plain English. Tutor mode (default)
explains what just happened after each stage — disable with --quiet.
Higher-quality version on asciinema:
assets/demo/osbuilder-demo.cast — replay
locally with asciinema play assets/demo/osbuilder-demo.cast.
Honest demo policy. Recording is unedited end-to-end (paragraph → derived spec → scaffold → verify → private GitHub URL) per the contract in
assets/demo/RECORDING-CHECKLIST.md. No cuts that hide friction. If the demo asset isn't present yet, the checklist is the source of truth for how it gets recorded.
- Plain-English intake. Describe an app in a paragraph; OSBuilder asks a few outcome-framed questions ("Should it work on phones too?") with an "I don't know, you decide" option that resolves to a sensible default.
- Auto-installed prereqs. First run detects missing Node, Python, git,
gh, and Docker; offers a single-confirmation auto-install. - Deterministic scaffolders. Always uses
create-next-app,cargo new, etc. — never hand-writespackage.jsonorpyproject.toml(avoids bolt.new's documented 10M-token spaghetti failure mode). - Slopsquatting gate. Every package install is verified against the
public registry before any code runs (
--ignore-scriptsuntil verified). - Private by default. Repos created
gh repo create --private; pass--publicto override. - Self-healing. 4-class failure classifier with documented retry strategies and a hard 3-reflection cap before structured handoff to you.
| Flag | Effect |
|---|---|
| (default) | Beginner mode — plain-English questioning, tutor narration on, sensible defaults |
--advanced |
Exposes stack choice, deploy targets, scaffolder selection |
--quiet |
Disables tutor mode (still narrates dev-team progress) |
--no-docker |
SQLite-only single-user builds (for users without Docker Desktop) |
--public |
Push to a public GitHub repo (default is private) |
--production-ready |
Adds named ROADMAP phases for hardening (see below) |
Passes a flag that adds these as named ROADMAP phases (not default
scaffold code). Phase 6 implements this; the flag is wired end-to-end
through intake_handler.py → state_writer.py → gsd_driver.py step 3 →
production_phase_writer.py (which emits the slash commands below).
The 7 named upgrades:
observability— logs/metrics/traces via OpenTelemetrymigrations— automated migrations via Drizzle Kit / Alembichealthchecks—/healthzendpointssecret-manager— secret manager integrationsentry— Sentry error trackingrate-limiting— rate limiting middlewarebackups— backup strategy
Default mode emits zero of these; the flag turns each into a
/gsd-add-phase <name> command appended to your project's ROADMAP.
See examples/ for real apps OSBuilder built end-to-end
— each with the original paragraph spec, screenshots, and a link to the
resulting GitHub repo (or NOT_PUBLISHED placeholder for local-only builds).
The current gallery covers 3 distinct playbooks: web, cli, and ai-service.
OSBuilder declares minimum versions for its sub-skills in SKILL.md
frontmatter (see references/version-policy.md).
On first invocation each session, scripts/check_skill_versions.py validates
that GSD, brainiac, predator, code-tester, and problem-solver meet those
minimums. Drift = friendly upgrade command and refusal to proceed.
To force a re-check after upgrading a sub-skill mid-session:
rm -f ~/.osbuilder/last_check.txtBuilt phase-by-phase via GSD itself.
See .planning/ROADMAP.md for shipped phases and
next milestones. Currently delivering Phase 8: Skill quality / publish-bar.
See LICENSE in the repo root.
SKILL.md— entry point + routing (≤ 200 lines, enforced by CI)references/— playbooks, role briefs, refusal list, version policy.planning/— full GSD planning historyexamples/— reference builds gallery