arkaos 4.12.0 → 4.13.0

package/departments/content/skills/video-setup/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: content/video-setup
+description: >
+  One-time environment bootstrap for video production — preflights and
+  (with per-step user confirmation) installs the Hyperframes skills,
+  Agent-Reach CLI, and Higgsfield key wiring, ending with an honest
+  capability matrix. TRIGGER: "/content video-setup", "setup video",
+  "prepara o ambiente de vídeo", "instala o hyperframes", "configura a
+  produção de vídeo", "video production setup". SKIP: actually producing
+  a video -> content/video-produce (it preflights non-interactively and
+  degrades); general MCP setup -> /arka keys or apply-mcps.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
+---
+
+<!-- arka:kb-first-prefix begin -->
+> **KB-first:** query `mcp__obsidian__search_notes` and cite
+> `[[wikilinks]]` — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
+<!-- arka:kb-first-prefix end -->
+
+# Video Setup — `/content video-setup`
+
+> **Agent:** Simão (Video Producer) | **Purpose:** environment bootstrap, run once per machine
+
+## Preflight (run first, print PASS/FAIL per row)
+
+| Check | Command | Needed for |
+|---|---|---|
+| Node.js 22+ | `node --version` | Hyperframes rendering |
+| FFmpeg | `ffmpeg -version` | encode/cut + transcription |
+| Hyperframes skills | `ls ~/.claude/skills/ \| grep -i hyperframes` | video-as-code editing |
+| Agent-Reach | `agent-reach doctor` | trend/research platform pulls |
+| Higgsfield key | `HIGGSFIELD_API_KEY` in env or `~/.arkaos/keys.json` | generation engine (MCP) |
+
+`npx arkaos doctor` runs the same five checks (warn-only) from the
+installer side — this skill is the interactive fix path.
+
+## Install steps — EACH gated on explicit user confirmation, never silent
+
+1. **Hyperframes skills** (free, Apache-2.0, HeyGen):
+   ```
+   npx skills add heygen-com/hyperframes --full-depth --yes
+   ```
+   `--full-depth` is MANDATORY — without it the skills registry serves a
+   stale snapshot that lags the upstream main branch. Installs ~20
+   skills including the `/hyperframes` router, `/talking-head-recut`,
+   `/faceless-explainer`, `/product-launch-video`, `/motion-graphics`,
+   `/embedded-captions`, `/media-use`. Keep fresh later with
+   `npx hyperframes skills update <workflow>`.
+2. **Agent-Reach CLI** (MIT, beta): install into an isolated tool env —
+   `pipx install agent-reach` (or `uv tool install agent-reach`),
+   NEVER a bare global pip (python-core rule: virtual environments
+   only). Then run `agent-reach doctor` and show the user which of the
+   15 platform backends are live; cookie/browser-session platforms
+   (X, Reddit, IG, FB) need the user's own logged sessions and stay
+   optional.
+3. **Higgsfield key**: `npx arkaos keys set HIGGSFIELD_API_KEY <key>`
+   (account at higgsfield.ai), then activate per project:
+   `bash apply-mcps.sh --add higgsfield` or select the `content` MCP
+   profile.
+
+## Never install binaries
+
+Node.js and FFmpeg are system packages — print the platform-specific
+instruction and stop:
+
+- macOS: `brew install ffmpeg` · `nvm install 22`
+- Linux: `apt install ffmpeg` (or distro equivalent)
+- Windows: `winget install Gyan.FFmpeg`
+
+ArkaOS detects and instructs; it never mutates the user's system
+package state.
+
+## Capability matrix (always print at the end — honest, per backend)
+
+| Capability | Full | Degraded | Manual |
+|---|---|---|---|
+| Asset generation | Higgsfield MCP | `arka-comfyui` (local) | asset brief with engine-ready prompts |
+| Edit / render | Hyperframes (Node 22 + FFmpeg) | Higgsfield `explainer_video` / `shorts_studio` (server-side) | edit-ready package (script + assets + EDL + SRT) |
+| Research | agent-reach | firecrawl + WebSearch | KB-only |
+
+State plainly which tier each capability landed on and what it takes to
+reach the tier above. A missing backend NEVER blocks the pipeline — it selects
+the next tier and says so (multi-backend rule: no capability is ever
+hardcoded to a single external backend).
+
+## Output
+
+Setup report: preflight table, what was installed (with user consent
+noted per step), the capability matrix, and the exact next command to
+try (`/content video <topic>`).

