aether-colony 5.0.0 → 5.2.1

package/.aether/skills/colony/state-safety/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: state-safety
+description: Use when reading or writing JSON state files including COLONY_STATE.json, pheromones.json, constraints.json, or session.json
+type: colony
+domains: [security, state, data-integrity, safety]
+agent_roles: [builder, watcher]
+priority: normal
+version: "1.0"
+---
+
+# State Safety
+
+## Purpose
+
+Colony state files are critical. A corrupted COLONY_STATE.json can lose an entire colony's progress. A malformed pheromones.json can silently break signal injection. This skill teaches safe state file handling to prevent data loss.
+
+## Atomic Writes
+
+All JSON state mutations must use atomic write: write to a temporary file first, then rename to the target. This prevents partial writes from corrupting the file if the process is interrupted.
+
+### Process
+
+1. Write the new content to a temporary file in the same directory (e.g., `COLONY_STATE.json.tmp`).
+2. Validate the temporary file is valid JSON: `jq . file.tmp > /dev/null 2>&1`.
+3. If validation passes, rename the temp file to the target: `mv file.tmp file.json`.
+4. If validation fails, delete the temp file and report the error -- never overwrite good data with bad.
+
+Use `atomic-write` utility when available. If writing state manually, follow these four steps exactly.
+
+## File Locking
+
+Before modifying any state file, acquire a lock to prevent concurrent writes:
+
+1. Call `file-lock acquire <file>` before the write operation.
+2. Perform the read-modify-write cycle.
+3. Call `file-lock release <file>` after the write completes.
+4. Always release locks in error paths -- use trap or ensure-release patterns.
+
+Lock contention should be rare (colony operations are typically single-threaded), but parallel worker spawns during builds can cause races on shared files like pheromones.json.
+
+## Post-Write Validation
+
+After every state file write, validate the result:
+
+```bash
+jq . "$state_file" > /dev/null 2>&1
+```
+
+If validation fails:
+1. Log a warning with the file path and the operation that triggered the write.
+2. Check for a backup (`.bak` extension in the same directory).
+3. If a backup exists and is valid, restore from backup and log the restoration.
+4. If no valid backup exists, report the corruption as a critical error.
+
+Never silently ignore a JSON parse failure. A silent parse error today becomes a mysterious crash tomorrow.
+
+## Corruption Detection
+
+When reading state files, validate before using the data:
+
+- Check that the file exists and is non-empty.
+- Parse with `jq` and check the exit code.
+- Verify expected top-level keys exist (e.g., COLONY_STATE.json must have `goal`, `state`, `current_phase`).
+- If any check fails, follow the fallback chain: try backup, then report error.
+
+## Backup Strategy
+
+Before making significant state changes (phase advances, plan regeneration, seal), create a backup:
+
+```bash
+cp "$state_file" "${state_file}.bak"
+```
+
+Keep exactly one backup per file. The backup represents the last known good state.
+
+## State Files and Their Critical Fields
+
+| File | Critical Fields | Risk if Corrupted |
+|------|----------------|-------------------|
+| COLONY_STATE.json | goal, state, current_phase, plan | Total colony loss |
+| pheromones.json | signals array | Silent signal failure |
+| constraints.json | focus, constraints | Lost constraints |
+| session.json | session_id, colony_goal | Resume failure |
+| midden.json | entries array | Lost failure history |

