# 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)
├── # Draft → Text (from @writer, renamed after PASS)
├── # SEO Optimization (from @seo)
└── # Image Specs (from @image-gen)
```

**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
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
└── dataforseo-guide.md    ← DataForSEO usage guide
```

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/
├── 0-spy/
│   ├── system-prompt.md   ← Full agent instructions
│   └── agent-guide.md     ← Quick reference for user help
├── 1-strategist/
├── 2-architect/
├── 3-writer/
├── 4-editor/
├── 5-seo/
├── 6-image-gen/
├── 7-style-guide-creator/
└── 8-webmaster/
```

**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
3-drafting/       ← Writing happens
4-human-review/   ← AI done, human needed
5-seo/            ← SEO optimization (folder name differs from 5-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
```

### 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 |
|---|--------|------|-------|--------|
| 0 | @spy | Research Scout | shared/, research/ | research/, 0-inbox/ |
| 1 | @strategist | Content Strategist | 0-inbox/, research/, style-guides/ | 1-planning/ |
| 2 | @architect | Article Architect | 1-planning/, style-guides/ | 2-outline/ |
| 3 | @writer | Draft Writer | 2-outline/, 3-drafting/, style-guides/ | 3-drafting/ |
| 4 | @editor | Quality Editor | 3-drafting/, style-guides/ | 3-drafting/, 4-human-review/ |
| 5 | @seo | SEO Optimizer | 4-human-review/ | 5-seo/ |
| 6 | @image-gen | Visual Designer | 5-seo/ | 6-ready/ |
| 7 | @style-guide-creator | Persona Designer | style-guides/ | style-guides/ |
| 8 | @webmaster | Web Content | research/, 0-inbox/ | pages/ |

### DataForSEO Access

Only some agents have DataForSEO MCP:
- @spy — competitor intelligence, backlinks, LLM mentions
- @strategist — keyword research, search intent
- @seo — SERP analysis, on-page, LLM responses

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

---

## 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)
4. @writer drafts               → 3-drafting/article.md (+ Draft)
5. @editor reviews              → FAIL: stays in 3-drafting/ (+ Critique)
                                → PASS: 4-human-review/article.md
6. Human edits                  → Same file, manual work
7. @seo optimizes               → 5-seo/article.md (+ SEO Optimization)
8. @image-gen specs             → 6-ready/article.md (+ Image Specs)
9. Publish                      → 7-published/article.md
```

### Revision Loop

```
@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/
```

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

---

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