banatie-content/content-framework.md

# Banatie Content System — Constitution

**Document owner:** Oleg + @men
**Purpose:** Design documentation for the multi-agent content creation system
**Audience:** Us (Oleg, @men). Not for agents.

---

## Why This Document Exists

This is the reference for understanding WHY the system is built this way. When we return to this project after a break, or when something breaks, or when we want to extend it — this document explains the reasoning.

Agents don't read this. They have their own instructions in system prompts.

---

## Core Architecture

### Single-File Article Pattern

Each article lives in ONE markdown file that accumulates sections as it moves through the pipeline:

```
article.md:
├── Frontmatter (metadata)
├── # Idea (from @spy or manual)
├── # Brief (from @strategist)
├── # Outline (from @architect)
├── # Validation Request (from @architect)
├── # Validation Results (from @validator)
├── # Draft → Text (from @writer, renamed after PASS)
├── # SEO Optimization (from @seo)
├── # Image Specs (from @image-gen)
└── # Review Chat (from @strategist, @architect, @editor)
```

**Why single file:**
- Git-friendly: one commit = one article state
- No sync issues: everything in one place
- Easy to move: just move the file
- Simple mental model: file location = article status

### Stage Folders (Kanban)

```
0-inbox/       → Raw ideas, discoveries
1-planning/    → Ideas with Briefs
2-outline/     → Articles with structure + validation
3-drafting/    → Writing in progress
4-human-review/→ Passed AI review, needs human touch
5-seo/         → SEO optimization stage
6-ready/       → Ready to publish
7-published/   → Archive of published content
```

**Why folders instead of status field:**
- Visual: `ls` shows pipeline state instantly
- Atomic: moving file = changing status
- Git history: folder shows when status changed
- No parsing: don't need to read file to know status

### Dual Context System

```
project-knowledge/  → Loaded into Claude Project Knowledge (static)
shared/             → Read via MCP at runtime (dynamic)
```

**Why two sources:**
- Project Knowledge is fast but requires manual update
- MCP read is slower but always current
- Base context rarely changes (product, audience, competitors)
- Operational context changes often (priorities, experiments, new findings)

**Priority:** shared/ overrides project-knowledge/

This lets us hot-patch agent behavior without rebuilding Claude Desktop projects.

---

## Agent Design Principles

### Agents Have "Soul"

Each agent has a Mindset section that establishes:
- Ownership of outcomes (not just task completion)
- Permission to question and propose
- Understanding of how their work fits the whole

**Why this matters:**
- Order-taking AI produces mediocre results
- Strategic thinking catches problems early
- Ownership means caring about quality

### Positive Instructions

Prompts tell agents what TO DO, not what NOT to do.

**Instead of:** "Don't use generic phrases"
**We write:** "Write like explaining to a smart colleague"

**Why:**
- Negative instructions often backfire (attention on forbidden thing)
- Positive framing is clearer and more actionable
- Matches how you'd instruct a human colleague

### Filesystem MCP Only

All agents use `filesystem:*` MCP tools. No virtual FS, no artifacts, no create_file.

**Why:**
- Real files on real disk
- Git tracks everything
- Human can edit same files
- No "where did my file go?" confusion

### Self-Reference via agent-guide.md

Each agent has an agent-guide.md that it can read to help users.

When user asks "что ты умеешь?" — agent reads its own guide and answers.

**Why:**
- Agent doesn't need to remember everything
- Guide can be updated without changing system prompt
- Consistent help across sessions

---

## File Locations

### Repository Root

```
/projects/my-projects/banatie-content/
```

### Static Context (for Project Knowledge)

```
project-knowledge/
├── project-soul.md        ← Mission, principles, team context
├── banatie-product.md     ← Product description
├── target-audience.md     ← ICP details
├── competitors.md         ← Competitive landscape
└── research-tools-guide.md ← DataForSEO, Brave Search, Perplexity usage
```

These files are added to Claude Desktop Project Knowledge. Agents reference them but don't modify.

### Dynamic Context

```
shared/
└── (empty by default, used for operational updates)
```

When we need to push urgent context to agents (new priority, experiment results, temporary instructions), we put files here. Agents check this folder at /init.

### Agent Definitions

```
desktop-agents/
├── 000-spy/
│   ├── system-prompt.md   ← Full agent instructions
│   └── agent-guide.md     ← Quick reference for user help
├── 001-strategist/
├── 002-architect/
├── 003-writer/
├── 004-editor/
├── 005-seo/
├── 006-image-gen/
├── 007-style-guide-creator/
├── 008-webmaster/
└── 009-validator/
```

