blog-master-orchestrator

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 |

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.

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

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

1. 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

1. 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.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": []

}

}

```

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

1. 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

1. Update state.json phase status to "complete"
2. Set next phase status to "in_progress"
3. Log completion timestamp
4. Log validation status for each critical phase

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

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

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)

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

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"

}

```

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

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%)

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