package/.aether/skills/colony/worker-priming/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: worker-priming
+description: Use when starting work as a spawned worker to understand what context you have been given and how to use it
+type: colony
+domains: [context, priming, awareness]
+agent_roles: [builder, watcher, scout, chaos, oracle, architect, colonizer, route_setter, archaeologist, chronicler, keeper, tracker, probe, weaver, auditor, gatekeeper, includer, measurer, sage, ambassador]
+priority: normal
+version: "1.0"
+---
+
+# Worker Priming
+
+## Purpose
+
+When you are spawned as a worker, your prompt contains assembled context from colony-prime. Understanding what is in your context -- and what might be missing -- helps you work more effectively. This skill teaches you how to interpret your assembled context.
+
+## The 9 Context Sections
+
+Colony-prime assembles up to 9 sections into your prompt. Here is what each contains and how to use it:
+
+### 1. Rolling Summary
+The most important section. Contains a condensed summary of what has happened in the colony so far: completed phases, key outcomes, current state. Read this first to orient yourself.
+
+### 2. Phase Learnings
+Lessons extracted from previous phases. These are things the colony learned while building -- patterns that worked, approaches that failed, technical discoveries. Use these to avoid repeating mistakes.
+
+### 3. Key Decisions
+Major decisions made during the colony's lifetime. These include architectural choices, technology selections, and scope changes. Respect these decisions unless your task explicitly requires revisiting them.
+
+### 4. Hive Wisdom
+Cross-colony patterns from the Hive Brain. These are generalized learnings from other projects on this machine. They are guidance, not absolute rules. If hive wisdom conflicts with project-specific learnings, prefer the project-specific learning.
+
+### 5. Context Capsule
+A snapshot of the most recent session state. Contains the current phase, recent task completions, and in-progress work.
+
+### 6. User Preferences
+The user's stated preferences from QUEEN.md. These override general patterns. If a user preference says "prefer dark mode" and a hive wisdom says "use light mode", follow the user preference.
+
+### 7. QUEEN Wisdom
+Strategic guidance from the colony's QUEEN.md file. This includes project-level principles, workflow preferences, and communication style notes.
+
+### 8. Blocker Warnings
+Any active blockers that may affect your work. If a blocker is relevant to your task, address it or report that you cannot proceed because of it.
+
+### 9. Pheromone Signals
+Active FOCUS, REDIRECT, and FEEDBACK signals. See the pheromone-protocol skill for how to handle these. Always check this section before starting work.
+
+## Missing Sections
+
+Some sections may be absent from your context. This happens when the token budget requires trimming. The trim order is:
+
+1. Pheromone signals (trimmed first -- lowest priority)
+2. QUEEN wisdom
+3. User preferences
+4. Context capsule
+5. Hive wisdom
+6. Key decisions
+7. Phase learnings
+8. Rolling summary (trimmed last -- highest priority)
+
+If a section is missing, it was trimmed for budget reasons. This is normal and not an error. Work with whatever context you have.
+
+## Priority Rules
+
+When context sources conflict, resolve in this order (highest priority first):
+
+1. **Explicit task instructions** -- What you were specifically asked to do.
+2. **REDIRECT signals** -- Hard constraints that override everything except the task itself.
+3. **User preferences** -- The user's stated wishes.
+4. **FOCUS signals** -- Areas to prioritize.
+5. **Phase learnings** -- Project-specific experience.
+6. **Hive wisdom** -- Cross-colony patterns.
+7. **FEEDBACK signals** -- Gentle adjustments.
+
+## Before Starting Work
+
+Every time you begin a task:
+1. Read the rolling summary to understand where the colony is.
+2. Check blocker warnings for anything that affects your task.
+3. Review pheromone signals for constraints and focus areas.
+4. Note any missing sections and adjust expectations accordingly.
+5. Begin your task with full awareness of your assembled context.

package/.aether/skills/domain/.manifest.json

@@ -0,0 +1,24 @@
+{
+  "managed_by": "aether",
+  "version": "2.1.0",
+  "skills": [
+    "django",
+    "docker",
+    "golang",
+    "graphql",
+    "html-css",
+    "nextjs",
+    "nodejs",
+    "postgresql",
+    "prisma",
+    "python",
+    "rails",
+    "react",
+    "rest-api",
+    "svelte",
+    "tailwind",
+    "testing",
+    "typescript",
+    "vue"
+  ]
+}

package/.aether/skills/domain/README.md

@@ -0,0 +1,33 @@
+# Domain Skills
+
+Drop a folder here with a SKILL.md to add custom domain skills.
+Skills created with `/ant:skill-create` are placed here automatically.
+
+## Creating a Custom Skill
+
+1. Create a directory: `mkdir ~/.aether/skills/domain/my-skill`
+2. Create `SKILL.md` inside it with this frontmatter:
+
+```yaml
+---
+name: my-skill
+description: Use when working with my technology
+type: domain
+domains: [my-domain, related-domain]
+agent_roles: [builder]
+detect_files: ["my-config.*"]
+detect_packages: ["my-package"]
+priority: normal
+version: "1.0"
+---
+
+Your best practices and guidance here.
+```
+
+3. The skill will be auto-detected on the next build
+
+## Important
+
+- Your custom skills are **never overwritten** by `aether update`
+- Only skills listed in `.manifest.json` are managed by Aether
+- Use `/ant:skill-create "<topic>"` for Oracle-powered skill generation

