# Product Requirements Document **Wursor** The Agentic WordPress Development Environment *Where WordPress products get built — code, site, and shipping in one loop.* | Field | Value | | :--- | :--- | | **Version** | 1.2 | | **Date** | August 13, 2026 | | **Author** | Patrick (Product Lead) | | **Status** | Draft — Internal (key decisions locked; Phase 0) | | **Repo** | SinachPat/wursor (renamed from originmain) | | **Classification** | Confidential | | **Supersedes** | v1.1 (renamed to Wursor; locked key decisions) | --- ## 1. Executive Summary Wursor 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." 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. Wursor makes that reality the environment: - 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:** 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 WordPress is a platform, not a folder of PHP 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 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`). 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 toolchain is fragmented | Concern | Typical tool today | | :--- | :--- | | Edit code | General IDE / editor | | Run site | Local WP, DDEV, Lando, wp-env, Docker | | 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 | 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 and product teams buy turnaround 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 Blast radius is real 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 Wursor 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. Wursor sits at the intersection of: | Category | What exists | What Wursor adds | | :--- | :--- | :--- | | 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 | **Positioning:** Wursor is the agentic **WordPress workshop** — not a generic coding assistant with a WordPress sticker, and not an AI writing widget inside wp-admin. --- ## 4. Target Users & Personas ### 4.1 Primary — Agency WordPress Engineer 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, wp-env, WPCS, tests, and release hygiene. Cares about headers, text domains, and build pipelines. ### 4.3 Secondary — Technical Founder / Solo Builder Runs a business on WordPress (WooCommerce, membership, LMS). Wants senior-WP leverage without a full bench. ### 4.4 Secondary — Design Engineer on Block Themes Lives in `theme.json`, patterns, and template parts. Needs structured edits plus visual proof. ### 4.5 Tertiary — Technical PM / Solutions Architect Scopes builds, reviews proposed changes, cares about migration plans and staging checks. **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 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** — The agent cannot mark a task "done" without a verify step (screenshot, HTTP check, or editor verification). Users may dismiss the proof; the agent may not skip producing it. 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. --- ## 6. Core Concepts & Mental Model ### 6.1 Workspace = Project + Site A **Workspace** binds: - 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) > **v1 scope (locked):** wp-env is the *only* supported runtime in v1. Local / DDEV / Bedrock import is P1 (§7.2.6). The runtime manager is still abstraction-bound (§8.1) so adding those backends later does not require a redesign. ### 6.2 WordPress Knowledge Graph Indexed understanding of: - Themes / child themes / active theme - Plugins (active, mu-plugins, drop-ins) - CPTs, taxonomies, REST routes - Hook registrations (best-effort from code) - Block inventory (`block.json`) - `theme.json` tokens and style variations - Template hierarchy for key routes **Build source (locked):** two passes. (1) *Static* — scan of `*.php`, `block.json`, `theme.json`, and plugin/theme headers at project open, refreshed on file-save and on git checkout. (2) *Runtime* — when the site is up, enrich via WP-CLI (`wp plugin list`, `wp theme list`, `wp post-type list`, `wp rewrite list`) with the *actual* active theme, active plugins, registered CPTs/taxonomies, and REST routes. **Freshness model:** every graph node carries a source stamp (static vs runtime) and timestamp. Both the agent context and the UI surface staleness explicitly (e.g., "active theme — static scan, site not loaded"). Full re-index runs on project open and on every `site.browse` boot; incremental updates follow file-save events. Runtime nodes are re-verified each time the site boots. ### 6.3 The build loop Plan → edit files → run WP-CLI / tests → refresh preview → read logs → revise. Every step uses WordPress-aware tools. ### 6.4 State Diffs When a task needs content or options changes, Wursor proposes a **State Diff**: WP-CLI commands and/or a migration script — never an invisible database tweak. The lifecycle is explicit: 1. **Create** — the agent generates a candidate diff (WP-CLI commands, SQL statements, or a PHP migration), each step annotated with intent and blast radius. 2. **Review** — shown in the State tab; every step expands to full text and effect; nothing runs without review. 3. **Stage** — approved steps form a numbered plan; steps can be reordered or dropped. 4. **Apply** — executes against the local environment by default; each step streams output and marks pass/fail. 5. **Verify** — the agent re-checks the site (option read-back, URL load, screenshot) before the diff counts as applied. 6. **Commit** — migration-style state scripts commit to the repo as `db/` migrations; pure WP-CLI plans persist as reviewable `.state-diff.json` artifacts under `.wursor/state-diffs/`. **Rollback (locked):** destructive steps must declare an inverse at create time (e.g., `wp option delete` paired with the prior value) or an explicit "manual backup required" acknowledgment; Wursor refuses to stage a destructive step without one. ### 6.5 Rules & Playbooks Project guidance lives in `WORDPRESS.md` / `.wursor/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 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 **P0** = launch-blocking · **P1** = ~30–60 days post-launch · **P2** = strategic ### 7.1 P0 — Launch Blocking #### 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`, `.wursor/rules`) #### 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 - Start/stop/reset via **wp-env** — the only supported runtime in v1 (the emitted Docker compose file is for debugging, not an alternative surface) - Embedded preview (front end + wp-admin) - Log tail (PHP / web server; Query Monitor later) - Runtime manager is abstraction-bound (§8.1); Local / DDEV import (P1) plugs in behind the same interface #### 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 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 - Verify runs by default on every agent task and is required before the agent marks a task "done" (Principle 5); users may dismiss the proof, the agent cannot skip producing it - Verify step: load URLs, screenshot, HTTP status + basic error sniff (PHP error log, 500s) - For block tasks: open editor routes and confirm the block can be inserted (lightweight P0) - Failures surface explicitly — "verify failed: /pricing returned 500" with the log excerpt — never a silent retry #### 7.1.7 Scaffolding playbooks - Plugin (headers, text domain, optional Composer/PHPUnit) - Static / dynamic block (`@wordpress/scripts`) - Child theme - CPT + REST + minimal admin UI #### 7.1.8 First-run experience - Install: single signed app bundle (macOS + Windows; Linux best-effort); no Docker prompt before first project open - First open: guided "open a project" with three paths — a WordPress repo (auto-detects wp-env config), a plain theme/plugin folder, or a built-in sample project - Dependency check: Docker / wp-env detection with one-click install guidance and a diagnostic panel — a dead end is not an option - First preview target: ≤ 10 minutes p50 from install to a live preview (§11) ### 7.2 P1 — Follow-on #### 7.2.1 Database & options introspection - Read-only schema explorer and options search - 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 - 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 + WordPress Coding Standards - PHPUnit / e2e hooks (Playwright or wp-env-based) - Agent runs configured gates before marking work done #### 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 - Live REST route list from the site - Assist for `add_action` / `add_filter` discovery #### 7.2.6 Import paths - Open Local WP / DDEV projects - Zero-config open for existing wp-env repos ### 7.3 P2 — Strategic - 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 Layers > **Shell decision (locked):** Desktop Electron app wrapping Code-OSS (VS Code's open-source editor core). Chosen because Wursor needs direct filesystem access, Docker socket control, embedded iframe preview, and native OS integration — a web IDE would require a local daemon layer that adds complexity with no benefit. The editor core is extended with Wursor panels and custom views, not abstracted from. | Layer | Responsibility | | :--- | :--- | | **Workspace shell** | Electron window, Code-OSS editor core, custom Wursor panels (preview, diff, state), terminal, git | | **WP language services** | PHP/JS, stubs, `block.json`, `theme.json` schemas | | **Site runtime manager** | wp-env/Docker lifecycle, ports, credentials (abstraction-bound for future backends) | | **Agent tool bus** | Files, WP-CLI, HTTP preview, DB read, linters (tool-calling interface, one schema per tool) | | **Knowledge index** | Code index + WP graph (static scan + runtime enrichment) | | **Policy engine** | Permissions, environment gates, secret redaction | | **Preview / verify** | Embedded browser, screenshots, HTTP checks, error sniff | | **Connectors** | GitHub, staging hosts, optional design tools | ### 8.1.1 Agent substrate (locked) - **Model:** Anthropic Claude (current best-in-class agentic coding); BYO API key at launch - **Routing:** All agent traffic goes through the user's own API key — no Wursor-hosted model tier in v1 - **Tool-calling protocol:** Every agent tool (§8.3) is a single tool schema, not a prompt chain. The agent calls tools; the tool bus executes against the local environment - **Fallback:** If the model is unreachable or returns an error, the agent panel shows a clear "Model unavailable" state with the raw error, logs, and a retry button. The workspace shell (editing, terminal, preview) remains fully functional - **P1 upsell:** Optional Wursor-hosted routing tier for users who prefer a managed key or bundled tokens ### 8.2 Default local stack - **wp-env** for local + CI parity (sole runtime in v1; runtime manager abstraction-bound for future backends) - MySQL as default; optional ultralight SQLite path for demos only - Node LTS for block builds ### 8.3 Initial agent tools - `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 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. ### 8.5 Error & offline states | State | What Wursor does | | :--- | :--- | | **Docker not installed** | Detect at project open; show diagnostic panel with one-click install guide; app remains usable for file editing and git | | **wp-env not found** | Offer to install via npm; fall back to npx | | **Site won't boot** | Stream logs live; highlight the first error; offer "reset" and "last known good config" | | **Model unreachable** | Show raw error + retry; workspace shell stays fully functional | | **API key invalid / expired** | Prompt for key update inline; no data loss | | **Network offline** | Cache last-known graph state; agent panel shows "offline" warning; local site and editing unaffected | | **File permission denied** | Surface the OS-level error; no silent fallback to a different path | --- ## 9. UX Notes - 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 type | Strength | Gap Wursor fills | | :--- | :--- | :--- | | 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 Wursor's v1 center | **Moat:** WP knowledge graph + controllable runtime + policy-aware tools + verify-via-preview, packaged as playbooks agencies and plugin teams repeat weekly. --- ## 11. Metrics & Success Criteria | Metric | Baseline | 6-month target | Owner | How we measure | | :--- | :--- | :--- | :--- | :--- | | Time to first local preview from new workspace | TBD (Phase 0 spike) | ≤ 10 min p50 | Eng lead | In-app timer from project open to first rendered preview | | Accepted agent runs on P0 playbooks (little rework) | TBD (alpha 1) | ≥ 60% | PM | Per-playbook accept/reject event, tagged by playbook | | Verify step catches issues before accept | TBD (alpha 1) | ≥ 30% of failing tasks | PM | Verify-fail event before accept, per task | | Trial → weekly habit by week 4 | TBD | ≥ 40% | PM | Weekly active usage per trial cohort | | Paying seats | n/a | TBD with pricing | GTM | Billing records | **Measurement plan:** all metrics instrumented from first alpha build (Phase 2). Every metric is a dashboarded event, not a manual tally. Baselines are collected during closed alpha (10–20 agencies / plugin teams) and reviewed as Phase 2 exit criteria. 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 prior product codebase - PRD + naming - Spike: wp-env control plane + agent tool bus ### Phase 1 — Foundation (weeks 1–8) - Ship Electron shell on Code-OSS (reused editor core; no greenfield chrome) - Project open + WP detection - wp-env lifecycle + preview - Agent chat + diffs + rules - WP-CLI tool + permission engine - P0 playbooks **Exit criteria:** a new user on a clean machine (no Docker, no wp-env) reaches a live preview of a WordPress repo in ≤ 10 minutes, and a P0 playbook (dynamic block) completes with a verified preview + accepted diff. ### Phase 2 — Intelligence (weeks 9–16) - Knowledge graph v1 (static + runtime passes) - WPCS / tests in the loop - State Diffs + read-only DB introspection - Careful staging pull - Closed alpha (10–20 agencies / plugin teams) **Exit criteria:** all §11 baselines collected and reviewed; knowledge graph staleness surfaced in UI; State Diff create→rollback loop demoed on a destructive option change. ### Phase 3 — Professional (weeks 17–28) - Block / FSE workshop - Role-based preview - Host deploy connectors - Shared team playbooks - Paid beta ### Phase 4 — Platform - WooCommerce, multisite, maintenance agents, ecosystem connectors --- ## 13. Risks & Mitigations | Risk | Impact | Mitigation | | :--- | :--- | :--- | | Building a full workspace is large | High | Electron shell on Code-OSS (reused editor core, not greenfield); WP runtime + tools get the focus | | Local Docker/wp-env pain (esp. Windows) | High | Diagnostics-first first-run; installer guides; early Local/DDEV import (P1) | | Agent harms a site | High | Permission tiers; local-default; production lock; State Diffs with rollback | | "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 | Resolved | Repo renamed to SinachPat/wursor | | Trademark / "WordPress" in marketing | Medium | Follow WordPress Foundation trademark rules | | LLM provider outage / model churn | Medium | BYO-key model; workspace shell stays usable offline; P1 hosted routing tier | | Docker Desktop licensing for commercial use | Low | Document; wp-env alternatives; Rancher Desktop path | --- ## 14. Decisions & Open Questions (Phase 0) ### Resolved (locked) 1. **Shell:** Electron desktop app on Code-OSS (VS Code's open-source editor core). Native filesystem, Docker socket, embedded preview, offline-capable. 2. **Name:** Wursor (locked in v1.2; no further rename planned). 3. **Repo:** renamed to `SinachPat/wursor`. 4. **Pricing:** seat-based ($X/dev/month, free tier with per-seat limits); agency teams primary. Final $X set during Phase 3 paid beta. 5. **Roots/Bedrock/Trellis support:** P1 (not v1). wp-env covers the launch segment; runtime manager is abstraction-bound for later import. 6. **Models:** Claude via BYO API key (v1); optional Wursor-hosted routing tier (P1 upsell). No local model support in v1. 7. **Runtime backends:** wp-env only in v1; Local / DDEV import is P1. ### Remaining (genuinely open) All Phase 0 questions are resolved above. New questions will be documented per phase and resolved before the next phase begins. --- ## 15. Appendices ### A. Glossary - **Workspace** — Project + site runtime + environment config bound together - **State Diff** — Reviewable WP-CLI / SQL / content mutation plan with a create→review→apply→rollback lifecycle - **Playbook** — Reusable agent workflow with tools and checks - **WP Knowledge Graph** — Map of themes, plugins, blocks, hooks, REST (static scan + runtime enrichment) - **Runtime** — The site execution environment (wp-env in v1) - **Environment** — A target (local / staging / production) with endpoints and policy - **Verify** — The proof step (screenshot / HTTP check / editor confirmation) required before a task is "done" - **FSE** — Full Site Editing (block themes) - **wp-env** — `@wordpress/env` local environment ### 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. 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 - A public extension/plugin API — connectors are internal; third-party integration ships after platform phase - Local / DDEV / Bedrock imports — P1 (§7.2.6) - Managed/hosted model tier — P1 upsell - **Accessibility certification (WCAG) or i18n / localization** — v1 is English-only with no formal accessibility conformance target. Basic keyboard navigation and screen reader support for the workspace shell are built in via Code-OSS; custom Wursor panels target standard web accessibility practices but will not be audited until Phase 3. ### C.1 Wursor's own test strategy - **Unit + integration tests** for the agent tool bus (each tool schema), the permission engine, and the State Diff lifecycle - **Fixture-based WP repos** in CI (wp-env in GitHub Actions) to test detection, indexing, and playbooks without a live install - **E2E smoke** on the Electron shell: open → detect → boot → preview → verify - **Release gates:** CI runs unit + integration on every PR; e2e before each release ### D. One-liner **Wursor is the agentic workshop for WordPress — code, WP-CLI, data, and a live site in one loop.** --- *End of PRD v1.2 — Wursor*