From product idea to a building, CI-gated, spec-driven repo — target: under 30 minutes. Assumes installation is done.
/wellforge:doctor
One table: tools, MCP servers, hooks, drift guards, project shape — with a fix command for
anything red, and the command index at the end if you just want to see what's available.
Worth running before your first scaffold, because the failures it catches are the silent
ones (no jq → every hook quietly does nothing; no uv → new fails inside copier with a
confusing error).
Open Claude Code in the directory where the project should live and run:
/wellforge:new a portal where external contractors manage their work orders
What happens (you stay in the loop at every decision):
-
Interview — a couple of question rounds: who uses it, expected lifetime/scale, domain complexity, anything already decided (DB, auth, hosting). The lifetime/scale answer also sets the rigor tier (
spike/mvp/production) — how strict the generated CI is. Throwaway PoC →spike; first real release →mvp; long-lived →production(default). Raise it later with/wellforge:promote. -
Stack recommendation — one of the three presets, with the rationale and why not the others. You confirm or override; your choice wins.
Preset Pick when spring-kotlin-reactrich domain logic, transactions, long-lived product hono-reactlightweight API, fast iteration, all-TS team pulumi-gcp-tsinfrastructure-as-code (not an app) — provision GCP with Pulumi + TypeScript -
Generation — Copier renders the project; first commit is the pristine scaffold.
-
Build verification —
mise run install,build,testmust pass before anything else happens. -
Connections — guided checklists: GitHub repo + branch protection, CI variables, MCP servers, local DB. Each ends with a verification command you can see pass. Steps needing org rights you don't have become explicit PENDING items.
You now have a repo with: pinned toolchain (mise.toml), CI calling the central quality
gates, project CLAUDE.md (AI-ready on first open), specs/ directory, and
.forge/manifest.json recording template+version for future upgrades.
uvx copier copy --trust <wellforge repo/URL> my-project --data preset=hono-react
cd my-project && git init -b main && git add -A && git commit -m "chore: scaffold"
mise trust && mise install && mise run install && mise run build && mise run testWhen you just want to test feasibility or a business idea, skip the ceremony:
/wellforge:spike a landing page that A/B-tests two pricing models
The main loop builds it directly from a one-paragraph brief.md — no agents, no
approval gates, advisory lint/build only (minutes, not the ~20-min full pipeline). A
security floor still blocks (secret scan), so fast never means leaky. When the spike
proves out, graduate it: /wellforge:promote <feature> --to mvp (then --to production)
writes the real spec/plan, backfills tests to the coverage floor, flips gates to blocking,
and runs the eval. A lower tier is tracked debt — raised deliberately, never silently.
For work you intend to keep, run the standard flow. Either drive the steps yourself:
/wellforge:spec contractors can accept or reject an assigned work order
# review → approve (add --grill for a one-question-at-a-time interview instead of the batched one)
/wellforge:plan
# review architecture + AC→test mapping → approve
/wellforge:design # UI features only — flows, screens, component reuse, a11y (optional)
/wellforge:tasks
# review task list, then implement tasks of the feature — dependency-aware, QE-verified.
# arg is [feature] [tasks]; the feature folder (specs/NNN-slug) leads, tasks follow:
/wellforge:implement 001-user-auth next # first ready task of that feature
/wellforge:implement 001-user-auth T3,T5 # a chosen subset
/wellforge:implement all # all ready tasks (feature inferred if only one in-progress)
…or let the orchestrator run the whole pipeline (you still approve spec and plan — exactly two pauses):
/wellforge:orchestrate contractors can accept or reject an assigned work order
The orchestrator routes work to the agent team (PO → Architect → Designer if UI → devs in parallel → QE verdict) and ends with an evidence-based gate report.
Rules worth knowing on day one:
- Only you approve specs and plans — nothing self-approves.
- If code and spec disagree, the spec gets amended first (a Stop hook blocks sessions that change a spec without re-syncing tasks).
- Commits reference tasks:
feat(orders): accept endpoint (T3, specs/001). - The dev agents work test-first: one behavior at a time, the test seen to fail before
the code exists. Each reports a
TDD:line; atest-afterentry in it is worth a look. - Domain words live in
.claude/context/glossary.md— one word per concept. Agents use its terms and propose new ones; only you (via/wellforge:grill-me --docsor the spec review) put them in.
| Need | Do |
|---|---|
| daily dev | mise run dev · mise run test · mise run lint |
| fast experiment / PoC | /wellforge:spike <goal> — main-loop build, advisory gates, no agents |
| graduate a spike/mvp | /wellforge:promote <feature> --to mvp · --to production (pays the deferred rigor) |
| new feature | /wellforge:spec → :plan → :design (UI only) → :tasks → :implement (or :orchestrate for all of it) |
| an idea that isn't decided yet | /wellforge:grill-me <idea or NNN-slug> — one question at a time, each with a recommendation, ending in a decision ledger file · then /wellforge:spec --ledger <path> or /wellforge:orchestrate --ledger <path> · --docs also maintains the glossary and offers ADRs |
| implement a feature's tasks | /wellforge:implement <feature> T3,T5 · <feature> next · all |
| where am I / what's next | /wellforge:status (all features + next command each) |
| the session was harder than it should have been | /wellforge:retro (or /wellforge:retro <feature>) — at most five evidence-backed fixes to the environment (tasks, hooks, docs), applied only on your yes |
| the codebase is getting harder to change | /wellforge:improve-architecture [path] — ranked refactor candidates from co-change and run-trace evidence; the one you pick goes through /wellforge:orchestrate as a refactor |
| bugfix | /wellforge:orchestrate <bug> → QE writes the failing repro test first |
| CI red on the quality gate | the gate report names the exact threshold; thresholds are central — fix the code, don't look for a config to weaken (there isn't one in your repo) |
| cut a release | /wellforge:release — version bump + CHANGELOG.md from your Conventional Commits, tag, GitHub release (release-it); dry-run preview first |
| template released a new version | /wellforge:upgrade — diff explained, conflicts resolved with you, gates re-run, one revertable commit |
| check the fleet | scripts/fleet-status.sh <github-org> (from the wellforge repo) |
Debugging is a skill, not a command — there is no /wellforge:debug. It loads itself the
moment anything goes red (failing test, red gate, build or CI failure, flaky test, unexpected
behavior), because that's when it's needed, not when you remember to ask. Paste the stack
trace or say "the build's failing" and it applies. To force it: /wellforge:systematic-debugging,
or "use systematic debugging on this".
It applies everywhere, not just in agent runs — the main loop, a /wellforge:spike, and dev
agents mid-task all work under it. What you'll notice:
| Instead of | You get |
|---|---|
| a fix proposed straight from the error | a stated root cause first — "X is the root cause because Y" |
| three changes at once, then re-run | one change per hypothesis, so you know which one mattered |
| the symptom quietly silenced | no raised timeout, unexplained retry, .skip/@Disabled, or lowered threshold — each hides the bug and the evidence |
| a fourth fix attempt | a stop: 3 failures on one symptom is an architecture signal, routed as drift to the architect (in a spec'd feature), recorded as the finding (in a spike), or said to you plainly (main loop) |
| "this looks like pre-existing breakage" | an environment check first — does it reproduce outside this checkout, and did the config actually resolve? Tests that fail in a parallel agent's worktree and pass on your branch are an environment fault, reported as one instead of "fixed" in working code |
The 3-attempt stop composes with /wellforge:implement's 2-round QE loop — whichever trips
first, the work stops and escalates rather than looping.
This is discipline, not enforcement: nothing counts attempts for you. If a fix ever arrives without a root cause, say "root cause first" — that's the whole trigger.
Agent commands are one-shot, not a mode. /wellforge:orchestrate and
/wellforge:implement run the agent loop (QE → dev → QE) for that single invocation — plain
follow-up messages only drive the main loop, so the agent team won't re-engage on its own. To
keep iterating after a partial fix, re-run the command with the remaining broken behavior:
/wellforge:orchestrate "the reset fix is incomplete — it works for email users but SSO users still get no token"
For a fix that needs several rounds, scope it as a feature (spec → plan → tasks) so
/wellforge:implement <feature> <tasks> can iterate task-by-task against a persistent tasks.md.
| Symptom | Fix |
|---|---|
mise: command not found tasks in CI/local |
mise trust in the project root, shell activation in your rc file |
gate fails: pnpm-lock.yaml missing |
mise run install locally, commit the lockfile (reproducibility gate — intended) |
/wellforge:* commands missing |
plugin not installed in this scope — see Installation §3–4 |
| upgrade refuses to run | working tree must be clean — commit or stash first (by design) |
| postgres tests fail locally | Docker running? docker compose up -d db, then docker compose exec db pg_isready |
Deeper dives: Features · Template contract · Gates policy