doc: add portable agentic instructions

.claude/.gitignore

@@ -0,0 +1,5 @@
+plans/
+skills/
+commands/
+agents/
+hooks/

.claude/CLAUDE.md

@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Go monorepo of utility libraries for the `go-openapi` / `go-swagger` ecosystem. The root package
+is a **backward-compat facade** — all its exported functions are deprecated and delegate to sub-packages.
+
+See [docs/MAINTAINERS.md](../docs/MAINTAINERS.md) for CI/CD, release process, and repo structure details.
+
+## Workspace & Modules
+
+Go workspace (`go.work`, Go 1.24). Contains 15+ modules:
+
+| Module | Purpose |
+|--------|---------|
+| `.` (root) | Deprecated shims forwarding to sub-packages |
+| `cmdutils` | CLI utility helpers |
+| `conv` | Type conversions: string-to-value, value-to-pointer, pointer-to-value (generics) |
+| `fileutils` | File and path utilities |
+| `jsonname` | Infer JSON field names from Go struct tags |
+| `jsonutils` | JSON read/write, `ConcatJSON`, `JSONMapSlice`; pluggable adapter system |
+| `jsonutils/adapters/easyjson` | easyjson adapter (separate module to isolate dependency) |
+| `loading` | Load specs from filesystem or HTTP |
+| `mangling` | Name mangling: `ToGoName`, `ToFileName`, `ToVarName`, etc.; configurable initialisms |
+| `netutils` | Host/port parsing |
+| `stringutils` | Slice search, query parameter splitting |
+| `typeutils` | Zero-value and nil-safe interface checks |
+| `yamlutils` | YAML-to-JSON conversion, ordered YAML documents |
+
+Inter-module dependencies use `replace` directives pointing to local paths.
+
+## Testing
+
+```sh
+# Run all tests across every workspace module
+go test work ./...
+
+# Run tests for a single module
+go test ./conv/...
+```
+
+Note: plain `go test ./...` only tests the root module. The `work` pattern expands to all
+modules listed in `go.work`.
+
+CI runs tests on `{ubuntu, macos, windows} x {stable, oldstable}` with `-race` via `gotestsum`.
+
+### Fuzz tests
+
+```sh
+# List all fuzz targets across the workspace
+go test work -list Fuzz ./...
+
+# Run a specific fuzz target (go test -fuzz cannot span multiple packages)
+go test -fuzz=Fuzz -run='FuzzToGoName$' -fuzztime=1m30s ./mangling
+```
+
+Fuzz corpus lives in `testdata/fuzz/` within each package. CI runs each fuzz target for 1m30s
+with a 5m minimize timeout.
+
+### Test framework
+
+`github.com/go-openapi/testify/v2` — a zero-dep fork of `stretchr/testify`.
+Because it's a fork, `testifylint` does not work.
+
+Patterns: table-driven tests with `t.Run`, fuzz tests, benchmarks, and integration
+tests in `jsonutils/adapters/testintegration/`.
+
+## Linting
+
+```sh
+golangci-lint run
+```
+
+Config: `.golangci.yml` — posture is `default: all` with explicit disables.
+See [docs/STYLE.md](../docs/STYLE.md) for the rationale behind each disabled linter.
+
+Key rules:
+- Every `//nolint` directive **must** have an inline comment explaining why.
+- Prefer disabling a linter over scattering `//nolint` across the codebase.
+
+## Code Conventions
+
+- All files must have SPDX license headers (Apache-2.0).
+- Go version policy: support the 2 latest stable Go minor versions.
+- Commits require DCO sign-off (`git commit -s`).
+- Root-level `*_iface.go` files are thin deprecated wrappers — do not add new public API there.
+- `jsonutils` uses a pluggable adapter registry (`adapters.Registry`); new JSON backends
+  should be separate modules implementing interfaces from `jsonutils/adapters/ifaces`.
+- `mangling.NameMangler` is configured via functional options and is concurrency-safe.

.claude/rules/contributions.md

@@ -0,0 +1,52 @@
+---
+paths:
+  - "**/*"
+---
+
+# Contribution rules (go-openapi)
+
+Read `.github/CONTRIBUTING.md` before opening a pull request.
+
+## Commit hygiene
+
+- Every commit **must** be DCO signed-off (`git commit -s`) with a real email address.
+  PGP-signed commits are appreciated but not required.
+- Agents may be listed as co-authors (`Co-Authored-By:`) but the commit **author must be the human sponsor**.
+  We do not accept commits solely authored by bots or agents.
+- Squash commits into logical units of work before requesting review (`git rebase -i`).
+
+## Linting
+
+Before pushing, verify your changes pass linting against the base branch:
+
+```sh
+golangci-lint run --new-from-rev master
+```
+
+Install the latest version if you don't have it:
+
+```sh
+go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
+```
+
+## Problem statement
+
+- Clearly describe the problem the PR solves, or reference an existing issue.
+- PR descriptions must not be vague ("fix bug", "improve code") — explain *what* was wrong and *why* the change is correct.
+
+## Tests are mandatory
+
+- Every bug fix or feature **must** include tests that demonstrate the problem and verify the fix.
+- The only exceptions are documentation changes and typo fixes.
+- Aim for at least 80% coverage of your patch.
+- Run the full test suite before submitting:
+
+For mono-repos:
+```sh
+go test work ./...
+```
+
+For single module repos:
+```sh
+go test ./...
+```