/andurel

name: andurel
description: Use this skill for Andurel framework projects when deciding where code belongs, adding or changing domains, services, handlers, routes, app middleware, background jobs, migrations, config, clients, or framework-adjacent internals. Focuses on project structure, layer placement, the read-only pattern library, and agent-safe CLI usage.

Andurel

Use this skill when working in an Andurel project or adding Andurel code. It helps place code in the right layer and use the `andurel` CLI safely.

Andurel is Go-native: `net/http` through `pkg/anduin`, explicit constructor injection (no DI container), and Inertia for the UI. There is no Echo, no Fx, and no templ page layer.

Agent Invariants

• Prefer `andurel --agent --help`, `andurel commands --json`, and `andurel commands --check` for discovery.
• Read [references/cli-catalog.md](references/cli-catalog.md) for group layout and workflows.
• Read [references/http-and-routing.md](references/http-and-routing.md) for the `pkg/anduin` HTTP model.
• `andurel skill show <reference>` prints `cli-catalog`, `http-and-routing`, or `layer-placement` without installing the skill; the same files ship in `<harness skills dir>/andurel/references/` after `andurel skill install`.
• Run `andurel inspect project --json` before changing code.
• Use `--json` or `--jq` when extracting data.
• `andurel generate` does not write application code. Read a pattern with `andurel patterns show <kind>` and write the files yourself. Only `andurel generate migration` creates a file.
• Run `andurel verify` after a change: it checks formatting, `go fix`, `go vet`, the typed layer rules, the `package.json` typecheck script, and generated-code drift. The rules are listed under [Verify](#verify). Pass Go package patterns to scope the Go checks, and add `--with-tests` to also run the test suite.
• Prefer the local project pattern over a generic Rails, Echo, Bun, Templ, or frontend convention.
• Keep handlers as thin HTTP adapters: parse input, call a domain or service, map errors, render a response.
• Create a service only when there is real cross-domain orchestration, not just because code exists.

Read When Placing Code

Read [references/layer-placement.md](references/layer-placement.md) before adding or moving behavior across domains, services, handlers, routes, middleware, queue jobs, config, clients, or internal packages. It is the one place the placement table, the hard rules per layer, and the decision checklist are written down.

First Pass

1. Inspect the existing resource closest to the requested change. 2. Identify the delivery surface: Inertia page, API endpoint, background job, email, or CLI/command. 3. Identify the domain object or workflow being changed. 4. Keep changes in the smallest layer that can own the behavior honestly. 5. Use `andurel patterns show <kind>` and `andurel inspect … --json` before writing.

Verify

`andurel verify` runs `gofmt`, `go fix`, `go vet`, the typed layer rules, the package manager's `typecheck` script when `package.json` defines one, and generated-code drift. It reports each violation as `{rule, file, line, message, fix}`. Apply the `fix` and re-run. `andurel verify [packages...]` scopes the Go checks to package patterns (for example `./internal/docs/...`); generated drift and the frontend typecheck stay whole-project. `--no-frontend` skips the typecheck. With `--with-tests`, packages that ran no tests are listed under `skipped_packages` and `t.Skip` calls under `skipped_tests` with their reason. Unresolved `inertia.FromStruct` payload roots are listed in the generated step's `warnings` and do not fail the run. Each violation's `rule` is one of these (`andurel verify --help` also prints each rule's fix):

<!-- andurel:verify-rules:begin: generated from the verify rule catalog by 'just docs-sync'; do not edit --> | Rule | Checks | | --- | --- | | `gofmt` | every Go file is gofmt-clean | | `go fix` | go fix reports no automatic rewrites | | `queries-import` | only domains/** imports domains/internal/queries | | `db-handle` | outside domains no SQL methods or SQL drivers; Connection/Transaction are persistence wiring | | `tx-unwrap` | storage.Unwrap is referenced only under domains/** | | `tx-escape` | a storage.AtomicOps callback uses only dependencies bound inside the transaction | | `tx-public-call` | a storage.AtomicOps callback does not call an exported method on its own receiver | | `tx-layer` | storage.AtomicOps and storage.Transactor are used only in services, domains, and internal/runtime | | `domain-transport` | domains/** imports no HTTP, Inertia, routing, handler, middleware, or route package | | `entity-columns` | every automatic generated query column maps to an exported andurel tag on its domain entity | | `setup` | project setup is complete: managed tool binaries and frontend dependencies are installed | | `frontend` | the package.json typecheck script passes when the scaffold defines one | | `frontend-route-usage` | frontend modules do not call full-URL route helpers at module initialization; use .path() or call while rendering | | `content-config` | andurel.content.toml parses, declares a supported schemaVersion, and its include/exclude globs are valid | | `content-catalog` | every declared content catalog entry resolves to an included Markdown file | | `content-slug` | content catalog slugs are non-empty, match the declared pattern, and are unique | | `content-required` | every path listed in andurel.content.toml required exists | | `content-link` | local Markdown links and images resolve inside the project; configured anchors exist | | `content-checker` | each declared content checker exits 0 within its timeout from its declared working directory | | `generated` | generated templ, email, queries, routes, and payload output is up to date | | `missing-tool` | a required generation binary is installed; run 'andurel tool sync' | <!-- andurel:verify-rules:end -->

Output Modes