admin-badge
Use when adding a new admin-portal sidebar badge — a pending-item count indicator such as "pending topups", "pending KYC", "unreviewed withdrawals", or any "show count on admin menu" request. Covers the full cross-layer flow: backend AdminBadge trait file + BadgeServiceProvider registration + frontend MenuItem wiring. Do NOT use for Forge user notifications (outbound messages delivered to users), dashboard metrics / charts, or generic global-state counters unrelated to admin work queues.
Repository SourceNeeds Review
frontend-form
Use when building a form anywhere in the frontend — inside a modal, on a full page, as a wizard step, or a settings panel. Typical phrasings: "add a form for X", "settings form", "profile form", "multi-step wizard", "form modal for create/edit Y", "confirm action dialog". Covers `useForm` wiring + `@shared/components` field composition + `modal.open` for form modals + 422 error auto-wiring + submit / cancel / delete button patterns. Do NOT use for: the full admin CRUD-page flow (that's `admin-datatable`, which invokes this for its form modal); picking which shared component to use (`shared-components` — consult that for field-type → primitive mapping); building a `<DataTable>` column filter (not a form, that's the datatable's built-in filter system); auth login/refresh forms (those ship as part of `new-portal`).
Repository SourceNeeds Review
new-event-listener
Use when adding a new event listener — a cross-cutting side effect that fires when a domain event or a Forge model lifecycle event (ModelCreated/Updated/Deleted) is emitted. Typical phrasings: "add an event listener for UserRegistered", "listen when a TopUp is saved", "react to X event", "hook into the model lifecycle event bus", "dispatch a job when Y happens", "add a domain event for X". Covers creating a custom Event struct if needed, writing the listener (single-event, multi-event, or container-resolving variants), and registering it via a service provider. Do NOT use for: adding a `write_mutator` to a model field (that's intra-model, part of `new-model`); implementing `ModelLifecycle<M>` (in-transaction multi-field coordination, also `new-model`); registering a WebSocket channel (separate system, see `src/realtime/` and CLAUDE.md "WebSocket" section); or registering a scheduled / cron task (separate concern, not yet skilled).
Repository SourceNeeds Review
new-store
Use when adding a new frontend shared-state store — a `createStore`-backed container for state that spans multiple components / hooks / pages within a portal. Typical phrasings: "add a shopping cart store", "global notification state", "store for admin's active filters", "track unread count across components", "persistent sidebar collapsed state". Covers choosing portal-local vs shared placement, the state shape + imperative API + selector-hook pattern, and the typical lifecycle (hydrate on mount, update via imperative setters, reset on logout). Do NOT use for: form state (→ `useForm` from `@shared/hooks` — never build custom form state); component-local state that doesn't need sharing (→ `useState` / `useReducer` in-place); server state that a single fetch handles (→ direct `api.get` in `useEffect`; no store needed); auth state (→ `auth.useAuth()` from `@/auth`); locale state (→ `localeStore` / `useLocale` from `@shared/i18n`); runtime config (→ `runtimeStore` / `getConfig` from `@shared/config`).
Repository SourceNeeds Review