Agentic cheat sheet

A one-page, scannable version of how Claude works on Baseleg. Distilled from agents/README.md (the plain-language why), CLAUDE.md (the enforced rules), and the agents/instructions/*.md agent-facing summaries. If a rule here feels too terse, follow its link — this page trades completeness for something you can scan in under a minute.

The delivery loop

1. File an issue (spec-kit template)
2. /tdd-plan <issue>       → .workspace/<issue>/{spec-kit,test-plan,impl-plan}.md
3. Implement one RED/GREEN/REFACTOR cycle at a time
4. /code-review (or /security-review for auth/permissions/compliance)
5. Open PR — Traceability + Validation results filled with real command output

• Step 1 uses .github/ISSUE_TEMPLATE/feature_request.md — INTENT, SCOPE, REQUIREMENTS (FR-NNN), SUCCESS_CRITERIA (SC-NNN), CONSTRAINTS, NON_GOALS, TEST_EXPECTATIONS. Nothing auto-rejects a vague one — the discipline is on the author.
• Step 3: each cycle is a named failing test, confirmed to fail for the right reason, then the minimal code to pass it. See a full worked example in agents/examples/README.md.
• Step 5: paste real pnpm typecheck/pnpm test/pnpm lint output — a description of expected output doesn’t satisfy this.

Run /compliance-audit after a large feature or before a release — the hooks below are diff-based and never check the whole repo, so drift introduced before a hook existed (or in a file nobody’s touched since) won’t otherwise surface.

Governance hooks (hard gates, not reminders)

Hook	Blocks	Override
evidence-gated-commit.js	Commit touching packages/**, apps/**, or db/migrations/** if pnpm typecheck or pnpm test fails	None — fix the failure
docs-and-tests-guard.js	App/domain logic change with no test in the same bounded context; new exported domain concept with no docs/domain/** change	[no-test-needed: <reason>] / [no-docs-needed: <reason>] in the commit message
destructive-ops-guard.js	Force-push, git reset --hard, rm -rf outside safe paths, raw DELETE/DROP without WHERE, D1 --remote ops, pipe-to-shell downloads	None
secrets-scanner.js	Edit/Write matching high-confidence secret formats (API keys, JWTs, PEM keys, credentialed connection strings)	None — first line of defense only, not a substitute for real secret scanning
self-protection-guard.js	Edit/Write to .claude/settings.json, .claude/hooks/**, .github/workflows/**, .github/CODEOWNERS	None — a human must change these directly

Architecture rules

• Canonical stack: Astro + TypeScript + Tailwind, Cloudflare Workers/Pages (apps/web), D1 + Drizzle, pnpm workspaces + Turborepo, Vitest.
• Dependency direction: apps/* → packages/application/* (+ packages/ui, selected domain types) → packages/domain/* + packages/shared/*. packages/infrastructure/* → domain + shared.
• Forbidden: domain importing infrastructure; UI importing infrastructure; Astro routes importing Drizzle schema or repository implementations directly.
• Bounded contexts: People, Aircraft, Scheduling, Training, Billing, Compliance, Notifications, Reporting — v1 spine is People/Aircraft/Scheduling. See the Domain overview & context map.
• Where logic belongs: domain = business rules/invariants; application = use cases/orchestration/ports; infrastructure = D1/Drizzle/adapters; UI = rendering + calling use cases, no business rules.
• Add an ADR for: layering/dependency rule changes, runtime/hosting choices, database/migration strategy, a new major framework/library, or a bounded-context/cross-context-ownership change. Full rules: Package boundaries, Architecture overview.

Coding standards

• Strict TypeScript; don’t weaken tsconfig.json without an ADR.
• Explicit return types at public/package boundaries — don’t rely on inference at the surface.
• Use Result<T, E> for expected domain failures; reserve throwing for truly exceptional cases.
• Typed identifiers (PersonId, not string) — prevents mixing IDs across contexts.
• Keep modules small and cohesive; avoid “god files”. Don’t add a new library without clear benefit and documentation. Full rules: Coding standards.

Testing rules

• Every application use case: happy path + key failure paths.
• Every bug fix: adds regression coverage.
• Scheduling and any billing/compliance rules need strong domain tests.
• D1-bound flows gain runtime-aware integration tests once that wiring exists. Full model: Testing strategy.

UI rules

• Use @baseleg/ui first; don’t hand-roll a component that already exists.
• Tokens only — no hardcoded colors/spacing, no styling drift.
• No new component library without an ADR.
• Update docs/ux/components/ or docs/ux/patterns/ whenever adding a reusable component or pattern. Full system: UX overview.

Naming

• Match Ubiquitous language exactly — a Person is a Person, never a User.
• Use cases: <verb><Noun> — createBooking, groundAircraft.
• Repositories: BookingRepository (port) / BookingRepositoryD1 (implementation).

Checklists

New feature — bounded context identified · use case defined · domain rules identified · schema impact assessed · UI states identified · tests added · docs updated · glossary updated if a new term was introduced.

Pull request — package boundaries respected · no direct page-to-DB shortcut · tests added or updated · docs updated · ADR added if architecture changed · visual atlas updated if a UI pattern was added · /code-review (or /security-review) run, any CRITICAL/security finding surfaced, never silently auto-fixed · Traceability + Validation results filled with real output. Full checklist: Definition of done.