@bonesofspring/ai-rules 0.2.5 → 0.2.6

package/presets/claude/go/rules/api-and-data/messaging-adapters.md

@@ -0,0 +1,21 @@
+---
+description: Messaging driven/driving adapters for Go hexagonal services
+paths:
+  - **/adapters/messaging/**/*
+---
+
+
+# Messaging adapters
+
+- **Publisher** (driven): implements outbound port; serializes domain events / integration events.
+- **Consumer** (driving): deserializes → calls use case / inbound port; ack/nack policy here.
+- Idempotency keys and retry/DLQ are adapter concerns; document at-least-once assumptions.
+- Do not put broker client types in domain or application signatures.
+
+## Event shapes
+
+- Prefer explicit event structs in application or a small `events` package used by ports — map to wire format in the adapter.
+
+## Tests
+
+- Unit-test mapping with fakes; integration against embedded/broker test duals when the repo has them.

package/presets/claude/go/rules/api-and-data/persistence-adapters.md

@@ -0,0 +1,28 @@
+---
+description: Persistence driven adapters (SQL/repos) for Go hexagonal services
+paths:
+  - **/adapters/persistence/**/*
+  - **/*repository*.go
+---
+
+
+# Persistence adapters
+
+- Implement outbound repository ports from application.
+- Use parameterized queries; map rows → domain entities inside the adapter.
+- Transactions: expose via port (`Transactional`, `UnitOfWork`) implemented here — use cases call the port, not `*sql.Tx` directly.
+- Migrations live with infra (separate package/dir) — not in domain.
+
+## Mapping
+
+- Persistence models (db tags) stay private to the adapter package when possible.
+- Nullability and DB defaults converted to domain values explicitly.
+
+## Forbidden
+
+- Importing persistence from domain or leaking `*sql.DB` through port APIs.
+- Building SQL strings in use cases.
+
+## Tests
+
+- Integration tests with testcontainers / test DB preferred for repos; unit-test mappers with fixtures.

package/presets/claude/go/rules/architecture/README.md

@@ -0,0 +1,16 @@
+# Architecture
+
+Hexagonal boundaries and delivery. Index only.
+
+| File | Cursor SoT |
+|------|------------|
+| [`boundaries.md`](./boundaries.md) | `architecture-boundaries.mdc` |
+| [`feature-delivery.md`](./feature-delivery.md) | `feature-delivery-workflow.mdc` |
+| [`reference-features.md`](./reference-features.md) | `reference-features.mdc` |
+| [`domain-layer.md`](./domain-layer.md) | `domain-layer.mdc` |
+| [`application-usecases.md`](./application-usecases.md) | `application-usecases.mdc` |
+| [`ports-interfaces.md`](./ports-interfaces.md) | `ports-interfaces.mdc` |
+| [`composition-root.md`](./composition-root.md) | `composition-root.mdc` |
+| [`module-public-api.md`](./module-public-api.md) | `module-public-api.mdc` |
+
+Full map: [`../README.md`](../README.md).

package/presets/claude/go/rules/architecture/application-usecases.md

@@ -0,0 +1,29 @@
+---
+description: Application use cases and orchestration in Go hexagonal services
+paths:
+  - internal/application/**/*
+  - **/application/**/*
+---
+
+
+# Application / use cases
+
+- One use case ≈ one application service method (command/query).
+- Depend on **outbound ports** (interfaces), not concrete repos/clients.
+- Orchestrate domain; transaction boundaries via ports (`UnitOfWork`) when needed — still no SQL here.
+- Accept `context.Context` on public methods; propagate to ports.
+
+## Forbidden
+
+- Importing `adapters/*`, SQL drivers, HTTP frameworks.
+- Embedding `*sql.DB`, Redis clients, or handler types in use-case structs.
+- Business rules that belong in domain entities (keep use cases thin).
+
+## Structure
+
+- Prefer `application/<usecase>.go` + `ports.go` (or `ports/`) colocated.
+- Inbound port = interface the driving adapter calls (optional if use-case struct is the API).
+
+## Tests
+
+- Mock outbound ports; assert domain outcomes and port interactions — no real DB.

package/presets/claude/go/rules/architecture/boundaries.md

