Plan it once. Let the agent build it while you sleep.
OneShot turns a product idea — or an existing codebase — into the three documents a coding agent needs to build unattended for hours: a technical PRD with a numbered findings register, a flat task list where every task has a done-condition the agent can verify itself, and the CLAUDE.md guardrails that decide what it may do alone and what it must park for you.
Then it runs the list.
/oneshot → interview → audit + technical PRD → your review → task list → CLAUDE.md
/oneshot-run → coordinator fans out 3–8 subagents per wave, verifies, commits, repeats
A long unattended run doesn't fail because the model is bad at code. It fails because it hits a decision nobody made — what's the session length, is money a float, does a member outrank an admin — and either stops to ask or guesses and drifts. Six hours later everything downstream inherits the guess.
So the work is front-loading every decision that could stall it, writing it down as one referenceable source of truth, and giving each task an observable done-condition. That's the whole idea:
- Ask little, assume loudly. 4–9 short questions. Everything else becomes a numbered assumption you correct in one pass at the review gate. Correcting a list beats filling in a form.
- Every task is checkable. Not "auth should be secure" —
done when: an unauthenticated request to /app/* returns 302 to /login, covered by an integration test. That's the self-verification loop that lets the agent keep moving without you grading it. - Flat and severity-ordered. No phases, no sprints. The next task is always the top unchecked one, so the agent never spends a turn deciding what to do next.
- Guardrails, not vibes. Green / yellow / red. Deploying, spending money, touching production data, and destructive migrations are red — parked as
⏸ BLOCKED — needs human:so one blocked item doesn't idle the whole run.
Pick one. All three land in the same place.
Clone — recommended, and the easiest to update:
git clone --single-branch --depth 1 https://github.com/uvesarshad/OneShot.git ~/.oneshot && ~/.oneshot/setupnpx — no clone to manage:
npx github:uvesarshad/OneShotClaude Code plugin marketplace:
/plugin marketplace add uvesarshad/OneShot
/plugin install oneshot@oneshot
Then start a new agent session so the skills are picked up.
Install OneShot: run git clone --single-branch --depth 1 https://github.com/uvesarshad/OneShot.git ~/.oneshot && ~/.oneshot/setup — this installs two skills, /oneshot (interview → audit + technical PRD → review gate → severity-ordered task list → CLAUDE.md and AGENTS.md guardrails) and /oneshot-run (coordinator that fans out 3-8 subagents per wave, verifies each task against its done-when condition, and commits after every wave). Then add a "OneShot" section to CLAUDE.md saying: use /oneshot to plan any new product, feature, or refactor before writing code, and /oneshot-run to execute the task list it produces; plans live in docs/plan/ as YY-MM-DD-audit-<slug>.md and YY-MM-DD-tasks-<slug>.md; never start building from an unreviewed audit. Then ask the user if they also want to add OneShot to the current project so teammates get it, which is ~/.oneshot/setup --project.
Commit the skills into the repo so everyone gets them:
~/.oneshot/setup --project && git add .claude/skills && git commit -m "add OneShot"/oneshot I want to build a SaaS where freelancers track billable hours per client and send invoices
It reads the ground (new project or existing code), asks up to nine short questions, verifies current stable versions and pricing thresholds for the stack it's proposing, and writes:
docs/plan/26-08-27-audit-initial-build.md
Then it stops and shows you the assumption register. That gate is the point — a task list built from an unreviewed PRD multiplies every wrong assumption across hours of work. Correct what's wrong; it folds the changes in.
Once you confirm, it writes the task list and the bootstrap files:
docs/plan/26-08-27-tasks-initial-build.md
CLAUDE.md
AGENTS.md
docs/prompts/documentation.md
> Source audit: [26-08-27-audit-initial-build](./26-08-27-audit-initial-build.md)
> Updated: 26-08-27 · 0/47 done
- [ ] **(A1, P0)** Convert money columns to integer cents + currency code — done when: no float money column exists in the schema and the cents-arithmetic unit test passes
- [ ] **(A2, P0)** Route all tenant reads through the scoped repository — done when: a cross-workspace integration test returns zero rows
- [ ] **(A9, P1)** Add /privacy and /terms routes — done when: both return 200 and appear in sitemap.xml/oneshot-run docs/plan/26-08-27-tasks-initial-build.md
The coordinator holds only the plan and the ledger. Each wave, it picks 3–8 tasks that don't touch the same files, briefs a subagent per task with the full finding and a scope boundary, runs the done-condition itself when they report back, and commits the wave. Schema, shared types, and dependency changes run alone, first — those touch everything downstream and conflict badly in parallel.
On a harness with a native /goal (Claude Code, Codex CLI), the single-threaded version:
/goal finish all tasks in docs/plan/26-08-27-tasks-initial-build.md — work the flat list top to bottom, verify each `done when:` before checking it off, commit per task, follow the guardrails in CLAUDE.md, and stop only on a listed stop condition.
Same command. It reads the repo first — manifest, schema, routes, env vars, auth, tests — and the findings become gaps measured against your target rather than things to build from scratch.
/oneshot audit this repo, we're two weeks from a public launch
The coverage checklist is the heart of it. Every topic ends up either specified in the PRD, deferred with a written reason, raised as a numbered finding, or carried into CLAUDE.md. Silence is the failure mode.
| Foundation | stack · repo conventions · environments & the env var contract · documentation system · code-graph tooling |
| Data | database & pooling · schema · migrations & seed data · multi-tenancy · money & rounding · time, DST & billing increments · sequences under concurrency |
| Access | authentication · authorization & where checks live · account lifecycle |
| Runtime | hosting & deploys · object storage & uploads · background jobs · caching & performance budgets |
| Safety | security posture · rate limiting & abuse · privacy, legal & compliance · error taxonomy |
| Surface | UI/UX & design tokens · light + dark · accessibility · zero states & onboarding · marketing pages · copy |
| Integration | external services · payments & entitlements · payouts between users · email & notifications · LLM cost ceilings · generated documents & record immutability |
| Operations | observability · testing & definition of done · CI/CD · feature flags · admin tooling · cost model · launch readiness |
| Agent | autonomy guardrails · task discipline |
Depth scales with the work — a three-page static site doesn't produce a forty-finding audit.
Written into the CLAUDE.md that ships with every plan, and binding on every subagent in a run.
Green — write code, add tests, run local migrations, install approved dependencies, commit and push to a working branch.
Yellow — proceed, then record it in the task list's ## Deviations section: choosing an approach the PRD didn't specify, adding a small utility dependency, correcting an error in the audit.
Red — never unattended, no matter how obvious it looks at hour nine: destructive migrations, production data or env vars, spending money, deploying, rotating credentials, force-pushing, disabling a security control to make something pass, changing what a paying user gets.
Plus: three failed attempts at the same problem means the approach is wrong, not the execution — park it with a written trail and move on. Four hours of thrashing produces nothing reviewable.
| Skills | Slash commands | Install path | |
|---|---|---|---|
| Claude Code | ✅ | /oneshot, /oneshot-run |
~/.claude/skills/ |
| Claude Cowork | ✅ | ✅ | ~/.claude/skills/ |
| Codex CLI | ✅ | $oneshot |
~/.agents/skills/ |
| Cursor | ✅ | ✅ | ~/.agents/skills/, ~/.cursor/skills/ |
| Gemini CLI | via generated TOML | /oneshot |
~/.gemini/commands/ |
| Anything else | Point it at ~/.oneshot/skills/oneshot/SKILL.md — it's plain Markdown |
setup only writes to a config directory for an agent that's actually installed, and never overwrites a file it didn't create.
cd ~/.oneshot && git pull # or: npx github:uvesarshad/OneShot
~/.oneshot/setup --uninstallskills/
oneshot/
SKILL.md the workflow: ground → interview → research → audit → gate → tasks → bootstrap
references/
interview.md question bank, branching, and what to assume instead of asking
spec-topics.md the coverage checklist — every topic, its default, what breaks without it
output-formats.md exact templates for the audit, task list, CLAUDE.md, AGENTS.md
autonomy-guardrails.md green/yellow/red, verification, commit and context discipline
assets/
documentation-prompt.md generates the project's own /docs tree and maintenance rules
oneshot-run/
SKILL.md the coordinator: waves, briefs, verification, commits, resuming
Everything is Markdown. Fork it and change the defaults — the house stack in spec-topics.md is a starting point, not a verdict.
MIT © Uves Arshad