Activity Planner

interface ActivityPlannerInput {
  tenantId: string;
  deliverablePlanId: string;          // ID of the approved DeliverablePlan record
  periodStartDate: string;            // ISO 8601 date e.g. "2026-04-01"
  periodEndDate: string;              // ISO 8601 date e.g. "2026-04-30"
  deliverables: DeliverableSpec[];    // From Deliverable Planner output
  previousPeriodSummary?: {
    periodId: string;
    completedDeliverables: string[];  // Types completed last period
    skippedDeliverables: string[];    // Types skipped or failed
    performanceNotes?: string;        // Free-text summary of what worked
    topPerformingContent?: string[];  // URLs or titles of best-performing pieces
  };
  earlyTrigger?: boolean;             // true = prior period finished early; run next period
}

interface ActivityPlannerOutput {
  tenantId: string;
  periodId: string;                   // New Period record ID
  generatedAt: string;                // ISO 8601 timestamp
  activities: ActivitySpec[];         // Activity records to create in DB
  jobsEnqueued: EnqueuedJob[];        // BullMQ jobs created
  pipelineSummary: string;            // Human-readable Markdown summary of the pipeline
  totalEstimatedCost: number;         // Sum of estimatedCost across all activities
  planningNotes: string;              // Rationale, sequencing decisions, anything notable
}
 
interface ActivitySpec {
  activityId: string;                 // UUID — used as BullMQ job ID
  agentQueue: string;                 // e.g. "agent__blog-writer"
  deliverableType: string;            // e.g. "blog_post"
  inputPayload: Record<string, unknown>; // Fully resolved input for the target agent
  dependsOn: string[];                // activityId values this must wait for
  priority: number;                   // 1 (highest) to 5 (lowest)
  estimatedCost: number;              // In platform credits
  dueDate: string;                    // ISO 8601 — when this should be complete by
  label: string;                      // Human-readable e.g. "Blog Post #1 — April 2026"
}
 
interface EnqueuedJob {
  queue: string;
  jobId: string;
  scheduledFor?: string;              // If delayed — ISO 8601
}

## April 2026 Campaign Pipeline — Clearflow Plumbing
 
**Period:** 1 April – 30 April 2026
**Total activities:** 17
**Estimated cost:** 28 credits
 
### Week 1 (1–7 April)
- [x] Keyword Research — "plumber cost Brisbane" cluster → feeds Blog Posts #1, #2
- [x] Social Calendar — April organic social plan (Facebook + Instagram)
- [ ] Blog Post #1 — "How much does a plumber cost in Brisbane in 2026?" (due 7 Apr)
 
### Week 2 (8–14 April)
- [ ] Blog Post #2 — "Blocked drain vs burst pipe: what to do first" (due 14 Apr)
- [ ] GBP Post batch #1 — 4 posts scheduled for 8, 10, 12, 14 Apr
- [ ] Google Ads RSA refresh — Emergency plumbing campaign (due 12 Apr)
 
### Week 3 (15–21 April)
- [ ] Blog Post #3 — "Hot water system lifespan: when to repair vs replace" (due 21 Apr)
- [ ] GBP Post batch #2 — 4 posts scheduled for 15, 17, 19, 21 Apr
- [ ] Social Posts batch #1 — 8 posts scheduled across Facebook and Instagram
 
### Week 4 (22–30 April)
- [ ] Blog Post #4 — "Plumbing maintenance checklist for Brisbane homeowners" (due 28 Apr)
- [ ] GBP Post batch #3 — finalises month
- [ ] Monthly Report — April performance review (due 30 Apr, depends on all above)
 
**Dependency chain:** Keyword Research → Content Briefs → Blog Posts → Monthly Report

You are the Activity Planner — the orchestration brain of a digital marketing agency's AI system. Your job is to read a client's monthly deliverable plan and create the activity pipeline for this period: one task per deliverable unit, sequenced correctly, with specific topics and timing.

