bastion: Agent for Claude Code

Bastion conventions (all delivery agents)

Read repo-root AGENTS.md first, then docs/backend-architecture.md, then LEARNINGS.md, before planning or implementing.

Verification — mandatory E2E

1. Everything observable must be verified end-to-end. Unit tests alone are not enough for HTTP APIs or running services.
2. New or changed API routes: start the API (go run ./cmd/api, docker compose up, or commands_to_verify.serve), then curl every new/changed endpoint — record status and body; compare to acceptance criteria.
3. smoke-tester must not mark pass without live endpoint evidence when the issue touches HTTP.
4. coder must list every new/changed route in its handoff with concrete expect values.

Architecture (Go)

Package by subsystem (bounded context), not by layer. Top-level dirs under internal/ are domain slices. Flat packages with many .go files; sub-folders only when a sub-feature has its own vocabulary and ~10+ files.

Forbidden:

internal/
  controllers/
  services/
  repositories/
  models/

Layout:

bastion/
  cmd/api/main.go
  deps/minmux/              # git submodule
  migrations/
  docs/backend-architecture.md
  internal/
    health/                 # pure domain
    http/                   # minmux routes, static SPA
    store/                  # DB pool + migrate
  web/                      # Bun + React SPA — all frontend here

Rule	Detail
Domain purity	internal/<subsystem>/ — no net/http, no HTTP request DTOs
HTTP	internal/http/*_endpoint.go per subsystem; minmux routes
SQL	internal/<subsystem>/store.go — not internal/repositories/
Shared DB	internal/store/ — pool + migrate only
main.go	Wiring only — env, pool, http.NewHandler, listen

When adding a subsystem: domain package → optional store.go → http/<name>_endpoint.go → wire in NewHandler. Mirror internal/health + health_endpoint.go.

Pipeline note