Open source · MIT · Claude Code, Codex, OpenCode, Copilot

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.

template version plugin version gates version license: MIT
from zero to a verified repo
$ 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.

The problem

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
What you get

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.

What WellForge is

Six pillars, one command

Each one is a thing every team ends up building for itself. WellForge builds them once.

01 · Spec-driven

Spec-driven framework

A standardized spec → plan → tasks workflow, owned in-house so it encodes your conventions and doesn't churn under you.

02 · Agents

Multi-agent team

Product Owner, Architect, Designer, Frontend & Backend Devs, DevOps, Quality Engineer and Evaluator, each a subagent with a crisp role.

03 · Orchestrator

AI orchestrator

Routes work to the right agents, enforces the spec workflow, and coordinates handoffs from PO → Architect → Devs → QE.

04 · Scaffold

Scaffolder + connections

Recommends a stack, generates from a versioned template, and guides MCP/CLI connections to GitHub, CI, cloud, and observability.

05 · Gates

Quality gates as law

Coverage, lint, types, SAST, dependency and secret scans: defined centrally, enforced in CI and locally. Never left to individual discretion.

06 · Lifecycle

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.

How a goal flows

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.

  1. Product Ownerspec.md
  2. Architectplan.md
  3. Designerdesign.md · UI only
  4. Frontend / Backend Devcode, test-first
  5. Quality Engineergates + verdict
  6. Evaluatoreval-report.md

A red QE verdict loops back to the devs, capped per feature, so a run always ends.

How it fits together

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.

wellforge-plugin/

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.

Covers: pillars 1, 2, 3
copier.yml + templates/

Copier template

A monorepo template chosen for first-class copier update re-templating: the scaffolder and the upgradeable lifecycle.

Covers: pillars 4, 6
.github/workflows + gates/

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.

Covers: pillar 5
Fair question

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.

Pick your stack

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.

full-stack

spring-kotlin-react

A JVM backend with a React SPA: the batteries-included enterprise path.

Backend: Spring Boot 4 · Kotlin · jOOQ · Liquibase
Frontend: React · TypeScript · Vite
full-stack

hono-react

An all-TypeScript, edge-ready full stack: one language end to end.

Backend: Hono · TypeScript · Drizzle
Frontend: React · TypeScript · Vite
infrastructure

pulumi-gcp-ts

Infrastructure-as-Code, not an app: provision Google Cloud with real TypeScript.

IaC: Pulumi · TypeScript · GCP
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.

Match ceremony to stakes

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.

spikemvpproduction
Feasibility, may be thrown awayValidate with usersShip it and own it
Who buildsMain loop, from a one-paragraph briefPO → dev agents → light QEThe full agent team
Human gatesNone (review the result)Spec approvalSpec + plan
CoverageAdvisoryAdvisory80%, blocking
SAST (high)Not runBlockingBlocking
LM-judge evalOffOffThe 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.

One command per job

Playbooks for the everyday jobs

The four jobs you'll do most. Each is one command.

Greenfield

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
Spec-driven

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"
Test-first

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
Existing code

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 →

Status · pre-1.0

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.

Get started

From nothing to building

macOS or Linux, GitHub, and one of Claude Code, Codex (native plugin), OpenCode, or GitHub Copilot (VS Code, via adapter).

1

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.

2

Run the front door

/wellforge:new interviews you, recommends a stack, generates the scaffold, verifies the build, and walks the connections.

3

Or adopt an existing repo

/wellforge:adopt brings the workflow and calibrated gates to a brownfield project, one layer at a time, additive only.

4

Build with the team

/wellforge:orchestrate drives the full agent pipeline on a goal: spec → plan → tasks → code → QE → eval.

5

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