arkaos 2.54.0 → 2.55.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/VERSION CHANGED
@@ -1 +1 @@
1
- 2.54.0
1
+ 2.55.0
@@ -1,7 +1,9 @@
1
1
  ---
2
2
  name: content/youtube-strategy
3
3
  description: >
4
- YouTube strategy: title/thumbnail packaging, script structure, SEO, upload cadence.
4
+ YouTube strategy channel positioning, title × thumbnail architecture,
5
+ hook + script structure, SEO + metadata, publishing cadence, cross-platform
6
+ distribution.
5
7
  allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
6
8
  ---
7
9
 
@@ -19,14 +21,141 @@ treat them as your default source. External research supplements, it
19
21
  does not replace the vault.
20
22
  <!-- arka:kb-first-prefix end -->
21
23
 
22
- # Youtube Strategy — `/content youtube <topic>`
24
+ # YouTube Strategy — `/content youtube <topic>`
23
25
 
24
- > **Agent:** Rafael (Content Strategist) | **Framework:** MrBeast Method + YouTube Algorithm
26
+ > **Lead:** Rafael (Content Strategist) | **Cross-dept:** Isabel (Visual Designer) + Teresa (Copy) + Luna (Marketing) | **Frameworks:** MrBeast Title × Thumbnail Method + Algorithm-Aware Retention Design
25
27
 
26
- ## What It Does
28
+ ## What ships
27
29
 
28
- YouTube strategy: title/thumbnail packaging, script structure, SEO, upload cadence.
30
+ A production YouTube strategy in 7 deliverables:
29
31
 
30
- ## Output
32
+ 1. **Channel positioning** with competing-channel analysis
33
+ 2. **10 title × thumbnail pairs** with CTR patterns named
34
+ 3. **Hook architecture** + retention curve plan per video
35
+ 4. **Script structure** with retention drops mapped
36
+ 5. **SEO metadata + playlist hierarchy**
37
+ 6. **Publishing cadence** with view + subscriber targets
38
+ 7. **Cross-platform derivative spec** (Shorts, threads, newsletter)
31
39
 
