From 0f08ccea0737c2dafa834760d53908f21aa41b2b Mon Sep 17 00:00:00 2001 From: Osinachi Patrick Date: Wed, 12 Aug 2026 11:54:09 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20PRD=20v1.1=20=E2=80=94=20WordPress-nati?= =?UTF-8?q?ve=20voice,=20drop=20editor-clone=20framing?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- PRD.md | 447 +++++++++++++++++++++++++++--------------------------- README.md | 2 +- 2 files changed, 224 insertions(+), 225 deletions(-) diff --git a/PRD.md b/PRD.md index 20a493c..3fb2d6e 100644 --- a/PRD.md +++ b/PRD.md @@ -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* diff --git a/README.md b/README.md index e74ea35..8de5e98 100644 --- a/README.md +++ b/README.md @@ -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.