Improve agent instructions with AGENTS.md as primary file

[wojtekn]

Related issues

• Related to improving coding agent effectiveness across the team (PCYsg-1bzA-p2)

Proposed Changes

This PR restructures and enhances the agent instruction files to follow industry best practices and improve coding agent effectiveness:

• Create AGENTS.md as primary file: Follows industry standard, making instructions accessible to all coding agents (Claude Code, Cursor, Windsurf, etc.)
• Remove symlink structure: Replaced symlinks with simple @AGENTS.md references in CLAUDE.md and .cursorrules for better cross-platform compatibility (Windows, repo sync)
• Add Common Pitfalls section: Documents WordPress Playground-specific gotchas and Electron architecture pitfalls that agents commonly encounter
• Add Git & PR Conventions: Specifies branch naming (add/, update/, fix/, etc.), commit message format, and PR workflow preferences
• Emphasize critical instructions: Strategic use of MUST/CRITICAL/IMPORTANT keywords to help agents distinguish critical requirements from suggestions

Testing Instructions

• Verify CLAUDE.md and .cursorrules are regular files (not symlinks) containing @AGENTS.md
• Verify AGENTS.md exists and contains comprehensive instructions
• Test with coding agents to ensure they properly load and follow the instructions

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

[wojtekn]

I tested those changes in Cursor and Claude Code and both pick the guidelines correctly.

[fredrikekelund]

I've adopted a convention that I originally picked up from @bcotrim where I use the Linear issue identifier as a branch prefix. Really clever approach, IMO. Maybe we can instruct the agent to ask for a Linear issue identifier before creating a branch and use it as the branch name prefix?

[sejas]

Let's include that as a second sentence here, something like:

Suggested change

	**Branches**: Create from `trunk` using dash-separated lowercase names with prefixes: `add/something-new`, `update/feature-xyz`, `delete/something-else`, `fix/foo-bar`, `release/1.7.8`
	**Branches**: Create from `trunk` using dash-separated lowercase names with prefixes: `add/something-new`, `update/feature-xyz`, `delete/something-else`, `fix/foo-bar`, `release/1.7.8`. When working on a Linear issue (STU-XYZ), include it in the branch name after the verb. Example: `add/stu-123-something-new`.

[wojtekn]

What convention would you use for PRs without a linear issue?

It would be nice to follow one convention as now we use multiple different ways:

[wojtekn]

@sejas thanks. On second thought, maybe we should drop the add/delete part, or move it to a place after the Linear code without a slash? I always preferred that style, but I'm no longer sure if it helps much.

For example:

• new-dark-mode
• improve-agent-instructions
• fix-login-bug
• add-logout-button
• stu-123-update-sync-feature

[gcsecsey]

I agree that adding the linear issue number as a prefix would be great, the Linear-generated branch names also use this pattern.

I don't have a strong opinion whether having a slash helps or not, I think having a verb at the beginning like add- or add/ helps to clarify the intent of the branch in both cases.

[sejas]

I think we can follow Linear’s suggested branch format, which starts with the Linear ID and then the slug, ideally we can include the verb: stu-123-add-something-new.

[wpmobilebot]

📊 Performance Test Results

Comparing a3fdb14 vs trunk

site-editor

Metric	trunk	a3fdb14	Diff	Change
load	2720.00 ms	2722.00 ms	+2.00 ms	⚪ 0.0%

site-startup

Metric	trunk	a3fdb14	Diff	Change
siteCreation	7094.00 ms	6084.00 ms	-1010.00 ms	🟢 -14.2%
siteStartup	3917.00 ms	3924.00 ms	+7.00 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)

[epeicher]

Thanks @wojtekn for applying this! I believe the main AGENTS.md is a living document that we should update constantly to adapt to our needs, and this PR introduces it. I have tested and confirmed that different agents can see the changes, so I think we can merge it and continue iterating.

Claude Code	Cursor using GPT-5.3 Codex

[sejas]

I tested the PR with Claude Code, and it loaded Agents.md into context without requiring any tool, and it was able to answer my questions:

Maybe we can mention the paths to AppData and the logs.

## WordPress Studio Paths

### App Data
- **macOS:** `~/Library/Application Support/Studio/appdata-v1.json`
- **Windows:** `C:\Users\<username>\AppData\Roaming\Studio\appdata-v1.json`

### Logs
- **macOS (release):** `~/Library/Logs/Studio/`
- **Windows:** `C:\Users\<username>\AppData\Roaming\Studio\logs\`

### Sites
- **All platforms:** `~/Studio/`

[sejas]

Let's include that as a second sentence here, something like:

Suggested change

	**Branches**: Create from `trunk` using dash-separated lowercase names with prefixes: `add/something-new`, `update/feature-xyz`, `delete/something-else`, `fix/foo-bar`, `release/1.7.8`
	**Branches**: Create from `trunk` using dash-separated lowercase names with prefixes: `add/something-new`, `update/feature-xyz`, `delete/something-else`, `fix/foo-bar`, `release/1.7.8`. When working on a Linear issue (STU-XYZ), include it in the branch name after the verb. Example: `add/stu-123-something-new`.

[gcsecsey]

LGTM and works great. I tested with Claude Code and the Codex app, to check different harnesses.

Claude Code	Codex (GPT-5.3)

[gcsecsey]

I agree that adding the linear issue number as a prefix would be great, the Linear-generated branch names also use this pattern.

I don't have a strong opinion whether having a slash helps or not, I think having a verb at the beginning like add- or add/ helps to clarify the intent of the branch in both cases.