# WordPress Content Sync Implementation Roadmap

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement the linked plans task-by-task.

**Source Spec:** `docs/superpowers/specs/2026-04-25-wordpress-content-sync-design.md`

**Purpose:** Break the approved product design into independently shippable implementation plans.

## Delivery Strategy

Build the plugin in small vertical slices. Each slice must leave the repository in a working, testable state and must preserve the project agreements: PHPCS using `phpcs.xml`, PHPStan level 6 or higher, PHPUnit, secure nonce checks, sanitized input, escaped output, and no direct reliance on git or WP-CLI at runtime.

## Phase 1: Plugin Foundation

**Plan:** `docs/superpowers/plans/2026-04-26-wordpress-content-sync-foundation.md`

Creates the WordPress plugin skeleton, Composer/dev tooling, bootstrap loader, activation/deactivation hooks, service container, admin shell, settings persistence, logging, and initial PHPUnit coverage.

**Exit Criteria:**
- WordPress can load the plugin without fatal errors.
- Composer scripts exist for `lint`, `stan`, `test`, and `validate`.
- Admin menu renders a dashboard shell for users with `manage_options`.
- Plugin settings can be registered and read through a typed settings object.
- Unit tests pass for settings defaults, service registration, and logger behavior.

## Phase 2: URL Transformation

**Plan to create after Phase 1:** `docs/superpowers/plans/2026-04-26-wordpress-content-sync-url-transformer.md`

Adds domain mapping, URL replacement in post content, URL replacement inside serialized metadata, and GUID/permalink transformation rules.

**Exit Criteria:**
- Plain text URLs, HTML attributes, JSON strings, and serialized PHP arrays are transformed safely.
- Serialized data remains valid after replacement.
- Mapping supports multiple source/destination pairs.
- Tests cover escaped URLs, protocol-relative URLs, and nested metadata.

## Phase 3: Content Package Schema and File Transport

**Plan to create after Phase 2:** `docs/superpowers/plans/2026-04-26-wordpress-content-sync-file-transport.md`

Defines the sync package schema and implements export/import through JSON files for posts, pages, taxonomies, media metadata, and custom post type records.

**Exit Criteria:**
- Export produces a versioned JSON package with manifest, content records, taxonomy records, media records, and checksum metadata.
- Import validates schema before mutating data.
- Invalid files produce actionable admin errors without partial writes.
- File import uses WordPress nonce and capability checks.

## Phase 4: REST Transport

**Plan to create after Phase 3:** `docs/superpowers/plans/2026-04-26-wordpress-content-sync-rest-transport.md`

Adds authenticated REST endpoints and REST client support using WordPress application passwords.

**Exit Criteria:**
- Destination exposes secure receive/status endpoints.
- Source can test connection and send packages.
- REST failures surface typed errors and can fall back to file transport.
- Endpoint mutations validate permissions and request shape.

## Phase 5: Sync Engine and Content Handlers

**Plan to create after Phase 4:** `docs/superpowers/plans/2026-04-26-wordpress-content-sync-engine-handlers.md`

Implements orchestration, content extraction/import handlers, conflict detection, retries, progress state, and operation logs.

**Exit Criteria:**
- Push and pull operations can sync posts, pages, custom post types, taxonomies, metadata, and media records.
- Last-write-wins conflict behavior is logged.
- Partial failures preserve operation state.
- Long-running work is chunked to avoid memory exhaustion.

## Phase 6: Admin Workflow and Hardening

**Plan to create after Phase 5:** `docs/superpowers/plans/2026-04-26-wordpress-content-sync-admin-hardening.md`

Completes the admin UI, connection diagnostics, operation history, import/export screens, user-facing errors, debug logging controls, and smoke/integration tests.

**Exit Criteria:**
- Users can configure sync pairs, credentials, URL mappings, content type selection, and sync direction.
- Every state-changing admin action verifies nonce and capability.
- Output is escaped and input is sanitized.
- Manual smoke checklist covers production-to-staging, staging-to-production, REST, and file fallback.

## Cross-Phase Standards

- Keep implementation files under `src/` with namespace `WPContentSync`.
- Keep tests under `tests/Unit` and `tests/Integration`.
- Keep admin templates under `templates/admin`.
- Use `wpcs_` as the option/transient/action prefix for this plugin.
- Prefer interfaces at boundaries: settings storage, logger, transport, handlers, package validation.
- Never store raw application passwords in logs.
- Never mutate WordPress content from an unauthenticated request.
- Every plan should include test-first steps and exact verification commands.