WP-Content-Sync/docs/superpowers/plans/2026-04-26-wordpress-content-sync-implementation-roadmap.md

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.