docs: add AGENTS.md + CLAUDE.md agent instructions

[pbean]

What

Adds the two root agent-instruction files this repo has been missing, plus one README wording fix they exposed.

AGENTS.md (94 lines) — what a coding agent needs before its first edit here:

• Hard invariants — the things that break silently: no LLM in the control loop, sessions complete only on hook Stop/window death, sprintstatus.advance() as the sole write path to the board, the _run_git chokepoint, new policy fields needing a settings/core.toml entry, canonical-vs-seeded skills, the --json schema contract, closed ExitCode allocation, tmux argv quarantine.
• Architecture — the two orthogonal seams (adapter axis / mux axis) and a module table, so an agent stops guessing which of ~35 modules owns a behavior.
• Dev environment, testing conventions, git/PR agreements, doctrine, docs index.

CLAUDE.md (7 lines) — @AGENTS.md plus the one Claude-Code-specific rule: never edit under .claude/; edit the canonical skill in src/bmad_loop/data/skills/ and run scripts/seed_skills.py.

Both were fact-checked line by line against the code — every claim traced to the module that enforces it, generic doctrine and CONTRIBUTING duplicates cut. All 12 relative links resolve.

The README fix (second commit — separable)

Auditing AGENTS.md against the code showed README.md:34 was wrong in both directions:

sprint-status.yaml is owned by the BMAD skills; the orchestrator only ever reads it.

The loop's dev skill doesn't touch sprint-status.yaml at all — it flips its story spec's frontmatter, and the engine mirrors that onto the board (engine.py _post_dev_state_sync → sprint_advance) before verify_dev gates on the stage. So the orchestrator plainly does write it. Replaced with the accurate invariant — advance() is the single idempotent, never-regress writer — which is also what AGENTS.md records.

Happy to drop that commit if you'd rather keep this PR to just the two new files.

Notes

• Docs only — no code, no tests, no CHANGELOG entry (contributor-facing, not a released behavior change).
• trunk check clean.

Summary by CodeRabbit

• Documentation
  • Added operational and architectural guidance for the bmad-loop project, including workflow rules, testing expectations, and contribution practices.
  • Added guidance for Claude Code on referencing project instructions and managing configuration changes.
  • Clarified that sprint status is synchronized with the board and re-verified after each session to prevent regressions.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 5875b0dc-1831-4459-8eae-a7270d293b58

📥 Commits

Reviewing files that changed from the base of the PR and between af6e1bc and 55ad58e.

📒 Files selected for processing (3)

• AGENTS.md
• CLAUDE.md
• README.md

---

Walkthrough

The PR adds repository-level agent guidance, documents bmad-loop architecture and development practices, adds Claude-specific instructions, and updates README wording to describe orchestrator-managed sprint-status synchronization and verification.

Changes

Repository guidance

Layer / File(s)	Summary
Operating contract and architecture AGENTS.md	Documents deterministic orchestration invariants, module responsibilities, environment commands, and testing constraints.
Contribution rules and documentation index AGENTS.md	Adds contribution agreements, engineering doctrine, and links to related documentation.
Agent entrypoint and status semantics CLAUDE.md, README.md	Adds canonical agent-instruction guidance and clarifies orchestrator writes and post-session verification for sprint-status.yaml.

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

Poem

A rabbit reads the rules with care,
Then hops through docs from here to there.
The sprint board marks each proper track,
While Claude finds guidance at its back.
Neat burrows, clear paths, no fuss—
The loop now knows what’s expected of us!

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/agents-claude-md

---

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

[greptile-apps]

Greptile Summary

Docs-only PR adding two root agent-instruction files (AGENTS.md and CLAUDE.md) and correcting a factual error in README.md. All technical claims were independently verified against the source code during review.

• AGENTS.md documents hard invariants, architecture, dev workflow, testing conventions, and a docs index; all 14+ relative links resolve to existing files, and every technical assertion (ExitCode values, _run_git chokepoint, sprint_advance write path, asyncio_mode, fixture names, etc.) was confirmed against the actual source.
• CLAUDE.md uses the @AGENTS.md include directive and adds one Claude Code–specific rule about never editing seeded skill forks under .claude/.
• README.md line 34 corrects the previously inaccurate claim that "the orchestrator only ever reads sprint-status.yaml" — engine.py's _post_dev_state_sync calls sprint_advance(), so the orchestrator plainly does write it; the new wording accurately reflects that flow.

Confidence Score: 5/5

Docs-only change with no runtime impact; all technical assertions cross-check against the source code.

Every factual claim in AGENTS.md was verified against the actual source — ExitCode values match cli.py exactly, _run_git lives in verify.py, sprint_advance is called from engine.py _post_dev_state_sync, asyncio_mode=auto is set in pyproject.toml, both conftest fixtures exist, and all 14+ relative links resolve to real files. The README correction is accurate. No code is modified.

Files Needing Attention: No files require special attention; all three changed files are documentation only.

Important Files Changed

Filename	Overview
AGENTS.md	New 94-line agent instructions file; all technical claims verified against the codebase (ExitCode values, _run_git chokepoint, sprint_advance write path, asyncio_mode, conftest fixtures, module table). All relative links resolve.
CLAUDE.md	New 7-line file using @AGENTS.md include directive plus one Claude Code–specific rule about canonical skill editing; scripts/seed_skills.py confirmed present.
README.md	Single bullet corrected from 'orchestrator only reads sprint-status.yaml' to the accurate description; confirmed by engine.py _post_dev_state_sync → sprint_advance() call chain.

_{Reviews (1): Last reviewed commit: "docs(readme): state the sprint-status si..." | Re-trigger Greptile}