docs: add AGENTS.md as the shared always-on agent contract

[alexeykazakov]

• Point Claude Code at AGENTS.md and share Cursor skills/commands via .claude symlinks
• Load skills by description; trigger use-modern-go on Go edits
• Keep AGENTS.md short and correct listed facts in the same change

Summary by CodeRabbit

• Documentation

  • Added project guidance covering development workflows, testing, linting, formatting, security safeguards, and contribution practices.
  • Added a reference document linking to the project guidance.
  • Updated Go development guidance to include modern syntax recommendations.

• Chores

  • Added shared command and skill references for compatible development tools.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Enterprise

Run ID: a93ea77e-c53d-4553-9bd6-126ef480a888

📥 Commits

Reviewing files that changed from the base of the PR and between 01d800e and 2208192.

📒 Files selected for processing (5)

• .claude/commands
• .claude/skills
• .cursor/skills/use-modern-go/SKILL.md
• AGENTS.md
• CLAUDE.md

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• codeready-toolchain/mcp-common (manual)
• codeready-toolchain/mcp-server-devsandbox (manual)
• codeready-toolchain/api (manual)
• codeready-toolchain/toolchain-common (manual)
• codeready-toolchain/host-operator (manual)
• codeready-toolchain/toolchain-e2e (manual)

Included review availability: Your plan provides up to 12 included reviews per hour; 10 remain after this review.

📜 Recent review details

⚠️ CI failures not shown inline (2)

GitHub Actions: CI / Lint: docs: add AGENTS.md as the shared always-on agent contract

Conclusion: failure

View job details

##[group]run golangci-lint
 Running [/home/runner/golangci-lint-2.12.2-linux-amd64/golangci-lint config path --config=./.golangci.yml] in [/home/runner/work/cli-mcp-operator/cli-mcp-operator] ...
 Running [/home/runner/golangci-lint-2.12.2-linux-amd64/golangci-lint config verify --config=./.golangci.yml] in [/home/runner/work/cli-mcp-operator/cli-mcp-operator] ...
 Running [/home/runner/golangci-lint-2.12.2-linux-amd64/golangci-lint run  --config=./.golangci.yml --verbose] in [/home/runner/work/cli-mcp-operator/cli-mcp-operator] ...
 ##[error]../../cli-mcp-server/cli-mcp-server/pkg/sandbox/bash.go:115:13: Error return value of `bs.cmd.Wait` is not checked (errcheck)

---

GitHub Actions: CI / 1_Lint.txt: docs: add AGENTS.md as the shared always-on agent contract

Conclusion: failure

View job details

##[group]run golangci-lint
 Running [/home/runner/golangci-lint-2.12.2-linux-amd64/golangci-lint config path --config=./.golangci.yml] in [/home/runner/work/cli-mcp-operator/cli-mcp-operator] ...
 Running [/home/runner/golangci-lint-2.12.2-linux-amd64/golangci-lint config verify --config=./.golangci.yml] in [/home/runner/work/cli-mcp-operator/cli-mcp-operator] ...
 Running [/home/runner/golangci-lint-2.12.2-linux-amd64/golangci-lint run  --config=./.golangci.yml --verbose] in [/home/runner/work/cli-mcp-operator/cli-mcp-operator] ...
 ##[error]../../cli-mcp-server/cli-mcp-server/pkg/sandbox/bash.go:115:13: Error return value of `bs.cmd.Wait` is not checked (errcheck)

🧰 Additional context used

📓 Path-based instructions (2)

**

⚙️ CodeRabbit configuration file

-Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity.

Files:

• CLAUDE.md
• AGENTS.md

AGENTS.md

📄 CodeRabbit inference engine (AGENTS.md)

AGENTS.md: If a change makes a stated fact here wrong (commands, paths, versions, binary names, safety constraints), update that bullet in the same change.
Do not add recap, new sections, or session learnings. Keep this file short.

Files:

• AGENTS.md

🧠 Learnings (1)

📓 Common learnings

Learnt from: CR
Repo: codeready-toolchain/cli-mcp-operator

Timestamp: 2026-08-19T00:04:43.043Z
Learning: Never invent alternate package-manager commands if these work.

Learnt from: CR
Repo: codeready-toolchain/cli-mcp-operator

Timestamp: 2026-08-19T00:04:43.043Z
Learning: Add or update tests for behavior changes.

Learnt from: CR
Repo: codeready-toolchain/cli-mcp-operator

Timestamp: 2026-08-19T00:04:43.043Z
Learning: Run the narrowest test first, then `make test` for the full unit gate.

Learnt from: CR
Repo: codeready-toolchain/cli-mcp-operator

Timestamp: 2026-08-19T00:04:43.043Z
Learning: Never commit, amend, or push unless the user explicitly asks in this turn

Learnt from: CR
Repo: codeready-toolchain/cli-mcp-operator

Timestamp: 2026-08-19T00:04:43.043Z
Learning: Do not commit secrets (HMAC keys, kubeconfigs, `.env`)

Learnt from: CR
Repo: codeready-toolchain/cli-mcp-operator

Timestamp: 2026-08-19T00:04:43.043Z
Learning: Do not weaken sandbox isolation, HMAC `/exec` auth, RBAC, or NetworkPolicy without an explicit human request

Learnt from: CR
Repo: codeready-toolchain/cli-mcp-operator

Timestamp: 2026-08-19T00:04:43.043Z
Learning: Ask before large architectural changes

🔀 Multi-repo context codeready-toolchain/mcp-server-devsandbox

Linked repositories findings

codeready-toolchain/mcp-server-devsandbox

• Existing agent guidance uses AGENTS.md as a symlink to CLAUDE.md, establishing a related MCP-server convention for shared instructions. [::codeready-toolchain/mcp-server-devsandbox::AGENTS.md]
• No changed APIs, shared contracts, or runtime dependencies were found in the linked repositories.

🔇 Additional comments (5)

.claude/commands (1)

1-1: LGTM!

.claude/skills (1)

1-1: LGTM!

.cursor/skills/use-modern-go/SKILL.md (1)

3-3: LGTM!

AGENTS.md (1)

1-46: LGTM!

CLAUDE.md (1)

1-1: LGTM!

---

Walkthrough

The repository adds shared Claude resource links, expands the modern Go skill description, and introduces project guidance in AGENTS.md with a reference from CLAUDE.md.

Changes

Agent guidance and shared resources

Layer / File(s)	Summary
Shared agent resources .claude/commands, .claude/skills, .cursor/skills/use-modern-go/SKILL.md	Claude command and skill directories link to Cursor resources. The modern Go skill now covers writing, editing, and reviewing Go code.
Project agent instructions AGENTS.md, CLAUDE.md	AGENTS.md documents project architecture, commands, workflows, safeguards, and maintenance rules. CLAUDE.md references AGENTS.md.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Merge Risk: ⚪ Minimal · up to 22081

This PR adds shared repository guidance and agent configuration without a supplied correctness, security, availability, or deployment risk; no actionable merge-blocking risk remains beyond normal checks and review.

Suggested labels: agentic, documentation

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the primary change: adding AGENTS.md as the shared agent contract.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/agent-harness

---

_{Comment @coderabbitai help to get the list of available commands.}