code-ai-installer 1.5.6 → 2.0.1

package/domains/content/locales/en/.agents/skills/handoff/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: handoff
+description: Transition between gates — preconditions, artifacts registry by transitions, reverse handoff, handoff log
+---
+# Handoff — Transition Between Gates
+
+## When to Use
+- On **every transition** between gates — forward handoff.
+- On **return for rework** — reverse handoff.
+- **Mandatory** on every transition, in any pipeline mode. No exceptions.
+
+> **Distinction:** `$gates` checks readiness. `$handoff` transfers work. `$board` tracks status. Order: `$gates` PASS → `$handoff` → update `$board`.
+
+## Input
+
+| Field | Required | Description |
+|------|:-----------:|----------|
+| `$gates` Result | ✅ | PASS or CONDITIONAL PASS — handoff impossible on FAIL |
+| Sending Agent | ✅ | Who is handing off (current gate) |
+| Receiving Agent | ✅ | Who is receiving (next gate) |
+| Gate Artifacts | ✅ | Deliverables of the current gate (from `$gates` registry) |
+| Pipeline Mode | ✅ | Full / Bugfix / Hotfix |
+| Handoff Type | ✅ | Forward / Reverse (return for rework) |
+
+> **Precondition:** Handoff is possible **only** after `$gates` PASS or CONDITIONAL PASS. On FAIL — return to agent, handoff is not performed.
+
+## Handoff Statuses
+
+| Status | Meaning | When |
+|--------|----------|-------|
+| **Completed** | All deliverables ready, `$gates` PASS | Normal transition |
+| **Conditional** | Deliverables ready with gaps, `$gates` CONDITIONAL PASS | Transition with note: gaps logged |
+| **Return** | Work returned for rework | `$gates` FAIL or feedback from next gate / user |
+| **Blocker** | Handoff impossible, escalation required | External blocker (legal, access, data) |
+
+## Handoff Registry — what to transfer
+
+### Full Pipeline
+
+| Transition | Artifacts | Key Context |
+|---------|-----------|-------------------|
+| **Conductor → Strategist** | Task, scope, mode, board | Business goal, brand, constraints |
+| **Strategist → Researcher** | Audience analysis, platform strategy, content calendar, competitor analysis | Personas, platforms, competitor gaps, priority topics |
+| **Researcher → Copywriter** | Topic research, source verification, data storytelling, content brief | Facts, sources, narrative, brief with theses |
+| **Copywriter → Visual Concept** | Final text, content brief (visual section) | Topic, mood, platform, brand style |
+| **Copywriter + Visual → Reviewer** | Final text, visual / visual brief, AI prompts | Brief for verification, brand guidelines |
+| **Reviewer → Release Gate** | Review checklist (APPROVED), brand compliance, fact checking, readability | Remarks (if any and fixed), final statuses |
+| **Release Gate → Publication** | Full package: text + visual + meta + schedule | Date, platform, cross-posting |
+
+### Bugfix Pipeline
+
+| Transition | Artifacts | Key Context |
+|---------|-----------|-------------------|
+| **Conductor → Copywriter/Researcher** | Problem description, fix scope | What's broken, where, priority |
+| **Copywriter/Researcher → Reviewer** | Fixed content | What exactly changed, diff |
+| **Reviewer → Release Gate** | Review checklist (APPROVED) | Focus on what was fixed |
+
+### Hotfix Pipeline
+
+| Transition | Artifacts | Key Context |
+|---------|-----------|-------------------|
+| **Conductor → Copywriter+Reviewer** | Problem description, fix | Blast radius ≈ 0 confirmed, mini-checklist |
+
+## Reverse Handoff
+
+When returning for rework — a special protocol:
+
+### When it happens
+- `$gates` — FAIL.
+- Reviewer — REQUIRES CHANGES.
+- User — requested rework.
+- Next gate — found an issue with an artifact from the previous one.
+
+### Reverse handoff protocol
+1. State the **reason for return** — specific gaps / remarks.
+2. State **what exactly to rework** — not "re-do", but "fix CTA: leave one instead of two, wording according to `$cta-optimization`".
+3. State **what NOT to touch** — what is already approved and needs no changes.
+4. Update `$board` — receiving gate → `[↩] Rework`, sending gate → `[→] In progress`.
+5. After rework — repeat `$gates` check → forward handoff.
+
+## Protocol
+
+### Forward Handoff
+
+#### Step 1 — Preconditions
+1. Ensure that `$gates` gave PASS or CONDITIONAL PASS.
+2. Determine receiving agent from registry.
+3. Collect all artifacts from the handoff registry.
+
+#### Step 2 — Envelope Formation
+1. Fill **all fields** of the template (see below).
+2. For CONDITIONAL PASS — explicitly specify the gaps being passed on.
+3. Formulate a **clear task** for the next agent (what to do, not how).
+
+#### Step 3 — User sign-off
+1. Show the envelope to the user.
+2. Await explicit **"Approved"**.
+3. Do not proceed without Approved. No exceptions.
+
+#### Step 4 — Activation
+1. Update `$board`: current gate → `[✓] Completed`, next → `[→] In progress`.
+2. Add entry to handoff log.
+3. Activate the next agent with full context.
+
+### Reverse Handoff
+
+#### Step 1 — Reverse Envelope Formation
+1. Specify reason, gaps, what to fix, what not to touch.
+
+#### Step 2 — User sign-off
+1. Show the reverse envelope to the user.
+2. Await Approved for return.
+
+#### Step 3 — Activation
+1. Update `$board`: current → `[↩] Rework`, target → `[→] In progress`.
+2. Add entry to handoff log (type: Reverse).
+
+## Envelope Validation (Quality Gate)
+
+A handoff envelope is considered complete if:
+
+- [ ] `$gates` result attached (PASS / CONDITIONAL PASS)
+- [ ] Sending and receiving agents specified
+- [ ] All artifacts from handoff registry attached
+- [ ] Task for next agent specifically formulated
+- [ ] Context transferred (brand, platform, audience, constraints)
+- [ ] Expected deliverable specified
+- [ ] Blockers / gaps logged (or "None")
+- [ ] User Approved obtained
+- [ ] `$board` updated
+- [ ] Entry added to handoff log
+
+## Integration with other skills
+
+| Skill | Interaction |
+|------|----------------|
+| `$gates` | **Precondition:** handoff only after PASS/CONDITIONAL PASS |
+| `$board` | **Update:** on every handoff — update gate statuses + event log |
+| `$content-release-gate` | Final handoff → publication package |
+| All gate skills | Skill artifacts = handoff envelope contents |
+
+## Anti-patterns
+
+| Mistake | Why it's bad | How to do it right |
+|--------|-------------|---------------|
+| Handoff without `$gates` | Unverified artifacts → issues at the next gate | Always `$gates` PASS → then handoff |
+| Handoff without Approved | Protocol violation, user unaware | Always wait for explicit Approved |
+| "Make content" instead of a task | Agent doesn't know scope, does too much or too little | Specific task: "Write text for brief IG-20260415-01, focus on persona X" |
+| Handoff without artifacts | Next agent works blind | All registry artifacts are attached |
+| Reverse handoff without specifics | Agent doesn't know what to fix | Specific gaps + what NOT to touch |
+| Failing to update `$board` | Board out of sync, unclear where we are | Update `$board` at every handoff |
+| Context lost during handoff | Next agent asks again | Brand, platform, audience, constraints — in every envelope |
+
+## Output Template
+
+### Forward Handoff
+
+```
+### Handoff Envelope — [Agent From] → [Agent To]
+
+**Type:** Forward
+**Mode:** [Full / Bugfix / Hotfix]
+**Gate Check:** [PASS / CONDITIONAL PASS] (iteration [N])
+**Date:** [YYYY-MM-DD]
+
+---
+
+**Status:** [Completed / Conditional]
+
+**Artifacts:**
+- [Artifact 1 — description / link]
+- [Artifact 2 — description / link]
+- [Artifact 3 — description / link]
+
+**Gaps (if CONDITIONAL):**
+- [Gap 1 — what to consider]
+
+---
+
+**Task for [Agent To]:**
+[Clear specific formulation: what to do, scope, focus]
+
+**Context:**
+- Brand: [brand]
+- Platform: [platform]
+- Audience: [persona from $audience-analysis]
+- Constraints: [constraints]
+- ToV: [tone from $brand-guidelines]
+
+**Expected deliverable:**
+[What the next agent should return — specific list]
+
+**Blockers:**
+[List of blockers or "None"]
+
+---
+
+→ Waiting for **"Approved"** to transition to **[Agent To]**
+```
+
+### Reverse Handoff
+
+```
+### Reverse Handoff — [Agent From] → [Agent To] (rework)
+
+**Type:** Reverse
+**Reason:** [FAIL on $gates / REQUIRES CHANGES from Reviewer / user feedback]
+**Date:** [YYYY-MM-DD]
+
+---
+
+**What to fix:**
+| # | Gap / Remark | Sev | Specific action |
+|---|----------------|-----|---------------------|
+| 1 | [description] | 🔴/🟡 | [what to do] |
+| 2 | [description] | 🔴/🟡 | [what to do] |
+
+**What NOT to touch:**
+- [Artifact / section inherently approved]
+
+**Context:**
+[Additional context, if needed]
+
+---
+
+→ After rework — repeated `$gates` check (iteration [N+1])
+→ Waiting for **"Approved"** for return
+```
+
+### Handoff Log
+
+```
+#### Handoff Log — [Task / ID]
+
+| # | Date | Type | From → To | Gate Check | Status | Gaps |
+|---|------|-----|-----------|------------|--------|-------|
+| 1 | [date] | Forward | Conductor → Strategist | PASS | Completed | — |
+| 2 | [date] | Forward | Strategist → Researcher | CONDITIONAL | Conditional | [gap] |
+| 3 | [date] | Forward | Researcher → Copywriter | PASS | Completed | — |
+| 4 | [date] | Reverse | Reviewer → Copywriter | FAIL | Return | [gaps] |
+| 5 | [date] | Forward | Copywriter → Reviewer | PASS | Completed | — |
+```

