{"owner":"goadesign","repo":"goa","hasSkills":true,"totalSkillsCount":7,"totalTokensCount":11501,"categories":["claude-rule","anthropic-skill","cursor-rule","root-instruction"],"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md","skills/goa-service-designer/SKILL.md",".cursorrules","skills/goa-service-designer/references/transport-errors-interceptors.md",".claude/skills/goa-release/SKILL.md",".cursor/skills/goa-release/SKILL.md","AGENTS.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nRead @AGENTS.md","skills/goa-service-designer/SKILL.md":"---\nname: goa-service-designer\ndescription: Design and evolve Goa application services. Use for Goa DSL changes, HTTP/gRPC/JSON-RPC contracts, validation, errors, interceptors, code generation, and service implementation.\n---\n\n# Goa Service Designer\n\nUse this skill for applications and plugins that declare or consume Goa contracts. Repository\ninstructions govern implementation. For changes to Goa's own compiler, runtime, templates, or\ngenerators, use Goa's contributor workflow instead of the application workflow below; still use the\nreference and capability checks below when deciding what the DSL or generated transport supports.\n\nLet Goa generate the mechanical code. Use the relevant design and generated service interface as\nthe working context; inspect transport output when the task changes wire behavior. Implement the\napplication's decisions outside `gen/`.\n\n## Consult The Relevant Reference Before Designing\n\nRead the relevant reference before a non-trivial design or implementation decision. Do not wait\nuntil generation fails, and do not treat the links as optional background reading:\n\n- For HTTP, gRPC, or JSON-RPC mappings, streaming, errors, security, or interceptor behavior, read\n  [transport guidance](references/transport-errors-interceptors.md).\n- For named types, aliases, pointers, defaults, unions, views, or validation, read\n  [modeling guidance](references/modeling-and-validation.md).\n- For generated signatures, constructors, codecs, imports, or downstream implementation changes,\n  read [generated-code guidance](references/generated-code-and-implementation.md).\n- When observed output or behavior contradicts the design, also read\n  [troubleshooting](references/troubleshooting.md).\n\nBefore introducing a transport workaround or claiming that Goa cannot express a requirement:\n\n1. Check the existing DSL mechanism in the reference and the selected Goa version's source. For\n   example, `Param(\"attributeName:url_name\")` separates a payload field from its URL parameter name;\n   inspect that mapping before renaming path tokens or adding transport-only replacement fields.\n2. Trace the authored mapping through generated payloads, client encoding, server decoding, and\n   endpoint invocation. Distinguish the payload name, HTTP element name, and generated Go selector.\n3. Verify the disputed capability with a minimal authored design and generated client/server check\n   before editing its replacement. A reference states the intended contract; it does not prove the\n   selected generator implements it correctly. Keep a failing result and trace its owning layer\n   rather than assuming the DSL lacks the feature.\n\nReuse a working native mechanism. If it fails, explain the exact generator gap and why a change\nbelongs in Goa or the consuming plugin before implementing it. Read only the references relevant\nto the decision; routine mechanical edits do not require loading every reference.\n\n## Default Workflow\n\n1. Find the local design, generated service contract, implementation, generation wrapper, validation\n   commands, and affected consumers. Check the Goa version and any replacement in `go.mod`.\n2. Reuse established local patterns for routine edits. Consult goa.design when choosing an\n   unfamiliar feature, resolving uncertain DSL or generated behavior, or troubleshooting.\n   Read only the relevant section, using these topic routes:\n   - New project: [Quickstart](https://goa.design/docs/1-goa/quickstart/) and [Code Generation](https://goa.design/docs/1-goa/code-generation/).\n   - Types, validation, views, or unions: [DSL Reference](https://goa.design/docs/1-goa/dsl-reference/).\n   - HTTP mapping, WebSocket, or SSE: [HTTP Guide](https://goa.design/docs/1-goa/http-guide/).\n   - gRPC, protobuf tags, metadata, or streaming: [gRPC Guide](https://goa.design/docs/1-goa/grpc-guide/).\n   - JSON-RPC: [transport reference](references/transport-errors-interceptors.md#json-rpc-mapping) and the selected Goa version's `dsl.JSONRPC` documentation.\n   - Errors: [Error Handling](https://goa.design/docs/1-goa/error-handling/).\n   - Interceptors or middleware: [Interceptors](https://goa.design/docs/1-goa/interceptors/).\n   - Security or production wiring: [Production](https://goa.design/docs/1-goa/production/).\n   Online docs may describe a different release. For release-specific behavior and upgrades, use the\n   selected Goa checkout's `UPGRADING.md` and generated output. Use a page's Markdown version\n   when available; do not preload every guide or reference.\n3. State the intended contract change in one or two sentences.\n4. Edit the Goa design first.\n5. Regenerate with the project's wrapper. Without one, use\n   `go run goa.design/goa/v3/cmd/goa gen <design-package-import-path>` so the command uses the\n   application's selected module version. Never use `goa gen ./design`.\n6. Implement the generated interface outside `gen/`.\n7. Update only affected consumers: mocks, clients, docs, examples, API snapshots, OpenAPI/protobuf\n   consumers, command wiring, and project-specific SDKs generated from Goa output.\n8. Run the generation, lint, type-check, and test commands allowed by the repository instructions.\n   If a command is prohibited or too broad, state exactly what was not run.\n9. Review generated and hand-written diffs together. Every generated change should follow from\n   the design or an intentional tooling upgrade.\n\nUse `goa example <design-package-import-path>` when starter files are needed. It creates missing\napplication files and does not update existing files. Review new files and update existing wiring\nyourself; do not expect it to migrate an implementation.\n\n## Hard Rules\n\n- Treat the Goa design as the canonical contract. If payload shape, result shape, validation,\n  security, errors, transport mapping, documentation, OpenAPI, protobuf, generated clients, or CLIs\n  need to change, edit the design first and regenerate.\n- Never patch generated files, OpenAPI output, protobuf output, or generated clients to hide a stale\n  design.\n- Keep protobuf field numbers unique within the final message, including inherited fields.\n  Never renumber or reuse released field numbers to make a sequence contiguous.\n- Put boundary validation in Goa. Use `Required`, `Enum`, `Format`, `Pattern`, `Minimum`,\n  `Maximum`, `MinLength`, `MaxLength`, defaults, security fields, and explicit transport mappings in\n  the design.\n- Model error applicability at the narrowest correct Goa scope. API-level errors define reusable\n  potential errors and let transports map them once; they do not mean every endpoint returns every\n  API-level error. Service-level errors apply to all methods in that service. Method-level errors\n  apply only to that method. Do not list an error at service scope just to make a generated\n  constructor convenient if only some methods can return it.\n- In service code, trust payloads already validated by the generated transport and enforce business\n  invariants. Direct service or endpoint calls bypass transport decoding; their callers must supply\n  valid values or validate at their own input boundary. Do not add nil guards,\n  fallback behavior, silent recovery, blanket string trimming, or compatibility shims for values the\n  design guarantees.\n- Do not use nil versus empty slices or maps as domain meaning. `Required` and `MinLength` express\n  different constraints, and JSON and protobuf have different collection presence rules. See\n  [presence and collections](references/modeling-and-validation.md#presence-and-collections).\n- Preserve compatibility for shipped public APIs, persisted data, external SDKs, and documented\n  behavior. For internal-only contracts or unshipped branch work, update callers cleanly instead of\n  adding shims.\n\n## Design Conventions\n\nFollow the application's existing conventions and compatibility requirements. For new designs:\n\n- Prefix explicit generated-package aliases with `gen`, such as `genfront` or `genfrontgrpc`.\n- Prefer lower camel case for public HTTP fields and parameters (`accountId`) and snake case for\n  method names (`get_account`). Map established wire names explicitly, for example\n  `Header(\"tusResumable:Tus-Resumable\")`.\n- Use literal integer `Field` tags so wire identities are easy to review. Start a new standalone\n  definition at `1`. For an `Extend` definition, `100` can start a new range only if inherited fields\n  leave that range free. Inspect the complete inheritance chain and assign unused numbers; nested\n  `Extend` calls must not restart at an occupied `100`. Existing tags always keep their numbers.\n\nThese are authoring conventions, not requirements imposed by Goa.\n\n## What To Read Next\n\nUse the decision triggers above to select references; the details below describe their scope:\n\n- `references/modeling-and-validation.md`: type modeling, primitive aliases, required fields,\n  pointer/default semantics, views, presence, and compatibility.\n- `references/transport-errors-interceptors.md`: HTTP, gRPC, JSON-RPC, streaming, errors, security,\n  interceptors, middleware, and observability labels.\n- `references/generated-code-and-implementation.md`: generated diff triage, dirty worktrees,\n  implementation updates, downstream artifacts, and validation commands.\n- `references/troubleshooting.md`: generation failures, decode bugs, gRPC output surprises,\n  interceptor ordering, and common mini-patterns.\n\n## Final Review\n\nBefore finishing, verify:\n\n- The design remains the source of truth.\n- Generated code was regenerated, not edited.\n- Payloads, results, validation, security, errors, and transport mappings are explicit.\n- Service code trusts established validation boundaries and handles real dependency failures.\n- Compatibility choices are represented in the design and tests, not hidden in service fallbacks.\n- Affected downstream consumers are updated; unaffected artifacts are left alone.\n- New transport workarounds and capability claims have evidence from the native generated path.\n- Test coverage matches the risk of the contract change.\n",".cursorrules":"# Goa repository rules for Cursor\n\n- Never edit generated code. Fix the generator/templates instead.\n- Prefer any over interface{} in new code.\n- Transports: HTTP, gRPC, and JSON-RPC 2.0 (HTTP, SSE, WebSocket). JSON-RPC supports batch and notifications; streaming over WS/SSE.\n- Testing:\n  - Run unit tests with `make test`.\n  - JSON-RPC integration tests live in `jsonrpc/integration_tests`; run with `make integration-test` (skips on Windows).\n  - Golden tests use testify; update with `go test -update` or `-u`.\n- Code style:\n  - Small, focused files; one main construct per file when possible.\n  - Public types first, then private types, public constants, private constants, public vars, private vars, public functions/methods, then private.\n  - Use `maps.Copy`/`slices.Contains`, `http.NoBody`, avoid shadowing builtins.\n- Architecture quick map:\n  - `dsl/` (design DSL), `expr/` (expressions), `codegen/` (generation engine & templates), `cmd/goa/` (CLI), `http/`, `grpc/`, `jsonrpc/` (transports), `pkg/`, `middleware/`, `security/`, `eval/`.\n- For deeper guidance, see `CLAUDE.md`.\n","skills/goa-service-designer/references/transport-errors-interceptors.md":"# Transport, Errors, And Interceptors\n\nUse this reference when changing HTTP, gRPC, or JSON-RPC mappings, streaming, errors, security,\ninterceptors, middleware, or production wiring. The gRPC presence and JSON-RPC behavior below\ndescribes Goa v3.31 and later. Check the application's selected module version and its\n`UPGRADING.md` before changing older code.\n\n## HTTP Mapping\n\n- Use resource nouns, plural names, stable hierarchy, and HTTP methods for actions.\n- Put stable prefixes in API-level or service-level `HTTP(Path(...))`.\n- Use `Parent` and `CanonicalMethod` only when nested resources become clearer.\n- Map path, query, header, and body fields deliberately with `Param`, `Header`, and `Body`.\n- Use explicit wire-name mapping when attribute names differ from HTTP element names.\n- Choose status codes intentionally. Use `StatusCreated` for creates when appropriate.\n- Use default content negotiation unless a real media type requires custom encoders or decoders.\n- Use the CORS plugin for browser-facing cross-origin policy.\n- Use `Files` only for HTTP static content.\n\nHTTP object payload checks:\n\n- Every path token must map to a payload field.\n- Every non-body attribute should land where intended.\n- Use `Body(\"field\")` only when the request body should be that field's raw value.\n- Unmapped object attributes are encoded in the body.\n\n```go\nHTTP(func() {\n    GET(\"/accounts/{account_id}/items\")\n    Param(\"accountId:account_id\")\n    Param(\"limit\")\n    Response(StatusOK)\n    Response(\"not_found\", StatusNotFound)\n})\n```\n\n## Streaming\n\nGoa's streaming DSL is transport-agnostic. The transport mapping determines HTTP behavior:\n\n- Plain HTTP streaming defaults to WebSocket.\n- Add `ServerSentEvents()` only for one-way server-to-client streams.\n- WebSocket endpoints use `GET`.\n- For gRPC streaming, check generated protobuf and server/client stream types.\n- JSON-RPC supports unary calls or a single request followed by an\n  explicit SSE stream. It rejects client or bidirectional streaming, WebSocket streams, and a\n  method combining `Result` with `StreamingResult`. Ordinary HTTP WebSocket support is separate.\n- Streaming implementations must handle flow control, `io.EOF`, send errors, context cancellation,\n  timeouts, and cleanup.\n\n## gRPC Mapping\n\n- Set package and version metadata for public or versioned APIs.\n- Keep domain data in messages.\n- Use metadata, headers, and trailers only for protocol metadata.\n- Use streaming for large or continuous datasets.\n- Never renumber released `Field` values.\n- Check `.proto` output after changing shared types, streaming methods, or custom protobuf metadata.\n- Required singular scalars preserve protobuf presence. An omitted required\n  boolean is invalid; an explicitly supplied `false` can be valid. Generated decoders validate\n  before converting to service values. See the modeling reference for collections and defaults.\n\n## JSON-RPC Mapping\n\n- Use service-level `JSONRPC` to configure the shared HTTP POST endpoint, and method-level\n  `JSONRPC` for method-specific behavior and error mappings.\n- Let generated code own the JSON-RPC envelope, dispatch, request IDs, batches, and protocol errors.\n  The payload describes `params`; do not handwrite transport envelopes in service code.\n- Ordinary generated client calls have an ID even without an `ID` payload field.\n  `Notification()` explicitly declares a one-way call. Having no result does not by itself make\n  a method a notification. Notifications cannot declare a result, ID field, or stream.\n- `ID` belongs directly in the payload, not the result. The transport returns the request ID;\n  the service does not choose a response ID.\n- Map designed errors with JSON-RPC `Response` codes. Verify the generated error `data` shape\n  before changing a custom client's decoding.\n- For SSE, pair `StreamingResult` with method-level `ServerSentEvents()`. Verify event field\n  mappings and cancellation through the generated client and server.\n\n## Errors\n\n- Define reusable potential errors at API scope when you want one canonical error type/name and one\n  transport mapping. API-level `Error(...)` declarations do not make those errors applicable to\n  every endpoint. Select a reusable definition with `Error(\"name\")` at service or method scope.\n- Define an error at service scope only when every method on that service can return it.\n- Define an error at method scope when only that method can return it.\n- Do not promote a method-specific error to service scope just to avoid repeating a declaration or to\n  make generated constructors easier to reach; the design would falsely advertise that all service\n  methods can return it.\n- Use descriptive names and descriptions.\n- Prefer `ErrorResult` for most errors.\n- Add `Temporary()`, `Timeout()`, or `Fault()` when clients should behave differently.\n- Use custom error types only when clients need structured context.\n- If multiple custom errors can return from the same method, include a field marked with\n  `Meta(\"struct:error:name\")`.\n- Map every exposed error for each enabled transport with `HTTP(Response(...))` and\n  `GRPC(Response(...))`, or the corresponding `JSONRPC(Response(...))`.\n- In implementation code, return generated error constructors or generated custom error payloads.\n- Wrap underlying causes for logs and tracing, but keep client-facing messages safe.\n- Test errors through the service API. Verify generated error names, transport status mappings when\n  practical, and custom error payloads.\n\n## Security\n\n- Declare security schemes, required scopes, and credential fields in the design.\n- Prefer API-level defaults.\n- Override at service or method scope when needed.\n- Use `NoSecurity()` explicitly for public methods.\n- Add matching security payload fields such as `TokenField` or `APIKeyField`.\n- Map credentials through HTTP headers/query parameters or gRPC metadata.\n- Implement the generated authentication callbacks and application authorization rules.\n  A scheme declaration does not verify a token or establish resource ownership by itself.\n\n## Goa Interceptors Vs Middleware\n\nUse Goa interceptors for type-safe domain concerns:\n\n- Business validation that is not boundary validation.\n- Request enrichment.\n- Response enrichment.\n- Auditing.\n- Domain-level transformations.\n\nUse HTTP middleware or gRPC interceptors for protocol concerns:\n\n- Logging.\n- Tracing.\n- CORS.\n- Compression.\n- Request IDs.\n- Rate limiting.\n- Panic recovery.\n- Wire-level metadata.\n\nGoa interceptors are generated endpoint wrappers, not transport middleware:\n\n- Server interceptors run after transport decoding and before the service method.\n- Client interceptors run around the typed client endpoint before transport encoding and after\n  transport decoding.\n- Use generated typed accessors.\n- Call `next` exactly once when continuing.\n- If order matters, inspect generated `Wrap<Method>Endpoint`; the last wrapper runs first on the\n  request path.\n\n## Observability\n\nFor production services, wire observability, health checks, timeouts, graceful shutdown, and\nconfiguration at application boundaries. Goa docs recommend Clue/OpenTelemetry. Use generated\n`ServiceName`, `APIVersion`, method names, endpoint wrappers, and interceptor metadata for stable\ntelemetry labels.\n",".claude/skills/goa-release/SKILL.md":"---\nname: goa-release\ndescription: Release Goa v3, including preflight tests, dependency updates, semver version bumps, release preparation commits, examples/plugins repo checks, and babysitting make release. Use when the user asks to release Goa, prepare a Goa release, bump the Goa version, or run make release.\n---\n\n# Goa Release\n\nUse this skill only from the Goa repository. A stable release and an opt-in preview are separate\nworkflows. `make release` pushes branches and tags for Goa, examples, and plugins. A preview tags\nGoa alone from a reviewed feature branch. Do not run either publishing command unless the user\nexplicitly approves that exact release.\n\n## Release Contract\n\n- Goa major version is always `3`. Never increment `MAJOR`; if it is not `3`, stop and ask.\n- Resolve the target version before making dependency-update commits in any repository. The agent\n  should pick the version from the changes, explain the reasoning, and get confirmation before\n  editing files or running dependency updates.\n- Apply semver within v3:\n  - Patch release: increment `BUILD`.\n  - Minor release: increment `MINOR` and reset `BUILD=0`.\n- An opt-in preview uses `v3.MINOR.BUILD-preview.NUMBER`. Its version is a testing label, not a\n  promise of the final stable minor version. The major version remains 3.\n- The preparation commit message must be exactly `Prepare v3.x.y`, where `x` is `MINOR` and `y`\n  is `BUILD`.\n- The preview preparation commit message must be exactly `Prepare v3.x.y-preview.n`.\n- Keep the working trees clean between phases. Never discard local changes unless the user\n  explicitly approves it.\n- Do not push preparation commits manually. `make release-goa` runs `git pull origin <branch>` in\n  examples and plugins; local-ahead preparation commits are fine as long as `origin` is not ahead.\n  Later, `make release-examples` and `make release-plugins` push those preparation commits together\n  with the release commits and tags.\n\n## Version Selection\n\nDetermine the target version before changing any repository:\n\n1. Read `MAJOR`, `MINOR`, and `BUILD` from the Goa `Makefile`.\n2. Confirm `MAJOR=3`.\n3. Inspect the commits and merged PRs since the previous release tag.\n4. Pick the semver bump:\n   - Minor when the release includes a user-visible feature, new DSL/runtime capability, or\n     backward-compatible public API addition.\n   - Patch when the release only includes fixes, dependency updates, docs, tests, or internal\n     maintenance.\n5. Tell the user the selected target version and the specific changes that justify it, then ask for\n   confirmation. If the user supplied an explicit version, validate it against the same reasoning and\n   call out any mismatch before continuing.\n6. Use the exact confirmed target version for every preparation commit, tag check, and release\n   command.\n\n## Preview Release Contract\n\nUse this workflow only when the confirmed version ends in `-preview.N`.\n\n- Work from the reviewed feature branch. Do not switch to or move the stable `v3` branch.\n- Publish Goa only. Do not update, tag, or push the examples and plugins repositories.\n- Keep the stable README badge and stable `@latest` installation instructions unchanged.\n- Make the preview public only after the upgrade guide describes every known source, design, wire,\n  deployment, and rollback effect in plain English.\n- Treat `prepare-preview` and `release-preview` as separate approval points. The first creates the\n  version commit. The second creates and pushes the public tag.\n- Never run `make release` with `PREVIEW_NUMBER` set. That target is the stable multi-repository\n  release and deliberately rejects preview versions.\n\n### Prepare a preview\n\n1. Confirm the complete version, such as `v3.31.0-preview.1`.\n2. Fetch `origin`, verify the feature branch contains the latest stable branch, and verify the\n   working tree is clean. Preserve and report any existing local changes.\n3. Verify the exact preview tag is absent locally and on `origin`.\n4. Read `UPGRADING.md` against the current diff. Confirm it tells application and plugin authors\n   how to install, regenerate, migrate, deploy, roll back, and report a problem.\n5. Run:\n\n   ```bash\n   make prepare-preview MINOR=31 BUILD=0 PREVIEW_NUMBER=1\n   ```\n\n   The target runs the full preflight, updates the Makefile version and `pkg/version.go`, verifies\n   the command reports the preview version, and creates the exact preparation commit. It does not\n   create or push a tag.\n\n6. Push the feature branch through the normal review workflow and wait for every required check.\n7. Review the complete diff and GitHub release notes one final time.\n\n### Publish a preview\n\n1. Inventory the current branch, commit, local tag, and remote branch and tag.\n2. Get explicit maintainer approval to publish the exact preview tag.\n3. Run `make release-preview` and watch it until it exits. The target reruns the full preflight,\n   verifies the current commit is already on the same remote feature branch, creates the tag, and\n   pushes only the tag.\n4. If the command fails after creating the local tag, inspect local and remote state before any\n   rerun. Never delete a public tag or force-push without an approved recovery plan.\n5. Create a GitHub release for the tag with `--prerelease`. Link `UPGRADING.md`, describe the\n   preview as opt-in, and explain that the final stable minor version follows compatibility review.\n6. Verify the Go proxy resolves the exact preview version and that `@latest` still resolves the\n   current stable release.\n\n## Required Repositories\n\nBefore release, verify these repositories exist, are on the expected branches, are clean, and are\nin sync with their upstreams:\n\n- Goa: current repository, expected branch `v3`.\n- Examples: `$(go env GOPATH)/src/goa.design/examples`, expected branch `main`.\n- Plugins: `$(go env GOPATH)/src/goa.design/plugins`, expected branch `v3`.\n\nFor each repository:\n\n1. Run `git status --porcelain` and stop if there are uncommitted changes.\n2. Verify the current branch is the expected branch. If not, ask before switching branches.\n3. Run `git fetch origin`.\n4. Verify `git rev-list --left-right --count @{u}...HEAD` reports `0 0`. If behind, run\n   `git pull --ff-only`. If ahead or diverged, stop and ask.\n5. Verify the target tag does not already exist locally or on `origin`.\n\n## Preparation Workflow\n\n1. In the Goa repository, read `UPGRADING.md` against the diff since the previous release tag.\n   Retitle it to the target version, replace every `(unreleased)` section marker with a\n   `v3.x.y:` heading, add a `v3.x.y: upgrade order and rollback` summary when the range needs\n   one, update the installation commands and the official plugins version to the target, and fix\n   the README links and paragraph that describe the current release. Merge those edits through a\n   normal pull request before creating any preparation commit; `make release` does not update\n   this guide.\n2. In the Goa repository, run `make`. Fix failures before continuing.\n3. In the Goa repository, run:\n\n   ```bash\n   go get -u -v ./...\n   go mod tidy\n   (cd jsonrpc/integration_tests && go get -u -v ./... && go mod tidy)\n   make\n   ```\n\n   The JSON-RPC integration tests are a nested Go module; update and tidy it before rerunning\n   `make` so `integration-test` does not fail on stale module metadata. `go get` should only update\n   `go.mod` and `go.sum`. If other files changed in any repository, review why before committing.\n\n4. In the examples repository, run:\n\n   ```bash\n   go list -m -f '{{if .Main}}{{.Dir}}{{end}}' all | while IFS= read -r mod; do\n     [ -n \"$mod\" ] && (cd \"$mod\" && go get -u -v ./... && go mod tidy)\n   done\n   make\n   ```\n\n   The examples repository has no root `go.mod`; each example listed in `go.work` owns its own\n   module. Update and tidy every example module before running `make`. If files changed, commit them\n   with `Prepare v3.x.y`. Do not push; `make release-examples` pushes the branch.\n\n5. In the plugins repository, run:\n\n   ```bash\n   go get -u -v ./...\n   go mod tidy\n   make\n   ```\n\n   If files changed, commit them with `Prepare v3.x.y`. Do not push; `make release-plugins`\n   pushes the branch.\n\n6. In the Goa repository, edit only `MINOR`, `BUILD`, and the preview marker in `Makefile` for the\n   target version. Leave `MAJOR=3`. For a stable release, `PREVIEW_NUMBER` must be empty. The stable\n   release target clears the suffix in `pkg/version.go`; do not edit that generated version value\n   by hand.\n7. If Goa files changed from dependency updates or the version bump, commit them with\n   `Prepare v3.x.y`.\n8. Re-check all three repositories are clean. They may be ahead of upstream by their preparation\n   commits; that is expected because `make release` pushes them.\n\n## Final Pre-Release Check\n\n`make release` runs its own clean checks and release preflight, but those checks happen inside a\ncommand that can create commits, tags, and pushes. Before running it:\n\n1. In all three repositories, run `git fetch origin`.\n2. Verify `git status --porcelain` is empty.\n3. Verify upstream is not ahead: the first number from\n   `git rev-list --left-right --count @{u}...HEAD` must be `0`. Local-ahead preparation commits are\n   expected.\n4. Do not push the local-ahead preparation commits. `make release` will push them together with the\n   release commits.\n5. Reconfirm the target version and that the target tag is absent locally and on `origin` in all\n   three repositories.\n\n## Run And Babysit Release\n\n1. From the Goa repository, run `make release`.\n2. Watch the command until it exits. Track which phase is running: `release-goa`,\n   `release-examples`, or `release-plugins`.\n3. If it fails, stop and inspect the failing repository before rerunning anything. Do not blindly\n   rerun the whole release after a tag or push may have succeeded.\n4. Before any rerun, inventory local and remote branches and tags for `v3.x.y` in all three\n   repositories. Never recreate an existing tag, delete a public tag, or force-push unless the user\n   explicitly approves the recovery plan.\n5. Fix the root cause, verify the affected repository is in the expected state, then rerun the\n   narrowest safe target or command.\n6. When release completes, report the released version and the branch/tag pushes that succeeded.\n\n## GitHub Release Notes\n\nAfter `make release` succeeds, create GitHub release notes for the Goa tag.\n\n1. Gather the final commit/PR list from the previous Goa tag to the new tag. Include merged PR\n   numbers, titles, authors, and any notable dependency or downstream examples/plugins release work.\n2. Identify every human contributor in that range from commit authors and PR authors. Do not miss\n   contributors whose commits were merged by someone else. Exclude bots from the thank-you list\n   unless their work is directly meaningful to users.\n3. Write notes that are clear and useful to someone who does not know Goa internals:\n   - Start with a short plain-language summary of why the release matters.\n   - Use sections only when the amount of change justifies them, such as `Highlights`, `Fixes`,\n     `Dependencies`, `Upgrade Notes`, and `Contributors`.\n   - Explain user impact before implementation detail. Avoid raw commit-log dumps.\n   - Include upgrade notes only for actions users may need to take.\n   - Thank every contributor by name or handle.\n4. Create or update the GitHub release for `v3.x.y` with the final notes. Do not mention agent or AI\n   tooling in public release notes.\n\n## Announcements\n\nAfter GitHub release notes are ready, draft announcements for Slack, Bluesky, and Substack. Make\nthem exciting and delightful by showing what the release helps users do, not by adding hype.\n\nVoice rules:\n\n- Lead with the most concrete user payoff.\n- Use warm, crisp language with one or two memorable details from the release.\n- Avoid empty hype, forced jokes, excessive exclamation marks, launch cliches, and insider-only\n  wording.\n- Keep contributor thanks visible and sincere.\n\nChannel guidance:\n\n- Slack: 2-4 short paragraphs or bullets. Sound like a maintainer sharing good news with the\n  community. Lead with the most useful user-facing change, link to the GitHub release, and thank\n  contributors.\n- Bluesky: Posts are limited to 300 graphemes. Stay under that limit, include the version, one\n  concrete highlight, and a release link. Make the line feel polished enough to repost.\n- Substack: Write a short note for readers who may not know Goa deeply. Use a friendly title, a\n  brief explanation of Goa, a user-centered story for the release highlights, upgrade guidance if\n  any, and contributor thanks. Keep it proportional to the release size.\n",".cursor/skills/goa-release/SKILL.md":"---\nname: goa-release\ndescription: Release Goa v3, including preflight tests, dependency updates, semver version bumps, release preparation commits, examples/plugins repo checks, and babysitting make release. Use when the user asks to release Goa, prepare a Goa release, bump the Goa version, or run make release.\n---\n\n# Goa Release\n\nUse this skill only from the Goa repository. A stable release and an opt-in preview are separate\nworkflows. `make release` pushes branches and tags for Goa, examples, and plugins. A preview tags\nGoa alone from a reviewed feature branch. Do not run either publishing command unless the user\nexplicitly approves that exact release.\n\n## Release Contract\n\n- Goa major version is always `3`. Never increment `MAJOR`; if it is not `3`, stop and ask.\n- Resolve the target version before making dependency-update commits in any repository. The agent\n  should pick the version from the changes, explain the reasoning, and get confirmation before\n  editing files or running dependency updates.\n- Apply semver within v3:\n  - Patch release: increment `BUILD`.\n  - Minor release: increment `MINOR` and reset `BUILD=0`.\n- An opt-in preview uses `v3.MINOR.BUILD-preview.NUMBER`. Its version is a testing label, not a\n  promise of the final stable minor version. The major version remains 3.\n- The preparation commit message must be exactly `Prepare v3.x.y`, where `x` is `MINOR` and `y`\n  is `BUILD`.\n- The preview preparation commit message must be exactly `Prepare v3.x.y-preview.n`.\n- Keep the working trees clean between phases. Never discard local changes unless the user\n  explicitly approves it.\n- Do not push preparation commits manually. `make release-goa` runs `git pull origin <branch>` in\n  examples and plugins; local-ahead preparation commits are fine as long as `origin` is not ahead.\n  Later, `make release-examples` and `make release-plugins` push those preparation commits together\n  with the release commits and tags.\n\n## Version Selection\n\nDetermine the target version before changing any repository:\n\n1. Read `MAJOR`, `MINOR`, and `BUILD` from the Goa `Makefile`.\n2. Confirm `MAJOR=3`.\n3. Inspect the commits and merged PRs since the previous release tag.\n4. Pick the semver bump:\n   - Minor when the release includes a user-visible feature, new DSL/runtime capability, or\n     backward-compatible public API addition.\n   - Patch when the release only includes fixes, dependency updates, docs, tests, or internal\n     maintenance.\n5. Tell the user the selected target version and the specific changes that justify it, then ask for\n   confirmation. If the user supplied an explicit version, validate it against the same reasoning and\n   call out any mismatch before continuing.\n6. Use the exact confirmed target version for every preparation commit, tag check, and release\n   command.\n\n## Preview Release Contract\n\nUse this workflow only when the confirmed version ends in `-preview.N`.\n\n- Work from the reviewed feature branch. Do not switch to or move the stable `v3` branch.\n- Publish Goa only. Do not update, tag, or push the examples and plugins repositories.\n- Keep the stable README badge and stable `@latest` installation instructions unchanged.\n- Make the preview public only after the upgrade guide describes every known source, design, wire,\n  deployment, and rollback effect in plain English.\n- Treat `prepare-preview` and `release-preview` as separate approval points. The first creates the\n  version commit. The second creates and pushes the public tag.\n- Never run `make release` with `PREVIEW_NUMBER` set. That target is the stable multi-repository\n  release and deliberately rejects preview versions.\n\n### Prepare a preview\n\n1. Confirm the complete version, such as `v3.31.0-preview.1`.\n2. Fetch `origin`, verify the feature branch contains the latest stable branch, and verify the\n   working tree is clean. Preserve and report any existing local changes.\n3. Verify the exact preview tag is absent locally and on `origin`.\n4. Read `UPGRADING.md` against the current diff. Confirm it tells application and plugin authors\n   how to install, regenerate, migrate, deploy, roll back, and report a problem.\n5. Run:\n\n   ```bash\n   make prepare-preview MINOR=31 BUILD=0 PREVIEW_NUMBER=1\n   ```\n\n   The target runs the full preflight, updates the Makefile version and `pkg/version.go`, verifies\n   the command reports the preview version, and creates the exact preparation commit. It does not\n   create or push a tag.\n\n6. Push the feature branch through the normal review workflow and wait for every required check.\n7. Review the complete diff and GitHub release notes one final time.\n\n### Publish a preview\n\n1. Inventory the current branch, commit, local tag, and remote branch and tag.\n2. Get explicit maintainer approval to publish the exact preview tag.\n3. Run `make release-preview` and watch it until it exits. The target reruns the full preflight,\n   verifies the current commit is already on the same remote feature branch, creates the tag, and\n   pushes only the tag.\n4. If the command fails after creating the local tag, inspect local and remote state before any\n   rerun. Never delete a public tag or force-push without an approved recovery plan.\n5. Create a GitHub release for the tag with `--prerelease`. Link `UPGRADING.md`, describe the\n   preview as opt-in, and explain that the final stable minor version follows compatibility review.\n6. Verify the Go proxy resolves the exact preview version and that `@latest` still resolves the\n   current stable release.\n\n## Required Repositories\n\nBefore release, verify these repositories exist, are on the expected branches, are clean, and are\nin sync with their upstreams:\n\n- Goa: current repository, expected branch `v3`.\n- Examples: `$(go env GOPATH)/src/goa.design/examples`, expected branch `main`.\n- Plugins: `$(go env GOPATH)/src/goa.design/plugins`, expected branch `v3`.\n\nFor each repository:\n\n1. Run `git status --porcelain` and stop if there are uncommitted changes.\n2. Verify the current branch is the expected branch. If not, ask before switching branches.\n3. Run `git fetch origin`.\n4. Verify `git rev-list --left-right --count @{u}...HEAD` reports `0 0`. If behind, run\n   `git pull --ff-only`. If ahead or diverged, stop and ask.\n5. Verify the target tag does not already exist locally or on `origin`.\n\n## Preparation Workflow\n\n1. In the Goa repository, read `UPGRADING.md` against the diff since the previous release tag.\n   Retitle it to the target version, replace every `(unreleased)` section marker with a\n   `v3.x.y:` heading, add a `v3.x.y: upgrade order and rollback` summary when the range needs\n   one, update the installation commands and the official plugins version to the target, and fix\n   the README links and paragraph that describe the current release. Merge those edits through a\n   normal pull request before creating any preparation commit; `make release` does not update\n   this guide.\n2. In the Goa repository, run `make`. Fix failures before continuing.\n3. In the Goa repository, run:\n\n   ```bash\n   go get -u -v ./...\n   go mod tidy\n   (cd jsonrpc/integration_tests && go get -u -v ./... && go mod tidy)\n   make\n   ```\n\n   The JSON-RPC integration tests are a nested Go module; update and tidy it before rerunning\n   `make` so `integration-test` does not fail on stale module metadata. `go get` should only update\n   `go.mod` and `go.sum`. If other files changed in any repository, review why before committing.\n\n4. In the examples repository, run:\n\n   ```bash\n   go list -m -f '{{if .Main}}{{.Dir}}{{end}}' all | while IFS= read -r mod; do\n     [ -n \"$mod\" ] && (cd \"$mod\" && go get -u -v ./... && go mod tidy)\n   done\n   make\n   ```\n\n   The examples repository has no root `go.mod`; each example listed in `go.work` owns its own\n   module. Update and tidy every example module before running `make`. If files changed, commit them\n   with `Prepare v3.x.y`. Do not push; `make release-examples` pushes the branch.\n\n5. In the plugins repository, run:\n\n   ```bash\n   go get -u -v ./...\n   go mod tidy\n   make\n   ```\n\n   If files changed, commit them with `Prepare v3.x.y`. Do not push; `make release-plugins`\n   pushes the branch.\n\n6. In the Goa repository, edit only `MINOR`, `BUILD`, and the preview marker in `Makefile` for the\n   target version. Leave `MAJOR=3`. For a stable release, `PREVIEW_NUMBER` must be empty. The stable\n   release target clears the suffix in `pkg/version.go`; do not edit that generated version value\n   by hand.\n7. If Goa files changed from dependency updates or the version bump, commit them with\n   `Prepare v3.x.y`.\n8. Re-check all three repositories are clean. They may be ahead of upstream by their preparation\n   commits; that is expected because `make release` pushes them.\n\n## Final Pre-Release Check\n\n`make release` runs its own clean checks and release preflight, but those checks happen inside a\ncommand that can create commits, tags, and pushes. Before running it:\n\n1. In all three repositories, run `git fetch origin`.\n2. Verify `git status --porcelain` is empty.\n3. Verify upstream is not ahead: the first number from\n   `git rev-list --left-right --count @{u}...HEAD` must be `0`. Local-ahead preparation commits are\n   expected.\n4. Do not push the local-ahead preparation commits. `make release` will push them together with the\n   release commits.\n5. Reconfirm the target version and that the target tag is absent locally and on `origin` in all\n   three repositories.\n\n## Run And Babysit Release\n\n1. From the Goa repository, run `make release`.\n2. Watch the command until it exits. Track which phase is running: `release-goa` (including\n   `warm-proxy`, which waits for `gopkg.in` to expose the new tag and warms `proxy.golang.org` and\n   `sum.golang.org` by commit hash before querying the tag), `release-examples`, or\n   `release-plugins`.\n3. If it fails, stop and inspect the failing repository before rerunning anything. Do not blindly\n   rerun the whole release after a tag or push may have succeeded.\n4. Before any rerun, inventory local and remote branches and tags for `v3.x.y` in all three\n   repositories. Never recreate an existing tag, delete a public tag, or force-push unless the user\n   explicitly approves the recovery plan.\n5. Fix the root cause, verify the affected repository is in the expected state, then rerun the\n   narrowest safe target or command.\n6. When release completes, report the released version and the branch/tag pushes that succeeded.\n\n## GitHub Release Notes\n\nAfter `make release` succeeds, create GitHub release notes for the Goa tag.\n\n1. Gather the final commit/PR list from the previous Goa tag to the new tag. Include merged PR\n   numbers, titles, authors, and any notable dependency or downstream examples/plugins release work.\n2. Identify every human contributor in that range from commit authors and PR authors. Do not miss\n   contributors whose commits were merged by someone else. Exclude bots from the thank-you list\n   unless their work is directly meaningful to users.\n3. Write notes that are clear and useful to someone who does not know Goa internals:\n   - Start with a short plain-language summary of why the release matters.\n   - Use sections only when the amount of change justifies them, such as `Highlights`, `Fixes`,\n     `Dependencies`, `Upgrade Notes`, and `Contributors`.\n   - Explain user impact before implementation detail. Avoid raw commit-log dumps.\n   - Include upgrade notes only for actions users may need to take.\n   - Thank every contributor by name or handle.\n4. Create or update the GitHub release for `v3.x.y` with the final notes. Do not mention agent or AI\n   tooling in public release notes.\n\n## Announcements\n\nAfter GitHub release notes are ready, draft announcements for Slack, Bluesky, and Substack. Make\nthem exciting and delightful by showing what the release helps users do, not by adding hype.\n\nVoice rules:\n\n- Lead with the most concrete user payoff.\n- Use warm, crisp language with one or two memorable details from the release.\n- Avoid empty hype, forced jokes, excessive exclamation marks, launch cliches, and insider-only\n  wording.\n- Keep contributor thanks visible and sincere.\n\nChannel guidance:\n\n- Slack: 2-4 short paragraphs or bullets. Sound like a maintainer sharing good news with the\n  community. Lead with the most useful user-facing change, link to the GitHub release, and thank\n  contributors.\n- Bluesky: Posts are limited to 300 graphemes. Stay under that limit, include the version, one\n  concrete highlight, and a release link. Make the line feel polished enough to repost.\n- Substack: Write a short note for readers who may not know Goa deeply. Use a friendly title, a\n  brief explanation of Goa, a user-centered story for the release highlights, upgrade guidance if\n  any, and contributor thanks. Keep it proportional to the release size.\n","AGENTS.md":"# Repository Guidelines\n\n## Common Rules\n\n### Agent Behavior\n\n- **Plan before acting**: For ≤2 files, state a brief plan then implement. For ≥3 files, write a step-by-step plan first.\n- **Read before editing**: Always read files before modifying. Search over guessing.\n- **Fix root causes**: Do not produce local workarounds—fix the real issue.\n- **Be concise**: Give short status updates during multi-step work. Present a short summary when done.\n\n### Go Code Style\n\n- **Go 1.26+**. Format with `go fmt ./...`.\n- **Imports**: Group stdlib separate from external. Let gofmt manage ordering.\n- **Files**: Use `lower_snake_case.go`. Keep ≤1000 lines; split proactively.\n- **Naming**: Packages are lowercase and short. Exported identifiers need GoDoc. Avoid stutter.\n- **Types**: Use `any` over `interface{}`. Prefer concrete types over `interface{}`.\n- **Errors**: Wrap with `%w`. Use `errors.Is/As`. **Never ignore errors or use `_ = call()`**.\n- **Signatures**: Keep on one line when ≤100 columns. Only wrap genuinely long signatures.\n- **Slice/map nil**: Do not check nil before `len`. `len(nil)` returns 0. Use `len(x) == 0` directly.\n\n### Code Blocks and Literals\n\n- Always place a newline after `{` and before `}` for `if`, `for`, `switch`, `func`, `type`.\n- No single-line blocks: `if cond { do() }` → use multiple lines.\n- Short struct literals are fine inline: `&T{A: 1}`. Break long literals to one field per line with trailing commas.\n\n### File Organization\n\nOrder declarations as:\n1. Types (public, then private) in a single `type (...)` block when practical\n2. Constants (public, then private)\n3. Variables (public, then private)\n4. Public functions\n5. Public methods\n6. Private functions\n7. Private methods\n\nNo commented-out code—delete dead code.\n\n### Error Handling & Contracts\n\n- **Always check errors**. Never discard with `_`.\n- **Strong contracts**: Goa validates payloads at boundaries. Do not re-validate inside service code.\n- **No defensive programming**: Do not add nil/empty guards for values guaranteed by construction, Goa, or prior validation.\n- **Validate only at boundaries**: HTTP/gRPC handlers, event consumers, DB results, third-party APIs, `ctx.Value()`, type assertions, required map lookups.\n- **Fail fast**: Unexpected states are bugs. Return precise errors or panic—do not silently recover or skip.\n\n### Goa DSL Rules\n\n- **Never edit `gen/`**: Always regenerate.\n- **DSL validation**: Put validations (lengths, enums, formats) in the design. Do not re-validate in code.\n- **Avoid `Any`**: Use concrete types to enable gRPC generation.\n\n### Codegen Implementation\n\n- **Critical — finish work during generation**: Use the complete design, generation plan,\n  and Go templates to decide everything that is known before the generated\n  program runs. Select branches, names, types, imports, field paths, helper\n  calls, and emitted files while generating source. Templates must write only\n  the selected code. Do not make generated programs inspect generated type\n  shapes, parse generator-made names, carry generator mode flags, or execute\n  branches whose answer was already known. Runtime code should contain only\n  logic that depends on actual runtime values. When a runtime value is truly\n  required, keep that input narrow and specialize all surrounding code during\n  generation.\n- **Use NameScope helpers** for type references: `GoTypeRef`, `GoFullTypeRef`, `GoTypeName`. Never concatenate strings for types.\n- Let Goa decide pointer/value semantics. Do not force `pointer=true` except in transport validation.\n- **Keep helper visibility minimal**: If logic is shared only inside one codegen area, keep it package-private or move it under an `internal` package. Do not export helpers from a parent package just to share them across sibling generators.\n- **Avoid pass-through wrappers**: When two helper functions differ only by forwarding arguments or hard-coding `nil`, collapse them into a single implementation instead of adding an extra layer.\n- **Generated packages own names**: When several services or plugins write to\n  one Go package, collect every package-level name before rendering and then\n  make those names final. A declaration and every HTTP, gRPC, or JSON-RPC use\n  of it must read the same name record. Do not give each service or plugin a\n  separate name scope for the same package, and do not add declarations after\n  names become final.\n- **Keep identity typed and explicit**: Do not hide a declaration's kind,\n  package, or use in a decorated name or a made-up string map key. Do not\n  change an expression's `Hash` behavior to solve a generation problem. Pass a\n  typed identifier where the generated declaration is named.\n- **Trace the complete lifecycle**: Before changing relocated types, union\n  naming, generation roots, plugins, or file merging, follow the declaration\n  from the evaluated design through service analysis, its generated Go\n  package, the emitted service code, HTTP and gRPC uses, plugin changes, and\n  the final file merge. A service-only rendering test is not enough.\n  See [`codegen/ARCHITECTURE.md`](codegen/ARCHITECTURE.md).\n\n### Documentation\n\n- Every exported type, function, method, and field must have a GoDoc comment explaining its contract—like Go stdlib documentation.\n\n### Safety & Forbidden Operations\n\n| Action | Policy |\n|--------|--------|\n| `git clean/stash/reset/checkout` | **FORBIDDEN** |\n| `go clean -cache` | **FORBIDDEN** during normal work |\n| Edit `gen/` directly | **FORBIDDEN** |\n| Changes ≥3 files | Describe plan first |\n| New dependencies | Explain why first |\n\n### Testing\n\n- Write table-driven tests in `*_test.go`.\n- Name tests `TestXxx`. Keep fast and deterministic.\n- Use `testify/require` for assertions.\n- Prefer `t.Errorf` over `t.Fatalf` so tests report multiple failures.\n\n---\n\n## Goa-Specific Rules\n\n### Project Structure\n\n- `dsl/`: Public DSL definitions (dot imports allowed per `.golangci.yml`)\n- `expr/`: Internal AST and validation\n- `codegen/`: Generators for transports, types, docs\n- `http/`, `grpc/`, `jsonrpc/`: Transport-specific codegen\n- `middleware/`: Built-in interceptors\n- `pkg/`: Core runtime\n- `cmd/goa/`: CLI source\n\n### Build & Test\n\n```bash\nmake lint          # Run linters\nmake test          # Run tests\ncd cmd/goa && go install .  # Install CLI locally\n```\n\n### Releases\n\n- For every Goa release or version bump, follow\n  [`.cursor/skills/goa-release/SKILL.md`](.cursor/skills/goa-release/SKILL.md).\n- Do not edit `pkg/version.go` or the README version badge by hand during the standard release\n  workflow; `make release` owns those changes.\n\n### Code Generation Behavior\n\n- After modifying goa source, `goa gen` and `goa example` automatically compile and use your changes—no manual rebuild needed.\n- `goa gen` deletes and recreates the entire `gen/` directory.\n- `goa example` only creates new files; it does not overwrite existing `cmd/` files.\n\n### Repro Protocol\n\nTo reproduce a codegen issue:\n1. Create `~/src/repros/<issue>/design/design.go`\n2. `go mod init <issue>` in the issue directory\n3. `goa gen <issue>/design`\n4. `go mod tidy`\n5. `go mod edit -replace goa.design/goa/v3=$HOME/src/goa`\n6. `goa gen <issue>/design` again with local goa\n7. Optional: `goa example <issue>/design`\n\n### Slices/Maps and Required Fields\n\nDo not rely on nil versus empty slices or maps to encode domain meaning.\nRequired JSON fields may contain empty collections unless a length constraint\nforbids them; keep `Required` when the JSON property must be present. Protobuf\nrepeated and map fields cannot distinguish absent from empty, so their generated\nvalidation checks length and contents, not presence. Message, scalar, and oneof\npresence checks remain independent of collection emptiness.\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nRead @AGENTS.md","skills/goa-service-designer/SKILL.md":"---\nname: goa-service-designer\ndescription: Design and evolve Goa application services. Use for Goa DSL changes, HTTP/gRPC/JSON-RPC contracts, validation, errors, interceptors, code generation, and service implementation.\n---\n\n# Goa Service Designer\n\nUse this skill for applications and plugins that declare or consume Goa contracts. Repository\ninstructions govern implementation. For changes to Goa's own compiler, runtime, templates, or\ngenerators, use Goa's contributor workflow instead of the application workflow below; still use the\nreference and capability checks below when deciding what the DSL or generated transport supports.\n\nLet Goa generate the mechanical code. Use the relevant design and generated service interface as\nthe working context; inspect transport output when the task changes wire behavior. Implement the\napplication's decisions outside `gen/`.\n\n## Consult The Relevant Reference Before Designing\n\nRead the relevant reference before a non-trivial design or implementation decision. Do not wait\nuntil generation fails, and do not treat the links as optional background reading:\n\n- For HTTP, gRPC, or JSON-RPC mappings, streaming, errors, security, or interceptor behavior, read\n  [transport guidance](references/transport-errors-interceptors.md).\n- For named types, aliases, pointers, defaults, unions, views, or validation, read\n  [modeling guidance](references/modeling-and-validation.md).\n- For generated signatures, constructors, codecs, imports, or downstream implementation changes,\n  read [generated-code guidance](references/generated-code-and-implementation.md).\n- When observed output or behavior contradicts the design, also read\n  [troubleshooting](references/troubleshooting.md).\n\nBefore introducing a transport workaround or claiming that Goa cannot express a requirement:\n\n1. Check the existing DSL mechanism in the reference and the selected Goa version's source. For\n   example, `Param(\"attributeName:url_name\")` separates a payload field from its URL parameter name;\n   inspect that mapping before renaming path tokens or adding transport-only replacement fields.\n2. Trace the authored mapping through generated payloads, client encoding, server decoding, and\n   endpoint invocation. Distinguish the payload name, HTTP element name, and generated Go selector.\n3. Verify the disputed capability with a minimal authored design and generated client/server check\n   before editing its replacement. A reference states the intended contract; it does not prove the\n   selected generator implements it correctly. Keep a failing result and trace its owning layer\n   rather than assuming the DSL lacks the feature.\n\nReuse a working native mechanism. If it fails, explain the exact generator gap and why a change\nbelongs in Goa or the consuming plugin before implementing it. Read only the references relevant\nto the decision; routine mechanical edits do not require loading every reference.\n\n## Default Workflow\n\n1. Find the local design, generated service contract, implementation, generation wrapper, validation\n   commands, and affected consumers. Check the Goa version and any replacement in `go.mod`.\n2. Reuse established local patterns for routine edits. Consult goa.design when choosing an\n   unfamiliar feature, resolving uncertain DSL or generated behavior, or troubleshooting.\n   Read only the relevant section, using these topic routes:\n   - New project: [Quickstart](https://goa.design/docs/1-goa/quickstart/) and [Code Generation](https://goa.design/docs/1-goa/code-generation/).\n   - Types, validation, views, or unions: [DSL Reference](https://goa.design/docs/1-goa/dsl-reference/).\n   - HTTP mapping, WebSocket, or SSE: [HTTP Guide](https://goa.design/docs/1-goa/http-guide/).\n   - gRPC, protobuf tags, metadata, or streaming: [gRPC Guide](https://goa.design/docs/1-goa/grpc-guide/).\n   - JSON-RPC: [transport reference](references/transport-errors-interceptors.md#json-rpc-mapping) and the selected Goa version's `dsl.JSONRPC` documentation.\n   - Errors: [Error Handling](https://goa.design/docs/1-goa/error-handling/).\n   - Interceptors or middleware: [Interceptors](https://goa.design/docs/1-goa/interceptors/).\n   - Security or production wiring: [Production](https://goa.design/docs/1-goa/production/).\n   Online docs may describe a different release. For release-specific behavior and upgrades, use the\n   selected Goa checkout's `UPGRADING.md` and generated output. Use a page's Markdown version\n   when available; do not preload every guide or reference.\n3. State the intended contract change in one or two sentences.\n4. Edit the Goa design first.\n5. Regenerate with the project's wrapper. Without one, use\n   `go run goa.design/goa/v3/cmd/goa gen <design-package-import-path>` so the command uses the\n   application's selected module version. Never use `goa gen ./design`.\n6. Implement the generated interface outside `gen/`.\n7. Update only affected consumers: mocks, clients, docs, examples, API snapshots, OpenAPI/protobuf\n   consumers, command wiring, and project-specific SDKs generated from Goa output.\n8. Run the generation, lint, type-check, and test commands allowed by the repository instructions.\n   If a command is prohibited or too broad, state exactly what was not run.\n9. Review generated and hand-written diffs together. Every generated change should follow from\n   the design or an intentional tooling upgrade.\n\nUse `goa example <design-package-import-path>` when starter files are needed. It creates missing\napplication files and does not update existing files. Review new files and update existing wiring\nyourself; do not expect it to migrate an implementation.\n\n## Hard Rules\n\n- Treat the Goa design as the canonical contract. If payload shape, result shape, validation,\n  security, errors, transport mapping, documentation, OpenAPI, protobuf, generated clients, or CLIs\n  need to change, edit the design first and regenerate.\n- Never patch generated files, OpenAPI output, protobuf output, or generated clients to hide a stale\n  design.\n- Keep protobuf field numbers unique within the final message, including inherited fields.\n  Never renumber or reuse released field numbers to make a sequence contiguous.\n- Put boundary validation in Goa. Use `Required`, `Enum`, `Format`, `Pattern`, `Minimum`,\n  `Maximum`, `MinLength`, `MaxLength`, defaults, security fields, and explicit transport mappings in\n  the design.\n- Model error applicability at the narrowest correct Goa scope. API-level errors define reusable\n  potential errors and let transports map them once; they do not mean every endpoint returns every\n  API-level error. Service-level errors apply to all methods in that service. Method-level errors\n  apply only to that method. Do not list an error at service scope just to make a generated\n  constructor convenient if only some methods can return it.\n- In service code, trust payloads already validated by the generated transport and enforce business\n  invariants. Direct service or endpoint calls bypass transport decoding; their callers must supply\n  valid values or validate at their own input boundary. Do not add nil guards,\n  fallback behavior, silent recovery, blanket string trimming, or compatibility shims for values the\n  design guarantees.\n- Do not use nil versus empty slices or maps as domain meaning. `Required` and `MinLength` express\n  different constraints, and JSON and protobuf have different collection presence rules. See\n  [presence and collections](references/modeling-and-validation.md#presence-and-collections).\n- Preserve compatibility for shipped public APIs, persisted data, external SDKs, and documented\n  behavior. For internal-only contracts or unshipped branch work, update callers cleanly instead of\n  adding shims.\n\n## Design Conventions\n\nFollow the application's existing conventions and compatibility requirements. For new designs:\n\n- Prefix explicit generated-package aliases with `gen`, such as `genfront` or `genfrontgrpc`.\n- Prefer lower camel case for public HTTP fields and parameters (`accountId`) and snake case for\n  method names (`get_account`). Map established wire names explicitly, for example\n  `Header(\"tusResumable:Tus-Resumable\")`.\n- Use literal integer `Field` tags so wire identities are easy to review. Start a new standalone\n  definition at `1`. For an `Extend` definition, `100` can start a new range only if inherited fields\n  leave that range free. Inspect the complete inheritance chain and assign unused numbers; nested\n  `Extend` calls must not restart at an occupied `100`. Existing tags always keep their numbers.\n\nThese are authoring conventions, not requirements imposed by Goa.\n\n## What To Read Next\n\nUse the decision triggers above to select references; the details below describe their scope:\n\n- `references/modeling-and-validation.md`: type modeling, primitive aliases, required fields,\n  pointer/default semantics, views, presence, and compatibility.\n- `references/transport-errors-interceptors.md`: HTTP, gRPC, JSON-RPC, streaming, errors, security,\n  interceptors, middleware, and observability labels.\n- `references/generated-code-and-implementation.md`: generated diff triage, dirty worktrees,\n  implementation updates, downstream artifacts, and validation commands.\n- `references/troubleshooting.md`: generation failures, decode bugs, gRPC output surprises,\n  interceptor ordering, and common mini-patterns.\n\n## Final Review\n\nBefore finishing, verify:\n\n- The design remains the source of truth.\n- Generated code was regenerated, not edited.\n- Payloads, results, validation, security, errors, and transport mappings are explicit.\n- Service code trusts established validation boundaries and handles real dependency failures.\n- Compatibility choices are represented in the design and tests, not hidden in service fallbacks.\n- Affected downstream consumers are updated; unaffected artifacts are left alone.\n- New transport workarounds and capability claims have evidence from the native generated path.\n- Test coverage matches the risk of the contract change.\n",".cursorrules":"# Goa repository rules for Cursor\n\n- Never edit generated code. Fix the generator/templates instead.\n- Prefer any over interface{} in new code.\n- Transports: HTTP, gRPC, and JSON-RPC 2.0 (HTTP, SSE, WebSocket). JSON-RPC supports batch and notifications; streaming over WS/SSE.\n- Testing:\n  - Run unit tests with `make test`.\n  - JSON-RPC integration tests live in `jsonrpc/integration_tests`; run with `make integration-test` (skips on Windows).\n  - Golden tests use testify; update with `go test -update` or `-u`.\n- Code style:\n  - Small, focused files; one main construct per file when possible.\n  - Public types first, then private types, public constants, private constants, public vars, private vars, public functions/methods, then private.\n  - Use `maps.Copy`/`slices.Contains`, `http.NoBody`, avoid shadowing builtins.\n- Architecture quick map:\n  - `dsl/` (design DSL), `expr/` (expressions), `codegen/` (generation engine & templates), `cmd/goa/` (CLI), `http/`, `grpc/`, `jsonrpc/` (transports), `pkg/`, `middleware/`, `security/`, `eval/`.\n- For deeper guidance, see `CLAUDE.md`.\n","skills/goa-service-designer/references/transport-errors-interceptors.md":"# Transport, Errors, And Interceptors\n\nUse this reference when changing HTTP, gRPC, or JSON-RPC mappings, streaming, errors, security,\ninterceptors, middleware, or production wiring. The gRPC presence and JSON-RPC behavior below\ndescribes Goa v3.31 and later. Check the application's selected module version and its\n`UPGRADING.md` before changing older code.\n\n## HTTP Mapping\n\n- Use resource nouns, plural names, stable hierarchy, and HTTP methods for actions.\n- Put stable prefixes in API-level or service-level `HTTP(Path(...))`.\n- Use `Parent` and `CanonicalMethod` only when nested resources become clearer.\n- Map path, query, header, and body fields deliberately with `Param`, `Header`, and `Body`.\n- Use explicit wire-name mapping when attribute names differ from HTTP element names.\n- Choose status codes intentionally. Use `StatusCreated` for creates when appropriate.\n- Use default content negotiation unless a real media type requires custom encoders or decoders.\n- Use the CORS plugin for browser-facing cross-origin policy.\n- Use `Files` only for HTTP static content.\n\nHTTP object payload checks:\n\n- Every path token must map to a payload field.\n- Every non-body attribute should land where intended.\n- Use `Body(\"field\")` only when the request body should be that field's raw value.\n- Unmapped object attributes are encoded in the body.\n\n```go\nHTTP(func() {\n    GET(\"/accounts/{account_id}/items\")\n    Param(\"accountId:account_id\")\n    Param(\"limit\")\n    Response(StatusOK)\n    Response(\"not_found\", StatusNotFound)\n})\n```\n\n## Streaming\n\nGoa's streaming DSL is transport-agnostic. The transport mapping determines HTTP behavior:\n\n- Plain HTTP streaming defaults to WebSocket.\n- Add `ServerSentEvents()` only for one-way server-to-client streams.\n- WebSocket endpoints use `GET`.\n- For gRPC streaming, check generated protobuf and server/client stream types.\n- JSON-RPC supports unary calls or a single request followed by an\n  explicit SSE stream. It rejects client or bidirectional streaming, WebSocket streams, and a\n  method combining `Result` with `StreamingResult`. Ordinary HTTP WebSocket support is separate.\n- Streaming implementations must handle flow control, `io.EOF`, send errors, context cancellation,\n  timeouts, and cleanup.\n\n## gRPC Mapping\n\n- Set package and version metadata for public or versioned APIs.\n- Keep domain data in messages.\n- Use metadata, headers, and trailers only for protocol metadata.\n- Use streaming for large or continuous datasets.\n- Never renumber released `Field` values.\n- Check `.proto` output after changing shared types, streaming methods, or custom protobuf metadata.\n- Required singular scalars preserve protobuf presence. An omitted required\n  boolean is invalid; an explicitly supplied `false` can be valid. Generated decoders validate\n  before converting to service values. See the modeling reference for collections and defaults.\n\n## JSON-RPC Mapping\n\n- Use service-level `JSONRPC` to configure the shared HTTP POST endpoint, and method-level\n  `JSONRPC` for method-specific behavior and error mappings.\n- Let generated code own the JSON-RPC envelope, dispatch, request IDs, batches, and protocol errors.\n  The payload describes `params`; do not handwrite transport envelopes in service code.\n- Ordinary generated client calls have an ID even without an `ID` payload field.\n  `Notification()` explicitly declares a one-way call. Having no result does not by itself make\n  a method a notification. Notifications cannot declare a result, ID field, or stream.\n- `ID` belongs directly in the payload, not the result. The transport returns the request ID;\n  the service does not choose a response ID.\n- Map designed errors with JSON-RPC `Response` codes. Verify the generated error `data` shape\n  before changing a custom client's decoding.\n- For SSE, pair `StreamingResult` with method-level `ServerSentEvents()`. Verify event field\n  mappings and cancellation through the generated client and server.\n\n## Errors\n\n- Define reusable potential errors at API scope when you want one canonical error type/name and one\n  transport mapping. API-level `Error(...)` declarations do not make those errors applicable to\n  every endpoint. Select a reusable definition with `Error(\"name\")` at service or method scope.\n- Define an error at service scope only when every method on that service can return it.\n- Define an error at method scope when only that method can return it.\n- Do not promote a method-specific error to service scope just to avoid repeating a declaration or to\n  make generated constructors easier to reach; the design would falsely advertise that all service\n  methods can return it.\n- Use descriptive names and descriptions.\n- Prefer `ErrorResult` for most errors.\n- Add `Temporary()`, `Timeout()`, or `Fault()` when clients should behave differently.\n- Use custom error types only when clients need structured context.\n- If multiple custom errors can return from the same method, include a field marked with\n  `Meta(\"struct:error:name\")`.\n- Map every exposed error for each enabled transport with `HTTP(Response(...))` and\n  `GRPC(Response(...))`, or the corresponding `JSONRPC(Response(...))`.\n- In implementation code, return generated error constructors or generated custom error payloads.\n- Wrap underlying causes for logs and tracing, but keep client-facing messages safe.\n- Test errors through the service API. Verify generated error names, transport status mappings when\n  practical, and custom error payloads.\n\n## Security\n\n- Declare security schemes, required scopes, and credential fields in the design.\n- Prefer API-level defaults.\n- Override at service or method scope when needed.\n- Use `NoSecurity()` explicitly for public methods.\n- Add matching security payload fields such as `TokenField` or `APIKeyField`.\n- Map credentials through HTTP headers/query parameters or gRPC metadata.\n- Implement the generated authentication callbacks and application authorization rules.\n  A scheme declaration does not verify a token or establish resource ownership by itself.\n\n## Goa Interceptors Vs Middleware\n\nUse Goa interceptors for type-safe domain concerns:\n\n- Business validation that is not boundary validation.\n- Request enrichment.\n- Response enrichment.\n- Auditing.\n- Domain-level transformations.\n\nUse HTTP middleware or gRPC interceptors for protocol concerns:\n\n- Logging.\n- Tracing.\n- CORS.\n- Compression.\n- Request IDs.\n- Rate limiting.\n- Panic recovery.\n- Wire-level metadata.\n\nGoa interceptors are generated endpoint wrappers, not transport middleware:\n\n- Server interceptors run after transport decoding and before the service method.\n- Client interceptors run around the typed client endpoint before transport encoding and after\n  transport decoding.\n- Use generated typed accessors.\n- Call `next` exactly once when continuing.\n- If order matters, inspect generated `Wrap<Method>Endpoint`; the last wrapper runs first on the\n  request path.\n\n## Observability\n\nFor production services, wire observability, health checks, timeouts, graceful shutdown, and\nconfiguration at application boundaries. Goa docs recommend Clue/OpenTelemetry. Use generated\n`ServiceName`, `APIVersion`, method names, endpoint wrappers, and interceptor metadata for stable\ntelemetry labels.\n",".claude/skills/goa-release/SKILL.md":"---\nname: goa-release\ndescription: Release Goa v3, including preflight tests, dependency updates, semver version bumps, release preparation commits, examples/plugins repo checks, and babysitting make release. Use when the user asks to release Goa, prepare a Goa release, bump the Goa version, or run make release.\n---\n\n# Goa Release\n\nUse this skill only from the Goa repository. A stable release and an opt-in preview are separate\nworkflows. `make release` pushes branches and tags for Goa, examples, and plugins. A preview tags\nGoa alone from a reviewed feature branch. Do not run either publishing command unless the user\nexplicitly approves that exact release.\n\n## Release Contract\n\n- Goa major version is always `3`. Never increment `MAJOR`; if it is not `3`, stop and ask.\n- Resolve the target version before making dependency-update commits in any repository. The agent\n  should pick the version from the changes, explain the reasoning, and get confirmation before\n  editing files or running dependency updates.\n- Apply semver within v3:\n  - Patch release: increment `BUILD`.\n  - Minor release: increment `MINOR` and reset `BUILD=0`.\n- An opt-in preview uses `v3.MINOR.BUILD-preview.NUMBER`. Its version is a testing label, not a\n  promise of the final stable minor version. The major version remains 3.\n- The preparation commit message must be exactly `Prepare v3.x.y`, where `x` is `MINOR` and `y`\n  is `BUILD`.\n- The preview preparation commit message must be exactly `Prepare v3.x.y-preview.n`.\n- Keep the working trees clean between phases. Never discard local changes unless the user\n  explicitly approves it.\n- Do not push preparation commits manually. `make release-goa` runs `git pull origin <branch>` in\n  examples and plugins; local-ahead preparation commits are fine as long as `origin` is not ahead.\n  Later, `make release-examples` and `make release-plugins` push those preparation commits together\n  with the release commits and tags.\n\n## Version Selection\n\nDetermine the target version before changing any repository:\n\n1. Read `MAJOR`, `MINOR`, and `BUILD` from the Goa `Makefile`.\n2. Confirm `MAJOR=3`.\n3. Inspect the commits and merged PRs since the previous release tag.\n4. Pick the semver bump:\n   - Minor when the release includes a user-visible feature, new DSL/runtime capability, or\n     backward-compatible public API addition.\n   - Patch when the release only includes fixes, dependency updates, docs, tests, or internal\n     maintenance.\n5. Tell the user the selected target version and the specific changes that justify it, then ask for\n   confirmation. If the user supplied an explicit version, validate it against the same reasoning and\n   call out any mismatch before continuing.\n6. Use the exact confirmed target version for every preparation commit, tag check, and release\n   command.\n\n## Preview Release Contract\n\nUse this workflow only when the confirmed version ends in `-preview.N`.\n\n- Work from the reviewed feature branch. Do not switch to or move the stable `v3` branch.\n- Publish Goa only. Do not update, tag, or push the examples and plugins repositories.\n- Keep the stable README badge and stable `@latest` installation instructions unchanged.\n- Make the preview public only after the upgrade guide describes every known source, design, wire,\n  deployment, and rollback effect in plain English.\n- Treat `prepare-preview` and `release-preview` as separate approval points. The first creates the\n  version commit. The second creates and pushes the public tag.\n- Never run `make release` with `PREVIEW_NUMBER` set. That target is the stable multi-repository\n  release and deliberately rejects preview versions.\n\n### Prepare a preview\n\n1. Confirm the complete version, such as `v3.31.0-preview.1`.\n2. Fetch `origin`, verify the feature branch contains the latest stable branch, and verify the\n   working tree is clean. Preserve and report any existing local changes.\n3. Verify the exact preview tag is absent locally and on `origin`.\n4. Read `UPGRADING.md` against the current diff. Confirm it tells application and plugin authors\n   how to install, regenerate, migrate, deploy, roll back, and report a problem.\n5. Run:\n\n   ```bash\n   make prepare-preview MINOR=31 BUILD=0 PREVIEW_NUMBER=1\n   ```\n\n   The target runs the full preflight, updates the Makefile version and `pkg/version.go`, verifies\n   the command reports the preview version, and creates the exact preparation commit. It does not\n   create or push a tag.\n\n6. Push the feature branch through the normal review workflow and wait for every required check.\n7. Review the complete diff and GitHub release notes one final time.\n\n### Publish a preview\n\n1. Inventory the current branch, commit, local tag, and remote branch and tag.\n2. Get explicit maintainer approval to publish the exact preview tag.\n3. Run `make release-preview` and watch it until it exits. The target reruns the full preflight,\n   verifies the current commit is already on the same remote feature branch, creates the tag, and\n   pushes only the tag.\n4. If the command fails after creating the local tag, inspect local and remote state before any\n   rerun. Never delete a public tag or force-push without an approved recovery plan.\n5. Create a GitHub release for the tag with `--prerelease`. Link `UPGRADING.md`, describe the\n   preview as opt-in, and explain that the final stable minor version follows compatibility review.\n6. Verify the Go proxy resolves the exact preview version and that `@latest` still resolves the\n   current stable release.\n\n## Required Repositories\n\nBefore release, verify these repositories exist, are on the expected branches, are clean, and are\nin sync with their upstreams:\n\n- Goa: current repository, expected branch `v3`.\n- Examples: `$(go env GOPATH)/src/goa.design/examples`, expected branch `main`.\n- Plugins: `$(go env GOPATH)/src/goa.design/plugins`, expected branch `v3`.\n\nFor each repository:\n\n1. Run `git status --porcelain` and stop if there are uncommitted changes.\n2. Verify the current branch is the expected branch. If not, ask before switching branches.\n3. Run `git fetch origin`.\n4. Verify `git rev-list --left-right --count @{u}...HEAD` reports `0 0`. If behind, run\n   `git pull --ff-only`. If ahead or diverged, stop and ask.\n5. Verify the target tag does not already exist locally or on `origin`.\n\n## Preparation Workflow\n\n1. In the Goa repository, read `UPGRADING.md` against the diff since the previous release tag.\n   Retitle it to the target version, replace every `(unreleased)` section marker with a\n   `v3.x.y:` heading, add a `v3.x.y: upgrade order and rollback` summary when the range needs\n   one, update the installation commands and the official plugins version to the target, and fix\n   the README links and paragraph that describe the current release. Merge those edits through a\n   normal pull request before creating any preparation commit; `make release` does not update\n   this guide.\n2. In the Goa repository, run `make`. Fix failures before continuing.\n3. In the Goa repository, run:\n\n   ```bash\n   go get -u -v ./...\n   go mod tidy\n   (cd jsonrpc/integration_tests && go get -u -v ./... && go mod tidy)\n   make\n   ```\n\n   The JSON-RPC integration tests are a nested Go module; update and tidy it before rerunning\n   `make` so `integration-test` does not fail on stale module metadata. `go get` should only update\n   `go.mod` and `go.sum`. If other files changed in any repository, review why before committing.\n\n4. In the examples repository, run:\n\n   ```bash\n   go list -m -f '{{if .Main}}{{.Dir}}{{end}}' all | while IFS= read -r mod; do\n     [ -n \"$mod\" ] && (cd \"$mod\" && go get -u -v ./... && go mod tidy)\n   done\n   make\n   ```\n\n   The examples repository has no root `go.mod`; each example listed in `go.work` owns its own\n   module. Update and tidy every example module before running `make`. If files changed, commit them\n   with `Prepare v3.x.y`. Do not push; `make release-examples` pushes the branch.\n\n5. In the plugins repository, run:\n\n   ```bash\n   go get -u -v ./...\n   go mod tidy\n   make\n   ```\n\n   If files changed, commit them with `Prepare v3.x.y`. Do not push; `make release-plugins`\n   pushes the branch.\n\n6. In the Goa repository, edit only `MINOR`, `BUILD`, and the preview marker in `Makefile` for the\n   target version. Leave `MAJOR=3`. For a stable release, `PREVIEW_NUMBER` must be empty. The stable\n   release target clears the suffix in `pkg/version.go`; do not edit that generated version value\n   by hand.\n7. If Goa files changed from dependency updates or the version bump, commit them with\n   `Prepare v3.x.y`.\n8. Re-check all three repositories are clean. They may be ahead of upstream by their preparation\n   commits; that is expected because `make release` pushes them.\n\n## Final Pre-Release Check\n\n`make release` runs its own clean checks and release preflight, but those checks happen inside a\ncommand that can create commits, tags, and pushes. Before running it:\n\n1. In all three repositories, run `git fetch origin`.\n2. Verify `git status --porcelain` is empty.\n3. Verify upstream is not ahead: the first number from\n   `git rev-list --left-right --count @{u}...HEAD` must be `0`. Local-ahead preparation commits are\n   expected.\n4. Do not push the local-ahead preparation commits. `make release` will push them together with the\n   release commits.\n5. Reconfirm the target version and that the target tag is absent locally and on `origin` in all\n   three repositories.\n\n## Run And Babysit Release\n\n1. From the Goa repository, run `make release`.\n2. Watch the command until it exits. Track which phase is running: `release-goa`,\n   `release-examples`, or `release-plugins`.\n3. If it fails, stop and inspect the failing repository before rerunning anything. Do not blindly\n   rerun the whole release after a tag or push may have succeeded.\n4. Before any rerun, inventory local and remote branches and tags for `v3.x.y` in all three\n   repositories. Never recreate an existing tag, delete a public tag, or force-push unless the user\n   explicitly approves the recovery plan.\n5. Fix the root cause, verify the affected repository is in the expected state, then rerun the\n   narrowest safe target or command.\n6. When release completes, report the released version and the branch/tag pushes that succeeded.\n\n## GitHub Release Notes\n\nAfter `make release` succeeds, create GitHub release notes for the Goa tag.\n\n1. Gather the final commit/PR list from the previous Goa tag to the new tag. Include merged PR\n   numbers, titles, authors, and any notable dependency or downstream examples/plugins release work.\n2. Identify every human contributor in that range from commit authors and PR authors. Do not miss\n   contributors whose commits were merged by someone else. Exclude bots from the thank-you list\n   unless their work is directly meaningful to users.\n3. Write notes that are clear and useful to someone who does not know Goa internals:\n   - Start with a short plain-language summary of why the release matters.\n   - Use sections only when the amount of change justifies them, such as `Highlights`, `Fixes`,\n     `Dependencies`, `Upgrade Notes`, and `Contributors`.\n   - Explain user impact before implementation detail. Avoid raw commit-log dumps.\n   - Include upgrade notes only for actions users may need to take.\n   - Thank every contributor by name or handle.\n4. Create or update the GitHub release for `v3.x.y` with the final notes. Do not mention agent or AI\n   tooling in public release notes.\n\n## Announcements\n\nAfter GitHub release notes are ready, draft announcements for Slack, Bluesky, and Substack. Make\nthem exciting and delightful by showing what the release helps users do, not by adding hype.\n\nVoice rules:\n\n- Lead with the most concrete user payoff.\n- Use warm, crisp language with one or two memorable details from the release.\n- Avoid empty hype, forced jokes, excessive exclamation marks, launch cliches, and insider-only\n  wording.\n- Keep contributor thanks visible and sincere.\n\nChannel guidance:\n\n- Slack: 2-4 short paragraphs or bullets. Sound like a maintainer sharing good news with the\n  community. Lead with the most useful user-facing change, link to the GitHub release, and thank\n  contributors.\n- Bluesky: Posts are limited to 300 graphemes. Stay under that limit, include the version, one\n  concrete highlight, and a release link. Make the line feel polished enough to repost.\n- Substack: Write a short note for readers who may not know Goa deeply. Use a friendly title, a\n  brief explanation of Goa, a user-centered story for the release highlights, upgrade guidance if\n  any, and contributor thanks. Keep it proportional to the release size.\n",".cursor/skills/goa-release/SKILL.md":"---\nname: goa-release\ndescription: Release Goa v3, including preflight tests, dependency updates, semver version bumps, release preparation commits, examples/plugins repo checks, and babysitting make release. Use when the user asks to release Goa, prepare a Goa release, bump the Goa version, or run make release.\n---\n\n# Goa Release\n\nUse this skill only from the Goa repository. A stable release and an opt-in preview are separate\nworkflows. `make release` pushes branches and tags for Goa, examples, and plugins. A preview tags\nGoa alone from a reviewed feature branch. Do not run either publishing command unless the user\nexplicitly approves that exact release.\n\n## Release Contract\n\n- Goa major version is always `3`. Never increment `MAJOR`; if it is not `3`, stop and ask.\n- Resolve the target version before making dependency-update commits in any repository. The agent\n  should pick the version from the changes, explain the reasoning, and get confirmation before\n  editing files or running dependency updates.\n- Apply semver within v3:\n  - Patch release: increment `BUILD`.\n  - Minor release: increment `MINOR` and reset `BUILD=0`.\n- An opt-in preview uses `v3.MINOR.BUILD-preview.NUMBER`. Its version is a testing label, not a\n  promise of the final stable minor version. The major version remains 3.\n- The preparation commit message must be exactly `Prepare v3.x.y`, where `x` is `MINOR` and `y`\n  is `BUILD`.\n- The preview preparation commit message must be exactly `Prepare v3.x.y-preview.n`.\n- Keep the working trees clean between phases. Never discard local changes unless the user\n  explicitly approves it.\n- Do not push preparation commits manually. `make release-goa` runs `git pull origin <branch>` in\n  examples and plugins; local-ahead preparation commits are fine as long as `origin` is not ahead.\n  Later, `make release-examples` and `make release-plugins` push those preparation commits together\n  with the release commits and tags.\n\n## Version Selection\n\nDetermine the target version before changing any repository:\n\n1. Read `MAJOR`, `MINOR`, and `BUILD` from the Goa `Makefile`.\n2. Confirm `MAJOR=3`.\n3. Inspect the commits and merged PRs since the previous release tag.\n4. Pick the semver bump:\n   - Minor when the release includes a user-visible feature, new DSL/runtime capability, or\n     backward-compatible public API addition.\n   - Patch when the release only includes fixes, dependency updates, docs, tests, or internal\n     maintenance.\n5. Tell the user the selected target version and the specific changes that justify it, then ask for\n   confirmation. If the user supplied an explicit version, validate it against the same reasoning and\n   call out any mismatch before continuing.\n6. Use the exact confirmed target version for every preparation commit, tag check, and release\n   command.\n\n## Preview Release Contract\n\nUse this workflow only when the confirmed version ends in `-preview.N`.\n\n- Work from the reviewed feature branch. Do not switch to or move the stable `v3` branch.\n- Publish Goa only. Do not update, tag, or push the examples and plugins repositories.\n- Keep the stable README badge and stable `@latest` installation instructions unchanged.\n- Make the preview public only after the upgrade guide describes every known source, design, wire,\n  deployment, and rollback effect in plain English.\n- Treat `prepare-preview` and `release-preview` as separate approval points. The first creates the\n  version commit. The second creates and pushes the public tag.\n- Never run `make release` with `PREVIEW_NUMBER` set. That target is the stable multi-repository\n  release and deliberately rejects preview versions.\n\n### Prepare a preview\n\n1. Confirm the complete version, such as `v3.31.0-preview.1`.\n2. Fetch `origin`, verify the feature branch contains the latest stable branch, and verify the\n   working tree is clean. Preserve and report any existing local changes.\n3. Verify the exact preview tag is absent locally and on `origin`.\n4. Read `UPGRADING.md` against the current diff. Confirm it tells application and plugin authors\n   how to install, regenerate, migrate, deploy, roll back, and report a problem.\n5. Run:\n\n   ```bash\n   make prepare-preview MINOR=31 BUILD=0 PREVIEW_NUMBER=1\n   ```\n\n   The target runs the full preflight, updates the Makefile version and `pkg/version.go`, verifies\n   the command reports the preview version, and creates the exact preparation commit. It does not\n   create or push a tag.\n\n6. Push the feature branch through the normal review workflow and wait for every required check.\n7. Review the complete diff and GitHub release notes one final time.\n\n### Publish a preview\n\n1. Inventory the current branch, commit, local tag, and remote branch and tag.\n2. Get explicit maintainer approval to publish the exact preview tag.\n3. Run `make release-preview` and watch it until it exits. The target reruns the full preflight,\n   verifies the current commit is already on the same remote feature branch, creates the tag, and\n   pushes only the tag.\n4. If the command fails after creating the local tag, inspect local and remote state before any\n   rerun. Never delete a public tag or force-push without an approved recovery plan.\n5. Create a GitHub release for the tag with `--prerelease`. Link `UPGRADING.md`, describe the\n   preview as opt-in, and explain that the final stable minor version follows compatibility review.\n6. Verify the Go proxy resolves the exact preview version and that `@latest` still resolves the\n   current stable release.\n\n## Required Repositories\n\nBefore release, verify these repositories exist, are on the expected branches, are clean, and are\nin sync with their upstreams:\n\n- Goa: current repository, expected branch `v3`.\n- Examples: `$(go env GOPATH)/src/goa.design/examples`, expected branch `main`.\n- Plugins: `$(go env GOPATH)/src/goa.design/plugins`, expected branch `v3`.\n\nFor each repository:\n\n1. Run `git status --porcelain` and stop if there are uncommitted changes.\n2. Verify the current branch is the expected branch. If not, ask before switching branches.\n3. Run `git fetch origin`.\n4. Verify `git rev-list --left-right --count @{u}...HEAD` reports `0 0`. If behind, run\n   `git pull --ff-only`. If ahead or diverged, stop and ask.\n5. Verify the target tag does not already exist locally or on `origin`.\n\n## Preparation Workflow\n\n1. In the Goa repository, read `UPGRADING.md` against the diff since the previous release tag.\n   Retitle it to the target version, replace every `(unreleased)` section marker with a\n   `v3.x.y:` heading, add a `v3.x.y: upgrade order and rollback` summary when the range needs\n   one, update the installation commands and the official plugins version to the target, and fix\n   the README links and paragraph that describe the current release. Merge those edits through a\n   normal pull request before creating any preparation commit; `make release` does not update\n   this guide.\n2. In the Goa repository, run `make`. Fix failures before continuing.\n3. In the Goa repository, run:\n\n   ```bash\n   go get -u -v ./...\n   go mod tidy\n   (cd jsonrpc/integration_tests && go get -u -v ./... && go mod tidy)\n   make\n   ```\n\n   The JSON-RPC integration tests are a nested Go module; update and tidy it before rerunning\n   `make` so `integration-test` does not fail on stale module metadata. `go get` should only update\n   `go.mod` and `go.sum`. If other files changed in any repository, review why before committing.\n\n4. In the examples repository, run:\n\n   ```bash\n   go list -m -f '{{if .Main}}{{.Dir}}{{end}}' all | while IFS= read -r mod; do\n     [ -n \"$mod\" ] && (cd \"$mod\" && go get -u -v ./... && go mod tidy)\n   done\n   make\n   ```\n\n   The examples repository has no root `go.mod`; each example listed in `go.work` owns its own\n   module. Update and tidy every example module before running `make`. If files changed, commit them\n   with `Prepare v3.x.y`. Do not push; `make release-examples` pushes the branch.\n\n5. In the plugins repository, run:\n\n   ```bash\n   go get -u -v ./...\n   go mod tidy\n   make\n   ```\n\n   If files changed, commit them with `Prepare v3.x.y`. Do not push; `make release-plugins`\n   pushes the branch.\n\n6. In the Goa repository, edit only `MINOR`, `BUILD`, and the preview marker in `Makefile` for the\n   target version. Leave `MAJOR=3`. For a stable release, `PREVIEW_NUMBER` must be empty. The stable\n   release target clears the suffix in `pkg/version.go`; do not edit that generated version value\n   by hand.\n7. If Goa files changed from dependency updates or the version bump, commit them with\n   `Prepare v3.x.y`.\n8. Re-check all three repositories are clean. They may be ahead of upstream by their preparation\n   commits; that is expected because `make release` pushes them.\n\n## Final Pre-Release Check\n\n`make release` runs its own clean checks and release preflight, but those checks happen inside a\ncommand that can create commits, tags, and pushes. Before running it:\n\n1. In all three repositories, run `git fetch origin`.\n2. Verify `git status --porcelain` is empty.\n3. Verify upstream is not ahead: the first number from\n   `git rev-list --left-right --count @{u}...HEAD` must be `0`. Local-ahead preparation commits are\n   expected.\n4. Do not push the local-ahead preparation commits. `make release` will push them together with the\n   release commits.\n5. Reconfirm the target version and that the target tag is absent locally and on `origin` in all\n   three repositories.\n\n## Run And Babysit Release\n\n1. From the Goa repository, run `make release`.\n2. Watch the command until it exits. Track which phase is running: `release-goa` (including\n   `warm-proxy`, which waits for `gopkg.in` to expose the new tag and warms `proxy.golang.org` and\n   `sum.golang.org` by commit hash before querying the tag), `release-examples`, or\n   `release-plugins`.\n3. If it fails, stop and inspect the failing repository before rerunning anything. Do not blindly\n   rerun the whole release after a tag or push may have succeeded.\n4. Before any rerun, inventory local and remote branches and tags for `v3.x.y` in all three\n   repositories. Never recreate an existing tag, delete a public tag, or force-push unless the user\n   explicitly approves the recovery plan.\n5. Fix the root cause, verify the affected repository is in the expected state, then rerun the\n   narrowest safe target or command.\n6. When release completes, report the released version and the branch/tag pushes that succeeded.\n\n## GitHub Release Notes\n\nAfter `make release` succeeds, create GitHub release notes for the Goa tag.\n\n1. Gather the final commit/PR list from the previous Goa tag to the new tag. Include merged PR\n   numbers, titles, authors, and any notable dependency or downstream examples/plugins release work.\n2. Identify every human contributor in that range from commit authors and PR authors. Do not miss\n   contributors whose commits were merged by someone else. Exclude bots from the thank-you list\n   unless their work is directly meaningful to users.\n3. Write notes that are clear and useful to someone who does not know Goa internals:\n   - Start with a short plain-language summary of why the release matters.\n   - Use sections only when the amount of change justifies them, such as `Highlights`, `Fixes`,\n     `Dependencies`, `Upgrade Notes`, and `Contributors`.\n   - Explain user impact before implementation detail. Avoid raw commit-log dumps.\n   - Include upgrade notes only for actions users may need to take.\n   - Thank every contributor by name or handle.\n4. Create or update the GitHub release for `v3.x.y` with the final notes. Do not mention agent or AI\n   tooling in public release notes.\n\n## Announcements\n\nAfter GitHub release notes are ready, draft announcements for Slack, Bluesky, and Substack. Make\nthem exciting and delightful by showing what the release helps users do, not by adding hype.\n\nVoice rules:\n\n- Lead with the most concrete user payoff.\n- Use warm, crisp language with one or two memorable details from the release.\n- Avoid empty hype, forced jokes, excessive exclamation marks, launch cliches, and insider-only\n  wording.\n- Keep contributor thanks visible and sincere.\n\nChannel guidance:\n\n- Slack: 2-4 short paragraphs or bullets. Sound like a maintainer sharing good news with the\n  community. Lead with the most useful user-facing change, link to the GitHub release, and thank\n  contributors.\n- Bluesky: Posts are limited to 300 graphemes. Stay under that limit, include the version, one\n  concrete highlight, and a release link. Make the line feel polished enough to repost.\n- Substack: Write a short note for readers who may not know Goa deeply. Use a friendly title, a\n  brief explanation of Goa, a user-centered story for the release highlights, upgrade guidance if\n  any, and contributor thanks. Keep it proportional to the release size.\n","AGENTS.md":"# Repository Guidelines\n\n## Common Rules\n\n### Agent Behavior\n\n- **Plan before acting**: For ≤2 files, state a brief plan then implement. For ≥3 files, write a step-by-step plan first.\n- **Read before editing**: Always read files before modifying. Search over guessing.\n- **Fix root causes**: Do not produce local workarounds—fix the real issue.\n- **Be concise**: Give short status updates during multi-step work. Present a short summary when done.\n\n### Go Code Style\n\n- **Go 1.26+**. Format with `go fmt ./...`.\n- **Imports**: Group stdlib separate from external. Let gofmt manage ordering.\n- **Files**: Use `lower_snake_case.go`. Keep ≤1000 lines; split proactively.\n- **Naming**: Packages are lowercase and short. Exported identifiers need GoDoc. Avoid stutter.\n- **Types**: Use `any` over `interface{}`. Prefer concrete types over `interface{}`.\n- **Errors**: Wrap with `%w`. Use `errors.Is/As`. **Never ignore errors or use `_ = call()`**.\n- **Signatures**: Keep on one line when ≤100 columns. Only wrap genuinely long signatures.\n- **Slice/map nil**: Do not check nil before `len`. `len(nil)` returns 0. Use `len(x) == 0` directly.\n\n### Code Blocks and Literals\n\n- Always place a newline after `{` and before `}` for `if`, `for`, `switch`, `func`, `type`.\n- No single-line blocks: `if cond { do() }` → use multiple lines.\n- Short struct literals are fine inline: `&T{A: 1}`. Break long literals to one field per line with trailing commas.\n\n### File Organization\n\nOrder declarations as:\n1. Types (public, then private) in a single `type (...)` block when practical\n2. Constants (public, then private)\n3. Variables (public, then private)\n4. Public functions\n5. Public methods\n6. Private functions\n7. Private methods\n\nNo commented-out code—delete dead code.\n\n### Error Handling & Contracts\n\n- **Always check errors**. Never discard with `_`.\n- **Strong contracts**: Goa validates payloads at boundaries. Do not re-validate inside service code.\n- **No defensive programming**: Do not add nil/empty guards for values guaranteed by construction, Goa, or prior validation.\n- **Validate only at boundaries**: HTTP/gRPC handlers, event consumers, DB results, third-party APIs, `ctx.Value()`, type assertions, required map lookups.\n- **Fail fast**: Unexpected states are bugs. Return precise errors or panic—do not silently recover or skip.\n\n### Goa DSL Rules\n\n- **Never edit `gen/`**: Always regenerate.\n- **DSL validation**: Put validations (lengths, enums, formats) in the design. Do not re-validate in code.\n- **Avoid `Any`**: Use concrete types to enable gRPC generation.\n\n### Codegen Implementation\n\n- **Critical — finish work during generation**: Use the complete design, generation plan,\n  and Go templates to decide everything that is known before the generated\n  program runs. Select branches, names, types, imports, field paths, helper\n  calls, and emitted files while generating source. Templates must write only\n  the selected code. Do not make generated programs inspect generated type\n  shapes, parse generator-made names, carry generator mode flags, or execute\n  branches whose answer was already known. Runtime code should contain only\n  logic that depends on actual runtime values. When a runtime value is truly\n  required, keep that input narrow and specialize all surrounding code during\n  generation.\n- **Use NameScope helpers** for type references: `GoTypeRef`, `GoFullTypeRef`, `GoTypeName`. Never concatenate strings for types.\n- Let Goa decide pointer/value semantics. Do not force `pointer=true` except in transport validation.\n- **Keep helper visibility minimal**: If logic is shared only inside one codegen area, keep it package-private or move it under an `internal` package. Do not export helpers from a parent package just to share them across sibling generators.\n- **Avoid pass-through wrappers**: When two helper functions differ only by forwarding arguments or hard-coding `nil`, collapse them into a single implementation instead of adding an extra layer.\n- **Generated packages own names**: When several services or plugins write to\n  one Go package, collect every package-level name before rendering and then\n  make those names final. A declaration and every HTTP, gRPC, or JSON-RPC use\n  of it must read the same name record. Do not give each service or plugin a\n  separate name scope for the same package, and do not add declarations after\n  names become final.\n- **Keep identity typed and explicit**: Do not hide a declaration's kind,\n  package, or use in a decorated name or a made-up string map key. Do not\n  change an expression's `Hash` behavior to solve a generation problem. Pass a\n  typed identifier where the generated declaration is named.\n- **Trace the complete lifecycle**: Before changing relocated types, union\n  naming, generation roots, plugins, or file merging, follow the declaration\n  from the evaluated design through service analysis, its generated Go\n  package, the emitted service code, HTTP and gRPC uses, plugin changes, and\n  the final file merge. A service-only rendering test is not enough.\n  See [`codegen/ARCHITECTURE.md`](codegen/ARCHITECTURE.md).\n\n### Documentation\n\n- Every exported type, function, method, and field must have a GoDoc comment explaining its contract—like Go stdlib documentation.\n\n### Safety & Forbidden Operations\n\n| Action | Policy |\n|--------|--------|\n| `git clean/stash/reset/checkout` | **FORBIDDEN** |\n| `go clean -cache` | **FORBIDDEN** during normal work |\n| Edit `gen/` directly | **FORBIDDEN** |\n| Changes ≥3 files | Describe plan first |\n| New dependencies | Explain why first |\n\n### Testing\n\n- Write table-driven tests in `*_test.go`.\n- Name tests `TestXxx`. Keep fast and deterministic.\n- Use `testify/require` for assertions.\n- Prefer `t.Errorf` over `t.Fatalf` so tests report multiple failures.\n\n---\n\n## Goa-Specific Rules\n\n### Project Structure\n\n- `dsl/`: Public DSL definitions (dot imports allowed per `.golangci.yml`)\n- `expr/`: Internal AST and validation\n- `codegen/`: Generators for transports, types, docs\n- `http/`, `grpc/`, `jsonrpc/`: Transport-specific codegen\n- `middleware/`: Built-in interceptors\n- `pkg/`: Core runtime\n- `cmd/goa/`: CLI source\n\n### Build & Test\n\n```bash\nmake lint          # Run linters\nmake test          # Run tests\ncd cmd/goa && go install .  # Install CLI locally\n```\n\n### Releases\n\n- For every Goa release or version bump, follow\n  [`.cursor/skills/goa-release/SKILL.md`](.cursor/skills/goa-release/SKILL.md).\n- Do not edit `pkg/version.go` or the README version badge by hand during the standard release\n  workflow; `make release` owns those changes.\n\n### Code Generation Behavior\n\n- After modifying goa source, `goa gen` and `goa example` automatically compile and use your changes—no manual rebuild needed.\n- `goa gen` deletes and recreates the entire `gen/` directory.\n- `goa example` only creates new files; it does not overwrite existing `cmd/` files.\n\n### Repro Protocol\n\nTo reproduce a codegen issue:\n1. Create `~/src/repros/<issue>/design/design.go`\n2. `go mod init <issue>` in the issue directory\n3. `goa gen <issue>/design`\n4. `go mod tidy`\n5. `go mod edit -replace goa.design/goa/v3=$HOME/src/goa`\n6. `goa gen <issue>/design` again with local goa\n7. Optional: `goa example <issue>/design`\n\n### Slices/Maps and Required Fields\n\nDo not rely on nil versus empty slices or maps to encode domain meaning.\nRequired JSON fields may contain empty collections unless a length constraint\nforbids them; keep `Required` when the JSON property must be present. Protobuf\nrepeated and map fields cannot distinguish absent from empty, so their generated\nvalidation checks length and contents, not presence. Message, scalar, and oneof\npresence checks remain independent of collection emptiness.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/goadesign/goa/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Repository Guidelines\n\n## Common Rules\n\n### Agent Behavior\n\n- **Plan before acting**: For ≤2 files, state a brief plan then implement. For ≥3 files, write a step-by-step plan first.\n- **Read before editing**: Always read files before modifying. Search over guessing.\n- **Fix root causes**: Do not produce local workarounds—fix the real issue.\n- **Be concise**: Give short status updates during multi-step work. Present a short summary when done.\n\n### Go Code Style\n\n- **Go 1.26+**. Format with `go fmt ./...`.\n- **Imports**: Group stdlib separate from external. Let gofmt manage ordering.\n- **Files**: Use `lower_snake_case.go`. Keep ≤1000 lines; split proactively.\n- **Naming**: Packages are lowercase and short. Exported identifiers need GoDoc. Avoid stutter.\n- **Types**: Use `any` over `interface{}`. Prefer concrete types over `interface{}`.\n- **Errors**: Wrap with `%w`. Use `errors.Is/As`. **Never ignore errors or use `_ = call()`**.\n- **Signatures**: Keep on one line when ≤100 columns. Only wrap genuinely long signatures.\n- **Slice/map nil**: Do not check nil before `len`. `len(nil)` returns 0. Use `len(x) == 0` directly.\n\n### Code Blocks and Literals\n\n- Always place a newline after `{` and before `}` for `if`, `for`, `switch`, `func`, `type`.\n- No single-line blocks: `if cond { do() }` → use multiple lines.\n- Short struct literals are fine inline: `&T{A: 1}`. Break long literals to one field per line with trailing commas.\n\n### File Organization\n\nOrder declarations as:\n1. Types (public, then private) in a single `type (...)` block when practical\n2. Constants (public, then private)\n3. Variables (public, then private)\n4. Public functions\n5. Public methods\n6. Private functions\n7. Private methods\n\nNo commented-out code—delete dead code.\n\n### Error Handling & Contracts\n\n- **Always check errors**. Never discard with `_`.\n- **Strong contracts**: Goa validates payloads at boundaries. Do not re-validate inside service code.\n- **No defensive programming**: Do not add nil/empty guards for values guaranteed by construction, Goa, or prior validation.\n- **Validate only at boundaries**: HTTP/gRPC handlers, event consumers, DB results, third-party APIs, `ctx.Value()`, type assertions, required map lookups.\n- **Fail fast**: Unexpected states are bugs. Return precise errors or panic—do not silently recover or skip.\n\n### Goa DSL Rules\n\n- **Never edit `gen/`**: Always regenerate.\n- **DSL validation**: Put validations (lengths, enums, formats) in the design. Do not re-validate in code.\n- **Avoid `Any`**: Use concrete types to enable gRPC generation.\n\n### Codegen Implementation\n\n- **Critical — finish work during generation**: Use the complete design, generation plan,\n  and Go templates to decide everything that is known before the generated\n  program runs. Select branches, names, types, imports, field paths, helper\n  calls, and emitted files while generating source. Templates must write only\n  the selected code. Do not make generated programs inspect generated type\n  shapes, parse generator-made names, carry generator mode flags, or execute\n  branches whose answer was already known. Runtime code should contain only\n  logic that depends on actual runtime values. When a runtime value is truly\n  required, keep that input narrow and specialize all surrounding code during\n  generation.\n- **Use NameScope helpers** for type references: `GoTypeRef`, `GoFullTypeRef`, `GoTypeName`. Never concatenate strings for types.\n- Let Goa decide pointer/value semantics. Do not force `pointer=true` except in transport validation.\n- **Keep helper visibility minimal**: If logic is shared only inside one codegen area, keep it package-private or move it under an `internal` package. Do not export helpers from a parent package just to share them across sibling generators.\n- **Avoid pass-through wrappers**: When two helper functions differ only by forwarding arguments or hard-coding `nil`, collapse them into a single implementation instead of adding an extra layer.\n- **Generated packages own names**: When several services or plugins write to\n  one Go package, collect every package-level name before rendering and then\n  make those names final. A declaration and every HTTP, gRPC, or JSON-RPC use\n  of it must read the same name record. Do not give each service or plugin a\n  separate name scope for the same package, and do not add declarations after\n  names become final.\n- **Keep identity typed and explicit**: Do not hide a declaration's kind,\n  package, or use in a decorated name or a made-up string map key. Do not\n  change an expression's `Hash` behavior to solve a generation problem. Pass a\n  typed identifier where the generated declaration is named.\n- **Trace the complete lifecycle**: Before changing relocated types, union\n  naming, generation roots, plugins, or file merging, follow the declaration\n  from the evaluated design through service analysis, its generated Go\n  package, the emitted service code, HTTP and gRPC uses, plugin changes, and\n  the final file merge. A service-only rendering test is not enough.\n  See [`codegen/ARCHITECTURE.md`](codegen/ARCHITECTURE.md).\n\n### Documentation\n\n- Every exported type, function, method, and field must have a GoDoc comment explaining its contract—like Go stdlib documentation.\n\n### Safety & Forbidden Operations\n\n| Action | Policy |\n|--------|--------|\n| `git clean/stash/reset/checkout` | **FORBIDDEN** |\n| `go clean -cache` | **FORBIDDEN** during normal work |\n| Edit `gen/` directly | **FORBIDDEN** |\n| Changes ≥3 files | Describe plan first |\n| New dependencies | Explain why first |\n\n### Testing\n\n- Write table-driven tests in `*_test.go`.\n- Name tests `TestXxx`. Keep fast and deterministic.\n- Use `testify/require` for assertions.\n- Prefer `t.Errorf` over `t.Fatalf` so tests report multiple failures.\n\n---\n\n## Goa-Specific Rules\n\n### Project Structure\n\n- `dsl/`: Public DSL definitions (dot imports allowed per `.golangci.yml`)\n- `expr/`: Internal AST and validation\n- `codegen/`: Generators for transports, types, docs\n- `http/`, `grpc/`, `jsonrpc/`: Transport-specific codegen\n- `middleware/`: Built-in interceptors\n- `pkg/`: Core runtime\n- `cmd/goa/`: CLI source\n\n### Build & Test\n\n```bash\nmake lint          # Run linters\nmake test          # Run tests\ncd cmd/goa && go install .  # Install CLI locally\n```\n\n### Releases\n\n- For every Goa release or version bump, follow\n  [`.cursor/skills/goa-release/SKILL.md`](.cursor/skills/goa-release/SKILL.md).\n- Do not edit `pkg/version.go` or the README version badge by hand during the standard release\n  workflow; `make release` owns those changes.\n\n### Code Generation Behavior\n\n- After modifying goa source, `goa gen` and `goa example` automatically compile and use your changes—no manual rebuild needed.\n- `goa gen` deletes and recreates the entire `gen/` directory.\n- `goa example` only creates new files; it does not overwrite existing `cmd/` files.\n\n### Repro Protocol\n\nTo reproduce a codegen issue:\n1. Create `~/src/repros/<issue>/design/design.go`\n2. `go mod init <issue>` in the issue directory\n3. `goa gen <issue>/design`\n4. `go mod tidy`\n5. `go mod edit -replace goa.design/goa/v3=$HOME/src/goa`\n6. `goa gen <issue>/design` again with local goa\n7. Optional: `goa example <issue>/design`\n\n### Slices/Maps and Required Fields\n\nDo not rely on nil versus empty slices or maps to encode domain meaning.\nRequired JSON fields may contain empty collections unless a length constraint\nforbids them; keep `Required` when the JSON property must be present. Protobuf\nrepeated and map fields cannot distinguish absent from empty, so their generated\nvalidation checks length and contents, not presence. Message, scalar, and oneof\npresence checks remain independent of collection emptiness.\n","isInternal":false,"tokens":1818,"sizeBytes":7753},{"name":"SKILL.md","path":".claude/skills/goa-release/SKILL.md","rawUrl":"https://raw.githubusercontent.com/goadesign/goa/HEAD/.claude/skills/goa-release/SKILL.md","title":"goa-release","category":"anthropic-skill","format":"markdown","content":"---\nname: goa-release\ndescription: Release Goa v3, including preflight tests, dependency updates, semver version bumps, release preparation commits, examples/plugins repo checks, and babysitting make release. Use when the user asks to release Goa, prepare a Goa release, bump the Goa version, or run make release.\n---\n\n# Goa Release\n\nUse this skill only from the Goa repository. A stable release and an opt-in preview are separate\nworkflows. `make release` pushes branches and tags for Goa, examples, and plugins. A preview tags\nGoa alone from a reviewed feature branch. Do not run either publishing command unless the user\nexplicitly approves that exact release.\n\n## Release Contract\n\n- Goa major version is always `3`. Never increment `MAJOR`; if it is not `3`, stop and ask.\n- Resolve the target version before making dependency-update commits in any repository. The agent\n  should pick the version from the changes, explain the reasoning, and get confirmation before\n  editing files or running dependency updates.\n- Apply semver within v3:\n  - Patch release: increment `BUILD`.\n  - Minor release: increment `MINOR` and reset `BUILD=0`.\n- An opt-in preview uses `v3.MINOR.BUILD-preview.NUMBER`. Its version is a testing label, not a\n  promise of the final stable minor version. The major version remains 3.\n- The preparation commit message must be exactly `Prepare v3.x.y`, where `x` is `MINOR` and `y`\n  is `BUILD`.\n- The preview preparation commit message must be exactly `Prepare v3.x.y-preview.n`.\n- Keep the working trees clean between phases. Never discard local changes unless the user\n  explicitly approves it.\n- Do not push preparation commits manually. `make release-goa` runs `git pull origin <branch>` in\n  examples and plugins; local-ahead preparation commits are fine as long as `origin` is not ahead.\n  Later, `make release-examples` and `make release-plugins` push those preparation commits together\n  with the release commits and tags.\n\n## Version Selection\n\nDetermine the target version before changing any repository:\n\n1. Read `MAJOR`, `MINOR`, and `BUILD` from the Goa `Makefile`.\n2. Confirm `MAJOR=3`.\n3. Inspect the commits and merged PRs since the previous release tag.\n4. Pick the semver bump:\n   - Minor when the release includes a user-visible feature, new DSL/runtime capability, or\n     backward-compatible public API addition.\n   - Patch when the release only includes fixes, dependency updates, docs, tests, or internal\n     maintenance.\n5. Tell the user the selected target version and the specific changes that justify it, then ask for\n   confirmation. If the user supplied an explicit version, validate it against the same reasoning and\n   call out any mismatch before continuing.\n6. Use the exact confirmed target version for every preparation commit, tag check, and release\n   command.\n\n## Preview Release Contract\n\nUse this workflow only when the confirmed version ends in `-preview.N`.\n\n- Work from the reviewed feature branch. Do not switch to or move the stable `v3` branch.\n- Publish Goa only. Do not update, tag, or push the examples and plugins repositories.\n- Keep the stable README badge and stable `@latest` installation instructions unchanged.\n- Make the preview public only after the upgrade guide describes every known source, design, wire,\n  deployment, and rollback effect in plain English.\n- Treat `prepare-preview` and `release-preview` as separate approval points. The first creates the\n  version commit. The second creates and pushes the public tag.\n- Never run `make release` with `PREVIEW_NUMBER` set. That target is the stable multi-repository\n  release and deliberately rejects preview versions.\n\n### Prepare a preview\n\n1. Confirm the complete version, such as `v3.31.0-preview.1`.\n2. Fetch `origin`, verify the feature branch contains the latest stable branch, and verify the\n   working tree is clean. Preserve and report any existing local changes.\n3. Verify the exact preview tag is absent locally and on `origin`.\n4. Read `UPGRADING.md` against the current diff. Confirm it tells application and plugin authors\n   how to install, regenerate, migrate, deploy, roll back, and report a problem.\n5. Run:\n\n   ```bash\n   make prepare-preview MINOR=31 BUILD=0 PREVIEW_NUMBER=1\n   ```\n\n   The target runs the full preflight, updates the Makefile version and `pkg/version.go`, verifies\n   the command reports the preview version, and creates the exact preparation commit. It does not\n   create or push a tag.\n\n6. Push the feature branch through the normal review workflow and wait for every required check.\n7. Review the complete diff and GitHub release notes one final time.\n\n### Publish a preview\n\n1. Inventory the current branch, commit, local tag, and remote branch and tag.\n2. Get explicit maintainer approval to publish the exact preview tag.\n3. Run `make release-preview` and watch it until it exits. The target reruns the full preflight,\n   verifies the current commit is already on the same remote feature branch, creates the tag, and\n   pushes only the tag.\n4. If the command fails after creating the local tag, inspect local and remote state before any\n   rerun. Never delete a public tag or force-push without an approved recovery plan.\n5. Create a GitHub release for the tag with `--prerelease`. Link `UPGRADING.md`, describe the\n   preview as opt-in, and explain that the final stable minor version follows compatibility review.\n6. Verify the Go proxy resolves the exact preview version and that `@latest` still resolves the\n   current stable release.\n\n## Required Repositories\n\nBefore release, verify these repositories exist, are on the expected branches, are clean, and are\nin sync with their upstreams:\n\n- Goa: current repository, expected branch `v3`.\n- Examples: `$(go env GOPATH)/src/goa.design/examples`, expected branch `main`.\n- Plugins: `$(go env GOPATH)/src/goa.design/plugins`, expected branch `v3`.\n\nFor each repository:\n\n1. Run `git status --porcelain` and stop if there are uncommitted changes.\n2. Verify the current branch is the expected branch. If not, ask before switching branches.\n3. Run `git fetch origin`.\n4. Verify `git rev-list --left-right --count @{u}...HEAD` reports `0 0`. If behind, run\n   `git pull --ff-only`. If ahead or diverged, stop and ask.\n5. Verify the target tag does not already exist locally or on `origin`.\n\n## Preparation Workflow\n\n1. In the Goa repository, read `UPGRADING.md` against the diff since the previous release tag.\n   Retitle it to the target version, replace every `(unreleased)` section marker with a\n   `v3.x.y:` heading, add a `v3.x.y: upgrade order and rollback` summary when the range needs\n   one, update the installation commands and the official plugins version to the target, and fix\n   the README links and paragraph that describe the current release. Merge those edits through a\n   normal pull request before creating any preparation commit; `make release` does not update\n   this guide.\n2. In the Goa repository, run `make`. Fix failures before continuing.\n3. In the Goa repository, run:\n\n   ```bash\n   go get -u -v ./...\n   go mod tidy\n   (cd jsonrpc/integration_tests && go get -u -v ./... && go mod tidy)\n   make\n   ```\n\n   The JSON-RPC integration tests are a nested Go module; update and tidy it before rerunning\n   `make` so `integration-test` does not fail on stale module metadata. `go get` should only update\n   `go.mod` and `go.sum`. If other files changed in any repository, review why before committing.\n\n4. In the examples repository, run:\n\n   ```bash\n   go list -m -f '{{if .Main}}{{.Dir}}{{end}}' all | while IFS= read -r mod; do\n     [ -n \"$mod\" ] && (cd \"$mod\" && go get -u -v ./... && go mod tidy)\n   done\n   make\n   ```\n\n   The examples repository has no root `go.mod`; each example listed in `go.work` owns its own\n   module. Update and tidy every example module before running `make`. If files changed, commit them\n   with `Prepare v3.x.y`. Do not push; `make release-examples` pushes the branch.\n\n5. In the plugins repository, run:\n\n   ```bash\n   go get -u -v ./...\n   go mod tidy\n   make\n   ```\n\n   If files changed, commit them with `Prepare v3.x.y`. Do not push; `make release-plugins`\n   pushes the branch.\n\n6. In the Goa repository, edit only `MINOR`, `BUILD`, and the preview marker in `Makefile` for the\n   target version. Leave `MAJOR=3`. For a stable release, `PREVIEW_NUMBER` must be empty. The stable\n   release target clears the suffix in `pkg/version.go`; do not edit that generated version value\n   by hand.\n7. If Goa files changed from dependency updates or the version bump, commit them with\n   `Prepare v3.x.y`.\n8. Re-check all three repositories are clean. They may be ahead of upstream by their preparation\n   commits; that is expected because `make release` pushes them.\n\n## Final Pre-Release Check\n\n`make release` runs its own clean checks and release preflight, but those checks happen inside a\ncommand that can create commits, tags, and pushes. Before running it:\n\n1. In all three repositories, run `git fetch origin`.\n2. Verify `git status --porcelain` is empty.\n3. Verify upstream is not ahead: the first number from\n   `git rev-list --left-right --count @{u}...HEAD` must be `0`. Local-ahead preparation commits are\n   expected.\n4. Do not push the local-ahead preparation commits. `make release` will push them together with the\n   release commits.\n5. Reconfirm the target version and that the target tag is absent locally and on `origin` in all\n   three repositories.\n\n## Run And Babysit Release\n\n1. From the Goa repository, run `make release`.\n2. Watch the command until it exits. Track which phase is running: `release-goa`,\n   `release-examples`, or `release-plugins`.\n3. If it fails, stop and inspect the failing repository before rerunning anything. Do not blindly\n   rerun the whole release after a tag or push may have succeeded.\n4. Before any rerun, inventory local and remote branches and tags for `v3.x.y` in all three\n   repositories. Never recreate an existing tag, delete a public tag, or force-push unless the user\n   explicitly approves the recovery plan.\n5. Fix the root cause, verify the affected repository is in the expected state, then rerun the\n   narrowest safe target or command.\n6. When release completes, report the released version and the branch/tag pushes that succeeded.\n\n## GitHub Release Notes\n\nAfter `make release` succeeds, create GitHub release notes for the Goa tag.\n\n1. Gather the final commit/PR list from the previous Goa tag to the new tag. Include merged PR\n   numbers, titles, authors, and any notable dependency or downstream examples/plugins release work.\n2. Identify every human contributor in that range from commit authors and PR authors. Do not miss\n   contributors whose commits were merged by someone else. Exclude bots from the thank-you list\n   unless their work is directly meaningful to users.\n3. Write notes that are clear and useful to someone who does not know Goa internals:\n   - Start with a short plain-language summary of why the release matters.\n   - Use sections only when the amount of change justifies them, such as `Highlights`, `Fixes`,\n     `Dependencies`, `Upgrade Notes`, and `Contributors`.\n   - Explain user impact before implementation detail. Avoid raw commit-log dumps.\n   - Include upgrade notes only for actions users may need to take.\n   - Thank every contributor by name or handle.\n4. Create or update the GitHub release for `v3.x.y` with the final notes. Do not mention agent or AI\n   tooling in public release notes.\n\n## Announcements\n\nAfter GitHub release notes are ready, draft announcements for Slack, Bluesky, and Substack. Make\nthem exciting and delightful by showing what the release helps users do, not by adding hype.\n\nVoice rules:\n\n- Lead with the most concrete user payoff.\n- Use warm, crisp language with one or two memorable details from the release.\n- Avoid empty hype, forced jokes, excessive exclamation marks, launch cliches, and insider-only\n  wording.\n- Keep contributor thanks visible and sincere.\n\nChannel guidance:\n\n- Slack: 2-4 short paragraphs or bullets. Sound like a maintainer sharing good news with the\n  community. Lead with the most useful user-facing change, link to the GitHub release, and thank\n  contributors.\n- Bluesky: Posts are limited to 300 graphemes. Stay under that limit, include the version, one\n  concrete highlight, and a release link. Make the line feel polished enough to repost.\n- Substack: Write a short note for readers who may not know Goa deeply. Use a friendly title, a\n  brief explanation of Goa, a user-centered story for the release highlights, upgrade guidance if\n  any, and contributor thanks. Keep it proportional to the release size.\n","frontmatter":{"name":"goa-release","description":"Release Goa v3, including preflight tests, dependency updates, semver version bumps, release preparation commits, examples/plugins repo checks, and babysitting make release. Use when the user asks to release Goa, prepare a Goa release, bump the Goa version, or run make release."},"isInternal":false,"tokens":2897,"sizeBytes":12662},{"name":"SKILL.md","path":".cursor/skills/goa-release/SKILL.md","rawUrl":"https://raw.githubusercontent.com/goadesign/goa/HEAD/.cursor/skills/goa-release/SKILL.md","title":"goa-release","category":"anthropic-skill","format":"markdown","content":"---\nname: goa-release\ndescription: Release Goa v3, including preflight tests, dependency updates, semver version bumps, release preparation commits, examples/plugins repo checks, and babysitting make release. Use when the user asks to release Goa, prepare a Goa release, bump the Goa version, or run make release.\n---\n\n# Goa Release\n\nUse this skill only from the Goa repository. A stable release and an opt-in preview are separate\nworkflows. `make release` pushes branches and tags for Goa, examples, and plugins. A preview tags\nGoa alone from a reviewed feature branch. Do not run either publishing command unless the user\nexplicitly approves that exact release.\n\n## Release Contract\n\n- Goa major version is always `3`. Never increment `MAJOR`; if it is not `3`, stop and ask.\n- Resolve the target version before making dependency-update commits in any repository. The agent\n  should pick the version from the changes, explain the reasoning, and get confirmation before\n  editing files or running dependency updates.\n- Apply semver within v3:\n  - Patch release: increment `BUILD`.\n  - Minor release: increment `MINOR` and reset `BUILD=0`.\n- An opt-in preview uses `v3.MINOR.BUILD-preview.NUMBER`. Its version is a testing label, not a\n  promise of the final stable minor version. The major version remains 3.\n- The preparation commit message must be exactly `Prepare v3.x.y`, where `x` is `MINOR` and `y`\n  is `BUILD`.\n- The preview preparation commit message must be exactly `Prepare v3.x.y-preview.n`.\n- Keep the working trees clean between phases. Never discard local changes unless the user\n  explicitly approves it.\n- Do not push preparation commits manually. `make release-goa` runs `git pull origin <branch>` in\n  examples and plugins; local-ahead preparation commits are fine as long as `origin` is not ahead.\n  Later, `make release-examples` and `make release-plugins` push those preparation commits together\n  with the release commits and tags.\n\n## Version Selection\n\nDetermine the target version before changing any repository:\n\n1. Read `MAJOR`, `MINOR`, and `BUILD` from the Goa `Makefile`.\n2. Confirm `MAJOR=3`.\n3. Inspect the commits and merged PRs since the previous release tag.\n4. Pick the semver bump:\n   - Minor when the release includes a user-visible feature, new DSL/runtime capability, or\n     backward-compatible public API addition.\n   - Patch when the release only includes fixes, dependency updates, docs, tests, or internal\n     maintenance.\n5. Tell the user the selected target version and the specific changes that justify it, then ask for\n   confirmation. If the user supplied an explicit version, validate it against the same reasoning and\n   call out any mismatch before continuing.\n6. Use the exact confirmed target version for every preparation commit, tag check, and release\n   command.\n\n## Preview Release Contract\n\nUse this workflow only when the confirmed version ends in `-preview.N`.\n\n- Work from the reviewed feature branch. Do not switch to or move the stable `v3` branch.\n- Publish Goa only. Do not update, tag, or push the examples and plugins repositories.\n- Keep the stable README badge and stable `@latest` installation instructions unchanged.\n- Make the preview public only after the upgrade guide describes every known source, design, wire,\n  deployment, and rollback effect in plain English.\n- Treat `prepare-preview` and `release-preview` as separate approval points. The first creates the\n  version commit. The second creates and pushes the public tag.\n- Never run `make release` with `PREVIEW_NUMBER` set. That target is the stable multi-repository\n  release and deliberately rejects preview versions.\n\n### Prepare a preview\n\n1. Confirm the complete version, such as `v3.31.0-preview.1`.\n2. Fetch `origin`, verify the feature branch contains the latest stable branch, and verify the\n   working tree is clean. Preserve and report any existing local changes.\n3. Verify the exact preview tag is absent locally and on `origin`.\n4. Read `UPGRADING.md` against the current diff. Confirm it tells application and plugin authors\n   how to install, regenerate, migrate, deploy, roll back, and report a problem.\n5. Run:\n\n   ```bash\n   make prepare-preview MINOR=31 BUILD=0 PREVIEW_NUMBER=1\n   ```\n\n   The target runs the full preflight, updates the Makefile version and `pkg/version.go`, verifies\n   the command reports the preview version, and creates the exact preparation commit. It does not\n   create or push a tag.\n\n6. Push the feature branch through the normal review workflow and wait for every required check.\n7. Review the complete diff and GitHub release notes one final time.\n\n### Publish a preview\n\n1. Inventory the current branch, commit, local tag, and remote branch and tag.\n2. Get explicit maintainer approval to publish the exact preview tag.\n3. Run `make release-preview` and watch it until it exits. The target reruns the full preflight,\n   verifies the current commit is already on the same remote feature branch, creates the tag, and\n   pushes only the tag.\n4. If the command fails after creating the local tag, inspect local and remote state before any\n   rerun. Never delete a public tag or force-push without an approved recovery plan.\n5. Create a GitHub release for the tag with `--prerelease`. Link `UPGRADING.md`, describe the\n   preview as opt-in, and explain that the final stable minor version follows compatibility review.\n6. Verify the Go proxy resolves the exact preview version and that `@latest` still resolves the\n   current stable release.\n\n## Required Repositories\n\nBefore release, verify these repositories exist, are on the expected branches, are clean, and are\nin sync with their upstreams:\n\n- Goa: current repository, expected branch `v3`.\n- Examples: `$(go env GOPATH)/src/goa.design/examples`, expected branch `main`.\n- Plugins: `$(go env GOPATH)/src/goa.design/plugins`, expected branch `v3`.\n\nFor each repository:\n\n1. Run `git status --porcelain` and stop if there are uncommitted changes.\n2. Verify the current branch is the expected branch. If not, ask before switching branches.\n3. Run `git fetch origin`.\n4. Verify `git rev-list --left-right --count @{u}...HEAD` reports `0 0`. If behind, run\n   `git pull --ff-only`. If ahead or diverged, stop and ask.\n5. Verify the target tag does not already exist locally or on `origin`.\n\n## Preparation Workflow\n\n1. In the Goa repository, read `UPGRADING.md` against the diff since the previous release tag.\n   Retitle it to the target version, replace every `(unreleased)` section marker with a\n   `v3.x.y:` heading, add a `v3.x.y: upgrade order and rollback` summary when the range needs\n   one, update the installation commands and the official plugins version to the target, and fix\n   the README links and paragraph that describe the current release. Merge those edits through a\n   normal pull request before creating any preparation commit; `make release` does not update\n   this guide.\n2. In the Goa repository, run `make`. Fix failures before continuing.\n3. In the Goa repository, run:\n\n   ```bash\n   go get -u -v ./...\n   go mod tidy\n   (cd jsonrpc/integration_tests && go get -u -v ./... && go mod tidy)\n   make\n   ```\n\n   The JSON-RPC integration tests are a nested Go module; update and tidy it before rerunning\n   `make` so `integration-test` does not fail on stale module metadata. `go get` should only update\n   `go.mod` and `go.sum`. If other files changed in any repository, review why before committing.\n\n4. In the examples repository, run:\n\n   ```bash\n   go list -m -f '{{if .Main}}{{.Dir}}{{end}}' all | while IFS= read -r mod; do\n     [ -n \"$mod\" ] && (cd \"$mod\" && go get -u -v ./... && go mod tidy)\n   done\n   make\n   ```\n\n   The examples repository has no root `go.mod`; each example listed in `go.work` owns its own\n   module. Update and tidy every example module before running `make`. If files changed, commit them\n   with `Prepare v3.x.y`. Do not push; `make release-examples` pushes the branch.\n\n5. In the plugins repository, run:\n\n   ```bash\n   go get -u -v ./...\n   go mod tidy\n   make\n   ```\n\n   If files changed, commit them with `Prepare v3.x.y`. Do not push; `make release-plugins`\n   pushes the branch.\n\n6. In the Goa repository, edit only `MINOR`, `BUILD`, and the preview marker in `Makefile` for the\n   target version. Leave `MAJOR=3`. For a stable release, `PREVIEW_NUMBER` must be empty. The stable\n   release target clears the suffix in `pkg/version.go`; do not edit that generated version value\n   by hand.\n7. If Goa files changed from dependency updates or the version bump, commit them with\n   `Prepare v3.x.y`.\n8. Re-check all three repositories are clean. They may be ahead of upstream by their preparation\n   commits; that is expected because `make release` pushes them.\n\n## Final Pre-Release Check\n\n`make release` runs its own clean checks and release preflight, but those checks happen inside a\ncommand that can create commits, tags, and pushes. Before running it:\n\n1. In all three repositories, run `git fetch origin`.\n2. Verify `git status --porcelain` is empty.\n3. Verify upstream is not ahead: the first number from\n   `git rev-list --left-right --count @{u}...HEAD` must be `0`. Local-ahead preparation commits are\n   expected.\n4. Do not push the local-ahead preparation commits. `make release` will push them together with the\n   release commits.\n5. Reconfirm the target version and that the target tag is absent locally and on `origin` in all\n   three repositories.\n\n## Run And Babysit Release\n\n1. From the Goa repository, run `make release`.\n2. Watch the command until it exits. Track which phase is running: `release-goa` (including\n   `warm-proxy`, which waits for `gopkg.in` to expose the new tag and warms `proxy.golang.org` and\n   `sum.golang.org` by commit hash before querying the tag), `release-examples`, or\n   `release-plugins`.\n3. If it fails, stop and inspect the failing repository before rerunning anything. Do not blindly\n   rerun the whole release after a tag or push may have succeeded.\n4. Before any rerun, inventory local and remote branches and tags for `v3.x.y` in all three\n   repositories. Never recreate an existing tag, delete a public tag, or force-push unless the user\n   explicitly approves the recovery plan.\n5. Fix the root cause, verify the affected repository is in the expected state, then rerun the\n   narrowest safe target or command.\n6. When release completes, report the released version and the branch/tag pushes that succeeded.\n\n## GitHub Release Notes\n\nAfter `make release` succeeds, create GitHub release notes for the Goa tag.\n\n1. Gather the final commit/PR list from the previous Goa tag to the new tag. Include merged PR\n   numbers, titles, authors, and any notable dependency or downstream examples/plugins release work.\n2. Identify every human contributor in that range from commit authors and PR authors. Do not miss\n   contributors whose commits were merged by someone else. Exclude bots from the thank-you list\n   unless their work is directly meaningful to users.\n3. Write notes that are clear and useful to someone who does not know Goa internals:\n   - Start with a short plain-language summary of why the release matters.\n   - Use sections only when the amount of change justifies them, such as `Highlights`, `Fixes`,\n     `Dependencies`, `Upgrade Notes`, and `Contributors`.\n   - Explain user impact before implementation detail. Avoid raw commit-log dumps.\n   - Include upgrade notes only for actions users may need to take.\n   - Thank every contributor by name or handle.\n4. Create or update the GitHub release for `v3.x.y` with the final notes. Do not mention agent or AI\n   tooling in public release notes.\n\n## Announcements\n\nAfter GitHub release notes are ready, draft announcements for Slack, Bluesky, and Substack. Make\nthem exciting and delightful by showing what the release helps users do, not by adding hype.\n\nVoice rules:\n\n- Lead with the most concrete user payoff.\n- Use warm, crisp language with one or two memorable details from the release.\n- Avoid empty hype, forced jokes, excessive exclamation marks, launch cliches, and insider-only\n  wording.\n- Keep contributor thanks visible and sincere.\n\nChannel guidance:\n\n- Slack: 2-4 short paragraphs or bullets. Sound like a maintainer sharing good news with the\n  community. Lead with the most useful user-facing change, link to the GitHub release, and thank\n  contributors.\n- Bluesky: Posts are limited to 300 graphemes. Stay under that limit, include the version, one\n  concrete highlight, and a release link. Make the line feel polished enough to repost.\n- Substack: Write a short note for readers who may not know Goa deeply. Use a friendly title, a\n  brief explanation of Goa, a user-centered story for the release highlights, upgrade guidance if\n  any, and contributor thanks. Keep it proportional to the release size.\n","frontmatter":{"name":"goa-release","description":"Release Goa v3, including preflight tests, dependency updates, semver version bumps, release preparation commits, examples/plugins repo checks, and babysitting make release. Use when the user asks to release Goa, prepare a Goa release, bump the Goa version, or run make release."},"isInternal":false,"tokens":2946,"sizeBytes":12832},{"name":"transport-errors-interceptors.md","path":"skills/goa-service-designer/references/transport-errors-interceptors.md","rawUrl":"https://raw.githubusercontent.com/goadesign/goa/HEAD/skills/goa-service-designer/references/transport-errors-interceptors.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Transport, Errors, And Interceptors\n\nUse this reference when changing HTTP, gRPC, or JSON-RPC mappings, streaming, errors, security,\ninterceptors, middleware, or production wiring. The gRPC presence and JSON-RPC behavior below\ndescribes Goa v3.31 and later. Check the application's selected module version and its\n`UPGRADING.md` before changing older code.\n\n## HTTP Mapping\n\n- Use resource nouns, plural names, stable hierarchy, and HTTP methods for actions.\n- Put stable prefixes in API-level or service-level `HTTP(Path(...))`.\n- Use `Parent` and `CanonicalMethod` only when nested resources become clearer.\n- Map path, query, header, and body fields deliberately with `Param`, `Header`, and `Body`.\n- Use explicit wire-name mapping when attribute names differ from HTTP element names.\n- Choose status codes intentionally. Use `StatusCreated` for creates when appropriate.\n- Use default content negotiation unless a real media type requires custom encoders or decoders.\n- Use the CORS plugin for browser-facing cross-origin policy.\n- Use `Files` only for HTTP static content.\n\nHTTP object payload checks:\n\n- Every path token must map to a payload field.\n- Every non-body attribute should land where intended.\n- Use `Body(\"field\")` only when the request body should be that field's raw value.\n- Unmapped object attributes are encoded in the body.\n\n```go\nHTTP(func() {\n    GET(\"/accounts/{account_id}/items\")\n    Param(\"accountId:account_id\")\n    Param(\"limit\")\n    Response(StatusOK)\n    Response(\"not_found\", StatusNotFound)\n})\n```\n\n## Streaming\n\nGoa's streaming DSL is transport-agnostic. The transport mapping determines HTTP behavior:\n\n- Plain HTTP streaming defaults to WebSocket.\n- Add `ServerSentEvents()` only for one-way server-to-client streams.\n- WebSocket endpoints use `GET`.\n- For gRPC streaming, check generated protobuf and server/client stream types.\n- JSON-RPC supports unary calls or a single request followed by an\n  explicit SSE stream. It rejects client or bidirectional streaming, WebSocket streams, and a\n  method combining `Result` with `StreamingResult`. Ordinary HTTP WebSocket support is separate.\n- Streaming implementations must handle flow control, `io.EOF`, send errors, context cancellation,\n  timeouts, and cleanup.\n\n## gRPC Mapping\n\n- Set package and version metadata for public or versioned APIs.\n- Keep domain data in messages.\n- Use metadata, headers, and trailers only for protocol metadata.\n- Use streaming for large or continuous datasets.\n- Never renumber released `Field` values.\n- Check `.proto` output after changing shared types, streaming methods, or custom protobuf metadata.\n- Required singular scalars preserve protobuf presence. An omitted required\n  boolean is invalid; an explicitly supplied `false` can be valid. Generated decoders validate\n  before converting to service values. See the modeling reference for collections and defaults.\n\n## JSON-RPC Mapping\n\n- Use service-level `JSONRPC` to configure the shared HTTP POST endpoint, and method-level\n  `JSONRPC` for method-specific behavior and error mappings.\n- Let generated code own the JSON-RPC envelope, dispatch, request IDs, batches, and protocol errors.\n  The payload describes `params`; do not handwrite transport envelopes in service code.\n- Ordinary generated client calls have an ID even without an `ID` payload field.\n  `Notification()` explicitly declares a one-way call. Having no result does not by itself make\n  a method a notification. Notifications cannot declare a result, ID field, or stream.\n- `ID` belongs directly in the payload, not the result. The transport returns the request ID;\n  the service does not choose a response ID.\n- Map designed errors with JSON-RPC `Response` codes. Verify the generated error `data` shape\n  before changing a custom client's decoding.\n- For SSE, pair `StreamingResult` with method-level `ServerSentEvents()`. Verify event field\n  mappings and cancellation through the generated client and server.\n\n## Errors\n\n- Define reusable potential errors at API scope when you want one canonical error type/name and one\n  transport mapping. API-level `Error(...)` declarations do not make those errors applicable to\n  every endpoint. Select a reusable definition with `Error(\"name\")` at service or method scope.\n- Define an error at service scope only when every method on that service can return it.\n- Define an error at method scope when only that method can return it.\n- Do not promote a method-specific error to service scope just to avoid repeating a declaration or to\n  make generated constructors easier to reach; the design would falsely advertise that all service\n  methods can return it.\n- Use descriptive names and descriptions.\n- Prefer `ErrorResult` for most errors.\n- Add `Temporary()`, `Timeout()`, or `Fault()` when clients should behave differently.\n- Use custom error types only when clients need structured context.\n- If multiple custom errors can return from the same method, include a field marked with\n  `Meta(\"struct:error:name\")`.\n- Map every exposed error for each enabled transport with `HTTP(Response(...))` and\n  `GRPC(Response(...))`, or the corresponding `JSONRPC(Response(...))`.\n- In implementation code, return generated error constructors or generated custom error payloads.\n- Wrap underlying causes for logs and tracing, but keep client-facing messages safe.\n- Test errors through the service API. Verify generated error names, transport status mappings when\n  practical, and custom error payloads.\n\n## Security\n\n- Declare security schemes, required scopes, and credential fields in the design.\n- Prefer API-level defaults.\n- Override at service or method scope when needed.\n- Use `NoSecurity()` explicitly for public methods.\n- Add matching security payload fields such as `TokenField` or `APIKeyField`.\n- Map credentials through HTTP headers/query parameters or gRPC metadata.\n- Implement the generated authentication callbacks and application authorization rules.\n  A scheme declaration does not verify a token or establish resource ownership by itself.\n\n## Goa Interceptors Vs Middleware\n\nUse Goa interceptors for type-safe domain concerns:\n\n- Business validation that is not boundary validation.\n- Request enrichment.\n- Response enrichment.\n- Auditing.\n- Domain-level transformations.\n\nUse HTTP middleware or gRPC interceptors for protocol concerns:\n\n- Logging.\n- Tracing.\n- CORS.\n- Compression.\n- Request IDs.\n- Rate limiting.\n- Panic recovery.\n- Wire-level metadata.\n\nGoa interceptors are generated endpoint wrappers, not transport middleware:\n\n- Server interceptors run after transport decoding and before the service method.\n- Client interceptors run around the typed client endpoint before transport encoding and after\n  transport decoding.\n- Use generated typed accessors.\n- Call `next` exactly once when continuing.\n- If order matters, inspect generated `Wrap<Method>Endpoint`; the last wrapper runs first on the\n  request path.\n\n## Observability\n\nFor production services, wire observability, health checks, timeouts, graceful shutdown, and\nconfiguration at application boundaries. Goa docs recommend Clue/OpenTelemetry. Use generated\n`ServiceName`, `APIVersion`, method names, endpoint wrappers, and interceptor metadata for stable\ntelemetry labels.\n","isInternal":false,"tokens":1479,"sizeBytes":7252},{"name":"SKILL.md","path":"skills/goa-service-designer/SKILL.md","rawUrl":"https://raw.githubusercontent.com/goadesign/goa/HEAD/skills/goa-service-designer/SKILL.md","title":"goa-service-designer","category":"anthropic-skill","format":"markdown","content":"---\nname: goa-service-designer\ndescription: Design and evolve Goa application services. Use for Goa DSL changes, HTTP/gRPC/JSON-RPC contracts, validation, errors, interceptors, code generation, and service implementation.\n---\n\n# Goa Service Designer\n\nUse this skill for applications and plugins that declare or consume Goa contracts. Repository\ninstructions govern implementation. For changes to Goa's own compiler, runtime, templates, or\ngenerators, use Goa's contributor workflow instead of the application workflow below; still use the\nreference and capability checks below when deciding what the DSL or generated transport supports.\n\nLet Goa generate the mechanical code. Use the relevant design and generated service interface as\nthe working context; inspect transport output when the task changes wire behavior. Implement the\napplication's decisions outside `gen/`.\n\n## Consult The Relevant Reference Before Designing\n\nRead the relevant reference before a non-trivial design or implementation decision. Do not wait\nuntil generation fails, and do not treat the links as optional background reading:\n\n- For HTTP, gRPC, or JSON-RPC mappings, streaming, errors, security, or interceptor behavior, read\n  [transport guidance](references/transport-errors-interceptors.md).\n- For named types, aliases, pointers, defaults, unions, views, or validation, read\n  [modeling guidance](references/modeling-and-validation.md).\n- For generated signatures, constructors, codecs, imports, or downstream implementation changes,\n  read [generated-code guidance](references/generated-code-and-implementation.md).\n- When observed output or behavior contradicts the design, also read\n  [troubleshooting](references/troubleshooting.md).\n\nBefore introducing a transport workaround or claiming that Goa cannot express a requirement:\n\n1. Check the existing DSL mechanism in the reference and the selected Goa version's source. For\n   example, `Param(\"attributeName:url_name\")` separates a payload field from its URL parameter name;\n   inspect that mapping before renaming path tokens or adding transport-only replacement fields.\n2. Trace the authored mapping through generated payloads, client encoding, server decoding, and\n   endpoint invocation. Distinguish the payload name, HTTP element name, and generated Go selector.\n3. Verify the disputed capability with a minimal authored design and generated client/server check\n   before editing its replacement. A reference states the intended contract; it does not prove the\n   selected generator implements it correctly. Keep a failing result and trace its owning layer\n   rather than assuming the DSL lacks the feature.\n\nReuse a working native mechanism. If it fails, explain the exact generator gap and why a change\nbelongs in Goa or the consuming plugin before implementing it. Read only the references relevant\nto the decision; routine mechanical edits do not require loading every reference.\n\n## Default Workflow\n\n1. Find the local design, generated service contract, implementation, generation wrapper, validation\n   commands, and affected consumers. Check the Goa version and any replacement in `go.mod`.\n2. Reuse established local patterns for routine edits. Consult goa.design when choosing an\n   unfamiliar feature, resolving uncertain DSL or generated behavior, or troubleshooting.\n   Read only the relevant section, using these topic routes:\n   - New project: [Quickstart](https://goa.design/docs/1-goa/quickstart/) and [Code Generation](https://goa.design/docs/1-goa/code-generation/).\n   - Types, validation, views, or unions: [DSL Reference](https://goa.design/docs/1-goa/dsl-reference/).\n   - HTTP mapping, WebSocket, or SSE: [HTTP Guide](https://goa.design/docs/1-goa/http-guide/).\n   - gRPC, protobuf tags, metadata, or streaming: [gRPC Guide](https://goa.design/docs/1-goa/grpc-guide/).\n   - JSON-RPC: [transport reference](references/transport-errors-interceptors.md#json-rpc-mapping) and the selected Goa version's `dsl.JSONRPC` documentation.\n   - Errors: [Error Handling](https://goa.design/docs/1-goa/error-handling/).\n   - Interceptors or middleware: [Interceptors](https://goa.design/docs/1-goa/interceptors/).\n   - Security or production wiring: [Production](https://goa.design/docs/1-goa/production/).\n   Online docs may describe a different release. For release-specific behavior and upgrades, use the\n   selected Goa checkout's `UPGRADING.md` and generated output. Use a page's Markdown version\n   when available; do not preload every guide or reference.\n3. State the intended contract change in one or two sentences.\n4. Edit the Goa design first.\n5. Regenerate with the project's wrapper. Without one, use\n   `go run goa.design/goa/v3/cmd/goa gen <design-package-import-path>` so the command uses the\n   application's selected module version. Never use `goa gen ./design`.\n6. Implement the generated interface outside `gen/`.\n7. Update only affected consumers: mocks, clients, docs, examples, API snapshots, OpenAPI/protobuf\n   consumers, command wiring, and project-specific SDKs generated from Goa output.\n8. Run the generation, lint, type-check, and test commands allowed by the repository instructions.\n   If a command is prohibited or too broad, state exactly what was not run.\n9. Review generated and hand-written diffs together. Every generated change should follow from\n   the design or an intentional tooling upgrade.\n\nUse `goa example <design-package-import-path>` when starter files are needed. It creates missing\napplication files and does not update existing files. Review new files and update existing wiring\nyourself; do not expect it to migrate an implementation.\n\n## Hard Rules\n\n- Treat the Goa design as the canonical contract. If payload shape, result shape, validation,\n  security, errors, transport mapping, documentation, OpenAPI, protobuf, generated clients, or CLIs\n  need to change, edit the design first and regenerate.\n- Never patch generated files, OpenAPI output, protobuf output, or generated clients to hide a stale\n  design.\n- Keep protobuf field numbers unique within the final message, including inherited fields.\n  Never renumber or reuse released field numbers to make a sequence contiguous.\n- Put boundary validation in Goa. Use `Required`, `Enum`, `Format`, `Pattern`, `Minimum`,\n  `Maximum`, `MinLength`, `MaxLength`, defaults, security fields, and explicit transport mappings in\n  the design.\n- Model error applicability at the narrowest correct Goa scope. API-level errors define reusable\n  potential errors and let transports map them once; they do not mean every endpoint returns every\n  API-level error. Service-level errors apply to all methods in that service. Method-level errors\n  apply only to that method. Do not list an error at service scope just to make a generated\n  constructor convenient if only some methods can return it.\n- In service code, trust payloads already validated by the generated transport and enforce business\n  invariants. Direct service or endpoint calls bypass transport decoding; their callers must supply\n  valid values or validate at their own input boundary. Do not add nil guards,\n  fallback behavior, silent recovery, blanket string trimming, or compatibility shims for values the\n  design guarantees.\n- Do not use nil versus empty slices or maps as domain meaning. `Required` and `MinLength` express\n  different constraints, and JSON and protobuf have different collection presence rules. See\n  [presence and collections](references/modeling-and-validation.md#presence-and-collections).\n- Preserve compatibility for shipped public APIs, persisted data, external SDKs, and documented\n  behavior. For internal-only contracts or unshipped branch work, update callers cleanly instead of\n  adding shims.\n\n## Design Conventions\n\nFollow the application's existing conventions and compatibility requirements. For new designs:\n\n- Prefix explicit generated-package aliases with `gen`, such as `genfront` or `genfrontgrpc`.\n- Prefer lower camel case for public HTTP fields and parameters (`accountId`) and snake case for\n  method names (`get_account`). Map established wire names explicitly, for example\n  `Header(\"tusResumable:Tus-Resumable\")`.\n- Use literal integer `Field` tags so wire identities are easy to review. Start a new standalone\n  definition at `1`. For an `Extend` definition, `100` can start a new range only if inherited fields\n  leave that range free. Inspect the complete inheritance chain and assign unused numbers; nested\n  `Extend` calls must not restart at an occupied `100`. Existing tags always keep their numbers.\n\nThese are authoring conventions, not requirements imposed by Goa.\n\n## What To Read Next\n\nUse the decision triggers above to select references; the details below describe their scope:\n\n- `references/modeling-and-validation.md`: type modeling, primitive aliases, required fields,\n  pointer/default semantics, views, presence, and compatibility.\n- `references/transport-errors-interceptors.md`: HTTP, gRPC, JSON-RPC, streaming, errors, security,\n  interceptors, middleware, and observability labels.\n- `references/generated-code-and-implementation.md`: generated diff triage, dirty worktrees,\n  implementation updates, downstream artifacts, and validation commands.\n- `references/troubleshooting.md`: generation failures, decode bugs, gRPC output surprises,\n  interceptor ordering, and common mini-patterns.\n\n## Final Review\n\nBefore finishing, verify:\n\n- The design remains the source of truth.\n- Generated code was regenerated, not edited.\n- Payloads, results, validation, security, errors, and transport mappings are explicit.\n- Service code trusts established validation boundaries and handles real dependency failures.\n- Compatibility choices are represented in the design and tests, not hidden in service fallbacks.\n- Affected downstream consumers are updated; unaffected artifacts are left alone.\n- New transport workarounds and capability claims have evidence from the native generated path.\n- Test coverage matches the risk of the contract change.\n","frontmatter":{"name":"goa-service-designer","description":"Design and evolve Goa application services. Use for Goa DSL changes, HTTP/gRPC/JSON-RPC contracts, validation, errors, interceptors, code generation, and service implementation."},"isInternal":false,"tokens":2062,"sizeBytes":10022},{"name":".cursorrules","path":".cursorrules","rawUrl":"https://raw.githubusercontent.com/goadesign/goa/HEAD/.cursorrules","title":"Cursor IDE Native Rules","category":"cursor-rule","format":"markdown","content":"# Goa repository rules for Cursor\n\n- Never edit generated code. Fix the generator/templates instead.\n- Prefer any over interface{} in new code.\n- Transports: HTTP, gRPC, and JSON-RPC 2.0 (HTTP, SSE, WebSocket). JSON-RPC supports batch and notifications; streaming over WS/SSE.\n- Testing:\n  - Run unit tests with `make test`.\n  - JSON-RPC integration tests live in `jsonrpc/integration_tests`; run with `make integration-test` (skips on Windows).\n  - Golden tests use testify; update with `go test -update` or `-u`.\n- Code style:\n  - Small, focused files; one main construct per file when possible.\n  - Public types first, then private types, public constants, private constants, public vars, private vars, public functions/methods, then private.\n  - Use `maps.Copy`/`slices.Contains`, `http.NoBody`, avoid shadowing builtins.\n- Architecture quick map:\n  - `dsl/` (design DSL), `expr/` (expressions), `codegen/` (generation engine & templates), `cmd/goa/` (CLI), `http/`, `grpc/`, `jsonrpc/` (transports), `pkg/`, `middleware/`, `security/`, `eval/`.\n- For deeper guidance, see `CLAUDE.md`.\n","isInternal":false,"tokens":288,"sizeBytes":1090},{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/goadesign/goa/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# CLAUDE.md\n\nRead @AGENTS.md","isInternal":false,"tokens":11,"sizeBytes":28}],"systemPromptSnippet":"<yakaai_skills repo=\"goadesign/goa\">\n<!-- File: AGENTS.md (Tokens: ~1818 | Category: root-instruction) -->\n# Repository Guidelines\n\n## Common Rules\n\n### Agent Behavior\n\n- **Plan before acting**: For ≤2 files, state a brief plan then implement. For ≥3 files, write a step-by-step plan first.\n- **Read before editing**: Always read files before modifying. Search over guessing.\n- **Fix root causes**: Do not produce local workarounds—fix the real issue.\n- **Be concise**: Give short status updates during multi-step work. Present a short summary when done.\n\n### Go Code Style\n\n- **Go 1.26+**. Format with `go fmt ./...`.\n- **Imports**: Group stdlib separate from external. Let gofmt manage ordering.\n- **Files**: Use `lower_snake_case.go`. Keep ≤1000 lines; split proactively.\n- **Naming**: Packages are lowercase and short. Exported identifiers need GoDoc. Avoid stutter.\n- **Types**: Use `any` over `interface{}`. Prefer concrete types over `interface{}`.\n- **Errors**: Wrap with `%w`. Use `errors.Is/As`. **Never ignore errors or use `_ = call()`**.\n- **Signatures**: Keep on one line when ≤100 columns. Only wrap genuinely long signatures.\n- **Slice/map nil**: Do not check nil before `len`. `len(nil)` returns 0. Use `len(x) == 0` directly.\n\n### Code Blocks and Literals\n\n- Always place a newline after `{` and before `}` for `if`, `for`, `switch`, `func`, `type`.\n- No single-line blocks: `if cond { do() }` → use multiple lines.\n- Short struct literals are fine inline: `&T{A: 1}`. Break long literals to one field per line with trailing commas.\n\n### File Organization\n\nOrder declarations as:\n1. Types (public, then private) in a single `type (...)` block when practical\n2. Constants (public, then private)\n3. Variables (public, then private)\n4. Public functions\n5. Public methods\n6. Private functions\n7. Private methods\n\nNo commented-out code—delete dead code.\n\n### Error Handling & Contracts\n\n- **Always check errors**. Never discard with `_`.\n- **Strong contracts**: Goa validates payloads at boundaries. Do not re-validate inside service code.\n- **No defensive programming**: Do not add nil/empty guards for values guaranteed by construction, Goa, or prior validation.\n- **Validate only at boundaries**: HTTP/gRPC handlers, event consumers, DB results, third-party APIs, `ctx.Value()`, type assertions, required map lookups.\n- **Fail fast**: Unexpected states are bugs. Return precise errors or panic—do not silently recover or skip.\n\n### Goa DSL Rules\n\n- **Never edit `gen/`**: Always regenerate.\n- **DSL validation**: Put validations (lengths, enums, formats) in the design. Do not re-validate in code.\n- **Avoid `Any`**: Use concrete types to enable gRPC generation.\n\n### Codegen Implementation\n\n- **Critical — finish work during generation**: Use the complete design, generation plan,\n  and Go templates to decide everything that is known before the generated\n  program runs. Select branches, names, types, imports, field paths, helper\n  calls, and emitted files while generating source. Templates must write only\n  the selected code. Do not make generated programs inspect generated type\n  shapes, parse generator-made names, carry generator mode flags, or execute\n  branches whose answer was already known. Runtime code should contain only\n  logic that depends on actual runtime values. When a runtime value is truly\n  required, keep that input narrow and specialize all surrounding code during\n  generation.\n- **Use NameScope helpers** for type references: `GoTypeRef`, `GoFullTypeRef`, `GoTypeName`. Never concatenate strings for types.\n- Let Goa decide pointer/value semantics. Do not force `pointer=true` except in transport validation.\n- **Keep helper visibility minimal**: If logic is shared only inside one codegen area, keep it package-private or move it under an `internal` package. Do not export helpers from a parent package just to share them across sibling generators.\n- **Avoid pass-through wrappers**: When two helper functions differ only by forwarding arguments or hard-coding `nil`, collapse them into a single implementation instead of adding an extra layer.\n- **Generated packages own names**: When several services or plugins write to\n  one Go package, collect every package-level name before rendering and then\n  make those names final. A declaration and every HTTP, gRPC, or JSON-RPC use\n  of it must read the same name record. Do not give each service or plugin a\n  separate name scope for the same package, and do not add declarations after\n  names become final.\n- **Keep identity typed and explicit**: Do not hide a declaration's kind,\n  package, or use in a decorated name or a made-up string map key. Do not\n  change an expression's `Hash` behavior to solve a generation problem. Pass a\n  typed identifier where the generated declaration is named.\n- **Trace the complete lifecycle**: Before changing relocated types, union\n  naming, generation roots, plugins, or file merging, follow the declaration\n  from the evaluated design through service analysis, its generated Go\n  package, the emitted service code, HTTP and gRPC uses, plugin changes, and\n  the final file merge. A service-only rendering test is not enough.\n  See [`codegen/ARCHITECTURE.md`](codegen/ARCHITECTURE.md).\n\n### Documentation\n\n- Every exported type, function, method, and field must have a GoDoc comment explaining its contract—like Go stdlib documentation.\n\n### Safety & Forbidden Operations\n\n| Action | Policy |\n|--------|--------|\n| `git clean/stash/reset/checkout` | **FORBIDDEN** |\n| `go clean -cache` | **FORBIDDEN** during normal work |\n| Edit `gen/` directly | **FORBIDDEN** |\n| Changes ≥3 files | Describe plan first |\n| New dependencies | Explain why first |\n\n### Testing\n\n- Write table-driven tests in `*_test.go`.\n- Name tests `TestXxx`. Keep fast and deterministic.\n- Use `testify/require` for assertions.\n- Prefer `t.Errorf` over `t.Fatalf` so tests report multiple failures.\n\n---\n\n## Goa-Specific Rules\n\n### Project Structure\n\n- `dsl/`: Public DSL definitions (dot imports allowed per `.golangci.yml`)\n- `expr/`: Internal AST and validation\n- `codegen/`: Generators for transports, types, docs\n- `http/`, `grpc/`, `jsonrpc/`: Transport-specific codegen\n- `middleware/`: Built-in interceptors\n- `pkg/`: Core runtime\n- `cmd/goa/`: CLI source\n\n### Build & Test\n\n```bash\nmake lint          # Run linters\nmake test          # Run tests\ncd cmd/goa && go install .  # Install CLI locally\n```\n\n### Releases\n\n- For every Goa release or version bump, follow\n  [`.cursor/skills/goa-release/SKILL.md`](.cursor/skills/goa-release/SKILL.md).\n- Do not edit `pkg/version.go` or the README version badge by hand during the standard release\n  workflow; `make release` owns those changes.\n\n### Code Generation Behavior\n\n- After modifying goa source, `goa gen` and `goa example` automatically compile and use your changes—no manual rebuild needed.\n- `goa gen` deletes and recreates the entire `gen/` directory.\n- `goa example` only creates new files; it does not overwrite existing `cmd/` files.\n\n### Repro Protocol\n\nTo reproduce a codegen issue:\n1. Create `~/src/repros/<issue>/design/design.go`\n2. `go mod init <issue>` in the issue directory\n3. `goa gen <issue>/design`\n4. `go mod tidy`\n5. `go mod edit -replace goa.design/goa/v3=$HOME/src/goa`\n6. `goa gen <issue>/design` again with local goa\n7. Optional: `goa example <issue>/design`\n\n### Slices/Maps and Required Fields\n\nDo not rely on nil versus empty slices or maps to encode domain meaning.\nRequired JSON fields may contain empty collections unless a length constraint\nforbids them; keep `Required` when the JSON property must be present. Protobuf\nrepeated and map fields cannot distinguish absent from empty, so their generated\nvalidation checks length and contents, not presence. Message, scalar, and oneof\npresence checks remain independent of collection emptiness.\n\n<!-- File: .claude/skills/goa-release/SKILL.md (Tokens: ~2897 | Category: anthropic-skill) -->\n---\nname: goa-release\ndescription: Release Goa v3, including preflight tests, dependency updates, semver version bumps, release preparation commits, examples/plugins repo checks, and babysitting make release. Use when the user asks to release Goa, prepare a Goa release, bump the Goa version, or run make release.\n---\n\n# Goa Release\n\nUse this skill only from the Goa repository. A stable release and an opt-in preview are separate\nworkflows. `make release` pushes branches and tags for Goa, examples, and plugins. A preview tags\nGoa alone from a reviewed feature branch. Do not run either publishing command unless the user\nexplicitly approves that exact release.\n\n## Release Contract\n\n- Goa major version is always `3`. Never increment `MAJOR`; if it is not `3`, stop and ask.\n- Resolve the target version before making dependency-update commits in any repository. The agent\n  should pick the version from the changes, explain the reasoning, and get confirmation before\n  editing files or running dependency updates.\n- Apply semver within v3:\n  - Patch release: increment `BUILD`.\n  - Minor release: increment `MINOR` and reset `BUILD=0`.\n- An opt-in preview uses `v3.MINOR.BUILD-preview.NUMBER`. Its version is a testing label, not a\n  promise of the final stable minor version. The major version remains 3.\n- The preparation commit message must be exactly `Prepare v3.x.y`, where `x` is `MINOR` and `y`\n  is `BUILD`.\n- The preview preparation commit message must be exactly `Prepare v3.x.y-preview.n`.\n- Keep the working trees clean between phases. Never discard local changes unless the user\n  explicitly approves it.\n- Do not push preparation commits manually. `make release-goa` runs `git pull origin <branch>` in\n  examples and plugins; local-ahead preparation commits are fine as long as `origin` is not ahead.\n  Later, `make release-examples` and `make release-plugins` push those preparation commits together\n  with the release commits and tags.\n\n## Version Selection\n\nDetermine the target version before changing any repository:\n\n1. Read `MAJOR`, `MINOR`, and `BUILD` from the Goa `Makefile`.\n2. Confirm `MAJOR=3`.\n3. Inspect the commits and merged PRs since the previous release tag.\n4. Pick the semver bump:\n   - Minor when the release includes a user-visible feature, new DSL/runtime capability, or\n     backward-compatible public API addition.\n   - Patch when the release only includes fixes, dependency updates, docs, tests, or internal\n     maintenance.\n5. Tell the user the selected target version and the specific changes that justify it, then ask for\n   confirmation. If the user supplied an explicit version, validate it against the same reasoning and\n   call out any mismatch before continuing.\n6. Use the exact confirmed target version for every preparation commit, tag check, and release\n   command.\n\n## Preview Release Contract\n\nUse this workflow only when the confirmed version ends in `-preview.N`.\n\n- Work from the reviewed feature branch. Do not switch to or move the stable `v3` branch.\n- Publish Goa only. Do not update, tag, or push the examples and plugins repositories.\n- Keep the stable README badge and stable `@latest` installation instructions unchanged.\n- Make the preview public only after the upgrade guide describes every known source, design, wire,\n  deployment, and rollback effect in plain English.\n- Treat `prepare-preview` and `release-preview` as separate approval points. The first creates the\n  version commit. The second creates and pushes the public tag.\n- Never run `make release` with `PREVIEW_NUMBER` set. That target is the stable multi-repository\n  release and deliberately rejects preview versions.\n\n### Prepare a preview\n\n1. Confirm the complete version, such as `v3.31.0-preview.1`.\n2. Fetch `origin`, verify the feature branch contains the latest stable branch, and verify the\n   working tree is clean. Preserve and report any existing local changes.\n3. Verify the exact preview tag is absent locally and on `origin`.\n4. Read `UPGRADING.md` against the current diff. Confirm it tells application and plugin authors\n   how to install, regenerate, migrate, deploy, roll back, and report a problem.\n5. Run:\n\n   ```bash\n   make prepare-preview MINOR=31 BUILD=0 PREVIEW_NUMBER=1\n   ```\n\n   The target runs the full preflight, updates the Makefile version and `pkg/version.go`, verifies\n   the command reports the preview version, and creates the exact preparation commit. It does not\n   create or push a tag.\n\n6. Push the feature branch through the normal review workflow and wait for every required check.\n7. Review the complete diff and GitHub release notes one final time.\n\n### Publish a preview\n\n1. Inventory the current branch, commit, local tag, and remote branch and tag.\n2. Get explicit maintainer approval to publish the exact preview tag.\n3. Run `make release-preview` and watch it until it exits. The target reruns the full preflight,\n   verifies the current commit is already on the same remote feature branch, creates the tag, and\n   pushes only the tag.\n4. If the command fails after creating the local tag, inspect local and remote state before any\n   rerun. Never delete a public tag or force-push without an approved recovery plan.\n5. Create a GitHub release for the tag with `--prerelease`. Link `UPGRADING.md`, describe the\n   preview as opt-in, and explain that the final stable minor version follows compatibility review.\n6. Verify the Go proxy resolves the exact preview version and that `@latest` still resolves the\n   current stable release.\n\n## Required Repositories\n\nBefore release, verify these repositories exist, are on the expected branches, are clean, and are\nin sync with their upstreams:\n\n- Goa: current repository, expected branch `v3`.\n- Examples: `$(go env GOPATH)/src/goa.design/examples`, expected branch `main`.\n- Plugins: `$(go env GOPATH)/src/goa.design/plugins`, expected branch `v3`.\n\nFor each repository:\n\n1. Run `git status --porcelain` and stop if there are uncommitted changes.\n2. Verify the current branch is the expected branch. If not, ask before switching branches.\n3. Run `git fetch origin`.\n4. Verify `git rev-list --left-right --count @{u}...HEAD` reports `0 0`. If behind, run\n   `git pull --ff-only`. If ahead or diverged, stop and ask.\n5. Verify the target tag does not already exist locally or on `origin`.\n\n## Preparation Workflow\n\n1. In the Goa repository, read `UPGRADING.md` against the diff since the previous release tag.\n   Retitle it to the target version, replace every `(unreleased)` section marker with a\n   `v3.x.y:` heading, add a `v3.x.y: upgrade order and rollback` summary when the range needs\n   one, update the installation commands and the official plugins version to the target, and fix\n   the README links and paragraph that describe the current release. Merge those edits through a\n   normal pull request before creating any preparation commit; `make release` does not update\n   this guide.\n2. In the Goa repository, run `make`. Fix failures before continuing.\n3. In the Goa repository, run:\n\n   ```bash\n   go get -u -v ./...\n   go mod tidy\n   (cd jsonrpc/integration_tests && go get -u -v ./... && go mod tidy)\n   make\n   ```\n\n   The JSON-RPC integration tests are a nested Go module; update and tidy it before rerunning\n   `make` so `integration-test` does not fail on stale module metadata. `go get` should only update\n   `go.mod` and `go.sum`. If other files changed in any repository, review why before committing.\n\n4. In the examples repository, run:\n\n   ```bash\n   go list -m -f '{{if .Main}}{{.Dir}}{{end}}' all | while IFS= read -r mod; do\n     [ -n \"$mod\" ] && (cd \"$mod\" && go get -u -v ./... && go mod tidy)\n   done\n   make\n   ```\n\n   The examples repository has no root `go.mod`; each example listed in `go.work` owns its own\n   module. Update and tidy every example module before running `make`. If files changed, commit them\n   with `Prepare v3.x.y`. Do not push; `make release-examples` pushes the branch.\n\n5. In the plugins repository, run:\n\n   ```bash\n   go get -u -v ./...\n   go mod tidy\n   make\n   ```\n\n   If files changed, commit them with `Prepare v3.x.y`. Do not push; `make release-plugins`\n   pushes the branch.\n\n6. In the Goa repository, edit only `MINOR`, `BUILD`, and the preview marker in `Makefile` for the\n   target version. Leave `MAJOR=3`. For a stable release, `PREVIEW_NUMBER` must be empty. The stable\n   release target clears the suffix in `pkg/version.go`; do not edit that generated version value\n   by hand.\n7. If Goa files changed from dependency updates or the version bump, commit them with\n   `Prepare v3.x.y`.\n8. Re-check all three repositories are clean. They may be ahead of upstream by their preparation\n   commits; that is expected because `make release` pushes them.\n\n## Final Pre-Release Check\n\n`make release` runs its own clean checks and release preflight, but those checks happen inside a\ncommand that can create commits, tags, and pushes. Before running it:\n\n1. In all three repositories, run `git fetch origin`.\n2. Verify `git status --porcelain` is empty.\n3. Verify upstream is not ahead: the first number from\n   `git rev-list --left-right --count @{u}...HEAD` must be `0`. Local-ahead preparation commits are\n   expected.\n4. Do not push the local-ahead preparation commits. `make release` will push them together with the\n   release commits.\n5. Reconfirm the target version and that the target tag is absent locally and on `origin` in all\n   three repositories.\n\n## Run And Babysit Release\n\n1. From the Goa repository, run `make release`.\n2. Watch the command until it exits. Track which phase is running: `release-goa`,\n   `release-examples`, or `release-plugins`.\n3. If it fails, stop and inspect the failing repository before rerunning anything. Do not blindly\n   rerun the whole release after a tag or push may have succeeded.\n4. Before any rerun, inventory local and remote branches and tags for `v3.x.y` in all three\n   repositories. Never recreate an existing tag, delete a public tag, or force-push unless the user\n   explicitly approves the recovery plan.\n5. Fix the root cause, verify the affected repository is in the expected state, then rerun the\n   narrowest safe target or command.\n6. When release completes, report the released version and the branch/tag pushes that succeeded.\n\n## GitHub Release Notes\n\nAfter `make release` succeeds, create GitHub release notes for the Goa tag.\n\n1. Gather the final commit/PR list from the previous Goa tag to the new tag. Include merged PR\n   numbers, titles, authors, and any notable dependency or downstream examples/plugins release work.\n2. Identify every human contributor in that range from commit authors and PR authors. Do not miss\n   contributors whose commits were merged by someone else. Exclude bots from the thank-you list\n   unless their work is directly meaningful to users.\n3. Write notes that are clear and useful to someone who does not know Goa internals:\n   - Start with a short plain-language summary of why the release matters.\n   - Use sections only when the amount of change justifies them, such as `Highlights`, `Fixes`,\n     `Dependencies`, `Upgrade Notes`, and `Contributors`.\n   - Explain user impact before implementation detail. Avoid raw commit-log dumps.\n   - Include upgrade notes only for actions users may need to take.\n   - Thank every contributor by name or handle.\n4. Create or update the GitHub release for `v3.x.y` with the final notes. Do not mention agent or AI\n   tooling in public release notes.\n\n## Announcements\n\nAfter GitHub release notes are ready, draft announcements for Slack, Bluesky, and Substack. Make\nthem exciting and delightful by showing what the release helps users do, not by adding hype.\n\nVoice rules:\n\n- Lead with the most concrete user payoff.\n- Use warm, crisp language with one or two memorable details from the release.\n- Avoid empty hype, forced jokes, excessive exclamation marks, launch cliches, and insider-only\n  wording.\n- Keep contributor thanks visible and sincere.\n\nChannel guidance:\n\n- Slack: 2-4 short paragraphs or bullets. Sound like a maintainer sharing good news with the\n  community. Lead with the most useful user-facing change, link to the GitHub release, and thank\n  contributors.\n- Bluesky: Posts are limited to 300 graphemes. Stay under that limit, include the version, one\n  concrete highlight, and a release link. Make the line feel polished enough to repost.\n- Substack: Write a short note for readers who may not know Goa deeply. Use a friendly title, a\n  brief explanation of Goa, a user-centered story for the release highlights, upgrade guidance if\n  any, and contributor thanks. Keep it proportional to the release size.\n\n<!-- File: .cursor/skills/goa-release/SKILL.md (Tokens: ~2946 | Category: anthropic-skill) -->\n---\nname: goa-release\ndescription: Release Goa v3, including preflight tests, dependency updates, semver version bumps, release preparation commits, examples/plugins repo checks, and babysitting make release. Use when the user asks to release Goa, prepare a Goa release, bump the Goa version, or run make release.\n---\n\n# Goa Release\n\nUse this skill only from the Goa repository. A stable release and an opt-in preview are separate\nworkflows. `make release` pushes branches and tags for Goa, examples, and plugins. A preview tags\nGoa alone from a reviewed feature branch. Do not run either publishing command unless the user\nexplicitly approves that exact release.\n\n## Release Contract\n\n- Goa major version is always `3`. Never increment `MAJOR`; if it is not `3`, stop and ask.\n- Resolve the target version before making dependency-update commits in any repository. The agent\n  should pick the version from the changes, explain the reasoning, and get confirmation before\n  editing files or running dependency updates.\n- Apply semver within v3:\n  - Patch release: increment `BUILD`.\n  - Minor release: increment `MINOR` and reset `BUILD=0`.\n- An opt-in preview uses `v3.MINOR.BUILD-preview.NUMBER`. Its version is a testing label, not a\n  promise of the final stable minor version. The major version remains 3.\n- The preparation commit message must be exactly `Prepare v3.x.y`, where `x` is `MINOR` and `y`\n  is `BUILD`.\n- The preview preparation commit message must be exactly `Prepare v3.x.y-preview.n`.\n- Keep the working trees clean between phases. Never discard local changes unless the user\n  explicitly approves it.\n- Do not push preparation commits manually. `make release-goa` runs `git pull origin <branch>` in\n  examples and plugins; local-ahead preparation commits are fine as long as `origin` is not ahead.\n  Later, `make release-examples` and `make release-plugins` push those preparation commits together\n  with the release commits and tags.\n\n## Version Selection\n\nDetermine the target version before changing any repository:\n\n1. Read `MAJOR`, `MINOR`, and `BUILD` from the Goa `Makefile`.\n2. Confirm `MAJOR=3`.\n3. Inspect the commits and merged PRs since the previous release tag.\n4. Pick the semver bump:\n   - Minor when the release includes a user-visible feature, new DSL/runtime capability, or\n     backward-compatible public API addition.\n   - Patch when the release only includes fixes, dependency updates, docs, tests, or internal\n     maintenance.\n5. Tell the user the selected target version and the specific changes that justify it, then ask for\n   confirmation. If the user supplied an explicit version, validate it against the same reasoning and\n   call out any mismatch before continuing.\n6. Use the exact confirmed target version for every preparation commit, tag check, and release\n   command.\n\n## Preview Release Contract\n\nUse this workflow only when the confirmed version ends in `-preview.N`.\n\n- Work from the reviewed feature branch. Do not switch to or move the stable `v3` branch.\n- Publish Goa only. Do not update, tag, or push the examples and plugins repositories.\n- Keep the stable README badge and stable `@latest` installation instructions unchanged.\n- Make the preview public only after the upgrade guide describes every known source, design, wire,\n  deployment, and rollback effect in plain English.\n- Treat `prepare-preview` and `release-preview` as separate approval points. The first creates the\n  version commit. The second creates and pushes the public tag.\n- Never run `make release` with `PREVIEW_NUMBER` set. That target is the stable multi-repository\n  release and deliberately rejects preview versions.\n\n### Prepare a preview\n\n1. Confirm the complete version, such as `v3.31.0-preview.1`.\n2. Fetch `origin`, verify the feature branch contains the latest stable branch, and verify the\n   working tree is clean. Preserve and report any existing local changes.\n3. Verify the exact preview tag is absent locally and on `origin`.\n4. Read `UPGRADING.md` against the current diff. Confirm it tells application and plugin authors\n   how to install, regenerate, migrate, deploy, roll back, and report a problem.\n5. Run:\n\n   ```bash\n   make prepare-preview MINOR=31 BUILD=0 PREVIEW_NUMBER=1\n   ```\n\n   The target runs the full preflight, updates the Makefile version and `pkg/version.go`, verifies\n   the command reports the preview version, and creates the exact preparation commit. It does not\n   create or push a tag.\n\n6. Push the feature branch through the normal review workflow and wait for every required check.\n7. Review the complete diff and GitHub release notes one final time.\n\n### Publish a preview\n\n1. Inventory the current branch, commit, local tag, and remote branch and tag.\n2. Get explicit maintainer approval to publish the exact preview tag.\n3. Run `make release-preview` and watch it until it exits. The target reruns the full preflight,\n   verifies the current commit is already on the same remote feature branch, creates the tag, and\n   pushes only the tag.\n4. If the command fails after creating the local tag, inspect local and remote state before any\n   rerun. Never delete a public tag or force-push without an approved recovery plan.\n5. Create a GitHub release for the tag with `--prerelease`. Link `UPGRADING.md`, describe the\n   preview as opt-in, and explain that the final stable minor version follows compatibility review.\n6. Verify the Go proxy resolves the exact preview version and that `@latest` still resolves the\n   current stable release.\n\n## Required Repositories\n\nBefore release, verify these repositories exist, are on the expected branches, are clean, and are\nin sync with their upstreams:\n\n- Goa: current repository, expected branch `v3`.\n- Examples: `$(go env GOPATH)/src/goa.design/examples`, expected branch `main`.\n- Plugins: `$(go env GOPATH)/src/goa.design/plugins`, expected branch `v3`.\n\nFor each repository:\n\n1. Run `git status --porcelain` and stop if there are uncommitted changes.\n2. Verify the current branch is the expected branch. If not, ask before switching branches.\n3. Run `git fetch origin`.\n4. Verify `git rev-list --left-right --count @{u}...HEAD` reports `0 0`. If behind, run\n   `git pull --ff-only`. If ahead or diverged, stop and ask.\n5. Verify the target tag does not already exist locally or on `origin`.\n\n## Preparation Workflow\n\n1. In the Goa repository, read `UPGRADING.md` against the diff since the previous release tag.\n   Retitle it to the target version, replace every `(unreleased)` section marker with a\n   `v3.x.y:` heading, add a `v3.x.y: upgrade order and rollback` summary when the range needs\n   one, update the installation commands and the official plugins version to the target, and fix\n   the README links and paragraph that describe the current release. Merge those edits through a\n   normal pull request before creating any preparation commit; `make release` does not update\n   this guide.\n2. In the Goa repository, run `make`. Fix failures before continuing.\n3. In the Goa repository, run:\n\n   ```bash\n   go get -u -v ./...\n   go mod tidy\n   (cd jsonrpc/integration_tests && go get -u -v ./... && go mod tidy)\n   make\n   ```\n\n   The JSON-RPC integration tests are a nested Go module; update and tidy it before rerunning\n   `make` so `integration-test` does not fail on stale module metadata. `go get` should only update\n   `go.mod` and `go.sum`. If other files changed in any repository, review why before committing.\n\n4. In the examples repository, run:\n\n   ```bash\n   go list -m -f '{{if .Main}}{{.Dir}}{{end}}' all | while IFS= read -r mod; do\n     [ -n \"$mod\" ] && (cd \"$mod\" && go get -u -v ./... && go mod tidy)\n   done\n   make\n   ```\n\n   The examples repository has no root `go.mod`; each example listed in `go.work` owns its own\n   module. Update and tidy every example module before running `make`. If files changed, commit them\n   with `Prepare v3.x.y`. Do not push; `make release-examples` pushes the branch.\n\n5. In the plugins repository, run:\n\n   ```bash\n   go get -u -v ./...\n   go mod tidy\n   make\n   ```\n\n   If files changed, commit them with `Prepare v3.x.y`. Do not push; `make release-plugins`\n   pushes the branch.\n\n6. In the Goa repository, edit only `MINOR`, `BUILD`, and the preview marker in `Makefile` for the\n   target version. Leave `MAJOR=3`. For a stable release, `PREVIEW_NUMBER` must be empty. The stable\n   release target clears the suffix in `pkg/version.go`; do not edit that generated version value\n   by hand.\n7. If Goa files changed from dependency updates or the version bump, commit them with\n   `Prepare v3.x.y`.\n8. Re-check all three repositories are clean. They may be ahead of upstream by their preparation\n   commits; that is expected because `make release` pushes them.\n\n## Final Pre-Release Check\n\n`make release` runs its own clean checks and release preflight, but those checks happen inside a\ncommand that can create commits, tags, and pushes. Before running it:\n\n1. In all three repositories, run `git fetch origin`.\n2. Verify `git status --porcelain` is empty.\n3. Verify upstream is not ahead: the first number from\n   `git rev-list --left-right --count @{u}...HEAD` must be `0`. Local-ahead preparation commits are\n   expected.\n4. Do not push the local-ahead preparation commits. `make release` will push them together with the\n   release commits.\n5. Reconfirm the target version and that the target tag is absent locally and on `origin` in all\n   three repositories.\n\n## Run And Babysit Release\n\n1. From the Goa repository, run `make release`.\n2. Watch the command until it exits. Track which phase is running: `release-goa` (including\n   `warm-proxy`, which waits for `gopkg.in` to expose the new tag and warms `proxy.golang.org` and\n   `sum.golang.org` by commit hash before querying the tag), `release-examples`, or\n   `release-plugins`.\n3. If it fails, stop and inspect the failing repository before rerunning anything. Do not blindly\n   rerun the whole release after a tag or push may have succeeded.\n4. Before any rerun, inventory local and remote branches and tags for `v3.x.y` in all three\n   repositories. Never recreate an existing tag, delete a public tag, or force-push unless the user\n   explicitly approves the recovery plan.\n5. Fix the root cause, verify the affected repository is in the expected state, then rerun the\n   narrowest safe target or command.\n6. When release completes, report the released version and the branch/tag pushes that succeeded.\n\n## GitHub Release Notes\n\nAfter `make release` succeeds, create GitHub release notes for the Goa tag.\n\n1. Gather the final commit/PR list from the previous Goa tag to the new tag. Include merged PR\n   numbers, titles, authors, and any notable dependency or downstream examples/plugins release work.\n2. Identify every human contributor in that range from commit authors and PR authors. Do not miss\n   contributors whose commits were merged by someone else. Exclude bots from the thank-you list\n   unless their work is directly meaningful to users.\n3. Write notes that are clear and useful to someone who does not know Goa internals:\n   - Start with a short plain-language summary of why the release matters.\n   - Use sections only when the amount of change justifies them, such as `Highlights`, `Fixes`,\n     `Dependencies`, `Upgrade Notes`, and `Contributors`.\n   - Explain user impact before implementation detail. Avoid raw commit-log dumps.\n   - Include upgrade notes only for actions users may need to take.\n   - Thank every contributor by name or handle.\n4. Create or update the GitHub release for `v3.x.y` with the final notes. Do not mention agent or AI\n   tooling in public release notes.\n\n## Announcements\n\nAfter GitHub release notes are ready, draft announcements for Slack, Bluesky, and Substack. Make\nthem exciting and delightful by showing what the release helps users do, not by adding hype.\n\nVoice rules:\n\n- Lead with the most concrete user payoff.\n- Use warm, crisp language with one or two memorable details from the release.\n- Avoid empty hype, forced jokes, excessive exclamation marks, launch cliches, and insider-only\n  wording.\n- Keep contributor thanks visible and sincere.\n\nChannel guidance:\n\n- Slack: 2-4 short paragraphs or bullets. Sound like a maintainer sharing good news with the\n  community. Lead with the most useful user-facing change, link to the GitHub release, and thank\n  contributors.\n- Bluesky: Posts are limited to 300 graphemes. Stay under that limit, include the version, one\n  concrete highlight, and a release link. Make the line feel polished enough to repost.\n- Substack: Write a short note for readers who may not know Goa deeply. Use a friendly title, a\n  brief explanation of Goa, a user-centered story for the release highlights, upgrade guidance if\n  any, and contributor thanks. Keep it proportional to the release size.\n\n<!-- File: skills/goa-service-designer/references/transport-errors-interceptors.md (Tokens: ~1479 | Category: anthropic-skill) -->\n# Transport, Errors, And Interceptors\n\nUse this reference when changing HTTP, gRPC, or JSON-RPC mappings, streaming, errors, security,\ninterceptors, middleware, or production wiring. The gRPC presence and JSON-RPC behavior below\ndescribes Goa v3.31 and later. Check the application's selected module version and its\n`UPGRADING.md` before changing older code.\n\n## HTTP Mapping\n\n- Use resource nouns, plural names, stable hierarchy, and HTTP methods for actions.\n- Put stable prefixes in API-level or service-level `HTTP(Path(...))`.\n- Use `Parent` and `CanonicalMethod` only when nested resources become clearer.\n- Map path, query, header, and body fields deliberately with `Param`, `Header`, and `Body`.\n- Use explicit wire-name mapping when attribute names differ from HTTP element names.\n- Choose status codes intentionally. Use `StatusCreated` for creates when appropriate.\n- Use default content negotiation unless a real media type requires custom encoders or decoders.\n- Use the CORS plugin for browser-facing cross-origin policy.\n- Use `Files` only for HTTP static content.\n\nHTTP object payload checks:\n\n- Every path token must map to a payload field.\n- Every non-body attribute should land where intended.\n- Use `Body(\"field\")` only when the request body should be that field's raw value.\n- Unmapped object attributes are encoded in the body.\n\n```go\nHTTP(func() {\n    GET(\"/accounts/{account_id}/items\")\n    Param(\"accountId:account_id\")\n    Param(\"limit\")\n    Response(StatusOK)\n    Response(\"not_found\", StatusNotFound)\n})\n```\n\n## Streaming\n\nGoa's streaming DSL is transport-agnostic. The transport mapping determines HTTP behavior:\n\n- Plain HTTP streaming defaults to WebSocket.\n- Add `ServerSentEvents()` only for one-way server-to-client streams.\n- WebSocket endpoints use `GET`.\n- For gRPC streaming, check generated protobuf and server/client stream types.\n- JSON-RPC supports unary calls or a single request followed by an\n  explicit SSE stream. It rejects client or bidirectional streaming, WebSocket streams, and a\n  method combining `Result` with `StreamingResult`. Ordinary HTTP WebSocket support is separate.\n- Streaming implementations must handle flow control, `io.EOF`, send errors, context cancellation,\n  timeouts, and cleanup.\n\n## gRPC Mapping\n\n- Set package and version metadata for public or versioned APIs.\n- Keep domain data in messages.\n- Use metadata, headers, and trailers only for protocol metadata.\n- Use streaming for large or continuous datasets.\n- Never renumber released `Field` values.\n- Check `.proto` output after changing shared types, streaming methods, or custom protobuf metadata.\n- Required singular scalars preserve protobuf presence. An omitted required\n  boolean is invalid; an explicitly supplied `false` can be valid. Generated decoders validate\n  before converting to service values. See the modeling reference for collections and defaults.\n\n## JSON-RPC Mapping\n\n- Use service-level `JSONRPC` to configure the shared HTTP POST endpoint, and method-level\n  `JSONRPC` for method-specific behavior and error mappings.\n- Let generated code own the JSON-RPC envelope, dispatch, request IDs, batches, and protocol errors.\n  The payload describes `params`; do not handwrite transport envelopes in service code.\n- Ordinary generated client calls have an ID even without an `ID` payload field.\n  `Notification()` explicitly declares a one-way call. Having no result does not by itself make\n  a method a notification. Notifications cannot declare a result, ID field, or stream.\n- `ID` belongs directly in the payload, not the result. The transport returns the request ID;\n  the service does not choose a response ID.\n- Map designed errors with JSON-RPC `Response` codes. Verify the generated error `data` shape\n  before changing a custom client's decoding.\n- For SSE, pair `StreamingResult` with method-level `ServerSentEvents()`. Verify event field\n  mappings and cancellation through the generated client and server.\n\n## Errors\n\n- Define reusable potential errors at API scope when you want one canonical error type/name and one\n  transport mapping. API-level `Error(...)` declarations do not make those errors applicable to\n  every endpoint. Select a reusable definition with `Error(\"name\")` at service or method scope.\n- Define an error at service scope only when every method on that service can return it.\n- Define an error at method scope when only that method can return it.\n- Do not promote a method-specific error to service scope just to avoid repeating a declaration or to\n  make generated constructors easier to reach; the design would falsely advertise that all service\n  methods can return it.\n- Use descriptive names and descriptions.\n- Prefer `ErrorResult` for most errors.\n- Add `Temporary()`, `Timeout()`, or `Fault()` when clients should behave differently.\n- Use custom error types only when clients need structured context.\n- If multiple custom errors can return from the same method, include a field marked with\n  `Meta(\"struct:error:name\")`.\n- Map every exposed error for each enabled transport with `HTTP(Response(...))` and\n  `GRPC(Response(...))`, or the corresponding `JSONRPC(Response(...))`.\n- In implementation code, return generated error constructors or generated custom error payloads.\n- Wrap underlying causes for logs and tracing, but keep client-facing messages safe.\n- Test errors through the service API. Verify generated error names, transport status mappings when\n  practical, and custom error payloads.\n\n## Security\n\n- Declare security schemes, required scopes, and credential fields in the design.\n- Prefer API-level defaults.\n- Override at service or method scope when needed.\n- Use `NoSecurity()` explicitly for public methods.\n- Add matching security payload fields such as `TokenField` or `APIKeyField`.\n- Map credentials through HTTP headers/query parameters or gRPC metadata.\n- Implement the generated authentication callbacks and application authorization rules.\n  A scheme declaration does not verify a token or establish resource ownership by itself.\n\n## Goa Interceptors Vs Middleware\n\nUse Goa interceptors for type-safe domain concerns:\n\n- Business validation that is not boundary validation.\n- Request enrichment.\n- Response enrichment.\n- Auditing.\n- Domain-level transformations.\n\nUse HTTP middleware or gRPC interceptors for protocol concerns:\n\n- Logging.\n- Tracing.\n- CORS.\n- Compression.\n- Request IDs.\n- Rate limiting.\n- Panic recovery.\n- Wire-level metadata.\n\nGoa interceptors are generated endpoint wrappers, not transport middleware:\n\n- Server interceptors run after transport decoding and before the service method.\n- Client interceptors run around the typed client endpoint before transport encoding and after\n  transport decoding.\n- Use generated typed accessors.\n- Call `next` exactly once when continuing.\n- If order matters, inspect generated `Wrap<Method>Endpoint`; the last wrapper runs first on the\n  request path.\n\n## Observability\n\nFor production services, wire observability, health checks, timeouts, graceful shutdown, and\nconfiguration at application boundaries. Goa docs recommend Clue/OpenTelemetry. Use generated\n`ServiceName`, `APIVersion`, method names, endpoint wrappers, and interceptor metadata for stable\ntelemetry labels.\n\n<!-- File: skills/goa-service-designer/SKILL.md (Tokens: ~2062 | Category: anthropic-skill) -->\n---\nname: goa-service-designer\ndescription: Design and evolve Goa application services. Use for Goa DSL changes, HTTP/gRPC/JSON-RPC contracts, validation, errors, interceptors, code generation, and service implementation.\n---\n\n# Goa Service Designer\n\nUse this skill for applications and plugins that declare or consume Goa contracts. Repository\ninstructions govern implementation. For changes to Goa's own compiler, runtime, templates, or\ngenerators, use Goa's contributor workflow instead of the application workflow below; still use the\nreference and capability checks below when deciding what the DSL or generated transport supports.\n\nLet Goa generate the mechanical code. Use the relevant design and generated service interface as\nthe working context; inspect transport output when the task changes wire behavior. Implement the\napplication's decisions outside `gen/`.\n\n## Consult The Relevant Reference Before Designing\n\nRead the relevant reference before a non-trivial design or implementation decision. Do not wait\nuntil generation fails, and do not treat the links as optional background reading:\n\n- For HTTP, gRPC, or JSON-RPC mappings, streaming, errors, security, or interceptor behavior, read\n  [transport guidance](references/transport-errors-interceptors.md).\n- For named types, aliases, pointers, defaults, unions, views, or validation, read\n  [modeling guidance](references/modeling-and-validation.md).\n- For generated signatures, constructors, codecs, imports, or downstream implementation changes,\n  read [generated-code guidance](references/generated-code-and-implementation.md).\n- When observed output or behavior contradicts the design, also read\n  [troubleshooting](references/troubleshooting.md).\n\nBefore introducing a transport workaround or claiming that Goa cannot express a requirement:\n\n1. Check the existing DSL mechanism in the reference and the selected Goa version's source. For\n   example, `Param(\"attributeName:url_name\")` separates a payload field from its URL parameter name;\n   inspect that mapping before renaming path tokens or adding transport-only replacement fields.\n2. Trace the authored mapping through generated payloads, client encoding, server decoding, and\n   endpoint invocation. Distinguish the payload name, HTTP element name, and generated Go selector.\n3. Verify the disputed capability with a minimal authored design and generated client/server check\n   before editing its replacement. A reference states the intended contract; it does not prove the\n   selected generator implements it correctly. Keep a failing result and trace its owning layer\n   rather than assuming the DSL lacks the feature.\n\nReuse a working native mechanism. If it fails, explain the exact generator gap and why a change\nbelongs in Goa or the consuming plugin before implementing it. Read only the references relevant\nto the decision; routine mechanical edits do not require loading every reference.\n\n## Default Workflow\n\n1. Find the local design, generated service contract, implementation, generation wrapper, validation\n   commands, and affected consumers. Check the Goa version and any replacement in `go.mod`.\n2. Reuse established local patterns for routine edits. Consult goa.design when choosing an\n   unfamiliar feature, resolving uncertain DSL or generated behavior, or troubleshooting.\n   Read only the relevant section, using these topic routes:\n   - New project: [Quickstart](https://goa.design/docs/1-goa/quickstart/) and [Code Generation](https://goa.design/docs/1-goa/code-generation/).\n   - Types, validation, views, or unions: [DSL Reference](https://goa.design/docs/1-goa/dsl-reference/).\n   - HTTP mapping, WebSocket, or SSE: [HTTP Guide](https://goa.design/docs/1-goa/http-guide/).\n   - gRPC, protobuf tags, metadata, or streaming: [gRPC Guide](https://goa.design/docs/1-goa/grpc-guide/).\n   - JSON-RPC: [transport reference](references/transport-errors-interceptors.md#json-rpc-mapping) and the selected Goa version's `dsl.JSONRPC` documentation.\n   - Errors: [Error Handling](https://goa.design/docs/1-goa/error-handling/).\n   - Interceptors or middleware: [Interceptors](https://goa.design/docs/1-goa/interceptors/).\n   - Security or production wiring: [Production](https://goa.design/docs/1-goa/production/).\n   Online docs may describe a different release. For release-specific behavior and upgrades, use the\n   selected Goa checkout's `UPGRADING.md` and generated output. Use a page's Markdown version\n   when available; do not preload every guide or reference.\n3. State the intended contract change in one or two sentences.\n4. Edit the Goa design first.\n5. Regenerate with the project's wrapper. Without one, use\n   `go run goa.design/goa/v3/cmd/goa gen <design-package-import-path>` so the command uses the\n   application's selected module version. Never use `goa gen ./design`.\n6. Implement the generated interface outside `gen/`.\n7. Update only affected consumers: mocks, clients, docs, examples, API snapshots, OpenAPI/protobuf\n   consumers, command wiring, and project-specific SDKs generated from Goa output.\n8. Run the generation, lint, type-check, and test commands allowed by the repository instructions.\n   If a command is prohibited or too broad, state exactly what was not run.\n9. Review generated and hand-written diffs together. Every generated change should follow from\n   the design or an intentional tooling upgrade.\n\nUse `goa example <design-package-import-path>` when starter files are needed. It creates missing\napplication files and does not update existing files. Review new files and update existing wiring\nyourself; do not expect it to migrate an implementation.\n\n## Hard Rules\n\n- Treat the Goa design as the canonical contract. If payload shape, result shape, validation,\n  security, errors, transport mapping, documentation, OpenAPI, protobuf, generated clients, or CLIs\n  need to change, edit the design first and regenerate.\n- Never patch generated files, OpenAPI output, protobuf output, or generated clients to hide a stale\n  design.\n- Keep protobuf field numbers unique within the final message, including inherited fields.\n  Never renumber or reuse released field numbers to make a sequence contiguous.\n- Put boundary validation in Goa. Use `Required`, `Enum`, `Format`, `Pattern`, `Minimum`,\n  `Maximum`, `MinLength`, `MaxLength`, defaults, security fields, and explicit transport mappings in\n  the design.\n- Model error applicability at the narrowest correct Goa scope. API-level errors define reusable\n  potential errors and let transports map them once; they do not mean every endpoint returns every\n  API-level error. Service-level errors apply to all methods in that service. Method-level errors\n  apply only to that method. Do not list an error at service scope just to make a generated\n  constructor convenient if only some methods can return it.\n- In service code, trust payloads already validated by the generated transport and enforce business\n  invariants. Direct service or endpoint calls bypass transport decoding; their callers must supply\n  valid values or validate at their own input boundary. Do not add nil guards,\n  fallback behavior, silent recovery, blanket string trimming, or compatibility shims for values the\n  design guarantees.\n- Do not use nil versus empty slices or maps as domain meaning. `Required` and `MinLength` express\n  different constraints, and JSON and protobuf have different collection presence rules. See\n  [presence and collections](references/modeling-and-validation.md#presence-and-collections).\n- Preserve compatibility for shipped public APIs, persisted data, external SDKs, and documented\n  behavior. For internal-only contracts or unshipped branch work, update callers cleanly instead of\n  adding shims.\n\n## Design Conventions\n\nFollow the application's existing conventions and compatibility requirements. For new designs:\n\n- Prefix explicit generated-package aliases with `gen`, such as `genfront` or `genfrontgrpc`.\n- Prefer lower camel case for public HTTP fields and parameters (`accountId`) and snake case for\n  method names (`get_account`). Map established wire names explicitly, for example\n  `Header(\"tusResumable:Tus-Resumable\")`.\n- Use literal integer `Field` tags so wire identities are easy to review. Start a new standalone\n  definition at `1`. For an `Extend` definition, `100` can start a new range only if inherited fields\n  leave that range free. Inspect the complete inheritance chain and assign unused numbers; nested\n  `Extend` calls must not restart at an occupied `100`. Existing tags always keep their numbers.\n\nThese are authoring conventions, not requirements imposed by Goa.\n\n## What To Read Next\n\nUse the decision triggers above to select references; the details below describe their scope:\n\n- `references/modeling-and-validation.md`: type modeling, primitive aliases, required fields,\n  pointer/default semantics, views, presence, and compatibility.\n- `references/transport-errors-interceptors.md`: HTTP, gRPC, JSON-RPC, streaming, errors, security,\n  interceptors, middleware, and observability labels.\n- `references/generated-code-and-implementation.md`: generated diff triage, dirty worktrees,\n  implementation updates, downstream artifacts, and validation commands.\n- `references/troubleshooting.md`: generation failures, decode bugs, gRPC output surprises,\n  interceptor ordering, and common mini-patterns.\n\n## Final Review\n\nBefore finishing, verify:\n\n- The design remains the source of truth.\n- Generated code was regenerated, not edited.\n- Payloads, results, validation, security, errors, and transport mappings are explicit.\n- Service code trusts established validation boundaries and handles real dependency failures.\n- Compatibility choices are represented in the design and tests, not hidden in service fallbacks.\n- Affected downstream consumers are updated; unaffected artifacts are left alone.\n- New transport workarounds and capability claims have evidence from the native generated path.\n- Test coverage matches the risk of the contract change.\n\n<!-- File: .cursorrules (Tokens: ~288 | Category: cursor-rule) -->\n# Goa repository rules for Cursor\n\n- Never edit generated code. Fix the generator/templates instead.\n- Prefer any over interface{} in new code.\n- Transports: HTTP, gRPC, and JSON-RPC 2.0 (HTTP, SSE, WebSocket). JSON-RPC supports batch and notifications; streaming over WS/SSE.\n- Testing:\n  - Run unit tests with `make test`.\n  - JSON-RPC integration tests live in `jsonrpc/integration_tests`; run with `make integration-test` (skips on Windows).\n  - Golden tests use testify; update with `go test -update` or `-u`.\n- Code style:\n  - Small, focused files; one main construct per file when possible.\n  - Public types first, then private types, public constants, private constants, public vars, private vars, public functions/methods, then private.\n  - Use `maps.Copy`/`slices.Contains`, `http.NoBody`, avoid shadowing builtins.\n- Architecture quick map:\n  - `dsl/` (design DSL), `expr/` (expressions), `codegen/` (generation engine & templates), `cmd/goa/` (CLI), `http/`, `grpc/`, `jsonrpc/` (transports), `pkg/`, `middleware/`, `security/`, `eval/`.\n- For deeper guidance, see `CLAUDE.md`.\n\n<!-- File: CLAUDE.md (Tokens: ~11 | Category: claude-rule) -->\n# CLAUDE.md\n\nRead @AGENTS.md\n</yakaai_skills>"}