@bonesofspring/ai-rules 0.2.6 → 0.2.7

package/CHANGELOG.md

@@ -2,8 +2,53 @@
 
 ## Unreleased
 
+### Claude Code handbook agent discipline
+
+Borrowed workflow patterns from [claude-code-rules](https://github.com/nikiforovall/claude-code-rules) (methodology marketplace — not coding standards). Additive on top of structure-change / preset-rules-improvements work.
+
+- **`feature-developer` ×6:** Zero improvisation + Will / Will not (scope discipline; clarify before guessing).
+- **`feature-delivery` skill ×6:** short Scope discipline pointer.
+- **`codebase-analyzer` agent ×6:** explain-as-is only; AGENTS/CLAUDE + agents README pointers; roster next/ios **22**, go **21**.
+- **`code-review` skill ×6:** Reuse + Efficiency lenses.
+- **`technical-retro` skill ×6:** wrong-turn taxonomy + conventions.md feedback (Rule of Three); full skill body on next/go/ios (not alias-only); no auto-apply.
+- **`agent-team-intake` / `agent-team-orchestrator`:** pure questions → prefer **`codebase-analyzer`** (aligned with AGENTS/CLAUDE maps).
+- **`docs/PRESET-CONTRIBUTION.md`:** Building blocks matrix (rule / command / skill / agent / conventions / hook).
+
+### Awesome-cursorrules borrow backlog
+
+- **`security-next`** (cursor + claude next): coding-time secrets/auth/XSS/Server Actions rule; wired into `security-reviewer`, catalogs, AGENTS/CLAUDE quick start.
+- **Anti-hallucination banlists:** `next-app-router`, `go-conventions`, `swift-conventions` (❌/✅ tables).
+- **Review output contract** in shared `review/code-review-mr` (+6 adapters) and all 6 `code-review` skills: `path:line`, severity `blocker|important|nit`, verdict line.
+- **Go:** expanded `go-conventions` (errors/interfaces/concurrency); `api-http` resilience (idempotency, bulkheads, thin handlers) — catalog depth stub→full.
+- **iOS:** `swiftui-ui` lifecycle/ownership (`.task`, DI vs `@StateObject`, hit testing).
+- **Shared quality:** Agent discipline (anti-sycophancy) section in `quality/code-quality-and-refactoring` (+6 adapters).
+
+### Preset rules improvements (9 items)
+
+Cross-cutting preset packaging work (all six presets unless noted **next-only**). Hard gates unchanged: twin sync, ≤3 always-on, no cross-stack leakage.
+
+| # | Item | Unreleased note |
+|---|------|-----------------|
+| 1 | Root `AGENTS.md` + **CLI** | `repoRootFiles`: `REPO_AGENTS.md` → `<cwd>/AGENTS.md` on cursor **and** claude `init` (overwrite policy A); removed on `clean` either tool |
+| 2 | Incorrect/Correct samples | **next only** — 9 domain rules with emedcard-grounded pairs |
+| 3 | Impact tags | `impact: CRITICAL\|HIGH\|MEDIUM\|LOW` frontmatter; documented in PRESET-CONTRIBUTION |
+| 4 | Eval harness (opt-in) | `eval/next/manifest.json`, `check-rule-eval.mjs`, `yarn check:rule-eval`, workflow `rule-eval.yml` |
+| 5 | Living conventions | `reference-features` lineage + `team/conventions.md` ×6 |
+| 6 | Hooks cookbook | `hooks/examples/` (secret-guard, format-edited, test-on-save); default `hooks.json` unchanged |
+| 7 | Skill `write-adr` | ×6 presets (on-demand) |
+| 8 | Skill `react-performance` | **next only** (cursor + claude) |
+| 9 | Linter-delegated style | Stack notes in code-quality adapters; `arrow-functions` trimmed → ESLint/Stylelint + `post-change-lint` |
+
 ### Added
 
+- **CLI `repoRootFiles` + root `AGENTS.md` (all stacks):** preset source `REPO_AGENTS.md` → `<cwd>/AGENTS.md` on cursor **and** claude `init` (overwrite); removed on `clean`. Lean cross-tool sections + pointer to `team/conventions.md`.
+- **Impact frontmatter:** `impact: CRITICAL|HIGH|MEDIUM|LOW` documented in `docs/PRESET-CONTRIBUTION.md`; applied on next golden domain rules with Incorrect/Correct samples.
+- **Next Incorrect/Correct samples** on 9 domain rules (architecture-boundaries, public-imports, api-services, store-rtk, react-ui, tests-unit, http-client, layer-barrel-exports, arrow-functions) + Claude twins.
+- **Opt-in eval:** `eval/next/manifest.json`, `scripts/check-rule-eval.mjs`, `yarn check:rule-eval`, workflow `.github/workflows/rule-eval.yml` (not in `check:preset-structure`).
+- **Living conventions:** lineage section in `reference-features.template.md` + 6 adapters; `team/conventions.md` template ×6.
+- **Skills:** `write-adr` ×6; `react-performance` ×2 (next cursor+claude only).
+- **Hooks cookbook:** `hooks/examples/` (secret-guard, format-edited, test-on-save) ×3 stacks ×2 platforms; default `hooks.json` unchanged.
+- **Dogfood:** `sync-dogfood-cursor.sh` copies root `AGENTS.md` from `REPO_AGENTS.md`; seeds `team/conventions.md` if absent.
 - **Always-on Principles** in shared `quality/code-quality-and-refactoring` (+6 adapters): compact § **Принципы** — KISS, DRY + Rule of Three, YAGNI, SOLID, CUPID, composition over inheritance, Law of Demeter hint. No smell/GoF catalogs in always-on.
 - **Requestable `quality/design-guidance`** (+6 adapters, Cursor/Claude × next/ios-swift/go): curated Fowler smells (≤12) + GoF (≤8) + skip/avoid; globs `app/src/**/*.{ts,tsx}` / `**/*.swift` / `**/*.go`. Cross-refs in `feature-delivery-workflow` (ubiquitous language) and `code-review-mr` checklist. One-liner wiring in feature-developer / code-review / debugger (+ recommended roles).
 - **Go hexagonal preset (`go`):** Cursor + Claude twins — 32 rules (always-on: `go-app-core`, `architecture-boundaries`, `code-quality-and-refactoring`), 20 agents (`integration-test-*`, no a11y/Playwright/XCUITest), 7 skills (+ `integration-testing`), hooks/commands/team/MCP. Structure scripts `STACKS` include `go`; leakage `GO_FORBIDDEN_*` + pairwise chain forks. Install: `init cursor|claude --preset go`. Lineage markers on go `feature-delivery-workflow` / `reference-features`; go team fixtures / commands READMEs use Go gates (not xcodebuild/XCUITest copy-paste).
@@ -19,6 +64,8 @@
 
 ### Changed
 
+- **Style delegate:** next `arrow-functions` trimmed → ESLint/Stylelint + `post-change-lint`; ios/go Stack notes point to SwiftLint / golangci; abstract style sentence in shared code-quality core (no tool names in core body).
+- **Leakage scan:** `hooks/**/*.sh` recursive (includes cookbook examples).
 - **Meta twin policy (three stacks):** `preset-twin-sync` / `preset-pr-checklist` / `preset-layering` core + embeds name **next, ios-swift, and go**; twin FAIL applies to all three (`check-preset-twin-map.sh`).
 - **PRESET-CONTRIBUTION:** shared-core sync step says **all six adapters** (3 stacks × 2 platforms), not «four presets».
 - **Claude session-start count (Option A):** when counting rules without `paths:`, **exclude `**/README.md`**; intended trio remains **exactly 3**; body budget sums only those 3 (`preset-token-budget`, PRESET-CONTRIBUTION, build-verifier ×4).

package/README.md

@@ -32,6 +32,7 @@ If `.cursor` does not appear, check the command output for errors and confirm yo
 - optional dirs when present: `agents/`, `hooks/`, `skills/`, `team/`
 - Cursor root files: `hooks.json`, `BUGBOT.md`, `AGENTS.md`, `MCP.md`, `mcp.json`
 - Claude: `CLAUDE.md`, `MCP.md` under `.claude/`; project `.mcp.json` at repo root
+- **Both tools:** repo-root `AGENTS.md` (from preset `REPO_AGENTS.md`)
 
 Any other files you added under `.cursor/` or `.claude/` (notes, local overrides, IDE state) are **left intact**. Older releases that deleted the whole tool directory are no longer the behavior.
 
@@ -43,10 +44,14 @@ Where things go on `init`:
 | commands | `.cursor/commands` | `.claude/commands` |
 | agents | `.cursor/agents` | `.claude/agents` |
 | hooks | `.cursor/hooks`, `.cursor/hooks.json` | `.claude/hooks` |
+| hooks cookbook | `.cursor/hooks/examples/` (not in default `hooks.json`) | `.claude/hooks/examples/` |
 | skills | `.cursor/skills` | `.claude/skills` |
-| team artifacts template | `.cursor/team` | `.claude/team` |
+| team artifacts template | `.cursor/team` (incl. `conventions.md`) | `.claude/team` |
 | MCP | `mcp.json` → `.cursor/mcp.json`, `MCP.md` → `.cursor/` | `mcp.json` → **`.mcp.json`** (project root), `MCP.md` → `.claude/` |
-| other | `BUGBOT.md`, `AGENTS.md` → `.cursor/` | `CLAUDE.md` → `.claude/CLAUDE.md` |
+| tool map | `AGENTS.md` → `.cursor/AGENTS.md`, `BUGBOT.md` | `CLAUDE.md` → `.claude/CLAUDE.md` |
+| **repo-root agents** | `REPO_AGENTS.md` → **`<cwd>/AGENTS.md`** | same |
+
+Skills of note: `write-adr` (all stacks); `react-performance` (**next only**). Living gotchas: `team/conventions.md`. Opt-in rule samples eval: `yarn check:rule-eval` (workflow `rule-eval.yml`; not part of `check:preset-structure`).
 
 The package ships presets including **`next`** (Next.js stack), **`ios-swift`** (iOS apps on Swift / SwiftUI), and **`go`** (Go backends with hexagonal architecture). Other preset names: see `presets/` in the [repo](https://github.com/bonesofspring/ai-rules). Name is a single path segment, no `/` or `..`.
 
@@ -65,8 +70,9 @@ Presets are developed in this monorepo under `presets/`. If you add or change ru
 
 - **Taxonomy & layers:** [`presets/_shared/README.md`](presets/_shared/README.md) — shared core (`_shared/core`), stack adapters, platform packaging
 - **Contribution guide:** [`docs/PRESET-CONTRIBUTION.md`](docs/PRESET-CONTRIBUTION.md) — SoT, twin sync, embed vs lineage, token budget (≤3 always-on), PR checklist, new stack preset, platform-only files (`BUGBOT.md`, `CLAUDE.md`)
-- **Dogfood / drift scripts:** [`scripts/sync-dogfood-cursor.sh`](scripts/sync-dogfood-cursor.sh), [`scripts/check-shared-core-drift.sh`](scripts/check-shared-core-drift.sh)
+- **Dogfood / drift scripts:** [`scripts/sync-dogfood-cursor.sh`](scripts/sync-dogfood-cursor.sh) (also syncs root `AGENTS.md` from `REPO_AGENTS.md`; seeds `team/conventions.md` if absent), [`scripts/check-shared-core-drift.sh`](scripts/check-shared-core-drift.sh)
 - **Preset structure CI gates** (exit non-zero on FAIL): `yarn check:preset-structure` (or `bash scripts/check-preset-structure.sh`) — twin map, session-start budget (Option A), leakage; soft drift included without `AI_RULES_DRIFT_FAIL`
+- **Opt-in rule eval:** `yarn check:rule-eval` + `.github/workflows/rule-eval.yml` (`workflow_dispatch` + paths-scoped PR) — **not** wired into `check:preset-structure`
 - **CLI note:** `_shared` is not an installable `--preset`; `init` copies only `presets/cursor/<name>/` or `presets/claude/<name>/`
 
 MIT.

package/bin/cli.js

@@ -21,6 +21,8 @@ const PRESETS = {
     mcpJsonSrc: 'mcp.json',
     mcpJsonDest: '.cursor/mcp.json',
     toolRootFiles: ['BUGBOT.md', 'AGENTS.md', 'MCP.md'],
+    /** Preset-root basename → path relative to cwd (not under .cursor/). */
+    repoRootFiles: { 'REPO_AGENTS.md': 'AGENTS.md' },
   },
   claude: {
     rulesDir: '.claude/rules',
@@ -32,6 +34,8 @@ const PRESETS = {
     mcpJsonSrc: 'mcp.json',
     mcpJsonDest: '.mcp.json',
     toolRootFiles: ['MCP.md'],
+    /** Same cross-tool root AGENTS.md as cursor (overwrite on init). */
+    repoRootFiles: { 'REPO_AGENTS.md': 'AGENTS.md' },
   },
 };
 
@@ -57,8 +61,10 @@ Options:
 
 Notes:
   init merges into the target directory; same-named files are overwritten.
-  Cursor init copies rules, commands, agents, hooks, skills, team, hooks.json, BUGBOT.md, AGENTS.md, MCP.md, mcp.json → .cursor/mcp.json.
+  Cursor init copies rules, commands, agents, hooks, skills, team, hooks.json, BUGBOT.md, AGENTS.md → .cursor/AGENTS.md, MCP.md, mcp.json → .cursor/mcp.json.
   Claude init copies rules, commands, skills, agents, hooks, team, CLAUDE.md, MCP.md, and mcp.json → .mcp.json (project root).
+  Both tools also copy REPO_AGENTS.md → <cwd>/AGENTS.md (repo-root cross-tool agents file; overwrite).
+  clean removes tool dirs/files and <cwd>/AGENTS.md (shared across tools — re-init the other tool to restore).
   Command forms: "init cursor --preset next", "init cursor next", "--preset next init cursor", "cursor init --preset next".
 
 Examples:
@@ -255,6 +261,11 @@ function presetHasAnySource(base, cfg) {
       return true;
     }
   }
+  for (const srcName of Object.keys(cfg.repoRootFiles || {})) {
+    if (fs.existsSync(path.join(base, srcName))) {
+      return true;
+    }
+  }
   return false;
 }
 