package/domains/content/locales/en/.agents/skills/headline-formulas/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: headline-formulas
+description: Headline creation — 15+ formulas, Power Words, funnel, platform adaptation, scorecard evaluation
+---
+# Headline Formulas
+
+## When to Use
+- When writing **post headlines**, articles, email subject lines, ads.
+- When creating **hooks** for reels, videos, carousels (first frame / first seconds).
+- When **optimizing existing** headlines — low CTR, low open rate.
+- As part of **`$content-brief`** — "Headline / Hook" section.
+
+## Input
+
+| Field | Required | Description |
+|------|:-----------:|----------|
+| Topic / key insight | ✅ | What the content is about — main idea or fact |
+| Target audience persona | ✅ | From `$audience-analysis` — language, pains, triggers |
+| Platform | ✅ | Determines character limits and style |
+| Content type | ✅ | Post / article / email / reel / carousel / landing page / ad |
+| Funnel stage | ✅ | TOFU / MOFU / BOFU — determines the approach |
+| SEO keyword | ⬚ | If SEO content — main keyword for title |
+| Current headline | ⬚ | If optimization — current version and its metrics |
+
+> If persona or platform are not specified — **request**. A headline without a target audience is a headline for nobody.
+
+## Headline Formulas
+
+### Basic (Universal)
+
+| # | Formula | Template | Example | Best for |
+|---|---------|--------|--------|-----------------|
+| 1 | **Number + Result** | "[N] ways to [achieve result]" | "7 ways to double your email conversion" | Articles, carousels, listicles |
+| 2 | **How-to** | "How to [achieve goal] without [problem]" | "How to get your first 1000 followers with zero budget" | Educational, TOFU/MOFU |
+| 3 | **Question + Pain** | "Why [problem]? (and how to fix it)" | "Why your posts aren't getting reach?" | Posts, emails, nurturing |
+| 4 | **Contradiction** | "[Opinion] — is actually [fact]" | "Everyone says to post daily — here is why it doesn't work" | Posts, viral, TOFU |
+
+### Advanced (High CTR)
+
+| # | Formula | Template | Example | Best for |
+|---|---------|--------|--------|-----------------|
+| 5 | **4U** | Urgent + Unique + Ultra-specific + Useful | "Before Friday: 3 steps to your first sale via Telegram" | Promo, BOFU, email |
+| 6 | **Before/After** | "[Before] → [After] in [time/action]" | "0 followers → 10K in 3 months: what worked" | Case studies, MOFU |
+| 7 | **Social Proof** | "[N people/companies] already [result]" | "500+ marketers already use this strategy" | MOFU/BOFU, promo |
+| 8 | **Negative / Fear** | "[N] mistakes that [kill result]" | "5 mistakes that are killing your email open rate" | Educational, TOFU |
+| 9 | **Curiosity Gap** | "[Intrigue] — [hint without revealing]" | "We found what marketers have ignored for years" | TOFU, viral |
+| 10 | **Specificity** | "[Exact number] + [specific result] + [condition]" | "How we got 847 leads for $0.12 each through one carousel" | Case studies, MOFU |
+
+### Specialized
+
+| # | Formula | Template | Example | Best for |
+|---|---------|--------|--------|-----------------|
+| 11 | **Celebrity / Authority** | "[Authority] recommends [method]" | "Gary V's method for creating 30 posts from one video" | TOFU, educational |
+| 12 | **This vs That** | "[A] vs [B]: what works better for [context]" | "Reels vs Carousels: what gets more reach in 2026" | Comparisons, MOFU |
+| 13 | **Secret / Insider** | "[Secret/trick] that [nobody talks about/few know]" | "A copywriting trick agencies keep silent about" | TOFU, curiosity |
+| 14 | **Challenge** | "[Result] in [time]: [challenge]" | "30 reels in 30 days: what happened to the account" | Series, engagement |
+| 15 | **Direct Benefit** | "[Get/Learn/Discover] [result] [right now]" | "Get a ready-made content plan for April — free" | BOFU, lead magnets |
+
+## Formulas by Funnel Stage
+
+| Stage | Headline Goal | Best Formulas | Style |
+|------|---------------|----------------|-------|
+| **TOFU** | Attract attention, broad reach | #4 Contradiction, #8 Negative, #9 Curiosity, #13 Secret, #14 Challenge | Provocative, intriguing, viral |
+| **MOFU** | Deepen interest, build trust | #2 How-to, #3 Question+Pain, #6 Before/After, #7 Social Proof, #10 Specificity, #12 This vs That | Expert, specific, data-driven |
+| **BOFU** | Convert | #5 4U, #7 Social Proof, #15 Direct Benefit | Direct, with urgency, value-driven |
+
+## Power Words
+
+Enhancing words that increase headline CTR:
+
+| Category | Words |
+|-----------|-------|
+| **Value** | free, ready-made, step-by-step, proven, guaranteed |
+| **Urgency** | now, today, by [date], last chance, before it's too late |
+| **Curiosity** | secret, unexpected, hidden, little-known, actually |
+| **Negative** | mistake, kills, losing, never, stop, enough |
+| **Emotion** | incredible, shocking, amazing, powerful |
+| **Specificity** | exact, step-by-step, specific, [number], in [time] |
+| **Exclusive** | only for, for the first time, insider, private |
+
+> Use 1-2 Power Words per headline. More = clickbait.
+
+## Platform Adaptation
+
+| Platform | Character Limit | Style | Features |
+|-----------|---------------|-------|-------------|
+| **Instagram (caption hook)** | First 125 chars visible without "more" | Short, intriguing, emotional | Hook = first line. Emojis allowed. Caps Lock for emphasis |
+| **Instagram (carousel cover)** | 5-8 words on cover | Large text, contrasting | Readability > creativity. Single hook |
+| **Telegram** | First 2-3 lines visible in preview | Informative, specific | No clickbait — Telegram audience is unforgiving |
+| **LinkedIn** | First 150 chars before "...see more" | Professional, expert | Start with an insight or number. No emojis |
+| **Email subject** | ≤ 50 chars (mobile) | Personal, curiosity or value | Preheader complements, doesn't repeat |
+| **Google Title (SEO)** | ≤ 60 chars | SEO keyword at start + value | Keyword as early as possible |
+| **YouTube** | ≤ 70 chars (truncates ~60) | Curiosity + specificity | Caps Lock for 1-2 words, numbers, emotion |
+| **Twitter/X** | ≤ 280 (shorter = better) | Sharp, provocative, meme-like | No links in text (reduces reach) |
+| **Ad Copy** | Varies by platform | Direct benefit + urgency | Test 3-5 variants |
+
+## Scorecard — Evaluation
+
+Each headline variant is evaluated on 6 criteria (1-5 points):
+
+| Criterion | 1 (Weak) | 3 (Average) | 5 (Strong) |
+|----------|-----------|------------|------------|
+| **Clarity** | Unclear what it's about | Understandable if read carefully | Instantly clear |
+| **Specificity** | Abstract ("improve marketing") | Hint of specificity | Exact numbers, deadlines, results |
+| **Value** | No benefit for reader | Benefit is implied | Explicit benefit in headline |
+| **Emotion / Curiosity** | Boring, no reaction | Slightly interesting | Elicits "seriously?!" or "I need to know" |
+| **Audience Fit** | For everyone = for nobody | Fits broadly | Speaks the specific persona's language |
+| **Platform Fit** | Doesn't fit format | Fits, but not optimal | Perfect for platform (limits, style) |
+
+**Threshold:** ≥ 22 out of 30 — strong headline. 18-21 — revise. < 18 — rewrite.
+
+## Protocol
+
+### Step 1 — Context
+1. Get input data: topic, persona, platform, funnel, content type.
+2. Determine character limit based on platform.
+3. If SEO — set the keyword.
+
+### Step 2 — Formula Selection
+1. Based on funnel stage — choose **3-4 suitable formulas** from the table.
+2. Consider content type (case study → Before/After, listicle → Number+Result).
+3. Consider persona (gen Z → provocation, B2B → expertise).
+
+### Step 3 — Generation
+1. For each formula — write **1-2 variants** of the headline.
+2. Use **1-2 Power Words** (no more).
+3. Check platform character limits.
+4. Total: **5-8 variants**.
+
+### Step 4 — Scorecard Evaluation
+1. Evaluate each variant on 6 criteria (1-5).
+2. Calculate total score.
+3. Discard variants < 18 points.
+
+### Step 5 — Final Selection
+1. **Primary** — variant with the highest score.
+2. **A/B Test** — variant using a different formula (to test the approach, not just wording).
+3. Justify the choice.
+
+## Validation (Quality Gate)
+
+Headlines are considered ready if:
+
+- [ ] Generated ≥ 5 variants using ≥ 3 formulas
+- [ ] Each variant is within platform limits
+- [ ] Each variant evaluated via Scorecard
+- [ ] Primary variant ≥ 22 points
+- [ ] Variant selected for A/B test (different formula)
+- [ ] Headline matches the funnel stage
+- [ ] Headline doesn't deceive expectations (no clickbait)
+- [ ] Power Words ≤ 2 per headline
+
+## Handoff
+
+| Consumer | How it's used |
+|-------------|---------------|
+| `$content-brief` | Headline as part of the "Hook / Headline" section |
+| `$email-copywriting` | Subject line from headline formulas |
+| `$seo-copywriting` | SEO-title with keyword |
+| `$social-media-formats` | Hook for post / first frame of carousel / reels |
+| `$content-review-checklist` | Reviewer checks headline according to item #10 |
+
+## Integration with other skills
+
+| Skill | Interaction |
+|------|----------------|
+| `$audience-analysis` | **Source:** persona, pains, customer language → wording |
+| `$cta-optimization` | **Complement:** headline attracts, CTA converts |
+| `$data-storytelling` | **Source:** fact-hook → headline via formula #10 Specificity |
+| `$seo-copywriting` | **Source:** SEO keyword → headline for Google Title |
+| `$tone-of-voice` | **Source:** headline tone = brand tone |
+
+## Anti-patterns
+
+| Mistake | Why it's bad | How to do it right |
+|--------|-------------|---------------|
+| Clickbait without substance | High clicks, but quick exits → ER drops, trust lost | Headline promises — content delivers |
+| "Read more" / "New post" | Zero value, nobody clicks | Specific benefit or intrigue |
+| 5+ Power Words | Looks like spam: "FREE SECRET INCREDIBLE AMAZING METHOD" | Maximum 1-2 Power Words |
+| Headline mismatch with funnel | TOFU audience sees "Buy now" → scroll past | Formula based on funnel stage |
+| One variant without A/B | No data for optimization | At least 2 variants with different formulas |
+| Long headline on mobile | Truncated, meaning lost | Check platform limits |
+| Abstraction without specifics | "Improve your marketing" — boring | Numbers, deadlines, results: "+340% reach in 2 weeks" |
+| Headline for yourself, not TA | Uses professional jargon for beginners | Persona language from `$audience-analysis` |
+
+## Output Template
+
+```
+### Headline Variants — [Topic]
+
+**Persona:** [from $audience-analysis]
+**Platform:** [platform] (limit: [N] chars)
+**Funnel Stage:** [TOFU / MOFU / BOFU]
+**Content Type:** [post / article / email / reel / carousel / landing page]
+**SEO Keyword:** [keyword or N/A]
+
+---
+
+#### Variants
+
+| # | Formula | Headline | Chars | Scorecard |
+|---|---------|-----------|----------|-----------|
+| 1 | Number + Result | "[headline]" | [N] | [score]/30 |
+| 2 | Question + Pain | "[headline]" | [N] | [score]/30 |
+| 3 | Contradiction | "[headline]" | [N] | [score]/30 |
+| 4 | Before/After | "[headline]" | [N] | [score]/30 |
+| 5 | Curiosity Gap | "[headline]" | [N] | [score]/30 |
+
+#### Scorecard (Top 3)
+
+| Criterion | Variant [A] | Variant [B] | Variant [C] |
+|----------|------------|------------|------------|
+| Clarity (1-5) | [N] | [N] | [N] |
+| Specificity (1-5) | [N] | [N] | [N] |
+| Value (1-5) | [N] | [N] | [N] |
+| Emotion / Curiosity (1-5) | [N] | [N] | [N] |
+| Audience Fit (1-5) | [N] | [N] | [N] |
+| Platform Fit (1-5) | [N] | [N] | [N] |
+| **Total** | **[N]/30** | **[N]/30** | **[N]/30** |
+
+---
+
+#### Recommendation
+
+**Primary:** Variant [X] — "[headline]"
+**Justification:** [why — formula, score, TA/funnel fit]
+
+**A/B Test:** Variant [Y] — "[headline]"
+**Hypothesis:** [what we are testing — different formula / different trigger]
+
+**Power Words Used:** [list]
+
+**→ Next step:** insert into `$content-brief` / `$email-copywriting` / handoff to Copywriter
+```