wellforge

Pulumi Infrastructure-as-Code in TypeScript on Google Cloud — best practices AND scaffolding a new IaC project from scratch (the **Pulumi / GCP / TypeScript path**). Use whenever building or reviewing Pulumi TS programs for GCP, OR scaffolding a new infrastructure project ("new Pulumi project", "set up infrastructure as code", "provision GCP with Pulumi", "IaC for this service"). Covers project + stack layout, typed config, `ComponentResource` abstractions, CrossGuard policy-as-code, unit testing with Pulumi mocks, the keyless credential model (ADC + Workload Identity Federation), and state backends. Trigger for any Pulumi TS task — even "add a bucket", "create a component", "write a policy", or "add a stack". FIRST confirm the target: this is **infrastructure** (Pulumi), not an application backend — for a Hono API use `hono-ts-backend`, for Spring use `springboot-scaffold`. This skill is the source of truth for the `pulumi-gcp-ts` Copier preset (`templates/pulumi-gcp-ts/`); pinned versions here and in the te

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 (/wellforge: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.

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 /wellforge:status surfaces recent runs and cost. Canonical reference for the .forge/runs/ schema — producers and consumers MUST follow it.

WellForge template extraction — turn an existing project into (1) a structured stack profile checked against the shipped presets (the gap check), and (2) an opt-in, org-internal reusable Copier template so a team can scaffold its next service from its own real stack. Use during /wellforge:adopt (Stage 0 always runs the profile+gap; extraction is an opt-in layer) and for the standalone /wellforge:extract-template command. Authoritative reference 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 template generation with copier --defaults verification. This produces an ORG-INTERNAL template the team owns — it never opens a PR to the WellForge repo or ships code upstream.

WellForge Visual Companion — a browser-based tool the designer agent uses during /wellforge:design to show mockups, wireframes, diagrams, and side-by-side layout comparisons instead of describing them in text, capturing the user's clicks. Use ONLY when the designer was invoked interactively with the visual companion enabled (the `--visual` flag on /wellforge:design); NEVER in a headless/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. The design.md artifact is still the deliverable — the browser only helps resolve visual questions faster.

Hono + TypeScript backend — best practices AND scaffolding a new service from scratch (the **TypeScript / Node backend path**). Use whenever 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) — especially when the project is already a TS/pnpm codebase. FIRST confirm the target stack — for a **JVM / Spring Boot / Kotlin** service use the `springboot-scaffold` skill instead; this skill is TypeScript-only. Covers project setup (pnpm, tsx, Biome), 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", or "set up validation".

Scaffold a new WellForge Spring Boot Kotlin service from scratch — the **JVM backend path**. Use when the user wants a new **Spring Boot / Kotlin / JVM** service specifically, OR when the project is already a JVM/Maven codebase. 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 the `hono-ts-backend` skill instead; this skill is JVM-only and must NOT scaffold Spring into a TypeScript codebase. Asks for artifactId + service name, then generates the complete project (Maven, jOOQ, Liquibase, Spring Modulith, Docker Compose, Result/DomainError, kotlin-logging) — all pre-wired.

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 /wellforge:spec, /wellforge:plan, /wellforge:design, and /wellforge:tasks commands — they MUST follow this format exactly.

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 /wellforge:spike, when /wellforge:orchestrate or /wellforge: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.

Standardized checklists for connecting a WellForge project to its ecosystem tools — GitHub (repo, branch protection, secrets), CI, MCP servers, environments and databases. Use during /wellforge: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.

Kotlin and Spring Boot development. Trigger this skill for ANY task involving Kotlin, Spring Boot, JVM, Maven, jOOQ, Liquibase, database migrations, REST APIs, or backend services. Covers WellForge best practices including functional error handling with Result/DomainError, Spring Modulith module boundaries, repository patterns, and Spring configuration. Use for writing code, reviewing code, setting up new services, defining migrations, configuring dependencies, scaffolding modules, or debugging Spring applications. Always trigger for partial tasks like "add a repository", "create a migration", "set up a new module", "add an endpoint", or "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.

Expert React + TypeScript + Vite frontend development skill. Use this skill whenever the user asks to build, scaffold, extend, or refactor a React application using TypeScript. Triggers include: "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 time the user describes frontend work in a React/TypeScript codebase. Always use this skill proactively whenever frontend React/TypeScript code is being produced — even if the user just says "create a form" or "add a new page". Prefer this skill over generic coding responses for any React work.