# Content Creation Framework

## Overview

Multi-agent system for creating technical content. **8 Claude Desktop agents** handle different aspects of content creation, **Claude Code** manages the repository.

**Core principle:** One file = one article. File moves between stage folders like a kanban card.

---

## File Structure

### Single File Per Article

Each article is ONE markdown file with frontmatter:

```
{stage}/{slug}.md
```

Examples:
- `0-inbox/nextjs-images.md`
- `3-drafting/nextjs-images.md`
- `7-published/nextjs-images.md`

### Frontmatter Template

```yaml
---
slug: nextjs-images
title: "Generate Images in Next.js with AI"
author: henry
status: drafting
created: 2024-12-22
updated: 2024-12-25
content_type: tutorial

# SEO (added by @seo)
primary_keyword: "ai image generation nextjs"
secondary_keywords: ["nextjs api", "gemini images"]
meta_description: "Learn how to generate AI images..."

# Images (added by @image-gen)
hero_image: "https://banatie.app/cdn/..."

# Publishing (added after publish)
publish_url: "https://dev.to/..."
publish_date: 2024-12-26
platform: dev.to
---
```

### Status Values

| Status | Folder | Meaning |
|--------|--------|---------|
| `inbox` | 0-inbox/ | Raw idea, not yet evaluated |
| `planning` | 1-planning/ | Brief being created |
| `outline` | 2-outline/ | Structure being designed |
| `drafting` | 3-drafting/ | Writing in progress |
| `revision` | 3-drafting/ | Revision after critique |
| `review` | 4-human-review/ | Human editing |
| `optimization` | 5-optimization/ | SEO + images |
| `ready` | 6-ready/ | Ready to publish |
| `published` | 7-published/ | Published, archived |

### "In Progress" Detection

- If `status` matches current folder → file is being worked on
- If `status` is from previous folder or missing → new file, not yet started

---

## File Evolution

File grows by accumulating sections as it moves through pipeline:

### Stage: 0-inbox
```markdown
---
slug: nextjs-images
title: "Idea: Next.js image generation"
status: inbox
created: 2024-12-22
---

# Idea

(raw notes, research links, pain points discovered)
```

### Stage: 1-planning (after @strategist)
```markdown
---
(frontmatter with author, keywords added)
---

# Brief

## Strategic Context
...

## Target Reader
...

## Keywords
...

## Content Requirements
...
```

### Stage: 2-outline (after @architect)
```markdown
---
(frontmatter)
---

# Brief
(preserved from planning)

---

# Outline

## Article Structure
...

## Section Breakdown
...

## Code Examples Planned
...
```

### Stage: 3-drafting (after @writer + @editor)
```markdown
---
(frontmatter)
---

# Brief
(preserved)

---

# Outline
(preserved)

---

# Draft

(full article text, latest version only)

---

# Critique

## Review 1 (2024-12-23)
**Score:** 5.8/10 — FAIL

### Critical Issues
- ...

### Recommendations
- ...

## Review 2 (2024-12-24)  
**Score:** 7.4/10 — PASS

### Minor Issues
- ...

(critique history accumulates, draft gets rewritten each iteration)
```

### Stage: 4-human-review (after PASS)
```markdown
---
(frontmatter)
---

# Brief
(preserved)

---

# Outline  
(preserved)

---

# Text

(draft renamed to Text, Critique section removed)
(human edits this section)
```

### Stage: 5-optimization (after @seo + @image-gen)
```markdown
---
(frontmatter with SEO fields, hero_image added)
---

# Brief
(preserved)

---

# Outline
(preserved)

---

# Text

(SEO-optimized text with images embedded)

![Diagram description](https://banatie.app/cdn/...)
```

### Stage: 6-ready
Same as optimization, ready for copy-paste to platform.

### Stage: 7-published
```markdown
---
(frontmatter with publish_url, publish_date, platform added)
---

(same content, archived)
```

---

## The Pipeline

```
Research → Inbox → Planning → Outline → Drafting ⟲ → Review → Optimization → Ready → Published
   @spy            @strategist  @architect  @writer     Human    @seo          Human   Human
                                            @editor              @image-gen
```

### Revision Loop

```
@writer creates Draft
    ↓
@editor reviews → FAIL (score < 7)
    ↓
status: revision, Critique added to file
    ↓
@writer reads Critique, rewrites Draft
    ↓
@editor reviews again → PASS (score ≥ 7)
    ↓
status: review, file moves to 4-human-review/
Critique section removed, Draft renamed to Text
```

---

## Agents

