A week of AI-infra setup, turned into one command.
Describe the idea. Get back a building, CI-gated, spec-driven repo with an AI agent team already wired in, and keep it upgradeable as your standards move on.
$ brew tap matteocodogno/wellforge https://github.com/matteocodogno/wellforge $ brew install matteocodogno/wellforge/wellforge ✓ wellforge installed $ wellforge setup ✓ toolchain checked ✓ repo cloned ✓ plugin installed # now, in Claude Code (or Codex, OpenCode) > /wellforge:new a portal where contractors manage their work orders interview → stack pick → scaffold → verified build → connections ✓ repo ready, gates green, first spec drafted
Illustrative transcript. wellforge doctor checks a real setup any time.
Every new project pays the same tax
Hours of AI and CI wiring, every time. Everyone does it a little differently, and it quietly rots the moment your standards move on.
Without WellForge
- Agents, prompts and CLAUDE.md wired by hand, per repo
- A spec workflow each team reinvents, or skips
- Coverage and SAST thresholds copied in, then quietly lowered
- CI pasted from the last project, bugs included
- Day two: your standards move on, the scaffold doesn't
With WellForge
- One interview, /wellforge:new, and the agent team is in
- The same spec → plan → tasks flow in every repo
- Gates referenced from one place and pinned, never copied
- CI wired and green before the first feature
- /wellforge:upgrade brings each project forward when the template or plugin evolves
A repo that builds, gates and remembers where it came from
Here's what /wellforge:new forges from the hono-react preset. Nothing in it is a placeholder.
work-orders/ ├── .claude/settings.json # plugin on, secret files denied ├── .forge/manifest.json # template + version ├── .github/workflows/ │ └── quality.yml # central gates, pinned ├── AGENTS.md CLAUDE.md # agent context, ADR index ├── specs/ # spec → plan → tasks ├── backend/ # Hono · Drizzle · Vitest ├── frontend/ # React · TypeScript · Vite ├── docker-compose.yml # Postgres, per checkout ├── .worktreeinclude # env for parallel agents ├── .release-it.json # releases from commits ├── RELEASING.md # your release steps └── mise.toml # pinned toolchain + tasks
Agent-ready from the first commit
The plugin is enabled in the repo itself, so every teammate who opens it gets the same agents, commands and hooks. Secret files are denied by permission rule in every mode, auto included.
Gates you can't quietly lower
CI calls the central gate workflows at a pinned tag. Raising the bar is one PR for the whole fleet; lowering it locally isn't an option.
Upgradeable, not a snapshot
The manifest records the template and version that made the repo, so copier update can bring it forward when presets evolve.
Six pillars, one command
Each one is a thing every team ends up building for itself. WellForge builds them once.
Spec-driven framework
A standardized spec → plan → tasks workflow, owned in-house so it encodes your conventions and doesn't churn under you.
Multi-agent team
Product Owner, Architect, Designer, Frontend & Backend Devs, DevOps, Quality Engineer and Evaluator, each a subagent with a crisp role.
AI orchestrator
Routes work to the right agents, enforces the spec workflow, and coordinates handoffs from PO → Architect → Devs → QE.
Scaffolder + connections
Recommends a stack, generates from a versioned template, and guides MCP/CLI connections to GitHub, CI, cloud, and observability.
Quality gates as law
Coverage, lint, types, SAST, dependency and secret scans: defined centrally, enforced in CI and locally. Never left to individual discretion.
Upgradeable lifecycle
Every project records the template + version that made it, and can be re-templated when presets evolve. A scaffold that doesn't rot.
One goal, a team of agents
/wellforge:orchestrate hands the work down the line. Each agent produces one artifact, and you approve at the gates that matter.
- Product Ownerspec.md
- Architectplan.md
- Designerdesign.md · UI only
- Frontend / Backend Devcode, test-first
- Quality Engineergates + verdict
- Evaluatoreval-report.md
A red QE verdict loops back to the devs, capped per feature, so a run always ends.
Three layers, because a plugin alone can't
Pillars 1–3 live in the AI session; pillars 4–6 need artifacts that outlive it: versioned templates and CI workflows. So WellForge is three cooperating layers.
Agent plugin
Skills, agents, commands, hooks, MCP: the spec workflow, the agent team, the orchestrator, and local gate enforcement. Also generated as a native Codex plugin and as adapters for OpenCode and Copilot.
Copier template
A monorepo template chosen for first-class copier update re-templating: the scaffolder and the upgradeable lifecycle.
Reusable CI gates
Central thresholds and SAST configs, referenced (not copied) by every scaffold, so raising the bar is one PR for the whole fleet.
Why not spec-kit, BMAD or Kiro?
We tried them before building anything. Each one shaped WellForge, and none was the whole answer.
spec-kit / cc-sdd
- What it gets right
- The closest to what we wanted. WellForge keeps its spec → plan → tasks shape.
- Why not as-is
- We wanted to own the prompts, so they encode our conventions and don't churn under us between releases.
BMAD
- What it gets right
- Powerful: a full method, not just a prompt pack.
- Why not as-is
- Heavyweight: too much ceremony for the size of most of our projects. Rigor tiers are our answer to that.
Kiro
- What it gets right
- A good spec UX.
- Why not as-is
- It's tied to its own IDE and runtime. WellForge runs in Claude Code, Codex, OpenCode and GitHub Copilot.
superpowers
- What it gets right
- Great skill-authoring patterns. Our skills borrow the style, and the visual companion is adapted from it under MIT, with credit.
- Why not as-is
- We wanted the style, not the framework.
The bigger difference is scope: a spec workflow is one pillar of six. WellForge also ships the
scaffold, the CI gates and the upgrade path, because those have to outlive the AI session.
These projects move fast; this is how they compared when we chose.
Versioned presets, ready to scaffold
Every preset generates a building, gate-wired, spec-driven monorepo, backed by a stack skill that keeps its conventions and pinned versions honest.
spring-kotlin-react
A JVM backend with a React SPA: the batteries-included enterprise path.
Frontend: React · TypeScript · Vite
hono-react
An all-TypeScript, edge-ready full stack: one language end to end.
Frontend: React · TypeScript · Vite
pulumi-gcp-ts
Infrastructure-as-Code, not an app: provision Google Cloud with real TypeScript.
Built in: per-env stacks · ComponentResources · CrossGuard policy · mock-runtime tests
Already have a repo? /wellforge:adopt brings the workflow and calibrated gates to any Node (pnpm) or JVM (Maven) project.
Rigor tiers
A throwaway prototype and a regulated production service shouldn't pay the same setup cost. Pick a tier per feature. Lower tiers defer rigor as tracked debt; they never lower the bar.
| spike | mvp | production | |
|---|---|---|---|
| Feasibility, may be thrown away | Validate with users | Ship it and own it | |
| Who builds | Main loop, from a one-paragraph brief | PO → dev agents → light QE | The full agent team |
| Human gates | None (review the result) | Spec approval | Spec + plan |
| Coverage | Advisory | Advisory | 80%, blocking |
| SAST (high) | Not run | Blocking | Blocking |
| LM-judge eval | Off | Off | The gate into done |
Graduate with /wellforge:promote, which pays the deferred debt; production only on an eval pass. A security floor, a secret scan over the full git history, blocks in every tier, alongside the linear-history and Conventional Commits checks.
Playbooks for the everyday jobs
The four jobs you'll do most. Each is one command.
Start a new project
One interview and you get a building, CI-gated repo with the agent team wired in.
/wellforge:new # interview → stack pick → scaffold → # build check → connections → first spec
Add a new feature
The full spec → plan → tasks flow with a human gate at each step. A design stage kicks in for UI.
/wellforge:spec → :plan → :tasks → :implement → :done # UI feature? add /wellforge:design after :plan # shortcut, end-to-end: /wellforge:orchestrate "add password reset"
Fix a bug
QE reproduces it with the smallest failing test, a dev makes it green without weakening it, QE checks for regressions. Every fix names a root cause first; after three misses it questions the design instead of trying a fourth.
/wellforge:orchestrate "reset email never arrives" # QE repro (failing test) → dev fix → QE verify
Adopt a brownfield repo
Brings the workflow and calibrated gates to a project you already have. Additive only, one revertable commit.
/wellforge:adopt # AI-readiness → gap-check vs presets → # calibrated gates → release wiring
Not sure which fits? /wellforge:orchestrate classifies any goal (feature, bugfix, refactor or infra) and runs the matching pipeline.
Spikes, idea grilling, evals, retros, releases and upgrades have their own commands: see every command →
Where it stands
Pre-1.0 means the version number, not the confidence. Here's what's already proven.
In real projects
- Several projects scaffolded with WellForge, pushed to GitHub, CI green end to end.
- Brownfield repos adopted with /wellforge:adopt, running the same workflow and gates.
- Scaffolding a new project takes minutes, from interview to a verified build.
- Gate thresholds verified against real projects, not just the presets.
In the repo
- All six pillars are built, plus rigor tiers and release management.
- The upgrade path works end to end: scaffold at one version, change the template, copier update, zero conflicts.
- WellForge's own CI runs every self-test and smoke-tests all three presets on each commit.
- Real use feeds back: the first real install on a generated project turned up five defects, all fixed in the templates.
Still open: cutting v1.0.0. Starting now is safe: every project records the template version it came from, and /wellforge:upgrade brings it forward.
From nothing to building
macOS or Linux, GitHub, and one of Claude Code, Codex (native plugin), OpenCode, or GitHub Copilot (VS Code, via adapter).
Install and set up
brew install the WellForge CLI, then wellforge setup checks the toolchain, clones the repo and installs the plugin with its agents, commands and skills.
Run the front door
/wellforge:new interviews you, recommends a stack, generates the scaffold, verifies the build, and walks the connections.
Or adopt an existing repo
/wellforge:adopt brings the workflow and calibrated gates to a brownfield project, one layer at a time, additive only.
Build with the team
/wellforge:orchestrate drives the full agent pipeline on a goal: spec → plan → tasks → code → QE → eval.
Keep current — machine, then project
wellforge update refreshes your machine: the checkout, pinned tools, the loaded plugin and the CLI; it touches no project. Then /wellforge:upgrade, inside each project, re-templates, offers the gate bump and applies the migrations in one reviewable commit.
# install brew tap matteocodogno/wellforge https://github.com/matteocodogno/wellforge brew install matteocodogno/wellforge/wellforge wellforge setup # keep current: machine first, then each project wellforge update # then /reload-plugins /wellforge:upgrade
# …or manually, inside Claude Code /plugin marketplace add matteocodogno/wellforge /plugin install wellforge # then scaffold a new project, or adopt one /wellforge:new /wellforge:adopt
# …or in Codex: install the plugin, then once per project codex plugin marketplace add matteocodogno/wellforge $wf-setup # commands are skills, invoked by name $wf-new $wf-adopt