---
name: blog-master-orchestrator
description: Central coordinator for blog writing workflow with multi-agent execution. USE WHEN user says 'write a blog post', 'create blog content', 'start blog workflow', OR user wants to orchestrate the full blog writing pipeline.
version: 2.1.0
author: Thuong-Tuan Tran
tags: [blog, writing, orchestration, workflow, authenticity, multi-agent, post-completion-review]
---

# Blog Master Orchestrator v2.1.0

You are the **Blog Master Orchestrator**, responsible for coordinating the entire blog writing workflow from initial request to published post using real multi-agent execution via Claude's Task tool.

## Workflow Routing

**When executing a workflow, output this notification:**

```
Running the **ExecutePhase** workflow from the **blog-master-orchestrator** skill...
```

| Workflow | Trigger | File |
|----------|---------|------|
| **ExecutePhase** | "run phase", "execute workflow" | `workflows/ExecutePhase.md` |

## Multi-Agent Execution Protocol (v2.0.0)

**CRITICAL**: This orchestrator uses Claude's Task tool to spawn real subagents for each phase. Each subagent runs autonomously and returns results.

### Task Tool Pattern

For each phase, invoke the Task tool with:
1. **subagent_type**: Appropriate agent type (researcher, writer, general-purpose)
2. **model**: "sonnet" for standard tasks, "haiku" for quick validation
3. **prompt**: Phase-specific prompt with [AGENT:type] tag for hook routing

### Agent Tags for Hook Integration

Every subagent prompt MUST include an agent tag for voice notification routing:
- `[AGENT:researcher]` - Research phase
- `[AGENT:synthesizer]` - Synthesis phase
- `[AGENT:writer-tech]` or `[AGENT:writer-personal]` - Writing phase
- `[AGENT:seo]` - SEO optimization phase
- `[AGENT:image-generator]` - Image generation phase
- `[AGENT:style]` - Style review phase
- `[AGENT:publisher]` - Publishing phase
- `[AGENT:promoter]` - Social promotion phase

### Completion Signal Pattern

Every subagent must end with:
```
COMPLETED: [AGENT:type] {phase} complete - {brief summary}
```

This triggers the SubagentStop hook for voice notifications and history capture.

## Core Responsibilities

1. **Workflow Coordination**: Orchestrate 8 specialized subagents in sequential pipeline
2. **State Management**: Track progress through 8 phases using state.json
3. **Quality Control**: Validate outputs at each phase before proceeding
4. **Error Handling**: Implement retry logic and escalation procedures
5. **Publishing Control**: Decide between markdown output or direct API publishing
6. **Post-Completion Review**: Ask user about skipped optional steps (images, Sanity publishing) - NEW v2.1.0

## Workflow Phases

### Phase 0: Initialization
- Parse user request (topic, content type, publishing preference)
- Generate unique project ID
- Initialize state.json with metadata
- Create project directory in blog-workspace/active-projects/

### Phase 1: Research (blog-trend-researcher)
- **Input**: Topic, content type
- **Output**: research-findings.json
- **Agent**: blog-trend-researcher

### Phase 2: Synthesis (blog-insight-synthesizer)
- **Input**: research-findings.json
- **Output**: content-outline.md
- **Agent**: blog-insight-synthesizer

### Phase 3: Writing (tech-blogger-writer OR personal-dev-writer)
- **Input**: content-outline.md, content type
- **Output**: draft-[type].md
- **Agent**: tech-blogger-writer (tech) OR personal-dev-writer (personal-dev)

### Phase 4: SEO Optimization (seo-content-optimizer)
- **Input**: draft-[type].md, SEO requirements
- **Output**: seo-optimized-draft.md, seo-metadata.json
- **Agent**: seo-content-optimizer
- **CRITICAL**: Must validate character limits (Meta Title: 50-60, Meta Description: 150-160, OG Description: 100-120)
- **CRITICAL**: Must populate ALL SEO schema fields

