Wursor — Agent Guide

This repository is Wursor, the agentic WordPress management platform. Before starting any non-trivial task, read this file and follow the skill routing below.

The product, in one line

Non-technical WordPress site owners describe what they want; Wursor makes it happen in a cloud sandbox, shows a live preview, and deploys on approval. The interface is chat → preview → approve. Nothing else.

Repo layout

api/               Node.js + TypeScript API server (empty until Phase 0 gate)
web/               React + TypeScript frontend (empty until Phase 0 gate)
plugin/            WordPress plugin (PHP) — empty until Phase 0 gate
infrastructure/    Docker images, warm pool, GC, deploy scripts
e2e/               Playwright + e2e/golden/ harness
spikes/            Phase 0 written results — gate before product code
docs/decisions/    Architecture Decision Records (0001–…)
PRD.md             Product requirements (v2.0 — non-technical-first)
IMPLEMENTATION.md  TDD build guide with 8-sprint Phase 1 plan
CHANGELOG.md       Keep-a-Changelog log of changes

Skill routing — use the precheck first

The .agents/skills/ directory is a family of rigor skills modeled on Cursor's pstack. The entry point for any non-trivial task is wursor-precheck — it routes to the right playbook and sets the verification bar.

Task shape	Skill
Any non-trivial task — start here	`wursor-precheck`
How does X work / why was Y built this way	`wursor-investigation`
A defect — reproduce, root-cause, fix	`wursor-bug-fix`
New behavior, TDD-first from a data shape	`wursor-feature`
Review a diff / PR across lenses	`wursor-review`
Any code change with a test path	`wursor-tdd`
Capture a reviewable decision trail	`wursor-decision-log`
Structure, tradeoffs, verification standards	`wursor-principles`

Hard rules

Tests first. No implementation without a failing test (see wursor-tdd). Coverage floors: api/ + web/ ≥ 90%, plugin/ ≥ 80%.
Prove it works. A task is not done on self-report — run the test, start the sandbox, hit the endpoint.
Non-technical-first. The user never sees a diff, a terminal, a settings screen, or an error log. If a change would leak engineer-only UI into the product, it's wrong.
Safety. Never touch a live WordPress site, production credentials, or real user data from this repo. Sandboxes are the only environment code runs against.
Decisions are logged. Non-trivial choices get a decision-log entry (see wursor-decision-log).

Stack notes

Backend: Node.js + TypeScript, Express/Fastify, PostgreSQL (Wursor data), Redis (SSE/queue)
Frontend: React + TypeScript, Vite
Sandboxes: Docker on VPS, pre-baked WordPress image, overlayfs layers, media proxied (not copied)
Plugin: standard WordPress PHP plugin, REST API + token auth
Tests: vitest (api, web), phpunit (plugin), Playwright (e2e)

2.9 KiB Raw Blame History