forge-orkes 0.62.0 → 0.63.0

package/experimental/conventions/install.sh

@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+# Forge conventions experimental installer — opt-in stack convention skills + path-scoped rules.
+# Stack-agnostic core stays portable; this pack adds Laravel/PHP, Python, Vue/Inertia, and
+# universal testing/code-quality conventions on demand. See ADR-018.
+#
+# Idempotent. Re-running skips anything already present and warns (never clobbers user files).
+#
+# Usage:
+#   bash experimental/conventions/install.sh [--dry-run] [TARGET] [stack ...]
+#
+#   TARGET   path to the Forge project (default: current directory)
+#   stack    one or more of: laravel python vue testing universal
+#            no stacks given = install all
+#
+# Examples:
+#   bash experimental/conventions/install.sh                 # all stacks, into cwd
+#   bash experimental/conventions/install.sh laravel vue     # only Laravel + Vue, into cwd
+#   bash experimental/conventions/install.sh /path/to/repo python
+#   bash experimental/conventions/install.sh --dry-run laravel
+
+set -euo pipefail
+
+DRY_RUN=0
+TARGET=""
+STACKS=()
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SOURCE_DIR="${SCRIPT_DIR}/source"
+
+ALL_STACKS=(laravel python vue testing universal)
+
+is_stack() {
+  local s="$1"
+  for known in "${ALL_STACKS[@]}"; do
+    [[ "$known" == "$s" ]] && return 0
+  done
+  return 1
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run) DRY_RUN=1; shift ;;
+    -h|--help)
+      sed -n '2,24p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+      exit 0
+      ;;
+    *)
+      if is_stack "$1"; then
+        STACKS+=("$1")
+      elif [[ -z "$TARGET" ]]; then
+        TARGET="$1"
+      else
+        echo "ERROR: unknown argument '$1' (not a path and not a known stack: ${ALL_STACKS[*]})" >&2
+        exit 2
+      fi
+      shift
+      ;;
+  esac
+done
+
+# Defaults: target = cwd, stacks = all
+[[ -z "$TARGET" ]] && TARGET="$(pwd)"
+[[ ${#STACKS[@]} -eq 0 ]] && STACKS=("${ALL_STACKS[@]}")
+
+[[ -d "$TARGET" ]] || { echo "ERROR: target '$TARGET' does not exist" >&2; exit 2; }
+[[ -f "$TARGET/.forge/project.yml" ]] || { echo "ERROR: target is not a Forge project (.forge/project.yml missing)" >&2; exit 2; }
+
+say() { echo "  $*"; }
+
+# Stack → skill names (space-separated)
+skills_for() {
+  case "$1" in
+    laravel)   echo "laravel-conventions" ;;
+    python)    echo "python-conventions" ;;
+    vue)       echo "vue-conventions" ;;
+    testing)   echo "testing-standards" ;;
+    universal) echo "" ;;
+  esac
+}
+
+# Stack → rule filenames (space-separated)
+rules_for() {
+  case "$1" in
+    laravel)   echo "laravel-http.md laravel-services.md laravel-jobs.md laravel-migrations.md" ;;
+    python)    echo "python.md" ;;
+    vue)       echo "vue-inertia.md" ;;
+    testing)   echo "testing.md" ;;
+    universal) echo "code-quality.md testing.md" ;;
+  esac
+}
+
+echo "==> Forge conventions installer"
+echo "    target: $TARGET"
+echo "    stacks: ${STACKS[*]}"
+[[ $DRY_RUN -eq 1 ]] && echo "    mode:   dry-run (no changes)"
+echo
+
+installed=0
+skipped=0
+
+install_skill() {
+  local name="$1"
+  local src="$SOURCE_DIR/skills/$name"
+  local dst="$TARGET/.claude/skills/$name"
+  [[ -d "$src" ]] || { say "WARN: source skill '$name' missing — skipping"; return; }
+  if [[ -e "$dst" ]]; then
+    say "skip: skill '$name' already present (not overwriting)"
+    skipped=$((skipped + 1))
+    return
+  fi
+  if [[ $DRY_RUN -eq 1 ]]; then
+    say "[dry-run] would install skill '$name' → .claude/skills/$name/"
+  else
+    mkdir -p "$TARGET/.claude/skills"
+    cp -R "$src" "$dst"
+    say "installed skill '$name'"
+  fi
+  installed=$((installed + 1))
+}
+
+install_rule() {
+  local file="$1"
+  local src="$SOURCE_DIR/rules/$file"
+  local dst="$TARGET/.claude/rules/$file"
+  [[ -f "$src" ]] || { say "WARN: source rule '$file' missing — skipping"; return; }
+  if [[ -e "$dst" ]]; then
+    say "skip: rule '$file' already present (not overwriting)"
+    skipped=$((skipped + 1))
+    return
+  fi
+  if [[ $DRY_RUN -eq 1 ]]; then
+    say "[dry-run] would install rule '$file' → .claude/rules/$file"
+  else
+    mkdir -p "$TARGET/.claude/rules"
+    cp "$src" "$dst"
+    say "installed rule '$file'"
+  fi
+  installed=$((installed + 1))
+}
+
+# Collect targets, de-duplicate (universal + testing both ship testing.md).
+# Bash 3.2-compatible: space-delimited strings, no namerefs.
+SKILL_LIST=""
+RULE_LIST=""
+contains_word() { case " $1 " in *" $2 "*) return 0 ;; *) return 1 ;; esac; }
+
+for stack in "${STACKS[@]}"; do
+  for s in $(skills_for "$stack"); do
+    contains_word "$SKILL_LIST" "$s" || SKILL_LIST="$SKILL_LIST $s"
+  done
+  for r in $(rules_for "$stack"); do
+    contains_word "$RULE_LIST" "$r" || RULE_LIST="$RULE_LIST $r"
+  done
+done
+
+if [[ -n "${SKILL_LIST// }" ]]; then
+  echo "==> Skills → .claude/skills/"
+  for s in $SKILL_LIST; do install_skill "$s"; done
+  echo
+fi
+
+if [[ -n "${RULE_LIST// }" ]]; then
+  echo "==> Rules → .claude/rules/"
+  for r in $RULE_LIST; do install_rule "$r"; done
+  echo
+fi
+
+cat <<EOF
+==> Done. installed: $installed   skipped (already present): $skipped
+
+Next steps:
+  1. Restart Claude Code in the target repo so the new skills/rules load.
+  2. Path-scoped rules auto-attach when you edit matching files (e.g. app/Http/**, **/*.vue, **/*.py).
+  3. Convention skills load when a task description matches (writing/reviewing Laravel/Python/Vue code).
+
+Anything already present was left untouched. To replace a stale skill/rule,
+remove the existing file first, then re-run.
+
+Uninstall: bash $(dirname "${BASH_SOURCE[0]}")/uninstall.sh '$TARGET' [stack ...]
+EOF

package/experimental/conventions/source/rules/code-quality.md

@@ -0,0 +1,17 @@
+# Code Quality
+
+Always-on rule (additive to core's `agent-discipline.md` — that rule covers
+agent failure modes like scope creep and phantom deps; this one covers code
+*shape*: function size, magic values, nesting). Universal, stack-agnostic.
+
+- Functions do one thing. If the description needs "and", split the function.
+- No magic values. Extract numbers, strings, and configuration to named constants or config files.
+- No dead code, no commented-out blocks. Git has the history.
+- Handle errors at the boundary where you can add context. Do not catch-and-rethrow without adding context about the operation that failed.
+- No premature abstractions. Three similar lines are easier to read than one helper used once.
+- No scope creep. Don't add features, "improvements", logging, metrics, or fallbacks beyond what was asked.
+- Composition over inheritance.
+- Guard clauses over nested conditionals. No more than 3 levels of nesting; extract helpers when you need more.
+- Descriptive names. `resolve_mechanism_to_ips` not `process`. Names describe what the function does, not that it does something.
+- Files under 300 lines, functions under 50 lines. If something grows past that, it's a sign to split.
+- Type hints / type declarations on every public function. Private helpers can skip docstrings but not types.

package/experimental/conventions/source/rules/laravel-http.md

@@ -0,0 +1,21 @@
+---
+paths:
+  - "app/Http/**"
+  - "app/*/*/Http/**"
+---
+
+# Laravel HTTP (Controllers, Requests, Resources)
+
+These files run on every inbound request. Auth, validation, and authorisation are the non-negotiables.
+
+- **Every new route needs auth.** Default to an authenticated middleware group. Only mark a route public with explicit sign-off.
+- **Tenant isolation is assumed, never skipped (multi-tenant apps).** Every query touching tenant-scoped data runs through the tenant scope/middleware. If you are writing raw queries, the tenant filter is your responsibility. (N/A for single-tenant apps.)
+- **Validate via Form Request classes.** Never use `$request->all()`. Use `$request->validated()` — it is the only input the controller should see.
+- **Authorise before acting.** Call `$this->authorize('action', $model)` (or equivalent policy check) before any state change. "Only admins use it" is not an authorisation strategy.
+- **Mass assignment needs a whitelist.** Eloquent models must declare `$fillable`. Never use `$guarded = []`.
+- **Thin controllers.** Controllers parse input, delegate to the module's Service or Action, return the response. No business logic, no multi-model orchestration, no direct DB calls.
+- **Resource classes shape responses.** Do not return Eloquent models *or bare arrays* directly — not even a three-field payload. A raw `response()->json([...])` produces no generated TypeScript type and forces the frontend to hand-roll one. Every data endpoint returns an API Resource or a typed DTO so field exposure is explicit and the contract propagates to the generated types.
+- **Consistent response envelope.** Follow the module's existing response shape. Do not invent a new one.
+- **Rate limiting on sensitive endpoints.** Auth, password reset, token-issuing, and any public write endpoint need a rate limiter.
+- **No business logic in middleware.** Middleware gates and transforms the request; it does not perform domain operations.
+- **Feature flag checks belong in the Form Request or controller, not in route middleware groups.** Route middleware is for structural, cross-cutting concerns (auth, throttle, CORS). Feature access is domain authorization.

package/experimental/conventions/source/rules/laravel-jobs.md

@@ -0,0 +1,19 @@
+---
+paths:
+  - "app/Jobs/**"
+  - "app/*/*/Jobs/**"
+---
+
+# Laravel Jobs
+
+Jobs run detached from the request, often retry, and can run long after the payload was created. Assume nothing about ambient state.
+
+- **Re-verify tenant context inside `handle()` (multi-tenant apps).** The queue worker does not carry the dispatching user's session. Resolve the tenant from the job payload, not from a request-scoped singleton.
+- **Declare `$tries` and `$backoff` explicitly.** No job should rely on framework defaults for retry behaviour. State the retry budget and the backoff strategy.
+- **`handle()` must be idempotent.** A retry or double-dispatch must not double-charge, double-email, or double-write. Use a ledger row, unique constraint, or idempotency key.
+- **Small payloads.** Serialize identifiers, not full models. `SerializesModels` makes this easy but mutation between dispatch and handle can still surprise you — re-fetch inside `handle()`.
+- **Set `$timeout` for anything that makes outbound I/O.** DNS lookups, HTTP calls, third-party APIs. A silent hang blocks the worker.
+- **`failed()` is not optional for critical jobs.** Log with enough context to triage. Page the right channel if the failure is user-impacting.
+- **No business logic in the job.** The job is a scheduler. It calls into a Service or Action that also works outside the queue. Keeps the logic testable without a queue runner.
+- **Queue selection is explicit.** Assign `$queue` by priority (high / default / low) rather than defaulting everything onto the same worker pool.
+- **Do not rescue broadly inside `handle()`.** Swallowing an exception defeats retry and failure handling. Let it bubble; translate at the edges only.

package/experimental/conventions/source/rules/laravel-migrations.md

@@ -0,0 +1,19 @@
+---
+paths:
+  - "database/migrations/**"
+  - "app/*/*/database/migrations/**"
+---
+
+# Laravel Migrations
+
+Migrations run against shared databases. A bad migration is hard to undo.
+
+- **Never modify an existing migration.** Always create a new migration for the change. Existing migrations may have run in production.
+- Every migration must be reversible. Implement both `up()` and `down()`.
+- Test both directions locally before committing.
+- Destructive operations (`dropColumn`, `dropTable`, `renameColumn`) require explicit confirmation the data is not needed. State what data is affected.
+- Add indexes in their own migration, separate from the schema change. Easier to roll back independently and often faster.
+- Prefer the schema builder over raw SQL. Only drop to raw SQL when the builder cannot express the operation, and document why.
+- No production seed data in migration files. Use dedicated seeders.
+- New `NOT NULL` columns on existing tables need a backfill strategy: nullable first → backfill → enforce NOT NULL in a second migration.
+- Foreign keys: declare `onDelete` / `onUpdate` behaviour explicitly. Default to `restrict` unless there's a reason otherwise.

package/experimental/conventions/source/rules/laravel-services.md

@@ -0,0 +1,21 @@
+---
+paths:
+  - "app/Services/**"
+  - "app/*/*/Services/**"
+  - "app/Actions/**"
+  - "app/*/*/Actions/**"
+---
+
+# Laravel Services & Actions
+
+Services and Actions hold the business logic. They are the layer that must stay framework-lean and testable.
+
+- **Constructor injection only.** No `app()`, no `resolve()`, no facades inside the class body. Type-hint dependencies in the constructor so tests can swap them.
+- **Take DTOs or primitives, not Request objects.** A Service that accepts `Request $request` is a controller in disguise. Accept typed data so the Service can be called from jobs, commands, and tests without fabricating a request.
+- **Return typed results — a DTO, model, or result object, not a bare array. Void returns are a code smell unless the operation is genuinely fire-and-forget. A `: array` return shaped as an associative `['key' => ...]` is an untyped blob in disguise: it carries no contract to the controller, the Resource layer, or the generated frontend types. If the shape has named fields, it is a DTO — declare one.**
+- **Transactions wrap the Service call, not stray queries.** Open a `DB::transaction(...)` at the operation boundary. Do not sprinkle `beginTransaction`/`commit` through private helpers.
+- **Resource classes shape responses.** Do not return Eloquent models *or bare arrays* directly — not even a three-field payload. A raw `response()->json([...])` produces no generated TypeScript type and forces the frontend to hand-roll one. Every data endpoint returns an API Resource or a typed DTO so field exposure is explicit and the contract propagates to the generated types.
+- **Consistent response envelope.** Follow the module's existing response shape. Do not invent a new one.
+- **No controller concerns.** Services do not build HTTP responses, do not call `response()`, do not `abort()`. Throw a domain exception and let the controller translate it.
+- **Idempotency where the operation can repeat.** If a retry or duplicate call is possible (webhooks, jobs, user double-clicks), state how the Service handles it.
+- **Tenant context is a parameter, never ambient (multi-tenant apps).** If the Service operates on tenant data, accept the tenant explicitly. Do not rely on a request-scoped singleton inside a Service that might also run from a job or command.

package/experimental/conventions/source/rules/python.md

@@ -0,0 +1,14 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Python
+
+- Type hints on every function signature (public and private), every method, and every module-level variable. Return type too, even when `None`.
+- No mutable default arguments. Use `None` and assign inside the body.
+- Pydantic v2 at boundaries. No raw dicts passed more than one function deep.
+- Never block the event loop inside `async def`. No `requests`, no `time.sleep`, no sync DB drivers.
+- Exceptions re-raised with context: `raise NewError("op failed") from e`, not bare `raise Exception(str(e))`.
+
+Framework detail (Django ORM patterns, FastAPI dependencies, tooling, project structure, error types) lives in the `python-conventions` skill.

package/experimental/conventions/source/rules/testing.md

@@ -0,0 +1,15 @@
+# Testing
+
+Always-on rule. Cheap ambient nudges so the basics fire even when the heavier
+`testing-standards` skill (in this pack) is not loaded for the current task.
+Universal, stack-agnostic. The skill is the deep reference; this is the floor.
+
+- Test behaviour, not implementation. If the test would still pass with a subtly wrong implementation, it's the wrong test.
+- Run the specific test file after a change, not the full suite. Full suite is for commits and CI.
+- Fix or delete flaky tests. Never retry to make a test pass.
+- AAA structure: Arrange, Act, Assert. No `if`/`for` logic in the test body.
+- One behaviour per test. If the name needs "and", split it.
+- Test names read as specifications: `it_requires_auth_on_domain_create`, not `test1`.
+- Prefer real implementations. Mock only at system boundaries (network, filesystem, clock, external APIs).
+- Never `expect(true)` or assert only that a mock was called without checking its arguments.
+- No tests for pure refactors, comment changes, file renames, or type-only changes.

package/experimental/conventions/source/rules/vue-inertia.md

@@ -0,0 +1,24 @@
+---
+paths:
+  - "resources/js/pages/**"
+  - "resources/js/components/**"
+  - "**/*.vue"
+---
+
+# Vue + Inertia
+
+Inertia makes the Laravel controller the single source of truth for page state. Client state is a cache, not a database. (The Inertia-specific points below apply when the project uses Inertia; the Vue/TypeScript points apply universally.)
+
+- **`<script setup lang="ts">` only.** Composition API. No Options API in new files. No `any` types — if you reach for `any`, type the shape properly or accept `unknown` and narrow.
+- **Server is the source of truth.** Page data arrives as Inertia props. Do not fetch the same data with `axios` on mount just because it is convenient.
+- **Never `as`-cast an HTTP/`useHttp`/`axios` response to assert its shape.** A loosely-typed response means the backend contract is undefined — fix the contract, do not override the compiler. The cast disables the one check that would catch backend drift.
+- **Response shapes come from the generated types file (e.g. `types.gen.ts`), never hand-declared.** If the generated type you need does not exist, the backend is missing a Resource/DTO — stop and add it, then regenerate. Do not write a local `type` that mirrors a server payload.
+- **No new Vuex.** Use Inertia shared props, `provide/inject`, or a scoped `ref`/`reactive`. A store for cross-page UI state needs explicit justification.
+- **Form submission via `useForm`.** Do not hand-roll `axios.post` + manual validation state. `useForm` handles errors, processing flags, and the Inertia navigation cycle.
+- **`:key` is a stable identifier, not the index.** Using array index as `:key` breaks component identity on reorder and causes stale form state.
+- **Emit names are past tense.** `@updated`, `@created`, `@deleted`, `@selected`. Declare them in `defineEmits<{}>()` with types.
+- **Props are typed and required by default.** `defineProps<{}>()` with a TypeScript interface. Default values via `withDefaults()`, not inline.
+- **Computed for derivations, watch for side effects.** If a `watch` is updating a ref based on another ref, it should be a `computed`.
+- **Components under 250 lines.** Past that, extract child components or a composable. The template getting hard to scan is the signal.
+- **Accessibility is not optional.** Semantic elements, `aria-*` on interactive custom components, visible focus states, keyboard navigation.
+- **Use design tokens, not arbitrary values.** Use the project's configured scale (e.g. Tailwind tokens). `w-[13px]` and `#3a7bc8` inline are code smells — add a token or use an existing one.

package/experimental/conventions/source/skills/laravel-conventions/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: laravel-conventions
+description: Laravel and PHP coding standards. Use when writing, reviewing, refactoring, or modifying PHP code in Laravel applications. Covers strict types, architecture patterns, Eloquent usage, testing, and security.
+---
+
+# Laravel / PHP Conventions
+
+## Language standards
+
+- `declare(strict_types=1)` at the top of every PHP file
+- PHP 8.2+ (use the project's actual minimum; prefer modern syntax throughout)
+- Constructor property promotion for value objects and services
+- Enums (not constants) for fixed sets of values
+- Match expressions over switch statements
+- Named arguments for functions with 3+ parameters
+- Return types on all methods. Parameter types on all methods.
+- Union types where appropriate: `string|int`
+
+## Architecture
+
+- Slim controllers: max 5 public methods (index, show, store, update, destroy)
+- Business logic in Service classes, not controllers or models
+- Form Requests for all input validation
+- API Resources for all response transformation
+- Action classes for complex single-purpose operations
+- One class per file, following PSR-4 autoloading
+
+```php
+// Correct: thin controller, logic in service
+class DomainController extends Controller
+{
+    public function store(StoreDomainRequest $request, DomainService $service): DomainResource
+    {
+        $domain = $service->create($request->validated());
+        return new DomainResource($domain);
+    }
+}
+
+// Wrong: business logic in controller
+class DomainController extends Controller
+{
+    public function store(Request $request): JsonResponse
+    {
+        $validated = $request->validate([...]);
+        $domain = Domain::create($validated);
+        // 50 more lines of business logic...
+    }
+}
+```
+
+## Eloquent
+
+- Eager load relationships to prevent N+1 queries: `->with(['relation'])`
+- Use query scopes for reusable query logic
+- Soft deletes via `SoftDeletes` trait where appropriate
+- Never use `DB::raw()` without parameterised bindings
+- Prefer Eloquent methods over raw queries
+- Use `$guarded` or `$fillable` on all models
+
+## Testing
+
+- Pest PHP or PHPUnit for all tests -- check what the project already uses and follow that
+- Feature tests for API endpoints (HTTP tests)
+- Unit tests for Services and Actions
+- Use factories and seeders for test data
+- `RefreshDatabase` trait for database tests
+
+## Code style
+
+- Laravel Pint where configured for formatting (PSR-12 based)
+- PHPStan where configured at level 8 minimum
+- PHP_CodeSniffer where configured (use the project's standards file)
+- Follow Laravel naming conventions:
+  - Models: singular PascalCase (`User`, `DomainConfig`)
+  - Controllers: singular PascalCase + Controller (`UserController`)
+  - Migrations: `create_users_table`, `add_status_to_domains_table`
+  - Routes: plural kebab-case (`/domain-configs`)
+
+## Security
+
+- Always use parameterised queries (Eloquent handles this)
+- Validate all input via Form Requests
+- Use policies for authorisation
+- Never expose internal IDs without authorisation checks; prefer UUIDs for public identifiers when the model has them
+- Hash sensitive data, encrypt at rest where required
+- If the application is multi-tenant, treat tenant isolation as a hard requirement: every tenant-scoped query runs through the tenant scope, and at least one test per tenant-scoped endpoint proves cross-tenant reads are denied. (Skip this section for single-tenant apps.)
+
+## Project structure
+
+Standard Laravel layout:
+
+```
+app/
+├── Http/
+│   ├── Controllers/
+│   ├── Requests/
+│   ├── Resources/
+│   └── Middleware/
+├── Models/
+├── Services/
+├── Actions/
+├── Policies/
+└── Observers/
+```
+
+This skill also supports a **module layout** some projects adopt, where each
+domain module nests its own `Http/`, `Services/`, `Actions/`, etc. under a
+per-project, per-module path such as `app/<project>/<module>/Http/...`. The
+path-scoped rules in this pack are dual-globbed so they fire on either layout.
+Follow whichever layout the project already uses — do not introduce a new one.
+
+## Laravel Boost MCP
+
+If the project has [Laravel Boost](https://github.com/laravel/boost) installed, use its MCP tools to inspect the database schema, routes, configuration, and logs rather than guessing from code. Boost provides runtime context about the application that static file reading cannot. Its generic Laravel guidelines supplement but do not override the conventions in this file. Where Boost's guidelines conflict with these standards, follow this file.
+
+## Common agent mistakes to avoid
+
+- Don't put business logic in controllers
+- Don't skip `declare(strict_types=1)`
+- Don't use `DB::raw()` without bindings
+- Don't forget eager loading (N+1 queries)
+- Don't validate input inline in controllers — use Form Requests
+- Don't return raw arrays from API endpoints — use Resources
+- Don't skip authorisation checks (policies)

package/experimental/conventions/source/skills/python-conventions/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: python-conventions
+description: Python coding standards and conventions. Use when writing, reviewing, refactoring, or modifying Python code. Covers type hints, async patterns, Pydantic usage, dependency injection, tooling, and project structure.
+---
+
+# Python Conventions
+
+## Language standards
+
+- Python 3.11+ with modern syntax throughout
+- `X | None` not `Optional[X]`
+- `list[str]`, `dict[str, int]` not `List[str]`, `Dict[str, int]`
+- Type hints on ALL functions (public and private), all method signatures, and all module-level variables
+- Use `type Alias = ...` for type aliases where appropriate
+- No mutable default arguments. `def f(x=[])` is a bug. Use `None` and assign inside the body.
+- Context managers for all resources: files, connections, locks, temp dirs. `with` always.
+- f-strings for formatting. Not `%` or `.format()`. Not `+` concatenation with variables.
+- `pathlib.Path`, not `os.path`. New code uses `Path`.
+- `enum.Enum` for closed sets of values. Not string constants.
+
+## Data validation
+
+- Use Pydantic v2 (BaseModel) for any data crossing a boundary: API requests/responses, config, external data, DB row mapping
+- Use dataclasses only for pure internal value objects with no validation needs
+- Never use plain dicts for structured data
+
+## Async patterns
+
+- `async def` for all I/O-bound operations (DNS, HTTP, database queries)
+- `asyncio.TaskGroup` (3.11+) for concurrent operations, not `asyncio.gather`
+- Sync `def` for CPU-bound and pure computation
+- Never block the event loop inside `async def`. No `requests.get`, no `time.sleep`, no synchronous DB drivers. Use `httpx.AsyncClient`, `asyncio.sleep`, async DB drivers.
+- Do not call `asyncio.run` inside a running loop. Use `await` or schedule on the existing loop.
+
+## Django
+
+- Atomic updates use `F()` expressions: `obj.counter = F('counter') + 1` then `save(update_fields=['counter'])`. Never read-modify-write without a lock.
+- Batches use `bulk_create` / `bulk_update`. Looping `.save()` over hundreds of rows is a performance bug.
+- `select_related` for forward FKs, `prefetch_related` for reverse and many-to-many. Profile before guessing.
+- Migrations are reversible. Data migrations and schema migrations live in separate files. Never edit a migration after it has run anywhere.
+- No raw SQL unless the ORM cannot express it. When you must, parameterise. Never f-string values into SQL.
+
+## FastAPI
+
+- Pydantic models on every request and response. `model_config = ConfigDict(extra="forbid")` on request models so unknown fields are rejected loudly.
+- Auth, DB session, current user — all declared via `Depends()` so they are overridable in tests.
+- Return a model or a `Response`. Never a raw dict. The response model enforces the contract.
+- Background work goes to a queue, not `BackgroundTasks`, for anything the user would notice failing.
+
+## Dependency injection
+
+- Protocol classes for interfaces. NOT ABC/abstract base classes.
+- Constructor injection for all dependencies
+- No module-level singletons or global state
+
+```python
+# Correct: Protocol defines the contract
+class DNSResolver(Protocol):
+    async def resolve(self, domain: str) -> list[str]: ...
+
+class MyService:
+    def __init__(self, resolver: DNSResolver) -> None:
+        self._resolver = resolver
+
+# Wrong: inheriting from ABC
+class DNSResolver(ABC):
+    @abstractmethod
+    async def resolve(self, domain: str) -> list[str]: ...
+```
+
+## Tooling
+
+- `uv` for dependency management. Never `pip install` directly.
+- `ruff` for linting and formatting
+- `mypy` in strict mode for type checking
+- `pytest` with `pytest-asyncio` for testing
+- `structlog` for logging. Never `print()`, never stdlib `logging` directly.
+
+## Error handling
+
+- Typed exceptions for application-specific errors, not generic `Exception`
+- Result types where appropriate for expected failure paths
+- Never bare `except:` or `except Exception:`
+- Log errors with context before re-raising
+
+## Project structure
+
+- Source code in `src/{package_name}/`
+- One module per concern. The parser parses. The resolver resolves.
+- `__init__.py` exports only public interfaces
+- Tests in `tests/unit/` (no network, no DB) and `tests/integration/`
+
+## Common agent mistakes to avoid
+
+- Don't use `Optional[X]` — use `X | None`
+- Don't use `asyncio.gather` — use `asyncio.TaskGroup`
+- Don't create abstract base classes — use `Protocol`
+- Don't use `print()` for logging
+- Don't put business logic in `__init__.py`
+- Don't skip type hints on private methods