wursor/PRD.md

# Product Requirements Document

**Wordbench**

The Agentic WordPress Development Environment

*Cursor for how software gets built. WordPress for how the web gets published. Wordbench is both.*

| Field | Value |
| :--- | :--- |
| **Version** | 1.0 |
| **Date** | August 12, 2026 |
| **Author** | Patrick (Product Lead) |
| **Status** | Draft — Internal |
| **Repo** | SinachPat/originmain (pivoting; rename TBD) |
| **Classification** | Confidential |

---

## 1. Executive Summary

Wordbench is an agentic development environment purpose-built for WordPress. It takes everything that makes Cursor transformative for general software engineering — repo-aware chat, multi-file agents, inline edit, terminal control, diffs you can trust, project rules, and tool use — and rebuilds it around how WordPress actually works: themes, plugins, blocks, hooks, the template hierarchy, WP-CLI, MySQL state, staging/production, and the plugin/theme ecosystem.

Today, WordPress builders bounce between Local/DDEV, VS Code/PhpStorm, a browser admin, WP-CLI in a separate terminal, phpMyAdmin, and ChatGPT tabs that do not know their `functions.php` from a mu-plugin. Agents that are great at TypeScript are naïve about `add_action`, `block.json`, or why a change in `theme.json` did not appear on the front end.

Wordbench collapses that into one environment where:

- The **site is a first-class runtime** (local WordPress you can boot, browse, and reset), not just a folder of files.
- The agent understands **WordPress semantics** (hooks, template hierarchy, CPT/taxonomies, block editor, WooCommerce patterns), not only PHP/JS syntax.
- Changes are proposed as reviewable diffs against theme/plugin code **and** as intentional WP-CLI / database operations when state must change.
- Design-to-build for blocks and FSE themes is native: edit `theme.json`, register blocks, sync patterns, preview in an embedded site frame.
- Shipping means **environments** (local → staging → production), not only `git push`.

**The opportunity:** be the default professional environment for anyone who builds with WordPress in an agent-native world — agencies, product teams on WP headless/hybrid, plugin vendors, and ambitious solo builders.

---

## 2. Problem Statement

### 2.1 Cursor is general; WordPress is a platform

General coding agents treat a WordPress project like any PHP app. They miss:

- The split between **code** (themes/plugins) and **content/state** (posts, options, post meta, transients).
- **Load order** and hook timing (`plugins_loaded` vs `init` vs `wp_enqueue_scripts`).
- **Child themes**, template hierarchy, and block theme / classic theme dual world.
- **WP-CLI** as the real automation API.
- **Multisite**, capability checks, and nonce/auth patterns.
- **Gutenberg** block development (`block.json`, `render.php`, editor APIs).

Result: plausible patches that break production, enqueue assets wrong, or bypass APIs the platform already provides.

### 2.2 The WordPress toolchain is fragmented

A typical build involves:

| Concern | Today's tool |
| :--- | :--- |
| Edit code | VS Code / PhpStorm |
| Run site | Local WP, DDEV, Lando, wp-env, Docker |
| Admin / content | wp-admin in browser |
| Automate | WP-CLI in another terminal |
| DB | phpMyAdmin / TablePlus |
| AI | Cursor/ChatGPT without site context |
| Deploy | FTP, rsync, Git push + host pipelines, ManageWP |

Context dies at every boundary. The agent cannot open wp-admin, inspect the REST schema of *this* site, or verify a block in the editor.

### 2.3 Agencies sell velocity; the stack sells friction

WordPress agencies and product studios compete on turnaround. Their bottleneck is not "writing PHP" — it is environment spin-up, safe changes across code+DB, regression checks on real themes, and handoff between design, content, and engineering. Existing AI features in hosts (e.g. copy helpers) do not replace an engineering environment.

### 2.4 Security and blast radius

WordPress sites are high-value attack surfaces. Unconstrained agents that edit `wp-config.php`, install plugins from arbitrary zips, or run SQL are dangerous. Wordbench must make **safe-by-default agent permissions** a product feature, not an afterthought.

