docs: align agent coding principles

[proerror77]

Change contract

Make the Karpathy-inspired coding principles and Matt Pocock workflow explicit in project instructions that Codex loads, with AGENTS.md as the shared authority.

Out of scope

Hooks, runtime code, Crypto E2E changes, and global user-level AGENTS.

Dependencies and merge order

None.

Focused validation

• git diff --check origin/main...HEAD
• Exact changed-file check: .claude/CLAUDE.md, AGENTS.md, CLAUDE.md
• Deterministic check for all four named Karpathy-inspired principles
• Deterministic check for Matt workflow mapping and no Superpowers default
• Standards review: PASS

Rollout and rollback

No runtime impact. Revert this commit to roll back the instruction change.

Scope exception

None.

Summary by CodeRabbit

• Documentation

  • Updated project guidance with clearer instructions for planning, implementation, debugging, testing, and code review.
  • Added principles emphasizing simplicity, focused changes, explicit assumptions, and validation.
  • Consolidated references to shared development workflows for more consistent project maintenance.

• Chores

  • Refined internal contributor guidance without changing product functionality or user-facing behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2072757b-2cbf-4417-8533-b9382ddc1c69

📥 Commits

Reviewing files that changed from the base of the PR and between f91ac36 and d90662b.

📒 Files selected for processing (3)

• .claude/CLAUDE.md
• AGENTS.md
• CLAUDE.md

---

📝 Walkthrough

Walkthrough

The change centralizes agent workflow guidance in AGENTS.md, adds coding principles, and updates both Claude instruction files to reference the shared guidance.

Changes

Agent guidance

Layer / File(s)	Summary
Shared workflow and coding principles AGENTS.md	Maps request types to specific skills and adds principles for assumptions, simplicity, surgical edits, and validation planning.
Claude guidance references CLAUDE.md, .claude/CLAUDE.md	References the shared AGENTS.md guidance and replaces the prior Superpowers workflow instruction.

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

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and clearly reflects the documentation change to agent coding principles.
Description check	✅ Passed	The description follows the required template and fills each section with relevant, specific content.
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

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/agent-rules-karpathy

---

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.}