claude-plugin-wordpress-manager 2.9.0 → 2.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/CHANGELOG.md +73 -0
  2. package/agents/wp-content-strategist.md +58 -1
  3. package/agents/wp-distribution-manager.md +39 -6
  4. package/docs/GUIDE.md +145 -14
  5. package/docs/plans/2026-03-01-tier6-7-design.md +246 -0
  6. package/docs/plans/2026-03-01-tier6-7-implementation.md +1629 -0
  7. package/hooks/hooks.json +18 -0
  8. package/package.json +6 -3
  9. package/servers/wp-rest-bridge/build/tools/index.js +9 -0
  10. package/servers/wp-rest-bridge/build/tools/linkedin.js +203 -0
  11. package/servers/wp-rest-bridge/build/tools/schema.js +159 -0
  12. package/servers/wp-rest-bridge/build/tools/twitter.js +183 -0
  13. package/servers/wp-rest-bridge/build/wordpress.js +94 -0
  14. package/skills/wordpress-router/references/decision-tree.md +10 -2
  15. package/skills/wp-content-generation/SKILL.md +128 -0
  16. package/skills/wp-content-generation/references/brief-templates.md +151 -0
  17. package/skills/wp-content-generation/references/generation-workflow.md +132 -0
  18. package/skills/wp-content-generation/references/outline-patterns.md +188 -0
  19. package/skills/wp-content-generation/scripts/content_gen_inspect.mjs +90 -0
  20. package/skills/wp-content-repurposing/SKILL.md +13 -0
  21. package/skills/wp-content-repurposing/references/auto-transform-pipeline.md +128 -0
  22. package/skills/wp-content-repurposing/references/transform-templates.md +304 -0
  23. package/skills/wp-linkedin/SKILL.md +96 -0
  24. package/skills/wp-linkedin/references/linkedin-analytics.md +58 -0
  25. package/skills/wp-linkedin/references/linkedin-posting.md +53 -0
  26. package/skills/wp-linkedin/references/linkedin-setup.md +59 -0
  27. package/skills/wp-linkedin/scripts/linkedin_inspect.mjs +55 -0
  28. package/skills/wp-structured-data/SKILL.md +94 -0
  29. package/skills/wp-structured-data/references/injection-patterns.md +160 -0
  30. package/skills/wp-structured-data/references/schema-types.md +127 -0
  31. package/skills/wp-structured-data/references/validation-guide.md +89 -0
  32. package/skills/wp-structured-data/scripts/schema_inspect.mjs +88 -0
  33. package/skills/wp-twitter/SKILL.md +101 -0
  34. package/skills/wp-twitter/references/twitter-analytics.md +60 -0
  35. package/skills/wp-twitter/references/twitter-posting.md +66 -0
  36. package/skills/wp-twitter/references/twitter-setup.md +62 -0
  37. package/skills/wp-twitter/scripts/twitter_inspect.mjs +58 -0
@@ -39,6 +39,8 @@ const bufSiteClients = new Map();
39
39
  const sgSiteClients = new Map();
40
40
  const plSiteClients = new Map();
41
41
  const slackBotClients = new Map();
42
+ const liSiteClients = new Map();
43
+ const twSiteClients = new Map();
42
44
  let activeSiteId = '';
43
45
  const parsedSiteConfigs = new Map();
44
46
  const MAX_CONCURRENT_PER_SITE = 5;
@@ -111,6 +113,14 @@ export async function initWordPress() {
111
113
  await initSlackBotClient(site.id, site.slack_bot_token);
112
114
  logToStderr(`Initialized Slack Bot for site: ${site.id}`);
113
115
  }
116
+ if (site.linkedin_access_token) {
117
+ await initLinkedInClient(site.id, site.linkedin_access_token);
118
+ logToStderr(`Initialized LinkedIn for site: ${site.id}`);
119
+ }
120
+ if (site.twitter_bearer_token) {
121
+ await initTwitterClient(site.id, site.twitter_bearer_token);
122
+ logToStderr(`Initialized Twitter for site: ${site.id}`);
123
+ }
114
124
  }
115
125
  activeSiteId = defaultSite || sites[0].id;
