docs: share AGENTS.md guidance with Claude and Codex (ENG-748)

[Istvan Docsa (istvandocsa)]

Summary

Make AGENTS.md the canonical instruction entrypoint and keep Claude Code compatibility through a relative CLAUDE.md symlink. Both clients receive the same organization guidance in standalone clones and worktrees through checked-in snapshots maintained by the metarepo.

Preserve the existing repository instruction body, updating instruction references. Repositories without prior guidance receive an entrypoint. Large documents remain complete in a required reference rather than being truncated by Codex's automatic instruction budget.

Refs ENG-748; part of Codex alongside Claude.

Validation

• Original repository instructions preserved (apart from instruction paths); rule bodies preserved byte-for-byte where present.
• Metarepo bin/check-agent-guidance passes: entrypoints, portable snapshots, symlinks, required references, and rule routing.
• git diff --check passes; no .entire/ content in the diff.
• Documentation/tooling only; product behavior is unchanged.

Summary by CodeRabbit

• Documentation
  • Added repository guidance covering organization conventions, development workflows, tool usage, and workspace hygiene.
  • Documented Linear work-tracking practices, including hierarchy, issue lifecycle, acceptance criteria, and workstream structure.
  • Added maintained reference copies for Linear-related documentation.
  • Added an entry point directing contributors and automated agents to relevant repository guidance.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: e950b742-d13a-485c-bc75-6daac5ad3841

📥 Commits

Reviewing files that changed from the base of the PR and between 725b066 and 933e73b.

📒 Files selected for processing (6)

• AGENTS.md
• CLAUDE.md
• docs/agents/org-rules/linear-surfaces.md
• docs/agents/org-rules/linear.md
• docs/agents/org-rules/tool-usage.md
• docs/agents/organization.md

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds repository agent entrypoints and documentation for organization workflows, tool usage, and Linear tracking conventions. It also adds derived Linear skill and template surfaces.

Changes

Agent guidance

Layer / File(s)	Summary
Repository instruction entrypoints AGENTS.md, CLAUDE.md	AGENTS.md defines required guidance and repository preparation steps. CLAUDE.md points to AGENTS.md.
Organization and tool rules docs/agents/organization.md, docs/agents/org-rules/tool-usage.md	The documentation defines platform workflows, release and runner policies, UUID rules, .entire/ hygiene, and approved command-line tools.
Linear convention and derived surfaces docs/agents/org-rules/linear.md, docs/agents/org-rules/linear-surfaces.md	The canonical Linear rules define workstream structure, issue requirements, and lifecycle handling. The derived file records the related skill and templates.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 933e7

This change establishes shared agent-guidance entrypoints and documented workflow conventions without modifying runtime behavior. No current merge-readiness risk is identified.

🚥 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 summarizes the main change: sharing AGENTS.md guidance with Claude and Codex. It is concise, specific, and relevant to the documentation-only changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
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.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[Istvan Docsa (istvandocsa)]

CodeRabbit (@coderabbitai) full review

[coderabbitai]

✅ Action performed

Full review finished.