@@ -0,0 +1,29 @@
+---
+description: Hexagonal layer boundaries for Go backends (domain, application, ports, adapters)
+---
+
+
+# Границы слоёв (hexagonal)
+
+- **Domain** (`internal/domain`, `**/domain`):
+  - Может: entities, value objects, domain services, domain errors; stdlib / same BC domain.
+  - Не должен: HTTP/gRPC/CLI frameworks, SQL/ORM/drivers, Redis/Kafka clients, transport DTO/`encoding/json` API shapes.
+- **Application** (`internal/application`, `**/application`):
+  - Может: use cases; **define ports** (inbound/outbound interfaces) with domain types in signatures.
+  - Не должен: concrete adapters, SQL strings, framework handler types (`gin.Context`, `http.Request` as domain input).
+- **Ports**: interfaces only — no adapter implementations in port packages.
+- **Driving adapters** (`adapters/http|grpc`, CLI): map DTO ↔ application/domain at the edge; no business rules/SQL in handlers.
+- **Driven adapters** (`persistence|cache|messaging|external`): implement outbound ports; map rows/messages → domain; do not leak persistence models upward.
+- **Composition root** (`cmd/`, `internal/app`): wires the graph; no business logic.
+
+# Зависимости
+
+- Направление: **adapters → application → domain**.
+- Driven adapters implement outbound ports defined by application.
+- Domain never imports adapters or frameworks.
+- Cross-feature access — only via public ports / `pkg` API, not deep imports of another feature's internals.
+
+# Требование к агенту
+
+- Класть файлы в правильный слой; не «коротить» слои ради скорости.
+- DI только в composition root.

package/presets/claude/go/rules/architecture/composition-root.md

@@ -0,0 +1,28 @@
+---
+description: Composition root and DI wiring for Go hexagonal services
+paths:
+  - cmd/**/*
+  - internal/app/**/*
+---
+
+
+# Composition root
+
+- Construct adapters, use cases, and servers in `cmd/<service>` and/or `internal/app`.
+- Wire interfaces to implementations explicitly (manual DI preferred unless repo already uses a container).
+- Load config once; fail fast on missing required settings.
+- Lifecycle: graceful shutdown via `context` cancel + server `Shutdown`.
+
+## Allowed here
+
+- Import all layers for wiring only.
+- Process-wide loggers/metrics providers.
+
+## Forbidden
+
+- Business rules, SQL queries, HTTP routing tables with domain logic.
+- Global mutable singletons for repos without clear init (prefer explicit deps).
+
+## Tests
+
+- Optional smoke that wiring builds (compile-time / construction test); heavy logic stays in unit/integration tests.

package/presets/claude/go/rules/architecture/domain-layer.md

@@ -0,0 +1,32 @@
+---
+description: Domain layer invariants for Go hexagonal services
+paths:
+  - internal/domain/**/*
+  - **/domain/**/*
+---
+
+
+# Domain layer
+
+- Pure business types and rules; no I/O.
+- Prefer small value objects with validation constructors (`NewX` / `ParseX` that return typed errors).
+- Domain errors are typed (sentinel or structured); map to HTTP/gRPC statuses only in adapters.
+- Domain services orchestrate entities without calling outbound ports (ports live in application).
+- Keep invariants close to the type that owns them; avoid anemic bags of fields with all logic in use cases.
+
+## Forbidden imports
+
+- `net/http`, `database/sql`, ORM packages, Redis/Kafka clients, router frameworks (`gin`, `chi` as handler deps).
+- Transport DTOs and `json` tags that mirror API contracts (keep API shapes in adapters).
+- Framework `context` cancellation plumbing as a substitute for domain deadlines (prefer explicit types).
+
+## Allowed
+
+- `context` only if domain API genuinely needs deadlines (prefer application to pass primitives).
+- Stdlib: `time`, `errors`, `fmt`, `slices`, `maps`, etc.
+- Cross-aggregate references by ID, not by loading other aggregates via ports.
+
+## Tests
+
+- Table-driven unit tests; no DB, no `httptest`, no framework contexts.
+- Cover invalid constructor inputs and invariant violations explicitly.

package/presets/claude/go/rules/architecture/feature-delivery.md

