forge

Visual-design discipline for forge frontends — brief the work before building (never invent an aesthetic without user input), declare the design system before coding, lean on the component library, use restrained color/type systems, never hand-draw complex SVGs, and verify visually before declaring done.

Write Next.js frontends — generated hooks, component library, Tailwind v4, visual verification, and Connect RPC clients.

Outbound boundary translators. One adapter per third-party system / queue / storage backend; narrow interface, vendor-neutral callers.

Write Connect RPC handlers — proto-driven codegen, the thin-translation handler pattern (validate, extract auth, convert proto↔internal, call service, wrap errors via `svcerr.Wrap`), middleware, and testing. Business logic lives in `internal/handlers/<svc>/contract.go`, never in handlers.

Forge project conventions and architecture — project structure, generated vs hand-written code, the generate pipeline, proto annotations, contracts, wiring, and naming.

Use-case orchestrators that compose two or more adapters/services. Deps are interfaces only — designed for unit tests with all-mock collaborators.

Proto file reference — annotations, CRUD conventions, field rules, and common mistakes.

Split a multi-service proto file into per-service files — when to split, how to identify shared types, and the commit-per-phase discipline that keeps each step shippable.

Business logic behind an interface — Service interface in domain types, Deps struct for collaborators, sentinel errors at the storage edge.

Investigate bugs — hypothesis formation, code tracing, and common Forge failure patterns.

Debug a k3d multi-cluster e2e env — read the pod status before theorizing the network, hold the pod up on failure, and the nested-cluster gotchas (image pull, host-gateway DNS, path-MTU) that bite only across clusters.

Reproduce bugs — diagnostic logging, runtime evidence collection, and e2e reproduction.

Debug methodology — triage, parallel investigation, and synthesis.

Observability — forge doctor, Grafana dashboards, querying logs/traces/metrics.

End-to-end tests — full stack, multi-service flows, browser testing.

Testing methodology — the test pyramid, mock vs real, harness patterns, flakiness prevention, and discipline.

Integration tests — real database, build tags, transaction isolation.

Unit tests — hermetic, fast, handler-level tests using generated mocks.

Testing methodology — test harness design, mock strategies, flakiness prevention, and structured test planning

Local-cluster dev loop primitives — cluster lifecycle, status, logs, ingress URLs, host/cluster split. Compose with project-specific bash for sibling-repo deploys, helm bootstraps, and webhook listeners.

Migrate serverkit from Run(ctx, cfg, hooks, args) — where args were service NAMES matched through a string registry — to Run(ctx, cfg, serverkit.Server{...}) with FULLY TYPED service selection. The Application interface, Hooks, string-keyed BootstrapOnly selection, the string→inventory mount lookup, AND the generated cmd/otel.go shim are all gone. The cmd layer becomes a real cobra command tree under cmd/<bin>/cmd (devspace idiom), dir-nested by category; each service gets a typed (*app.Components).Mount<Svc> method and its own cmd/<bin>/cmd/services/<name>.go subcommand that passes that method EXPRESSION to a shared cmd.Serve() helper. serverkit OWNS OTel. Use when bumping across the typed-composed-server release.

Migrate DI from wire_gen.go name-matching + the appkit string-keyed DI table to a GENERATED type-topological composition (internal/app/compose.go, func NewComponents(infra) (*Components, error)) that resolves each Deps field BY TYPE from constructed components or fields on an OWNED Infra struct (internal/app/providers.go, OpenInfra). The old pkg/app DI unit is fully removed; a missing required provider is now a loud error (generate-time when provable, compile-time otherwise), not a silent nil. Move setup.go infra construction into Infra/OpenInfra; two-phase setters (e.g. billing.WithReliantAPIKeyIssuer(llm)) are wired by `forge disown internal/app/compose.go` and editing the construction site. Use when bumping across the typed-DI release.

REST URLs on top of Connect handlers via connectrpc.com/vanguard — opt-in runtime transcoding (no parallel codegen), default annotations on CRUD RPCs, and composition with api.openapi.

Reading `forge audit --json` and `forge map --json` — the JSON shapes, common jq queries, CI integration patterns, and the additive-extension contract that keeps consumers stable as new finding types appear.

Non-server long-running binaries — when to use `forge add binary` vs `forge add worker` vs `forge add service`, plus the lifecycle and deploy story.

Create a new Forge project, add components, and understand the development workflow.

Migrate a CLI / library project to forge — --kind cli, second binaries, when contract.go isn't worth it.

Migrate a server-shaped project to forge — services, operators, workers, webhooks, packs, multi-binary cmd/, k8s manifests.

Migrate an existing project to forge — pre-flight, project shape, module path strategy, package porting order, common gotchas.

Write a forge pack — when to use packs vs. scaffold code, the manifest schema, the install lifecycle, conventions.

Scaffold and wire new services, packages, and frontends in a Forge project.

Background workers — adding, implementing, and testing workers (including cron-scheduled).

Authentication, authorization, and multi-tenancy — forge.yaml config, JWT, API keys, RBAC, dev mode, and tenant scoping.

Using forge's contract system — when to use contract.go, how to write one, what forge generate produces, integrating with tests.

One-page index of every forge/pkg/* subpackage. Read this BEFORE porting a utility from an existing codebase — the equivalent may already exist.

Upgrade a forge project to a newer forge binary version — version pinning in forge.yaml, per-version migration skills, and the deprecation cycle policy.

TOMBSTONE — retired migration. v0.2's name-matched wire_gen.go DI (pkg/app/{wire_gen,app_gen,app_extras}.go, AppExtras exact-name resolution) was itself removed. Do NOT migrate toward this shape. To arrive at the current explicit composition root, use v0.x-to-typed-di (and v0.x-to-serverkit-composed for the typed-mount cmd layer).

Migrate a multi-service forge project from binary=per-service (one Application per service in KCL, one image build per service) to binary=shared (one Go binary, cobra subcommand per service, one Docker image, MultiServiceApplication for KCL deploy). Use when CI image builds dominate cycle time or when services share substantial internal libraries.

Migrate top-level handlers/, workers/, operators/ into internal/handlers/, internal/workers/, internal/operators/. The packages are app-internal (no external importers), so they belong under internal/ where the compiler enforces privacy. This is a mechanical move + import-path rewrite; the pkg/ → internal/ fold is a SEPARATE later migration. Use when bumping across the layout-collapse release.

Database work — SQL migrations are the single schema source of truth; forge generate projects the applied schema into entity structs, ORM, CRUD wiring, and frontend pages.