matteocodogno/wellforge

Standardized checklists for connecting a WellForge project to its ecosystem tools — GitHub (repo, branch protection, secrets), CI, MCP servers, environments and databases. Use during $wf-new stage 5, when the user asks to "connect", "set up", or "wire up" a tool/integration for a project, or when the devops agent needs the standard procedure. Every checklist ends with a verification command: a connection is established only when that command's output says so.

WellForge domain modeling — the project glossary: one term per concept, stress-tested against edge cases. Use when a spec, plan or grilling session introduces, renames or contradicts a domain term.

WellForge visual direction — choosing palette, typography, layout and the one signature element deliberately, instead of the look every project in the stack gets by default. Use when designing a NEW product surface (a greenfield first UI, a landing/marketing/public page, a standalone prototype or demo), when reshaping an existing UI on purpose, or when the user asks for "personality", "a visual identity", or something that "doesn't look AI-generated". Do NOT use to add a feature inside a project that already has a design system — there the system wins. Authoritative for the surface-class gate, the two-pass token system, the anti-default calibration list, the contrast/motion floor, and how direction lands in design.md and the theme (never ad-hoc CSS).

WellForge git policy — linear history (no merge commits) and Conventional Commits, in every WellForge repo including generated ones. Use whenever writing a commit message, integrating a branch, opening or merging a PR, setting up a fresh clone, fixing a rejected commit or a red commit-lint / linear-history gate, or configuring branch protection. Authoritative reference for the commit format, the four enforcement layers (local config, committed hooks, CI gates, branch protection), the rebase-not-merge integration rule, and what to do when a gate rejects your commit.

WellForge grilling — the one-question-at-a-time interview that walks an idea, spec or plan down its decision tree. Used by $wf-grill-me and $wf-spec --grill. Main loop only, never in a subagent.

WellForge heartbeat / scheduled-automation conventions — the "automations" pillar of loop engineering. Scheduled tasks that do discovery + triage on a cadence and SURFACE work for a human (never auto-ship). Use whenever adding or reasoning about a heartbeat: the scheduled gate heartbeat, the template-drift heartbeat, the fleet heartbeat, or the spec-health heartbeat ($wf-triage). Authoritative reference for the surface-never-ship rule, the one-deduplicated-issue-per-concern rule, the deterministic-vs-agentic split, the off-for-spike rule, the cost bound, and where each heartbeat records its trace.

Hono + TypeScript backend — best practices and scaffolding a new service (the **TypeScript / Node backend path**). Use when building or reviewing Hono TS APIs, or scaffolding a new **TypeScript / Node / all-TS** backend service: "new backend service", "scaffold a service", "bootstrap a TS API", "new microservice" in a TS/Node project. FIRST confirm the target stack — for a **JVM / Spring Boot / Kotlin** service use the springboot-scaffold skill instead; this skill is TypeScript-only. Covers pnpm/tsx/Biome setup, Hono routing, Zod validation, Effect TS error handling, Drizzle ORM + PostgreSQL, OpenAPI, Docker. Trigger for any Hono TS task — even "add a route", "create middleware", "set up validation".

Kotlin and Spring Boot development. Trigger for ANY Kotlin, Spring Boot, JVM, Maven, jOOQ, Liquibase, database-migration, REST-API or backend-service task — writing or reviewing code, setting up services, defining migrations, configuring dependencies, scaffolding modules, debugging Spring apps. Covers WellForge practices: functional error handling with Result/DomainError, Spring Modulith module boundaries, repository patterns, Spring configuration. Trigger for partial tasks too: "add a repository", "create a migration", "set up a new module", "add an endpoint", "fix a Spring Boot issue".

mise (dev tools version manager) expert for full-stack monorepos. Use this skill whenever the user asks to set up mise, add tools to mise, create or edit a mise.toml, define mise tasks, manage Java/Node/pnpm/Maven versions, or replace npm scripts / Makefile with mise tasks. Also trigger for phrases like "pin the node version", "add a task for", "run with mise", "how do I manage tool versions", "set up dev environment", or any question about .mise.toml configuration. Always use this skill proactively when scaffolding new projects or services — every WellForge project should have a mise.toml.