@@ -0,0 +1,51 @@
+---
+description: End-to-end delivery checklist for Go hexagonal features
+paths:
+  - .cursor/team/**/*
+  - .claude/team/**/*
+  - **/*.go
+  - internal/**/*
+  - cmd/**/*
+---
+
+<!-- shared-core: architecture/feature-delivery-workflow.md -->
+
+# Feature delivery (Go hexagonal)
+
+Order of work:
+
+1. **Domain** — entities/VOs/errors (`domain-layer`).
+2. **Application + ports** — use case + outbound interfaces (`application-usecases`, `ports-interfaces`).
+3. **Driven adapters** — persistence/cache/messaging implementing ports.
+4. **Driving adapters** — HTTP/gRPC/CLI mapping DTOs.
+5. **Composition root** — wire in `cmd/` / `internal/app`.
+6. **Tests** — unit (domain/app) → integration (adapters) → optional e2e smoke.
+7. **Gate** — `post-change-test` (+ `go-tooling`).
+
+```mermaid
+flowchart LR
+  D[Domain] --> A[Application+Ports]
+  A --> Drv[Driven adapters]
+  Drv --> A
+  HTTP[Driving HTTP] --> A
+  CR[Composition root] --> HTTP
+  CR --> A
+  CR --> Drv
+```
+
+## Matrix
+
+| Path | Rules |
+|------|-------|
+| `**/domain/**` | `domain-layer`, `architecture-boundaries` |
+| `**/application/**` | `application-usecases`, `ports-interfaces` |
+| `**/adapters/http/**` | `adapters-driving`, `api-http` |
+| `**/adapters/persistence/**` | `adapters-driven`, `persistence-adapters` |
+| `cmd/**`, `internal/app/**` | `composition-root` |
+| After `*.go` edits | `post-change-test` |
+
+## Anti-patterns
+
+- Framework types in domain; SQL in use cases; DI inside handlers; skipping port interfaces “for speed”.
+- **Ubiquitous language:** Domain names/boundaries reflect the feature domain — do not mix transport/framework terms into domain without need.
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/claude/go/rules/architecture/module-public-api.md

@@ -0,0 +1,23 @@
+---
+description: Public module API (pkg/) and internal boundaries for Go services
+paths:
+  - pkg/**/*
+  - go.mod
+---
+
+
+# Module public API
+
+- Anything under `pkg/` is a compatibility surface — change carefully; prefer additive APIs.
+- Service-private code stays in `internal/`.
+- Do not import another module's `internal/` (compiler enforces for separate modules).
+- Document breaking Go API changes in CHANGELOG when the repo publishes libraries.
+
+## go.mod
+
+- Module path and Go version are SoT for toolchain.
+- Prefer minimal direct deps; pin via `go.mod` / `go.sum`.
+
+## Cross-feature
+
+- Inside one module, features communicate via application ports or small `pkg` facades — not by importing sibling feature adapter packages.

package/presets/claude/go/rules/architecture/ports-interfaces.md

@@ -0,0 +1,34 @@
+---
+description: Inbound and outbound port interfaces for Go hexagonal services
+paths:
+  - **/ports/**/*
+  - internal/application/**/*port*
+  - **/application/**/*port*
+---
+
+
+# Ports (interfaces)
+
+## Outbound (driven)
+
+- Repository, cache, publisher, clock, ID generator, external client — defined by **application**.
+- Signatures use **domain** types (or small application DTOs), never ORM models.
+- Keep interfaces small (ISP); prefer role interfaces over god-repos.
+- Accept `context.Context` as the first parameter when the call may block or cancel.
+
+## Inbound (driving)
+
+- Optional interface wrapping use cases for multiple drivers (HTTP + gRPC + CLI).
+- Drivers depend on inbound ports / use-case APIs — not on each other.
+- Prefer a concrete use-case struct when only one driver exists; extract an interface when a second driver appears.
+
+## Naming
+
+- `SaveOrder`, `FindOrderByID`, `PublishOrderPlaced` — verb-oriented.
+- Implementation types live in adapters (`PostgresOrderRepository`), not beside the interface in domain.
+
+## Anti-patterns
+
+- Ports returning `map[string]any` or `json.RawMessage` without need.
+- Putting port interfaces inside adapter packages (wrong owner).
+- Leakage of SQL/`driver.Valuer` types through port method signatures.

package/presets/claude/go/rules/architecture/reference-features.md

@@ -0,0 +1,30 @@
+---
+description: Reference paths for Go hexagonal layout (fill after init)
+paths:
+  - internal/**/*
+  - cmd/**/*
+---
+
+<!-- shared-core: architecture/reference-features.template.md -->
+
+# Reference features (Go)
+
+Fill TBD paths after adopting this preset in a real service repo.
+
+| Area | Example path (TBD) | Glob hint |
+|------|--------------------|-----------|
+| Domain | `internal/domain/` | `**/domain/**` |
+| Application / ports | `internal/application/` | `**/application/**` |
+| HTTP adapter | `internal/adapters/http/` | `**/adapters/http/**` |
+| Persistence | `internal/adapters/persistence/` | `**/adapters/persistence/**` |
+| Composition root | `cmd/<service>/`, `internal/app/` | `cmd/**`, `internal/app/**` |
+| Unit tests | `*_test.go` beside packages | `**/*_test.go` |
+| Integration | `**/integration/` | `**/*_integration_test.go` |
+
+## Dogfood scenarios
+
+1. `/task` new use case — domain → ports → adapters → wire → `post-change-test`.
+2. Bug in handler mapping — debugger + httptest unit.
+3. Repository contract — integration-test trio.
+4. OpenAPI/proto drift — api-contract-reviewer.
+5. Secrets in logs — security-reviewer + `security-go`.