116
126
  logToStderr(`Active site: ${activeSiteId}`);
@@ -234,6 +244,30 @@ async function initSlackBotClient(id, botToken) {
234
244
  });
235
245
  slackBotClients.set(id, client);
236
246
  }
247
+ async function initLinkedInClient(id, accessToken) {
248
+ const client = axios.create({
249
+ baseURL: 'https://api.linkedin.com/rest/',
250
+ headers: {
251
+ 'Content-Type': 'application/json',
252
+ 'Authorization': `Bearer ${accessToken}`,
253
+ 'LinkedIn-Version': '202401',
254
+ 'X-Restli-Protocol-Version': '2.0.0',
255
+ },
256
+ timeout: DEFAULT_TIMEOUT_MS,
257
+ });
258
+ liSiteClients.set(id, client);
259
+ }
260
+ async function initTwitterClient(id, bearerToken) {
261
+ const client = axios.create({
262
+ baseURL: 'https://api.twitter.com/2/',
263
+ headers: {
264
+ 'Content-Type': 'application/json',
265
+ 'Authorization': `Bearer ${bearerToken}`,
266
+ },
267
+ timeout: DEFAULT_TIMEOUT_MS,
268
+ });
269
+ twSiteClients.set(id, client);
270
+ }
237
271
  // ── Site Management ──────────────────────────────────────────────────