package/departments/content/squad.yaml

@@ -37,3 +37,9 @@ workflows:
   - workflow_id: content-youtube
     trigger_command: "/content youtube"
     tier: enterprise
+  - workflow_id: content-video
+    trigger_command: "/content video"
+    tier: enterprise
+  - workflow_id: content-shorts-produce
+    trigger_command: "/content shorts"
+    tier: focused

package/departments/content/workflows/shorts-social.yaml

@@ -0,0 +1,83 @@
+id: content-shorts-produce
+name: Shorts Batch Production
+description: Batch production of 3-5 rendered short-form videos — trend check, hooks, scripts, assets, vertical render, posting schedule (distinct from /content short, which is script-only)
+department: content
+tier: focused
+command: "/content shorts"
+requires_branch: false
+requires_spec: false
+quality_gate_required: true
+
+phases:
+  - id: brief
+    name: Shorts Brief
+    description: Define niche/topic, platform mix (Reels / TikTok / Shorts), batch size, and capability preflight
+    agents:
+      - agent_id: content-strategist-rafael
+        role: Frame niche, platforms, batch size, cadence
+      - agent_id: video-producer-simao
+        role: Capability preflight — state the asset and render tiers
+        parallel: true
+    gate:
+      type: user_approval
+      description: User confirms the batch brief
+
+  - id: trend-hooks
+    name: Trend Check & Hooks
+    description: Demand-first validation of the batch angles plus hook variants per short
+    agents:
+      - agent_id: trends-analyst-margarida
+        role: Trend check per angle (declared platform skips), STEPPS shortlist
+      - agent_id: viral-engineer-filipe
+        role: Hook variants (3 per short) mapped to the shortlist
+        parallel: true
+    gate:
+      type: auto
+      description: Shortlist and hooks feed the scripts
+
+  - id: script-assets
+    name: Scripts & Assets
+    description: Batch scripts (storyboard-ready, vertical framing) and asset generation per the capability matrix
+    agents:
+      - agent_id: scriptwriter-joana
+        role: Batch scripts — vertical-first scenes, hook in the first 2 seconds, caption-safe framing
+      - agent_id: video-producer-simao
+        role: Assets per short (Higgsfield shorts_studio when live; declared degraded tiers otherwise)
+    gate:
+      type: user_approval
+      description: User approves scripts and generated assets before render — credits are metered
+
+  - id: quality-gate
+    name: Quality Gate
+    description: Mandatory pre-delivery review — binary verdict on the whole batch
+    model_override: opus
+    agents:
+      - agent_id: cqo-marta
+        role: Orchestrate review, aggregate verdicts, issue binary decision
+      - agent_id: copy-director-eduardo
+        role: Scripts, captions, on-screen text
+        parallel: true
+      - agent_id: tech-director-francisca
+        role: Render quality, vertical specs, caption sync
+        parallel: true
+    gate:
+      type: quality_gate
+      required_verdict: APPROVED
+
+  - id: delivery
+    name: Delivery
+    description: Rendered batch plus posting schedule
+    agents:
+      - agent_id: video-producer-simao
+        role: 3-5 rendered 9:16 MP4s + SRTs + thumbnails
+      - agent_id: repurpose-distributor-nuno
+        role: Posting schedule per platform (native captions, hashtags, timing)
+        parallel: true
+    gate:
+      type: auto
+      description: Batch delivered
+    outputs:
+      - type: document
+        format: markdown
+        obsidian_path: "WizardingCode/Content/Shorts/"
+        description: Batch manifest — files, posting schedule, backend tiers used

package/departments/content/workflows/video-production.yaml