package/presets/claude/go/rules/stack/README.md

@@ -0,0 +1,10 @@
+# Stack
+
+Язык, платформа и базовый каркас сервиса. Index only — тела в topic `.md`.
+
+| File | Cursor SoT |
+|------|------------|
+| [`go-app-core.md`](./go-app-core.md) | `go-app-core.mdc` |
+| [`go-conventions.md`](./go-conventions.md) | `go-conventions.mdc` |
+
+Sync: change Cursor → update Claude twin same PR. Full map: [`../README.md`](../README.md).

package/presets/claude/go/rules/stack/go-app-core.md

@@ -0,0 +1,31 @@
+---
+description: Go backend stack, module layout, and agent entry points (hexagonal preset)
+---
+
+
+# Стек и окружение
+
+Версии Go, toolchain и зависимостей — **из `go.mod` / `go.work` целевого репозитория**. Рамка preset:
+
+- **Язык / платформа:** Go (module mode); min version — из `go` directive в `go.mod`.
+- **Архитектура:** hexagonal (ports & adapters); слой domain не знает HTTP/SQL/брокеры.
+- **Точки входа:** `cmd/<service>/main.go` → composition root.
+- **Concurrency:** `context.Context` в API границ; не хранить Context в структурах дольше запроса.
+- **Тесты:** `testing` + table-driven; integration за адаптерами; e2e HTTP smoke — по необходимости.
+- **HTTP:** framework-agnostic (`net/http`, chi/gin/echo — примеры, не мандат).
+- **Наблюдаемость:** только если уже в репо — централизованно (логи/metrics/tracing).
+
+# Структура (default: layer-first)
+
+```text
+cmd/<service>/main.go
+internal/domain/
+internal/application/          # use cases + ports
+internal/adapters/http|grpc|persistence|cache|messaging/
+internal/app/                  # optional DI wiring
+pkg/                           # optional public library API
+```
+
+**Feature-first variant** allowed: `internal/<feature>/{domain,application,adapters}` — same dependency direction.
+
+Границы — **`architecture-boundaries.mdc`**. Tooling — requestable **`go-tooling.mdc`**. После правок Go — **`post-change-test.mdc`**.

package/presets/claude/go/rules/stack/go-conventions.md

@@ -0,0 +1,24 @@
+---
+description: Idiomatic Go conventions for this hexagonal preset
+paths:
+  - **/*.go
+---
+
+
+# Go conventions
+
+- Follow [Effective Go](https://go.dev/doc/effective_go) and repo `golangci-lint` / `staticcheck` when present.
+- Accept `context.Context` as first param on I/O and use-case methods.
+- Wrap errors: `fmt.Errorf("…: %w", err)`; avoid panics in library/service code.
+- Prefer `camelCase` unexported, `PascalCase` exported; package names short and lowercase.
+- Do not expose `internal/` outside the module.
+- Prefer table-driven tests; use `t.Parallel` only when safe.
+
+## Packages
+
+- Avoid `util`/`common` dumping grounds — name by domain capability.
+- Keep `main` packages thin (see composition-root).
+
+## Concurrency
+
+- Document cancelation; do not start unbounded goroutines from handlers without supervision.

package/presets/claude/go/rules/testing/README.md

@@ -0,0 +1,11 @@
+# Testing
+
+Unit, integration, e2e smoke. Index only.
+
+| File | Cursor SoT |
+|------|------------|
+| [`unit.md`](./unit.md) | `tests-unit.mdc` |
+| [`integration.md`](./integration.md) | `tests-integration.mdc` |
+| [`e2e.md`](./e2e.md) | `tests-e2e.mdc` |
+
+Full map: [`../README.md`](../README.md).

package/presets/claude/go/rules/testing/e2e.md

@@ -0,0 +1,18 @@
+---
+description: End-to-end HTTP smoke tests for Go services
+paths:
+  - **/e2e/**/*_test.go
+  - **/*_e2e_test.go
+---
+
+
+# E2E / HTTP smoke
+
+- Black-box against a running server (httptest with full composition root, or localhost in CI).
+- Cover critical paths only; prefer integration + unit for breadth.
+- Stable test data; avoid depending on wall-clock flakiness.
+- Do not use browser/Playwright tooling in this preset.
+
+## Placement
+
+- `e2e/` package or `*_e2e_test.go` with build tags if needed.

package/presets/claude/go/rules/testing/integration.md

@@ -0,0 +1,23 @@
+---
+description: Integration / adapter contract tests for Go hexagonal services
+paths:
+  - **/integration/**/*_test.go
+  - **/*_integration_test.go
+---
+
+
+# Integration tests
+
+- Exercise driven adapters against real infra doubles (testcontainers, docker compose test DB, miniredis, etc.).
+- Or exercise HTTP adapter with `httptest` + wired use case + fake/real ports — still no full prod cluster required.
+- Build tags (`//go:build integration`) if the repo separates CI jobs.
+- Keep fixtures deterministic; clean up data between tests.
+
+## Scope
+
+- Contract of a port implementation (repo save/load roundtrip).
+- Not a substitute for domain unit tests.
+
+## Agents
+
+- Planning/generation: `integration-test-{planner,generator,healer}` + skill `integration-testing`.

package/presets/claude/go/rules/testing/unit.md

@@ -0,0 +1,24 @@
+---
+description: Unit testing conventions for Go hexagonal services
+paths:
+  - **/*_test.go
+---
+
+
+# Unit tests
+
+- Table-driven tests; clear arrange/act/assert.
+- Domain and application: mock/fake **ports** only — no real DB/network.
+- Prefer fakes over heavy mocking frameworks when simple.
+- Skip integration/e2e files matching `*_integration_test.go`, `*_e2e_test.go`, or dirs `integration/`, `e2e/` — those use other rules.
+
+## Forbidden smells
+
+- `gin.Context` / `http.Request` in domain tests.
+- SQL or live HTTP in use-case unit tests.
+- Brittle tests on unexported adapter internals without need.
+- Structural smells vocabulary (Feature Envy, Message Chains, …): see requestable `design-guidance` — do not duplicate the catalog here.
+
+## Naming
+
+- `TestUseCase_DoX` / `TestEntity_Invariant`.