238
272
  /**
239
273
  * Get the active site's client, or a specific site's client
@@ -647,6 +681,66 @@ export async function makeSlackBotRequest(method, endpoint, data, siteId) {
647
681
  limiter.release();
648
682
  }
649
683
  }
684
+ // ── LinkedIn Interface ──────────────────────────────────────────
685
+ export function hasLinkedIn(siteId) {
686
+ const id = siteId || activeSiteId;
687
+ return liSiteClients.has(id);
688
+ }
689
+ export async function makeLinkedInRequest(method, endpoint, data, siteId) {
690
+ const id = siteId || activeSiteId;
691
+ const client = liSiteClients.get(id);
692
+ if (!client) {
693
+ throw new Error(`LinkedIn not configured for site "${id}". Add linkedin_access_token to WP_SITES_CONFIG.`);
694
+ }
695
+ const limiter = getLimiter(id);
696
+ await limiter.acquire();
697
+ try {
698
+ const response = await client.request({ method, url: endpoint, data: method !== 'GET' ? data : undefined, params: method === 'GET' ? data : undefined });
699
+ return response.data;
700
+ }
701
+ finally {
702
+ limiter.release();
703
+ }
704
+ }
705
+ export function getLinkedInPersonUrn(siteId) {
706
+ const id = siteId || activeSiteId;
707
+ const sites = JSON.parse(process.env.WP_SITES_CONFIG || '[]');
708
+ const site = sites.find((s) => s.id === id);
709
+ if (!site?.linkedin_person_urn) {
710
+ throw new Error(`LinkedIn person URN not configured for site "${id}". Add linkedin_person_urn to WP_SITES_CONFIG.`);
711
+ }
712
+ return site.linkedin_person_urn;
713
+ }
714
+ // ── Twitter/X Interface ─────────────────────────────────────────
715
+ export function hasTwitter(siteId) {
716
+ const id = siteId || activeSiteId;
717
+ return twSiteClients.has(id);
718
+ }
719
+ export async function makeTwitterRequest(method, endpoint, data, siteId) {
720
+ const id = siteId || activeSiteId;
721
+ const client = twSiteClients.get(id);
722
+ if (!client) {
723
+ throw new Error(`Twitter not configured for site "${id}". Add twitter_bearer_token to WP_SITES_CONFIG.`);
724
+ }
725
+ const limiter = getLimiter(id);
726
+ await limiter.acquire();
727
+ try {
728
+ const response = await client.request({ method, url: endpoint, data: method !== 'GET' ? data : undefined, params: method === 'GET' ? data : undefined });
729
+ return response.data;
730
+ }
731
+ finally {
732
+ limiter.release();
733
+ }
734
+ }
735
+ export function getTwitterUserId(siteId) {
736
+ const id = siteId || activeSiteId;
737
+ const sites = JSON.parse(process.env.WP_SITES_CONFIG || '[]');
738
+ const site = sites.find((s) => s.id === id);
739
+ if (!site?.twitter_user_id) {
740
+ throw new Error(`Twitter user ID not configured for site "${id}". Add twitter_user_id to WP_SITES_CONFIG.`);
741
+ }
742
+ return site.twitter_user_id;
743
+ }
650
744
  // ── Plugin Repository (External API) ────────────────────────────────
651
745
  /**
652
746
  * Search the WordPress.org Plugin Repository
@@ -1,4 +1,4 @@
1
- # Router decision tree (v16 — development + local environment + operations + multisite + CI/CD + monitoring + webhooks + content repurposing + programmatic SEO + content attribution + multi-language network + social/email distribution + search console + content optimization + analytics + alerting + workflows)
1
+ # Router decision tree (v18 — development + local environment + operations + multisite + CI/CD + monitoring + webhooks + content repurposing + programmatic SEO + content attribution + multi-language network + social/email distribution + search console + content optimization + analytics + alerting + workflows + LinkedIn + Twitter/X + content generation + structured data)
2
2
 
3
3
  This routing guide covers WordPress **development**, **local environment**, and **operations** workflows.
4
4
 
@@ -14,7 +14,7 @@ Keywords that indicate **local environment**:
14
14
  local site, Studio, LocalWP, Local by Flywheel, wp-env, local WordPress, start site, stop site, create local site, local development, symlink plugin, local database, switch PHP version, localhost, local preview, detect environment, WASM, SQLite local
15
15
 
16
16
  Keywords that indicate **operations**:
17
- deploy, push to production, audit, security check, backup, restore, migrate, move site, create post, manage content, site status, check plugins, performance check, SEO audit, WooCommerce, prodotto, ordine, coupon, negozio, catalogo, inventario, vendite, carrello, multisite, network, sub-site, sub-sito, domain mapping, super admin, network activate, monitor, uptime, health report, trend, scansione periodica, alerting, performance baseline, fleet, all sites, network health, cross-site, webhook, outbound notification, event propagation, Zapier, content sync, repurpose content, social posts from blog, content atomization, newsletter from posts, content distribution, programmatic SEO, template pages, city pages, location pages, bulk page generation, scalable landing pages, content ROI, attribution, which content drives sales, conversion tracking, UTM tracking, revenue per post, multilingual, multi-language, hreflang, international SEO, translate site, language sites, localize content, social publish, schedule post, Buffer, email campaign, Mailchimp, SendGrid, transactional email, content distribution, newsletter send, Google Search Console, GSC, keyword tracking, keyword rankings, search analytics, indexing status, URL inspection, sitemap submit, search performance, SERP data, optimize content, headline scoring, readability analysis, SEO score, content scoring, meta optimization, content freshness, content triage, bulk optimize, Flesch-Kincaid, keyword density, Google Analytics, GA4, traffic analytics, pageviews, sessions, user analytics, Plausible, privacy analytics, Core Web Vitals, CWV, LCP, INP, CLS, PageSpeed, page speed, site speed, performance score, Slack alert, email alert, notification channel, alert threshold, severity routing, escalation, incident notification, uptime alert, error alert, performance alert, scheduled report, health digest, alert cooldown, alert dedup, workflow trigger, automation, scheduled event, content lifecycle, cron trigger, hook trigger, workflow rule, automate, trigger management
17
+ deploy, push to production, audit, security check, backup, restore, migrate, move site, create post, manage content, site status, check plugins, performance check, SEO audit, WooCommerce, prodotto, ordine, coupon, negozio, catalogo, inventario, vendite, carrello, multisite, network, sub-site, sub-sito, domain mapping, super admin, network activate, monitor, uptime, health report, trend, scansione periodica, alerting, performance baseline, fleet, all sites, network health, cross-site, webhook, outbound notification, event propagation, Zapier, content sync, repurpose content, social posts from blog, content atomization, newsletter from posts, content distribution, programmatic SEO, template pages, city pages, location pages, bulk page generation, scalable landing pages, content ROI, attribution, which content drives sales, conversion tracking, UTM tracking, revenue per post, multilingual, multi-language, hreflang, international SEO, translate site, language sites, localize content, social publish, schedule post, Buffer, email campaign, Mailchimp, SendGrid, transactional email, content distribution, newsletter send, Google Search Console, GSC, keyword tracking, keyword rankings, search analytics, indexing status, URL inspection, sitemap submit, search performance, SERP data, optimize content, headline scoring, readability analysis, SEO score, content scoring, meta optimization, content freshness, content triage, bulk optimize, Flesch-Kincaid, keyword density, Google Analytics, GA4, traffic analytics, pageviews, sessions, user analytics, Plausible, privacy analytics, Core Web Vitals, CWV, LCP, INP, CLS, PageSpeed, page speed, site speed, performance score, Slack alert, email alert, notification channel, alert threshold, severity routing, escalation, incident notification, uptime alert, error alert, performance alert, scheduled report, health digest, alert cooldown, alert dedup, workflow trigger, automation, scheduled event, content lifecycle, cron trigger, hook trigger, workflow rule, automate, trigger management, LinkedIn, LinkedIn post, LinkedIn article, B2B social, pubblica LinkedIn, Twitter, X, tweet, thread, pubblica tweet, Twitter analytics, 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
18
18
 
19
19
  Keywords that indicate **development**:
20
20
  create block, block.json, theme.json, register_rest_route, plugin development, hooks, PHPStan, build, test, scaffold, i18n, translation, accessibility, a11y, headless, decoupled, WPGraphQL, CI, CD, pipeline, GitHub Actions, GitLab CI, deploy automatico, workflow, quality gate
@@ -116,6 +116,14 @@ Priority: `gutenberg` > `wp-core` > `wp-site` > `wp-block-theme` > `wp-block-plu
116
116
  → `wp-alerting` skill + `wp-monitoring-agent` agent
117
117
  - **Workflow trigger / automation / scheduled event / content lifecycle / cron trigger / hook trigger / workflow rule / automate / trigger management**
118
118
  → `wp-content-workflows` skill + `wp-site-manager` agent
119
+ - **LinkedIn / LinkedIn post / LinkedIn article / B2B social / pubblica LinkedIn**
120
+ → `wp-linkedin` skill + `wp-distribution-manager` agent
121
+ - **Twitter / X / tweet / thread / pubblica tweet / Twitter analytics**
122
+ → `wp-twitter` skill + `wp-distribution-manager` agent
123
+ - **genera contenuto / scrivi post / AI content / content brief / crea articolo / draft post / genera bozza**
124
+ → `wp-content-generation` skill + `wp-content-strategist` agent
125
+ - **structured data / Schema.org / JSON-LD / rich snippet / schema markup / dati strutturati**
126
+ → `wp-structured-data` skill + `wp-content-strategist` agent
119
127
 
120
128
  ## Step 2c: route by local environment intent (keywords)
121
129
 
@@ -0,0 +1,128 @@
1
+ ---
2
+ name: wp-content-generation
3
+ description: This skill should be used when the user asks to "generate content",
4
+ "write a blog post", "create an article", "AI content", "content brief", "draft
5
+ a post", "genera contenuto", "scrivi post", "crea articolo", "genera bozza",
6
+ "content pipeline", "create content from brief", or mentions AI-assisted content
7
+ creation for WordPress.
8
+ version: 1.0.0
9
+ ---
10
+
11
+ # WordPress Content Generation Skill
12
+
13
+ ## Overview
14
+
15
+ AI-driven content generation pipeline for WordPress. This skill guides Claude through a structured 7-step process: from content brief to published, SEO-optimized post with structured data. It uses existing MCP tools — no new tools are introduced.
16
+
17
+ ## When to Use
18
+
19
+ - User wants to create new blog posts or articles with AI assistance
20
+ - User has a content brief or topic and wants a full draft
21
+ - User asks for SEO-optimized content creation
22
+ - User wants to generate content with structured data included
23
+ - User mentions content pipeline, content brief, or AI writing
24
+
25
+ ## Content Generation vs Content Repurposing
26
+
27
+ | Need | Skill |
28
+ |------|-------|
29
+ | Create new original content from scratch | `wp-content-generation` (this skill) |
30
+ | Transform existing content for new channels | `wp-content-repurposing` |
31
+ | Edit/update existing posts | `wp-content` |
32
+ | Bulk page generation from templates | `wp-programmatic-seo` |
33
+
34
+ ## Decision Tree
35
+
36
+ 1. **What does the user need?**
37
+ - "write a post" / "create article" / "generate content" → Full Pipeline (Section 1)
38
+ - "content brief" / "what to write about" → Brief Creation (Section 2)
39
+ - "outline" / "structure" / "plan the article" → Outline Patterns (Section 3)
40
+ - "optimize" / "SEO" / "improve draft" → Integrate with `wp-content-optimization`
41
+
42
+ 2. **Run detection first:**
43
+ ```bash
44
+ node skills/wp-content-generation/scripts/content_gen_inspect.mjs [--cwd=/path/to/project]
45
+ ```
46
+ This checks for REST API access, GSC availability, and existing content volume.
47
+
48
+ ## The 7-Step Pipeline
49
+
50
+ ### Step 1: Brief
51
+ Define the content brief with target audience, goal, and constraints.
52
+ See `references/brief-templates.md`
53
+
54
+ **Input from user:**
55
+ - Topic or keyword
56
+ - Target audience
57
+ - Content goal (inform, convert, engage)
58
+ - Word count target (optional)
59
+
60
+ ### Step 2: Keyword Research
61
+ Use GSC data (if available) to identify keyword opportunities.
62
+
63
+ **Tools used:**
64
+ - `gsc_query_analytics` — find related queries with impressions and CTR
65
+ - `gsc_list_pages` — check existing content for the keyword to avoid cannibalization
66
+
67
+ **Fallback:** If GSC not configured, use the topic as primary keyword and suggest 3-5 related terms based on semantic analysis.
68
+
69
+ ### Step 3: Outline
70
+ Create a structured outline with H2/H3 hierarchy.
71
+ See `references/outline-patterns.md`
72
+
73
+ **Output:** Markdown outline with headings, key points per section, target word count per section.
74
+
75
+ ### Step 4: Draft
76
+ Generate the full draft following the outline.
77
+
78
+ **Writing guidelines:**
79
+ - Match the site's existing voice and tone (analyze recent posts)
80
+ - Include data, examples, and actionable takeaways
81
+ - Write naturally — avoid AI-typical phrases ("delve into", "it's important to note")
82
+ - Target the specified word count (default: 1,200-1,500 words)
83
+
84
+ ### Step 5: SEO Optimize
85
+ Apply on-page SEO using `wp-content-optimization` patterns.
86
+
87
+ **Checks:**
88
+ - Primary keyword in title, first paragraph, and 1-2 H2s
89
+ - Meta description (150-160 chars) with keyword
90
+ - Internal linking to 2-3 related posts (find via `wp_list_posts`)
91
+ - Image alt text with keyword
92
+ - Readability: short paragraphs, sub-headings every 300 words
93
+
94
+ ### Step 6: Structured Data
95
+ Add appropriate Schema.org markup using `sd_inject`.
96
+
97
+ **Auto-detection:**
98
+ - Contains FAQ section → FAQPage schema
99
+ - Is a how-to/tutorial → HowTo schema
100
+ - Default → Article schema
101
+
102
+ ### Step 7: Publish
103
+ Create the post via WordPress REST API.
104
+
105
+ **Tools used:**
106
+ - `create_content` — create the post (status: draft by default)
107
+ - `sd_inject` — add structured data
108
+ - User confirms before changing status to `publish`
109
+
110
+ ## Reference Files
111
+
112
+ | File | Content |
113
+ |------|---------|
114
+ | `references/generation-workflow.md` | Detailed 7-step pipeline with prompts and checkpoints |
115
+ | `references/brief-templates.md` | Brief templates for different content types |
116
+ | `references/outline-patterns.md` | Outline structures for articles, tutorials, listicles |
117
+
118
+ ## Recommended Agent
119
+
120
+ **`wp-content-strategist`** — coordinates the full pipeline, selects keywords, creates outlines, and manages the publish workflow.
121
+
122
+ ## Related Skills
123
+
124
+ - **`wp-content`** — content lifecycle management and editing
125
+ - **`wp-content-optimization`** — SEO scoring, readability analysis, meta optimization
126
+ - **`wp-search-console`** — keyword data for Step 2 (keyword research)
127
+ - **`wp-structured-data`** — schema injection for Step 6
128
+ - **`wp-content-repurposing`** — distribute published content to social/email channels
@@ -0,0 +1,151 @@
1
+ # Brief Templates
2
+
3
+ ## Template 1: Blog Post Brief
4
+
5
+ For informational articles, thought leadership, and evergreen content.
6
+
7
+ ```markdown
8
+ ## Content Brief: Blog Post
9
+
10
+ **Topic:** [Main subject]
11
+ **Primary Keyword:** [Target search term]
12
+ **Secondary Keywords:** [3-5 related terms]
13
+
14
+ **Audience:**
15
+ - Who: [Target reader persona]
16
+ - Knowledge level: [Beginner / Intermediate / Advanced]
17
+ - Pain point: [What problem does this solve?]
18
+
19
+ **Content Goal:**
20
+ - [ ] Inform (educational content)
21
+ - [ ] Convert (drive to product/CTA)
22
+ - [ ] Engage (build community/discussion)
23
+
24
+ **Format:** Blog post
25
+ **Word Count:** 1,200-1,500 words
26
+ **Tone:** [Informative / Casual / Professional / Technical]
27
+
28
+ **Key Points to Cover:**
29
+ 1. [Main point 1]
30
+ 2. [Main point 2]
31
+ 3. [Main point 3]
32
+
33
+ **Internal Links:** Link to [related post 1], [related post 2]
34
+ **CTA:** [What should the reader do next?]
35
+ **Schema Type:** Article
36
+ ```
37
+
38
+ ## Template 2: Tutorial Brief
39
+
40
+ For step-by-step guides and how-to content.
41
+
42
+ ```markdown
43
+ ## Content Brief: Tutorial
44
+
45
+ **Topic:** How to [achieve specific outcome]
46
+ **Primary Keyword:** "how to [action]"
47
+ **Secondary Keywords:** [related terms]
48
+
49
+ **Audience:**
50
+ - Who: [Target reader]
51
+ - Prerequisite knowledge: [What should they already know?]
52
+ - Expected outcome: [What will they be able to do after reading?]
53
+
54
+ **Content Goal:** Educate and enable
55
+ **Format:** Step-by-step tutorial
56
+ **Word Count:** 1,500-2,000 words
57
+ **Tone:** Instructive, encouraging
58
+
59
+ **Steps to Cover:**
60
+ 1. [Step 1: Setup/Prerequisites]
61
+ 2. [Step 2: First action]
62
+ 3. [Step 3: Next action]
63
+ 4. [Step 4: Verification/Testing]
64
+ 5. [Step 5: Troubleshooting common issues]
65
+
66
+ **Visuals Needed:**
67
+ - [ ] Screenshots for each step
68
+ - [ ] Final result image
69
+ - [ ] Before/after comparison
70
+
71
+ **Internal Links:** Link to [prerequisite guide], [advanced guide]
72
+ **CTA:** [Try the product / Read the next tutorial]
73
+ **Schema Type:** HowTo
74
+ ```
75
+
76
+ ## Template 3: Listicle Brief
77
+
78
+ For "N best/top/ways" format content.
79
+
80
+ ```markdown
81
+ ## Content Brief: Listicle
82
+
83
+ **Topic:** [N] [superlative] [subject] for [audience/purpose]
84
+ **Primary Keyword:** "[best/top] [subject]"
85
+ **Secondary Keywords:** [specific items in the list]
86
+
87
+ **Audience:**
88
+ - Who: [Target reader]
89
+ - Intent: [Research / Comparison / Discovery]
90
+
91
+ **Content Goal:** Inform + drive clicks to specific items
92
+ **Format:** Numbered list (N items)
93
+ **Word Count:** 1,000-1,800 words (depends on N)
94
+ **Tone:** Authoritative, concise
95
+
96
+ **List Items:**
97
+ 1. [Item] — [1-2 sentence reason for inclusion]
98
+ 2. [Item] — [reason]
99
+ 3. [Item] — [reason]
100
+ ...
101
+
102
+ **Per-Item Structure:**
103
+ - H2 heading with item name
104
+ - 100-200 word description
105
+ - Key benefit or differentiator
106
+ - Link (if external) or CTA (if internal)
107
+
108
+ **Schema Type:** Article (or ItemList if appropriate)
109
+ ```
110
+
111
+ ## Template 4: FAQ Content Brief
112
+
113
+ For frequently asked questions and knowledge base articles.
114
+
115
+ ```markdown
116
+ ## Content Brief: FAQ
117
+
118
+ **Topic:** [Subject area for questions]
119
+ **Primary Keyword:** "[subject] FAQ" or "[subject] questions"
120
+ **Secondary Keywords:** [specific questions as long-tail]
121
+
122
+ **Audience:**
123
+ - Who: [Customers / Prospects / Users]
124
+ - Stage: [Awareness / Consideration / Decision]
125
+
126
+ **Content Goal:** Answer common questions, reduce support load
127
+ **Format:** Q&A pairs
128
+ **Word Count:** 800-1,200 words
129
+ **Tone:** Helpful, authoritative, concise
130
+
131
+ **Questions to Answer:**
132
+ 1. What is [subject]?
133
+ 2. How does [subject] work?
134
+ 3. How much does [subject] cost?
135
+ 4. Is [subject] right for [audience]?
136
+ 5. How do I get started with [subject]?
137
+
138
+ **Per-Question Structure:**
139
+ - H3 heading with the question
140
+ - 50-150 word answer
141
+ - Link to detailed resource if available
142
+
143
+ **Schema Type:** FAQPage
144
+ ```
145
+
146
+ ## Using Briefs
147
+
148
+ 1. Select the appropriate template based on content format
149
+ 2. Fill in all fields with the user (or ask clarifying questions)
150
+ 3. Use the completed brief as input to Step 3 (Outline) of the generation pipeline
151
+ 4. Keep the brief alongside the published post for future optimization reference
@@ -0,0 +1,132 @@
1
+ # Generation Workflow
2
+
3
+ ## Full Pipeline: Brief → Publish
4
+
5
+ ### Step 1: Brief Creation
6
+
7
+ **Goal:** Define what to write and for whom.
8
+
9
+ **Prompt to user:**
10
+ > What topic would you like to write about? Who is your target audience?
11
+
12
+ **Brief structure:**
13
+ | Field | Description | Example |
14
+ |-------|-------------|---------|
15
+ | Topic | Main subject | "Benefits of cactus water for athletes" |
16
+ | Primary keyword | Target search term | "cactus water benefits" |
17
+ | Audience | Who reads this | Health-conscious millennials |
18
+ | Goal | Content purpose | Drive product page visits |
19
+ | Format | Content type | Blog post / Tutorial / Listicle |
20
+ | Word count | Target length | 1,200-1,500 words |
21
+ | Tone | Writing style | Informative, friendly, evidence-based |
22
+
23
+ ### Step 2: Keyword Research
24
+
25
+ **If GSC is available:**
26
+ 1. Run `gsc_query_analytics` for the primary keyword (last 90 days)
27
+ 2. Identify: current rankings, impressions, CTR
28
+ 3. Find related queries with high impressions but low CTR (optimization opportunities)
29
+ 4. Check for keyword cannibalization: `gsc_list_pages` filtered by keyword
30
+
31
+ **If GSC is not available:**
32
+ 1. Use the primary keyword as anchor
33
+ 2. Generate 5-7 semantically related terms
34
+ 3. Suggest long-tail variations (question-based: "how", "why", "what is")
35
+
36
+ **Output:** Primary keyword + 5-7 secondary keywords + 2-3 long-tail variations
37
+
38
+ ### Step 3: Outline Creation
39
+
40
+ **See `outline-patterns.md` for templates per content type.**
41
+
42
+ **Process:**
43
+ 1. Select outline pattern based on content format
44
+ 2. Create H2/H3 hierarchy with 5-8 main sections
45
+ 3. Assign word count targets per section
46
+ 4. Place keywords: primary in H1, secondary in H2s, long-tail in body
47
+ 5. Plan internal links: identify 2-3 existing posts to link to
48
+
49
+ **Quality check:**
50
+ - Does each section deliver standalone value?
51
+ - Is there a logical flow from introduction to conclusion?
52
+ - Are keywords placed naturally (not forced)?
53
+
54
+ ### Step 4: Draft Writing
55
+
56
+ **Writing process:**
57
+ 1. Write introduction: hook → context → promise (what reader will learn)
58
+ 2. Write each section following the outline
59
+ 3. Add data points, examples, or quotes where possible
60
+ 4. Write conclusion: summary → takeaway → CTA
61
+ 5. Self-review: cut filler, tighten sentences, check flow
62
+
63
+ **Voice calibration:**
64
+ - Analyze 2-3 recent posts from the site (use `wp_list_posts`)
65
+ - Match sentence length, vocabulary level, and tone
66
+ - Avoid: "delve into", "it's crucial to note", "in today's fast-paced world"
67
+ - Prefer: direct statements, active voice, specific numbers
68
+
69
+ ### Step 5: SEO Optimization
70
+
71
+ **Checklist:**
72
+ - [ ] Primary keyword in title (first 60 chars)
73
+ - [ ] Primary keyword in first paragraph
74
+ - [ ] Primary keyword in 1-2 H2 headings
75
+ - [ ] Meta description: 150-160 chars with keyword
76
+ - [ ] Internal links: 2-3 links to related posts
77
+ - [ ] Image alt text includes keyword variant
78
+ - [ ] Short paragraphs (2-4 sentences)
79
+ - [ ] Sub-headings every 250-350 words
80
+ - [ ] Total word count meets target
81
+
82
+ **Internal linking strategy:**
83
+ 1. Fetch recent posts: `wp_list_posts(per_page: 20, orderby: "relevance", search: PRIMARY_KEYWORD)`
84
+ 2. Select 2-3 most relevant posts
85
+ 3. Link naturally within content (not forced anchor text)
86
+
87
+ ### Step 6: Structured Data
88
+
89
+ **Auto-detect schema type from content:**
90
+
91
+ | Content Pattern | Schema | Tool Call |
92
+ |----------------|--------|-----------|
93
+ | Contains numbered steps / "how to" | HowTo | `sd_inject(post_id, "HowTo", {...})` |
94
+ | Contains Q&A pairs | FAQPage | `sd_inject(post_id, "FAQPage", {...})` |
95
+ | Default blog post | Article | `sd_inject(post_id, "Article", {...})` |
96
+
97
+ **Article schema (default):**
98
+ ```
99
+ sd_inject(post_id, "Article", {
100
+ headline: POST_TITLE,
101
+ image: FEATURED_IMAGE_URL,
102
+ datePublished: POST_DATE,
103
+ author: { "@type": "Person", "name": AUTHOR_NAME },
104
+ description: META_DESCRIPTION
105
+ })
106
+ ```
107
+
108
+ ### Step 7: Publish
109
+
110
+ **Pre-publish checklist:**
111
+ 1. Show draft to user for review
112
+ 2. Confirm title, excerpt, categories, tags
113
+ 3. Confirm featured image
114
+ 4. Confirm publish date (immediate or scheduled)
115
+
116
+ **Publish as draft first:**
117
+ ```
118
+ create_content(type: "post", title: TITLE, content: HTML_CONTENT, status: "draft",
119
+ excerpt: EXCERPT, categories: [CAT_IDS], tags: [TAG_IDS])
120
+ ```
121
+
122
+ **After user approval:**
123
+ ```
124
+ update_content(id: POST_ID, status: "publish")
125
+ ```
126
+
127
+ ## Post-Publish
128
+
129
+ After publishing, suggest:
130
+ 1. **Distribution:** Use `wp-content-repurposing` to create social/email variants
131
+ 2. **Monitoring:** Check GSC in 7-14 days for indexing and initial rankings
132
+ 3. **Optimization:** Re-optimize in 30 days based on search performance data