---

## 3. Vision & Opportunity

**Vision:** Open a WordPress project in Wordbench the way you open a repo in Cursor — and the site boots, the agent already knows your theme/plugin map, and "add a pricing block that matches our patterns and ship it to staging" is one agent run with diffs + CLI + preview.

Wordbench occupies the intersection of:

| Category | Examples | Wordbench stance |
| :--- | :--- | :--- |
| AI code editors | Cursor, Windsurf, Copilot Workspace | Same agent UX ceiling; WP-native tools & runtime |
| Local WP environments | Local, DDEV, wp-env | Environment is embedded and agent-controllable |
| WP-specific IDEs / studios | Limited / aging | Modern agent-first, block-era native |
| Host AI / site copilots | Host dashboards | Dev environment, not marketing copy widgets |

**Differentiation:** Wordbench is not "ChatGPT in wp-admin." It is not "Cursor with a WordPress system prompt." It is an **environment** where code, runtime, CLI, database introspection, and preview share one agent loop.

---

## 4. Target Users & Personas

### 4.1 Primary — Agency WordPress Engineer

Builds custom themes/plugins for clients weekly. Lives in deadlines. Wants faster scaffolding, safer refactors, and less context switching. Comfortable with Git; allergic to FTP surprises.

### 4.2 Primary — Plugin / Block Product Developer

Ships commercial or open-source plugins and block libraries. Needs scaffolding, test runs, wp-env, WPCS, and release hygiene. Wants agents that respect plugin headers, text domains, and `@wordpress/scripts` build pipelines.

### 4.3 Secondary — Technical Founder / Solo Builder

Uses WordPress as the product surface (LMS, membership, WooCommerce). Wants Cursor-like leverage without hiring a full WP team.

### 4.4 Secondary — Design Engineer on Block Themes

Works in `theme.json`, patterns, and template parts. Needs visual preview + structured edits, not only raw PHP.

### 4.5 Tertiary — Technical PM / Solutions Architect

Scopes client builds, reviews agent diffs, cares about migration plans and staging verification.

**Non-goals for v1 users:** pure content editors who only need AI to write posts inside wp-admin (different product).

---

## 5. Product Principles

1. **Site is a runtime, not a folder** — If the agent cannot boot, browse, and assert against a real WordPress, it is guessing.
2. **Code and state are both first-class** — File diffs *and* explicit data/CLI operations; never silent DB mutation.
3. **WordPress semantics over generic PHP** — Prefer platform APIs, hooks, and block patterns the way a senior WP engineer would.
4. **Safe by default** — Capability-scoped tools; production gated; secrets redacted; destructive ops require confirmation.
5. **Preview is proof** — Agent claims are backed by screenshots, HTTP assertions, or editor canvas checks when possible.
6. **Git is the system of record for code** — Content/state migrations are exported as replayable WP-CLI scripts or migration packages, not tribal knowledge.
7. **Feels like Cursor** — Chat, inline edit, multi-file agent, rules, terminal, diffs — familiar UX, deeper WP tools underneath.

---

## 6. Core Concepts & Mental Model

### 6.1 Workspace = Project + Site

A Wordbench **Workspace** binds:

- A Git repo (theme, plugin, monorepo of plugins, or Bedrock/WordPress Composer layout)
- A **Site runtime** (wp-env, Docker, or imported Local/DDEV)
- Environment config (local/staging/production endpoints & credentials vault)

### 6.2 The WordPress Knowledge Graph

Indexed understanding of:

- Themes / child themes / active theme
- Plugins (active, mu-plugins, drop-ins)
- Registered CPTs, taxonomies, REST routes
- Hook map (approximate: from code analysis)
- Block library (`block.json` inventory)
- `theme.json` tokens and style variations
- Template hierarchy resolution for key routes

### 6.3 The Agent Loop (WP-native)

Plan → edit files → run WP-CLI / tests → refresh preview → read logs → revise. Tools are WordPress-aware (see §7).