@@ -0,0 +1,142 @@
+id: content-video
+name: Video Production
+description: End-to-end video production — sourced research, Hollywood script, storyboard, Higgsfield asset generation, Hyperframes edit/render, virality QA, quality gate, multi-format delivery
+department: content
+tier: enterprise
+command: "/content video"
+requires_branch: false
+requires_spec: false
+quality_gate_required: true
+
+phases:
+  - id: brief
+    name: Production Brief
+    description: Define target (brand channel / personal / client / new niche), format, platform, length; run the capability preflight and state the backend tier per capability
+    agents:
+      - agent_id: content-strategist-rafael
+        role: Frame target, audience, platform, format, success metric
+      - agent_id: video-producer-simao
+        role: Capability preflight (assets / edit / research tiers) + production constraints
+        parallel: true
+    gate:
+      type: user_approval
+      description: User confirms the production brief and the backend tiers
+
+  - id: research-trends
+    name: Research & Trend Validation
+    description: Sourced research with claim ledger plus demand-first angle validation, compiled into the production brief the script consumes
+    agents:
+      - agent_id: content-researcher-madalena
+        role: Sourced research — CRAAP-rated sources, claim ledger, [UNVERIFIED] fail-closed
+      - agent_id: trends-analyst-margarida
+        role: Demand-first angle validation + STEPPS scoring of the chosen angle
+        parallel: true
+      - agent_id: info-compiler-dinis
+        role: Compile the production brief (angle / audience / proof / hooks / beats / claim-source table)
+    gate:
+      type: user_approval
+      description: User approves the production brief
+    outputs:
+      - type: document
+        format: markdown
+        obsidian_path: "WizardingCode/Content/Research/"
+        description: Production brief with claim-source table
+
+  - id: script
+    name: Hollywood Script
+    description: Beat sheet then full script in scene/shot/VO/on-screen-text columns, Hook Architecture on the first 30 seconds, never-default voice
+    agents:
+      - agent_id: scriptwriter-joana
+        role: Beat sheet (Save the Cat / Story Circle adapted to length) + full script with scene/shot/VO/OST columns
+      - agent_id: viral-engineer-filipe
+        role: 3 hook variants + retention-drop map
+        parallel: true
+    gate:
+      type: user_approval
+      description: User approves the script and picks the hook
+
+  - id: storyboard
+    name: Storyboard & Shot List
+    description: Shot list with per-shot generation prompts, audio/VO plan, and thumbnail package under the brand design doctrine (benchmark named, [arka:design] marker)
+    agents:
+      - agent_id: video-producer-simao
+        role: Shot list + per-shot generation prompts + audio/VO plan + EDL skeleton
+      - agent_id: visual-designer-isabel
+        role: Thumbnail package (anti-default doctrine, benchmark named, structured design marker)
+        parallel: true
+    gate:
+      type: user_approval
+      description: User approves the storyboard — creative lock before credits are spent
+    outputs:
+      - type: document
+        format: markdown
+        obsidian_path: "WizardingCode/Content/Video/Storyboards/"
+        description: Shot list, generation prompts, audio plan, thumbnail specs
+
+  - id: asset-generation
+    name: Asset Generation
+    description: Execute per the capability matrix — Higgsfield primary (cost-tier models for routine b-roll, hero models only for hero shots), comfyui or manual asset brief as degraded tiers
+    agents:
+      - agent_id: video-producer-simao
+        role: Generate voice, b-roll, stills per shot list; post-process (remove_background / upscale / reframe); log credits spent
+    gate:
+      type: user_approval
+      description: User reviews generated assets BEFORE render — Higgsfield credits are metered; regeneration requires explicit approval, never a loop
+
+  - id: edit-render
+    name: Edit & Render
+    description: Hyperframes composition (HTML+GSAP motion graphics, word-level captions) and deterministic MP4 render, or the declared degraded path
+    agents:
+      - agent_id: video-producer-simao
+        role: Compose and render — /hyperframes workflow per format, GSAP timeline for motion graphics, embedded captions; state the tier actually used
+    gate:
+      type: auto
+      description: Proceeds to QA when the render (or edit-ready package) exists
+
+  - id: virality-qa
+    name: Virality & Technical QA
+    description: STEPPS audit and virality prediction plus technical quality control before the quality gate
+    agents:
+      - agent_id: viral-engineer-filipe
+        role: STEPPS audit + virality_predictor / video_analysis when Higgsfield is live (hook strength, retention risk)
+      - agent_id: video-producer-simao
+        role: Technical QC — sync, caption accuracy, aspect ratios, loudness
+        parallel: true
+    gate:
+      type: auto
+      description: QA findings attached to the quality-gate input
+
+  - id: quality-gate
+    name: Quality Gate
+    description: Mandatory pre-delivery review — binary verdict
+    model_override: opus
+    agents:
+      - agent_id: cqo-marta
+        role: Orchestrate review, aggregate verdicts, issue binary decision
+      - agent_id: copy-director-eduardo
+        role: Script, captions, title and description copy
+        parallel: true
+      - agent_id: tech-director-francisca
+        role: Render quality, spec compliance, delivery formats
+        parallel: true
+    gate:
+      type: quality_gate
+      required_verdict: APPROVED
+
+  - id: delivery
+    name: Delivery
+    description: Final package and repurposing spec
+    agents:
+      - agent_id: video-producer-simao
+        role: Master MP4 + 9:16 reframe + thumbnail + title/description/tags + SRT
+      - agent_id: repurpose-distributor-nuno
+        role: Repurposing spec (1 → 30+) and distribution calendar
+        parallel: true
+    gate:
+      type: auto
+      description: Package delivered
+    outputs:
+      - type: document
+        format: markdown
+        obsidian_path: "WizardingCode/Content/Video/"
+        description: Delivery manifest — files, metadata, repurposing spec, backend tiers used

