@event4u/agent-config 5.10.0 → 6.0.0

package/dist/agent-src/skills/accessibility-auditor/data/aria-patterns.csv

@@ -0,0 +1,13 @@
+Component,Keywords,Pattern,Implementation,WCAG Refs,Anti-Patterns,Docs URL
+Modal dialog,modal dialog overlay popup confirm,dialog role + aria-modal,"role=dialog aria-modal=true aria-labelledby; focus moves in on open, trapped while open, returns to trigger on close; Esc closes","WCAG 2.4.3, 2.1.2; APG dialog pattern",Focus left behind the overlay; close only via pointer,https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
+Combobox / autocomplete,combobox autocomplete select search suggest dropdown,combobox + listbox popup,"role=combobox aria-expanded aria-controls aria-activedescendant; Down opens list, Enter selects, Esc closes; results announced via live region count","WCAG 4.1.2, 1.3.1",Re-implementing as div+onclick without keyboard model,https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+Tabs,tabs tabpanel tablist switch view,tablist/tab/tabpanel triad,"role=tablist/tab/tabpanel, aria-selected, tab order: one tabstop into list then Arrow keys; panel labelled by its tab","WCAG 2.1.1, 4.1.2",Each tab a separate Tab stop; panels not labelled,https://www.w3.org/WAI/ARIA/apg/patterns/tabs/
+Accordion / disclosure,accordion disclosure expand collapse faq section,button + aria-expanded,Header is a real button with aria-expanded + aria-controls; content region labelled; Enter/Space toggle,"WCAG 4.1.2, 1.3.1",Heading-with-onclick; hiding content with display:none while aria-expanded=true,https://www.w3.org/WAI/ARIA/apg/patterns/accordion/
+Menu / dropdown actions,menu dropdown actions kebab context,menu button + menu/menuitem,"menubutton with aria-haspopup=menu aria-expanded; Arrow navigation, Esc closes and returns focus; menuitem (not links styled as menu)",WCAG 2.1.1,Using role=menu for site navigation (use nav+links),https://www.w3.org/WAI/ARIA/apg/patterns/menubutton/
+Toast / status message,toast notification snackbar status alert,status / alert live regions,"role=status (polite) for confirmations, role=alert (assertive) sparingly for errors; never move focus to a toast; pause on hover/focus; allow dismissal","WCAG 4.1.3, 2.2.1",Focus-stealing toasts; auto-dismiss with no persistence option for critical info,https://www.w3.org/WAI/ARIA/apg/patterns/alert/
+Data table,table grid sortable data rows columns,table semantics + aria-sort,Native table elements with th scope; sortable headers are buttons inside th with aria-sort on the th; caption or aria-label names the table,WCAG 1.3.1,Div-grid for tabular data; sort state only as an icon,https://www.w3.org/WAI/ARIA/apg/patterns/table/
+Form validation feedback,form error validation invalid message field,described-by + alert summary,aria-invalid + aria-describedby on the field; on submit failure move focus to first invalid field or an error-summary with anchor links; errors persist until fixed,"WCAG 3.3.1, 3.3.3, 2.4.3",Placeholder-only labels; toast-only errors,https://www.w3.org/WAI/tutorials/forms/notifications/
+Skip link & landmarks,skip link landmark main nav banner region,landmarks + skip to main,"First focusable element is a skip-to-main link (visible on focus); one main, labelled nav/aside regions",WCAG 2.4.1,Multiple unlabelled navs; skip link that never becomes visible,https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/
+Drag and drop / reorder,drag drop reorder sortable kanban move,keyboard-equivalent commands,Every drag operation has a keyboard path (move-up/move-down buttons or grab mode with arrows + announcements); aria-live announces position changes,"WCAG 2.1.1, 2.5.7",Pointer-only reordering,https://www.w3.org/WAI/ARIA/apg/patterns/listbox/
+Loading / busy state,loading spinner skeleton busy progress,aria-busy + progressbar/status,Region marked aria-busy during load OR role=progressbar with valuenow; announce completion via status region; skeletons are aria-hidden,WCAG 4.1.3,Spinner gif with no text alternative; focus lost on content swap,https://www.w3.org/WAI/ARIA/apg/patterns/meter/
+Icon-only button,icon button close edit delete aria-label svg,accessible name on control,aria-label (or visually-hidden text) on the button; svg aria-hidden=true focusable=false; hit area ≥44px,"WCAG 4.1.2, 2.5.8",title attribute as the only name; emoji as icon,https://www.w3.org/WAI/ARIA/apg/patterns/button/