package/.aether/skills/domain/django/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: django
+description: Use when the project uses Django for Python web development
+type: domain
+domains: [backend, python, web]
+agent_roles: [builder]
+detect_files: ["manage.py"]
+detect_packages: ["django"]
+priority: normal
+version: "1.0"
+---
+
+# Django Best Practices
+
+## Project Structure
+
+Follow Django's app-based architecture. Each app should represent a distinct feature or domain concept. Keep apps small and focused -- if an app has 20+ models, it probably needs splitting.
+
+Place reusable utilities in a `core` or `common` app. Keep `settings.py` clean by splitting into `base.py`, `development.py`, and `production.py` using a settings package.
+
+## Models
+
+Define explicit `Meta` classes with `ordering`, `verbose_name`, and `db_table` where appropriate. Add `__str__` methods to every model for admin and debugging readability.
+
+Use model managers for complex queries rather than scattering `filter()` chains through views. Create custom querysets with `as_manager()` for chainable query methods.
+
+Always create migrations after model changes with `makemigrations`. Review generated migration files before running them. Never edit migrations manually unless you understand the implications.
+
+## Views
+
+Prefer class-based views (CBVs) for CRUD operations -- they eliminate boilerplate. Use function-based views for complex custom logic where CBV mixins would become contorted. In Django REST Framework, use `ModelViewSet` for standard CRUD and `APIView` for custom endpoints.
+
+Keep views thin. Business logic belongs in services or model methods, not in views. A view should validate input, call a service, and return a response.
+
+## Security
+
+Never expose raw model instances to API responses -- use serializers or forms to control which fields are visible. Always validate and clean form input. Use Django's CSRF protection and never disable it.
+
+Set `DEBUG = False` in production. Configure `ALLOWED_HOSTS` explicitly. Use environment variables for `SECRET_KEY` and database credentials.
+
+## Database
+
+Use `select_related()` for foreign key joins and `prefetch_related()` for reverse and many-to-many relationships to avoid N+1 query problems. Use Django Debug Toolbar in development to spot excessive queries.
+
+Write data migrations for schema changes that need data transformation. Keep schema and data migrations separate.
+
+## Testing
+
+Use `TestCase` for tests that need database access, `SimpleTestCase` for those that do not. Use `factory_boy` or model `baker` over fixtures for test data. Test views through the test client, not by calling view functions directly.

package/.aether/skills/domain/docker/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: docker
+description: Use when the project uses Docker for containerization and deployment
+type: domain
+domains: [infrastructure, containers, deployment]
+agent_roles: [builder]
+detect_files: ["Dockerfile*", "docker-compose.*"]
+priority: normal
+version: "1.0"
+---
+
+# Docker Best Practices
+
+## Dockerfile Construction
+
+Use multi-stage builds to keep production images small. Build dependencies in one stage, copy only the compiled output to a minimal runtime stage. This can reduce image sizes by 10x or more.
+
+Order instructions from least to most frequently changed. `COPY package.json` and `RUN npm install` before `COPY . .` so dependency installation is cached when only source code changes. Cache invalidation on early layers rebuilds everything after them.
+
+Use specific base image tags (`node:20-alpine`), never `latest`. Pin versions for reproducible builds. Alpine-based images are smaller but may lack libraries -- use slim variants if Alpine causes compatibility issues.
+
+## Image Security
+
+Run containers as a non-root user. Add `RUN addgroup -S app && adduser -S app -G app` and `USER app` in your Dockerfile. Running as root inside a container is a security risk if the container is compromised.
+
+Do not include secrets in images. Never use `COPY .env .` or `ARG SECRET_KEY`. Use runtime environment variables or Docker secrets instead.
+
+Minimize the attack surface: install only what you need, remove package manager caches (`rm -rf /var/cache/apk/*`), use `.dockerignore` to exclude `node_modules`, `.git`, and test files from the build context.
+
+## Docker Compose
+
+Use `docker-compose.yml` for local development and testing environments. Define services, networks, and volumes clearly. Use named volumes for data persistence -- anonymous volumes are harder to manage and back up.
+
+Set `depends_on` with health checks for service ordering. Without health checks, `depends_on` only waits for the container to start, not for the service inside it to be ready.
+
+Use `.env` files with Compose for configuration, but never commit them to the repository. Document required environment variables in a `.env.example` file.
+
+## Networking
+
+Use Docker networks to isolate services. Only expose ports that need external access. Internal services (databases, caches) should communicate on internal Docker networks, not through published ports.
+
+## Logging
+
+Log to stdout/stderr, not to files inside the container. Docker captures stdout/stderr and makes it available via `docker logs`. File-based logging inside containers is difficult to access and fills up container storage.
+
+## Health Checks
+
+Add `HEALTHCHECK` instructions to Dockerfiles. A health check lets orchestrators (Compose, Kubernetes) detect when a container is running but the application inside has crashed or hung.
+
+## Resource Limits
+
+Set memory and CPU limits in Compose or your orchestrator. Without limits, a single misbehaving container can starve the host and crash other services.

