build-my-apps

name

build-my-apps

description

Apply the user's general application-building defaults across stacks. Use when building, refactoring, or reviewing apps where language-specific skills may also apply, especially for default Rust backends and Angular frontends, design inspiration, Tailwind styling, structure, event logging, routes/services/libs/models boundaries, PostgreSQL, Temporal, Docker and image registries, CI, releases, JWTs, docs, observability, OpenAPI, permissions, generated clients, tests, or app-wide conventions.

Build My Apps

Core Defaults

Build apps with clear domain boundaries, boring operational workflows, and observable behavior. Prefer explicit structure over clever abstractions.

Choose Rust for backend services and Angular for frontend applications by default unless the user or existing repo clearly chooses another stack.

For frontend work, ask for design inspiration before building. Prefer a website URL, product reference, screenshot, brand guide, or clear descriptive direction. If there is no inspiration or the answer is ambiguous, use Apple's design language as the default guide: clean hierarchy, restrained motion, careful spacing, strong typography, and polished details.

Always use Tailwind for styling frontends. Avoid custom CSS like a plague unless the needed functionality cannot reasonably be done with Tailwind utilities, Tailwind configuration, component variants, or framework-supported class composition.

Use PostgreSQL by default for application persistence. Use Temporal by default for background tasks, durable workflows, retries, and long-running orchestration.

Use Resend as the default email provider.

Use asymmetric signing algorithms for JWTs. Prefer private-key signing and public-key verification over shared symmetric secrets.

Use language-specific skills when applicable:

• Use $build-rust-apps for Rust backends.
• Use $build-typescript-apps for Fastify TypeScript backends.
• Use $build-python-apps for general Python services.
• Use $build-django-apps for Django/DRF services.
• Use $build-microservices for service-to-service permissions, manifests, registration, generated clients, and dedicated auth/accounts frontend architecture.

When multiple skills apply, use this skill for cross-stack defaults and the language skill for implementation details.

Structure

Use the same conceptual boundaries across backends:

• routes or apis: API endpoints only.
• services: internal business logic and orchestration.
• libs: integrations with dependencies and infrastructure.
• models: application, domain, or persistence models.
• middleware: request/response middleware and request context.
• config: environment and runtime settings.
• types or schemas: shared type definitions and API/data schemas.

Keep UI components and endpoint handlers thin. Move reusable business logic into services.

Keep functions small and clean. Avoid dirty branching and deeply nested if statements. Group related behavior under a class, trait, impl block, service, module, or file. Do not put standalone helper functions in route/API files.

Use app/library separation where useful, but do not default TypeScript apps to monorepos. Monorepos are appropriate when there are multiple applications or shared libraries that justify the coordination cost.

Do not be afraid to make large changes or refactors when they are needed to bring the codebase in line with these conventions.

Backend Defaults

Apply these defaults where the framework supports them:

• Validate environment variables at startup with typed settings, such as Pydantic BaseSettings in Python/Django.
• Parse database URLs with the ecosystem-standard parser, such as dj_database_url for Django.
• Use PostgreSQL connection settings and enable atomic request transactions where supported, such as Django ATOMIC_REQUESTS.
• Keep constants shared across files in a constants module/file.
• Ensure new code is typed.
• Keep API handlers/controllers thin; do not use framework shortcuts that blur boundaries, such as DRF viewsets in Django.
• Store static assets and media/uploads intentionally; use WhiteNoise for Django static files and Cloudflare R2/S3-compatible storage for Django media uploads.

Request Event Logging

Every backend should have a wide event log for each request.

Create a request event context in middleware and pass it through functions, classes, services, repositories, clients, and workflow code. Each layer should add useful details to the current event through a standardized API instead of scattering unrelated log lines.

The final event should be logged once at the end of the request lifecycle and should include as much safe detail as possible:

• request ID, method, path, route name, query shape, user agent, remote address, and timing
• auth context, user/service identity, permissions checked, and auth outcome
• service/domain action names and relevant resource IDs
• dependency calls, retries, queue/workflow IDs, database operation summaries, and external service names
• response status, error category, validation failures, and outcome

Never include secrets, raw tokens, passwords, OTPs, private keys, or sensitive payloads. Standardize field names so logs are queryable across services.

Environment Files

Each service must have an .env.example file that lists the environment variables needed to run the service, with comments explaining what they do.

The repo root must also have an .env.example that combines all service variables. In the root file, prefix each variable with the service name. Docker Compose should deconstruct those prefixed variables into the unprefixed variables expected inside each service container.

Keep all .env.example files updated whenever config changes.

