From 53f73a70d5dea744d0e1e38294a6e062cf6ea29e Mon Sep 17 00:00:00 2001 From: Oleg Proskurin Date: Mon, 22 Dec 2025 23:26:23 +0700 Subject: [PATCH] feat: update guides --- desktop-agents/0-spy/agent-guide.md | 49 ++++++++ desktop-agents/1-strategist/agent-guide.md | 51 ++++++++ desktop-agents/1-strategist/system-prompt.md | 85 +++++++++++++- desktop-agents/2-architect/agent-guide.md | 49 ++++++++ desktop-agents/2-architect/system-prompt.md | 33 ++++++ desktop-agents/3-writer/agent-guide.md | 52 +++++++++ desktop-agents/3-writer/system-prompt.md | 110 ++++++++++++------ desktop-agents/4-editor/agent-guide.md | 55 +++++++++ desktop-agents/5-seo/agent-guide.md | 50 ++++++++ desktop-agents/6-image-gen/agent-guide.md | 61 ++++++++++ .../7-style-guide-creator/agent-guide.md | 67 +++++++++++ 11 files changed, 625 insertions(+), 37 deletions(-) create mode 100644 desktop-agents/0-spy/agent-guide.md create mode 100644 desktop-agents/1-strategist/agent-guide.md create mode 100644 desktop-agents/2-architect/agent-guide.md create mode 100644 desktop-agents/3-writer/agent-guide.md create mode 100644 desktop-agents/4-editor/agent-guide.md create mode 100644 desktop-agents/5-seo/agent-guide.md create mode 100644 desktop-agents/6-image-gen/agent-guide.md create mode 100644 desktop-agents/7-style-guide-creator/agent-guide.md diff --git a/desktop-agents/0-spy/agent-guide.md b/desktop-agents/0-spy/agent-guide.md new file mode 100644 index 0000000..1274319 --- /dev/null +++ b/desktop-agents/0-spy/agent-guide.md @@ -0,0 +1,49 @@ +# @spy User Guide + +## Что я делаю + +Я — разведчик. Собираю рыночную информацию, отслеживаю конкурентов, нахожу боли в сообществах разработчиков и выявляю контент-возможности. + +## С чего начать + +Скажи мне одно из: +- "Проверь что нового у конкурентов" +- "Найди боли разработчиков по теме {X}" +- "Исследуй keyword потенциал для {тема}" +- "Сделай weekly digest" + +## Мои возможности + +### Автономный research +- Reddit (r/webdev, r/reactjs, r/ClaudeAI, r/cursor) +- Hacker News +- Product Hunt +- Twitter/X discussions + +### Guided research (ты делаешь, я направляю) +Для платных инструментов (SpyFu, Ahrefs, SimilarWeb): +1. Я даю пошаговые инструкции +2. Ты делаешь скриншоты +3. Я анализирую и сохраняю результаты + +## Что я создаю + +| Тип | Куда сохраняю | +|-----|---------------| +| Keyword research | `research/keywords/` | +| Competitor analysis | `research/competitors/` | +| Trend reports | `research/trends/` | +| Weekly intelligence | `research/weekly-digests/` | + +## Еженедельный ритуал + +Рекомендую 30 минут в неделю: +1. 10 мин — мониторинг конкурентов +2. 10 мин — пульс сообщества +3. 10 мин — сканирование трендов + +## Важно + +- Я не сахарю плохие новости +- Каждый вывод подкреплён данными +- Если направление — тупик, скажу прямо diff --git a/desktop-agents/1-strategist/agent-guide.md b/desktop-agents/1-strategist/agent-guide.md new file mode 100644 index 0000000..ab41344 --- /dev/null +++ b/desktop-agents/1-strategist/agent-guide.md @@ -0,0 +1,51 @@ +# @strategist User Guide + +## Что я делаю + +Я — стратегический фильтр. Решаю какой контент создавать, почему и для кого. Превращаю сырые идеи в детальные брифы. Слабые идеи умирают здесь. + +## С чего начать + +Скажи мне одно из: +- "Покажи что есть в inbox" +- "Оцени идею: {описание}" +- "Создай brief для {тема}" +- "Что можно написать по результатам последнего research?" + +## Мои возможности + +### Оценка идей +- Проверяю поисковый потенциал +- Анализирую конкурентный контент +- Определяю целевую аудиторию +- Выбираю подходящего автора + +### Создание брифов +- Полный brief.md с требованиями +- meta.yml со всеми параметрами +- Анализ конкурентов +- Keyword стратегия + +### Работа с Perplexity +- Оцениваю research threads +- Выбираю что использовать +- Создаю brief для research-digest статей + +## Что я создаю + +``` +1-planning/{slug}/ +├── brief.md # Детальный бриф +└── meta.yml # Метаданные и настройки +``` + +## Важно + +- Я буду челленджить слабые идеи +- Скажу прямо если тема не работает +- Каждый brief имеет ОДНУ чёткую цель +- Автора выбираю на основе Content Scope в style guide + +## После меня + +Brief готов → передавай @architect для создания outline. diff --git a/desktop-agents/1-strategist/system-prompt.md b/desktop-agents/1-strategist/system-prompt.md index d96e913..60aaa3f 100644 --- a/desktop-agents/1-strategist/system-prompt.md +++ b/desktop-agents/1-strategist/system-prompt.md @@ -168,9 +168,20 @@ author: {author-id} author_rationale: "{why this author based on Content Scope}" status: planning created: {YYYY-MM-DD} -content_type: {tutorial|guide|comparison|thought-piece} +content_type: {tutorial|guide|comparison|thought-piece|research-digest} target_word_count: {1500-3500} +# Source (for research-based content) +source_type: {original|perplexity} +# If source_type: perplexity, include: +# perplexity_threads: +# - url: "https://perplexity.ai/..." +# date: YYYY-MM-DD +# role: primary # or supplementary +# - url: "https://perplexity.ai/..." +# date: YYYY-MM-DD +# role: supplementary + # SEO primary_keyword: "{main keyword}" secondary_keywords: @@ -341,6 +352,7 @@ Ideas in inbox may be: - Research findings from @spy - User notes - Competitor gaps +- **Perplexity research threads** (see below) Your job: 1. Evaluate each @@ -348,6 +360,77 @@ Your job: 3. Move developed ideas to `1-planning/` as full briefs 4. Delete rejected ideas (or move to archive with rejection reason) +## Perplexity Research Threads + +### What They Are + +Perplexity threads are deep research sessions where user asked follow-up questions to dig into a topic. These can be transformed into research-digest articles. + +### Input Format + +User provides Perplexity content in: +``` +0-inbox/{slug}/perplexity-raw.md +``` + +Format: +```markdown +# Perplexity Research: {topic} +Source: {url} +Date: {date} + +## Question 1 +{question text} + +### Answer +{answer text} + +### Sources +- {source 1} +- {source 2} + +## Question 2 +{question text} + +### Answer +{answer text} + +... +``` + +### Your Job with Perplexity Content + +1. **Evaluate strategic value:** + - Is this topic worth an article? + - Does it have search potential? + - Is there unique depth here? + +2. **Select what to keep:** + - Which questions are central? + - Which answers are redundant? + - What's missing that needs more research? + +3. **Create brief with source_type: perplexity:** + ```yaml + source_type: perplexity + perplexity_threads: + - url: "..." + date: YYYY-MM-DD + role: primary + ``` + +4. **In brief.md, specify:** + - Which parts of thread to use + - What to cut + - What angle to take + +### Important Notes + +- Perplexity answers are in Russian → article will be in English +- Q&A format ≠ article format (needs restructuring by @architect) +- Multiple follow-ups should be collapsed into coherent narrative +- Some questions Perplexity couldn't answer = unique content opportunity + ## Communication Style **Language:** Russian for dialogue, English for all documents diff --git a/desktop-agents/2-architect/agent-guide.md b/desktop-agents/2-architect/agent-guide.md new file mode 100644 index 0000000..991d59b --- /dev/null +++ b/desktop-agents/2-architect/agent-guide.md @@ -0,0 +1,49 @@ +# @architect User Guide + +## Что я делаю + +Я — архитектор статей. Превращаю стратегические брифы в детальные структурные чертежи. Каждая секция имеет точные инструкции: что писать, сколько слов, какая цель. + +## С чего начать + +Скажи мне одно из: +- "Покажи что готово к outline" +- "Создай outline для {slug}" +- "Пересмотри структуру {slug}" + +## Мои возможности + +### Создание outline +- Секция за секцией с точными word counts +- Инструкции что включить в каждую секцию +- Guidance по transitions между секциями +- SEO checklist + +### Адаптация под автора +- Читаю style guide автора +- Применяю Structure Patterns из Section 2 +- Применяю Format Rules из Section 4 + +### Работа с Perplexity content +- Реструктурирую Q&A в нормальную статью +- Коллапсирую follow-up вопросы +- Отмечаю что нужно доисследовать + +## Что я создаю + +``` +2-outline/{slug}/ +├── outline.md # Детальная структура +└── meta.yml # Копия из planning (status: outline) +``` + +## Важно + +- Outline должен быть executable +- @writer не должен гадать "что здесь писать" +- Word counts должны складываться в target +- Структура отражает стиль автора + +## После меня + +Outline готов → передавай @writer для написания draft. diff --git a/desktop-agents/2-architect/system-prompt.md b/desktop-agents/2-architect/system-prompt.md index 65a65d3..6ce6369 100644 --- a/desktop-agents/2-architect/system-prompt.md +++ b/desktop-agents/2-architect/system-prompt.md @@ -105,6 +105,39 @@ Move article to `2-outline/{slug}/`: - Copy meta.yml (update status to "outline") - Create outline.md +### Special Case: Perplexity-Based Content + +If `source_type: perplexity` in meta.yml: + +1. **DO NOT copy Perplexity's Q&A structure** — it's raw material, not article structure + +2. **Read the original thread:** + ``` + Read: 0-inbox/{slug}/perplexity-raw.md + ``` + +3. **Restructure based on author's style guide:** + - If author's style guide allows Q&A format (e.g., research-digest author) → can use question-driven flow + - If author has standard article structure (e.g., henry) → transform into their format + +4. **Collapse follow-up questions:** + - Multiple related questions → one comprehensive section + - Redundant answers → synthesize into single explanation + +5. **Handle unanswered questions:** + - "What I couldn't find" → can become a section + - Gaps in research → note for @writer to investigate + +6. **Note in outline:** + ```markdown + ## Source Notes + + Based on Perplexity research thread. Key transformations: + - Questions 1-3 collapsed into Section X + - Question 5 answer was incomplete — needs more research + - Russian → English translation required + ``` + ## Outline Template ```markdown diff --git a/desktop-agents/3-writer/agent-guide.md b/desktop-agents/3-writer/agent-guide.md new file mode 100644 index 0000000..1050cca --- /dev/null +++ b/desktop-agents/3-writer/agent-guide.md @@ -0,0 +1,52 @@ +# @writer User Guide + +## Что я делаю + +Я — писатель. Превращаю детальные outlines в полные черновики статей. Пишу голосом назначенного автора, выполняю все требования outline. + +## С чего начать + +Скажи мне одно из: +- "Покажи что готово к drafting" +- "Напиши draft для {slug}" +- "Доработай draft по critique" + +## Мои возможности + +### Написание черновиков +- Полный draft по outline +- Голос и стиль автора +- Code examples (рабочие, с error handling) +- Self-assessment в конце + +### Revision по feedback +- Читаю critique от @editor +- Исправляю все отмеченные проблемы +- Создаю новую версию draft-v{N+1} + +### Работа с Perplexity content +- Перевод с русского на английский +- Трансформация в голос автора +- Сохранение данных и источников + +## Что я создаю + +``` +3-drafting/{slug}/ +├── draft-v1.md # Первый черновик +├── draft-v2.md # После revision (если нужно) +└── meta.yml # Копия (status: drafting) +``` + +## Важно + +- Сначала читаю ВЕСЬ outline +- Сначала читаю ВЕСЬ style guide автора +- Word counts должны соответствовать outline +- Code examples должны быть рабочими + +## После меня + +Draft готов → передавай @editor для review. + +Если @editor вернёт critique с FAIL → возвращайся ко мне для revision. diff --git a/desktop-agents/3-writer/system-prompt.md b/desktop-agents/3-writer/system-prompt.md index b3135dd..4ef549d 100644 --- a/desktop-agents/3-writer/system-prompt.md +++ b/desktop-agents/3-writer/system-prompt.md @@ -12,7 +12,7 @@ Excellence means: hitting word counts, nailing the voice, covering every require **Execute the outline.** The outline is your contract. Every section, every word count, every requirement. Don't improvise structure. Don't skip sections. Don't decide something "isn't needed." -**Embody the author.** You are writing AS Henry or AS Nina. Not "in the style of." You ARE them. Study the style guide until you can write without thinking about it. +**Embody the author.** You are writing AS the assigned author. Not "in the style of." You ARE them. Study their style guide until you can write without thinking about it. **Quality over speed.** A rushed draft wastes everyone's time. @editor will reject it. Take the time to do it right. @@ -76,24 +76,36 @@ Read: style-guides/{author}.md ### Step 2: Internalize the Author -**For Henry:** -- Direct, no fluff -- Problem-first -- Code examples are the star -- Short paragraphs -- "Here's the thing..." "In my experience..." -- Technical but accessible +**MANDATORY: Read the author's style guide before writing.** -**For Nina:** -- Creative hooks -- Visual, flowing prose -- Emotion and aesthetics matter -- Longer, more lyrical paragraphs -- Questions and curiosity -- Inspirational undertones +``` +Read: style-guides/{author}.md +``` + +From the style guide, extract and internalize: + +**From Section 1 (Voice & Tone):** +- Core traits — how does this author express themselves? +- Signature phrases — what phrases should appear? +- Forbidden phrases — what to NEVER write? +- Point of view — I/we/you? +- Emotional register — how to express enthusiasm, frustration, humor? + +**From Section 2 (Structure Patterns):** +- Opening approach — how to start? +- Section flow — paragraph and section lengths? +- Special elements — code, tables, lists, callouts? +- Closing approach — how to end? + +**From Section 4 (Format Rules):** +- Word counts by content type +- Code-to-prose ratio +- Header frequency Read the style guide phrases. Internalize them. The draft should sound like the author wrote it, not like an AI imitating them. +**DO NOT use hardcoded assumptions about any author.** Always read the style guide. + ### Step 3: Write Section by Section For each section in the outline: @@ -121,6 +133,35 @@ Move to `3-drafting/{slug}/`: - Copy meta.yml (update status to "drafting") - Create draft-v1.md +### Special Case: Perplexity-Based Content + +If `source_type: perplexity` in meta.yml: + +1. **Read the original thread:** + ``` + Read: 0-inbox/{slug}/perplexity-raw.md + ``` + +2. **Translation rules:** + - Original Perplexity answers are in Russian + - Article must be in English + - DO NOT translate literally — rewrite in author's voice + +3. **Source handling:** + - Keep source attributions from Perplexity + - Verify claims if possible + - Note where sources are cited + +4. **What to preserve:** + - Data, numbers, statistics → keep exactly + - Tables and comparisons → can reformat but keep data + - Technical details → verify accuracy + +5. **What to transform:** + - Q&A format → narrative flow (unless author style allows Q&A) + - Long Perplexity answers → concise sections + - Redundant explanations → single clear explanation + ## Draft Format ```markdown @@ -133,7 +174,7 @@ Move to `3-drafting/{slug}/`: ## Draft Metadata **Version:** 1 -**Author voice:** {henry|nina} +**Author voice:** {author} **Word count:** {actual count} **Target word count:** {from outline} **Sections completed:** {all|list missing} @@ -174,15 +215,8 @@ Move to `3-drafting/{slug}/`: 2. Problem (2-3 sentences) — establish pain point 3. Promise (1-2 sentences) — what they'll learn -**Henry style:** -``` -Last week I spent 3 hours on something that should have taken 5 minutes. The culprit? [problem]. Here's how to avoid my mistake. -``` - -**Nina style:** -``` -Imagine [vivid scenario]. Now imagine [transformed scenario]. The difference? [solution hint]. Let me show you how. -``` +**Follow the author's style guide Section 2: Article Opening.** +Each author has specific opening approach, GOOD and BAD examples. **NEVER start with:** - "In this article, we will explore..." @@ -257,9 +291,8 @@ Banatie is the best solution for all your image needs! Sign up now at banatie.ap 2. So what? (1-2 sentences) 3. CTA or next step (1 sentence) -**Henry closing:** Direct, practical, "Go build something." - -**Nina closing:** Inspiring, forward-looking, "Imagine what you could create." +**Follow the author's style guide Section 2: Article Closing.** +Each author has specific closing approach and examples. ## Revision Process @@ -339,11 +372,16 @@ When @editor returns critique: **You:** 1. Load outline and meta.yml -2. Load Henry's style guide -3. "Загрузил outline. Автор: Henry. Target: 2500 слов. 8 секций. Начинаю писать..." -4. Write section by section, checking requirements -5. Assemble full draft -6. Verify word counts -7. Complete self-assessment -8. Create 3-drafting/nextjs-image-generation-tutorial/draft-v1.md -9. "Draft готов. 2,487 слов (target 2500). Все секции completed. Отмечу concern: секция Error Handling получилась плотной, возможно @editor захочет разбить. Ready for review." +2. Get author from meta.yml, load style-guides/{author}.md +3. Extract from style guide: voice traits, structure patterns, format rules +4. "Загрузил outline. Автор: {author}. Target: 2500 слов. 8 секций. + + Из style guide: {key traits from Section 1}, {opening approach from Section 2}. + + Начинаю писать..." +5. Write section by section, checking requirements +6. Assemble full draft +7. Verify word counts +8. Complete self-assessment +9. Create 3-drafting/nextjs-image-generation-tutorial/draft-v1.md +10. "Draft готов. 2,487 слов (target 2500). Все секции completed. Отмечу concern: секция Error Handling получилась плотной, возможно @editor захочет разбить. Ready for review." diff --git a/desktop-agents/4-editor/agent-guide.md b/desktop-agents/4-editor/agent-guide.md new file mode 100644 index 0000000..c9cad5a --- /dev/null +++ b/desktop-agents/4-editor/agent-guide.md @@ -0,0 +1,55 @@ +# @editor User Guide + +## Что я делаю + +Я — редактор качества. Последняя линия обороны перед человеческим review. Оцениваю drafts по 6 измерениям, выставляю баллы, пишу детальные critiques. + +## С чего начать + +Скажи мне одно из: +- "Покажи что готово к review" +- "Review draft для {slug}" +- "Пере-review после revision {slug}" + +## Мои возможности + +### Систематическая оценка +6 измерений с весами: +- Technical Accuracy (25%) +- Structure & Flow (20%) +- Author Voice (20%) +- Actionability (15%) +- Engagement (10%) +- SEO & Requirements (10%) + +### Verdict +- Score ≥ 7.0 → **PASS** → готов к human review +- Score < 7.0 → **FAIL** → требует revision + +### Детальный critique +- Critical issues (must fix) +- Major issues (should fix) +- Minor issues (nice to fix) +- What works well +- Voice check +- Prioritized fix list + +## Что я создаю + +``` +3-drafting/{slug}/ +└── critique-v1.md # Детальный разбор +``` + +## Важно + +- Я не сахарю проблемы +- Каждая критика = конкретный fix +- Стандарты не снижаются +- Author voice проверяется по style guide + +## После меня + +**PASS:** Draft готов → Human review в 4-human-review/ + +**FAIL:** Draft требует revision → возвращай @writer с critique diff --git a/desktop-agents/5-seo/agent-guide.md b/desktop-agents/5-seo/agent-guide.md new file mode 100644 index 0000000..11c3b67 --- /dev/null +++ b/desktop-agents/5-seo/agent-guide.md @@ -0,0 +1,50 @@ +# @seo User Guide + +## Что я делаю + +Я — SEO оптимизатор. Беру статьи после human review и готовлю их к максимальной видимости в поиске, не жертвуя читабельностью. + +## С чего начать + +Скажи мне одно из: +- "Покажи что готово к SEO" +- "Оптимизируй {slug}" + +## Мои возможности + +### On-Page SEO +- Title tag оптимизация +- Meta description +- Header hierarchy +- Keyword placement +- Internal/external links + +### Technical SEO +- Schema markup recommendations +- Featured snippet optimization +- Image alt text requirements + +### Audit +- Проверка всех SEO элементов +- Сравнение с конкурентами в SERP +- Рекомендации по улучшению + +## Что я создаю + +``` +5-optimization/{slug}/ +├── seo-package.md # Полный SEO пакет +├── final.md # Оптимизированная статья +└── meta.yml # Копия (status: optimization) +``` + +## Важно + +- User intent важнее keywords +- Натуральность важнее плотности +- Не порчу голос автора +- Читабельность не снижается + +## После меня + +SEO готов → передавай @image-gen для создания визуалов. diff --git a/desktop-agents/6-image-gen/agent-guide.md b/desktop-agents/6-image-gen/agent-guide.md new file mode 100644 index 0000000..c573809 --- /dev/null +++ b/desktop-agents/6-image-gen/agent-guide.md @@ -0,0 +1,61 @@ +# @image-gen User Guide + +## Что я делаю + +Я — генератор изображений. Создаю visual assets для статей: hero images, diagrams, screenshots, illustrations. Знаю ограничения AI generation. + +## С чего начать + +Скажи мне одно из: +- "Покажи что готово к image generation" +- "Создай image brief для {slug}" +- "Сгенерируй изображения для {slug}" + +## Мои возможности + +### Image Brief +- Детальное описание каждого изображения +- Prompts для AI generation +- Fallback подходы если AI не справится +- Alt text для SEO + +### Типы изображений +- Hero images (1200x630) +- Concept diagrams +- Code screenshots +- Process illustrations +- Comparison visuals + +### Author Visual Style +- Читаю Section 5 из style guide автора +- Использую правильный Banatie Project +- Применяю эстетику автора + +## Что я создаю + +``` +5-optimization/{slug}/ +└── image-brief.md # Спецификации изображений + +assets/{slug}/ +├── hero-{slug}.png +├── diagram-1.png +└── ... +``` + +## Что AI делает хорошо +- Abstract patterns +- Gradients и colors +- Geometric illustrations +- Conceptual imagery + +## Что AI делает плохо +- Text in images +- Hands +- Specific UI +- Brand logos +- Realistic screenshots + +## После меня + +Images готовы → статья переезжает в 6-ready/ diff --git a/desktop-agents/7-style-guide-creator/agent-guide.md b/desktop-agents/7-style-guide-creator/agent-guide.md new file mode 100644 index 0000000..c6225c1 --- /dev/null +++ b/desktop-agents/7-style-guide-creator/agent-guide.md @@ -0,0 +1,67 @@ +# @style-guide-creator User Guide + +## Что я делаю + +Я — создатель авторских персон. Провожу structured interview и создаю детальные style guides которые позволяют другим агентам писать голосом автора. + +## С чего начать + +Скажи мне одно из: +- "Покажи текущих авторов" +- "Создай нового автора" +- "Дополни style guide для {author}" + +## Мои возможности + +### Создание нового автора +- 5-фазный discovery interview +- Генерация полного style guide (5 секций) +- Автоматическое обновление AUTHORS.md + +### Обновление существующего +- Проверка какие секции неполные +- Targeted questions только для gaps +- Обновление guide + +### 5 обязательных секций +1. **Voice & Tone** — личность, фразы, эмоциональный регистр +2. **Structure Patterns** — openings, sections, closings +3. **Content Scope** — типы контента, темы, глубина +4. **Format Rules** — word counts, форматирование +5. **Visual Style** — эстетика изображений, Banatie project + +## Что я создаю + +``` +style-guides/ +├── AUTHORS.md # Реестр (обновляю) +└── {author-id}.md # Полный style guide +``` + +## Discovery Interview + +### Phase 1: Identity & Purpose +- Имя, background, цель + +### Phase 2: Voice & Personality +- Формальность, юмор, uncertainty + +### Phase 3: Structure & Format +- Openings, sections, code, closings + +### Phase 4: Scope +- Типы контента, темы in/out scope + +### Phase 5: Visuals +- Image aesthetic, Banatie project + +## Важно + +- Не принимаю vague ответы — уточняю +- Все 5 секций обязательны +- Примеры (GOOD/BAD) в каждой секции +- AUTHORS.md обновляется автоматически + +## После меня + +Style guide готов → другие агенты могут работать с этим автором без изменений в их system prompts.