### 6.4 Intent Diffs for State

When a task requires DB/content changes (create CPT seed data, flip an option, import a pattern), Wordbench proposes a **State Diff**: WP-CLI commands and/or a migration script the user can apply, review, and commit — not a hidden phpMyAdmin edit.

### 6.5 Rules & Playbooks

Cursor Rules equivalent: `WORDPRESS.md` / `.wordbench/rules` covering coding standards, agency patterns, banned functions (`extract`, direct SQL without `$wpdb->prepare`), and deploy checklists. **Playbooks** are reusable agent workflows ("scaffold a dynamic block", "migrate classic → block theme section").

### 6.6 Environments

Local (full control) → Staging (restricted agent: sync down, careful push) → Production (read + observe by default; write only with explicit break-glass).

---

## 7. Feature Requirements

Priority: **P0** launch-blocking, **P1** within ~30–60 days of launch, **P2** strategic.

### 7.1 P0 — Launch Blocking

#### 7.1.1 Cursor-class Editor UX
- Repo-aware chat with @-context (files, symbols, docs)
- Inline edit / Cmd-K style rewrite
- Multi-file agent mode with applyable diffs
- Terminal panel
- Git status, diff review, commit message assist
- Project rules (`.wordbench/rules`, `WORDPRESS.md`)

#### 7.1.2 WordPress Project Intelligence
- Auto-detect project shape: classic theme, block theme, single plugin, `wp-content` checkout, Bedrock/Composer
- Map active theme/plugins when site is connected
- PHP + JS (block) language support with WP stubs / wordpress-stubs integration
- Awareness of template hierarchy and `block.json` packages

#### 7.1.3 Embedded Local Site Runtime
- One-click (or one-command) local site via **wp-env** (default) and documented Docker compose escape hatch
- Start/stop/reset site from the IDE
- Embedded browser preview (front end + wp-admin)
- Log tail (PHP error log, web server; Query Monitor integration later)

#### 7.1.4 WP-CLI Tooling for Agents
- First-class WP-CLI runner tool with allowlist
- Common recipes: scaffold plugin/theme/block, rewrite flush, cache flush, plugin activate, db export/import (local only by default)
- Command preview before execute for destructive commands

#### 7.1.5 Safe Apply & Permissions
- Tool permission tiers: Read FS, Edit FS, Run WP-CLI (safe), Run WP-CLI (destructive), SQL read, SQL write, Network install
- Production write disabled by default
- Secret scanning on apply; redact `.env` / `wp-config` secrets in agent context by default

#### 7.1.6 Preview Verification
- After agent edits, optional "Verify" step: load URL(s), capture screenshot, basic console/network error sniff
- Block editor open-and-insert check for block tasks (P0 lightweight: open site editor / post editor URL)

#### 7.1.7 Scaffolding Playbooks
- New plugin (headers, text domain, composer/phpunit optional)
- New dynamic / static block (`@wordpress/scripts`)
- Child theme
- CPT + REST + basic admin UI (generate + wire)

### 7.2 P1 — Launch Critical Follow-on

#### 7.2.1 Database & Options Introspection
- Read-only schema explorer and options search
- "Explain this options row" with link back to plugin code when possible
- State Diff generator for option/post meta changes

#### 7.2.2 Block & FSE Workshop
- `theme.json` structured editor + agent tools
- Pattern library sync (export/import patterns as files)
- Visual select-an-element → jump to template part / block source (best-effort)

#### 7.2.3 Quality Gates
- PHPCS with WordPress Coding Standards
- PHPUnit / Playwright (or wp-env e2e) hooks
- Agent must run configured gates before "done" on PRs

#### 7.2.4 Staging Connectors
- Pull DB/media from staging (explicit, logged)
- Deploy code via GitHub Actions / host APIs (extendable)
- Never pull production DB without double confirm + scrubbing warnings

#### 7.2.5 Hook & REST Introspection
- List REST routes from living site
- Static analysis assist for `add_action` / `add_filter` registrations

