pat/wursor
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity

docs: PRD v1.1 — WordPress-native voice, drop editor-clone framing

Browse Source
This commit is contained in:
Osinachi Patrick
2026-08-12 11:54:09 +01:00
parent 702ce4e9c1
commit 0f08ccea07
2 changed files with 224 additions and 225 deletions
Download Patch File Download Diff File Expand all files Collapse all files
PRD.md
+223 -224
View File
@@ -4,92 +4,91 @@
The Agentic WordPress Development Environment
*Cursor for how software gets built. WordPress for how the web gets published. Wordbench is both.*
*Where WordPress products get built — code, site, and shipping in one loop.*
| Field | Value |
| :--- | :--- |
| **Version** | 1.0 |
| **Version** | 1.1 |
| **Date** | August 12, 2026 |
| **Author** | Patrick (Product Lead) |
| **Status** | Draft — Internal |
| **Repo** | SinachPat/originmain (pivoting; rename TBD) |
| **Classification** | Confidential |
| **Supersedes** | v1.0 (removed editor-clone framing) |
---
## 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.
Wordbench is a development environment built for people who ship on WordPress. It combines an AI agent that can plan and edit real project code with a live WordPress runtime, WP-CLI, database awareness, and preview — so building a theme, plugin, or block is not split across five apps and a hope that the model "knows WordPress."
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.
WordPress work is not generic app development. The product surface is a CMS platform with themes, plugins, hooks, a block editor, content in MySQL, and a long tail of agency and product workflows. Today's stack forces builders to keep that reality in their head while jumping between an editor, a local site tool, wp-admin, a terminal for WP-CLI, and a database client.
Wordbench collapses that into one environment where:
Wordbench makes that reality the environment:
- 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`.
- A **site you can boot, browse, reset, and inspect** sits beside the code.
- The agent is taught **WordPress semantics** — template hierarchy, hooks, `block.json`, capabilities, text domains — not only PHP syntax.
- Changes show up as **reviewable code diffs** and, when content or options must move, as explicit **State Diffs** (WP-CLI / migration scripts), never silent database edits.
- **Blocks and block themes** are first-class: `theme.json`, patterns, template parts, and editor preview.
- **Environments matter**: local → staging → production, with write access gated by policy.
**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.
**The opportunity:** become the default professional workspace for WordPress product and agency teams in an agent-assisted era — without pretending WordPress is "just another repo."
---
## 2. Problem Statement
### 2.1 Cursor is general; WordPress is a platform
### 2.1 WordPress is a platform, not a folder of PHP
General coding agents treat a WordPress project like any PHP app. They miss:
Competent general coding agents still miss what breaks real WP projects:
- 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).
- **Child themes**, template hierarchy, and the dual world of classic vs block themes.
- **WP-CLI** as the practical automation layer.
- **Multisite**, capabilities, nonces, and auth patterns.
- **Block development** (`block.json`, `render.php`, editor scripts, `@wordpress/scripts`).
Result: plausible patches that break production, enqueue assets wrong, or bypass APIs the platform already provides.
The failure mode is confident patches that enqueue wrong, ignore APIs WordPress already provides, or "fix" a theme without ever loading the site.
### 2.2 The WordPress toolchain is fragmented
### 2.2 The toolchain is fragmented
A typical build involves:
| Concern | Today's tool |
| Concern | Typical tool today |
| :--- | :--- |
| Edit code | VS Code / PhpStorm |
| Edit code | General IDE / editor |
| 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 |
| Admin / content | wp-admin in a browser |
| Automate | WP-CLI in a separate terminal |
| Database | phpMyAdmin / TablePlus |
| Assist | Chat tools with no live site context |
| Deploy | FTP, rsync, Git + host pipelines, site managers |
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.
Every hop drops context. Nothing in that chain can scaffold a block, flush rewrites, open the editor, and prove the front end in one continuous run.
### 2.3 Agencies sell velocity; the stack sells friction
### 2.3 Agencies and product teams buy turnaround
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.
WordPress shops compete on speed and reliability. Friction is environment spin-up, safe changes across code and data, regression checks on real themes, and handoff between design, content, and engineering. Host "AI" features aimed at writing posts do not solve that.
### 2.4 Security and blast radius
### 2.4 Blast radius is real
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.
WordPress sites are high-value targets. An agent that can edit `wp-config.php`, install arbitrary zips, or run unchecked SQL is a liability. **Safe-by-default permissions** are a core product requirement.
---
## 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.
**Vision:** Open a WordPress project in Wordbench and you get a workspace that already understands the shape of the project, can start the site, and can take a job like "add a pricing block that matches our patterns and verify it on /pricing" through edit → CLI → preview → review in one place.
Wordbench occupies the intersection of:
Wordbench sits at the intersection of:
| Category | Examples | Wordbench stance |
| Category | What exists | What Wordbench adds |
| :--- | :--- | :--- |
| 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 |
| AI-assisted coding | General editors and agents | WP-native tools, playbooks, and site loop |
| Local WP environments | Local, DDEV, wp-env | Runtime embedded and controllable by the agent |
| In-admin AI helpers | Host and plugin copilots | Real engineering workspace (Git, diffs, tests), not post drafting |
| Block / theme tooling | `@wordpress/scripts`, theme.json editors | Unified with agent + live preview |
**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.
**Positioning:** Wordbench is the agentic **WordPress workshop** — not a generic coding assistant with a WordPress sticker, and not an AI writing widget inside wp-admin.
---
@@ -97,37 +96,37 @@ Wordbench occupies the intersection of:
### 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.
Ships custom themes/plugins for clients on deadline. Wants faster scaffolding, safer refactors, fewer context switches. Uses Git; distrusts mystery FTP deploys.
### 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.
Ships commercial or open-source plugins and block libraries. Needs scaffolding, wp-env, WPCS, tests, and release hygiene. Cares about headers, text domains, and 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.
Runs a business on WordPress (WooCommerce, membership, LMS). Wants senior-WP leverage without a full bench.
### 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.
Lives in `theme.json`, patterns, and template parts. Needs structured edits plus visual proof.
### 4.5 Tertiary — Technical PM / Solutions Architect
Scopes client builds, reviews agent diffs, cares about migration plans and staging verification.
Scopes builds, reviews proposed changes, cares about migration plans and staging checks.
**Non-goals for v1 users:** pure content editors who only need AI to write posts inside wp-admin (different product).
**Out of scope for v1:** content-only users who mainly need AI inside wp-admin to draft posts.
---
## 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.
1. **Site is a runtime, not a folder** — If it cannot boot, browse, and assert against WordPress, it is guessing.
2. **Code and state are both first-class** — File diffs and explicit State Diffs; no silent DB mutation.
3. **WordPress semantics over generic PHP** — Prefer platform APIs, hooks, and patterns a senior WP engineer would choose.
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.
5. **Preview is proof** — Prefer screenshots, HTTP checks, or editor verification over "trust me."
6. **Git records code; scripts record state** — Migrations and WP-CLI plans are reviewable artifacts.
7. **Opinionated for WordPress** — Defaults follow WPCS, wp-env, and block-era workflows; escape hatches exist but are not the center.
---
@@ -135,192 +134,192 @@ Scopes client builds, reviews agent diffs, cares about migration plans and stagi
### 6.1 Workspace = Project + Site
A Wordbench **Workspace** binds:
A **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)
- A Git project (theme, plugin, plugin monorepo, `wp-content` checkout, or Composer/Bedrock layout)
- A **site runtime** (wp-env by default; Docker / Local / DDEV import paths)
- Environment config (local / staging / production endpoints and a credentials vault)
### 6.2 The WordPress Knowledge Graph
### 6.2 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)
- CPTs, taxonomies, REST routes
- Hook registrations (best-effort from code)
- Block inventory (`block.json`)
- `theme.json` tokens and style variations
- Template hierarchy resolution for key routes
- Template hierarchy for key routes
### 6.3 The Agent Loop (WP-native)
### 6.3 The build loop
Plan → edit files → run WP-CLI / tests → refresh preview → read logs → revise. Tools are WordPress-aware (see §7).
Plan → edit files → run WP-CLI / tests → refresh preview → read logs → revise. Every step uses WordPress-aware tools.
### 6.4 Intent Diffs for State
### 6.4 State Diffs
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.
When a task needs content or options changes, Wordbench proposes a **State Diff**: WP-CLI commands and/or a migration script to review, apply, and commit — not an invisible database tweak.
### 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").
Project guidance lives in `WORDPRESS.md` / `.wordbench/rules` (standards, banned patterns, deploy checklists). **Playbooks** are reusable workflows: scaffold a dynamic block, spin a child theme, register a CPT, harden a plugin release.
### 6.6 Environments
Local (full control) → Staging (restricted agent: sync down, careful push) → Production (read + observe by default; write only with explicit break-glass).
- **Local** — full control for the agent under user policy
- **Staging** — sync down and careful promote
- **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.
**P0** = launch-blocking · **P1** = ~30–60 days post-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.1 Agentic editing workspace
- Project-aware chat with file/symbol/doc context
- Inline rewrite of selections
- Multi-file agent runs with reviewable patches
- Integrated terminal
- Git status, diff review, commit assist
- Project rules (`WORDPRESS.md`, `.wordbench/rules`)
#### 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.2 WordPress project intelligence
- Detect project shape: classic theme, block theme, single plugin, `wp-content` tree, Bedrock/Composer
- When the site is up: map active theme and plugins
- PHP + block JS support with WordPress stubs
- Template hierarchy and `block.json` awareness
#### 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.3 Embedded local site runtime
- Start/stop/reset via **wp-env** (default), with documented Docker compose escape hatch
- Embedded preview (front end + wp-admin)
- Log tail (PHP / web server; Query Monitor 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.4 WP-CLI as an agent tool
- Allowlisted WP-CLI runner
- Recipes: scaffold plugin/theme/block, rewrite flush, cache flush, activate plugins, local DB export/import
- Preview destructive commands before run
#### 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.5 Permissions & safety
- Tiers: read FS, edit FS, WP-CLI safe, WP-CLI destructive, SQL read, SQL write, network install
- Production writes off by default
- Redact secrets from `.env` / `wp-config` in agent context; scan on apply
#### 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.6 Preview verification
- Optional verify step: load URLs, screenshot, basic error sniff
- For block tasks: open editor routes and confirm the block can be inserted (lightweight P0)
#### 7.1.7 Scaffolding Playbooks
- New plugin (headers, text domain, composer/phpunit optional)
- New dynamic / static block (`@wordpress/scripts`)
#### 7.1.7 Scaffolding playbooks
- Plugin (headers, text domain, optional Composer/PHPUnit)
- Static / dynamic block (`@wordpress/scripts`)
- Child theme
- CPT + REST + basic admin UI (generate + wire)
- CPT + REST + minimal admin UI
### 7.2 P1 — Launch Critical Follow-on
### 7.2 P1 — Follow-on
#### 7.2.1 Database & Options Introspection
#### 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
- Explain an options row with link-back to plugin code when possible
- State Diff generation for options / post meta
#### 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.2 Block & FSE workshop
- Structured `theme.json` editing + agent tools
- Pattern export/import as files
- Best-effort jump from preview selection → template part / block source
#### 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.3 Quality gates
- PHPCS + WordPress Coding Standards
- PHPUnit / e2e hooks (Playwright or wp-env-based)
- Agent runs configured gates before marking work done
#### 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.4 Staging connectors
- Explicit, logged pull of DB/media from staging
- Deploy via GitHub Actions / host APIs
- Production DB pull requires 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.5 Hook & REST introspection
- Live REST route list from the site
- Assist for `add_action` / `add_filter` discovery
#### 7.2.6 Migration from Existing Tools
- Import Local WP / DDEV project paths
- Open existing wp-env repos with zero config
#### 7.2.6 Import paths
- Open Local WP / DDEV projects
- Zero-config open for existing wp-env repos
### 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
- WooCommerce-oriented skills
- Multisite tools
- Host integrations (WP Cloud, SpinupWP, Rocket.net, etc.)
- Team workspaces and shared playbooks for agencies
- Sandboxed maintenance agent (updates, conflict triage)
- Optional design intake (e.g. Figma → patterns)
- Headless / hybrid (Faust, Next) workspaces
---
## 8. Architecture & System Design
### 8.1 High-level
### 8.1 Layers
| 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 |
| **Workspace shell** | Files, agent chat, terminal, git, preview layout |
| **WP language services** | PHP/JS, 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) |
| **Agent tool bus** | Files, WP-CLI, HTTP preview, DB read, linters |
| **Knowledge index** | Code index + WP graph |
| **Policy engine** | Permissions, environment gates, secret redaction |
| **Preview** | Embedded browser + screenshot/verify services |
| **Preview / verify** | Embedded browser, screenshots, checks |
| **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
- **wp-env** for local + CI parity
- MySQL as default; optional ultralight SQLite path for demos only
- Node LTS for block builds
### 8.3 Agent tools (initial set)
### 8.3 Initial agent tools
- `fs.read` / `fs.write` / `fs.apply_patch`
- `wpcli.run` (categorized)
- `site.browse` / `site.screenshot`
- `site.request` (front/REST)
- `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.
### 8.4 Example flow
1. "Add an FAQ accordion block and show it on /pricing."
2. Detect theme type, build setup, existing patterns.
3. Scaffold and register the block; wire pattern or template.
4. Build assets; flush as needed via WP-CLI.
5. Load /pricing and editor insert path; capture proof.
6. Present file diffs (+ State Diff if any); user accepts.
---
## 9. Design System & UX Notes
## 9. 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
- Dark-first, dense workshop UI; calm over theatrical
- **Site status bar:** environment, WP version, active theme, permission mode
- **Diff view:** Files tab + State tab
- **Preview:** dockable; device widths; view-as role (Admin / Editor / Customer)
- Keyboard-complete for agent flows; escape hatch from preview focus
---
## 10. Competitive Landscape
| Product | Strength | Gap vs Wordbench |
| Product type | Strength | Gap Wordbench fills |
| :--- | :--- | :--- |
| 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 |
| General AI code editors | Strong general coding agents | No WordPress runtime loop or WP semantics |
| Classic PHP IDEs | Deep PHP tooling | Weak agent-native site loop |
| Local WP apps | Easy site spin-up | Not an engineering agent workspace |
| wp-env / DDEV | Solid runtimes | CLI-centric; no integrated agent UX |
| Host / plugin AI | Handy in wp-admin | Content-oriented; not Git/theme/plugin shipping |
| Page builders | Fast visual pages | Different paradigm; not Wordbench's v1 center |
**Moat:** the closed loop of **WP knowledge graph + controllable runtime + policy-aware tools + verify-via-preview**, trained into playbooks agencies repeat daily.
**Moat:** WP knowledge graph + controllable runtime + policy-aware tools + verify-via-preview, packaged as playbooks agencies and plugin teams repeat weekly.
---
@@ -328,47 +327,47 @@ Priority: **P0** launch-blocking, **P1** within ~30–60 days of launch, **P2**
| 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 |
| Time to first local preview from new workspace | ≤ 10 min p50 | Including deps |
| Accepted agent runs on P0 playbooks (little rework) | ≥ 60% | Block, child theme, CPT |
| Verify step catches issues before accept | ≥ 30% of failing tasks | Loop quality signal |
| Trial → weekly habit by week 4 | ≥ 40% | Retention |
| Paying seats | TBD with pricing | Agency teams primary |
Qualitative bar: senior WP engineers say "it doesn't do dumb WordPress things."
Qualitative bar: experienced WordPress engineers say it behaves like someone who has shipped WP for years.
---
## 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 0 — Pivot & spec (now)
- Clear prior product codebase
- PRD + naming
- 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 1 — Foundation (weeks 1–8)
- Workspace shell (implementation vehicle TBD: desktop vs web; prefer proven editor foundations over greenfield chrome)
- Project open + WP detection
- wp-env lifecycle + preview
- Agent chat + diffs + rules
- WP-CLI tool + permission engine
- P0 playbooks
### 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 2 — Intelligence (weeks 9–16)
- Knowledge graph v1
- WPCS / tests in the loop
- State Diffs + read-only DB introspection
- Careful staging pull
- Closed alpha (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 3 — Professional (weeks 17–28)
- Block / FSE workshop
- Role-based preview
- Host deploy connectors
- Shared team playbooks
- Paid beta
### Phase 4 — Platform
- WooCommerce skills, multisite, maintenance agents, marketplace
- WooCommerce, multisite, maintenance agents, ecosystem connectors
---
@@ -376,50 +375,50 @@ Qualitative bar: senior WP engineers say "it doesn't do dumb WordPress things."
| 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 |
| Building a full workspace is large | High | Reuse a mature editor foundation; invest in WP runtime + tools |
| Local Docker/wp-env pain (esp. Windows) | High | Diagnostics first; early Local/DDEV import |
| Agent harms a site | High | Permission tiers; local-default; production lock; State Diffs |
| "Prompts in my current editor are enough" | Medium | Demo the site loop and playbooks general setups fail |
| Legacy PHP / chaotic themes | Medium | Stubs, WPCS, honest limits; playbooks for clean paths first |
| Repo still named originmain | Low | Rename after name lock |
| Trademark / "WordPress" in marketing | Medium | Follow WordPress Foundation trademark rules |
---
## 14. Open Questions (resolve in Phase 0)
## 14. Open Questions (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.
1. **Shell:** desktop vs browser-first; which editor foundation to adopt?
2. **Name:** keep **Wordbench** or replace before public use?
3. **Repo rename** away from `originmain`?
4. **Pricing:** seat vs workspace vs hosted-runtime usage?
5. **Roots/Bedrock/Trellis** support depth for v1?
6. **Models:** BYO keys vs hosted; default routing?
---
## 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`
- **State Diff** — Reviewable WP-CLI / SQL / content mutation plan
- **Playbook** — Reusable agent workflow with tools and checks
- **WP Knowledge Graph** — Map of themes, plugins, blocks, hooks, REST
- **FSE** — Full Site Editing (block themes)
- **wp-env** — `@wordpress/env` local environment
### 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
### B. P0 playbook sketches
1. **Dynamic block** — detect build → scaffold → register → build → verify in editor → diff
2. **Child theme** — scaffold → enqueue parent → override template → 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
### C. Non-goals (v1)
- Replacing wp-admin for authors
- Unattended production hotfixes
- Competing with Elementor-class page builders as the core offer
- Equal-class support for every legacy builder shortcode ecosystem 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.**
### D. One-liner
**Wordbench is the agentic workshop for WordPress — code, WP-CLI, data, and a live site in one loop.**
---
*End of PRD v1.0 — Wordbench*
*End of PRD v1.1 — Wordbench*
README.md
+1 -1
View File
@@ -1,6 +1,6 @@
# Wordbench
**Working title.** Agentic WordPress development environment — Cursor-depth tooling, WordPress-native runtime.
**Working title.** Agentic WordPress development environment — code, live site, WP-CLI, and shipping in one loop.
> This repository previously contained **Originmain** (AI design-engineering canvas). That codebase was removed in the product pivot of August 2026.