Guidelines

Guide agent through creating mermaid class diagrams for entity relationships

Set up a deployment adapter (Dokploy, docker-compose, SSH) for a registered server

Review existing user stories and function models before writing new ones to ensure consistency

Create a docker-compose project in Dokploy for Git-sourced deployment

How to securely store and reference credentials in SBX workspace projects

Research a question, analyze options, recommend a source-backed decision, and record it

Cross-platform guideline ensuring agents research dependencies thoroughly before adoption. Uses context7 MCP for current documentation, investigates known issues, prefers official/battle-tested packages, vets third-party deps, and always consumes libraries through SBX wrapper packages.

Two-tier dictionary architecture — system defaults (YAML) + project extensions (DB) with CLI promotion workflow

Create, research, and validate a domain expert that captures specialized knowledge from sources

Canonical pattern for localizing DYNAMIC row content (entity field values) — per-row translations JSONB, base-column fallback, FTS folding, and the boundary against the UI-chrome i18n key system

Build domain entities through Feature-Driven Development's five processes

Guide agent through domain entity modeling with IDEA+PD+UI/SI/MD layers

Design test fixtures as specifications before implementation — fixture-first TDD

Provide navigable, queryable, auto-updating access to .framework content via CLI, API, and Web

Use git commit history as a structured, searchable knowledge source for component work — trailers enable domain filtering, LESSONS blocks capture fix knowledge, dynamic queries prevent repeated mistakes

Validation rules and requirements for implementation capability deliverables

Detailed ETVX pipeline for implementation capability with subprocess breakdown

Standards, rules, and patterns for the implementation capability with infrastructure variants

Deploy shared infrastructure services (postgres, redis) to a server as independent Dokploy apps

Define the layered security architecture for web applications — each layer hides the one below it

Every package, CLI command, and API endpoint MUST have test coverage — no exceptions

Wait for the PR opened in FDD5.COMMIT to be merged before the task completes

Enforce that every SDLC task produces traceable, complete models before closing. Code without requirements has no reason to exist — TDD principles applied to models. Quick bootstrap during FDD4 is fine; FDD5 gates enforce.

Validation rules and requirements for modeling capability deliverables

Detailed ETVX pipeline for modeling capability with subprocess breakdown

Standards, rules, and patterns for the modeling capability with infrastructure variants

Step-by-step procedure for creating a new shared package in a monorepo with proper TypeScript, build, and dependency setup

Three-tier TypeScript configuration strategy for monorepos — base, type-specific, project-specific

How to provision a new project with infrastructure allocations

Register a client project as a deployment mirror with external repo, SSH deploy key, and Dokploy wiring

Define the complete workflow for creating new SBX schemas with Active Object support

Guide agent through creating mermaid sequence diagrams for data flows

Decision matrix and implementation pattern for shadcn/ui component placement in a monorepo — shared core vs app-specific extensions

Patterns for creating shared types used across multiple projects — attribute split, field mapping, fixtures

All SI functions (filesystem, network, DB, external API) execute server-side by default. Client-side SI is an explicit opt-in that requires a declared reason. This prevents accidental data leakage, bundle bloat from server-only deps, and security issues from exposing API keys or auth tokens to the browser.

Design patterns for System Integration (SI) layer

Guide agent through creating state diagrams for entity lifecycle management

Define testing process for quality assurance and verification

Define expected testing deliverables and validation rules

Guide agent through domain type creation — category selection, reference semantics, attribute-groups, co-location

Comprehensive audit methodology for typography, color contrast, visual composition, and reading rhythm — machine-readable governance consumed during FDD4.UI.VERIFY and code review

Guide agent through writing user stories that bridge goals to function models

Naming convention for 1Password items in the sbx.workspace vault

Health check procedures and rollback verification after deployment

Step-executable security checklist for web application features — consolidates nfr-platform-matrix security constraints into phase-organized checkable items

Generate web-standard favicon, apple-touch-icon, and OG image assets for SvelteKit apps

Enforceable rules for robots.txt validity, sitemap.xml health, llms.txt format, and canonical URLs. Operationalises the seo-specialist role's crawlability mandate into pass/fail checks for every web product.