| # | Agent | Role | Reads from | Writes to |
|---|-------|------|------------|-----------|
| 0 | @spy | Research | web, communities | research/ |
| 1 | @strategist | Topic planning | 0-inbox/, research/ | 1-planning/ |
| 2 | @architect | Article structure | 1-planning/ | 2-outline/ |
| 3 | @writer | Draft writing | 2-outline/, 3-drafting/ | 3-drafting/ |
| 4 | @editor | Quality review | 3-drafting/ | 3-drafting/ (adds Critique) |
| 5 | @seo | SEO + GEO | 4-human-review/ | 5-optimization/ |
| 6 | @image-gen | Visual assets | 5-optimization/ | 5-optimization/ (updates file) |
| 7 | @style-guide-creator | Author personas | interview | style-guides/ |

### Special Agents

**@spy** — Creates research files in `research/`, not article files. Other agents read from there.

**@style-guide-creator** — Creates author style guides in `style-guides/`. Not part of article pipeline.

---

## Agent Session Protocol

### Starting a Session

Every agent responds to `/init` command:

1. Read required shared files
2. List files in input folder(s)
3. Show which files are new vs in-progress
4. Ask user which file to work on

Example:
```
User: /init

Agent: Загружаю контекст...
✓ shared/banatie-product.md
✓ style-guides/AUTHORS.md

Файлы в 2-outline/:
• nextjs-images.md — status: outline (в работе)
• react-placeholders.md — status: planning (новый)

С каким файлом работаем?
```

### During Session

- One file per conversation
- Agent works on that file until done
- User can ask agent to perform operations

### Ending Session (Handoff)

When work is complete:

1. Agent summarizes what was done
2. Agent asks: "Переносим в {next-stage}?"
3. User confirms
4. Agent moves file to next folder
5. Agent updates status in frontmatter
6. Agent reports: "Готово. Открой @{next-agent} для продолжения."

---

## Stage Transitions

### Allowed Transitions

| From | To | Trigger |
|------|----|---------|
| inbox | planning | @strategist approves idea |
| planning | outline | @strategist completes brief |
| outline | drafting | @architect completes outline |
| drafting | drafting | @editor FAIL → revision |
| drafting | review | @editor PASS |
| review | optimization | Human completes edit |
| optimization | ready | @seo + @image-gen complete |
| ready | published | Human publishes |

### Backward Transitions (with user confirmation)

| From | To | When |
|------|----|------|
| review | drafting | Human found major issues |
| optimization | review | Need more human edits |
| Any | inbox | Start over |

---

## Content Sources

### Original Content
Standard flow: idea → planning → outline → draft

### From @spy Research
1. @spy creates `research/topic-name.md`
2. @strategist reads research, creates article in 0-inbox/
3. Normal flow continues

### From Perplexity Threads
1. Save Perplexity thread to `research/perplexity-topic.md`
2. @strategist evaluates, creates article with source reference
3. @architect restructures Q&A into article format
4. @writer translates Russian → English, adapts to author voice

---

## Folder Structure

```
banatie-content/
├── CLAUDE.md                 ← Claude Code instructions
├── README.md
├── shared/
│   ├── banatie-product.md
│   ├── target-audience.md
│   ├── competitors.md
│   ├── content-framework.md  ← This file
│   ├── model-recommendations.md
│   └── human-editing-checklist.md
├── style-guides/
│   ├── AUTHORS.md
│   ├── banatie-brand.md
│   └── henry-technical.md
├── research/                 ← @spy output
│   ├── keywords/
│   ├── competitors/
│   ├── trends/
│   └── weekly-digests/
├── desktop-agents/           ← Agent configs
│   └── {N}-{name}/
│       ├── system-prompt.md
│       └── agent-guide.md
├── 0-inbox/                  ← Raw ideas
├── 1-planning/               ← Briefs
├── 2-outline/                ← Structures
├── 3-drafting/               ← Drafts + Revisions
├── 4-human-review/           ← Human editing
├── 5-optimization/           ← SEO + Images
├── 6-ready/                  ← Ready to publish
└── 7-published/              ← Archive
```

---

## Model Recommendations

| Agent | Model | Reason |
|-------|-------|--------|
| @spy | Sonnet | Web search, aggregation |
| @strategist | **Opus** | Strategic decisions |
| @architect | **Opus** | Structure design |
| @writer | Sonnet | Content generation |
| @editor | **Opus** | Critical analysis |
| @seo | Sonnet | Technical optimization |
| @image-gen | Sonnet | Image prompts |
| @style-guide-creator | **Opus** | Deep persona work |

---

## Language Protocol

- **Files:** Always English
- **Communication with agents:** Russian
- **Tech terms:** English even in Russian dialogue

---

## Time Estimates

| Phase | Time |
|-------|------|
| Research (@spy) | 30 min/week |
| Planning + Outline | 30-45 min |
| Draft + Critique cycle | 30-45 min |
| Human Edit | 30-60 min |
| SEO + Images | 20-30 min |
| **Total per article** | **2.5-4 hrs** |