package/departments/content/workflows/youtube.yaml

@@ -28,6 +28,9 @@ phases:
       - agent_id: brand-strategist-mateus
         role: Differentiation angle, channel identity
         parallel: true
+      - agent_id: trends-analyst-margarida
+        role: Data-backed niche validation (demand volume, competition density)
+        parallel: true
     gate:
       type: user_approval
       description: User approves channel positioning

package/departments/dev/agents/frontend-dev.yaml

@@ -3,7 +3,7 @@ name: Diana
 role: Senior Frontend Developer
 department: dev
 tier: 2
-model: sonnet
+model: opus
 
 behavioral_dna:
   disc:

package/installer/doctor.js

@@ -23,7 +23,7 @@ function commandExists(cmd) {
   }
 }
 
-const checks = [
+export const checks = [
   {
     name: "install-dir",
     description: "ArkaOS installation directory exists",
@@ -230,6 +230,61 @@ const checks = [
     },
     fix: () => "Run: npx arkaos keys set MAGIC_API_KEY <your-21st-dev-key>  (or re-run npx arkaos@latest update)",
   },
+  // ─── Content production prerequisites (PR-C2) — all warn-only:
+  // video production is opt-in; the installer never fails on these and
+  // never installs the binaries itself (detect + instruct only).
+  {
+    name: "node-22-video",
+    description: "Node.js 22+ (required by Hyperframes video rendering)",
+    severity: "warn",
+    check: () => {
+      const major = parseInt(process.version.slice(1).split(".")[0], 10);
+      return Number.isFinite(major) && major >= 22;
+    },
+    fix: () => "Install Node.js 22+ (nvm install 22) — only needed for /content video rendering",
+  },
+  {
+    name: "ffmpeg",
+    description: "FFmpeg present (video encode/cut for Hyperframes + transcription workflows)",
+    severity: "warn",
+    check: () => commandExists("ffmpeg"),
+    fix: () => "Install FFmpeg: brew install ffmpeg (macOS) / apt install ffmpeg (Linux) / winget install Gyan.FFmpeg (Windows)",
+  },
+  {
+    name: "agent-reach",
+    description: "Agent-Reach CLI present (multi-platform source pulls for the content trend and research skills)",
+    severity: "warn",
+    check: () => commandExists("agent-reach"),
+    fix: () => "Install: pipx install agent-reach (or uv tool install agent-reach), then run: agent-reach doctor",
+  },
+  {
+    name: "hyperframes-skills",
+    description: "Hyperframes skills installed (video-as-code editing for /content video)",
+    severity: "warn",
+    check: () => {
+      // `npx skills add heygen-com/hyperframes` lands skills under
+      // ~/.claude/skills/<name>; the router skill is the sentinel.
+      return ["hyperframes", "hyperframes-core"].some((name) =>
+        existsSync(join(homedir(), ".claude", "skills", name, "SKILL.md"))
+      );
+    },
+    fix: () => "Run /content video-setup in Claude Code, or: npx skills add heygen-com/hyperframes --full-depth --yes",
+  },
+  {
+    name: "higgsfield-api-key",
+    description: "Higgsfield API key configured (image/video/audio generation engine)",
+    severity: "warn",
+    check: () => {
+      if (process.env.HIGGSFIELD_API_KEY) return true;
+      const keysPath = join(INSTALL_DIR, "keys.json");
+      if (!existsSync(keysPath)) return false;
+      try {
+        const keys = JSON.parse(readFileSync(keysPath, "utf-8"));
+        return !!keys.HIGGSFIELD_API_KEY;
+      } catch { return false; }
+    },
+    fix: () => "Run: npx arkaos keys set HIGGSFIELD_API_KEY <key> (https://higgsfield.ai) — needed for Higgsfield MCP generation",
+  },
 ];
 
 // ─── Windows-only checks ───────────────────────────────────────────────