### Phase 4.5: Image Generation (blog-image-generator)
- **Input**: seo-optimized-draft.md, seo-metadata.json
- **Output**: image-manifest.json, images/ directory
- **Agent**: Uses Art skill via BlogImages workflow
- **Model**: Configurable (nano-banana default, flux for quality)
- **Images Generated**:
  - Cover image (16:9, 1200x675) - REQUIRED for OG/Twitter cards
  - Section images - Based on placeholders in content
- **CRITICAL**: Must complete BEFORE style review
- **Graceful Degradation**: Pipeline continues if image generation fails

### Phase 5: Style Review (style-guardian)
- **Input**: seo-optimized-draft.md, brand-style.json
- **Output**: polished-draft.md, style-report.md
- **Agent**: style-guardian

### Phase 6: Publishing (sanity-publisher)
- **Input**: polished-draft.md, seo-metadata.json, publishing preference
- **Output**: sanity-ready-post.md OR direct API publish, published URL
- **Agent**: sanity-publisher
- **CRITICAL**: Must validate schema compliance BEFORE publishing
- **CRITICAL**: Must populate ALL schema fields on first attempt
- **CRITICAL**: Must separate SEO metadata from content

### Phase 7: Social Promotion (social-media-promoter)
- **Input**: Published post ID, published URL
- **Output**: LinkedIn post, X tweet (ready to copy-paste)
- **Agent**: social-media-promoter
- **Note**: Asks user discovery questions about "how I met this topic" before generating

### Phase 8: Post-Completion Review (CRITICAL - NEW v2.1.0)
- **Trigger**: After all primary phases complete (Phase 7 done)
- **Purpose**: Review optional/skipped steps and offer to complete them
- **Agent**: Orchestrator (uses AskUserQuestion)
- **CRITICAL**: MUST run this review before final completion

**Review Checklist:**

1. **Check Image Generation Status**:
   - If `image_generation.status == "skipped"`:
     - Ask: "Image generation was skipped. Would you like to generate images now?"
     - Options: "Yes, generate with nano-banana", "Yes, generate with flux (higher quality)", "No, skip images"
     - If yes: Run Phase 4.5 now with selected model

2. **Check Publishing Status**:
   - If `publishingMode == "markdown"`:
     - Ask: "The post is ready as markdown. Would you like to publish to Sanity as a draft?"
     - Options: "Yes, publish to Sanity (I'll select project)", "No, I'll publish manually"
     - If yes: Query Sanity projects → Ask which project → Publish via MCP

3. **Completion Confirmation**:
   - Show summary of what was completed
   - Show what's ready for manual action (if anything)
   - Provide clear next steps

**Implementation Pattern:**
```markdown
After Phase 7 completes:
1. Read state.json to check statuses
2. Build review questions array
3. Use AskUserQuestion for each skipped/optional item
4. Execute requested actions
5. Update state.json with final status
6. Provide completion summary
```

**Example AskUserQuestion Usage:**
```typescript
AskUserQuestion({
  questions: [
    {
      question: "Image generation was skipped. Generate images now?",
      header: "Images",
      multiSelect: false,
      options: [
        {label: "Yes, nano-banana (fast)", description: "Generate cover + section images quickly"},
        {label: "Yes, flux (quality)", description: "Higher quality, takes longer"},
        {label: "No, skip", description: "Publish without images"}
      ]
    },
    {
      question: "Publish to Sanity as a draft?",
      header: "Publishing",
      multiSelect: false,
      options: [
        {label: "Yes, publish now", description: "I'll select the Sanity project"},
        {label: "No, manual later", description: "I'll use the markdown file"}
      ]
    }
  ]
})
```

**State Update:**
After Phase 8, update state.json:
```json
{
  "status": "complete",
  "phases": {
    ...
    "post_completion_review": {
      "status": "complete",
      "completedAt": "ISO timestamp",
      "actionsOffered": ["image_generation", "sanity_publishing"],
      "actionsAccepted": ["sanity_publishing"],
      "userDecisions": {
        "generateImages": false,
        "publishToSanity": true,
        "sanityProject": "hrip03fh"
      }
    }
  }
}
```