**system-prompt.md** — copied into Claude Desktop Project system prompt
**agent-guide.md** — added to Project Knowledge, agent reads to help users

### Content Pipeline

```
0-inbox/          ← Ideas land here
1-planning/       ← Briefs created
2-outline/        ← Structure done + validation pending/complete
3-drafting/       ← Writing happens
4-human-review/   ← AI done, human needed
5-seo/            ← SEO optimization
6-ready/          ← Ready to publish
7-published/      ← Archive
```

### Supporting Files

```
research/              ← All research outputs (@spy writes here)
style-guides/          ← Author personas
pages/                 ← Landing page content (@webmaster writes here)
assets/                ← Static assets
assets/avatars/        ← Author avatar images
```

### Root Level Docs

```
CLAUDE.md                    ← Instructions for Claude Code
README.md                    ← Project overview
human-editing-checklist.md   ← Human editing guide
batch-processing.md          ← Intensive workflow guide
```

---

## Agent Roster

| # | Handle | Role | Reads | Writes | Tools |
|---|--------|------|-------|--------|-------|
| 000 | @spy | Research Scout | shared/, research/ | research/, 0-inbox/, banatie-strategy/inbox/ | DataForSEO, Brave, Perplexity |
| 001 | @strategist | Content Strategist | 0-inbox/, research/, style-guides/ | 1-planning/ | DataForSEO, Perplexity |
| 002 | @architect | Article Architect | 1-planning/, style-guides/ | 2-outline/ | — |
| 003 | @writer | Draft Writer | 2-outline/, 3-drafting/, style-guides/ | 3-drafting/ | — |
| 004 | @editor | Quality Editor | 3-drafting/, style-guides/ | 3-drafting/, 4-human-review/ | — |
| 005 | @seo | SEO Optimizer | 4-human-review/ | 5-seo/ | DataForSEO, Brave |
| 006 | @image-gen | Visual Designer | 5-seo/ | 6-ready/ | — |
| 007 | @style-guide-creator | Persona Designer | style-guides/ | style-guides/ | — |
| 008 | @webmaster | Web Content | research/, 0-inbox/ | pages/ | Brave, Perplexity |
| 009 | @validator | Fact Checker | 2-outline/ | 2-outline/ | Brave, Perplexity |

### Research Tools Distribution

| Tool | @spy | @strategist | @seo | @webmaster | @validator |
|------|------|-------------|------|------------|------------|
| DataForSEO | ✓ | ✓ | ✓ | — | — |
| Brave Search | ✓ | — | ✓ | ✓ | ✓ |
| Perplexity | ✓ | ✓ | — | ✓ | ✓ |

Budget: $0.50/session default for DataForSEO, ~$10/month total.

### @validator — Intentional Isolation

@validator does NOT have access to:
- banatie-product.md
- target-audience.md
- competitors.md

This is intentional. Validator should not know what outcome the article wants. They verify facts objectively, without bias toward "claims that help our positioning."

---

## Key Workflows

### Article Creation (Happy Path)

```
1. @spy discovers topic         → 0-inbox/article.md (Idea)
2. @strategist evaluates        → 1-planning/article.md (+ Brief)
3. @architect structures        → 2-outline/article.md (+ Outline + Validation Request)
4. @validator verifies          → 2-outline/article.md (+ Validation Results)
                                → PASS: ready for writing
                                → REVISE: back to @architect
                                → STOP: kill or major pivot
5. @writer drafts               → 3-drafting/article.md (+ Draft)
6. @editor reviews              → FAIL: stays in 3-drafting/ (+ Critique)
                                → PASS: 4-human-review/article.md
7. Human edits                  → Same file, manual work
8. @seo optimizes               → 5-seo/article.md (+ SEO Optimization)
9. @image-gen specs             → 6-ready/article.md (+ Image Specs)
10. Final review                → Review Chat with @strategist, @architect, @editor
11. Publish                     → 7-published/article.md
```

### Validation Loop

```
@architect creates outline + Validation Request
    ↓
@validator: checks each claim
    ↓
PASS → file moves to 3-drafting/, @writer starts
    ↓
REVISE → @architect fixes claims, @validator re-checks
    ↓
STOP → discuss with human, kill or pivot article
```

### Revision Loop (Writing)