#### 7.2.6 Migration from Existing Tools
- Import Local WP / DDEV project paths
- Open existing wp-env repos with zero config

### 7.3 P2 — Strategic

#### 7.3.1 WooCommerce-aware agent skills
#### 7.3.2 Multisite management tools
#### 7.3.3 Host marketplace integrations (WP Cloud, SpinupWP, Rocket.net, etc.)
#### 7.3.4 Collaborative multiplayer workspaces for agencies
#### 7.3.5 Autonomous "site maintenance agent" (updates, conflict triage) with strict sandboxes
#### 7.3.6 Design intake (Figma → block theme patterns) as an optional bridge
#### 7.3.7 Headless WP (Faust/Next) hybrid workspaces

---

## 8. Architecture & System Design

### 8.1 High-level

| Layer | Responsibility |
| :--- | :--- |
| **Editor shell** | Cursor-like IDE UX (files, chat, agent, terminal, git) |
| **WP language services** | PHP/JS + WP stubs, `block.json`, `theme.json` schemas |
| **Site runtime manager** | wp-env/Docker lifecycle, ports, credentials |
| **Agent tool bus** | File tools, WP-CLI, HTTP preview, DB read, linters |
| **Knowledge index** | Codebase index + WP graph (plugins, blocks, routes) |
| **Policy engine** | Permissions, environment gates, secret redaction |
| **Preview** | Embedded browser + screenshot/verify services |
| **Connectors** | GitHub, staging hosts, optional design tools |

### 8.2 Default local stack
- **wp-env** for reproducibility and CI parity
- SQLite integration option for ultralight demos (secondary); MySQL remains default for fidelity
- Node LTS for `@wordpress/scripts` block builds

### 8.3 Agent tools (initial set)
- `fs.read` / `fs.write` / `fs.apply_patch`
- `wpcli.run` (categorized)
- `site.browse` / `site.screenshot`
- `site.request` (front/REST)
- `db.query` (read-only default)
- `lint.phpcs` / `test.phpunit`
- `index.search` / `wp.graph.lookup`

### 8.4 Data flow (happy path)
1. User: "Add an FAQ accordion block to the theme and show it on /pricing."
2. Agent reads theme type, block build setup, existing patterns.
3. Scaffolds block, registers it, adds pattern or template reference.
4. Runs build + WP-CLI flush as needed.
5. Opens /pricing + editor insert path; screenshots.
6. Presents file diffs + optional State Diff; user approves.

---

## 9. Design System & UX Notes

- Dark-first IDE aesthetic (Cursor-familiar), dense but calm
- **Site status bar**: environment, WP version, active theme, agent permission mode
- **Diff view**: Files tab + State tab
- **Preview pane**: dockable; device widths; logged-in as role selector (Admin/Editor/Customer)
- Accessibility: full keyboard for chat/agent; don't trap focus in preview iframe without escape

---

## 10. Competitive Landscape

| Product | Strength | Gap vs Wordbench |
| :--- | :--- | :--- |
| Cursor | Best-in-class agentic coding | Not WP-runtime aware |
| VS Code + Copilot | Ubiquitous | Same fragmentation; weak WP semantics |
| PhpStorm | Deep PHP | Not agent-native; no WP site loop |
| Local WP | Easy site spin-up | Not a coding agent environment |
| wp-env / DDEV | Solid runtimes | CLI-centric, no agent UX |
| Host AI features | Convenient for content | Not engineering environments |
| Specialized WP AI plugins | In-admin helpers | No real IDE / Git / agent loop |

**Moat:** the closed loop of **WP knowledge graph + controllable runtime + policy-aware tools + verify-via-preview**, trained into playbooks agencies repeat daily.

---

## 11. Metrics & Success Criteria

| Metric | 6-month target | Notes |
| :--- | :--- | :--- |
| Time to first local site preview from new workspace | ≤ 10 minutes p50 | Including deps |
| Agent task success (user accepts without major rework) | ≥ 60% on P0 playbooks | Scaffold block, child theme, CPT |
| Verify step catches regressions before accept | ≥ 30% of failed tasks | Leading indicator of loop value |
| Weekly active paying seats | TBD after pricing | Agency team seats primary |
| Retention (trial → weekly habit by week 4) | ≥ 40% | Habit formation |