WellForge run-trace / observability conventions — the .forge/runs/ trace format that records which agents ran for which feature, their outcomes, drift events, verdicts, and (best effort) token cost. Use whenever a workflow command (orchestrate, implement, eval) runs agents and must record a run, when reading agent run history, when the evaluator needs trajectory evidence, or when $wf-status surfaces recent runs and cost. Canonical reference for the .forge/runs/ schema — producers and consumers MUST follow it.

Pulumi Infrastructure-as-Code in TypeScript on GCP — best practices and scaffolding a new IaC project. Use for any Pulumi TS task, building or reviewing: "new Pulumi project", "set up infrastructure as code", "provision GCP with Pulumi", "IaC for this service", and the small ones too — "add a bucket", "create a component", "write a policy", "add a stack". Covers stack layout, typed config, ComponentResource, CrossGuard policy-as-code, unit testing with Pulumi mocks, the keyless credential model (ADC + Workload Identity Federation), state backends. This is **infrastructure**, not an application backend — for a Hono API use hono-ts-backend, for Spring springboot-scaffold. Source of truth for the pulumi-gcp-ts Copier preset; versions here and there must match.

WellForge quality gates — what CI enforces, where the thresholds live, and how to change one. Use when wiring CI into a project, when a gate is red and you need to know whether it blocks at this rigor tier, when someone proposes lowering a threshold, when pinning or bumping a gates-v* ref, or when the devops agent needs the standard wiring. Authoritative reference for the gate catalogue, the central-threshold rule (change by PR to gates/, never locally), the security floor that blocks at every tier, and the reusable-workflow calling convention.

React + TypeScript + Vite frontend development. Use whenever building, scaffolding, extending or refactoring a React app in TypeScript: "create a React component", "build a page with React", "add a feature to my React app", "scaffold a new Vite project", "write a custom hook", "set up React Context", "add TanStack Query/Router", "style with Tailwind", "refactor this component", "use Effect TS in React" — or any frontend work in a React/TypeScript codebase. Use it proactively whenever React/TS code is being produced, even for "create a form" or "add a new page", in preference to a generic coding response.

WellForge rigor tiers — match ceremony to stakes. The spike / mvp / production vocabulary that governs how much of the pipeline runs (agents, approval gates, models, quality gates, eval) for a feature. Use whenever running $wf-spike, when $wf-orchestrate or $wf-implement is given a --mode, when reading a feature's rigor: frontmatter, or when deciding how strict gates should be. Authoritative reference for the three tiers, the non-negotiable security floor, advisory-gate behavior, and the rigor precedence rule.

WellForge self-critique pass — the ONE bounded review an agent runs on its own artifact before handing it to a human gate, to QE, or to the evaluator. Use whenever you are about to return a spec.md, plan.md, design.md, tasks.md or an implemented task, whether from an agent or from the main loop ($wf-spec, :plan, :design, :tasks). Authoritative reference for the one-pass rule, the per-artifact failure checklists, the tier gating, and the hard line between critiquing your own work and verifying it — self-critique never approves, never blocks, and never substitutes for QE or the eval.

WellForge spec-driven development conventions: the spec → plan → tasks workflow, file formats, status lifecycle, and drift rule. Use whenever working in a project that has a specs/ directory, when the user mentions a spec, feature specification, or task list, when implementing any task that references a specs/NNN-slug/ path, or when asked about the status of a feature. Also the authoritative reference for the $wf-spec, $wf-plan, $wf-design, and $wf-tasks commands — they MUST follow this format exactly.

How a Spring Boot / Kotlin service comes into existence in a WellForge project — the JVM backend path. Use when the user wants a new Spring Boot / Kotlin / JVM service, or a second service in an existing JVM monorepo. Trigger phrases: "new Spring Boot service", "new Kotlin/JVM microservice", "scaffold a JVM/Spring backend", "new spring boot app". FIRST confirm the target stack — for a TypeScript / Hono service use hono-ts-backend; this skill is JVM-only and must NOT put Spring into a TypeScript codebase. It routes to the right generator and owns the module conventions; it does not hand-generate a project.

WellForge debugging discipline — find the root cause before proposing a fix, and know when to stop fixing. Use the moment anything goes red: a failing test, a failing quality gate, a build or CI failure, a flaky test, unexpected runtime behavior, or a bug report — in the main loop, in a spike, or inside a dev agent whose own task tests fail. Load it BEFORE proposing or attempting a fix, not after the first one misses. Authoritative for the root-cause-first rule, the fix-attempt counter and the architecture stop, the never-make-the-symptom-disappear rule, and how a root cause is recorded and routed.