32
- YouTube strategy with 10 video ideas, title/thumb variants, and growth targets
40
+ ## The CTR-Retention Math (why packaging matters)
41
+
42
+ The YouTube algorithm rewards two metrics in tight loop:
43
+
44
+ - **CTR (click-through rate)** — % of impressions that click. Median is 4-6%; top performers 10-15%.
45
+ - **AVD (average view duration)** — minutes watched per view. Algorithm normalizes by video length but rewards higher absolute AVD.
46
+
47
+ CTR depends on **title × thumbnail × topic** working together. AVD depends on **hook + retention curve + payoff**. If CTR is high but AVD is low, the algorithm interprets the video as clickbait and demotes it. If CTR is low but AVD is high, the video starves of impressions.
48
+
49
+ Target floor: CTR ≥ 6%, AVD ≥ 40% of length, retention curve no sharp drops in first 30 seconds.
50
+
51
+ ## Title × Thumbnail Patterns (CTR levers)
52
+
53
+ Each title × thumbnail pair uses one of these named patterns. Mixing patterns randomly produces noise; picking a primary pattern per channel produces compounding.
54
+
55
+ | Pattern | Title shape | Thumbnail shape | Use case |
56
+ |---|---|---|---|
57
+ | **Curiosity Gap** | "What happens when [unexpected]" | One element + question mark + face surprised | Investigation, experiment videos |
58
+ | **Transformation** | "From X to Y in Z time" | Before / After split | Tutorial, journey, case study |
59
+ | **Specific Claim** | "I [verb] [specific number] [specific subject]" | Numbers visible + product / outcome | Stunt, achievement, deep-dive |
60
+ | **Loss Aversion** | "Don't [common mistake]" | Red X + warning icon + face concerned | Warning, education |
61
+ | **Authority + Specific** | "How [expert title] [does specific thing]" | Person + tool / artifact + clean type | Expert content, behind-the-scenes |
62
+ | **Comparison** | "X vs Y: Which actually [outcome]" | Split with both items + clear winner cue | Review, head-to-head |
63
+ | **Contrarian** | "Why everyone is wrong about X" | Strikethrough on common belief + face defiant | Opinion, takedown, education |
64
+
65
+ Thumbnail design rules (visual hierarchy):
66
+ - **One focal point** — eye lands on a single element first
67
+ - **Face if relevant** — human face drives 30-40% CTR lift on most topics
68
+ - **Contrast** — high-saturation focal vs muted background
69
+ - **Type ≤ 4 words** — readable on mobile at 320px width
70
+ - **No clickbait that breaks promise** — title and thumbnail must accurately preview the payoff
71
+
72
+ ## Hook Architecture (first 30 seconds)
73
+
74
+ The first 30 seconds determines whether the viewer stays. The hook structure that consistently retains:
75
+
76
+ ```
77
+ 0-3s PATTERN INTERRUPT — visual + audio shock or unexpected statement
78
+ 3-10s PROMISE — name the transformation / outcome the viewer gets
79
+ 10-20s STAKES — why this matters, what they'll lose by leaving
80
+ 20-30s PREVIEW — quick montage of the 3 best moments coming up
81
+ ```
82
+
83
+ Pattern interrupts that work: starting mid-action, a contradictory statement, an unexpected location, an unexpected visual element. Pattern interrupts that don't work: long intro animations, founder face talking to camera with no visual.
84
+
85
+ ## Script Structure (full video)
86
+
87
+ Default structure for a 10-12 minute video (the optimal range for monetisation + retention):
88
+
89
+ ```
90
+ 0:00 - 0:30 Hook (see Hook Architecture)
91
+ 0:30 - 2:00 Setup — name the problem, stakes, why now
92
+ 2:00 - 4:00 Reframe — show the prevailing wrong answer + your alternative frame
93
+ 4:00 - 8:00 Content blocks (2-3 blocks) — each with a mini-hook, a payoff, a transition
94
+ 8:00 - 10:00 Payoff — the promised transformation / answer delivered concretely
95
+ 10:00 - 11:00 Recap + CTA — quick recap + subscribe / next video / link in description
96
+ 11:00 - 12:00 Outro + end screen — pattern-interrupt sting + related video CTA
97
+ ```
98
+
99
+ Retention drops happen at predictable moments: 1:00 (initial commitment), 4:00 (mid-video boredom), 8:00 (sense of completion). Insert a mini-hook 10 seconds before each predicted drop to retain viewers through it.
100
+
101
+ ## SEO Metadata Stack
102
+
103
+ For each video, fill the metadata stack:
104
+
105
+ ```yaml
106
+ title:
107
+ primary_keyword: "<2-3 word keyword>"
108
+ full_title: "<title with keyword + pattern + emotional anchor>"
109
+ variants_for_testing: 3-5 alternates
110
+
111
+ description:
112
+ first_140_chars: "<keyword-loaded summary that appears in search>"
113
+ full_description:
114
+ - paragraph 1: hook + value prop (250 chars)
115
+ - paragraph 2: timestamps with keyword variants
116
+ - paragraph 3: links + CTAs
117
+ - paragraph 4: hashtags (3-5 max, mixed broad + niche)
118
+ pinned_comment: "<first comment author posts with related links>"
119
+
120
+ tags:
121
+ primary: ["<broad topic>", "<specific topic>"]
122
+ long_tail: ["<specific phrase>", "<question phrase>"]
123
+ branded: ["<channel name>", "<series name>"]
124
+
125
+ end_screen:
126
+ best_for_viewer: <related video by same channel>
127
+ subscribe_cta: <button position>
128
+
129
+ playlists:
130
+ series_playlist: <series name if applicable>
131
+ topic_playlist: <topic cluster>
132
+ ```
133
+
134
+ ## Publishing Cadence Math
135
+
136
+ Sustainability beats burst. The cadence math:
137
+
138
+ - **Long-form video** anchor — 1 per week typical floor for growth channels, 1 per 2 weeks for high-production
139
+ - **Shorts derivatives** — 3-5 per long-form video, posted on rolling schedule
140
+ - **Community posts** — 2-3 per week to keep algorithm engagement signal
141
+ - **Live / Premiere** — optional monthly cadence for community deepening
142
+
143
+ First 90 days targets:
144
+ - Week 1-4: 4 long-forms, 16-20 shorts. Target: identify which pattern resonates.
145
+ - Week 5-8: Double down on winning pattern. Target: first video to 10k views.
146
+ - Week 9-12: Optimise + scale. Target: first 1000 subs OR 100k cumulative views, whichever ships first.
147
+
148
+ ## Cross-Platform Derivatives (per long-form video)
149
+
150
+ Each long-form video should produce:
151
+ - **3-5 YouTube Shorts** (vertical, 30-60s, hook-led clips)
152
+ - **1 Twitter/X thread** (10-15 tweets summarising the video with embedded clips)
153
+ - **1 LinkedIn post** (professional framing for B2B audiences)
154
+ - **1 newsletter section** (long-form summary with personal context)
155
+ - **1 Podcast adaptation** (audio extraction if relevant)
156
+
157
+ Derivative production should be templated — derivatives are not new content, they are repackaging.
158
+
159
+ ## Output → Obsidian: `WizardingCode/Content/YouTube/<topic>-<date>/`
160
+
161
+ Delivers: channel positioning + 10 title × thumbnail pairs + hook architecture + script structure for 3-5 videos + SEO metadata stack per video + 90-day cadence + cross-platform derivative spec + 1-page executive summary.
@@ -0,0 +1,136 @@
1
+ id: content-system
2
+ name: Content Operating System
3
+ description: Build a complete Content OS — strategy + production system + distribution + repurposing + analytics — that compounds output over time
4
+ department: content
5
+ tier: enterprise
6
+ command: "/content system"
7
+ requires_branch: false
8
+ requires_spec: false
9
+ quality_gate_required: true
10
+
11
+ phases:
12
+ - id: brief
13
+ name: Content OS Brief
14
+ description: Define audience, content goals, current capacity, platforms, runway, success metric
15
+ agents:
16
+ - agent_id: content-director-rafael
17
+ role: Frame audience, goals, current production cadence, target platforms, success metric
18
+ gate:
19
+ type: user_approval
20
+ description: User confirms audience, goals, platforms, success metric
21
+
22
+ - id: pillar-design
23
+ name: Content Pillar Design
24
+ description: Define 3-5 content pillars that align audience interest × business value × differentiation
25
+ agents:
26
+ - agent_id: content-director-rafael
27
+ role: 3-5 pillar topics with audience-interest score + business-value score per pillar
28
+ - agent_id: marketing-director-luna
29
+ role: Search demand + competitive density per pillar
30
+ parallel: true
31
+ gate:
32
+ type: user_approval
33
+ description: User approves the pillar set
34
+ outputs:
35
+ - type: document
36
+ format: markdown
37
+ obsidian_path: "WizardingCode/Content/OS/Pillars/"
38
+ description: Content pillar definition with audience/business/differentiation scoring
39
+
40
+ - id: format-stack
41
+ name: Format Stack
42
+ description: Define the format stack per pillar (long-form anchor + short-form derivatives + repurposing chain)
43
+ agents:
44
+ - agent_id: content-director-rafael
45
+ role: Format stack design (anchor format + 4-6 derivative formats per anchor)
46
+ - agent_id: short-form-specialist
47
+ role: Short-form derivative specifications (Reels / Shorts / Tweets / Carousels)
48
+ parallel: true
49
+ gate:
50
+ type: user_approval
51
+ description: User approves the format stack
52
+
53
+ - id: production-cadence
54
+ name: Production Cadence
55
+ description: Set realistic cadence — anchor pieces per month, derivatives per anchor, total weekly output
56
+ agents:
57
+ - agent_id: content-director-rafael
58
+ role: Cadence math — anchor cycle time, derivative multiplier, weekly total, sustainability check
59
+ gate:
60
+ type: user_approval
61
+ description: User approves the cadence
62
+
63
+ - id: distribution-channels
64
+ name: Distribution Channels
65
+ description: Map content type × platform — where each anchor and each derivative lives, with platform-native adaptations
66
+ agents:
67
+ - agent_id: content-director-rafael
68
+ role: Channel map with platform-native adaptations per format
69
+ - agent_id: marketing-director-luna
70
+ role: Distribution amplification — paid, partnerships, syndication options
71
+ parallel: true
72
+ gate:
73
+ type: user_approval
74
+ description: User approves distribution map
75
+
76
+ - id: analytics-stack
77
+ name: Analytics Stack
78
+ description: Define the metrics that matter — per-pillar performance, per-format performance, per-channel performance, North Star metric
79
+ agents:
80
+ - agent_id: content-director-rafael
81
+ role: Analytics dashboard spec with per-level metrics (pillar / format / channel)
82
+ - agent_id: tech-director-francisca
83
+ role: Tracking implementation feasibility
84
+ parallel: true
85
+ gate:
86
+ type: user_approval
87
+ description: User approves analytics stack
88
+
89
+ - id: ops-systems
90
+ name: Ops & Systems
91
+ description: Templates, briefs, asset library, review workflow, publishing workflow, archive
92
+ agents:
93
+ - agent_id: content-director-rafael
94
+ role: Operational templates and workflow specs (brief, review, publish, archive)
95
+ gate:
96
+ type: auto
97
+
98
+ - id: self-critique
99
+ name: Self-Critique
100
+ description: Stress-test the system — is cadence sustainable? Are pillars differentiated? Does analytics tie to North Star?
101
+ agents:
102
+ - agent_id: content-director-rafael
103
+ role: Coherence check across pillars / format stack / cadence / analytics / North Star
104
+ gate:
105
+ type: auto
106
+
107
+ - id: quality-gate
108
+ name: Quality Gate
109
+ model_override: opus
110
+ description: Mandatory quality review
111
+ agents:
112
+ - agent_id: cqo-marta
113
+ role: Orchestrate quality review
114
+ - agent_id: copy-director-eduardo
115
+ role: Pillar prose, format brief quality, no clichés
116
+ parallel: true
117
+ - agent_id: tech-director-francisca
118
+ role: Cadence feasibility, tracking integrity, workflow operability
119
+ parallel: true
120
+ gate:
121
+ type: quality_gate
122
+ required_verdict: APPROVED
123
+
124
+ - id: delivery
125
+ name: Content OS Package Delivery
126
+ description: Compile the full Content OS — pillars + format stack + cadence + distribution + analytics + ops templates
127
+ agents:
128
+ - agent_id: content-director-rafael
129
+ role: Full Content OS package + 1-page executive summary
130
+ gate:
131
+ type: auto
132
+ outputs:
133
+ - type: document
134
+ format: markdown
135
+ obsidian_path: "WizardingCode/Content/OS/"
136
+ description: Complete Content OS — pillars + format stack + cadence + distribution + analytics + ops templates + exec summary
@@ -0,0 +1,144 @@
1
+ id: content-youtube
2
+ name: YouTube Strategy
3
+ description: Full YouTube strategy — channel positioning, title × thumbnail × hook architecture, script structure, SEO optimization, distribution
4
+ department: content
5
+ tier: enterprise
6
+ command: "/content youtube"
7
+ requires_branch: false
8
+ requires_spec: false
9
+ quality_gate_required: true
10
+
11
+ phases:
12
+ - id: brief
13
+ name: YouTube Brief
14
+ description: Define topic, target audience, current channel state, monetisation goal, weekly capacity
15
+ agents:
16
+ - agent_id: content-director-rafael
17
+ role: Frame topic, audience, current subscribers + AVG view duration, monetisation goal
18
+ gate:
19
+ type: user_approval
20
+ description: User confirms YouTube brief
21
+
22
+ - id: channel-positioning
23
+ name: Channel Positioning
24
+ description: Position the channel in the YouTube taxonomy — niche, target persona, channel promise, competing channels
25
+ agents:
26
+ - agent_id: content-director-rafael
27
+ role: Channel positioning statement + competing channels analysis
28
+ - agent_id: brand-strategist-mateus
29
+ role: Differentiation angle, channel identity
30
+ parallel: true
31
+ gate:
32
+ type: user_approval
33
+ description: User approves channel positioning
34
+ outputs:
35
+ - type: document
36
+ format: markdown
37
+ obsidian_path: "WizardingCode/Content/YouTube/Positioning/"
38
+ description: Channel positioning + competing channels + differentiation angle
39
+
40
+ - id: title-thumbnail-architecture
41
+ name: Title × Thumbnail Architecture
42
+ description: Design 10 title × thumbnail pairs using CTR-tested patterns — curiosity gap + transformation + specificity + visual hierarchy
43
+ agents:
44
+ - agent_id: content-director-rafael
45
+ role: 10 title × thumbnail pairs with CTR pattern named per pair
46
+ - agent_id: visual-designer-isabel
47
+ role: Thumbnail visual hierarchy specs (face / contrast / focal-point / text-overlay rules)
48
+ parallel: true
49
+ gate:
50
+ type: user_approval
51
+ description: User selects 3-5 title × thumbnail pairs for first videos
52
+
53
+ - id: hook-script-structure
54
+ name: Hook × Script Structure
55
+ description: First 30s hook architecture + retention curve plan for the full script
56
+ agents:
57
+ - agent_id: content-director-rafael
58
+ role: Hook framework (negative → positive → curiosity gap → preview) + retention curve plan
59
+ - agent_id: sales-copywriter-teresa
60
+ role: Hook copy variants (3 per video) + script outline with retention drops mapped
61
+ parallel: true
62
+ gate:
63
+ type: user_approval
64
+ description: User approves hook + script structure
65
+ outputs:
66
+ - type: document
67
+ format: markdown
68
+ obsidian_path: "WizardingCode/Content/YouTube/Scripts/"
69
+ description: Hook architecture + script structure with retention curve plan
70
+
71
+ - id: seo-metadata
72
+ name: SEO & Metadata
73
+ description: Title keywords, description optimization, tags, end-screen design, playlist architecture
74
+ agents:
75
+ - agent_id: content-director-rafael
76
+ role: SEO metadata specs per video; playlist hierarchy
77
+ - agent_id: marketing-director-luna
78
+ role: Keyword research + search volume targeting
79
+ parallel: true
80
+ gate:
81
+ type: user_approval
82
+ description: User approves SEO + playlist architecture
83
+
84
+ - id: publishing-cadence
85
+ name: Publishing Cadence
86
+ description: Set sustainable publishing cadence with first-week / first-month / first-quarter targets
87
+ agents:
88
+ - agent_id: content-director-rafael
89
+ role: Cadence math + first-week / first-month / first-quarter view + subscriber targets
90
+ gate:
91
+ type: user_approval
92
+ description: User approves cadence and targets
93
+
94
+ - id: distribution-amplification
95
+ name: Distribution & Amplification
96
+ description: Cross-platform distribution — Shorts derivatives, Twitter/LinkedIn threads, email newsletter, podcast
97
+ agents:
98
+ - agent_id: content-director-rafael
99
+ role: Cross-platform derivative spec per long-form video
100
+ - agent_id: short-form-specialist
101
+ role: Shorts adaptation spec (3-5 Shorts per long-form)
102
+ parallel: true
103
+ gate:
104
+ type: auto
105
+
106
+ - id: self-critique
107
+ name: Self-Critique
108
+ description: Stress-test the strategy — is the cadence sustainable? Does positioning differentiate from competing channels? Does the CTR pattern math hold?
109
+ agents:
110
+ - agent_id: content-director-rafael
111
+ role: Coherence + sustainability + differentiation check
112
+ gate:
113
+ type: auto
114
+
115
+ - id: quality-gate
116
+ name: Quality Gate
117
+ model_override: opus
118
+ description: Mandatory quality review
119
+ agents:
120
+ - agent_id: cqo-marta
121
+ role: Orchestrate quality review
122
+ - agent_id: copy-director-eduardo
123
+ role: Title copy, hook copy, script structure, no clickbait that breaks promise
124
+ parallel: true
125
+ - agent_id: tech-director-francisca
126
+ role: Thumbnail visual hierarchy, retention curve feasibility, SEO metadata correctness
127
+ parallel: true
128
+ gate:
129
+ type: quality_gate
130
+ required_verdict: APPROVED
131
+
132
+ - id: delivery
133
+ name: YouTube Strategy Package Delivery
134
+ description: Compile the full YouTube strategy package
135
+ agents:
136
+ - agent_id: content-director-rafael
137
+ role: Full YouTube strategy package + 1-page executive summary
138
+ gate:
139
+ type: auto
140
+ outputs:
141
+ - type: document
142
+ format: markdown
143
+ obsidian_path: "WizardingCode/Content/YouTube/"
144
+ description: Complete YouTube strategy — positioning + title × thumbnail pairs + hook architecture + script structure + SEO metadata + publishing cadence + distribution + exec summary
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "arkaos",
3
- "version": "2.54.0",
3
+ "version": "2.55.0",
4
4
  "description": "The Operating System for AI Agent Teams",
5
5
  "type": "module",
6
6
  "bin": {
package/pyproject.toml CHANGED
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "arkaos-core"
3
- version = "2.54.0"
3
+ version = "2.55.0"
4
4
  description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
5
5
  readme = "README.md"
6
6
  license = {text = "MIT"}