[VIP-2845] Add agent documentation and skills infrastructure

[abdullah-kasim]

Description

This is a PR that adds AGENTS.md and some placeholder-ish skills.

Only way to test this is kinda to just develop a feature. Do not expect a perfect recollection from Claude from this, but do expect that the context that the AI has to initially hold become a lot smaller compared to putting everything in CLAUDE.md. Also, expect good recollection when you ask it to do one thing that matches the agent_docs, or if you reference agent_docs directly. It's almost like skills, but skills are actions, and these are more like memory files. Lastly, expect better code quality due to the smaller initial context 😊

My usual workflow would be:

1. Tell the agent to 'Do x, here's my wishlist: 1), 2), 3)`
2. Once the agent is done, Tell the agent Okay, add tests!
3. Do some manual e2e testing.
4. If bug found Okay I see some issue here, (show screenshot, paste json, etc) etc. Can you fix it and use a feedback loop?
5. Finally, I'd tell the agent to run linting.

I can only tell you that this has been my workflow for 2 months, and I haven't changed it. So the fact that I didn't change my workflow is amazing enough - I used to keep trying something new every 1 or 2 weeks, trying to make Claude remember. The only thing I stripped off from my actual workflow, is the YOLO mode notice, the auto-git-commit (in my actual workflow, the agent will commit on EVERY edit), and the communication style.

This workflow was based on https://href.li/?https://www.humanlayer.dev/blog/writing-a-good-claude-md .

Anyway, back to the PR, here's a few descriptions of the file added by this PR:

Universal layer (committed, works for any agent — Codex, CI, Claude):

• AGENTS.md — entry point with pre-task discovery and learning mode. As small as possible to reduce initial context size.
• CLAUDE.md — one-liner redirect to AGENTS.md
• agent_docs/ — topic files:
  • architecture.md — directory structure, key modules, entry points
  • commands.md — build, lint, test, dev commands with exact flags
  • coding.md — code principles and rules
  • linting.md — PHP/JS lint fix workflows
  • testing.md — PHPUnit conventions, runner, file patterns
  • feedback-loops.md — verification routing table (types → logs → CLI → REST → visual → tests → lint)
  • dev-environment.md — vip dev-env setup, WP-CLI, logs, database, shell, cron
  • visual-verification.md — REST API testing and browser automation (Claude Chrome + agent-browser)
  • MEMORY/* - Memory folder for the agent to auto-save what they've learned.

Skills (committed under .agents/skills/):

• lint/SKILL.md — PHP + JS lint commands
• setup-claude/SKILL.md — one-time .claude/skills symlink setup
• update-agent-context/SKILL.md — instructions for updating agent docs

Personal layer (gitignored via .gitignore updates):

• CLAUDE.local.md, agent_docs_local/, .claude/skills symlink

Pre-review checklist

• This change works and has been tested locally or in Codespaces (or has an appropriate fallback).
• This change has relevant unit tests (if applicable).
• This change has relevant documentation additions / updates (if applicable).
• I've created a changelog description that aligns with the provided examples.

[Copilot]

Pull request overview

Adds a structured “agent docs” + “skills” layer intended to reduce initial AI context while keeping task-specific guidance discoverable (AGENTS.md → agent_docs/ + .agents/skills).

Changes:

• Added AGENTS.md as the entrypoint for agent task discovery and “learning mode” memory capture.
• Added agent_docs/ topic docs covering architecture, commands, testing, linting, dev environment, feedback loops, and visual verification.
• Added .agents/skills/* markdown skills plus local-only overrides via .gitignore, and a CLAUDE.md redirect.

Reviewed changes

Copilot reviewed 13 out of 15 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
agent_docs/visual-verification.md	Documents REST and browser-based verification workflows.
agent_docs/testing.md	Documents PHPUnit conventions and test-running commands.
agent_docs/linting.md	Documents when/how to run linting and fix workflows.
agent_docs/feedback-loops.md	Defines a verification routing table/checklist for changes.
agent_docs/dev-environment.md	Captures vip dev-env usage, logs, DB, shell, and cron commands.
agent_docs/commands.md	Central reference for build/lint/test/dev commands.
agent_docs/coding.md	States coding principles and “no unrelated refactors” rule.
agent_docs/architecture.md	Summarizes repo layout and key modules/entry points.
agent_docs/MEMORY/.keep	Keeps the memory directory present in git.
CLAUDE.md	Redirects readers to AGENTS.md.
AGENTS.md	Agent entrypoint: discovery steps + learning mode memory format.
.gitignore	Ignores local agent overrides and the local Claude skills symlink.
.agents/skills/update-agent-context/SKILL.md	Skill instructions for updating agent docs/memory.
.agents/skills/setup-claude/SKILL.md	One-time setup steps for local .claude/skills symlink.
.agents/skills/lint/SKILL.md	Skill instructions for running formatter/lint/type checks.

---

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

[andrea-sdl]

Nitpick: we could also add Firefox MCP/Chrome DevTools MCP. They were quite useful in testing stuff.

[abdullah-kasim]

Those tools are more for debugging?

But that said, I don't have experience with either MCP tools, so maybe a good time to pick it up - I can see smaller feedback loops can be formed with those MCPs.

[andrea-sdl]

To me Claude Chrome equals using Chrome MCP, whereas Agent Browser feels more of a "drop-in", but at the end of the day, IMO they're all tools that the agent can use/rely to test the output. If we think about isolated environments then Agent Browser probably excels, but if we're thinking about local machines, then I think Claude Chrome (which is model-specific) could be sided with Firefox/Chrome MCP to make sure this is model-agnostic, that's how I was thinking about it.

[andrea-sdl]

here we could probably add an example on how to populate the env.php file locally so that the agent can add custom values to test in the WP Admin settings and in the site page.