package/dist/agent-src/skills/accessibility-auditor/data/manifest.json

@@ -0,0 +1,34 @@
+{
+  "manifest_version": 1,
+  "domain": "a11y-patterns",
+  "tier": "lookup-only",
+  "retriever": "bm25",
+  "default_domain": "patterns",
+  "domains": {
+    "patterns": {
+      "file": "aria-patterns.csv",
+      "search_cols": [
+        "Component",
+        "Keywords",
+        "Pattern",
+        "Implementation"
+      ],
+      "output_cols": [
+        "Component",
+        "Pattern",
+        "Implementation",
+        "WCAG Refs",
+        "Anti-Patterns",
+        "Docs URL"
+      ],
+      "max_results": 3
+    }
+  },
+  "owner": "package-maintainer",
+  "refresh_cadence": "quarterly",
+  "upstream": {
+    "repo": "derived: W3C ARIA Authoring Practices Guide + WCAG 2.2",
+    "sha": "APG 2026 / WCAG 2.2",
+    "last_checked": "2026-06-07"
+  }
+}

package/dist/agent-src/skills/agents-md-thin-root/SKILL.md

@@ -0,0 +1,143 @@
+---
+model_tier: inherit
+name: agents-md-thin-root
+description: "Use when editing AGENTS.md (package root) or templates/AGENTS.md (consumer) — enforces Thin-Root contract: hard char ceilings, ≥40% pointer ratio, mandatory emergency-triage block."
+domain: process
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+<!-- cloud_safe: noop -->
+
+# agents-md-thin-root
+
+## When to use
+
+Use when:
+- Editing `AGENTS.md` at the package root.
+- Editing `packages/core/.agent-src.uncondensed/templates/AGENTS.md` (consumer-shipped template).
+- Reviewing a PR that changes either file.
+- Running `/optimize/agents`.
+- A budget meter (`scripts/measure_augment_budget.py`) flags the package-root AGENTS.md as the dominant cost.
+
+## Do NOT
+
+- Edit `.github/copilot-instructions.md` with this skill (use `copilot-agents-optimization` instead).
+- Edit other `.md` files under `.augment/`, `packages/*/.agent-src.uncondensed/`, or `agents/` with this skill.
+- Add a section to AGENTS.md without first checking whether an outboard target already exists in `agents/settings/contexts/` or `docs/contracts/`.
+- Replace prose with a bare link `[label](path)` — every pointer needs a *why*-clause ≥ 60 chars or it does not count toward the 40 % ratio.
+- Reuse the package-root anatomy in the consumer template — caps and target paths differ.
+
+## Why Thin-Root
+
+Augment Code injects `AGENTS.md` verbatim into every workspace prompt. Each kilobyte spent here permanently consumes the 49,512-char workspace-guidelines budget shared with always-rules and auto-rule registry stubs. The Thin-Root pattern keeps the entry point a navigation surface (pointers + intent) and pushes deep detail into files Augment loads on demand via `load_context` or that other tools fetch only when their search retrieves them. Strategic council R2 (2026-05-08, Sonnet 4.5 / Opus 4.1 / gpt-4o / o1) converged on the contract codified below as the minimum guard against AGENTS.md re-bloat.
+
+## Iron Law — Capabilities over Structure
+
+Every entry describes **what** the project does or **where** to learn more — never **where** individual files live. Path lists rot every refactor and poison context; capability pointers survive structural churn. Full anatomy with rewrite recipes, monorepo guidance, and multi-tool symlink strategy: [`agents-md-anatomy`](../../contexts/contracts/agents-md-anatomy.md).
+
+## The contract — hard caps
+
+| File | FAIL above | WARN above | Target |
+|---|---|---|---|
+| `AGENTS.md` (package root) | 3,000 chars | 2,800 chars | ≤ 2,800 |
+| `packages/core/.agent-src.uncondensed/templates/AGENTS.md` (consumer) | 2,500 chars | 2,300 chars | ≤ 2,300 |
+
+Char-count is raw file size (`wc -c`), frontmatter included. Enforcement: `scripts/lint_agents_md.py` (Phase 7), wired into the package's CI pipeline via the `lint-agents-md` task. WARN is a soft signal in CI; FAIL blocks merge.
+
+The R2 council originally proposed 2,500 / 2,000 caps. Phase 6.4 empirical refactor demonstrated that the mandatory emergency-triage block (≈ 700 chars) plus operational must-haves (source-of-truth disclaimer, `task` quickstart, six substantive pointers) raise the achievable floor by ≈ 500 chars. The caps above are the post-refactor baseline; the previous numbers stayed unattainable without dropping mandatory content.
+
+## The contract — pointer ratio
+
+≥ 40 % of non-blank lines must be **substantive pointers**. A substantive pointer is a Markdown link `[label](path[#anchor])` whose surrounding sentence carries a *why* clause ≥ 60 chars explaining what the reader will learn there. Decorative links (table-of-contents, badges, repeated cross-refs) do not count. Lint formula:
+
+```
+pointer_ratio = (substantive_pointer_lines / non_blank_lines) >= 0.40
+```
+
+## The contract — pointer anatomy
+
+Every substantive pointer specifies, on the same line or the immediately following line:
+
+1. **Target file path** — repo-relative, no leading `./`.
+2. **Optional anchor** — `#section-slug` when the linked file's content is large enough that landing in the middle saves the reader. Skip only when the linked file is itself short.
+3. ***Why* clause** — ≥ 60 chars, present-tense, names the concrete decision the pointer unblocks. Not "see also", not "more info", not the file's title repeated.
+
+### Wrong vs. right
+
+❌ **Wrong** — bare link, no *why*, no anchor:
+> See [`commit-policy`](dist/agent-src/rules/commit-policy.md).
+
+❌ **Wrong** — *why* present but < 60 chars:
+> Commit rules: [`commit-policy`](dist/agent-src/rules/commit-policy.md).
+
+✅ **Right** — full anatomy, anchor, *why* ≥ 60 chars:
+> Commit policy — never auto-commit, four named exceptions, Hard Floor list of bulk-deletion / infra triggers: [`commit-policy § Iron Law`](dist/agent-src/rules/commit-policy.md#the-iron-law).
+
+✅ **Right** — anchor optional when target is short:
+> Mirror the user's language every reply, single Iron Law that overrides any momentum: [`language-and-tone`](dist/agent-src/rules/language-and-tone.md).
+
+## The contract — emergency-triage block
+
+Every Thin-Root AGENTS.md MUST contain an **Emergency Triage** section verbatim from `packages/core/.agent-src.uncondensed/contexts/contracts/emergency-triage-block.md` (Phase 6.4 will create that file as the canonical source). The block lists the five questions a host agent answers from the root file alone when network / tool access is degraded:
+
+1. What is this repository?
+2. What language(s) does this repository accept?
+3. Where do I edit (source-of-truth path)?
+4. What is the lint / test / sync entry point?
+5. Where do the always-active behavior rules live?
+
+Each answer must fit on one line. The block exists so the root never silently degrades to "useful only when every linked file is reachable".
+
+## Procedure — apply Thin-Root to AGENTS.md
+
+1. **Measure baseline.** `wc -c AGENTS.md` and `python3 scripts/measure_augment_budget.py`. Record current char-count and the gap to 2,200 / 2,500.
+2. **Inventory sections.** List every `## ` heading and its char-count. Mark each as `keep-inline` (Iron-Law-adjacent, ≤ 200 chars, no good outboard target) or `outboard-candidate` (longer-form prose, table-only sections, narrative).
+3. **Identify outboard targets.** For each `outboard-candidate`, name the destination — `packages/core/.agent-src.uncondensed/contexts/`, `docs/contracts/`, an existing rule body, an existing skill body. Never invent a new top-level directory.
+4. **Move content; insert pointer.** Cut the section into the target file. Replace it in AGENTS.md with a single substantive pointer per anatomy above. Verify the *why*-clause length.
+5. **Re-measure.** `wc -c AGENTS.md` again. If above 2,200, repeat steps 2–4 on the next-largest section. Above 2,500 = must outboard further before commit.
+6. **Validate pointer ratio.** Count non-blank lines and substantive-pointer lines. Ratio < 0.40 = collapse decorative or boilerplate lines into a single pointer or remove.
+7. **Verify emergency-triage block.** Diff the in-file block against `packages/core/.agent-src.uncondensed/contexts/contracts/emergency-triage-block.md`. Drift = revert to canonical.
+8. **Run lints.** `task lint-agents-md && task check-refs && task lint-skills`. All green before commit.
+
+## Procedure — apply Thin-Root to consumer template
+
+Same procedure, applied to `packages/core/.agent-src.uncondensed/templates/AGENTS.md`. Hard cap shifts to 2,000 / 1,700. The consumer template intentionally lacks the package-self-references — its pointers target files that exist in the **consumer's** repo (`.augment/skills/`, `agents/settings/contexts/`, ...), not this package's authoring tree.
+
+## Gotchas
+
+- **Outboarding to a new top-level dir.** Inventing `agents/explainers/` or `docs/notes/` for the moved content silently widens the contract surface. Outboard only into `packages/core/.agent-src.uncondensed/contexts/`, `docs/contracts/`, an existing rule body, or an existing skill body.
+- **Pointer-ratio inflation by decoration.** Adding boilerplate "Browse all skills" / "See also" links to lift the ratio above 40 % defeats the purpose. The lint counts only substantive pointers (with a *why*-clause ≥ 60 chars); decorative links get filtered out and the ratio drops back below threshold.
+- **Emergency-triage drift.** Editing the in-file emergency-triage block instead of the canonical `packages/core/.agent-src.uncondensed/contexts/contracts/emergency-triage-block.md` causes the package-root and consumer-template versions to diverge silently. Always edit the canonical file and let the lint diff pull both back in sync.
+- **Cap inversion under WARN.** A 2,250-char AGENTS.md (above 2,200 WARN, below 2,500 FAIL) is a yellow signal not a green one — every additional sentence raises the probability of the next FAIL. Treat WARN as the spend boundary, not a buffer.
+- **Char-count includes frontmatter.** `wc -c` counts every byte including the YAML preamble, blank lines, and the trailing newline. Stripping a section to "look smaller" without re-running `wc -c` understates the true budget impact.
+- **Path enumeration.** A run of three or more bare `` `path/to/dir/` `` bullets without *why*-clauses is the classic re-bloat pattern. The lint emits a WARN at ≥ 3 such lines. Collapse them into one capability-style pointer — see the recipe in [`agents-md-anatomy § Iron Law`](../../contexts/contracts/agents-md-anatomy.md#iron-law--capabilities-over-structure).
+- **Tool-specific duplicates.** Copy-pasting AGENTS.md into `CLAUDE.md` / `GEMINI.md` / `.cursorrules` doubles the budget cost across tools. Use the symlink-or-stub pattern in [`agents-md-anatomy § Multi-tool symlink strategy`](../../contexts/contracts/agents-md-anatomy.md#multi-tool-symlink-strategy) instead.
+
+## Output format
+
+When invoked as a planning step, produce:
+
+1. Current size + gap to target (one line per file).
+2. Inventory table (section, chars, keep-inline / outboard-candidate, target).
+3. Pointer ratio before / after (predicted).
+4. Specific outboarding edits as a numbered diff plan.
+5. The four lint commands the agent must run before claiming completion.
+
+## Cloud Behavior
+
+Inert on cloud surfaces. The skill governs the package-root `AGENTS.md` and the consumer-shipped template — both authoring artifacts inside this repository. Cloud agents working on consumer projects never edit those files directly; their copy is delivered by the package install pipeline and refreshed by the package sync pipeline. The Thin-Root contract therefore has no cloud-side procedure to execute, which is why this skill is marked `cloud_safe: noop`.
+
+## See also
+
+- [`agents-md-anatomy`](../../contexts/contracts/agents-md-anatomy.md) — Capabilities-over-Structure Iron Law, multi-tool symlink strategy, monorepo per-package layout, refactor recipe, full gotcha catalog.
+- [`copilot-agents-optimization`](../copilot-agents-optimization/SKILL.md) — sibling skill for `.github/copilot-instructions.md`; runs alongside Thin-Root in `/agents optimize`.
+- [`agent-docs-writing`](../agent-docs-writing/SKILL.md) — broader documentation-structure context for navigating outboard targets.
+- [`size-enforcement`](../../rules/size-enforcement.md) — covers per-skill / per-rule / per-command size budgets; AGENTS.md caps live in this skill instead.
+- [`ADR-004-rule-governance-pruning`](../../../docs/decisions/ADR-004-rule-governance-pruning.md) — captures the rule-governance pruning that freed the workspace-guidelines budget; the Thin-Root caps build on that headroom.

package/dist/agent-src/skills/api-design/SKILL.md

@@ -0,0 +1,120 @@
+---
+model_tier: medium
+name: api-design
+description: "Use when designing APIs, planning endpoints, REST conventions, versioning, or deprecation — even when the user just says 'expose this as an endpoint' without naming API design."
+personas:
+  - backend-architect
+domain: engineering
+recommended_for_user_types: [developer, founder]
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# api-design
+
+
+> **Grounded corpus (Tier-1 consultation):** pagination, versioning,
+> error shape (RFC 9457), idempotency, async ops, rate limiting, bulk,
+> naming, expansion, webhooks — `ground.py search --manifest
+> <skills-root>/api-design/data/manifest.json "<concern>"` proposes the
+> grounded pattern (+ hardening + anti-patterns + RFC link) before
+> designing from memory. Corpus: [`data/api-patterns.csv`](data/api-patterns.csv).
+
+## When to use
+
+Use this skill when designing new API endpoints, restructuring existing APIs, or deciding about versioning and deprecation.
+
+Do NOT use when:
+- Implementing an already-designed endpoint (use `api-endpoint` skill)
+- Writing tests for APIs (use `api-testing` skill)
+
+## Procedure: Design an API
+
+1. **Gather context** — read `agents/settings/contexts/api-versioning.md`, `agents/reference/docs/api-resources.md`, `agents/reference/docs/query-filter.md`, `agents/reference/docs/controller.md`, and guideline `php/api-design.md`.
+2. **Identify the resource** — determine the domain entity, its attributes, and relationships. Check existing models and resources for field naming patterns.
+3. **Define endpoints** — list each endpoint with HTTP method, URL path, request body, query parameters, and response structure. Follow existing route file patterns.
+4. **Decide versioning** — determine whether this extends the current version or requires a new version (see decision table below).
+5. **Design error responses** — define 4xx/5xx responses matching the project's existing error format.
+6. **Validate against existing patterns** — compare your design with 2-3 similar existing endpoints. Flag any inconsistencies.
+7. **Run adversarial review** — use `adversarial-review` skill to check for breaking changes, consistency issues, and missing error cases.
+
+## Versioning decisions
+
+### URL-based versioning
+
+Routes versioned via URL prefix: `/api/v1/...`, `/api/v2/...`
+
+```
+routes/api/v1/projects.php  → /api/v1/projects
+routes/api/v2/projects.php  → /api/v2/projects
+```
+
+### Automatic fallback
+
+If a route doesn't exist in the requested version, the system falls back to the next older version. Configured in `config/app.php`:
+
+```php
+'api_versioning' => [
+    'versions' => 'v2,v1',  // newest first
+],
+```
+
+### When to create a new version
+
+| Change type | Action |
+|---|---|
+| Add optional field | Extend current version |
+| Add new endpoint | Add to current version |
+| Remove/rename field | New version |
+| Change field type | New version |
+| Change validation rules | New version |
+
+> If an existing client would break without code changes → **new version required**.
+
+### Deprecation workflow
+
+1. **Mark as deprecated** — add headers: `Deprecation: true`, `Sunset: YYYY-MM-DD`, `Link: <successor>`
+2. **Document** — add to API changelog with sunset date
+3. **Monitor usage** — track clients still using deprecated endpoints
+4. **Remove** — after sunset date, remove route + controller + docs
+
+Minimum 3 months between deprecation and removal.
+
+## Design review
+
+Before presenting an API design, run the **`adversarial-review`** skill.
+Focus on: Breaking changes? Consistency? Error responses?
+
+## Output format
+
+1. Endpoint specification — method, path, request/response structure
+2. Versioning decision with rationale
+3. Error response format following existing project patterns
+
+## Gotcha
+
+- Consistency beats "better" design — check existing patterns first.
+- Always include pagination on list endpoints.
+- Max nesting depth: 2 levels (`/users/{id}/orders/{id}`).
+- Don't version internal APIs only your own frontend consumes.
+- Deprecation without migration path is useless — always provide the replacement.
+- Don't duplicate controllers for new versions — use fallback logic.
+
+## Do NOT
+
+- Do NOT introduce a new response format in an established API — match existing patterns.
+- Do NOT create v2 endpoints without a deprecation plan for v1.
+- Do NOT skip pagination on list endpoints.
+
+## Auto-trigger keywords
+
+- API design
+- REST API
+- endpoint design
+- resource structure
+- response format
+- API versioning
+- deprecation
+- breaking changes

package/dist/agent-src/skills/api-design/data/api-patterns.csv

@@ -0,0 +1,13 @@
+Concern,Keywords,Applies To,Recommended Pattern,Hardening,Anti-Patterns,Docs URL
+Pagination,collection list large dataset paging,REST any scale,"Cursor-based pagination for unbounded/ordered feeds; offset only for small, stable admin tables",Cursor token opaque + signed; include next/prev links (RFC 8288); cap page size server-side,Offset pagination on hot tables (deep-offset scans); exposing raw DB ids as cursors,https://www.rfc-editor.org/rfc/rfc8288
+Versioning,breaking change version v1 v2 deprecate,public REST API,URI major version (/v1/) for public APIs; additive changes within a version; sunset with Deprecation + Sunset headers,Announce ≥6 months; dual-run window; changelog per version,Header-only versioning for public consumers (invisible in logs/docs); breaking within a version,https://www.rfc-editor.org/rfc/rfc8594
+Error shape,error response problem detail validation message,any HTTP API,"RFC 9457 application/problem+json: type, title, status, detail, instance + per-field errors array",Stable machine-readable type URIs; correlation id; never leak stack traces,Bare string bodies; 200-with-error-flag envelopes; localized-only messages,https://www.rfc-editor.org/rfc/rfc9457
+Idempotency,retry duplicate POST payment create network timeout,mutating endpoints,Idempotency-Key header on POST money/resource creation; store key→result with TTL; replay returns first result,Scope keys per principal; 409 on key reuse with different payload,Relying on client dedupe; making POST 'safe' by chance,https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
+Filtering & sorting,filter query search sort fields sparse,collection endpoints,Explicit allowlisted filter/sort params; document operators; reject unknown params with 400 problem+json,Index-backed filters only; combine with cursor pagination,Free-form q= passed to the DB; sort on unindexed columns,https://www.rfc-editor.org/rfc/rfc9110
+Partial update,update patch put field subset,resource endpoints,PATCH with JSON Merge Patch (RFC 7396) for flat resources; full PUT for replace semantics; ETag + If-Match for lost-update protection,412 on stale ETag; document null-vs-absent semantics,PUT that silently merges; PATCH without concurrency control,https://www.rfc-editor.org/rfc/rfc7396
+Async operations,long running job export import 202 status polling,operations >2s,"202 Accepted + operation resource (/operations/{id}) with status, progress, result link; optional webhook on completion",Operation resource is GET-pollable + cacheable; include Retry-After,Holding the connection open; 200 with 'check back later' prose,https://www.rfc-editor.org/rfc/rfc9110#status.202
+Rate limiting,throttle quota 429 rate limit headers,public/partner APIs,429 + RateLimit headers (limit/remaining/reset); per-principal buckets; document burst vs sustained,Distinguish per-IP (anon) vs per-key (auth); Retry-After on 429,Silent throttling; global single bucket; HTML error bodies,https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/
+Bulk operations,bulk batch many items import,write-heavy integrations,Dedicated /batch endpoint with per-item status array (multi-status semantics); cap batch size; idempotency key per batch,"Partial success is explicit per item, never all-or-nothing-by-accident",Looping client calls as the documented path; unbounded batch size,https://www.rfc-editor.org/rfc/rfc9110
+Resource naming,naming url path nouns plural kebab,any REST API,"Plural nouns, kebab-case paths, no verbs in URIs (verbs live in HTTP methods or POST /resource/{id}/actions for true RPC)",Stable ids in paths; relationship via sub-resources one level deep,Deep nesting >2 levels; mixed singular/plural; camelCase paths,https://www.rfc-editor.org/rfc/rfc9110
+Field selection & expansion,sparse fieldsets include expand embed n+1,read-heavy APIs,Explicit ?fields= allowlist and ?include= for relationships with a documented max depth,Defaults stay lean; expansion costs documented; guard with per-include query budget,Auto-embedding everything; client-driven unbounded expansion,https://jsonapi.org/format/#fetching-sparse-fieldsets
+Webhook delivery,webhook callback event delivery retry signature,outbound events,"Signed payloads (HMAC + timestamp), exponential backoff retries with dead-letter, event id for consumer idempotency",Document signature scheme + rotation; include event type registry,Fire-and-forget delivery; unsigned payloads; retrying forever,https://www.rfc-editor.org/rfc/rfc2104

package/dist/agent-src/skills/api-design/data/manifest.json

@@ -0,0 +1,34 @@
+{
+  "manifest_version": 1,
+  "domain": "api-design",
+  "tier": "lookup-only",
+  "retriever": "bm25",
+  "default_domain": "patterns",
+  "domains": {
+    "patterns": {
+      "file": "api-patterns.csv",
+      "search_cols": [
+        "Concern",
+        "Keywords",
+        "Applies To",
+        "Recommended Pattern"
+      ],
+      "output_cols": [
+        "Concern",
+        "Applies To",
+        "Recommended Pattern",
+        "Hardening",
+        "Anti-Patterns",
+        "Docs URL"
+      ],
+      "max_results": 3
+    }
+  },
+  "owner": "package-maintainer",
+  "refresh_cadence": "quarterly",
+  "upstream": {
+    "repo": "derived: RFC 9110/9457/7396/8288 + httpapi WG drafts",
+    "sha": "RFC set as of 2026-06",
+    "last_checked": "2026-06-07"
+  }
+}

package/dist/agent-src/skills/api-endpoint/SKILL.md

@@ -0,0 +1,100 @@
+---
+model_tier: medium
+name: api-endpoint
+description: "Use when creating an API endpoint or HTTP route handler — detects the project stack and routes to the matching carve-out (laravel-api-endpoint, nextjs-patterns, symfony-workflow)."
+domain: engineering
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# api-endpoint
+
+
+> **Grounded corpus:** endpoint-shape decisions (pagination, error shape,
+> idempotency, rate limits) ground via the
+> [`api-design`](../api-design/SKILL.md) corpus — `ground.py search
+> --manifest <skills-root>/api-design/data/manifest.json "<concern>"`.
+
+## When to use
+
+Use this skill when the user asks to create a new API endpoint, REST route, or HTTP handler.
+
+Do NOT use when:
+- Modifying existing endpoints — use the code-refactoring skill.
+- API design decisions (versioning, deprecation, contract shape) — use [`api-design`](../api-design/SKILL.md).
+
+## Stack routing
+
+Detect the stack, then hand off to the matching carve-out skill for the framework-specific procedure (file layout, validation primitive, response-shaping convention).
+
+| Detected stack | Carve-out skill |
+|---|---|
+| Laravel (`artisan` + `composer.json` with `laravel/framework`) | [`laravel-api-endpoint`](../laravel-api-endpoint/SKILL.md) |
+| Symfony (`bin/console` + `composer.json` with `symfony/framework-bundle`) | [`symfony-workflow`](../symfony-workflow/SKILL.md) |
+| Next.js (`next` in `package.json`) | [`nextjs-patterns`](../nextjs-patterns/SKILL.md) |
+| Express / Fastify / NestJS / plain Node | follow project conventions in `agents/` + `package.json scripts` |
+| FastAPI / Django / Flask | follow project conventions in `agents/` + `pyproject.toml` |
+| Go (`net/http`, `gin`, `echo`, `fiber`) | follow project conventions in `agents/` + `go.mod` |
+| Rust (`axum`, `actix-web`, `rocket`) | follow project conventions in `agents/` + `Cargo.toml` |
+
+If the project doc folder (`agents/`) has an endpoint-creation guide, that is the source of truth — read it before generating code.
+
+## Procedure: Create an API endpoint (stack-neutral)
+
+1. **Read project docs** — Check `./agents/` and `AGENTS.md` for endpoint conventions, routing layout, response shape.
+2. **Detect stack** and route to the carve-out per the table above.
+3. **Plan the endpoint** — method, path, request shape, response shape, auth requirement, idempotency.
+4. **Create the route registration** in the project's routing surface (route file, decorator-annotated handler, file-based router).
+5. **Create the request handler / controller** — thin; delegate business logic to a service / use-case.
+6. **Validate input at the boundary** via the framework's validation primitive (FormRequest, Zod, class-validator, Pydantic, struct-tag validators, etc.) — never inline ad-hoc `if` checks.
+7. **Authorize the action** via the framework's authz primitive (Policy, voter, guard, middleware, route dependency).
+8. **Shape the response** through a transformer / serializer / DTO — never return raw ORM entities.
+9. **Document** the endpoint (OpenAPI annotations / generated spec / project doc).
+10. **Verify** — run the project type-checker + targeted tests + smoke probe (`curl` / Bruno / Postman / integration test).
+
+## Conventions (apply on every stack)
+
+- **One handler, one responsibility** — prefer single-purpose handlers over multi-action controllers when the framework supports it.
+- **No business logic in the handler** — delegate to a service / use-case layer.
+- **Validate at the boundary** — never trust raw request data inside the handler.
+- **Authorize every state-changing action** — no unprotected mutating endpoints.
+- **Shape responses through a transformer** — DTO, serializer, API resource, response model — never expose raw ORM entities.
+- **Version the API surface** explicitly (`/v1/`, header, content-type) — don't rely on implicit versioning.
+
+## Stack-specific procedures
+
+For Laravel projects (the most fully-fleshed-out carve-out in this package), see [`laravel-api-endpoint`](../laravel-api-endpoint/SKILL.md) — covers single-action controllers, `FormRequest`, `Resource`, `Policy`, `CollectionFormRequest`, OpenAPI attributes, and the versioned route layout.
+
+For other stacks, read the matching carve-out from the table above and combine with the project's `agents/` docs.
+
+## Output format
+
+1. Generated files — route registration, handler, request validator, response shaper, authorization rule.
+2. Test file with happy path and validation-error cases (using the project's test framework).
+3. Summary of created files and their locations.
+
+## Gotcha
+
+- Don't forget to register the route — creating the handler without the route is a common miss.
+- Always check if a similar endpoint already exists — duplicates cause confusion.
+- Validation rules must match the documented contract (OpenAPI / schema / typed client) — keep them in sync.
+- Response shapes are part of the public contract — adding a field is additive; renaming or removing is breaking.
+
+## Do NOT
+
+- Do NOT put business logic in the handler — delegate to services / use-cases.
+- Do NOT skip request validation — every handler validates at the boundary via the framework's primitive.
+- Do NOT return raw ORM entities — always go through a transformer / serializer / response model.
+- Do NOT create unprotected state-changing endpoints — authorize every mutation.
+- Do NOT improvise framework idioms — read the carve-out (`laravel-api-endpoint`, `nextjs-patterns`, etc.) for the stack-correct shape.
+
+## Auto-trigger keywords
+
+- create endpoint
+- new API route
+- route handler
+- controller creation
+- REST endpoint
+- add endpoint