claude-plugin-wordpress-manager 2.9.1 → 2.12.1

package/docs/plans/2026-03-01-tier6-7-design.md

@@ -0,0 +1,246 @@
+# Tier 6+7 Design — Distribution Completeness + Content Factory
+
+> **Approved:** 2026-03-01
+> **Target:** v2.10.0 → v2.12.0
+> **WCOP Score:** 8.8/10 → 9.2/10
+
+## Goal
+
+Complete the Distribution layer (8→9/10) with direct social APIs (LinkedIn + Twitter/X) and an auto-transform pipeline, then complete the Content Factory layer (9→10/10) with AI-driven content generation and structured data management.
+
+## Architecture
+
+Approach A — Connector-per-Platform. Each social API is a separate TypeScript tool file in `servers/wp-rest-bridge/build/tools/` with its own skill. Structured data uses 3 dedicated MCP tools. Content generation is procedure-based (Claude-native) with no new MCP tools.
+
+## Release Plan
+
+| Release | Focus | New Skills | New MCP Tools | Enhanced Skills |
+|---------|-------|------------|---------------|-----------------|
+| **v2.10.0** | Direct Social APIs | `wp-linkedin`, `wp-twitter` | 10 (5+5) | Router v17 |
+| **v2.11.0** | Auto-Transform Pipeline | — | 0 | `wp-content-repurposing` |
+| **v2.12.0** | Content Gen + Schema | `wp-content-generation`, `wp-structured-data` | 3 | Router v18 |
+
+**Totals (v2.9.1 → v2.12.0):**
+- Skills: 39 → 43 (+4 new, +1 enhanced)
+- MCP Tools: 132 → 145 (+13)
+- Router: v16 → v18
+- Hooks: 10 → 12 (+2)
+
+---
+
+## v2.10.0 — Direct Social APIs
+
+### LinkedIn MCP Tools (5) — `linkedin.ts`
+
+Namespace: `li_*`. Auth: OAuth 2.0 access token (`WP_SITES_CONFIG.linkedin_access_token`).
+
+| Tool | Description | Key Params |
+|------|-------------|------------|
+| `li_get_profile` | Authenticated user profile (name, headline, vanity URL) | — |
+| `li_create_post` | Create LinkedIn feed post (text, link, images) | `text`, `link_url?`, `image_url?`, `visibility` |
+| `li_create_article` | Publish long-form LinkedIn article | `title`, `body_html`, `thumbnail_url?` |
+| `li_get_analytics` | Post analytics (impressions, clicks, engagement rate) | `post_id?`, `period?` |
+| `li_list_posts` | List recent user posts with base metrics | `count?`, `start?` |
+
+### Twitter/X MCP Tools (5) — `twitter.ts`
+
+Namespace: `tw_*`. Auth: Bearer token + API key/secret (`WP_SITES_CONFIG.twitter_bearer_token`, `twitter_api_key`, `twitter_api_secret`).
+
+| Tool | Description | Key Params |
+|------|-------------|------------|
+| `tw_create_tweet` | Publish a tweet (text, media, thread reply) | `text`, `media_ids?`, `reply_to?` |
+| `tw_create_thread` | Publish a connected tweet thread | `tweets[]` |
+| `tw_get_metrics` | Tweet metrics (impressions, likes, retweets, replies) | `tweet_id` |
+| `tw_list_tweets` | List recent user tweets | `count?`, `since?` |
+| `tw_delete_tweet` | Delete a tweet | `tweet_id` |
+
+### Skill: `wp-linkedin`
+
+- **Triggers:** "LinkedIn", "pubblica su LinkedIn", "LinkedIn article", "LinkedIn post", "LinkedIn analytics", "B2B social"
+- **Sections:** LinkedIn setup (OAuth) → Posting (post vs article) → Analytics
+- **References:** `linkedin-setup.md`, `linkedin-posting.md`, `linkedin-analytics.md`
+- **Detection:** `linkedin_inspect.mjs`
+- **Agent:** `wp-distribution-manager`
+
+### Skill: `wp-twitter`
+
+- **Triggers:** "Twitter", "X", "tweet", "thread", "pubblica tweet", "Twitter analytics"
+- **Sections:** Twitter setup (API v2) → Single tweet → Thread → Analytics → Delete
+- **References:** `twitter-setup.md`, `twitter-posting.md`, `twitter-analytics.md`
+- **Detection:** `twitter_inspect.mjs`
+- **Agent:** `wp-distribution-manager`
+
+### Router v17
+
+Add 2 categories to `decision-tree.md` Step 2b:
+
+```
+- LinkedIn / LinkedIn post / LinkedIn article / B2B social / pubblica LinkedIn
+  → `wp-linkedin` skill + `wp-distribution-manager` agent
+- Twitter / X / tweet / thread / pubblica tweet / Twitter analytics
+  → `wp-twitter` skill + `wp-distribution-manager` agent
+```
+
+Keywords in Step 0 operations block: `LinkedIn, LinkedIn post, LinkedIn article, B2B social, pubblica LinkedIn, Twitter, X, tweet, thread, pubblica tweet, Twitter analytics`
+
+### Hooks (+2)
+
+| Hook | Type | Tool | Message |
+|------|------|------|---------|
+| `tw_delete_tweet` | PreToolUse prompt | `tw_delete_tweet` | Confirm tweet deletion |
+| `li_create_article` | PreToolUse prompt | `li_create_article` | Confirm LinkedIn article publication |
+
+### Agent Update: `wp-distribution-manager`
+
+Add to agent description: "Manages direct social publishing to LinkedIn and Twitter/X alongside existing Mailchimp, Buffer, and SendGrid channels."
+
+Add to monitoring areas or related skills: `wp-linkedin`, `wp-twitter`.
+
+---
+
+## v2.11.0 — Auto-Transform Pipeline
+
+### Enhancement: `wp-content-repurposing`
+
+Add new section "Auto-Transform Pipeline" to existing SKILL.md.
+
+**New references:**
+- `auto-transform-pipeline.md` — Template system for automatic blog→social format conversion
+- `transform-templates.md` — Ready-to-use templates: blog→tweet, blog→LinkedIn post, blog→LinkedIn article, blog→thread, blog→email snippet
+
+**Pipeline flow:**
+1. Fetch post via REST API (`wp/v2/posts/{id}`)
+2. Extract: title, excerpt, featured image, categories, tags, key quotes
+3. Apply platform template (configurable per channel)
+4. Output formatted content ready for `li_create_post` / `tw_create_tweet` / `tw_create_thread` / `buf_create_update` / `mc_set_campaign_content`
+
+**Templates include:**
+- Character limit enforcement per platform
+- Hashtag generation from post tags
+- CTA insertion patterns
+- Image sizing recommendations
+- Thread splitting logic (for long-form → Twitter thread)
+
+No new MCP tools — this is purely skill/reference enhancement.
+
+### Router
+
+No router change (v17 stays). The repurposing skill already has routing keywords.
+
+---
+
+## v2.12.0 — Content Generation + Structured Data
+
+### Skill: `wp-content-generation` (procedure-based)
+
+- **Triggers:** "genera contenuto", "scrivi post", "content brief", "crea articolo", "draft post", "AI content", "genera bozza"
+- **Procedure (Claude-native, no new MCP tools):**
+  1. **Brief intake:** topic, target audience, keywords, tone, length
+  2. **Keyword research:** use `gsc_*` tools for search volume and existing rankings
+  3. **Outline generation:** Claude generates H2/H3 structure with key points
+  4. **Draft writing:** Claude writes full post body following outline
+  5. **SEO optimization:** apply `wp-content-optimization` skill (readability, keyword density, headline scoring)
+  6. **Structured data:** apply `wp-structured-data` skill for JSON-LD injection
+  7. **Publish:** use `wp/v2/posts` to create draft or publish
+- **References:** `generation-workflow.md`, `brief-templates.md`, `outline-patterns.md`
+- **Detection:** `content_gen_inspect.mjs` (verifies wp/v2 access + optional GSC config)
+- **Agent:** `wp-content-strategist`
+
+### Structured Data MCP Tools (3) — `schema.ts`
+
+Namespace: `sd_*`. No external auth — operates on WordPress posts via REST API.
+
+| Tool | Description | Key Params |
+|------|-------------|------------|
+| `sd_validate` | Validate JSON-LD/Schema.org markup against Google specs | `url` or `markup` |
+| `sd_inject` | Inject/update JSON-LD structured data in a WordPress post/page | `post_id`, `schema_type`, `schema_data` |
+| `sd_list_schemas` | List Schema.org types present across the site with counts | `schema_type?` |
+
+### Skill: `wp-structured-data`
+
+- **Triggers:** "structured data", "Schema.org", "JSON-LD", "rich snippet", "schema markup", "dati strutturati"
+- **Sections:** Validate existing → Inject new → Audit site-wide
+- **Schema types covered:** Article, Product, LocalBusiness, Event, FAQ, HowTo, Organization, BreadcrumbList
+- **References:** `schema-types.md`, `validation-guide.md`, `injection-patterns.md`
+- **Detection:** `schema_inspect.mjs` (checks for existing schema plugins like Yoast, Rank Math)
+- **Agent:** `wp-content-strategist`
+
+### Router v18
+
+Add 2 categories to `decision-tree.md` Step 2b:
+
+```
+- genera contenuto / scrivi post / AI content / content brief / crea articolo / draft post / genera bozza
+  → `wp-content-generation` skill + `wp-content-strategist` agent
+- structured data / Schema.org / JSON-LD / rich snippet / schema markup / dati strutturati
+  → `wp-structured-data` skill + `wp-content-strategist` agent
+```
+
+Keywords in Step 0 operations block: `genera contenuto, scrivi post, AI content, content brief, crea articolo, draft post, genera bozza, structured data, Schema.org, JSON-LD, rich snippet, schema markup, dati strutturati`
+
+### Agent Update: `wp-content-strategist`
+
+Add to agent description: "Guides AI-driven content generation workflows and manages structured data markup for SEO-rich content."
+
+Add related skills: `wp-content-generation`, `wp-structured-data`.
+
+---
+
+## WCOP Score Impact
+
+| Layer | v2.9.1 | v2.12.0 | Delta |
+|-------|--------|---------|-------|
+| Content Factory | 9/10 | **10/10** | +1 (AI generation + structured data) |
+| Quality Assurance | 9/10 | 9/10 | — |
+| Distribution | 8/10 | **9/10** | +1 (direct social + auto-transform) |
+| Observability | 9/10 | 9/10 | — |
+| Automation | 9/10 | 9/10 | — |
+| **TOTAL** | **8.8** | **9.2** | **+0.4** |
+
+---
+
+## SiteConfig Extensions
+
+### v2.10.0
+```json
+{
+  "linkedin_access_token": "...",
+  "twitter_bearer_token": "...",
+  "twitter_api_key": "...",
+  "twitter_api_secret": "..."
+}
+```
+
+### v2.12.0
+No new SiteConfig keys — `sd_*` tools operate via existing WordPress REST API credentials.
+
+---
+
+## Files Created/Modified Summary
+
+### v2.10.0
+- **Create:** `servers/wp-rest-bridge/build/tools/linkedin.{ts,js,d.ts}`
+- **Create:** `servers/wp-rest-bridge/build/tools/twitter.{ts,js,d.ts}`
+- **Create:** `skills/wp-linkedin/` (SKILL.md + references/ + scripts/)
+- **Create:** `skills/wp-twitter/` (SKILL.md + references/ + scripts/)
+- **Modify:** `skills/wordpress-router/references/decision-tree.md` → v17
+- **Modify:** `hooks/hooks.json` → +2 hooks
+- **Modify:** `agents/wp-distribution-manager.md` → updated duties
+- **Modify:** `package.json` → v2.10.0
+- **Modify:** `CHANGELOG.md` → v2.10.0 entry
+
+### v2.11.0
+- **Modify:** `skills/wp-content-repurposing/SKILL.md` → +1 section
+- **Create:** `skills/wp-content-repurposing/references/auto-transform-pipeline.md`
+- **Create:** `skills/wp-content-repurposing/references/transform-templates.md`
+- **Modify:** `package.json` → v2.11.0
+- **Modify:** `CHANGELOG.md` → v2.11.0 entry
+
+### v2.12.0
+- **Create:** `servers/wp-rest-bridge/build/tools/schema.{ts,js,d.ts}`
+- **Create:** `skills/wp-content-generation/` (SKILL.md + references/ + scripts/)
+- **Create:** `skills/wp-structured-data/` (SKILL.md + references/ + scripts/)
+- **Modify:** `skills/wordpress-router/references/decision-tree.md` → v18
+- **Modify:** `agents/wp-content-strategist.md` → updated duties
+- **Modify:** `package.json` → v2.12.0
+- **Modify:** `CHANGELOG.md` → v2.12.0 entry