WellForge test-first discipline — red, green, refactor, one behavior at a time. Use when a dev agent implements a task at the mvp or production tier, or makes a QE reproduction test pass.

The binding contract every WellForge Copier template must satisfy — the single root copier.yml, the shared question set, required generated files, the manifest, and the versioning rules that make copier update work. Use when adding or editing a preset, when writing an org-internal template with $wf-extract-template, when a scaffold or an upgrade behaves unexpectedly, or when deciding which version series a change belongs to. Authoritative reference for the monorepo template pattern, the no-hidden-answers rule, the two independent version series, and what a template may never do.

WellForge template extraction — turn an existing project into (1) a stack profile checked against the shipped presets (the gap check) and (2) an opt-in, org-internal Copier template a team can scaffold its next service from. Use during $wf-adopt (Stage 0 always runs profile+gap; extraction is opt-in) and for $wf-extract-template. Authoritative for the .forge/stack-profile.json schema, the preset gap-check heuristic, the mandatory IP/secret scrub gate (skeleton-only, no domain code, no secrets), and CONTRACT-compliant generation verified with copier --defaults. Produces an ORG-INTERNAL template the team owns — it never opens a PR to the WellForge repo or ships code upstream.

WellForge terse mode — the token-efficient conversational output cue, orthogonal to rigor tier. Use whenever running $wf-spike (terse by default), when $wf-orchestrate or $wf-implement is given --terse/--no-terse, when the main-loop $wf-terse toggle is invoked, or when deciding whether a piece of output should be compressed. Authoritative reference for the terse cue directive text, the byte-identical invariant, which artifacts are exempt, the activation matrix, and $wf-terse session semantics.

WellForge Visual Companion — a browser tool the designer uses during $wf-design to show mockups, wireframes, diagrams and side-by-side layouts instead of describing them, capturing the user's clicks. Use ONLY when the designer was invoked interactively with the companion enabled (the --visual flag on $wf-design); NEVER in a headless or orchestrated run and NEVER in the spike tier. Covers the just-in-time offer, the per-question show-vs-tell test, theme selection from the project's real component library, the write-screen/read-events loop, .forge/design/ persistence, and the CSS classes the frame provides. design.md is still the deliverable — the browser only resolves visual questions faster.

WellForge command — Adopt WellForge in an existing (brownfield) project — AI-readiness, spec workflow, calibrated quality gates, release management. Invoke explicitly: $wf-adopt [--dry-run] (run from the project root)

WellForge command — Design the UX for a UI feature — flows, screens/states, component reuse, a11y (spec-driven workflow, optional stage for UI features). Invoke explicitly: $wf-design [NNN-slug] [--gate] [--visual] — --gate adds an approve/iterate checkpoint; --visual enables the browser visual companion (more tokens, better UI outcome)

WellForge command — Health check — tools, MCP servers, hooks, guards and self-tests; also the index of what WellForge can do here. Invoke explicitly: $wf-doctor [--tests] [--quiet] — --tests also runs the plugin's own regression matrices (slower)

WellForge command — Close a feature — verifies the tier-aware done gate (tasks + QE + eval) then sets status: done, or retires it as superseded. Invoke explicitly: $wf-done [feature] [--superseded-by <NNN-slug>] [--archive "<reason>"] — NNN-slug / slug / NNN; omit to infer the in-progress feature ready to close

WellForge command — Score a feature's implementation against the eval rubric (LM-judge — the non-deterministic verification half). Invoke explicitly: $wf-eval [feature] — NNN-slug / slug / NNN; omit to infer the in-progress/most-recent feature

WellForge command — Profile an existing project's stack, gap-check it against the WellForge presets, and optionally extract a reusable org-internal Copier template from it. Invoke explicitly: $wf-extract-template (run from the project root) [--profile-only] — --profile-only stops after the stack profile + gap check

WellForge command — Grill an idea, spec or plan — one question at a time, each with a recommendation, until it is decided. Invoke explicitly: $wf-grill-me <idea in a sentence or two> | <NNN-slug of an existing feature> [--docs]

WellForge command — Implement tasks of a feature from its approved tasks.md (dependency-aware, parallel, QE-verified). Invoke explicitly: $wf-implement [feature] [tasks] [--mode mvp|production] [--terse|--no-terse] — e.g. "001-user-auth", "user-auth T3,T5", "T2-T4", "next", "all"