@@ -386,6 +397,17 @@ function cmdInit(tool, preset, cwdOption) {
         copiedSteps++;
       }
     }
+
+    for (const [srcName, destRel] of Object.entries(cfg.repoRootFiles || {})) {
+      const from = path.join(base, srcName);
+      if (fs.existsSync(from)) {
+        const destAbs = path.join(cwd, destRel);
+        fs.mkdirSync(path.dirname(destAbs), { recursive: true });
+        fs.copyFileSync(from, destAbs);
+        console.log(`Copied ${srcName} → ${destRel}`);
+        copiedSteps++;
+      }
+    }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`init failed: ${msg}`);
@@ -444,6 +466,11 @@ function cmdClean(tool, cwdOption) {
     removedParts.push(`${toolRoot}/${name}`);
   }
 
+  for (const destRel of Object.values(cfg.repoRootFiles || {})) {
+    removeFileIfExists(path.join(cwd, destRel));
+    removedParts.push(destRel);
+  }
+
   console.log(`Removed ${removedParts.join(', ')} (if present)`);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonesofspring/ai-rules",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Presets of Cursor and Claude rules/commands for Revy Ross personal use",
   "license": "MIT",
   "author": "Revy Ross",
@@ -29,7 +29,8 @@
     "check:preset-twin-map": "bash scripts/check-preset-twin-map.sh",
     "check:preset-token-budget": "bash scripts/check-preset-token-budget.sh",
     "check:preset-leakage": "bash scripts/check-preset-leakage.sh",