The single runnable pre-deploy gate for any web product — one checklist that DETECTS every performance, accessibility, crawlability, social-meta, and structured-data issue automatically. Run this before shipping shredbx, BR, or any future web product; it maps each detector to the domain guideline it enforces.

Operational Core Web Vitals rules — image delivery, CSS/JS critical path, composited animation, DOM budget, caching. Operationalises the CWV NFR (nfr-platform-matrix) into enforceable, reusable pass/fail rules for every web product.

How to configure Dokploy compose projects from Git repos

How to promote changes through dev → stage → prod environments

Post-deploy verification procedures for Dokploy compose deployments

Guidelines for production docker-compose files used by Dokploy

Per-app SA token setup via Dokploy env vars

How to connect infrastructure services to workspace projects

Configure and deploy SvelteKit applications to Vercel from a monorepo using the managed git-push-to-deploy pipeline

Concrete patterns for adopting pkg/httputil (Go) + zod via $lib/server/validation.ts (Svelte) in any workspace app. Companion to nfr-enforcement-non-negotiable.yml (the rule) — this file is the cookbook (the how).

Guide agent through defining API contracts — routes, request/response shapes, error codes

Guide agent through updating API documentation after implementation

How to mask credentials in Go API response payloads

Guide agent through creating Chi router API route handlers

Guide agent through credential masking in API responses

Guide agent through curl-based API endpoint verification

Governs how Go route handlers construct HTTP clients for external APIs. Prevents ad-hoc client construction and ensures centralized credential resolution.

How to create, organize, and consume test fixtures in Go packages

Complete configuration checklist for Go REST API applications — ensures nothing is forgotten during modeling

Decompose monolithic Go HTTP API handlers into domain-scoped handler structs composed via Chi Mount()

Guide agent through Go backend implementation — handlers, services, types

Centralized HTTP client resolution for external service APIs (Dokploy, Gateway). Eliminates ad-hoc client construction in route handlers by providing a Registry that resolves, caches, and returns typed clients per server name.

Ensure parallel methods (Connect/Test, Create/Update) share identical option construction to prevent feature drift

Safely persist state to YAML files under concurrent access using mutex-protected atomic writes

Complete configuration checklist for Go packages — ensures nothing is forgotten during modeling

Generate Mermaid diagrams from YAML model files using raw map parsing and DSL string building

Decompose HTTP handlers into domain-scoped structs composed via chi subrouter mounting

Define standard implementation patterns for Go services across all internal projects

Guide agent through input validation at API boundaries

