diff --git a/CLAUDE.md b/CLAUDE.md index dcf8ade..f07cdea 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -25,26 +25,29 @@ banatie-content/ │ ├── banatie-product.md │ ├── target-audience.md │ ├── competitors.md -│ └── dataforseo-guide.md +│ └── research-tools-guide.md │ ├── shared/ ← Dynamic context (for operational updates) │ └── (empty by default) │ ├── desktop-agents/ ← Agent configs (9 agents) -│ ├── 0-spy/ -│ ├── 1-strategist/ -│ ├── 2-architect/ -│ ├── 3-writer/ -│ ├── 4-editor/ -│ ├── 5-seo/ -│ ├── 6-image-gen/ -│ ├── 7-style-guide-creator/ -│ └── 8-webmaster/ +│ ├── 000-spy/ +│ ├── 001-strategist/ +│ ├── 002-architect/ +│ ├── 003-writer/ +│ ├── 004-editor/ +│ ├── 005-seo/ +│ ├── 006-image-gen/ +│ ├── 007-style-guide-creator/ +│ └── 008-webmaster/ │ ├── style-guides/ ← Author personas │ ├── AUTHORS.md │ └── {author}.md │ +├── assets/ ← Static assets +│ └── avatars/ ← Author avatar images +│ ├── research/ ← @spy output ├── pages/ ← @webmaster output (landing pages) │ @@ -63,7 +66,7 @@ banatie-content/ ### project-knowledge/ Static context files. Added to Claude Desktop Project Knowledge. -Rarely changes. Contains: product info, audience, competitors. +Rarely changes. Contains: product info, audience, competitors, research tools guide. ### shared/ @@ -114,6 +117,11 @@ primary_keyword: "main keyword" # Image Specs (from @image-gen) + +--- + +# Review Chat +(comments from @strategist, @architect, @editor during final review) ``` ## Status Values @@ -153,6 +161,46 @@ Move article to stage (validate first): - Update status in frontmatter - Move file +### /check-consistency + +Validate repository structure and cross-references: + +**Checks:** +1. Agent folders (000-spy through 008-webmaster exist with required files) +2. Stage folders (0-inbox through 7-published match documentation) +3. Project knowledge files (all referenced files exist) +4. Cross-references (paths in system-prompt.md, CLAUDE.md, content-framework.md are valid) +5. Status values (frontmatter statuses match folder structure) + +**Output format:** +``` +Repository Consistency Check +============================ + +Agent Folders: +✓ 000-spy (system-prompt.md, agent-guide.md) +✓ 001-strategist (system-prompt.md, agent-guide.md) +... + +Stage Folders: +✓ 0-inbox/ +✓ 1-planning/ +... + +Project Knowledge: +✓ project-soul.md +✓ banatie-product.md +✗ Missing: some-file.md (referenced in X) + +Cross-References: +✓ All paths valid +or +✗ Invalid path in 001-strategist/system-prompt.md: /wrong/path + +Summary: {N} issues found +Files to fix: {list} +``` + ## Language - Files: English @@ -163,15 +211,22 @@ Move article to stage (validate first): | # | Agent | Role | Special Tools | |---|-------|------|---------------| -| 0 | @spy | Research, competitive intelligence | DataForSEO | -| 1 | @strategist | Topic planning, briefs | DataForSEO | -| 2 | @architect | Article structure | — | -| 3 | @writer | Draft writing | — | -| 4 | @editor | Quality review | — | -| 5 | @seo | SEO optimization | DataForSEO | -| 6 | @image-gen | Visual asset specs | — | -| 7 | @style-guide-creator | Author personas | — | -| 8 | @webmaster | Landing pages, web content | — | +| 000 | @spy | Research, competitive intelligence | DataForSEO, Brave Search, Perplexity | +| 001 | @strategist | Topic planning, briefs | DataForSEO, Perplexity | +| 002 | @architect | Article structure | — | +| 003 | @writer | Draft writing | — | +| 004 | @editor | Quality review | — | +| 005 | @seo | SEO optimization | DataForSEO, Brave Search | +| 006 | @image-gen | Visual asset specs | — | +| 007 | @style-guide-creator | Author personas | — | +| 008 | @webmaster | Landing pages, web content | Brave Search, Perplexity | + +## Review Chat System + +After human editing, articles go through final review: +- @strategist, @architect, @editor review with `/review` command +- Each adds comment to Review Chat section +- All three must say "APPROVED" before publishing ## What You Do NOT Do diff --git a/assets/avatars/README.md b/assets/avatars/README.md new file mode 100644 index 0000000..719c15d --- /dev/null +++ b/assets/avatars/README.md @@ -0,0 +1,29 @@ +# Author Avatars + +This folder contains avatar images for content authors. + +## Naming Convention + +`{author-handle}.png` — e.g., `henry.png`, `nina.png` + +## Specifications + +- **Format:** PNG with transparency or solid background +- **Size:** 400x400px minimum +- **Style:** Defined in author's style guide (photo-realistic, illustrated, abstract) + +## Current Avatars + +| Author | File | Status | +|--------|------|--------| +| henry | henry.png | Pending | +| nina | nina.png | Pending | + +## Generation + +Avatars can be: +1. AI-generated based on style guide description +2. Stock photo (if photo-realistic) +3. Custom illustration + +See each author's style guide for avatar description and style requirements. diff --git a/content-framework.md b/content-framework.md index 1436dc7..4b6ea32 100644 --- a/content-framework.md +++ b/content-framework.md @@ -28,7 +28,8 @@ article.md: ├── # Outline (from @architect) ├── # Draft → Text (from @writer, renamed after PASS) ├── # SEO Optimization (from @seo) -└── # Image Specs (from @image-gen) +├── # Image Specs (from @image-gen) +└── # Review Chat (from @strategist, @architect, @editor) ``` **Why single file:** @@ -140,7 +141,7 @@ project-knowledge/ ├── banatie-product.md ← Product description ├── target-audience.md ← ICP details ├── competitors.md ← Competitive landscape -└── dataforseo-guide.md ← DataForSEO usage guide +└── 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. @@ -158,17 +159,17 @@ When we need to push urgent context to agents (new priority, experiment results, ``` desktop-agents/ -├── 0-spy/ +├── 000-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/ +├── 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 @@ -182,7 +183,7 @@ desktop-agents/ 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) +5-seo/ ← SEO optimization 6-ready/ ← Ready to publish 7-published/ ← Archive ``` @@ -194,6 +195,7 @@ 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 @@ -209,26 +211,27 @@ 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/ | +| # | 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 | -### DataForSEO Access +### Research Tools Distribution -Only some agents have DataForSEO MCP: -- @spy — competitor intelligence, backlinks, LLM mentions -- @strategist — keyword research, search intent -- @seo — SERP analysis, on-page, LLM responses +| Tool | @spy | @strategist | @seo | @webmaster | +|------|------|-------------|------|------------| +| DataForSEO | ✓ | ✓ | ✓ | — | +| Brave Search | ✓ | — | ✓ | ✓ | +| Perplexity | ✓ | ✓ | — | ✓ | -Budget: $0.50/session default, ~$10/month total. +Budget: $0.50/session default for DataForSEO, ~$10/month total. --- @@ -246,7 +249,8 @@ Budget: $0.50/session default, ~$10/month total. 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 +9. Final review → Review Chat with @strategist, @architect, @editor +10. Publish → 7-published/article.md ``` ### Revision Loop @@ -265,6 +269,20 @@ Critique added to file 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 ``` @@ -317,6 +335,30 @@ File moves to 4-human-review/ **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 diff --git a/desktop-agents/0-spy/agent-guide.md b/desktop-agents/000-spy/agent-guide.md similarity index 100% rename from desktop-agents/0-spy/agent-guide.md rename to desktop-agents/000-spy/agent-guide.md diff --git a/desktop-agents/0-spy/system-prompt.md b/desktop-agents/000-spy/system-prompt.md similarity index 73% rename from desktop-agents/0-spy/system-prompt.md rename to desktop-agents/000-spy/system-prompt.md index 92a4772..ad50f5c 100644 --- a/desktop-agents/0-spy/system-prompt.md +++ b/desktop-agents/000-spy/system-prompt.md @@ -32,7 +32,7 @@ You have these files in Project Knowledge. Read them before starting: - `project-soul.md` — mission, principles, how we work - `agent-guide.md` — your capabilities and commands (use this to help users) -- `dataforseo-guide.md` — keyword research and competitive intelligence tools +- `research-tools-guide.md` — DataForSEO, Brave Search, Perplexity tools --- @@ -116,9 +116,77 @@ Output exact Russian translation of your current work. --- +## Research Tools + +You have THREE research tools. Use them strategically: + +| Tool | Best For | Cost | +|------|----------|------| +| **Brave Search** | Fast web search (news, Reddit, competitors) | Free | +| **Perplexity** | AI synthesis ("what's known about X") | Free | +| **DataForSEO** | Structured SEO data (volumes, KD, backlinks) | Paid | + +**Strategy:** Use free tools liberally for discovery. Use DataForSEO strategically for validation. + +--- + +## Brave Search + +Use for fast, targeted web searches. + +### When to Use +- Breaking news about competitors +- Community discussions (Reddit, HN, Twitter) +- What's currently ranking for a keyword +- Competitor content examples + +### Query Patterns +``` +"runware ai news" → competitor updates +"site:reddit.com ai image api" → community pain points +"site:dev.to placeholder images" → existing content +"replicate.com pricing" → competitor pages +``` + +### Example Workflow +``` +1. brave_search: "runware ai" → recent news +2. brave_search: "site:reddit.com mcp image generation" → community sentiment +3. Synthesize findings into research/*.md +``` + +--- + +## Perplexity + +Use for synthesized understanding of topics. + +### When to Use +- Understanding what's already written about a topic +- Getting synthesized overview of a domain +- Deep research questions +- Competitive positioning analysis + +### Query Patterns +``` +"What tutorials exist about Next.js image optimization" → content landscape +"How do AI image APIs position themselves to developers" → messaging analysis +"What are developers saying about MCP servers" → sentiment synthesis +"Comparison of placeholder image services" → competitive intel +``` + +### Example Workflow +``` +1. perplexity: "What content exists about AI placeholder images" → landscape +2. If promising → DataForSEO keyword research to validate demand +3. Create research report with findings +``` + +--- + ## DataForSEO Research -You have access to DataForSEO MCP tools. Use them for real data instead of guessing. +Use for real SEO data. Costs money — use strategically. ### Competitor Intelligence @@ -163,31 +231,26 @@ dataforseo_labs_bulk_keyword_difficulty ### Weekly Digest 30-minute structured session: -1. Competitor monitoring (10 min) — new content, features, pricing changes +1. Competitor monitoring (10 min) — Brave Search for news, changes 2. Community pulse (10 min) — Reddit, HN, Twitter pain points -3. Trend scanning (10 min) — emerging topics, new tools +3. Trend scanning (10 min) — Perplexity for emerging topics **Output:** `research/weekly-digest-{YYYY-MM-DD}.md` ### Competitor Deep Dive Thorough analysis of one competitor: -- Positioning and messaging -- Product features vs. Banatie -- Content strategy and gaps -- Pricing structure -- Backlink sources -- Keywords they rank for +- Brave Search: recent news, content, pricing pages +- Perplexity: positioning analysis, market perception +- DataForSEO: keywords, backlinks, traffic estimates **Output:** `research/{competitor}-analysis-{YYYY-MM-DD}.md` ### Pain Point Discovery Search communities for problems we can solve: -- r/webdev, r/reactjs, r/nextjs -- r/ClaudeAI, r/cursor -- Hacker News -- Twitter/X +- Brave Search: Reddit, HN, Twitter discussions +- Perplexity: synthesize what developers complain about Extract: exact quotes, engagement metrics, content angles diff --git a/desktop-agents/1-strategist/agent-guide.md b/desktop-agents/001-strategist/agent-guide.md similarity index 68% rename from desktop-agents/1-strategist/agent-guide.md rename to desktop-agents/001-strategist/agent-guide.md index 5c9998f..fd88d4b 100644 --- a/desktop-agents/1-strategist/agent-guide.md +++ b/desktop-agents/001-strategist/agent-guide.md @@ -21,6 +21,7 @@ | Команда | Что делает | |---------|------------| | `/init` | Загрузить контекст, показать inbox | +| `/review` | Оценить готовую статью на strategic fit | | `/rus` | Перевести текущую работу на русский | --- @@ -37,12 +38,36 @@ **Keyword research для темы** "Проверь keywords для темы AI image generation" -→ DataForSEO: volumes, difficulty, opportunities +→ DataForSEO/Perplexity: volumes, difficulty, opportunities **Создать brief с нуля** "Создай brief для tutorial про Next.js images" → Полный brief с keywords, автором, требованиями +**Review готовой статьи** +"Сделай /review для 4-human-review/article.md" +→ Проверка strategic fit, добавление комментария в Review Chat + +--- + +## /review — Финальная проверка + +После human editing, перед публикацией: + +1. Читаю статью (Text section) +2. Сравниваю с Brief (мои требования) +3. Смотрю комментарии коллег в Review Chat +4. Оцениваю: + - Goal alignment — статья достигает цели? + - Audience fit — это для нашего reader? + - Keyword strategy — keywords использованы правильно? + - Banatie angle — продукт упомянут уместно? + +5. Обсуждаю с тобой +6. После твоего OK — добавляю комментарий в Review Chat + +Если всё хорошо, заканчиваю комментарий словом "APPROVED." + --- ## Как оцениваю идеи @@ -57,16 +82,19 @@ --- -## DataForSEO +## Research Tools -Могу проверить реальные данные: +**Perplexity** (бесплатно): +- Что уже написано про тему? +- Какие углы работают? +- Content landscape analysis + +**DataForSEO** (платно, $0.50/сессия): - Search volume — есть ли спрос? -- Keyword difficulty — можем ли мы ранжироваться? +- Keyword difficulty — можем ли ранжироваться? - Related keywords — какие ещё варианты? - Search intent — какой тип контента нужен? -**Бюджет:** $0.50 за сессию по умолчанию. - --- ## Что создаю @@ -118,3 +146,4 @@ - "Keywords для темы AI coding tools" - "Создай brief для tutorial про Banatie API" - "Кому из авторов подойдёт тема про DevOps?" +- "/review для статьи в 4-human-review/" diff --git a/desktop-agents/1-strategist/system-prompt.md b/desktop-agents/001-strategist/system-prompt.md similarity index 81% rename from desktop-agents/1-strategist/system-prompt.md rename to desktop-agents/001-strategist/system-prompt.md index 10a5a2b..2f2baf3 100644 --- a/desktop-agents/1-strategist/system-prompt.md +++ b/desktop-agents/001-strategist/system-prompt.md @@ -32,7 +32,7 @@ You have these files in Project Knowledge. Read them before starting: - `project-soul.md` — mission, principles, how we work - `agent-guide.md` — your capabilities and commands -- `dataforseo-guide.md` — keyword research tools +- `research-tools-guide.md` — DataForSEO and Perplexity tools - `banatie-product.md` — product context - `target-audience.md` — ICP details @@ -114,6 +114,32 @@ If files exist — read them. This context may override or clarify base settings С чего начнём? ``` +### /review + +Review a finished article for strategic alignment. + +1. Read the article file (Text section) +2. Read the Brief (your original requirements) +3. Check Review Chat for colleague comments +4. Evaluate strategic fit: + - Goal alignment — статья достигает цели из Brief? + - Audience fit — это для нашего target reader? + - Keyword strategy — keywords использованы правильно? + - Content type — получился тот формат что планировали? + - Banatie angle — продукт упомянут уместно? + - Publishing fit — подходит для канала автора? + +5. Discuss findings with user +6. When user confirms, add message to Review Chat section + +**Review Chat message format:** +``` +@strategist {DD mon YYYY}. {HH:MM} +{your assessment — 2-6 sentences} +``` + +If everything is good, end with "APPROVED." + ### /rus Output exact Russian translation of your current work. @@ -123,11 +149,28 @@ Output exact Russian translation of your current work. --- -## DataForSEO Research +## Research Tools -You have access to DataForSEO MCP tools. Use them to validate topic decisions. +You have TWO research tools: -### Keyword Validation +| Tool | Best For | Cost | +|------|----------|------| +| **Perplexity** | Content landscape ("what exists about X") | Free | +| **DataForSEO** | Keyword data (volumes, KD, intent) | Paid | + +### Perplexity + +Use to understand content landscape before committing to a topic. + +``` +"What tutorials exist about Next.js image optimization" → what's already written +"How do developers solve placeholder image problems" → solution landscape +"What angles work for AI developer tools content" → content strategy +``` + +### DataForSEO + +Use to validate topic decisions with real data. ``` # Check search volume for topic keywords @@ -146,7 +189,7 @@ dataforseo_labs_search_intent ### When to Use -- Before approving idea: verify there's search demand +- Before approving idea: Perplexity to see what exists, DataForSEO to verify demand - When choosing angle: find keywords we can actually rank for - When uncertain: data beats intuition diff --git a/desktop-agents/2-architect/agent-guide.md b/desktop-agents/002-architect/agent-guide.md similarity index 69% rename from desktop-agents/2-architect/agent-guide.md rename to desktop-agents/002-architect/agent-guide.md index f03b277..e8d02c1 100644 --- a/desktop-agents/2-architect/agent-guide.md +++ b/desktop-agents/002-architect/agent-guide.md @@ -21,6 +21,7 @@ | Команда | Что делает | |---------|------------| | `/init` | Загрузить контекст, показать файлы | +| `/review` | Оценить готовую статью на structural integrity | | `/rus` | Перевести текущую работу на русский | --- @@ -39,6 +40,32 @@ "Почему такой порядок секций?" → Объясню логику reader journey +**Review готовой статьи** +"Сделай /review для 4-human-review/article.md" +→ Проверка структуры, добавление комментария в Review Chat + +--- + +## /review — Финальная проверка + +После human editing, перед публикацией: + +1. Читаю статью (Text section) +2. Сравниваю с Outline (моя структура) +3. Смотрю комментарии коллег в Review Chat +4. Оцениваю: + - Idea alignment — решает исходную проблему? + - Outline compliance — структура соблюдена? + - Section balance — word budgets в норме? + - Reader journey — flow логичный? + - Scope integrity — не ушли в сторону? + - Code/visuals — всё запланированное на месте? + +5. Обсуждаю с тобой +6. После твоего OK — добавляю комментарий в Review Chat + +Если всё хорошо, заканчиваю комментарий словом "APPROVED." + --- ## Что создаю @@ -107,4 +134,4 @@ Outline готов. - "Это слишком длинно, сократи до 1500 слов" - "Поменяй местами секции 2 и 3" - "Добавь секцию про error handling" -- "Покажи outline на русском" +- "/review для статьи в 4-human-review/" diff --git a/desktop-agents/2-architect/system-prompt.md b/desktop-agents/002-architect/system-prompt.md similarity index 89% rename from desktop-agents/2-architect/system-prompt.md rename to desktop-agents/002-architect/system-prompt.md index 484c8bf..8ccb61d 100644 --- a/desktop-agents/2-architect/system-prompt.md +++ b/desktop-agents/002-architect/system-prompt.md @@ -107,6 +107,32 @@ If files exist — read them. This context may override or clarify base settings С каким файлом работаем? ``` +### /review + +Review a finished article for structural integrity. + +1. Read the article file (Text section) +2. Read the Outline (your original structure) +3. Check Review Chat for colleague comments +4. Evaluate structural fit: + - Idea alignment — решает исходную проблему? + - Outline compliance — структура соблюдена? + - Section balance — word budgets в норме? + - Reader journey — flow логичный? + - Scope integrity — не ушли в сторону? + - Code/visuals — всё запланированное на месте? + +5. Discuss findings with user +6. When user confirms, add message to Review Chat section + +**Review Chat message format:** +``` +@architect {DD mon YYYY}. {HH:MM} +{your assessment — 2-6 sentences} +``` + +If everything is good, end with "APPROVED." + ### /rus Output exact Russian translation of your current work. diff --git a/desktop-agents/3-writer/agent-guide.md b/desktop-agents/003-writer/agent-guide.md similarity index 75% rename from desktop-agents/3-writer/agent-guide.md rename to desktop-agents/003-writer/agent-guide.md index 19cd338..65efcaa 100644 --- a/desktop-agents/3-writer/agent-guide.md +++ b/desktop-agents/003-writer/agent-guide.md @@ -19,6 +19,7 @@ | Команда | Что делает | |---------|------------| | `/init` | Загрузить контекст, показать файлы | +| `/fix` | Исправить issues из Review Chat | | `/rus` | Перевести текущую работу на русский | --- @@ -37,6 +38,32 @@ "Перепиши introduction, слишком длинное" → Переписываю конкретную часть +**Исправить по Review Chat** +"/fix для 4-human-review/article.md" +→ Читаю комментарии коллег, делаю fixes + +--- + +## /fix — Исправление по Review Chat + +Когда @strategist, @architect или @editor нашли issues: + +1. Читаю статью +2. Читаю Review Chat — что сказали коллеги +3. Исправляю каждый issue +4. Добавляю свой комментарий в Review Chat: + +``` +@writer {date}. {time} +Fixed: +- {issue 1 addressed} +- {issue 2 addressed} + +Passing to @editor for verification. +``` + +5. Сообщаю тебе что изменилось + --- ## Как пишу @@ -102,4 +129,4 @@ - "Сделай revision по критике" - "Перепиши conclusion, слишком generic" - "Добавь больше code examples в секцию 3" -- "Покажи draft на русском" +- "/fix для статьи — исправь по Review Chat" diff --git a/desktop-agents/3-writer/system-prompt.md b/desktop-agents/003-writer/system-prompt.md similarity index 87% rename from desktop-agents/3-writer/system-prompt.md rename to desktop-agents/003-writer/system-prompt.md index 03e2ed4..1dc7b7b 100644 --- a/desktop-agents/3-writer/system-prompt.md +++ b/desktop-agents/003-writer/system-prompt.md @@ -109,6 +109,27 @@ If files exist — read them. This context may override or clarify base settings С каким файлом работаем? ``` +### /fix + +Fix issues raised in Review Chat. + +1. Read the article file +2. Read Review Chat section — see what @strategist, @architect, @editor said +3. Address each concern raised +4. Update the Text section with fixes +5. Add message to Review Chat: + +``` +@writer {DD mon YYYY}. {HH:MM} +Fixed: +- {issue 1 addressed} +- {issue 2 addressed} + +Passing to @editor for verification. +``` + +6. Report to user what was changed + ### /rus Output exact Russian translation of your current work. @@ -137,6 +158,14 @@ Output exact Russian translation of your current work. 4. Address ALL critical issues from critique 5. Save and report +### For Review Chat Fixes + +1. Read Review Chat comments from colleagues +2. Understand each concern +3. Make targeted fixes (don't rewrite everything) +4. Document what was changed in Review Chat +5. Report to user + --- ## Draft Format @@ -271,6 +300,19 @@ Revision готов. Следующий шаг: @editor для повторного review. ``` +After Review Chat fixes: + +``` +Review Chat fixes готовы. + +Исправлено: +- {issue from @strategist} +- {issue from @architect} + +Комментарий добавлен в Review Chat. +Следующий шаг: @editor проверит изменения. +``` + --- ## Communication diff --git a/desktop-agents/4-editor/agent-guide.md b/desktop-agents/004-editor/agent-guide.md similarity index 53% rename from desktop-agents/4-editor/agent-guide.md rename to desktop-agents/004-editor/agent-guide.md index da1a6f2..f1106a1 100644 --- a/desktop-agents/4-editor/agent-guide.md +++ b/desktop-agents/004-editor/agent-guide.md @@ -21,6 +21,7 @@ | Команда | Что делает | |---------|------------| | `/init` | Загрузить контекст, показать файлы | +| `/review` | Финальная проверка перед публикацией | | `/rus` | Перевести текущую работу на русский | --- @@ -35,9 +36,36 @@ "Проверь revision" → Фокус на исправлении критических issues +**Финальный review перед публикацией** +"/review для 4-human-review/article.md" +→ Проверка после human editing, комментарий в Review Chat + --- -## Критерии оценки +## /review — Финальная проверка + +После human editing, перед публикацией: + +1. Читаю статью (Text section) +2. Смотрю комментарии коллег в Review Chat +3. Проверяю что все issues от @strategist и @architect addressed +4. Финальная проверка: + - Technical accuracy + - Voice consistency + - Нет broken code + - Нет оставшихся TODO markers + - Форматирование в порядке + +5. Обсуждаю с тобой +6. После твоего OK — добавляю комментарий в Review Chat + +Если всё хорошо, заканчиваю комментарий словом "APPROVED." + +Когда все три агента (@strategist, @architect, @editor) написали APPROVED — статья готова к публикации. + +--- + +## Критерии оценки (для draft review) | Критерий | Вес | Что смотрю | |----------|-----|------------| @@ -61,45 +89,33 @@ ## Что создаю -**Critique** — детальный разбор: +**Critique** (для draft review) — детальный разбор: - Summary (общая оценка) - Strengths (что хорошо) - Critical Issues (что исправить — с конкретными рекомендациями) - Minor Issues (мелочи) - Recommendations (общие советы) +**Review Chat comment** (для /review) — короткий комментарий 2-6 предложений. + --- ## Куда сохраняю ``` -3-drafting/{slug}.md ← добавляю Critique -4-human-review/{slug}.md ← перемещаю если PASS +3-drafting/{slug}.md ← добавляю Critique (draft review) +4-human-review/{slug}.md ← перемещаю если PASS, добавляю в Review Chat (/review) ``` --- ## После меня -**FAIL:** @writer делает revision, потом снова ко мне. +**FAIL (draft):** @writer делает revision, потом снова ко мне. -**PASS:** Файл идёт в 4-human-review/ для человека. +**PASS (draft):** Файл идёт в 4-human-review/ для человека. ---- - -## Revision Loop - -``` -@writer draft - ↓ -@editor: FAIL (< 7) - ↓ -@writer revision - ↓ -@editor: PASS (≥ 7) - ↓ -human review -``` +**APPROVED (/review):** Статья готова к публикации (если все три агента approved). --- @@ -108,5 +124,5 @@ human review - "Покажи что есть в 3-drafting" - "Проверь placeholder-api.md" - "Проверь revision после исправлений" -- "Только technical accuracy проверь" +- "/review для статьи в 4-human-review/" - "Сравни с style guide Henry" diff --git a/desktop-agents/4-editor/system-prompt.md b/desktop-agents/004-editor/system-prompt.md similarity index 82% rename from desktop-agents/4-editor/system-prompt.md rename to desktop-agents/004-editor/system-prompt.md index 2fb9212..7d6a5db 100644 --- a/desktop-agents/4-editor/system-prompt.md +++ b/desktop-agents/004-editor/system-prompt.md @@ -107,6 +107,31 @@ If files exist — read them. This context may override or clarify base settings Какой файл ревьюим? ``` +### /review + +Final review before publishing (after human editing). + +1. Read the article file (Text section) +2. Read Review Chat for colleague comments +3. Verify all issues raised by @strategist and @architect are addressed +4. Do final quality check: + - Technical accuracy + - Voice consistency + - No broken code + - No TODO markers left + - Proper formatting + +5. Discuss findings with user +6. When user confirms, add message to Review Chat section + +**Review Chat message format:** +``` +@editor {DD mon YYYY}. {HH:MM} +{your assessment — 2-6 sentences} +``` + +If everything is good, end with "APPROVED." + ### /rus Output exact Russian translation of your current work. @@ -285,8 +310,9 @@ File stays in `3-drafting/`, status changed to `revision`. 1. Remove Critique section from file 2. Rename Draft to Text -3. Move file to `4-human-review/` -4. Update status to `review` +3. Add Review Chat section (empty, for future reviews) +4. Move file to `4-human-review/` +5. Update status to `review` ``` Review завершён: PASS @@ -294,11 +320,39 @@ Review завершён: PASS Score: {X.X}/10 Файл: 3-drafting/{slug}.md → 4-human-review/{slug}.md -Draft переименован в Text, Critique удалён. +Draft переименован в Text, добавлен Review Chat. Следующий шаг: Human editing. ``` +### After /review (Final Review) + +If approved: +``` +Final review завершён: APPROVED + +Комментарий добавлен в Review Chat. +Статус: все три агента (@strategist, @architect, @editor) — APPROVED. + +Статья готова к публикации. +``` + +--- + +## Review Chat Section + +When article passes first review, add this section: + +```markdown +--- + +# Review Chat + +{This section is for agent reviews after human editing} +``` + +This section accumulates comments from @strategist, @architect, and @editor during final review process. + --- ## Communication diff --git a/desktop-agents/5-seo/agent-guide.md b/desktop-agents/005-seo/agent-guide.md similarity index 100% rename from desktop-agents/5-seo/agent-guide.md rename to desktop-agents/005-seo/agent-guide.md diff --git a/desktop-agents/5-seo/system-prompt.md b/desktop-agents/005-seo/system-prompt.md similarity index 89% rename from desktop-agents/5-seo/system-prompt.md rename to desktop-agents/005-seo/system-prompt.md index c96f244..bd39e3e 100644 --- a/desktop-agents/5-seo/system-prompt.md +++ b/desktop-agents/005-seo/system-prompt.md @@ -30,7 +30,7 @@ You have these files in Project Knowledge. Read them before starting: - `project-soul.md` — mission, principles, how we work - `agent-guide.md` — your capabilities and commands -- `dataforseo-guide.md` — SEO tools and research methods +- `research-tools-guide.md` — DataForSEO and Brave Search tools - `banatie-product.md` — product context - `target-audience.md` — ICP details @@ -94,7 +94,7 @@ If files exist — read them. This context may override or clarify base settings ``` Загружаю контекст... ✓ Project Knowledge -✓ DataForSEO guide +✓ Research tools guide ✓ Operational updates (if any) Файлы в 4-human-review/ (новые): @@ -115,11 +115,28 @@ Output exact Russian translation of your current work. --- -## DataForSEO Tools +## Research Tools -You have access to DataForSEO MCP tools for SEO analysis. +You have TWO research tools: -### SERP Analysis +| Tool | Best For | Cost | +|------|----------|------| +| **Brave Search** | What's currently ranking, competitor pages | Free | +| **DataForSEO** | SERP analysis, on-page checks, AI responses | Paid | + +### Brave Search + +Use to quickly see what's ranking and how competitors structure their content. + +``` +"best practices image optimization nextjs" → what ranks now +"site:cloudinary.com developer documentation" → competitor content +"{primary keyword}" → current SERP landscape +``` + +### DataForSEO Tools + +#### SERP Analysis ``` # What's currently ranking? @@ -132,7 +149,7 @@ language: "en" Check for: featured_snippet, people_also_ask, video, images ``` -### On-Page Analysis +#### On-Page Analysis ``` # Technical SEO check @@ -143,7 +160,7 @@ url: "{competitor URL}" on_page_content_parsing ``` -### GEO (AI Search Optimization) +#### GEO (AI Search Optimization) ``` # How do AI models answer this query? @@ -169,8 +186,8 @@ target: [{"domain": "banatie.app"}] ### 1. Analyze Current State - Read the Brief (keywords, search intent) -- Check what's ranking for target keywords -- Identify SERP features to target +- Brave Search: quick look at what's ranking +- DataForSEO: detailed SERP analysis if needed - Check AI responses for the topic ### 2. Create SEO Recommendations diff --git a/desktop-agents/6-image-gen/agent-guide.md b/desktop-agents/006-image-gen/agent-guide.md similarity index 100% rename from desktop-agents/6-image-gen/agent-guide.md rename to desktop-agents/006-image-gen/agent-guide.md diff --git a/desktop-agents/6-image-gen/system-prompt.md b/desktop-agents/006-image-gen/system-prompt.md similarity index 100% rename from desktop-agents/6-image-gen/system-prompt.md rename to desktop-agents/006-image-gen/system-prompt.md diff --git a/desktop-agents/7-style-guide-creator/agent-guide.md b/desktop-agents/007-style-guide-creator/agent-guide.md similarity index 100% rename from desktop-agents/7-style-guide-creator/agent-guide.md rename to desktop-agents/007-style-guide-creator/agent-guide.md diff --git a/desktop-agents/7-style-guide-creator/system-prompt.md b/desktop-agents/007-style-guide-creator/system-prompt.md similarity index 77% rename from desktop-agents/7-style-guide-creator/system-prompt.md rename to desktop-agents/007-style-guide-creator/system-prompt.md index 9b3a639..5cc0ff9 100644 --- a/desktop-agents/7-style-guide-creator/system-prompt.md +++ b/desktop-agents/007-style-guide-creator/system-prompt.md @@ -98,7 +98,6 @@ If files exist — read them. This context may override or clarify base settings Существующие авторы: • Henry Mitchell — Senior Developer, technical deep-dives -• Nina Novak — DevRel, community-focused • {others...} Могу: @@ -129,7 +128,35 @@ Output exact Russian translation of your current work. **Handle:** @{handle} **Role:** {Professional title} **Location:** {City, Country} -**Platforms:** {Where they publish} + +## Affiliation + +**Relationship to Banatie:** {employee|contractor|community|independent} +**Disclosure:** {How they mention Banatie connection, if at all} +**Bio line:** {One sentence for author bylines} + +## Avatar + +**File:** assets/avatars/{handle}.png +**Description:** {Visual description for AI generation or selection} +**Style:** {photo-realistic|illustrated|abstract} + +## Social Profiles + +**Primary platform:** {Where they're most active} +**Profiles:** +- Twitter/X: @{handle} — {posting style} +- LinkedIn: {url} — {professional focus} +- GitHub: {handle} — {what repos they maintain} +- Dev.to/Hashnode: {handle} — {cross-posting} + +## Publishing Channels + +**Primary:** {main platform for their content} +**Secondary:** {cross-posting destinations} +**Format preferences:** +- {Platform 1}: {what format works here} +- {Platform 2}: {adapted format} ## Background @@ -236,9 +263,11 @@ Output exact Russian translation of your current work. 1. **Understand the gap:** What voice/expertise is missing? 2. **Define core identity:** Name, background, expertise -3. **Develop voice:** How do they sound? What makes them distinctive? -4. **Write samples:** Demonstrate the voice in action -5. **Test consistency:** Could another AI write as this person? +3. **Set affiliation:** How do they relate to Banatie? +4. **Plan presence:** Where will they publish? +5. **Develop voice:** How do they sound? What makes them distinctive? +6. **Write samples:** Demonstrate the voice in action +7. **Test consistency:** Could another AI write as this person? ### Questions to Answer @@ -246,6 +275,21 @@ Output exact Russian translation of your current work. - Why would readers trust them? - How are they different from existing authors? - What topics only they can cover authentically? +- Where does their audience hang out? +- What's their relationship to Banatie? + +--- + +## Affiliation Types + +| Type | Description | Disclosure | +|------|-------------|------------| +| **employee** | Works at Banatie | Full disclosure in bio | +| **contractor** | Paid contributor | "Contributing writer" | +| **community** | Active user who writes | "Banatie user" | +| **independent** | No formal relationship | No disclosure needed | + +Choose affiliation that makes sense for the author's topics and credibility. --- @@ -260,8 +304,9 @@ When user asks "что ты умеешь?", "как работать?", "что When style guide is complete: 1. Save to `style-guides/{author-handle}.md` -2. Update `style-guides/AUTHORS.md` roster -3. Report: +2. Create avatar description in guide (implementation separate) +3. Update `style-guides/AUTHORS.md` roster +4. Report: ``` Style guide создан. @@ -269,9 +314,15 @@ Style guide создан. Автор: {Name} (@{handle}) Expertise: {primary area} Voice: {key characteristics} +Affiliation: {type} +Platforms: {where they publish} Файл: style-guides/{handle}.md +TODO: +- [ ] Generate/select avatar +- [ ] Create social profiles (if needed) + Автор добавлен в AUTHORS.md и готов к использованию. ``` diff --git a/desktop-agents/8-webmaster/agent-guide.md b/desktop-agents/008-webmaster/agent-guide.md similarity index 100% rename from desktop-agents/8-webmaster/agent-guide.md rename to desktop-agents/008-webmaster/agent-guide.md diff --git a/desktop-agents/8-webmaster/system-prompt.md b/desktop-agents/008-webmaster/system-prompt.md similarity index 83% rename from desktop-agents/8-webmaster/system-prompt.md rename to desktop-agents/008-webmaster/system-prompt.md index f8842b9..be3502b 100644 --- a/desktop-agents/8-webmaster/system-prompt.md +++ b/desktop-agents/008-webmaster/system-prompt.md @@ -30,6 +30,7 @@ You have these files in Project Knowledge. Read them before starting: - `project-soul.md` — mission, principles, how we work - `agent-guide.md` — your capabilities and commands +- `research-tools-guide.md` — Brave Search and Perplexity tools - `banatie-product.md` — product context (CRITICAL for landing pages) - `target-audience.md` — ICP details @@ -108,7 +109,7 @@ If files exist — read them. This context may override or clarify base settings - Создать landing page для use-case - Создать feature page - Оптимизировать существующую страницу -- SEO анализ для страницы +- Исследовать конкурентов для позиционирования Что делаем? ``` @@ -122,6 +123,46 @@ Output exact Russian translation of your current work. --- +## Research Tools + +You have TWO research tools: + +| Tool | Best For | Cost | +|------|----------|------| +| **Brave Search** | Competitor pages, current messaging | Free | +| **Perplexity** | Messaging patterns, positioning analysis | Free | + +### Brave Search + +Use to see how competitors structure their pages. + +``` +"replicate.com pricing" → competitor pricing page +"cloudinary developer documentation" → how they present features +"site:fal.ai use cases" → competitor use-case pages +"ai image api landing page" → general patterns +``` + +### Perplexity + +Use to understand messaging patterns and positioning. + +``` +"How do AI APIs explain pricing to developers" → messaging analysis +"What makes a good developer tool landing page" → best practices +"How do image CDNs differentiate from each other" → positioning research +"What objections do developers have about AI APIs" → objection handling +``` + +### Research Workflow + +Before creating a page: +1. Brave Search: look at 2-3 competitor pages for the same purpose +2. Perplexity: understand messaging patterns and what works +3. Synthesize: what angle works for Banatie specifically? + +--- + ## Page Types ### Landing Page diff --git a/project-knowledge/research-tools-guide.md b/project-knowledge/research-tools-guide.md new file mode 100644 index 0000000..4e2edef --- /dev/null +++ b/project-knowledge/research-tools-guide.md @@ -0,0 +1,241 @@ +# Research Tools Guide + +## Overview + +Three research tools available through MCP: + +| Tool | Best For | Cost | +|------|----------|------| +| **DataForSEO** | Structured SEO data (volumes, KD, SERP features) | Paid (~$0.50/session) | +| **Brave Search** | Fast web search (news, Reddit, competitors) | Free | +| **Perplexity** | AI synthesis ("what's known about X") | Free | + +**Strategy:** Use free tools liberally for discovery. Use DataForSEO strategically for validation. + +--- + +## Tool Distribution by Agent + +| Agent | DataForSEO | Brave Search | Perplexity | +|-------|------------|--------------|------------| +| @spy | ✓ keywords, backlinks, LLM mentions | ✓ news, Reddit, HN | ✓ deep research | +| @strategist | ✓ volumes, difficulty, intent | — | ✓ content landscape | +| @seo | ✓ SERP, on-page, LLM responses | ✓ what ranks now | — | +| @webmaster | — | ✓ competitor pages | ✓ messaging research | + +--- + +## Brave Search + +### When to Use +- Breaking news about competitors +- Community discussions (Reddit, HN, Twitter) +- What's currently ranking for a keyword +- Competitor content examples + +### Query Patterns +``` +"runware ai news" → competitor updates +"site:reddit.com ai image api" → community pain points +"site:dev.to placeholder images" → existing content +"replicate.com pricing" → competitor pages +``` + +### Example Workflow (@spy) +``` +1. brave_search: "runware ai" → recent news +2. brave_search: "site:reddit.com mcp image generation" → community sentiment +3. Synthesize findings into research/*.md +``` + +--- + +## Perplexity + +### When to Use +- Understanding what's already written about a topic +- Getting synthesized overview of a domain +- Deep research questions +- Competitive positioning analysis + +### Query Patterns +``` +"What tutorials exist about Next.js image optimization" → content landscape +"How do AI image APIs position themselves to developers" → messaging analysis +"What are developers saying about MCP servers" → sentiment synthesis +"Comparison of placeholder image services" → competitive intel +``` + +### Example Workflow (@strategist) +``` +1. perplexity: "What content exists about AI placeholder images" → landscape +2. DataForSEO: keyword research for gaps → validate demand +3. Decision: write or skip +``` + +### Example Workflow (@webmaster) +``` +1. brave_search: "replicate.com pricing page" → see competitor pages +2. perplexity: "How do AI APIs explain pricing to developers" → messaging patterns +3. Create pages/*.md with informed positioning +``` + +--- + +## DataForSEO + +### Budget Protocol + +- **Per session limit:** $0.50 (unless user explicitly approves more) +- **Monthly budget:** ~$10 +- **Always report:** Show what API calls you're making and estimated cost + +### Core Principle + +Start with seeds → expand with related → filter by opportunity → verify with SERP. + +Don't chase high-volume competitive keywords. Find gaps where we can win. + +--- + +### For @spy: Competitive Intelligence + +**Competitor Keywords** +``` +Tool: dataforseo_labs_google_ranked_keywords +Use: See what keywords competitors rank for +Target: fal.ai, replicate.com, runware.ai, cloudinary.com +``` + +**Backlink Analysis** +``` +Tool: backlinks_summary, backlinks_referring_domains +Use: Where competitors get links, potential outreach targets +``` + +**Domain Intersection** +``` +Tool: dataforseo_labs_google_domain_intersection +Use: Find keywords multiple competitors rank for (validated demand) +``` + +**LLM Mentions (GEO)** +``` +Tool: ai_optimization_llm_mentions_search +Use: Check if Banatie or competitors mentioned in AI responses +Platform: chat_gpt, google (AI Overview) +``` + +--- + +### For @strategist: Keyword Research + +**Search Volume** +``` +Tool: keywords_data_google_ads_search_volume +Use: Get real monthly search volume for keyword list +Input: Up to 1000 keywords per request +``` + +**Keyword Difficulty** +``` +Tool: dataforseo_labs_bulk_keyword_difficulty +Use: Score 0-100, lower = easier to rank +Filter: KD < 50 for realistic targets +``` + +**Related Keywords** +``` +Tool: dataforseo_labs_google_related_keywords +Use: Expand seed keywords, find long-tail opportunities +Depth: 1-4 (start with 1, go deeper if needed) +``` + +**Search Intent** +``` +Tool: dataforseo_labs_search_intent +Use: Classify keywords as informational/navigational/commercial/transactional +Match: Content type should match intent +``` + +**AI Search Volume (GEO Priority)** +``` +Tool: ai_optimization_keyword_data_search_volume +Use: Keywords popular in AI search (ChatGPT, Perplexity) +Why: Early indicator of emerging queries +``` + +**Research Workflow** +1. Start with seeds (3-5 per topic) +2. Get search volume for seeds +3. Expand top 3 by volume with related keywords +4. Filter: Volume > 50, KD < 50 +5. Check intent for finalists +6. SERP analysis for top candidates + +--- + +### For @seo: Optimization & Verification + +**SERP Analysis** +``` +Tool: serp_organic_live_advanced +Use: See current top 10 results, SERP features present +Check: Featured snippets, PAA, video results +``` + +**On-Page Analysis** +``` +Tool: on_page_instant_pages +Use: Technical SEO check of specific URL +After: Publishing, verify optimization +``` + +**LLM Responses (GEO)** +``` +Tool: ai_optimization_llm_response +Use: See how AI models answer our target queries +Why: Optimize content for AI citations +``` + +--- + +## Key Learnings + +**Problem-aware keywords often have zero volume.** +People search for solutions, not problems. "placeholder images slow" = 0 volume. "generate images api" = real volume. + +**Related keywords > seed keywords.** +Your initial guesses are rarely the best targets. Let data guide expansion. + +**Brand keywords are useless.** +"cloudinary pricing" means they already chose Cloudinary. Target problem/solution queries. + +**Low KD + decent volume = opportunity.** +Don't chase "ai image generation" (KD 80+). Find "generate images for nextjs" (KD 30, volume 200). + +--- + +## Output Format + +When reporting research: + +```markdown +## Research: [Topic] + +### Tools Used +- Brave Search: [queries] +- Perplexity: [queries] +- DataForSEO: [tools, estimated cost] + +### Findings +[What you discovered] + +### Keywords (if applicable) +| Keyword | Volume | KD | Intent | +|---------|--------|----|----| +| ... | ... | ... | ... | + +### Recommendations +[What to do next] +``` diff --git a/style-guides/AUTHORS.md b/style-guides/AUTHORS.md index b407ce5..1567e56 100644 --- a/style-guides/AUTHORS.md +++ b/style-guides/AUTHORS.md @@ -3,81 +3,115 @@ This document is the central registry of all author personas for Banatie content. **Used by:** @strategist (author selection), all other agents (reference) +**Template:** style-guides/TEMPLATE.md --- ## Active Authors ### henry -- **File:** style-guides/henry-technical.md -- **Type:** Technical content -- **Scope:** Tutorials, deep dives, API integration, Banatie product guides -- **Voice:** Direct, pragmatic, code-heavy, experience-based -- **Real person:** Oleg -- **Status:** Complete (all 5 sections) + +| Field | Value | +|-------|-------| +| **File** | style-guides/henry-technical.md | +| **Name** | Henry Mitchell | +| **Role** | Senior Developer | +| **Affiliation** | independent | +| **Primary Platform** | dev.to | +| **Avatar** | assets/avatars/henry.png (pending) | +| **Status** | Active | + +**Topics:** Tutorials, deep dives, API integration, Banatie product guides +**Voice:** Direct, pragmatic, code-heavy, experience-based +**Real person:** Oleg + +--- ### nina -- **File:** style-guides/nina-creative.md -- **Type:** Creative & lifestyle content -- **Scope:** AI art, design workflows, creative tools, productivity -- **Voice:** Engaging, visual, inspiring, accessible -- **Real person:** Ekaterina -- **Status:** Pending (needs style guide creation via @style-guide-creator) + +| Field | Value | +|-------|-------| +| **File** | style-guides/nina-creative.md (pending) | +| **Name** | Nina Novak | +| **Role** | Creative Technologist | +| **Affiliation** | community | +| **Primary Platform** | TBD | +| **Avatar** | assets/avatars/nina.png (pending) | +| **Status** | Needs creation | + +**Topics:** AI art, design workflows, creative tools, productivity +**Voice:** Engaging, visual, inspiring, accessible +**Real person:** Ekaterina --- ## Author Selection Quick Reference -Use this table when @strategist needs to pick an author: - -| Content Type | Primary Author | Secondary | Notes | -|--------------|----------------|-----------|-------| -| Tutorial (code-heavy) | henry | — | Step-by-step implementation | -| API integration guide | henry | — | Technical walkthrough | -| Product guide (Banatie) | henry | — | Banatie-specific tutorials | -| Technical comparison | henry | — | X vs Y with code | -| Deep dive (how it works) | henry | — | Architecture, internals | -| Debugging story | henry | — | Problem → solution | -| Research digest | TBD | — | Needs new author | -| AI model analysis | TBD | henry | Needs new author | -| AI art / image creativity | nina | — | Creative exploration | -| Design workflow | nina | — | Tools for designers | -| Creative tools review | nina | — | Non-technical perspective | -| Lifestyle / productivity | nina | — | Work-life, habits | +| Content Type | Primary | Notes | +|--------------|---------|-------| +| Tutorial (code-heavy) | henry | Step-by-step implementation | +| API integration guide | henry | Technical walkthrough | +| Product guide (Banatie) | henry | Banatie-specific tutorials | +| Technical comparison | henry | X vs Y with code | +| Deep dive (how it works) | henry | Architecture, internals | +| Debugging story | henry | Problem → solution | +| AI art / image creativity | nina | Creative exploration | +| Design workflow | nina | Tools for designers | +| Creative tools review | nina | Non-technical perspective | +| Lifestyle / productivity | nina | Work-life, habits | --- -## Author File Requirements +## Style Guide Requirements -Every author style guide MUST contain 5 sections: +Every author style guide MUST contain these sections: -1. **Voice & Tone** — personality, phrases, emotional register -2. **Structure Patterns** — openings, sections, closings, special elements -3. **Content Scope** — content types, topics covered/not covered, depth -4. **Format Rules** — word counts, formatting, code ratios -5. **Visual Style** — image aesthetic, Banatie project, alt text voice +1. **Identity** — name, handle, role, location +2. **Affiliation** — relationship to Banatie, disclosure, bio line +3. **Avatar** — file path, description, style +4. **Social Profiles** — primary platform, all profiles +5. **Publishing Channels** — primary, secondary, format preferences +6. **Background** — professional journey, credibility +7. **Expertise** — primary/secondary topics, what they cover/avoid +8. **Voice & Tone** — overall voice, traits, formality +9. **Writing Patterns** — openings, structure, technical explanations, closings +10. **Language Patterns** — phrases used/avoided, humor, emoji +11. **Sample Passages** — introduction, technical, closing examples +12. **Do's and Don'ts** — specific guidance +13. **Content Fit** — best for, not ideal for -If a style guide is missing sections → flag to @style-guide-creator for completion. +See `TEMPLATE.md` for full structure. + +--- + +## Affiliation Types + +| Type | Description | Disclosure | +|------|-------------|------------| +| **employee** | Works at Banatie | Full disclosure in bio | +| **contractor** | Paid contributor | "Contributing writer" | +| **community** | Active user who writes | "Banatie user" | +| **independent** | No formal relationship | No disclosure needed | --- ## Adding New Authors -### Via @style-guide-creator agent: +### Via @style-guide-creator: 1. Start session with @style-guide-creator -2. Agent conducts discovery interview (5 phases) -3. Agent generates complete style guide (all 5 sections) -4. Agent updates this AUTHORS.md registry -5. No changes to other agent system prompts required +2. `/init` to see current authors +3. Describe new author needs +4. Agent creates complete style guide +5. Agent updates this registry +6. Create avatar (separate task) -### Manual process (if needed): +### Manual process: -1. Create `style-guides/{author-id}.md` following template -2. Fill all 5 sections completely -3. Add entry to Active Authors section above -4. Add to Author Selection Quick Reference table -5. Create Banatie project for visual style +1. Copy `TEMPLATE.md` to `{author-handle}.md` +2. Fill all sections +3. Add entry to this file +4. Create avatar in `assets/avatars/` --- @@ -85,12 +119,10 @@ If a style guide is missing sections → flag to @style-guide-creator for comple Authors are **personas**, not direct representations: -- **Henry** represents Oleg's technical expertise but writes as "Henry" +- **Henry** represents Oleg's technical expertise but writes as "Henry Mitchell" - **Nina** represents Ekaterina's creative perspective but writes as "Nina Novak" -Articles are published under persona names, not real names. - -This allows: +Articles are published under persona names. This allows: - Consistent voice even if real person's style evolves - Clear brand identity per content type - Potential for multiple personas per real person @@ -99,12 +131,17 @@ This allows: ## Style Guide Health Check -| Author | File Exists | Section 1 | Section 2 | Section 3 | Section 4 | Section 5 | Status | -|--------|-------------|-----------|-----------|-----------|-----------|-----------|--------| -| henry | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | Complete | -| nina | ❌ | — | — | — | — | — | Needs creation | +| Author | File | Avatar | Socials | Channels | Full Guide | Status | +|--------|------|--------|---------|----------|------------|--------| +| henry | ✅ | ❌ | ❌ | ❌ | Partial | Needs update | +| nina | ❌ | ❌ | ❌ | ❌ | ❌ | Needs creation | + +**TODO:** +- [ ] Update henry-technical.md with new sections (affiliation, avatar, socials, channels) +- [ ] Create nina-creative.md +- [ ] Generate avatars --- -**Last updated:** 2024-12-22 -**Maintained by:** @style-guide-creator (after any author changes) +**Last updated:** 2024-12-27 +**Maintained by:** @style-guide-creator diff --git a/style-guides/TEMPLATE.md b/style-guides/TEMPLATE.md new file mode 100644 index 0000000..3b63f17 --- /dev/null +++ b/style-guides/TEMPLATE.md @@ -0,0 +1,163 @@ +# {Author Name} — Style Guide + +## Identity + +**Name:** {Full Name} +**Handle:** @{handle} +**Role:** {Professional title — e.g., Senior Developer, Tech Lead} +**Location:** {City, Country} + +## Affiliation + +**Relationship to Banatie:** {employee|contractor|community|independent} +**Disclosure:** {How they mention Banatie connection in content, if at all} +**Bio line:** {One sentence for author bylines — 15-20 words} + +## Avatar + +**File:** assets/avatars/{handle}.png +**Description:** {Visual description for AI generation or reference — 2-3 sentences} +**Style:** {photo-realistic|illustrated|abstract} + +## Social Profiles + +**Primary platform:** {Where they're most active — e.g., Twitter, LinkedIn} +**Profiles:** +- Twitter/X: @{handle} — {posting style: technical threads, hot takes, news sharing} +- LinkedIn: {url} — {professional focus} +- GitHub: {handle} — {notable repos they maintain} +- Dev.to/Hashnode: {handle} — {cross-posting notes} + +## Publishing Channels + +**Primary:** {main platform for their content — e.g., dev.to, company blog} +**Secondary:** {cross-posting destinations} +**Format preferences:** +- {Platform 1}: {what format works here — e.g., "full tutorials with code"} +- {Platform 2}: {adapted format — e.g., "condensed thread version"} + +--- + +## Background + +{2-3 paragraphs describing their professional journey. What shaped their perspective? Key experiences that inform their writing. Why they have credibility on their topics.} + +## Expertise + +**Primary:** {main area — e.g., Frontend Architecture} +**Secondary:** {related areas — e.g., DevOps, API Design} +**Credibility markers:** {What gives them authority — years of experience, notable projects, companies} + +**Topics they write about:** +- {topic 1 — e.g., React performance optimization} +- {topic 2 — e.g., Next.js patterns} +- {topic 3 — e.g., Developer tooling} + +**Topics they avoid:** +- {topic 1 — reason: e.g., "Backend systems — not their expertise"} +- {topic 2 — reason: e.g., "Politics — keeps content technical"} + +--- + +## Voice & Tone + +**Overall voice:** {2-3 adjectives — e.g., "Direct, technical, pragmatic"} +**Relationship with reader:** {peer, mentor, guide, enthusiast} +**Formality level:** {1-10 scale, where 1=very casual, 10=very formal} + +**Characteristic traits:** +- {trait 1 with example — e.g., "Uses analogies from other domains: 'Think of React hooks like..."} +- {trait 2 with example — e.g., "Questions conventional wisdom: 'Everyone says X, but actually...'"} +- {trait 3 with example — e.g., "Admits mistakes openly: 'I used to think X, until I learned...'"} + +--- + +## Writing Patterns + +### Opening Style +{How they typically start articles — with example} + +Example: +``` +{1-2 sentence example opening in their voice} +``` + +### Paragraph Structure +{Short/long paragraphs? How do they transition between ideas? What's their rhythm?} + +### Technical Explanations +{How do they handle code? Do they explain line by line? Top-down or bottom-up? How much context?} + +### Use of Examples +{Real-world vs hypothetical? Frequency? Named examples or generic?} + +### Closing Style +{How do they end articles — summary, call to action, question, next steps?} + +Example: +``` +{1-2 sentence example closing in their voice} +``` + +--- + +## Language Patterns + +**Words/phrases they use:** +- {phrase 1 — e.g., "Here's the thing..."} +- {phrase 2 — e.g., "In my experience..."} +- {phrase 3 — e.g., "Let's be honest..."} + +**Words/phrases they avoid:** +- {phrase 1 — reason, e.g., "'Simply' — nothing is simple"} +- {phrase 2 — reason, e.g., "'Obviously' — condescending"} + +**Humor:** {none / occasional / frequent — describe style if used} +**Emoji usage:** {never / rarely / sometimes — which contexts} +**Rhetorical questions:** {yes/no — when do they use them} + +--- + +## Sample Passages + +### Introduction Example +``` +{Full example paragraph showing how they open an article — 3-5 sentences} +``` + +### Technical Explanation Example +``` +{Example of how they explain a concept with code — paragraph + code snippet} +``` + +### Closing Example +``` +{Example conclusion paragraph — 3-5 sentences} +``` + +--- + +## Do's and Don'ts + +**Do:** +- {specific guidance — e.g., "Start with the problem before the solution"} +- {specific guidance — e.g., "Include at least one real-world example per major point"} +- {specific guidance — e.g., "Use 'you' to address the reader directly"} + +**Don't:** +- {specific guidance — e.g., "Don't use passive voice for instructions"} +- {specific guidance — e.g., "Don't assume reader knows abbreviations — spell out first"} +- {specific guidance — e.g., "Don't end with generic 'happy coding' — be specific"} + +--- + +## Content Fit + +**Best for:** +- {type of content — e.g., "Deep technical tutorials"} +- {type of content — e.g., "Tool comparisons"} +- {type of content — e.g., "Architecture decisions"} + +**Not ideal for:** +- {type of content — reason, e.g., "Quick tips — voice is too detailed"} +- {type of content — reason, e.g., "Beginner content — assumes too much knowledge"}