Qualitative bar: senior WP engineers say "it doesn't do dumb WordPress things."

---

## 12. Phased Roadmap

### Phase 0 — Pivot & Spec (now)
- Clear old Originmain codebase
- PRD + positioning + name finalization (**Wordbench** working title)
- Technical spike: wp-env control plane + agent tool bus

### Phase 1 — Foundation (Weeks 1–8)
- Editor shell (reuse strategy TBD: VS Code OSS vs cloud remote)
- Project open + WP detection
- wp-env lifecycle + preview iframe
- Chat + diffs + rules
- WP-CLI tool + permission engine
- P0 playbooks (plugin, block, child theme)

### Phase 2 — Intelligence (Weeks 9–16)
- WP knowledge graph v1
- PHPCS/WPCS + tests in agent loop
- State Diffs + DB introspection (read)
- Staging pull (careful)
- Closed alpha with 10–20 agencies/plugin teams

### Phase 3 — Professional (Weeks 17–28)
- Block/FSE workshop
- Role-based preview
- Host deploy connectors
- Team rules / shared playbooks
- Paid beta

### Phase 4 — Platform
- WooCommerce skills, multisite, maintenance agents, marketplace

---

## 13. Risks & Mitigations

| Risk | Impact | Mitigation |
| :--- | :--- | :--- |
| Building a full IDE is enormous | High | Start from VS Code OSS or equivalent shell; buy don't rebuild editor chrome |
| wp-env/Docker reliability on Win/macOS | High | First-class diagnostics; support DDEV import early |
| Agent damages sites | High | Permission tiers; local-default; production lock; State Diffs |
| "Just use Cursor + prompts" objection | Medium | Runtime+verify loop demos; playbooks that general agents fail |
| WordPress PHP legacy complexity | Medium | Stubs, WPCS, curated playbooks; don't claim magic on 10-year themes day one |
| Naming/repo still "originmain" | Low | Rename product + repo after PRD buy-in |
| WordPress trademark in marketing | Medium | Follow WordPress Foundation trademark policy |

---

## 14. Open Questions (resolve in Phase 0)

1. **Shell strategy:** VS Code OSS fork vs cloud-only web IDE vs thin client over remote VMs?
2. **Distribution:** Desktop-first (agency reality) vs browser-first?
3. **Final name** (Wordbench is working title) and whether to rename the GitHub repo.
4. **Pricing:** per seat vs per agency workspace vs usage on hosted runtimes.
5. **How much of Bedrock/Trellis/Roots stack to support on day one?**
6. **Model routing:** bring-your-own key vs hosted; default model mix.

---

## 15. Appendices

### A. Glossary
- **State Diff** — Reviewable proposal of WP-CLI/SQL/content mutations
- **Playbook** — Reusable agent workflow with tools + checks
- **WP Knowledge Graph** — Indexed map of theme/plugin/block/hook/REST reality
- **FSE** — Full Site Editing (block themes)
- **wp-env** — Official local environment tooling from WordPress / `@wordpress/env`

### B. P0 Playbook sketches
1. **Scaffold dynamic block** — detect build system → create-block or equivalent → register → build → verify insert in editor → diff
2. **Child theme** — scaffold → enqueue parent → template override → screenshot home
3. **CPT** — register → flush rewrites → seed via WP-CLI → REST check → diff

### C. Explicit non-goals (v1)
- Replacing wp-admin for content authors
- Automatic production hotfixes without human approval
- Full visual page builder competing with Elementor (enhance code-era WP first)
- Supporting every classic page builder's proprietary shortcodes equally on day one

### D. Positioning one-liner
**Wordbench is Cursor for WordPress — an agentic environment where your code, WP-CLI, database, and live site share one brain.**

---

*End of PRD v1.0 — Wordbench*