12 KiB
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)
└── # 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
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:
lsshows 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/
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
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/ | 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 |
Research Tools Distribution
| Tool | @spy | @strategist | @seo | @webmaster |
|---|---|---|---|---|
| DataForSEO | ✓ | ✓ | ✓ | — |
| Brave Search | ✓ | — | ✓ | ✓ |
| Perplexity | ✓ | ✓ | — | ✓ |
Budget: $0.50/session default for DataForSEO, ~$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. Final review → Review Chat with @strategist, @architect, @editor
10. 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/
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-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) 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.