Guide agent through Go package.yml model creation (Decision

How to write table-driven tests for Go packages

Template and reference for creating domain type package.yml with layers config, Go types, and fixtures

Enforce compile-time type safety for all database CRUD wrappers — no map[string]any, no string field names, no untyped values

Guide agent through Go unit test creation using table-driven pattern

Prevent dead code where optimization components are created but never integrated into production code paths

Canonical composition for admin editor surfaces: ONE composable shell (TabbedPageShell, @sbx/core-ui) configured per root page — a config-driven heading + a route-driven tab bar whose tabs are the data view(s)/facets plus ONE canonical "Page" tab that edits the public page; page CTAs forwarded UP into the layout's persistent topbar (Save/Publish/Visit ↗); the inverse manager-only "Manage this Page ↗" CTA on the public page; and single-purpose admin pages staying bare. Listing, scaffold, and entity-detail are CONFIGURATIONS of the one shell, never separate components (Decision #0290). Keeps the two surfaces that describe one thing structurally mirrored and mutually navigable.

Guide agent through creating ASCII UI mockups during design phase

Categorization taxonomy for UI components and animations extracted from HTML prototypes. Used during /component-import to classify extracted assets into the correct package, layer, and category. Decision #0208.

Guide agent through designing UI component hierarchy with reuse-check and ownership assignment per level

Ensure all UI components maintain readable contrast in both light and dark themes

Guide agent through Playwright end-to-end test creation

Map user stories to application entry points (routes/pages) with metadata

Enrich user stories with web-specific requirements from page protocol and NFR platform matrix

Define the Section-Browse Navigation pattern — anchor-based sidebar navigation with FeatureSection previews, deep pages, and self-filtering blocks

Guide agent through SvelteKit page and component implementation with Svelte 5 runes

Comprehensive page composition guideline for SvelteKit apps built on @sbx/core-ui. Defines the golden composer-only rule, the atomic component hierarchy, the Three-Level Composition navigation pattern, and practical notes for per-session orientation. Source of truth for what belongs on a page, what belongs in a component, and what belongs in a layout shell.

Svelte 5 runes, component patterns, event handling, and CSS scoping rules for all SvelteKit page and component implementation in this workspace. Sourced from official Svelte 5 documentation — enforced during FDD4.UI steps.

Standard SvelteKit app scaffold structure derived from sbx-web — ensures all apps follow the same tested directory layout

Complete configuration checklist for SvelteKit web applications — ensures nothing is forgotten during modeling

SvelteKit routing, server load functions, form actions, error handling, and layout patterns. Sourced from official SvelteKit documentation — enforced during FDD4.UI steps. Complements the sveltekit-server-load-pattern solution with broader routing coverage.

Use +page.server.ts load functions instead of onMount() for data fetching in SvelteKit pages

Render streaming ML output in stable+tentative zones with commit-window throttle

UI components that depend on async resources (images, deferred data from MD/SI) MUST implement explicit state machines rather than binary show/hide logic. Each component defines its own loading, ready, and error states. Each state controls the component's visible properties and animations. SSR hydration reserves space for the resource so layout does not shift when the resource arrives. Rule: The view is always in exactly one state. State transitions drive property changes, not imperative DOM manipulation.

Categorization for UI components that render device chrome (browser, phone, terminal, IDE), the scenes that compose them (fans, stacks), and the app-level composers that drive them from project data. Prevents chrome-CSS duplication across Fan components, showcases, card covers, and hero groups.

Manage video playback, DOM observation, and navigation state during SvelteKit client-side View Transitions

Define the full composition flow for web application pages — from entry point to primitive, with reuse-first strategy and ownership rules

Composable state management for single-item data with progressive enhancement (get/set → mutate → restore → refresh)

Composable state management for collection data with progressive enhancement (lookup → mutate+track → reorder)

Patterns for composing zustand slices into complete stores with hooks, persistence, and multi-slice integration

Public brand name lives in project.yml `brand:` block; codegen emits per-app Brand constants; internal folder name never changes

Combine for continuous state, async/await for one-shots — Apple-native reactive stack for UIKit MVVM

Feature triple — {Interface protocol, Data struct, Impl class} with constructor DI

Thin Coordinator protocol — addressable navigation graph for UIKit MVVM apps without subclassing UIViewController

iOS 16.0 minimum deployment target — annual review at each major release

Core Data + NSPersistentCloudKitContainer — local-first persistence with automatic private CloudKit sync

XcodeGen for the .xcodeproj + Swift Package Manager for deps — Xcode project as a generated artifact, no CocoaPods

Day-one iOS test harness — AppManagers factories, Service mocks, in-memory CoreData, fixtures, Combine helpers, swift-snapshot-testing

Privacy invariants for local-first Swift apps — no-network, no-content-in-logs, filename opacity

Protocol-based DI container — composition root, constructor injection, bounded service locator

GoF State in Swift — protocol-composed state contract with registry-based factory

Cross the actor → @MainActor boundary safely in Swift 6 strict concurrency. Keep view models as plain Sendable data, never pass non-Sendable types (NSAttributedString, NSView, NSButton, UIView) across isolation domains, and avoid holding @MainActor references from within actor-isolated code.

Crash-safe persistence for AppKit apps using debounced atomic writes to applicationSupportDirectory, applicationWillTerminate flush hook, and recovery-stamp behavior on load. Guarantees the user never loses more than a few hundred milliseconds of work even if the app is force-quit mid-session.

Standard AppKit recipe for a vertical-scrolling NSStackView inside an NSScrollView. Fixes the "history window renders empty" bug class caused by missing width-pin between the scroll view's content view and the documentView.

AppManagers registry + init-injection — testable singleton-like access for UIKit MVVM+Coordinator+Flow apps

VIPER — View/Interactor/Presenter/Entity/Router screen decomposition for testability

Zero-warnings policy — SwiftLint mandatory, strict mode, custom project rules