Content Hubs

Planning repository for the WordPress plugin Content Hubs.

This repo is intentionally starting with product, architecture, delivery, and QA documents before any plugin code is scaffolded. The goal is to give Claude Code and Codex a stable pre-code blueprint that can be used for implementation, review, and milestone tracking.

What We’re Building

Content Hubs is a WordPress plugin that turns an existing site’s category and tag structure into topic-driven hub experiences without changing existing post, page, or category URLs.

Instead of treating a blog as only a reverse-chronological feed, the plugin adds:

• a hub landing page that surfaces major topic areas
• individual hub pages built from mapped categories
• optional curated and auto-populated sections
• editorial gap signals for underdeveloped topics
• hub-specific SEO and structured data

The plugin is designed first for established WordPress sites where categories and tags already represent the core content architecture.

Why This Exists

Large WordPress sites often have good content but weak discoverability. As content volume grows, the default archive model stops being enough:

• users struggle to browse by topic
• category archives are useful but not editorially shaped
• internal linking opportunities stay underused
• content gaps are hard to see
• search engines get less clear topical structure than they could

Content Hubs addresses that by adding a structured presentation layer on top of native WordPress taxonomy, rather than replacing the site’s existing content model.

Benefits

• preserves existing URLs and taxonomy behavior
• works with the site’s current categories and tags
• gives editors a clearer topic-level organizational layer
• supports both lightweight auto hubs and more curated mature hubs
• improves the site’s ability to present topical depth
• surfaces missing-content opportunities inside wp-admin

Current Scope

Content Hubs is a WordPress plugin for building topic-based landing pages and hub pages on top of existing posts and categories, without changing existing URLs.

Core constraints from the source brief:

• WordPress 6.4+
• PHP 8.1+
• No custom post type for hubs
• No external APIs
• No Gutenberg block in v1
• Must coexist with major SEO plugins
• Hub URLs are additive only

Documentation Map

• Docs Index
• Implementation Blueprint
• Milestones And QA
• Source Spec Snapshot
• Agent Delivery Workflow
• Repo Workflow

Intended Workflow

1. Treat docs/source-spec-snapshot.md as the canonical source brief.
2. Start from docs/index.md when orienting a new human or coding agent.
3. Treat docs/implementation-blueprint.md as the pre-code engineering plan.
4. Treat docs/milestones-and-qa.md as the execution and verification checklist.
5. Use docs/agent-delivery-workflow.md for best practices when working with Claude Code and Codex.
6. Use docs/repo-workflow.md for lightweight Git and GitHub planning workflows.
7. Start code only after unresolved decisions in the blueprint are accepted or explicitly deferred.

Repo Status

• This repo began as a planning-first workspace.
• Git has been initialized locally.
• The first planning-doc baseline has been committed.
• No plugin scaffold has been created yet.