claude-plugin-wordpress-manager 2.12.2 → 2.13.0

package/skills/wp-content-pipeline/references/site-config-schema.md

@@ -0,0 +1,431 @@
+# Site Configuration Schema
+
+Schema reference for `.config.md` files -- per-site configuration that the `wp-content-pipeline` skill reads when processing briefs.
+
+Config files live in `.content-state/` with the naming pattern `{site_id}.config.md`. They are gitignored because they contain site-specific values (profile IDs, audience IDs) that vary per environment.
+
+---
+
+## File Format
+
+Each `.config.md` file consists of:
+
+1. **YAML frontmatter** between `---` delimiters (structured configuration)
+2. **Markdown body** after the closing `---` (free-form notes for Claude context)
+
+```
+---
+site_id: opencactus
+site_url: https://opencactus.com
+last_updated: 2026-03-02
+# ... other fields ...
+---
+
+## Notes
+
+Free-form context that Claude uses when generating or adapting content for this site...
+```
+
+---
+
+## Frontmatter Fields
+
+### `site_id`
+
+| Property | Value |
+|----------|-------|
+| Type | `string` |
+| Required | **Yes** |
+| Format | Lowercase alphanumeric with hyphens |
+| Example | `opencactus` |
+
+Unique identifier for the site. **Must match** the `id` field in the `WP_SITES_CONFIG` environment variable JSON array. This is how the pipeline resolves WordPress credentials (URL, username, app password) for API calls.
+
+### `site_url`
+
+| Property | Value |
+|----------|-------|
+| Type | `string` (URL) |
+| Required | **Yes** |
+| Format | `https://example.com` (no trailing slash) |
+| Example | `https://opencactus.com` |
+
+The public-facing URL of the WordPress site. Used for constructing internal links and verifying published content. Should match the `url` field in `WP_SITES_CONFIG`.
+
+### `last_updated`
+
+| Property | Value |
+|----------|-------|
+| Type | `string` (ISO 8601 date) |
+| Required | No |
+| Default | Date of file creation |
+| Example | `2026-03-02` |
+
+Date when this config was last reviewed or modified. Helps track staleness -- configs older than 90 days should be reviewed for accuracy.
+
+---
+
+### `brand` block
+
+Defines the brand voice and editorial identity for the site. These values provide Claude with the context needed to generate on-brand content.
+
+When `GenBrand` produces brand analysis output, those results map directly into this block. See [Integration Notes](#integration-notes) for the mapping.
+
+```yaml
+brand:
+  tone: professional, accessible, sustainability-focused
+  language: it
+  style_notes: |
+    Voice: warm but authoritative. Avoid corporate jargon.
+    Always emphasize the Sicilian heritage and natural ingredients.
+    Use "noi" (we) when referring to the company.
+    Sustainability is a core value, not a marketing angle.
+```
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `tone` | `string` | **Yes** | -- | Comma-separated tone descriptors. Used by Claude to calibrate writing style. Examples: `professional, warm`, `casual, witty`, `technical, precise` |
+| `language` | `string` | **Yes** | -- | ISO 639-1 language code for the site's primary content language. Affects content generation, SEO, and readability scoring |
+| `style_notes` | `string` (multi-line) | No | `null` | Free-form editorial guidelines in YAML literal block scalar (`|`) format. Can include voice rules, banned words, preferred terminology, formatting conventions. No length limit |
+
+---
+
+### `defaults` block
+
+Default values applied to briefs when the brief does not specify them explicitly. Brief-level values always override these defaults.
+
+```yaml
+defaults:
+  content_type: post
+  status: draft
+  categories:
+    - blog
+  author: editorial-team
+```
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `content_type` | `string` | No | `post` | Default WordPress content type: `post`, `page`, or any registered custom post type |
+| `status` | `string` | No | `draft` | Default WordPress post status: `draft`, `pending`, `publish`, `future`, `private` |
+| `categories` | `string[]` | No | `[]` | Default category slugs applied when a brief omits categories |
+| `author` | `string` | No | `null` | Default WordPress username or slug for post attribution. If `null`, uses the authenticated user from `WP_SITES_CONFIG` |
+
+---
+
+### `channels` block
+
+Configures external distribution channels for the site. Each sub-key is a channel name with its own configuration. The pipeline reads this block to determine which channels are available and their credentials.
+
+```yaml
+channels:
+  linkedin:
+    enabled: true
+    profile_id: "urn:li:person:AbCdEf123"
+    format: professional
+  twitter:
+    enabled: true
+    format: concise
+  buffer:
+    enabled: false
+    profile_id: "buf_profile_abc123"
+    format: casual
+  mailchimp:
+    enabled: true
+    audience_id: "mc_aud_xyz789"
+    segment: newsletter-subscribers
+```
+
+#### Channel: `linkedin`
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `enabled` | `boolean` | **Yes** | -- | Whether LinkedIn distribution is active for this site |
+| `profile_id` | `string` | Yes (if enabled) | -- | LinkedIn profile URN. Required by `li_create_post` MCP tool. Format: `urn:li:person:XXXXX` or `urn:li:organization:XXXXX` |
+| `format` | `string` | No | `professional` | Content adaptation style: `professional`, `thought-leadership`, `casual` |
+
+#### Channel: `twitter`
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `enabled` | `boolean` | **Yes** | -- | Whether Twitter/X distribution is active for this site |
+| `format` | `string` | No | `concise` | Content adaptation style: `concise`, `thread`, `conversational` |
+
+**Note:** Twitter tools (`tw_create_tweet`, `tw_create_thread`) authenticate via the MCP server configuration, so no `profile_id` is needed here.
+
+#### Channel: `buffer`
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `enabled` | `boolean` | **Yes** | -- | Whether Buffer distribution is active for this site |
+| `profile_id` | `string` | Yes (if enabled) | -- | Buffer profile ID. Required by `buf_create_update` MCP tool |
+| `format` | `string` | No | `casual` | Content adaptation style: `professional`, `casual`, `promotional` |
+
+#### Channel: `mailchimp`
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `enabled` | `boolean` | **Yes** | -- | Whether Mailchimp distribution is active for this site |
+| `audience_id` | `string` | Yes (if enabled) | -- | Mailchimp audience/list ID. Required by `mc_create_campaign` MCP tool |
+| `segment` | `string` | No | `null` | Mailchimp segment or tag to target within the audience. If `null`, sends to the full audience |
+
+---
+
+### `seo` block
+
+Site-level SEO defaults. These apply when a brief does not specify its own SEO parameters. Brief-level `seo` values always override these.
+
+```yaml
+seo:
+  default_schema: Article
+  min_score: 70
+  auto_internal_links: true
+```
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `default_schema` | `string` | No | `Article` | Default JSON-LD schema type for content: `Article`, `BlogPosting`, `HowTo`, `FAQPage`, `Product`, `Recipe`, `NewsArticle` |
+| `min_score` | `integer` (0-100) | No | `70` | Default value for `brief.gates.seo_score_min` when the brief omits that field. Does not enforce a gate directly -- the gate is enforced at the brief level |
+| `auto_internal_links` | `boolean` | No | `true` | Automatically discover and suggest internal links based on existing site content. When `true`, the pipeline scans the site's published posts to find relevant linking opportunities |
+
+---
+
+### `cadence` block
+
+Editorial calendar configuration. Used by Phase 3 planning features. In Phase 1, the pipeline reads `publish_time` as default when `target.scheduled_date` is set without an explicit time.
+
+```yaml
+cadence:
+  posts_per_week: 3
+  preferred_days:
+    - monday
+    - wednesday
+    - friday
+  publish_time: "09:00"
+```
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `posts_per_week` | `integer` | No | `2` | Target number of posts per week. Informs editorial planning and capacity alerts |
+| `preferred_days` | `string[]` | No | `["monday", "thursday"]` | Preferred days of the week for publishing. Lowercase English day names |
+| `publish_time` | `string` | No | `"09:00"` | Default publish time in `HH:MM` format (24-hour, site's local timezone). Applied when scheduling future posts without an explicit time |
+
+---
+
+## Body Section
+
+The body section (after the closing `---`) is free-form Markdown that provides Claude with additional context about the site. This content is read by Claude when generating or adapting content but is not parsed as structured data.
+
+Recommended content for the body section:
+
+- **Brand story** -- brief narrative that Claude can reference for tone consistency
+- **Product line** -- key products/services and how to reference them
+- **Competitor notes** -- what to avoid saying, differentiation points
+- **Seasonal considerations** -- recurring themes, campaigns, events
+- **Terminology** -- preferred terms, abbreviations, translations
+
+---
+
+## Validation Rules
+
+### Required Fields
+
+These fields **must** be present for a config file to be valid:
+
+| Field | Reason |
+|-------|--------|
+| `site_id` | Links config to `WP_SITES_CONFIG` credentials |
+| `site_url` | Required for link construction and verification |
+| `brand.tone` | Minimum brand voice definition |
+| `brand.language` | Content language for generation and SEO |
+
+### Channel Validation
+
+For each channel where `enabled: true`:
+
+| Channel | Required Field | MCP Tool |
+|---------|---------------|----------|
+| `linkedin` | `profile_id` | `li_create_post` |
+| `buffer` | `profile_id` | `buf_create_update` |
+| `mailchimp` | `audience_id` | `mc_create_campaign` |
+| `twitter` | *(none)* | `tw_create_tweet`, `tw_create_thread` |
+
+### Override Hierarchy
+
+Brief-level values always take precedence over site config defaults:
+
+```
+Brief value > Site config default > System default
+```
+
+Specific overrides:
+- `brief.target.content_type` > `config.defaults.content_type`
+- `brief.target.status` > `config.defaults.status`
+- `brief.target.categories` > `config.defaults.categories`
+- `brief.content.author` > `config.defaults.author`
+- `brief.seo.schema_type` > `config.seo.default_schema`
+- `brief.gates.seo_score_min` > `config.seo.min_score`
+- `brief.distribution.channels` -- selects which enabled channels to use; cannot activate a channel the config has `enabled: false`
+
+---
+
+## Integration Notes
+
+### GenBrand Output Mapping
+
+The `GenBrand` skill produces brand analysis that maps to the `brand` block:
+
+| GenBrand Output | Config Field | Notes |
+|-----------------|-------------|-------|
+| Voice/tone descriptors | `brand.tone` | Comma-separated list of tone attributes |
+| Primary language | `brand.language` | ISO 639-1 code |
+| Editorial guidelines | `brand.style_notes` | Multi-line YAML block scalar. Include voice rules, banned words, preferred terminology |
+| Brand narrative | Body section | Free-form context for Claude |
+
+After running `GenBrand`, update the config file with the output. The `brand` block captures the structured attributes; the body section captures the narrative context.
+
+### WP_SITES_CONFIG Mapping
+
+The `WP_SITES_CONFIG` environment variable is a JSON array of site credentials:
+
+```json
+[
+  {
+    "id": "opencactus",
+    "url": "https://opencactus.com",
+    "username": "api-user",
+    "app_password": "xxxx xxxx xxxx xxxx"
+  }
+]
+```
+
+The mapping between `WP_SITES_CONFIG` and the config file:
+
+| WP_SITES_CONFIG Field | Config Field | Relationship |
+|----------------------|-------------|--------------|
+| `id` | `site_id` | **Must match exactly** -- this is the join key |
+| `url` | `site_url` | Should match; config value used for public-facing links |
+| `username` | `defaults.author` | Can differ; config author is for attribution, WP_SITES_CONFIG username is for API authentication |
+| `app_password` | *(none)* | Credentials are never stored in config files |
+
+**Important:** The config file never contains authentication credentials. All sensitive values remain in the `WP_SITES_CONFIG` environment variable.
+
+### Brief Cross-Reference
+
+When the pipeline processes a brief, it resolves the site config via `brief.target.site_id`:
+
+1. Read `brief.target.site_id` (e.g., `opencactus`)
+2. Load `.content-state/opencactus.config.md`
+3. Apply config defaults for any fields the brief omits
+4. Use `brand` block for content adaptation/generation
+5. Use `channels` block for distribution routing
+
+---
+
+## Example Config
+
+A complete `.config.md` for the opencactus site:
+
+```markdown
+---
+site_id: opencactus
+site_url: https://opencactus.com
+last_updated: 2026-03-02
+
+brand:
+  tone: professional, accessible, sustainability-focused
+  language: it
+  style_notes: |
+    Voice: warm but authoritative. Avoid corporate jargon.
+    Always emphasize the Sicilian heritage and natural ingredients.
+    Use "noi" (we) when referring to the company.
+    Sustainability is a core value, not a marketing angle -- weave it naturally.
+    Product names are always capitalized: Poco Dolce, Dolce, Molto Dolce.
+    Refer to the fruit as "fico d'India" (not "cactus" in Italian content).
+    Scientific claims must cite specific compounds (betalaine, polifenoli).
+
+defaults:
+  content_type: post
+  status: draft
+  categories:
+    - blog
+  author: editorial-team
+
+channels:
+  linkedin:
+    enabled: true
+    profile_id: "urn:li:organization:opencactus"
+    format: professional
+  twitter:
+    enabled: true
+    format: concise
+  buffer:
+    enabled: false
+    profile_id: ""
+    format: casual
+  mailchimp:
+    enabled: true
+    audience_id: "mc_aud_opencactus_main"
+    segment: newsletter-subscribers
+
+seo:
+  default_schema: Article
+  min_score: 75
+  auto_internal_links: true
+
+cadence:
+  posts_per_week: 3
+  preferred_days:
+    - monday
+    - wednesday
+    - friday
+  publish_time: "09:00"
+---
+
+## Brand Context
+
+OpenCactus is the digital home of DolceZero, an Italian zero-calorie beverage brand based on Sicilian cactus water (acqua di fico d'India). The brand sits at the intersection of traditional Sicilian agriculture and modern wellness.
+
+### Product Line
+
+- **Poco Dolce** -- Light sweetness, subtle cactus flavor. Entry-level product.
+- **Dolce** -- Medium sweetness, balanced flavor profile. The core product.
+- **Molto Dolce** -- Full sweetness, rich cactus flavor. For those who prefer bolder taste.
+
+All variants are zero-calorie, naturally flavored, with no artificial sweeteners.
+
+### Key Differentiators
+
+- Only cactus water brand with full Sicilian supply chain
+- Zero calorie without artificial sweeteners (uses natural cactus compounds)
+- 85% lower water footprint than conventional beverages
+- Rich in betalains and polyphenols (natural antioxidants)
+
+### Content Themes
+
+- Sustainability and environmental responsibility
+- Sicilian heritage and terroir
+- Health and wellness (zero-calorie, natural ingredients)
+- Innovation in food technology
+- Community and local farmers
+
+### Competitor Positioning
+
+Avoid direct competitor mentions. Focus on DolceZero's unique attributes rather than comparison. Never claim "best" or "only" without substantiation.
+```
+
+---
+
+## File Naming Convention
+
+Config files follow this naming pattern:
+
+```
+{site_id}.config.md
+```
+
+Examples:
+- `opencactus.config.md`
+- `my-blog.config.md`
+- `corporate-site.config.md`
+
+Files are stored in `.content-state/` and are gitignored (site-specific configuration).

package/skills/wp-editorial-planner/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: wp-editorial-planner
+description: This skill should be used when the user asks to "create an editorial
+  plan", "update the calendar", "schedule posts", "plan content for March",
+  "convert calendar to briefs", "sync calendar with WordPress", "show editorial
+  status", or mentions planning content over time. Orchestrates monthly editorial
+  calendars that bridge signals intelligence to content publishing.
+version: 1.0.0
+---
+
+# WordPress Editorial Planner Skill
+
+## Overview
+
+The editorial planner manages monthly content calendars as `.state.md` files stored in `.content-state/`. It reads site configuration for publishing cadence, optionally consumes the signals feed generated by `wp-analytics` for data-driven topic ideas, and produces structured briefs that flow into the content pipeline for WordPress publishing. The workflow follows four sequential steps: **PLAN** (create or update the monthly calendar), **BRIEF** (convert planned entries into pipeline brief files), **SCHEDULE** (create WordPress future posts from ready briefs), and **SYNC** (synchronize WordPress publish status back to the calendar). Each step is idempotent and can be run independently.
+
+## When to Use
+
+- User wants to create a new monthly editorial plan
+- User asks to update or view the current calendar
+- User wants to convert planned entries into content briefs
+- User asks to schedule ready briefs as WordPress future posts
+- User wants to sync WordPress publish status back to the calendar
+- User mentions "piano editoriale", "calendario", "schedula"
+
+## Workflow Overview
+
+```
+PLAN --> BRIEF --> SCHEDULE --> SYNC
+```
+
+---
+
+## Step 1: PLAN -- Create or update editorial calendar
+
+**When to run:** User asks to create a new plan or update an existing one.
+
+**Procedure:**
+
+1. **Read site configuration** from `.content-state/{site_id}.config.md`:
+   - `cadence.posts_per_week` -- calculate `goals.posts_target` as `posts_per_week * weeks_in_month`
+   - `cadence.preferred_days` -- determine which weekdays to assign calendar entries
+   - `cadence.publish_time` -- note for the SCHEDULE step
+   - `defaults.categories`, `defaults.content_type` -- pre-fill the entry Tipo column
+
+2. **Read signals feed** from `.content-state/signals-feed.md` if it exists:
+   - Extract anomalies with action containing "content cluster" or "Investigate"
+   - Suggest these as topics for `[da assegnare]` entries
+   - Present suggestions to user for approval before inserting into the calendar
+
+3. **Optional strategic planning:** If the user wants a higher-level content strategy, suggest invoking GenMarketing for content calendar strategy development before populating individual entries.
+
+4. **Generate or update** `.content-state/{YYYY-MM}-editorial.state.md`:
+   - Create YAML frontmatter with `calendar_id`, `site_id`, `period`, `goals`
+   - Create weekly tables with one row per `preferred_day`
+   - Fill known titles where provided, leave others as `[da assegnare]`
+   - Set all new entries as `status: planned`
+
+5. **Present the calendar** to the user for review before writing to disk.
+
+**Safety rules:**
+- ALWAYS show the generated calendar to the user before writing the file
+- If a calendar for the month already exists, show the diff and ask before overwriting
+- Preserve existing entries that have `status: draft` or higher -- never reset them to `planned`
+
+---
+
+## Step 2: BRIEF -- Convert calendar entries to brief files
+
+**When to run:** User asks to "create briefs from calendar" or "convert planned entries to briefs".
+
+**Procedure:**
+
+1. Read the current editorial calendar `.state.md` file.
+
+2. For each entry with `status: planned` AND a defined title (not `[da assegnare]`):
+   a. Generate a new `brief_id` as `BRF-YYYY-NNN` (sequential; scan existing briefs in both `pipeline-active/` and `pipeline-archive/` to determine the next number)
+   b. Read `.content-state/{site_id}.config.md` for site defaults
+   c. Create `.content-state/pipeline-active/{brief_id}.brief.md` with:
+      - `source.skill: wp-editorial-planner`
+      - `source.domain: editorial-calendar`
+      - `target.site_id`: from calendar `site_id`
+      - `target.content_type`: from entry Tipo column
+      - `target.scheduled_date`: from entry Data column (convert to ISO 8601)
+      - `target.categories`: from site config defaults
+      - `distribution.channels`: from entry Canali column (parse comma-separated)
+      - `content.title`: from entry Titolo column
+      - `status: draft` (brief starts as draft; user fills content)
+   d. Update the calendar entry: `status: planned` becomes `draft`, set the Brief ID column
+
+3. For entries with an existing Brief ID (already has a brief): skip creation, just verify the brief file exists in `pipeline-active/`. If the file is missing, report it.
+
+4. Write the updated calendar back to the `.state.md` file.
+
+5. Report to user:
+   ```
+   N brief creati in pipeline-active/. Compila il contenuto e imposta status: ready.
+   ```
+
+**Safety rules:**
+- NEVER create briefs for entries with `[da assegnare]` title -- report them as needing titles first
+- NEVER overwrite existing brief files -- if a Brief ID already exists as a file, skip and report
+- Show a summary of briefs to be created and ask user confirmation before writing any files
+
+---
+
+## Step 3: SCHEDULE -- Convert ready briefs to WordPress scheduled posts
+
+**When to run:** User asks to "schedule ready posts" or "schedula i post pronti".
+
+**Procedure:**
+
+1. Read the current editorial calendar `.state.md` file.
+
+2. For each entry with `status: ready`:
+   a. Read the corresponding brief file from `pipeline-active/{brief_id}.brief.md`
+   b. Verify the brief has `status: ready` (consistency check between calendar and brief)
+   c. Create the WordPress post using MCP tool:
+      ```
+      create_content:
+        content_type: {entry.Tipo}
+        title: {brief.content.title}
+        content: {brief body markdown}
+        excerpt: {brief.content.excerpt}
+        status: "future"
+        date: {entry.Data as ISO 8601 datetime with site config publish_time}
+        slug: {auto-generated from title}
+      ```
+   d. Assign taxonomy terms using MCP tool:
+      ```
+      assign_terms_to_content:
+        content_type: {entry.Tipo}
+        id: {post_id}
+        categories: {brief.target.categories}
+        tags: {brief.target.tags}
+      ```
+   e. Update the calendar entry: `status: ready` becomes `scheduled`, set Post ID column
+   f. Update the brief file: add `post_id` and `post_url` to frontmatter
+
+3. If the entry has `distribution.channels` (from the Canali column):
+   - Compute `scheduled_at` using the entry date + `config.cadence.publish_time` + `distribution.schedule_offset_hours`
+   - For Buffer: call `buf_create_update` with the computed `scheduled_at`
+     ```
+     buf_create_update:
+       profile_ids: [{config.channels.buffer.profile_id}]
+       text: {adapted content}
+       media:
+         photo: {featured image URL if available}
+       scheduled_at: {ISO 8601 UTC timestamp}
+     ```
+   - For Mailchimp: note for manual campaign creation (not auto-scheduled at this step)
+
+4. Write the updated calendar back to the `.state.md` file.
+
+5. Report to user:
+   ```
+   N post schedulati su WordPress. Verranno pubblicati automaticamente alla data prevista.
+   ```
+
+**Safety rules:**
+- ALWAYS create WordPress posts as `status: future` (never directly `publish`)
+- ALWAYS confirm with user before scheduling, showing the list of posts and their dates
+- If `create_content` fails for any entry, stop processing that entry, report the error, and keep the entry as `ready`
+- Verify the scheduled date is in the future before calling `create_content` -- if the date is in the past, report to user and skip
+
+---
+
+## Step 4: SYNC -- Synchronize WordPress status back to calendar
+
+**When to run:** User asks to "sync calendar" or "aggiorna stato calendario".
+
+**Procedure:**
+
+1. Read the current editorial calendar `.state.md` file.
+
+2. For each entry with a Post ID (status: `scheduled` or `published`):
+   a. Call `list_content` with the content type and filter by post ID:
+      ```
+      list_content:
+        content_type: {entry.Tipo}
+        search: {post_id}
+        per_page: 1
+      ```
+   b. Check the returned post status and update the calendar accordingly:
+      - If WP status = `publish` and calendar status = `scheduled` --> update to `published`
+      - If WP status = `future` --> keep as `scheduled`
+      - If WP status = `draft` --> note: post was reverted, update calendar to `draft`
+      - If WP status = `trash` --> note: post was deleted, report to user
+
+3. Recalculate `goals.posts_published` = count of entries with `status: published`.
+
+4. Write the updated calendar back to the `.state.md` file.
+
+5. Report to user:
+   ```
+   Sync calendario {calendar_id}:
+   - Post pubblicati: {posts_published}/{posts_target}
+   - Post schedulati: {scheduled_count}
+   - Post in lavorazione: {draft_count + ready_count}
+   - Slot da assegnare: {planned_count}
+   ```
+
+**Safety rules:**
+- NEVER modify WordPress post status during sync -- sync is read-only from WordPress
+- If a post was deleted or trashed, report to user but do not remove the calendar entry (mark with a note instead)
+
+---
+
+## Creating a Calendar Manually
+
+When the user wants to create a calendar without running the full PLAN step:
+
+1. Copy the structure from `references/editorial-schema.md`
+2. Fill in `site_id`, dates for each entry, and known titles
+3. Set `status: planned` for all entries
+4. Save as `.content-state/{YYYY-MM}-editorial.state.md`
+5. Then run the BRIEF step to generate brief files from the planned entries
+
+---
+
+## Safety Rules Summary
+
+- **ALWAYS** show the calendar and briefs to the user before writing any files
+- **ALWAYS** create WordPress posts as `status: future` (never `publish` directly)
+- **NEVER** overwrite existing briefs or calendar entries with higher status
+- **NEVER** modify WordPress posts during SYNC (read-only operation)
+- **ALWAYS** confirm with the user before scheduling posts to WordPress
+- **LOG** all scheduling actions in the calendar state file
+
+---
+
+## Known Limitations
+
+### AIWU MCP Server (cloud-based)
+
+The AIWU MCP server (`mcp__claude_ai_AIWU`) does **not** support the `post_date` field in `wp_create_post` or `wp_update_post`. This means `post_status: "future"` cannot be achieved through AIWU — WordPress auto-publishes the post when no future date is provided.
+
+**E2E test results (2026-03-02):**
+- `wp_create_post` with `post_status: "future"` → auto-published (no `post_date` parameter available)
+- `wp_update_post` with `post_date` + `post_status: "future"` from `draft` → auto-published (`post_date` not passed through)
+- `wp_update_post` on already-published post → `post_date` updated but status cannot revert from `publish` to `future`
+
+**Workaround:** Use the wp-rest-bridge MCP server's `create_content` tool, which natively supports the `date` parameter for scheduling future posts. AIWU can still be used for SYNC (read-only) and for content management tasks that don't require future scheduling.
+
+---
+
+## Reference Files
+
+- `references/editorial-schema.md` -- complete schema for editorial calendar `.state.md` files
+- `../wp-content-pipeline/references/content-brief-schema.md` -- brief file format and frontmatter fields
+- `../wp-content-pipeline/references/site-config-schema.md` -- site configuration defaults and cadence settings
+- `../wp-analytics/references/signals-feed-schema.md` -- signals feed format for topic suggestions
+
+---
+
+## Related Skills
+
+- **`wp-content-pipeline`** -- publishes briefs created by the BRIEF step through the full pipeline workflow
+- **`wp-analytics`** -- generates the signals feed consumed by the PLAN step for data-driven topic ideas
+- **`wp-content`** -- content creation and management (provides `create_content`, `list_content` MCP tools)
+- **`wp-social-email`** -- distribution channel scheduling (Buffer via `buf_create_update`, Mailchimp campaigns)
+- **`wp-content-repurposing`** -- multi-format adaptation for social distribution channels