Add AGENTS and CLAUDE project files

[SamErde]

This pull request introduces comprehensive documentation for the Maester project, focusing on agent and repository conventions. The main addition is a detailed AGENTS.md file that outlines the project structure, build and test processes, CI/CD workflows, and conventions for both code and AI tooling. Additionally, a CLAUDE.md file is added to bridge Claude Code tooling with the canonical agent context.

Documentation and Project Structure:

• Added a new AGENTS.md file that provides an in-depth overview of the Maester project, including repository layout, build and packaging steps, test architecture, website and report generator details, CI/CD workflows, and coding conventions. This serves as the canonical, tool-agnostic agent context for the repository.

AI Tooling Integration:

• Introduced CLAUDE.md as a thin bridge that imports AGENTS.md for Claude Code compatibility, with guidance on maintaining tool-agnostic documentation in AGENTS.md and placing Claude-specific notes in CLAUDE.md.

Summary by CodeRabbit

• Documentation

  • Added canonical repository guidance for structure, build/test workflow, contribution conventions, and agent usage.
  • Added a Claude-specific entry point that points to the canonical agent context.
  • Added a repository restructure proposal with recommended layout and a phased migration plan.

• Chores

  • Updated ignore rules to exclude a local Claude configuration file from version control.

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 30374316-57b5-421f-8790-316fe75630b8

📥 Commits

Reviewing files that changed from the base of the PR and between e937fd9 and 133c546.

📒 Files selected for processing (4)

• .gitignore
• AGENTS.md
• CLAUDE.md
• docs/proposals/repo-restructure.md

✅ Files skipped from review due to trivial changes (4)

• .gitignore
• CLAUDE.md
• docs/proposals/repo-restructure.md
• AGENTS.md

---

📝 Walkthrough

Walkthrough

This PR adds agent context docs, ignores CLAUDE.local.md, and adds a repository restructure proposal covering current layout, target layouts, phased migration steps, and draft conventions.

Changes

Documentation additions

Layer / File(s)	Summary
AGENTS.md, CLAUDE.md, and gitignore AGENTS.md, CLAUDE.md, .gitignore	Adds AGENTS.md with repo map, build/packaging, tests, website, report generator, commands, CI/CD, and conventions; adds CLAUDE.md referencing AGENTS.md; ignores CLAUDE.local.md.
Current state and inventory docs/proposals/repo-restructure.md	Introduces the proposal, documents the current repository tree, and lists path consumers and layout discrepancies.
Candidate structures and migration plan docs/proposals/repo-restructure.md	Compares target directory structures and lays out the phased Candidate B migration plan with move steps, shim behavior, gitignore fixes, and validation gates.
Appendices and conclusion docs/proposals/repo-restructure.md	Adds proposed repository conventions, a draft file-placement decision procedure, and the closing document content.

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

Possibly related PRs

• maester365/maester#1786: Adds canonical agent-context entrypoints that complement the new AGENTS.md/CLAUDE.md split and related tool-specific projections.

Suggested reviewers: merill

🚥 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 accurately summarizes the main change by adding AGENTS.md and CLAUDE.md project files.
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 refactor/repository-structure

Warning

Tools execution failed with the following error:

Failed to run tools: 13 INTERNAL: Received RST_STREAM with code 2 (Internal server error)

---

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

[Copilot]

Pull request overview

This pull request adds repository/agent-context documentation files to help humans and AI tooling understand Maester’s layout, build/test workflows, and conventions, plus includes a detailed (non-binding) proposal document for a future repo restructure.

Changes:

• Added AGENTS.md as the canonical, tool-agnostic repository context and conventions reference.
• Added CLAUDE.md as a thin Claude Code bridge that imports AGENTS.md.
• Added a comprehensive restructure proposal doc and updated .gitignore to ignore a local Claude notes file.

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated no comments.

File	Description
docs/proposals/repo-restructure.md	Adds a detailed, explicitly “PROPOSAL” restructure plan and evidence inventory for future work.
CLAUDE.md	Adds a Claude Code entrypoint that imports the canonical agent context from AGENTS.md.
AGENTS.md	Adds the canonical repository map, build/test architecture, CI/CD overview, and conventions.
.gitignore	Ignores CLAUDE.local.md to avoid committing local Claude-specific notes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cloudflare-workers-and-pages]

Deploying maester with    Cloudflare Pages

Latest commit:	5e69f53
Status:	✅  Deploy successful!
Preview URL:	https://9c18cdef.maester.pages.dev
Branch Preview URL:	https://refactor-repository-structur.maester.pages.dev

View logs

[merill]

@SamErde thanks for this. I've been meaning too as well.

A quick note. Based on all the commentary around this, the recommendation appears to be to limit the agents.md to only about 20 lines, hand written and very precise.

if not it can lead to context bloat.

Right now it's mostly describing the project strucutre which I don't think is the right thing for the agents file. I think we should only add very specific instructions.

I would say that each line we add to agents.md should come through as an independant PR for review.

Refernces:

• https://arxiv.org/abs/2601.20404
• https://www.thoughtworks.com/radar/techniques/agent-instruction-bloat

[SamErde]

I think this will still be beneficial but have not had time to dig into it yet. If anyone is interested and would like to take over this enhancement, please feel free to do so! 😅