341 lines
10 KiB
Markdown
341 lines
10 KiB
Markdown
# 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.
|