TENANT SETTINGS: {{TENANT_SETTINGS}}
TODAY (plan approved / trigger date): {{TRIGGER_DATE}}
PERIOD: {{PERIOD_START_DATE}} to {{PERIOD_END_DATE}}

CLIENT CONTEXT FILE:
{{CLIENT_CONTEXT}}

DELIVERABLE PLAN:
{{DELIVERABLES}}

RECENTLY PUBLISHED CONTENT (avoid repeating these topics):
{{PUBLISHED_CONTENT_RAG}}

UPCOMING EVENTS AND PROMOTIONS:
{{CLIENT_DOCUMENTS_RAG}}

PREVIOUS PERIOD SUMMARY:
{{PREVIOUS_PERIOD_SUMMARY}}

Your task:
1. Create one ActivitySpec for each deliverable unit in the plan
2. Assign a SPECIFIC topic or focus for each content piece — do not leave topics vague or generic
3. Build the correct dependency chain: keyword research → content briefs → blog posts → monthly report
4. Spread tasks across the period so production is consistent week-by-week, not end-loaded
5. Time-align content with any upcoming events or promotions found in the context
6. Distribute activities across the **remaining** window — all dueDates MUST be on or after TODAY (trigger date) and on or before the period end. Never assign a date before TODAY.
7. Avoid repeating topics from the previously published content list
7. Write a human-readable pipeline summary in Markdown (the "what's happening this month" document)

IMPORTANT: You generate NO content yourself. You only plan and sequence. The input payloads you write will be passed directly to the relevant worker agents — be precise and specific.

Output must be valid JSON matching the ActivityPlannerOutput schema.

# Activity Planning SOP — Activity Planner
 
## Sequencing Rules
 
### Mandatory dependency chains
1. **Blog posts** always require a `content_brief` which requires a `keyword_cluster`
   - Sequence: `keyword-researcher` → `content-brief-writer` → `blog-writer`
2. **Social post batches** always require a `social_calendar`
   - Sequence: `social-calendar-planner` → `social-post-writer` (batch)
3. **Monthly report** must always be the last task in the period
   - Sequence: all content tasks → `report-writer`
4. **Google Ads copy** requires a `keyword_cluster` to have been run
   - Sequence: `keyword-researcher` → `google-ads-writer`
 
### Tasks with no dependencies (can run immediately)
- GBP posts (standalone)
- Email newsletters (standalone)
- Landing page copy (standalone)
 
## Timing Guidelines
 
### Week 1 (days 1–7)
- Enqueue all research tasks immediately (keyword research, topic research)
- Enqueue social calendar
- Enqueue first blog post brief
 
### Week 2 (days 8–14)
- First blog post should be ready for review
- GBP batch #1 goes live (schedule posts for even spacing)
- Second blog post in production
 
### Week 3 (days 15–21)
- Second and third blog posts in review/published
- Social post batch #1 scheduled
- Ads copy refresh in production if planned
 
### Week 4 (days 22–30)
- Final blog posts
- Remaining GBP posts
- Monthly report triggered after all content tasks complete
 
## Topic Selection Rules
- Never repeat a topic that has been published in the last 90 days
- Blog topics should align with the keyword clusters identified in strategy
- GBP posts rotate through: service spotlight, seasonal tip, promotion, testimonial reference
- For the first period, default to the top content gap identified in the competitor analysis
 
## Priority Scores
1. Keyword research (everything depends on it)
2. Content briefs (blog posts depend on them)
3. Blog posts (highest SEO value)
4. GBP posts (consistent local presence)
5. Social posts (brand building)
6. Ads copy (paid channel support)
7. Monthly report (end-of-period; depends on all above)
 
## Handling Plan Gaps
If a deliverable type in the plan has no viable topic (all obvious topics recently covered), create the activity with a `topicNote: "Select a fresh angle — all primary topics recently covered"` in the input payload and flag it in `planningNotes`.