Skip to content

AGENTS.md

Latest commit

 

History

History
73 lines (55 loc) · 6.78 KB

AGENTS.md

File metadata and controls

73 lines (55 loc) · 6.78 KB
Raw

AGENTS.md

bex is the open-source Render alternative — AI-native (ADR008). A Go Kubernetes operator reconciles App CRs (app.bex.co/v1alpha1, bex-system) into running services. All Go lives in lego/ (Latin legō, "I assemble") — one image, four workspace modules: types/ (CRD contract, leaf), operator/ (mechanism, DB-free manager), backend/ (bex-api on :8090 + SSH gateway), cli/ (Render CLI launcher, bex-cli/v* train). operator → types ← backend; cli imports none.

Repo map

  • lego/ — all Go, self-contained (go.work, Dockerfile; context lego/). README, workspace rules.
    • lego/types/ — App/Database CRD types
    • lego/operator/ — manager → Deployment/Service/Ingress; owns config/ + codegen. operator guide
    • lego/backend/ — bex-api (REST/GraphQL/MCP + OpenFGA) + ssh-gateway. backend guide
    • lego/cli/ — bex CLI launcher (pinned render-oss/cli). README
  • dashboard/ — TanStack Start + Apollo + shadcn, client of bex-api GraphQL. dashboard guide
  • infra/ — day-0: Terraform + Cluster API (local-capd ⇄ hetzner-caph)
  • deploy/gitops/ — day-1: Argo CD platform infra (not user deploys)
  • examples/ — whoami-app.yaml, hello-go/
  • scripts/ — cluster helpers (mock-cluster.sh, app-apply.sh, deploy-sample.sh)
  • docs/ — one file per topic. Full catalog in docs/AGENTS.md
  • .pm/ — internal PM board (may be stale). Conventions in .pm/AGENTS.md

Commands

All make targets live in lego/operator/; see lego/AGENTS.md for workspace Go-version split + codegen. CI gates:

  • make test (operator, from lego/operator/) — CRD/RBAC codegen + envtest
  • cd lego/backend && go test ./... — backend (real Postgres + OpenFGA in CI)
  • make lint (all four modules) — golangci-lint + whole-program dead-code analysis; depguard guards the id convention
  • cd lego/cli && go test ./... — CLI launcher

All three platform suites + dashboard/yarn test must pass before deploy.yml builds.

Local cluster workflow

  • bash scripts/mock-cluster.sh — kind infra + CAPI + CAPD app cluster; kubeconfig infra/local/bex.kubeconfig (gitignored)
  • bash scripts/mock-cluster.sh scale N — add/remove workers
  • scripts/app-apply.sh <bex.yml> — render.yaml-shaped bex.yml → App CR (DRY_RUN=1 preview)
  • scripts/deploy-sample.sh / kubectl get apps.app.bex.co — deploy + status

Environment variables

Inventories live with the code (cascading):

Docs — where to look

Full ADR/ledger catalog with one-line summaries: docs/AGENTS.md (cascading — loaded only when working in docs/).

Key entry points:

Rules

  • Never git commit/push unless user runs /ship (Claude) or $ship (Codex), or explicitly requests an rt-* routine run. A routine request authorizes planning, fixing, verification, and invoking ship in the same run without first filing a .pm milestone. Honor explicit audit-only or no-ship limits; follow the ship skill’s safety rules.
  • Never commit/print .env or *.kubeconfig.
  • Local dev environments are pre-approved (user decision 2026-09-09). scripts/dev-env.sh <N> {up,down,status,clean,env} for any dev-N, and scripts/mock-cluster.sh (bring-up, reprovision, scale N) on the local kind/CAPD cluster, never require user approval — run them whenever the work needs it, including destructive recovery (reprovision, clean) when the harness's own diagnostics point there. Still respect each harness's isolation boundaries (own dev-N namespaces/ports; read-only on other workstreams' stacks), and report what was rebuilt.
  • Skill layout: canonical .claude/skills/<name>/SKILL.md; .agents/skills/<name> is ../../.claude/skills/<name> symlink; no .claude/commands/. Validate: bash scripts/skill-layout-validate.sh.
  • .env.example mirrors .env names (no values). cp .env.example .env must never fall out of date; scripts/gh-secrets.sh pushes .env → GitHub secrets.
  • Markdown CI: npx prettier@3.4.2 --write "**/*.md" before finishing.
  • Go ids: mint only via lego/backend/internal/id (id.New(kind)), hyphen not underscore; boilerplate header per lego/operator/hack/boilerplate.go.txt. See lego/AGENTS.md.
  • .pm done: move folder to done/ (task tNNN.md → done/tNNN.md; milestone mN/ → wN/done/mN/), leave no stub; sync status in workstream README + milestone README + frontmatter. See .pm/AGENTS.md.
  • Dashboard preloading skeletons must match their post-loading contents. A skeleton is a structural preview of the exact ready state at the same responsive breakpoint: preserve its outer bounds, padding, max-width, columns, headings/actions, tabs, and major content regions with stable heights. Do not substitute a generic list/form/detail skeleton when the destination geometry differs. Verify pending and ready states side by side at desktop and narrow-mobile widths; see dashboard/AGENTS.md.
  • Playwright MCP: writes to .playwright-mcp/ (--output-dir in .mcp.json); use bare filenames for screenshots.