doc: add portable agentic instructions (#136)

Add contributions rule, AGENTS.md symlink, fix mono-repo description
in CLAUDE.md, add hooks/ to .claude/.gitignore.

Signed-off-by: Frederic BIDON <[email protected]>
Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>

Author: fredbi

.claude/.gitignore

@@ -2,3 +2,4 @@ plans/
 skills/
 commands/
 agents/
+hooks/

.claude/CLAUDE.md

@@ -10,12 +10,12 @@ This repository provides shared, reusable GitHub Actions workflows for the go-op
 
 When working with GitHub Actions workflows in this repository, refer to:
 
-📖 **`.claude/rules/github-workflows-conventions.md`** (auto-loaded for workflow files):
+**`.claude/rules/github-workflows-conventions.md`** (auto-loaded for workflow files):
 - YAML formatting and style conventions (expression spacing, step arrays, conditionals)
 - Security rules (SHA pinning, permissions, secret exposure)
 - Common gotchas (boolean inputs, description fields)
 
-📖 **`.claude/skills/github-actions.md`** for:
+**`.claude/skills/github-actions.md`** for:
 - Behavioral patterns (race condition handling, optimistic execution)
 - Workflow recipes (bot-credentials, wait-pending-jobs, auto-merge)
 - Action definition best practices and documentation standards
@@ -137,11 +137,12 @@ The `auto-merge.yml` workflow handles two bot types:
 - `.golangci.yml` - Linter configuration (many linters disabled to match go-openapi style)
 - `.cliff.toml` - Release notes generation configuration
 - `.github/dependabot.yaml` - Dependency update configuration
+- `go.work` - Go workspace tying root and `sample-monorepo` modules together
 - `go.mod` - Requires Go 1.24.0
 
 ## Important Notes
 
 - All workflow action versions are pinned to commit SHAs for security
 - Permissions are explicitly granted at job level to follow least-privilege principle
-- This repo itself uses minimal Go code (just sample tests); it's primarily YAML workflows
+- This repo is a mono-repo (`go.work`) with a `sample-monorepo` submodule used to exercise the CI workflows against a multi-module layout; it's primarily YAML workflows
 - The `local-*` workflows serve as both tests and documentation of proper usage

.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 ./...
+```

.claude/rules/github-workflows-conventions.md

@@ -265,3 +265,33 @@ description: |
    **Rule**: Use `type: string` with values `'true'` or `'false'` for all boolean-like workflow inputs.
 
    **Note**: Step outputs and bash variables are always strings, so `x == 'true'` works fine for those.
+
+### YAML fold scalars in action inputs
+
+**NEVER** use `>` or `>-` (fold scalars) for `with:` input values:
+
+> The YAML spec says fold scalars replace newlines with spaces, but the GitHub Actions runner
+> does not reliably honor this for action inputs. The action receives the literal multi-line string
+> instead of a single folded line, which breaks flag parsing.
+
+```yaml
+# ❌ BROKEN - Fold scalar, args received with embedded newlines
+- uses: goreleaser/goreleaser-action@...
+  with:
+    args: >-
+      release
+        --clean
+        --release-notes /tmp/notes.md
+
+# ✅ CORRECT - Single line
+- uses: goreleaser/goreleaser-action@...
+  with:
+    args: release --clean --release-notes /tmp/notes.md
+
+# ✅ CORRECT - Literal block scalar (|) is fine for run: scripts
+- run: |
+    echo "line 1"
+    echo "line 2"
+```
+
+**Rule**: Use single-line strings for `with:` inputs. Only use `|` (literal block scalar) for `run:` scripts where multi-line is intentional.

.github/copilot-instructions.md

@@ -17,3 +17,10 @@ When editing workflow files, follow the conventions documented in `.github/copil
 - **Shared workflows** (`.github/workflows/*.yml`): called by other go-openapi repos
 - **Local test workflows** (`local-*.yml`): test the shared workflows within this repo
 - New reusable actions belong in `go-openapi/gh-actions`, not here
+
+## Contributions
+
+- Every commit must be DCO signed-off (`git commit -s`)
+- Agents may be co-authors but the commit author must be a human
+- PRs must clearly describe the problem and include tests
+- Run `golangci-lint run --new-from-rev master` before pushing

.gitignore

@@ -27,6 +27,9 @@ profile.cov
 # env file
 .env
 
+# MCP configuration
+.mcp.json
+
 # Editor/IDE
 # .idea/
 # .vscode/

AGENTS.md

@@ -0,0 +1 @@
+.github/copilot-instructions.md