package/presets/claude/go/rules/tooling-and-review/README.md

@@ -0,0 +1,21 @@
+# Tooling and review
+
+Качество, review, test gate, security, agent-team, retro, preset meta. Index only.
+
+| File | Cursor SoT |
+|------|------------|
+| [`code-quality.md`](./code-quality.md) | `code-quality-and-refactoring.mdc` |
+| [`code-review.md`](./code-review.md) | `code-review-mr.mdc` |
+| [`post-change-test.md`](./post-change-test.md) | `post-change-test.mdc` |
+| [`go-tooling.md`](./go-tooling.md) | `go-tooling.mdc` |
+| [`security-go.md`](./security-go.md) | `security-go.mdc` |
+| [`agent-team-intake.md`](./agent-team-intake.md) | `agent-team-intake.mdc` |
+| [`agent-team-orchestrator.md`](./agent-team-orchestrator.md) | `agent-team-orchestrator.mdc` |
+| [`technical-retro.md`](./technical-retro.md) | `technical-retro.mdc` |
+| [`preset-layering.md`](./preset-layering.md) | `preset-layering.mdc` |
+| [`preset-twin-sync.md`](./preset-twin-sync.md) | `preset-twin-sync.mdc` |
+| [`preset-token-budget.md`](./preset-token-budget.md) | `preset-token-budget.mdc` |
+| [`preset-pr-checklist.md`](./preset-pr-checklist.md) | `preset-pr-checklist.mdc` |
+| [`preset-no-cross-stack-leakage.md`](./preset-no-cross-stack-leakage.md) | `preset-no-cross-stack-leakage.mdc` |
+
+Sync: change Cursor → update Claude twin same PR. Full map: [`../README.md`](../README.md).

package/presets/claude/go/rules/tooling-and-review/agent-team-intake.md

@@ -0,0 +1,25 @@
+---
+description: Suggest /task for Go backend work requests
+paths:
+  - .cursor/team/**/*
+  - .claude/team/**/*
+  - **/*.go
+  - internal/**/*
+  - cmd/**/*
+---
+
+<!-- shared-core: agent-team/agent-team-intake.md -->
+
+# Agent team intake
+
+When the user message looks like a **work request** (implement, add, fix, refactor, review MR, write tests, spike) — not a question about how code works:
+
+1. Prefer **`/task <their request>`** or invoke **task-router** first.
+2. Do not jump straight to coding without router + pipeline when scope is non-trivial.
+3. Pure questions («как работает X», «объясни») — answer normally, no `/task`.
+
+Exceptions: user explicitly says «без pipeline», «просто сделай», or continues an active slug.
+
+## Stack notes
+
+- Scope: Go services (`cmd/`, `internal/**`) — hexagonal ports/adapters — not Playwright/XCUITest UI flows.