feat: add agents, claude MD and update readme

[laurelfulford]

All Submissions:

• Have you followed the Newspack Contributing guideline?
• Does your code follow the WordPress' coding standards and VIP Go coding standards?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?

Changes proposed in this Pull Request:

This PR adds an AGENTS.md and CLAUDE.md to provide AI coding agents with repo-specific guidance.

It also updates the README.md file with information that agents can glean from the theme's file structure and code, but humans may not as easily.

The CLAUDE.md simply references AGENTS.md, matching the pattern used in the parent workspace.

Closes: NPPD-1253

How to test the changes in this Pull Request:

1. Review AGENTS.md for accuracy against the codebase.
2. Review the updates to README.md for accuracy against the codebase.
3. Confirm CLAUDE.md contains only @AGENTS.md.

Other information:

• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your changes, as applicable?
• Have you successfully ran tests with your changes locally?

[Copilot]

Pull request overview

This PR adds AI agent-specific documentation to help AI coding assistants understand the newspack-theme repository structure, conventions, and common gotchas. It includes a new AGENTS.md file with repository-specific guidance, a CLAUDE.md file that references the AGENTS.md, and enhancements to README.md that provide detailed structural information about the theme's PHP files, SCSS organization, and child theme architecture.

Changes:

• Added AGENTS.md with repository-specific guidelines covering theme structure, build tooling, PHP architecture, and common development pitfalls
• Added CLAUDE.md that references AGENTS.md, following parent workspace pattern
• Enhanced README.md with detailed sections on repository structure, PHP file organization, SCSS directory layout, and child theme architecture

Reviewed changes

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

File	Description
AGENTS.md	New file providing AI agents with newspack-theme-specific guidelines including repository layout quirks, build tooling details, and common gotchas to avoid
CLAUDE.md	New file that references AGENTS.md, matching the pattern used in the parent workspace
README.md	Enhanced with detailed structural documentation including PHP file purposes, SCSS directory organization, and child theme architecture diagrams

---

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

[laurelfulford]

Thanks @rbcorrales! I made the couple tweaks Copilot suggested since they made sense; they seemed pretty low-risk (one word in the Agents, and a couple in the Readme) so I'm going to go ahead and merge 🙂

[github-actions]

Hey @laurelfulford, good job getting this PR merged! 🎉

Now, the needs-changelog label has been added to it.

Please check if this PR needs to be included in the "Upcoming Changes" and "Release Notes" doc. If it doesn't, simply remove the label.

If it does, please add an entry to our shared document, with screenshots and testing instructions if applicable, then remove the label.

Thank you! ❤️

[github-actions]

🎉 This PR is included in version 2.19.0-alpha.1 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