zircote

Content Generation System

Overview

This document describes the AI-assisted content generation system for zircote.com. The system combines:

  1. Editorial Calendars - YAML-based content planning with quarterly schedules
  2. Brand Configuration - Voice, tone, audience, and visual identity definitions
  3. Content Templates - AI prompt templates for consistent content generation
  4. Schema Validation - JSON schemas ensuring content structure compliance
  5. GitHub Automation - Cron-scheduled workflows for issue creation and content tracking

System Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                        Content Generation Pipeline                      │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐               │
│  │   Calendar   │───▶│    Brand     │───▶│   Template   │               │
│  │  (q1-q4.yml) │    │ (brand.yml)  │    │ (.prompt.md) │               │
│  └──────────────┘    └──────────────┘    └──────────────┘               │
│         │                   │                   │                       │
│         ▼                   ▼                   ▼                       │
│  ┌──────────────────────────────────────────────────────┐               │
│  │              GitHub Actions Workflow                 │               │
│  │        (.github/workflows/calendar-check.yml)        │               │
│  └──────────────────────────────────────────────────────┘               │
│         │                                                               │
│         ▼                                                               │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐               │
│  │    Issues    │───▶│   AI Draft   │───▶│   Validate   │               │
│  │   Created    │    │  Generation  │    │   (Schema)   │               │
│  └──────────────┘    └──────────────┘    └──────────────┘               │
│         │                                                               │
│         ▼                                                               │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐               │
│  │    Review    │───▶│   Publish    │───▶│    Social    │               │
│  │    & Edit    │    │  (Jekyll)    │    │ Repurposing  │               │
│  └──────────────┘    └──────────────┘    └──────────────┘               │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Directory Structure

zircote.github.io/
├── calendar/                          # Editorial calendars
│   ├── 2026/
│   │   ├── q1.yml                    # January-March schedule
│   │   ├── q2.yml                    # April-June schedule
│   │   ├── q3.yml                    # July-September schedule
│   │   └── q4.yml                    # October-December schedule
│   └── schema.yml                    # Calendar validation schema
│
├── brands/                            # Brand configurations
│   └── zircote/
│       ├── brand.yml                 # Brand identity definition
│       └── templates/
│           ├── blog-post.prompt.md   # Blog post generation prompt
│           └── release-notes.prompt.md
│
├── templates/                         # Generic content templates
│   ├── blog-post.md                  # Jekyll blog post template
│   ├── social/
│   │   ├── twitter.prompt.md         # Twitter/X prompt template
│   │   ├── linkedin.prompt.md        # LinkedIn prompt template
│   │   ├── bluesky.prompt.md         # Bluesky prompt template
│   │   └── mastodon.prompt.md        # Mastodon prompt template
│   └── release/
│       └── release-notes.md          # Release notes template
│
├── prompts/                           # Content transformation prompts
│   ├── blog-to-social.prompt.md      # Blog → social media conversion
│   ├── video-to-social.prompt.md     # Video → social media conversion
│   └── repurpose-content.prompt.md   # General repurposing prompt
│
├── schemas/                           # Content validation schemas
│   ├── blog.schema.yml               # Blog post schema
│   └── social.schema.yml             # Social post schema
│
├── .github/workflows/
│   ├── calendar-check.yml            # Weekly calendar check (cron)
│   └── validate-content.yml          # Content validation on PR
│
└── docs/content-generation/           # This documentation
    ├── README.md                      # This file
    ├── CALENDAR.md                    # Calendar reference
    ├── WORKFLOW.md                    # Workflow guide
    ├── AUTOMATION.md                  # GitHub Actions reference
    ├── TEMPLATES.md                   # Templates reference
    └── NEWS-SOURCES.md                # News curation guide

Quick Start

1. View Upcoming Content

Check the current quarter’s calendar:

cat calendar/2026/q1.yml

2. Manually Run Calendar Check

Trigger the calendar workflow manually:

gh workflow run calendar-check.yml

3. Create Content from Issue

When a GitHub Issue is created by the calendar workflow:

  1. Open the issue (labeled content, copilot)
  2. Read the issue body for context, brand voice, and templates
  3. Generate draft using the specified template
  4. Save to content/blog/drafts/YYYY-MM-DD-slug.md
  5. Validate against schema
  6. Review, edit, publish

4. Generate Social Posts

After publishing a blog post:

# Use blog-to-social.prompt.md to generate platform-specific posts

Content Pillars

Content is organized around four strategic pillars with target allocations:

Pillar Allocation Topics
AI Development 42% LLM tools, agent patterns, AI workflows, industry news
Developer Tools 25% git-adr, claude-spec, git-notes-memory, marketplace
Agriculture Tech 23% NSIP, LambLedger, cloudgrow-sim, IoT sensors
Community 10% Retrospectives, roadmaps, announcements

2026 Annual Summary

Metric Count
Total blog posts 63
AI industry analysis posts 24
Friday Roundup news digests 51
Video content 4

Quarterly Themes

Quarter Theme Focus Areas
Q1 AI-Assisted Development & Smart Agriculture git-adr launch, AI coding assistants, NSIP intro
Q2 AI Multimodality & Agriculture IoT Multimodal AI, structured outputs, greenhouse sim
Q3 AI Reasoning & Precision Agriculture Chain-of-thought, breeding season, LambLedger
Q4 AI Year in Review & 2027 Planning Retrospectives, predictions, roadmaps
Document Description
CALENDAR.md Calendar file format reference - YAML schema, fields, enums
WORKFLOW.md Step-by-step content workflow - from calendar to publish
AUTOMATION.md GitHub Actions configuration - cron schedules, issue creation
TEMPLATES.md Template syntax and usage - prompts, schemas, variables
NEWS-SOURCES.md News curation sources and workflow - Friday Roundup guide
SCHEDULING.md Post scheduling methods - PRs, future dates, automation
SOCIAL-CREDENTIALS.md Social media API credentials - OAuth setup, secrets storage

Key Concepts

Content Status Lifecycle

planned → in-progress → review → published
Status Description
planned Scheduled in calendar, not started
in-progress Draft being written
review Draft complete, awaiting review
published Live on website

Priority Levels

Priority Action Timeline
critical Must publish on schedule, no delays
high Target date, minor flexibility
medium Flexible within week
low Can be rescheduled if needed

News Integration

Posts with news_integration: true should incorporate current events from the curated news sources defined in the calendar. The Friday Roundup series always has news integration enabled.

Maintenance

Weekly Tasks (Monday 9am UTC)

Quarterly Tasks

Annual Tasks