Operations

Prefer Docker Compose for local and deployable service dependencies. Every deployable app should have local and production container definitions:

• Local Dockerfile: Dockerfile
• Production Dockerfile: prod.Dockerfile
• Local Compose file: docker-compose.yml
• Production Compose file: docker-compose.prod.yml

Put container entrypoint commands inside Dockerfiles when practical instead of relying on separate entrypoint scripts for app containers.

Ask which image registry to use before wiring image publishing: ghcr.io or docker.io.

Prefer Makefile wrappers for common commands:

• setup/install
• up/down/logs
• format and format-check
• lint
• test
• build
• migrate or migrations
• service-specific run/build/test targets

Keep commands discoverable with a help target when the project has many targets.

Add pre-commit hooks that check formatting and linting.

Temporal

Use the Temporal setup from /Users/lordsarcastic/Code/the-old-ways/temporal as the standard default when adding Temporal infrastructure.

The default Temporal setup should include:

• temporal/Dockerfile with temporalio/server as the base and temporalio/admin-tools as a source for temporal, temporal-sql-tool, and schema files.
• temporal/dynamicconfig/development-sql.yaml.
• temporal/scripts/setup-postgres.sh.
• temporal/scripts/create-namespace.sh.
• temporal/scripts/start-temporal-with-bootstrap.sh.
• Local and prod Compose files at temporal/docker-compose.yml and temporal/docker-compose.prod.yml.

The Temporal container should run a bootstrap entrypoint that prepares PostgreSQL, starts Temporal, waits for health, and creates namespaces from TEMPORAL_NAMESPACES automatically. Require env vars such as DB_PORT, DBNAME, VISIBILITY_DBNAME, POSTGRES_SEEDS, POSTGRES_USER, POSTGRES_PWD, TEMPORAL_ADDRESS, and TEMPORAL_NAMESPACES.

APIs And Contracts

Prefer OpenAPI-first or OpenAPI-aligned APIs:

• Keep request and response types explicit.
• Keep validation at the API boundary.
• Keep standard error responses consistent.
• Include auth and permission metadata in docs where possible.
• Generate clients when multiple services or frontends depend on the API.

Use permission-aware endpoints. Make read/write/delete permissions explicit when they differ.

For microservice architectures with service-to-service calls, use explicit permissions and service manifests. Load $build-microservices and include service manifests, frontend manifests, registration scripts, dedicated auth frontend, and dedicated accounts frontend as appropriate.

For public-facing apps, plan for a CLI and an MCP server. The MCP server should support both streaming HTTP and stdio transports.

Documentation

Apps should have a docs/ folder with architecture notes, planned feature specs, and implemented feature specs.

Use docs/ for Plan Mode outputs so future users and agents can understand why a feature was implemented in a particular way. Keep specs updated when implementation changes materially.

Releases And Versioning

Always ask which release/versioning pattern to use before implementing release CI, tagging, or image tagging.

Supported patterns:

• Git tag pattern for repos with only main: tag releases as v<service-name>-<semantic-version>. Add -beta.<n> for staging releases and -alpha.<n> for dev releases. Omit <service-name>- in non-monorepos.
• Metadata file pattern: use a metadata/version file as the source of truth. This pattern assumes a staging branch and a main branch. Prefix staging branch image tags with staging-.

Use the selected release pattern consistently for Git tags, image tags, and deployment references.

CI And Images

CI should have a quality workflow that checks:

• build
• lint
• formatting
• tests

CI should also have a Docker image workflow that:

• builds the production Docker image from prod.Dockerfile
• tags the image according to the selected release/versioning rules
• pushes to the user-selected registry
• runs migrations using the DATABASE_URL secret tied to the target environment

Keep environment-specific secrets pegged to their environment. Do not reuse production database secrets for staging or development workflows.

Observability

Add observability by default for production-facing services:

• structured request logs
• tracing spans around meaningful service work
• metrics middleware/exporters where useful
• Sentry or equivalent error capture
• graceful shutdown for servers, workers, queues, and pools

Never log secrets, raw tokens, passwords, OTPs, or sensitive payloads.

Testing

Prefer behavior-focused tests:

• service tests for domain rules
• API tests for auth, permissions, validation, and response shape
• persistence tests for migrations and model constraints
• integration tests around external boundaries when feasible
• tests against the Docker Compose database or inside Docker context by default, except when a test truly does not need Docker
• factory-generated models and payloads instead of hand-written model payloads in tests

Use the repo's existing test runner and Makefile targets. Do not replace tooling unless requested.