-    "check:shared-core-drift": "bash scripts/check-shared-core-drift.sh"
+    "check:shared-core-drift": "bash scripts/check-shared-core-drift.sh",
+    "check:rule-eval": "node scripts/check-rule-eval.mjs"
   },
   "engines": {
     "node": ">=18"

package/presets/_shared/core/agent-team/agent-team-intake.md

@@ -4,6 +4,6 @@ When the user message looks like a **work request** (implement, add, fix, refact
 
 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`.
+3. Pure questions («как работает X», «объясни») — prefer agent **`codebase-analyzer`** (explain-as-is); trivial one-liners may be answered inline. Do not open `/task`.
 
 Exceptions: user explicitly says «без pipeline», «просто сделай», or continues an active slug.

package/presets/_shared/core/agent-team/agent-team-orchestrator.md

@@ -126,7 +126,7 @@ If `pipeline.json` is missing (old `/feature-start` tasks), fall back to fixed p
 
 Do **not** run `/task` + router for:
 
-- Pure questions («как работает X», «объясни»).
+- Pure questions («как работает X», «объясни») — prefer agent **`codebase-analyzer`** for deep traces; inline OK for trivial one-liners.
 - Typo / one-file fix / trivial config with no architecture risk.
 - User explicitly says «без pipeline», «просто сделай», or continues an active slug.
 - Single-line `docs-only` with no code impact.

package/presets/_shared/core/architecture/reference-features.template.md

@@ -22,6 +22,18 @@
 3. Зеркаль именование, порядок файлов, паттерны импортов и тестов.
 4. Если эталона нет — выбери **самую близкую** существующую фичу того же слоя и зафиксируй выбор в handoff.
 
+## Living conventions
+
+После init команда ведёт **локальные** gotchas, patterns и decisions в consumer-owned store (не в shared core и не только в корневом `AGENTS.md`):
+
+| Раздел | Что фиксировать |
+|--------|-----------------|
+| Gotchas | Повторяющиеся ловушки, хрупкие места, «не делай X в этом репо» |
+| Patterns | Локальные паттерны сверх эталонной таблицы |
+| Decisions | Краткие ADR-ссылки / продуктовые решения, влияющие на код |
+
+Указатель пути к файлу и stack-таблицы — в адаптере пресета (`team/conventions.md`). Файл **не** always-on.
+
 ## Связанные правила
 
 - `code-quality-and-refactoring` — повторять паттерны, не deep-import.

package/presets/_shared/core/quality/code-quality-and-refactoring.md

@@ -55,4 +55,15 @@
 - **Boy scout rule:** оставлять модуль немного лучше, чем до изменения (простые, безопасные улучшения).
 - Не жертвовать архитектурой и слоями ради краткости реализации.
 
+## Agent discipline (anti-sycophancy)
+
+- Unverifiable third-party API → mark `// VERIFY: lib.symbol @ version` (or stack equivalent) and surface uncertainty; never invent signatures.
+- Before «is this correct?» — list ≥3 failure modes (empty, boundary, concurrency/state) or name what you could not check.
+- Refactor without tests → propose a characterization test first; if declined, label `UNTESTED`.
+- Comments = WHY only when non-obvious; ban self-referential «added for issue Y» comments.
+- Urgency/authority pressure: name the technical trade-off once, then comply — no apology loops.
+- Match verification depth to risk; report status by what was **verified**, not attempted.
+
+Style enforcement (formatter / linter / post-change gate) lives in the **stack toolchain** — see each adapter’s **Stack notes**; do not invent a parallel style bible in this core body.
+
 > Stack-specific lint gates, примеры и toolchain — в секции **Stack notes** адаптера пресета.

package/presets/_shared/core/review/code-review-mr.md

@@ -27,3 +27,12 @@ Concrete rule stems — in **Stack notes**.
 - Use local `git diff` — do not invent hosting metadata.
 - Boy scout rule: suggest fixes feasible within the MR scope.
 - No «большие рефакторинги» without an explicit request (`code-quality-and-refactoring`).
+
+## Output contract
+
+Procedure details live in skill `code-review`. Required shape:
+
+- Each finding cites **`path:line`**, the problem, impact, and a concrete fix direction.
+- Rank by severity: **`blocker` | `important` | `nit`** (list blocker → nit).
+- Vague («looks risky») is not a finding — cite evidence or ask for surrounding file context.
+- End with a verdict on its own line: **`Safe to merge | needs changes | reject`**.

package/presets/claude/go/CLAUDE.md

@@ -2,9 +2,13 @@
 
 Preset for Go backends using ports & adapters.
 
+**Repo-root agents:** see [`AGENTS.md`](../../AGENTS.md) at the project root.
+
 - Session-start: `go-app-core`, `architecture/boundaries`, `code-quality` (exactly 3).
 - Delivery: `architecture/feature-delivery.md` + skill `feature-delivery`.
 - After Go edits: `tooling-and-review/post-change-test.md`.
 - Integration tests: agents `integration-test-*` (never Playwright/XCUITest).
+- ADR: skill `write-adr` (on-demand).
+- How does X work: agent `codebase-analyzer` (explain-as-is; no `/task`).
 
-Init: `npx @bonesofspring/ai-rules init claude --preset go`
+Init: `npx @bonesofspring/ai-rules init claude --preset go` (also copies `REPO_AGENTS.md` → root `AGENTS.md`).

package/presets/claude/go/README.md

@@ -12,7 +12,7 @@ npx @bonesofspring/ai-rules init claude --preset go
 |------|------------|
 | `CLAUDE.md` | Thin session entry |
 | `rules/**` | Topic `.md` + `paths:` (session-start = 3) |
-| `agents/**` | **20** ролей |
+| `agents/**` | **21** ролей (+ `codebase-analyzer`) |
 | `skills/**` | **7** skills (в т.ч. `integration-testing`) |
 | `commands/**` | task, task-continue, feature-start/continue, technical-retro |
 | `hooks/**` | guard-shell + chain-team-phases |
@@ -32,3 +32,7 @@ npx @bonesofspring/ai-rules init claude --preset go
 ## Sync with Cursor
 
 SoT = `presets/cursor/go/`. Update this twin **in the same PR** when Cursor changes.
+
+## Cross-tool root AGENTS
+
+`REPO_AGENTS.md` → project-root `AGENTS.md` on init. Living conventions: `team/conventions.md`. Skill `write-adr` on-demand.

package/presets/claude/go/REPO_AGENTS.md

@@ -0,0 +1,48 @@
+# Go — agent instructions
+
+Cross-tool repo-root guide. Tool-specific maps stay under `.cursor/AGENTS.md` and `.claude/CLAUDE.md`.
+
+## Cross-tool setup
+
+- Treat this file as the **shared** entry for any agent (Cursor, Claude Code, or other).
+- Tool maps live in `.cursor/AGENTS.md` / `.claude/CLAUDE.md` when that tool is installed.
+- Install:
+
+```bash
+npx @bonesofspring/ai-rules init cursor --preset go
+npx @bonesofspring/ai-rules init claude --preset go
+```
+
+`init` overwrites this file from the preset (`REPO_AGENTS.md` → `AGENTS.md`). Living gotchas belong in `team/conventions.md`, not here.
+
+## Commands (test / lint / build)
+
+Prefer hexagonal / ports-and-adapters layout from stack rules (`go-app-core`, `architecture-boundaries`).
+
+| Gate | Typical command |
+|------|-----------------|
+| Test | `go test ./...` (or package-scoped) |
+| Vet | `go vet ./...` |
+| Lint | **golangci-lint** when configured |
+| Format | `gofmt` / `goimports` |
+
+After code edits: invoke **`post-change-test`** (requestable). Full gate: agent `build-verifier`.
+
+## Security basics
+
+- Do not commit secrets (tokens, `.env`, private keys).
+- Review destructive git before running; respect shell hooks.
+- Do not weaken CI or skip hooks unless the user explicitly asks.
+
+## Tool entry points
+
+| Tool | Map |
+|------|-----|
+| Cursor | `.cursor/AGENTS.md` (optional if Cursor not installed) |
+| Claude Code | `.claude/CLAUDE.md` (optional if Claude not installed) |
+
+Rules: `.cursor/rules/` or `.claude/rules/`. Skills: `.cursor/skills/` or `.claude/skills/`.
+
+## Living conventions
+
+Gotchas, local patterns, and team decisions: **`.cursor/team/conventions.md`** and/or **`.claude/team/conventions.md`** (fill after init).

package/presets/claude/go/agents/README.md

@@ -1,8 +1,19 @@
 # `.claude/agents` (preset go)
 
+Ролевые subagents для командного пайплайна Claude Code (Go hexagonal).
+
+## Analysis (on-demand)
+
+| Agent | Файл | Production-код |
+|-------|------|----------------|
+| Codebase analyzer | `codebase-analyzer.md` | no (explain-as-is only) |
+
+## Roster (21)
+
 | Agent | Production writes |
 |-------|-------------------|
 | task-router, task-analyst, solution-architect | team only |
+| codebase-analyzer | no (explain-as-is only) |
 | feature-developer | yes (Go sources) |
 | build-verifier | no (report only) |
 | debugger, ci-investigator | minimal |
@@ -10,6 +21,12 @@
 | migration-specialist, api-contract-reviewer, tech-writer | team / docs |
 | qa-tester, unit-test-*, integration-test-* | tests |
 
-**Roster:** 20 agents. **No** `accessibility-reviewer`, Playwright, or XCUITest stems.
+**No** `accessibility-reviewer`, Playwright, or XCUITest stems. Replace those intents with **`integration-test-*`**.
+
+## Model matrix
 
-Replace Playwright/XCUITest intents with **`integration-test-*`**.
+| Tier | Agents |
+|------|--------|
+| **cheap** | router, analyst, build-verifier, code-reviewer, tech-writer, codebase-analyzer |
+| **standard** | developer, debugger, ci-investigator, api-contract, qa, unit-*, integration-* |
+| **strong** | solution-architect, migration-specialist, security-reviewer, performance-auditor |

package/presets/claude/go/agents/build-verifier.md

@@ -28,3 +28,8 @@ yarn check:preset-structure
 Hard gates: twin-map (stacks include **go**), token-budget (alwaysApply/session-start = 3), leakage (`GO_FORBIDDEN_*`, chain forks go≠next≠ios-swift).
 
 Document PASS/FAIL in `validation-report.md`.
+
+9. **Root AGENTS template:** each installable preset (`cursor|claude` × `next|ios-swift|go`) must ship `REPO_AGENTS.md` when validating preset packaging → **FAIL** if missing.
+10. **Hooks cookbook:** default `hooks.json` must **not** reference `hooks/examples/` → **FAIL** if it does.
+11. **No react-performance on ios/go:** skill directory / required handoff must be absent under ios-swift and go → **FAIL** (leakage). Prefer `check:preset-leakage`.
+12. **Rule eval (WARN):** `scripts/check-rule-eval.mjs` / `yarn check:rule-eval` should exist for maintainers; smoke optional. Hard fail only when the opt-in eval job runs — not part of default `check:preset-structure`.

package/presets/claude/go/agents/codebase-analyzer.md

@@ -0,0 +1,28 @@
+---
+name: codebase-analyzer
+description: Explains HOW existing Go code works as-is. Use when the user asks how something works, to trace ports/adapters, or document architecture — without suggesting changes. Prefer over /task for pure questions.
+readonly: false
+model: fast
+---
+
+You are a specialist at understanding HOW this Go hexagonal service works. Document implementation details with precise `path:line` references.
+
+## CRITICAL — explain as-is only
+
+- DO NOT suggest improvements, refactors, or "better approaches" unless the user explicitly asks.
+- DO NOT perform root-cause analysis or bug hunts unless asked.
+- DO NOT critique quality, performance, or security unless asked.
+- ONLY describe what exists, how it works, and how components interact.
+
+## Workflow
+
+1. Start from entry points the user named (`cmd/`, handlers, use cases, ports).
+2. Trace domain → application/ports → adapters → composition root as applicable.
+3. Summarize: purpose, flow, port contracts, adapter placement, conventions observed.
+4. End with open questions only if facts are missing — not with a wishlist of changes.
+
+## Will / Will not
+
+**Will:** map packages, call chains, ports/adapters as they exist today.
+
+**Will not:** edit production code; open `/task` pipelines; propose PRs or refactors unprompted; require Next/iOS gates.

package/presets/claude/go/agents/feature-developer.md

@@ -19,6 +19,19 @@ Implement Go features following hexagonal boundaries.
 - **Don't** import frameworks into domain; don't use SQL in use cases.
 - **Don't** require Playwright, XCUITest, or yarn lint gates.
 
+## Zero improvisation
+
+- Implement **only** what the brief / AC / current decomposition task require.
+- If requirements are ambiguous, conflicting, or multi-way — **ask** before coding; do not guess extras as "best practices".
+- Forbidden without explicit AC/task: unrelated security hardening, extra validation, observability, drive-by refactors, new config/env.
+- Boy scout / `design-guidance` improvements stay **within** touched files and must not expand task scope.
+
+## Will / Will not
+
+**Will:** follow hexagonal order; add required tests; run `post-change-test` (+ `go-tooling`); update task artifacts.
+
+**Will not:** formal code review; invent AC; pull Next/iOS gates; auto-continue the next WP when the pipeline expects a human gate or handoff.
+
 ## Preset packaging
 
 When editing ai-rules `presets/**/go/**`, keep Cursor/Claude twins in sync and preserve chain fork ≠ next/ios-swift.

package/presets/claude/go/hooks/README.md

@@ -8,3 +8,9 @@
 Claude Code may not use Cursor `hooks.json`. Wire scripts per project docs when enabling agent-team auto-chain.
 
 **No `hooks.json` in Claude preset** (platform limit — same as next Claude).
+
+## Optional cookbook
+
+Example scripts live in `hooks/examples/` (secret-guard, format-edited, test-on-save). They are **not** auto-enabled.
+
+To wire in Claude Code: copy an `.example.sh` into `hooks/`, make executable, and register per [Claude Code hooks](https://code.claude.com/docs/en/hooks) for your project. Keep stack-safe recipes (this preset: **go**). Cursor twin examples under `presets/cursor/go/hooks/examples/` are the same allowlist forks.

package/presets/claude/go/hooks/examples/README.md

@@ -0,0 +1,18 @@
+# Hooks cookbook (examples)
+
+Optional scripts under `hooks/examples/`. **Not** referenced from default `hooks.json` (only `guard-shell-command.sh` + `chain-team-phases.sh`).
+
+| Script | Purpose |
+|--------|---------|
+| `secret-guard.example.sh` | Fail if staged diff looks like secrets |
+| `format-edited.example.sh` | Stack formatter / linter on edited files |
+| `test-on-save.example.sh` | Scoped tests for the stack |
+
+## Wiring (Cursor)
+
+1. Copy an example into `hooks/` (drop `.example` suffix), e.g. `cp hooks/examples/secret-guard.example.sh hooks/secret-guard.sh`.
+2. `chmod +x hooks/secret-guard.sh`.
+3. Add a hook entry in `.cursor/hooks.json` (e.g. `beforeShellExecution` or `afterFileEdit` — see Cursor hooks docs).
+4. Keep cookbook scripts **out** of the default preset `hooks.json` when contributing back upstream.
+
+Stack: **go** — recipes must stay stack-safe (no cross-stack lint/test commands).

package/presets/claude/go/hooks/examples/format-edited.example.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Optional: gofmt / golangci-lint on edited packages.
+# NOT in default hooks.json.
+set -euo pipefail
+gofmt -w $(git diff --name-only --diff-filter=ACMR HEAD 2>/dev/null | grep '\.go$' || true) 2>/dev/null || true
+if command -v golangci-lint >/dev/null 2>&1; then
+  golangci-lint run ./... 2>/dev/null || true
+fi
+exit 0

package/presets/claude/go/hooks/examples/secret-guard.example.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Optional cookbook: block committing likely secrets in staged diffs.
+# NOT wired in default hooks.json — copy to hooks/ and register manually.
+set -euo pipefail
+PATTERN='(AKIA[0-9A-Z]{16}|-----BEGIN (RSA |OPENSSH )?PRIVATE KEY-----|api[_-]?key\s*[:=]\s*['\''\"][^'\''\"]{12,})'
+if git diff --cached -U0 2>/dev/null | grep -Eiq "$PATTERN"; then
+  echo "secret-guard: possible secret in staged diff — review before commit" >&2
+  exit 1
+fi
+exit 0

package/presets/claude/go/hooks/examples/test-on-save.example.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# Optional: package-scoped go test for changed packages.
+# NOT in default hooks.json.
+set -euo pipefail
+pkgs=$(git diff --name-only --diff-filter=ACMR HEAD 2>/dev/null | grep '\.go$' | xargs -n1 dirname 2>/dev/null | sort -u | sed 's|^|./|' || true)
+if [[ -n "${pkgs:-}" ]]; then
+  go test $pkgs 2>/dev/null || true
+else
+  go test ./... 2>/dev/null || true
+fi
+exit 0

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

@@ -6,15 +6,21 @@ paths:
   - **/*router*.go
 ---
 
-
 # HTTP API adapters
 
-- Handlers call inbound ports / use cases; return mapped status + body.
-- Use consistent error envelope; map domain errors centrally.
+- Handlers are **thin**: parse input, call one inbound port / use case, map status + body.
+- Use consistent error envelope; map **domain exceptions** centrally — do not leak transport types into use cases.
 - Version routes if the repo already versions (`/v1/...`).
 - Prefer `net/http` interfaces so tests can use `httptest` without a full framework.
 - Timeouts: set server read/write timeouts; propagate request context.
 
+## Resilience
+
+- Side-effect endpoints (charge, create, enqueue): accept/propagate an **idempotency key** when the domain already uses one; document if intentionally omitted.
+- Outbound HTTP to third parties: prefer **per-provider clients** (separate timeouts/pools) — bulkhead isolation, not one shared client for everything.
+- Provider/ACL adapters return typed results or errors — never raw `map[string]any` / untyped JSON blobs into the domain.
+- Soft file-size hint: plan a split when a handler/router file grows past ~400 LOC; prefer package + re-export over god-files.
+
 ## Testing
 
 - Prefer `httptest` against handler/router with mocked use cases (unit of adapter).
@@ -24,3 +30,4 @@ paths:
 
 - Business rules or SQL in handlers.
 - Ignoring `ctx` cancelation from `r.Context()`.
+- Raising transport-only errors from use cases (keep HTTP mapping at the adapter edge).

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

@@ -21,6 +21,10 @@ Fill TBD paths after adopting this preset in a real service repo.
 | Unit tests | `*_test.go` beside packages | `**/*_test.go` |
 | Integration | `**/integration/` | `**/*_integration_test.go` |
 
+## Living conventions
+
+Post-init gotchas / patterns / decisions: **`.claude/team/conventions.md`** (and the twin tool path if both Cursor and Claude are installed). Consumer-owned; not always-on. See root `AGENTS.md` § Living conventions.
+
 ## Dogfood scenarios
 
 1. `/task` new use case — domain → ports → adapters → wire → `post-change-test`.

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

@@ -4,21 +4,48 @@ 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.
 
+## Errors
+
+- Always handle errors — never `_ = err`.
+- Wrap with `fmt.Errorf("…: %w", err)`; check with `errors.Is` / `errors.As`.
+- Prefer domain/custom error types for structured cases; avoid panics in library/service code.
+
+## Interfaces
+
+- Accept interfaces, return concrete types.
+- Define interfaces at the **call site** (ports / consumers), not on every implementation.
+- Prefer small, single-method interfaces when they match the use.
+
 ## Packages
 
 - Avoid `util`/`common` dumping grounds — name by domain capability.
 - Keep `main` packages thin (see composition-root).
+- No `init()` for business logic; no package-level mutable state for request data.
 
 ## Concurrency
 
-- Document cancelation; do not start unbounded goroutines from handlers without supervision.
+- Document cancelation; `defer cancel()` after creating a derived context.
+- Do not start unbounded goroutines from handlers without a termination condition / supervision (`WaitGroup`, errgroup, or context cancel).
+- Channels for communication, mutexes for shared state — match existing package patterns.
+
+## Anti-hallucination
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| `_ = err` / ignored errors | Handle or wrap with `%w` |
+| Interfaces on every struct «just in case» | Ports at consumer / call site |
+| Invented modules not in `go.mod` | Add dependency explicitly or copy existing import |
+| `interface{}` where generics or a concrete type fit | Generics / concrete types used by the repo |
+| Business logic in `init()` | Wire in composition root / `main` |
+
+## Agent requirement
+
+New Go code must stay idiomatic and verifiable against `go.mod` and neighboring packages. Less guessed code is better than more.

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

@@ -16,7 +16,7 @@ When the user message looks like a **work request** (implement, add, fix, refact
 
 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`.
+3. Pure questions («как работает X», «объясни») — prefer agent **`codebase-analyzer`** (explain-as-is); trivial one-liners may be answered inline. Do not open `/task`.
 
 Exceptions: user explicitly says «без pipeline», «просто сделай», or continues an active slug.
 

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

@@ -138,7 +138,7 @@ If `pipeline.json` is missing (old `/feature-start` tasks), fall back to fixed p
 
 Do **not** run `/task` + router for:
 
-- Pure questions («как работает X», «объясни»).
+- Pure questions («как работает X», «объясни») — prefer agent **`codebase-analyzer`** for deep traces; inline OK for trivial one-liners.
 - Typo / one-file fix / trivial config with no architecture risk.
 - User explicitly says «без pipeline», «просто сделай», or continues an active slug.
 - Single-line `docs-only` with no code impact.