WellForge command — Find shallow modules — ranked, evidenced refactor candidates, routed to the refactor pipeline. Invoke explicitly: $wf-improve-architecture [path or module] (default: the whole repo)

WellForge command — Scaffold a new WellForge project — interview, stack recommendation, generation, connections. Invoke explicitly: $wf-new <short product description> (optional — interview fills the gaps)

WellForge command — Orchestrate the full agent team on a goal (spec → plan → tasks → implementation → QE verdict). Invoke explicitly: $wf-orchestrate <goal> [--mode spike|mvp|production] [--ledger <path>] [--terse|--no-terse] — feature request, bug report, refactor, or infra change

WellForge command — Write the technical plan for an approved spec (spec-driven workflow, step 2 of 3). Invoke explicitly: $wf-plan [NNN-slug] (defaults to the most recent approved spec without a plan)

WellForge command — Graduate a feature (or the project) up a rigor tier — pay the deferred debt (retro plan, backfill tests, blocking gates, eval). Invoke explicitly: $wf-promote <feature> --to mvp|production | --project --to mvp|production [--dry-run]

WellForge command — Cut a release — auto version bump + CHANGELOG from Conventional Commits, git tag, GitHub release (release-it). Invoke explicitly: $wf-release [patch|minor|major] (optional — default: auto-computed from commits) [--dry-run]

WellForge command — Retro a session or feature — ranked, evidence-backed fixes to the environment, not the code. Invoke explicitly: $wf-retro [NNN-slug] (default: this session)

WellForge command — set up (or refresh) WellForge in this project after installing the WellForge Codex plugin: the agent team, the scripts the $wf-* commands run, the eval rubric and the AGENTS.md block. Run once per project and again after every plugin update. Invoke explicitly: $wf-setup [--hooks]

WellForge command — Write a feature specification (spec-driven workflow, step 1 of 3). Invoke explicitly: $wf-spec <feature description> | <NNN-slug to resume> [--grill] [--ledger <path>]

WellForge command — Spike a goal fast — main-loop build from a one-paragraph brief, advisory gates, no agents, no approval (rigor tier: spike). Invoke explicitly: $wf-spike <goal — what to prototype / which feasibility question to answer> [--no-terse]

WellForge command — Recap every feature's position in the spec→plan→tasks→implement flow, with the next command to run. Invoke explicitly: $wf-status [feature] — omit for all features; or NNN-slug / slug / NNN for one in detail

WellForge command — Derive the task list from an approved plan — or, at rigor mvp, straight from the approved spec (spec-driven workflow, step 3 of 3). Invoke explicitly: $wf-tasks [NNN-slug] (defaults to the most recent feature ready for tasks)

WellForge command — Toggle terse mode for the main-loop session — token-efficient conversational output, on this run and off the next. Invoke explicitly: $wf-terse (no arguments — toggles)

WellForge command — One-way compression of a WellForge-owned file (memory / AGENTS.md / a skill-command-agent description) with a fact-preservation safety gate. Invoke explicitly: $wf-terse-compress <path> — memory/*.md | AGENTS.md | a skill/command/agent file (its description: frontmatter is the compression target)

WellForge command — Spec-health heartbeat — surface features that are rotting (stale in-progress, unresolved drift, passed QE but never eval'd, parked before it started). Read-only digest, runnable manually or on a schedule.. Invoke explicitly: $wf-triage [--stale-days N] — staleness threshold for in-progress features (default 14)

WellForge command — Upgrade a scaffolded project to a newer template version (copier update + AI conflict resolution). Invoke explicitly: $wf-upgrade [target version, e.g. v0.2.0 — defaults to latest] [--dry-run]

WellForge parallel-safety discipline — what a git worktree isolates, what it does NOT, and the preflight before dispatching a parallel batch. Use whenever ≥2 dependency-independent agents are about to be dispatched ($wf-implement Step 3, $wf-orchestrate implementation stages), whenever an agent in a worktree hits a failure it cannot explain, and whenever deciding if a batch is safe to parallelize at all. Authoritative for the touches-nothing-outside-itself rule, the shared-state enumeration and its three dispositions, the env carry-in step, file-overlap DAG edges, and the isolate → constrain → integrate → reconcile → prune protocol.