package/.aether/skills/domain/golang/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: golang
+description: Use when the project uses Go for systems programming or backend services
+type: domain
+domains: [backend, systems, concurrency]
+agent_roles: [builder]
+detect_files: ["go.mod", "*.go"]
+priority: normal
+version: "1.0"
+---
+
+# Go Best Practices
+
+## Error Handling
+
+Check every error. The `if err != nil` pattern is intentional -- Go makes error handling explicit. Never discard errors with `_`. Wrap errors with context using `fmt.Errorf("doing X: %w", err)` so call chains produce readable messages.
+
+Use sentinel errors (`var ErrNotFound = errors.New("not found")`) for expected conditions that callers check with `errors.Is()`. Use custom error types for errors that carry structured data.
+
+## Project Structure
+
+Follow the standard layout: `cmd/` for application entry points, `internal/` for private packages, `pkg/` for public libraries (if any). Keep `main.go` minimal -- it wires up dependencies and starts the server.
+
+One package per directory. Package names should be short, lowercase, and descriptive. Avoid `util` or `common` packages -- they become dumping grounds.
+
+## Concurrency
+
+Do not communicate by sharing memory -- share memory by communicating. Use channels for synchronization between goroutines. Use `sync.Mutex` only for protecting simple shared state where channels would be overkill.
+
+Always ensure goroutines can be stopped. Pass `context.Context` and check `ctx.Done()`. Leaking goroutines is a memory leak that grows over time.
+
+Use `sync.WaitGroup` when you need to wait for a known number of goroutines to complete. Use `errgroup.Group` when any goroutine failure should cancel the rest.
+
+## Interfaces
+
+Define interfaces where they are used, not where they are implemented. Keep interfaces small -- one or two methods is ideal. The `io.Reader` and `io.Writer` interfaces are the gold standard.
+
+Accept interfaces, return structs. This makes code testable -- callers can inject mocks that satisfy the interface.
+
+## Testing
+
+Use table-driven tests for functions with multiple input/output combinations. Name test cases clearly. Use `t.Run()` for subtests so failures identify which case broke.
+
+Use `testing.T.Helper()` in test helper functions so failure messages point to the calling test, not the helper.
+
+## Dependencies
+
+Use `go mod tidy` to keep `go.mod` clean. Vendor dependencies with `go mod vendor` for reproducible builds in CI. Avoid unnecessary dependencies -- the standard library is comprehensive. Check if `net/http`, `encoding/json`, or `os` already do what you need.
+
+## Performance
+
+Profile before optimizing with `pprof`. Pre-allocate slices with `make([]T, 0, expectedCap)` when the size is known. Avoid string concatenation in loops -- use `strings.Builder`. Reduce allocations by reusing buffers with `sync.Pool` for hot paths.