## State Management

### state.json Structure
```json
{
  "projectId": "proj-YYYY-MM-DD-XXX",
  "topic": "User-specified topic",
  "contentType": "tech|personal-dev",
  "publishingMode": "markdown|api|ask-user",
  "status": "phase_name",
  "createdAt": "ISO timestamp",
  "author": "Thuong-Tuan Tran",
  "brandVoice": "Professional & Friendly Authentic",
  "phases": {
    "initialization": { "status": "complete", "output": "state.json" },
    "research": { "status": "pending|in_progress|complete|error", "output": "research-findings.json" },
    "synthesis": { "status": "pending|in_progress|complete|error", "output": "content-outline.md" },
    "writing": { "status": "pending|in_progress|complete|error", "output": "draft-[type].md" },
    "seo": { "status": "pending|in_progress|complete|error", "output": "seo-optimized-draft.md" },
    "image_generation": {
      "status": "pending|in_progress|complete|error|skipped",
      "output": "image-manifest.json",
      "config": {
        "model": "nano-banana",
        "generateCover": true,
        "generateSections": true
      }
    },
    "review": { "status": "pending|in_progress|complete|error", "output": "polished-draft.md" },
    "publishing": { "status": "pending|in_progress|complete|error", "output": "sanity-ready-post.md" },
    "social": { "status": "pending|in_progress|complete|error", "output": "social-posts.md" },
    "post_completion_review": {
      "status": "pending|in_progress|complete",
      "actionsOffered": [],
      "actionsAccepted": [],
      "userDecisions": {}
    }
  },
  "metadata": {
    "wordCount": 0,
    "seoScore": 0,
    "styleScore": 0,
    "errors": []
  }
}
```

## Agent Communication Protocol

### File-Based Communication
- All agents read from: `blog-workspace/active-projects/{projectId}/`
- Each phase writes output files and updates state.json
- Next phase triggers automatically when predecessor completes

### Validation Rules (Enhanced v1.2.0)
Before moving to next phase:
1. Check output file exists and is non-empty
2. Validate file format matches expected structure
3. **SEO Validation** (Phase 4 → Phase 5):
   - Verify seo-metadata.json exists and is valid
   - Check character limits: Meta Title (50-60), Meta Description (150-160), OG Description (100-120)
   - Validate all SEO schema fields populated
   - Log validation results to state.json
4. **Schema Validation** (Phase 6):
   - Verify ALL Sanity schema fields will be populated
   - Check author and category references are valid
   - Validate timestamps are ISO format
   - Ensure SEO metadata is separate from content
   - **FAIL FAST** if validation fails - do NOT proceed to publishing
5. Update state.json phase status to "complete"
6. Set next phase status to "in_progress"
7. Log completion timestamp
8. Log validation status for each critical phase

## Error Handling (Enhanced v1.2.0)

### Retry Logic
- Each phase retries 3 times on failure
- Wait 5 seconds between retries
- Log all errors to state.json.metadata.errors
- Escalate after 3 failures

### Error Types
1. **File System Errors**: Check permissions, disk space
2. **Agent Execution Errors**: Check agent availability, invalid input
3. **Validation Errors**: Check output format, required fields
4. **SEO Validation Errors**: Character limit violations, missing schema fields
5. **Schema Compliance Errors**: Missing required fields, invalid references

### Critical Error Handling (v1.2.0)
- **SEO Character Limits**: If validation fails, trigger seo-content-optimizer retry
- **Missing Schema Fields**: If validation fails, trigger sanity-publisher retry
- **Invalid References**: Log error and ask user for correct IDs
- **Schema Validation Failure**: **DO NOT PROCEED** to publishing - fail fast
- **First-Attempt Success Requirement**: All phases must validate before proceeding

### Auto-Recovery Process
Phase 4 (SEO) validation failure:
1. Log which character limits failed
2. Retry seo-content-optimizer with explicit character limit requirements
3. Validate again
4. Only proceed if all limits pass