```
@writer creates draft
    ↓
@editor: FAIL (score < 7)
    ↓
Critique added to file
    ↓
@writer reads Critique, rewrites Draft
    ↓
@editor: PASS (score ≥ 7)
    ↓
File moves to 4-human-review/
```

### Review Chat Process

```
After human editing, before publishing:

1. Open chat with @strategist
2. Discuss article, request /review
3. @strategist adds comment to Review Chat
4. Repeat with @architect
5. @editor already gave PASS, can add final comment

All three APPROVED → ready to publish
```

### Landing Page Creation

```
1. Idea/research               → research/ or 0-inbox/
2. @webmaster creates content  → pages/page-name.md
3. Implementation via Claude Code → /projects/.../banatie-service/apps/landing
```

---

## Design Decisions Log

### 2024-12-28: Fact Validator Agent

**Problem:** @writer created drafts with unverified claims presented as facts. Risk of publishing false information that damages credibility.

**Decision:** Added @validator (009) as mandatory step between @architect and @writer.

**Rationale:**
- Opinion pieces need fact-checking before writing, not after
- Validator is intentionally isolated from product/audience context to stay unbiased
- "Guilty until proven innocent" approach — try to disprove claims first
- Clear verdicts (PASS/REVISE/STOP) prevent ambiguity

**Implementation:**
- @architect creates Validation Request section with claims list
- @validator adds Validation Results section
- File stays in 2-outline/ until validation complete
- Only after PASS does file move to 3-drafting/

### 2024-12-27: Dual Context Architecture

**Problem:** Static Project Knowledge couldn't be updated quickly for operational needs.

**Decision:** project-knowledge/ (static, in Project Knowledge) + shared/ (dynamic, read via MCP).

**Rationale:** Base context rarely changes. Operational context (priorities, experiments) changes often. This separation gives us flexibility without constant Project rebuilding.

### 2024-12-27: Agent Mindset Sections

**Problem:** Agents executed tasks mechanically without strategic thinking.

**Decision:** Added "Your Mindset" section to each agent with ownership language.

**Rationale:** Framing affects behavior. Agents that "own outcomes" produce better results than agents that "complete tasks."

### 2024-12-27: DataForSEO Integration

**Problem:** Keyword research was fake (web search guessing volumes).

**Decision:** Integrated DataForSEO MCP for real data.

**Rationale:** Content strategy must be data-driven. $10/month is worth it for real search volumes and difficulty scores.

### 2024-12-27: @webmaster Agent Added

**Problem:** System only produced blog articles, no landing pages.

**Decision:** Created @webmaster for conversion-focused web content.

**Rationale:** Different skill: blog educates, landing converts. Different structure, different copy principles.

### 2024-12-27: Filesystem MCP Enforcement

**Problem:** Agents tried to use virtual FS, artifacts, create_file — files got lost.

**Decision:** Explicit "CRITICAL" section in every prompt: only filesystem:* MCP tools.

**Rationale:** Real files on disk = git tracking, human access, persistence across sessions.

### 2024-12-27: Multi-Tool Research Architecture

**Problem:** DataForSEO is expensive, can't use for all research. Web search is limited.

**Decision:** Three-tool system: DataForSEO (paid, structured), Brave Search (free, fast), Perplexity (free, synthesis).

**Rationale:** Use free tools liberally for discovery, paid tools for validation. Different tools for different purposes.

### 2024-12-27: Review Chat System

**Problem:** After human editing, no validation that article still meets strategic goals.

**Decision:** Review Chat section where @strategist, @architect, @editor leave comments before publishing.

**Rationale:** Human edits might break structure or strategy. Final check by agents catches issues before publishing.

### 2024-12-27: Agent Numbering (000-008)

**Problem:** Single-digit numbering (0-8) sorted incorrectly in some contexts.

**Decision:** Three-digit numbering (000-008, now 000-009) for consistent sorting.

**Rationale:** Future-proof for more agents, consistent display in all tools.

---

## What's NOT Documented Here

- **Agent prompts** — live in desktop-agents/*/system-prompt.md
- **Research findings** — live in research/
- **Style guides** — live in style-guides/
- **Current priorities** — live in shared/ (if any)

This document is architecture. Not operations.

---

## When to Update This Document

- New agent added → update roster
- Folder structure changes → update paths
- Major workflow change → update workflows
- Design decision made → add to log

Don't update for: content changes, research findings, style guide updates.