package/.aether/skills/domain/graphql/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: graphql
+description: Use when the project uses GraphQL for API queries and mutations
+type: domain
+domains: [api, query, schema]
+agent_roles: [builder]
+detect_files: ["*.graphql"]
+detect_packages: ["apollo", "graphql"]
+priority: normal
+version: "1.0"
+---
+
+# GraphQL Best Practices
+
+## Schema Design
+
+Design your schema around the client's needs, not your database tables. Use descriptive type names and field names. Every field should have a clear purpose -- do not expose internal implementation details.
+
+Use `ID` type for identifiers, `String` for text, `Int`/`Float` for numbers, `Boolean` for flags. Define custom scalars (DateTime, URL, Email) for domain-specific values that need validation.
+
+Make fields non-nullable by default (`String!`). Only use nullable fields when null carries meaning (e.g., "no value set"). Lists should be non-nullable with non-nullable items: `[User!]!`.
+
+## Queries and Mutations
+
+Separate reads (queries) from writes (mutations). Mutations should return the affected object so clients can update their cache without a refetch. Name mutations as verbs: `createUser`, `updatePost`, `deleteComment`.
+
+Use input types for mutation arguments: `input CreateUserInput { name: String!, email: String! }`. This keeps the schema clean and makes validation straightforward.
+
+## Pagination
+
+Use Relay-style cursor pagination for all list fields: `Connection` type with `edges`, `node`, `pageInfo`, and `cursor`. This handles infinite scroll, bidirectional loading, and real-time updates cleanly. Avoid offset-based pagination -- it breaks when data changes between pages.
+
+## N+1 Problem
+
+GraphQL's nested resolution model naturally creates N+1 queries. Use DataLoader to batch and cache database lookups within a single request. Every resolver that touches the database should go through a DataLoader.
+
+Without DataLoader, a query fetching 50 users with their posts makes 51 database calls (1 for users + 50 for each user's posts). With DataLoader, it makes 2.
+
+## Error Handling
+
+Return errors in the `errors` array, not in the data. Use error `extensions` for machine-readable codes: `{ "extensions": { "code": "UNAUTHORIZED" } }`. Partial failures are valid in GraphQL -- a query can return data for some fields and errors for others.
+
+## Security
+
+Limit query depth (typically 7-10 levels) to prevent deeply nested queries that overwhelm the server. Limit query complexity by assigning cost values to fields and rejecting queries that exceed a budget.
+
+Disable introspection in production unless your API is intentionally public. Introspection exposes your entire schema to attackers.
+
+## Performance
+
+Persisted queries reduce bandwidth and prevent arbitrary query execution. Clients send a hash instead of the full query string. Cache responses at the field level, not the query level, since GraphQL queries are highly variable.

package/.aether/skills/domain/html-css/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: html-css
+description: Use when the project uses plain HTML, CSS, or SCSS for web pages
+type: domain
+domains: [frontend, styling, markup]
+agent_roles: [builder]
+detect_files: ["*.html", "*.css", "*.scss"]
+priority: normal
+version: "1.0"
+---
+
+# HTML & CSS Best Practices
+
+## Semantic HTML
+
+Use the right element for the job: `<nav>` for navigation, `<main>` for primary content, `<article>` for self-contained content, `<section>` for thematic groupings, `<aside>` for tangential content. Avoid div-soup -- excessive `<div>` nesting with no semantic meaning.
+
+Use `<button>` for actions, `<a>` for navigation. Never put click handlers on `<div>` or `<span>` elements -- they are not keyboard accessible.
+
+## Accessibility Fundamentals
+
+Every `<img>` needs an `alt` attribute. Decorative images get `alt=""`. Every form input needs a `<label>` linked via `for`/`id`. Heading levels (`h1`-`h6`) must not skip levels -- go `h1`, `h2`, `h3`, never `h1` to `h3`.
+
+Ensure color contrast ratios meet WCAG AA (4.5:1 for text, 3:1 for large text). Test with browser DevTools accessibility panel.
+
+## CSS Architecture
+
+Avoid deeply nested selectors (more than 3 levels). Flat, specific class selectors are faster and easier to override. Prefer BEM naming (`.block__element--modifier`) for vanilla CSS projects to keep specificity predictable.
+
+Never use `!important` to fix layout problems. It signals a specificity battle -- fix the root cause by reducing selector complexity.
+
+## Layout
+
+Use CSS Grid for two-dimensional layouts (rows and columns simultaneously). Use Flexbox for one-dimensional layouts (a row or a column). Avoid floats for layout -- they exist for wrapping text around images, not for page structure.
+
+Set `box-sizing: border-box` globally. Without it, padding and borders add to element dimensions, making math unpredictable.
+
+## Responsive Design
+
+Use relative units (`rem`, `em`, `%`, `vw`, `vh`) over fixed pixels for sizing and spacing. Set font sizes in `rem` so they respect user browser settings.
+
+Write mobile-first media queries: base styles for small screens, `min-width` breakpoints for larger ones.
+
+## Performance
+
+Minimize CSS file count and size. Remove unused selectors. Avoid expensive properties in animations: stick to `transform` and `opacity` for smooth 60fps transitions. Never animate `width`, `height`, `top`, or `left`.
+
+Place `<link rel="stylesheet">` in the `<head>`. Place `<script>` before `</body>` or use `defer`/`async` attributes to avoid blocking rendering.

package/.aether/skills/domain/nextjs/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: nextjs
+description: Use when the project uses Next.js for server-side rendering or full-stack React
+type: domain
+domains: [frontend, ssr, fullstack]
+agent_roles: [builder]
+detect_files: ["next.config.*"]
+detect_packages: ["next"]
+priority: normal
+version: "1.0"
+---
+
+# Next.js Best Practices
+
+## App Router vs Pages Router
+
+Next.js 13+ uses the App Router by default. Check which router the project uses before making changes. App Router uses `app/` directory with `layout.tsx`, `page.tsx`, and `loading.tsx` conventions. Pages Router uses `pages/` with `_app.tsx` and `_document.tsx`. Never mix patterns within the same route.
+
+## Server vs Client Components
+
+In the App Router, components are Server Components by default. Only add `"use client"` when you need browser APIs, event handlers, hooks, or browser-only libraries. Push `"use client"` as far down the tree as possible -- wrap only the interactive leaf, not the entire page.
+
+Server Components can fetch data directly without `useEffect` or API routes. This is the preferred pattern for data loading.
+
+## Data Fetching
+
+Use `fetch` in Server Components with caching options (`cache: 'force-cache'` for static, `cache: 'no-store'` for dynamic). For mutations, use Server Actions -- functions marked with `"use server"` that run on the server but can be called from client forms.
+
+Avoid calling your own API routes from Server Components. You have direct access to the database and services -- use them.
+
+## Route Handlers
+
+API routes live in `app/api/*/route.ts`. Export named functions matching HTTP methods: `GET`, `POST`, `PUT`, `DELETE`. Always return `NextResponse` objects with appropriate status codes.
+
+## Common Gotchas
+
+Middleware runs on the Edge Runtime -- no Node.js APIs like `fs` or `path`. Keep middleware lean: auth checks, redirects, header modifications only.
+
+Dynamic imports with `next/dynamic` for heavy client components keep initial bundle sizes small. Always provide a loading fallback.
+
+Environment variables prefixed with `NEXT_PUBLIC_` are exposed to the browser. Never put secrets in `NEXT_PUBLIC_` variables.
+
+## Image and Font Optimization
+
+Use `next/image` for all images -- it handles lazy loading, sizing, and format optimization automatically. Use `next/font` for fonts to eliminate layout shift.

package/.aether/skills/domain/nodejs/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: nodejs
+description: Use when the project uses Node.js for server-side JavaScript
+type: domain
+domains: [backend, server, api]
+agent_roles: [builder]
+detect_files: ["*.js", "*.mjs"]
+detect_packages: ["express", "fastify"]
+priority: normal
+version: "1.0"
+---
+
+# Node.js Best Practices
+
+## Error Handling
+
+Never ignore errors. Every callback gets an `err` first argument -- check it. With async/await, wrap operations in try/catch and handle failures explicitly. Unhandled promise rejections crash Node.js in modern versions.
+
+Use custom error classes that extend `Error` for different failure types (ValidationError, NotFoundError, AuthorizationError). This makes error handling in middleware clean and predictable.
+
+## Async Patterns
+
+Use `async/await` over raw callbacks or `.then()` chains. For parallel operations, use `Promise.all()`. For parallel with partial failure tolerance, use `Promise.allSettled()`.
+
+Never use `async` functions as `EventEmitter` listeners without wrapping them -- thrown errors will be silently swallowed. Wrap in a try/catch and emit an error event.
+
+## Project Structure
+
+Organize by feature, not by technical role. Group routes, controllers, services, and models for a feature together rather than having separate `routes/`, `controllers/`, `services/` directories.
+
+Keep `index.js` or `app.js` thin -- it should only wire up middleware and routes, not contain business logic.
+
+## Environment and Configuration
+
+Load configuration from environment variables using a dedicated config module. Never hardcode ports, database URLs, or API keys. Validate required env vars at startup and fail fast if any are missing.
+
+Use `.env` files only for local development. Never commit `.env` files. Add `.env` to `.gitignore` immediately.
+
+## Security
+
+Validate and sanitize all input. Use parameterized queries for database access -- never interpolate user input into SQL strings. Set HTTP security headers with `helmet` middleware.
+
+Rate-limit API endpoints to prevent abuse. Use `express-rate-limit` or equivalent. Enable CORS explicitly for known origins only, never `*` in production.
+
+## Process Management
+
+Handle `SIGTERM` and `SIGINT` for graceful shutdown. Close database connections, finish in-flight requests, then exit. This is critical for container deployments where processes receive termination signals during scaling.
+
+Never use `process.exit()` in library code. Reserve it for the top-level application entry point.
+
+## Logging
+
+Use a structured logger (pino, winston) -- not `console.log`. Log with levels (error, warn, info, debug). Include request IDs for tracing across async operations. Never log sensitive data like passwords, tokens, or full credit card numbers.

package/.aether/skills/domain/postgresql/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: postgresql
+description: Use when the project uses PostgreSQL for relational data storage
+type: domain
+domains: [database, sql, data]
+agent_roles: [builder]
+detect_files: ["*.sql"]
+detect_packages: ["pg", "psycopg2"]
+priority: normal
+version: "1.0"
+---
+
+# PostgreSQL Best Practices
+
+## Schema Design
+
+Design tables in third normal form unless you have a measured performance reason to denormalize. Use meaningful table and column names -- `user_email` over `ue`. Always define primary keys, preferably `BIGSERIAL` or `UUID` depending on scale requirements.
+
+Add `created_at` and `updated_at` timestamps to every table. Use `TIMESTAMPTZ` (timestamp with time zone), never `TIMESTAMP` without timezone -- timezone-naive timestamps cause bugs when servers span time zones.
+
+## Indexing
+
+Create indexes to support your query patterns, not speculatively. Use `EXPLAIN ANALYZE` to verify that queries use indexes. A missing index on a frequently-queried column is a common source of slow pages.
+
+Use partial indexes for queries that filter on a condition: `CREATE INDEX idx_active_users ON users(email) WHERE active = true`. Use composite indexes with columns ordered by selectivity (most selective first).
+
+Do not over-index. Every index slows down writes. Remove unused indexes identified by `pg_stat_user_indexes` where `idx_scan = 0`.
+
+## Queries
+
+Always use parameterized queries -- never concatenate user input into SQL strings. This prevents SQL injection and lets PostgreSQL cache query plans.
+
+Use `LIMIT` and `OFFSET` for simple pagination, but switch to cursor-based pagination (keyset pagination using `WHERE id > last_seen_id ORDER BY id LIMIT N`) for large datasets. `OFFSET` scans and discards rows, getting slower as pages increase.
+
+## Migrations
+
+Write migrations as idempotent scripts when possible. Use `IF NOT EXISTS` for `CREATE TABLE` and `CREATE INDEX`. Always test migrations against a copy of production data before deploying.
+
+For large tables, avoid `ALTER TABLE ... ADD COLUMN ... DEFAULT` on PostgreSQL versions before 11 -- it rewrites the entire table. Add the column as nullable first, backfill data, then add the constraint.
+
+## Transactions
+
+Keep transactions short. Long-running transactions hold locks and block other operations. Never leave a transaction open while waiting for user input or external API calls.
+
+Use `SERIALIZABLE` isolation only when you need it -- `READ COMMITTED` (the default) is sufficient for most workloads and has better concurrency.
+
+## Connection Management
+
+Use a connection pool (PgBouncer, or your driver's built-in pool). PostgreSQL creates a process per connection -- too many connections waste memory and degrade performance. Set pool size based on `max_connections` and your application's concurrency needs.
+
+## Backups
+
+Use `pg_dump` for logical backups and `pg_basebackup` for physical backups. Test restoring from backups regularly. An untested backup is not a backup.