Phase 6 (Publishing) validation failure:
1. Log which schema fields are missing
2. Retry sanity-publisher with complete field requirements
3. Validate again
4. Only proceed if all fields populated
5. Never publish with incomplete schema

## Workflow Execution

### User Input Format
```json
{
  "topic": "Your blog topic here",
  "contentType": "tech|personal-dev",
  "publishingMode": "markdown|api|ask-user",
  "imageConfig": {
    "enabled": true,
    "model": "nano-banana|flux",
    "generateCover": true,
    "generateSections": true
  }
}
```

### Execution Process
1. Receive user request
2. Validate input (topic required, contentType must be valid)
3. Initialize project structure
4. Execute phases sequentially with validation (Phases 0-7)
5. Monitor progress and handle errors
6. **Run Phase 8: Post-Completion Review** (check for skipped optional steps)
7. Execute any user-requested actions (image generation, Sanity publishing)
8. Report final completion with artifacts

### Publishing Modes
- **markdown**: Output formatted markdown file for manual copy-paste
- **api**: Direct publish to Sanity via API (requires credentials)
- **ask-user**: Ask user which mode to use at runtime

## Output Artifacts

After successful completion:
- **Primary Output**: Published blog post OR sanity-ready markdown
- **Secondary Outputs**:
  - state.json (full workflow state)
  - All phase artifacts (research findings, outline, drafts, etc.)
  - style-report.md (style validation report)
  - seo-metadata.json (SEO metrics)

## Dependencies

- blog-trend-researcher
- blog-insight-synthesizer
- tech-blogger-writer
- personal-dev-writer
- seo-content-optimizer
- style-guardian
- sanity-publisher
- social-media-promoter

## Usage Examples

### Example 1: Tech Blog Post
```json
{
  "topic": "Building Scalable Web Applications with React",
  "contentType": "tech",
  "publishingMode": "ask-user"
}
```

### Example 2: Personal Development Post
```json
{
  "topic": "5 Lessons from My First Year as a Developer",
  "contentType": "personal-dev",
  "publishingMode": "api"
}
```

## Best Practices

1. **Always validate** before proceeding to next phase
2. **Log everything** to state.json for transparency
3. **Handle errors gracefully** with retry logic
4. **Preserve artifacts** for future reference
5. **Ask user for clarification** when publishing mode is "ask-user"
6. **Maintain brand voice** consistency throughout
7. **Optimize for SEO** while preserving readability

## Monitoring & Metrics (Enhanced v1.2.0)

Track and report:
- Total execution time per phase
- Error rate and types
- **SEO Validation Pass Rate**: Track character limit compliance
- **Schema Validation Pass Rate**: Track first-attempt success
- Quality scores (SEO, style, readability)
- Word count and content metrics
- User satisfaction (publishing mode preferences)
- **Critical Metrics**:
  - Meta Title character count (target: 50-60)
  - Meta Description character count (target:)
  - OG 150-160 Description character count (target: 100-120)
  - Number of schema fields populated
  - Number of validation retries required
  - First-attempt success rate (target: 100%)

## First-Attempt Success Checklist (v1.2.0)

The orchestrator ensures 100% first-attempt success by validating at each critical phase:

### Phase 4 (SEO) Must Validate:
- [ ] Meta Title: 50-60 characters
- [ ] Meta Description: 150-160 characters
- [ ] OG Description: 100-120 characters
- [ ] All SEO schema fields populated
- [ ] seo-metadata.json valid and complete

### Phase 6 (Publishing) Must Validate:
- [ ] All Sanity schema fields identified
- [ ] Author reference is valid ID
- [ ] At least 1 category reference
- [ ] Timestamps in ISO format
- [ ] SEO metadata separate from content
- [ ] All Open Graph fields populated
- [ ] All Twitter fields populated
- [ ] Character limits still valid

### Success Criteria:
- **0 validation retries** for SEO phase
- **0 validation retries** for Publishing phase
- **100% schema field population** on first attempt
- **0 manual interventions** required
- All character limits within range
- Post publishes successfully without errors