Claude Code: Agent Harness for WordPress

Focused entry for Claude Code. Full index and rules: docs/AGENTS.md. Do not duplicate the long docs index here; read that file for retrieval paths.

Maintenance: When stack pins, commands, or git summary change, update this file, root AGENTS.md, and .cursor/AGENTS.md, plus matching sections in docs/AGENTS.md as needed. See docs/agents/agent-contract.md (Cross-tool parity).

What this repo is

Local, disposable WordPress harness for coding agents. WordPress and MariaDB run in Docker on this machine; you reach the site through the wordpress MCP server (local WordPress MCP Adapter endpoint). The WordPress harness is localhost-only (not a production WordPress deploy); site/ is the public marketing page. This repository does not ship an MCP server, abilities framework, or WordPress plugin of its own.

MCP registration and scopes: docs/claude-code.md. Task contract: docs/agents/agent-contract.md.

What the MCP server gives you

The MCP Adapter's default server exposes three meta-tools, not one tool per capability:

• mcp-adapter-discover-abilities: list the abilities this site exposes
• mcp-adapter-get-ability-info: fetch one ability's input schema
• mcp-adapter-execute-ability: run an ability with parameters

So the loop is: discover, inspect the schema, execute. Do not assume ability names or parameters from memory; call get-ability-info when you are unsure. The abilities themselves come from the MS WP Abilities plugin and WordPress core (core/*).

Its rest-get and rest-write abilities bridge to any registered REST route, so reach for them before concluding something is not possible.

How to work on this site

• Inspect before you change. Read the current state of a post, setting or plugin before modifying it, and say what you found.
• Prefer WordPress-native APIs and established WordPress conventions over bespoke solutions. If core or the active theme already does something, use it.
• Write block markup. Content should be Gutenberg-compatible; create-post accepts markdown and converts it to native blocks server-side, which is usually the cleanest route.
• Follow WordPress coding standards in any PHP, JS or CSS you write.
• Default to drafts. Do not publish, delete or bulk-change anything unless the task asks for it.
• For content edits, patch-post-content is the surgical option; preview-post-update then apply-post-update is the staged one. State the proposed change in plain language and wait for a real answer before applying it. The approval gate (bin/ability-gate, wired in .claude/settings.json) also makes Claude Code ask before every write ability; do not route a write around it through ./bin/wp or rest-write.
• Destructive operations (trashing, deactivating plugins, changing site settings) need an explicit instruction first.

Infrastructure

docker-compose.yml, docker/, bin/ and .env are the environment, not the site. Do not change them for a content or site-building task. If a task really needs an infrastructure change, say so before making it.

The database and the WordPress install live in Docker volumes and are disposable: ./bin/reset destroys and rebuilds them. Do not treat anything in them as durable, and do not store anything there that is not reproducible.

Commands

./bin/setup               build, start and provision the stack
./bin/status              container, WordPress, ability and MCP health
./bin/connect             register MCP with Claude Code
./bin/connect --print     MCP URL + auth export (Codex / Cursor)
./bin/wp <wp-cli args>    WP-CLI inside the container
./bin/wp ability list     the abilities this site registers, without MCP
./bin/logs --debug        WordPress's own PHP debug log
./bin/seed                demo content for the examples (--remove deletes it)
./bin/audit               write abilities agents have called
./bin/test --skip-claude  layers 0–3 of the test suite

./bin/wp ability list and ./bin/wp ability run are the independent diagnostic path: if an ability works there but not over MCP, the problem is in the MCP layer, not in WordPress.

Skills

A curated subset of WordPress/agent-skills lives under .claude/skills/, linked per skill from .agents/skills/ (blocks, themes, plugins, REST, Abilities API, WP-CLI, router/triage). Use them for WordPress coding patterns.

They do not replace this stack. Site work still goes through the wordpress MCP abilities or ./bin/wp. Do not switch to @wordpress/env, WordPress Playground, or Blueprints for the local site; this repository's Docker Compose setup is the environment. Content and admin rules above still apply (drafts by default, inspect before change, no destructive ops without an explicit ask).

Boundaries

• Never expose this harness's MCP endpoint or WordPress site beyond localhost. Connecting an agent to a separate live site is documented in docs/remote-site.md and is outside the harness.
• Never put credentials in a tracked file. .env and .secrets/ are ignored and must stay that way; the Application Password lives in Claude Code's own config, outside this repository.
• Test content must be uniquely named and cleaned up. ./bin/reset is the only thing allowed to destroy unrelated development content.
• Never add agent attribution on commits or PRs.