OpenWriterControle/.opencode/context/content-creation/formats/video-content.md
Darren Hinde 5a40b6fdc4
feat(context): Standardize context system with navigation, frontmatter, and MVI compliance (#209)
* feat: add OAC package refactor context file

- Add comprehensive feature context for OAC package refactor
- Document multi-IDE support architecture
- Define community component registry (shadcn-like)
- Outline flexible configuration system
- Detail context file location flexibility
- Define 7-phase implementation plan
- Include CLI commands reference
- Add community publishing guidelines

* docs: add OAC refactor quick start guide

- Add quick reference for Phase 1 implementation
- Include project structure and file locations
- Document configuration schema and defaults
- Add testing strategy and validation steps
- Include development workflow
- Reference all related resources

* feat: add critical user approval and context resolution systems

CRITICAL FEATURES ADDED:

1. User Approval & YOLO Mode
   - Default: Interactive approval for all file operations
   - Always asks: local vs global install
   - Confirms before overwriting files
   - Shows diffs and file details
   - YOLO mode (--yolo): Skip confirmations, auto-resolve, report at end
   - Conflict strategies: ask, skip, overwrite, backup, yolo
   - Safety: backups, git detection, rollback support, audit log

2. Context Resolution System
   - Layered context resolution (6 priority levels)
   - Project override (.oac/context/) - highest priority
   - Project context (.opencode/context/)
   - IDE context (.cursor/, .claude/)
   - Project docs (docs/)
   - User global (~/.config/oac/context/)
   - OAC official (~/.config/oac/official/) - lowest priority
   - Smart resolution based on agent location (global vs local)
   - preferLocal config option
   - Context merging strategies
   - CLI commands for context management
   - Environment variable overrides
   - Validation and fallback support

3. Enhanced CLI Commands
   - All commands support --yolo, --dry-run, --local, --global
   - Context management: resolve, list, validate, override, sync
   - Detailed help and examples
   - Global flags for all commands

This ensures users maintain full control over their projects while
supporting both local and global workflows with intelligent context
resolution.

* feat: add component creation wizard and IDE feature parity system

NEW FEATURES:

1. Interactive Component Creation
   - oac create (interactive wizard)
   - Create agents, skills, contexts, plugins, commands, tools
   - Template system for scaffolding
   - Auto-generate tests and boilerplate
   - Multi-IDE compatibility selection
   - Size optimization options

2. IDE Feature Parity & Capacity Management (CRITICAL)
   - Feature support matrix for all IDEs
   - OpenCode/Claude Code: Full support (all features)
   - Cursor: Limited (single file, no skills/plugins, 100KB limit)
   - Windsurf: Partial support
   - Adaptive installation based on IDE capabilities
   - Automatic feature filtering and warnings
   - Component merging for single-file IDEs (Cursor)
   - Capacity warnings and optimization
   - IDE-specific profiles

3. Enhanced CLI Commands
   - oac create [type] - Component creation wizard
   - oac templates - List available templates
   - oac compatibility <ide> - Check IDE compatibility
   - oac ides - List supported IDEs with features
   - oac ide info <ide> - Show IDE capabilities
   - oac optimize --for <ide> - Optimize for specific IDE
   - oac validate --ide <ide> - Validate IDE installation

4. Smart Installation
   - Detects IDE capabilities
   - Warns about unsupported features
   - Auto-filters components
   - Merges agents for Cursor
   - Embeds contexts for limited IDEs
   - Monitors file size limits
   - Suggests IDE-specific profiles

This ensures users can easily create components and OAC gracefully
handles different IDE capabilities with clear warnings and automatic
optimization.

* docs: add critical feedback from parallel agent review

CRITICAL FINDINGS:

Security Gaps (BLOCKER):
- No component signing or verification
- No malware/secret scanning
- No permission system
- Action: Add security layer in Phase 1

Missing Features (CRITICAL):
- Discovery (browse, search, trending)
- Lockfile for reproducibility
- Version conflict management
- Interactive onboarding
- Progress indicators
- Auto-detection for local/global

Approaches to Rethink:
- Context merging → Use composition instead
- Always asking local/global → Auto-detect with smart defaults
- Cursor agent merging → Router pattern instead

Repository Structure:
- Recommended: Monorepo with pnpm workspaces
- Packages: core, adapters, registry, security, cli
- Benefits: Shared deps, atomic commits, easier testing

Community Workflow:
- Component submission process
- Automated security scanning
- Manual review for verification
- Moderation system

Updated Priorities:
- v1.0 MVP: Add 6 critical features (discovery, lockfile, security, etc.)
- v1.1: Plugin system, workspace support, marketplace
- v2.0: Enterprise features

Documentation Needs:
- Quick Start (5-minute guide)
- CLI Reference (auto-generated)
- Recipes/Cookbook
- Component Creation Guide
- Migration Guide

Overall: Plan is 80% solid, needs 20% critical additions before Phase 1

* feat: add comprehensive agent customization and preset system

CRITICAL FEATURE: Agent Customization & Personal Presets

Problem:
- Users want to customize agent prompts for their workflow
- Users want to save personal configurations
- Updates shouldn't overwrite customizations
- Need easy way to view and edit agents

Solution: Multi-Layer Customization System

Layer 1: View Agent Configuration
- oac show agent:openagent (view in pager)
- oac edit agent:openagent (open in editor)
- oac config show agent:openagent (config only)
- oac export agent:openagent (export to file)

Layer 2: Create Personal Preset
- oac customize agent:openagent (create preset)
- Copies to ~/.config/oac/presets/agents/
- Links to base agent for updates
- Tracks customizations in metadata

Layer 3: Edit Personal Preset
- oac edit preset:my-openagent (edit in $EDITOR)
- oac customize preset:my-openagent --interactive (wizard)
- Auto-backup on save
- Track modification history

Layer 4: Use Personal Preset
- oac use preset:my-openagent (activate)
- oac use preset:my-openagent --global (set default)
- oac presets list --active (show active)
- Switch between presets and base agents

Layer 5: Update Management (CRITICAL)
- Smart update detection for base agents
- Merge strategies: manual, auto-base, auto-merge, locked
- Conflict resolution with user prompts
- Show diffs before merging
- Auto-backup before updates
- Preserve user customizations by default

Layer 6: Preset Sharing
- oac export preset:my-openagent (export)
- oac import preset ./preset.md (import)
- oac share preset:my-openagent (share with team)
- oac publish preset:my-openagent (publish to community)

Layer 7: In-Place Editing (Advanced)
- oac edit agent:openagent --in-place (risky, warns user)
- Creates backup before editing
- Warns that updates will overwrite
- Recommends preset creation instead

Update Strategies:
- manual: User reviews every update
- auto-base: Auto-update base, keep preset unchanged
- auto-merge: Auto-merge, prompt on conflicts
- locked: Never update base

Configuration:
- Preset metadata (.presets.json)
- Update strategies per preset
- Merge conflict resolution
- Backup management
- Warning preferences

Edge Cases Handled:
- In-place edits before updates
- Multiple updates behind
- Multiple presets for same base
- Preset conflicts with IDE
- Deleted base agent

Best Practices:
- Always create presets (safest)
- Document customizations
- Review updates before merging
- Keep backups
- Use descriptive names

This ensures users can safely customize agents without fear of
losing changes on updates, while still benefiting from base agent
improvements.

* docs: complete comprehensive user scenario analysis (16,014 lines)

PLANNING PHASE COMPLETE:

Documents Created (9 files, 400KB):
- 00-INDEX.md (388 lines) - Planning index and overview
- 01-main-plan.md (2,338 lines) - Complete feature specification
- 02-quickstart-guide.md (450 lines) - Phase 1 quick reference
- 03-critical-feedback.md (599 lines) - Parallel agent review
- 04-solo-developer-scenarios.md (2,106 lines) - Individual workflows
- 05-team-lead-scenarios.md (3,977 lines) - Team collaboration
- 07-content-creator-scenarios.md (2,581 lines) - Non-technical users
- 08-open-source-maintainer-scenarios.md (3,575 lines) - Community management
- 09-SYNTHESIS.md (1,000+ lines) - Consolidated findings

User Personas Analyzed (4/5):
✅ Solo Developer (Primary - 40% market)
✅ Team Lead (Secondary - 30% market)
✅ Content Creator (Emerging - 20% market)
✅ Open Source Maintainer (Future - 5% market)
⏸️ Enterprise Admin (Deferred to v2.0 - 5% market)

Key Findings:

Solo Developer (Primary User):
- Setup must be < 2 minutes or they skip
- Preview before committing (try mode)
- Safe customization (presets)
- Easy rollback/undo
- Zero docs reading to start

Team Lead (Secondary User):
- Lockfile is non-negotiable (oac.lock)
- Team configuration (oac-team.json)
- Compliance monitoring (90%+ required)
- Onboarding: 4-8 hours → 15 minutes (96% reduction)
- Staged rollouts for updates

Content Creator (Emerging - 20% market):
- CLI is intimidating (need GUI wrapper)
- Plain language mode (no jargon)
- Visual undo (version history)
- Templates and examples
- Guided setup

Open Source Maintainer (Future):
- Security scanning pipeline (ClamAV + gitleaks)
- Quality gates (70% test coverage)
- Review/approval workflow
- Deprecation workflow
- Sustainability model

Critical Additions to MVP:
1. Interactive onboarding wizard (all personas)
2. TUI browser with preview (solo dev, team lead)
3. Lockfile (oac.lock) (team lead)
4. Security scanning (all personas)
5. Try mode (solo dev)
6. Team configuration (team lead)
7. oac doctor health checks (solo dev)
8. Quality gates (maintainer)

Market Opportunity:
- v1.0: 70% market (solo + team)
- v1.1: 90% market (+ content creators with GUI)
- v2.0: 100% market (+ enterprise)

Recommended Changes:
- Expand MVP scope (+2 weeks, 9 weeks total)
- Plan v1.1 for content creators (GUI wrapper)
- Defer enterprise features to v2.0
- Build community features early (trust)

Status: Ready to finalize plan and start implementation
Confidence: Very High (95%+)
Risk: Low (comprehensive analysis complete)

* docs: add comprehensive final review of OAC planning

FINAL REVIEW COMPLETE:

Overall Assessment: CONDITIONAL GO ✅⚠️
Confidence Level: 85% (High, with conditions)
Success Probability: 75% (with modifications)

Key Strengths:
✅ Exceptional user research (16,000+ lines, 4 personas)
✅ Clear technical architecture (monorepo, TypeScript, Zod)
✅ Security-first mindset (signing, scanning, verification)
✅ Realistic scope management (v1.0 vs v1.1 vs v2.0)
✅ Comprehensive feature coverage

Critical Gaps Identified:
❌ Discovery/Onboarding not in Phase 1 (but P0 in scenarios)
❌ Lockfile not in Phase 2 (but critical for teams)
❌ Security Pipeline not detailed in phases
❌ Progress UI not in Phase 1 (but needed for UX)
❌ Auto-detection not in Phase 1 (but reduces friction)

Conditions for Go:
1. Add discovery/onboarding to Phase 1 (+3 days)
2. Add lockfile to Phase 2 (+2 days)
3. Add security pipeline to Phase 1 (+2 days)
4. Add progress UI to Phase 1 (+1 day)
5. Revise timeline: 7 weeks → 9 weeks

Critical Action Items (6 days before Phase 1):
1. Add missing features to phases (2 days)
2. Define acceptance criteria (1 day)
3. Define testing strategy (1 day)
4. Design security pipeline (1 day)
5. Create monorepo structure (1 day)

Top Risks:
🔴 Timeline Slip (70% probability, high impact)
🟡 Scope Creep (50% probability, high impact)
🟡 Context Merging Complexity (60% probability, medium impact)

Recommendation: PROCEED WITH MODIFICATIONS
- Complete 6 days of prerequisite work
- Extend timeline to 9 weeks
- Add missing features to phases
- Define acceptance criteria and testing strategy

Status: READY TO IMPLEMENT (with modifications)
Next Steps: Complete prerequisites → Setup monorepo → Start Phase 1

* feat(context): Standardize context system with navigation, frontmatter, and MVI compliance

- Add 77 navigation.md files across all context categories for token-efficient discovery
- Standardize frontmatter format on 198+ context files (HTML comment format, 2026-02-15)
- Compress 3 oversized guide files applying MVI principle (802 lines removed, 63% reduction)
- Add context system analysis and planning artifacts in context-findings/
- Add task management enhancements (stage orchestration, planning subagents)
- Document compression techniques and future optimization recommendations

Context System Improvements:
- All active directories now have navigation.md (200-300 tokens each)
- 100% frontmatter compliance with priority/version/date metadata
- Improved scannability through MVI compression (compact.md, organizing-context.md, creation.md)
- Token efficiency increased for AI agent consumption

Planning & Analysis:
- Context system implementation plan and simplification analysis
- ADR standard proposal and runtime permission architecture
- SQLite context design for future scale (deferred until 500+ files)
- Context discovery script analysis (rejected in favor of navigation-first)

Task Management:
- Enhanced task schema with stage orchestration support
- New planning subagents (ADR, Architecture, Story Mapping, Prioritization)
- Stage orchestrator for multi-stage workflow management
- Session context management and lightweight handoff patterns

Closes: context-simple-fixes task
Ref: context-system-implementation analysis

* fix: resolve markdown link validation errors in navigation files

- Remove non-existent react-patterns.md link from react/navigation.md
- Remove non-existent premium-dark-ui-quick-start.md link from design/navigation.md
- Add skip patterns for pre-existing broken links in example/template files
- Validation now passes: 215 files validated, 0 errors

* fix: resolve all 119 broken markdown links across documentation

- Update agent paths to new subagents structure (TestEngineer, ContextScout, etc.)
- Fix animation file references (animation-ui.md → animation-components.md)
- Update guide references (adding-agent.md → adding-agent-basics.md)
- Convert non-existent example paths to placeholder text format
- Add skip patterns for intentional example placeholders
- Validation now passes: 232 files validated, 0 errors

Co-authored-by: CoderAgent <coder@openagents.dev>

---------

Co-authored-by: CoderAgent <coder@openagents.dev>
2026-02-15 23:01:19 +00:00

9.3 KiB

Video Content Guidelines

Best practices for creating engaging video content across platforms: YouTube, TikTok, Instagram Reels, and video ads.


Video Script Structure

Standard Video Flow

1. Hook (First 3 seconds)

  • Visual hook (movement, text, face)
  • Verbal hook (compelling statement)
  • Pattern interrupt (unexpected element)

2. Promise (3-10 seconds)

  • What they'll learn/get
  • Why it matters
  • Build anticipation

3. Content Delivery (Main Body)

  • Deliver on the promise
  • Keep pace moving
  • Use visual variety

4. Call-to-Action (Last 5-10 seconds)

  • Clear next step
  • Like, comment, subscribe
  • Link to related content

Hook and Retention Strategies

First 3 Seconds Are Critical

Visual Hooks:

  • Fast movement or action
  • Text overlay with bold claim
  • Close-up of face (emotion)
  • Unexpected visual
  • Before/after comparison

Verbal Hooks:

  • Surprising statement
  • Bold claim
  • Question that resonates
  • Tease the payoff
  • Personal story opening

Pattern Interrupts:

  • Sudden sound effect
  • Jump cut
  • Visual effect
  • Unexpected statement
  • Format change

Retention Techniques Throughout

Pacing:

  • Cut dead air ruthlessly
  • Change camera angle every 3-5 seconds
  • Vary shot types (close-up, medium, wide)
  • Use B-roll to illustrate points

Open Loops:

  • Promise information later
  • "More on that in a minute..."
  • "Wait until you see what happens next..."
  • Build anticipation

Visual Variety:

  • Text overlays for key points
  • Graphics and animations
  • B-roll footage
  • Screen recordings
  • Multiple camera angles

Verbal Engagement:

  • Direct address ("You might be thinking...")
  • Questions to audience
  • Acknowledge objections
  • Personal asides
  • Humor and personality

Platform-Specific Guidelines

YouTube

Video Length:

  • Short-form (< 60 seconds): Quick tips, teasers
  • Mid-form (3-8 minutes): Tutorials, how-tos
  • Long-form (10-20+ minutes): Deep dives, vlogs

Structure:

  • Hook (0-3 seconds)
  • Intro/Promise (3-15 seconds)
  • Content (main body)
  • Recap (optional)
  • CTA (end screen)

Optimization:

  • Thumbnail: High contrast, clear text, expressive face
  • Title: Keyword-rich, compelling, 60 characters
  • Description: First 2 lines visible, include keywords
  • Tags: Relevant keywords and phrases
  • End screen: Subscribe + related videos

Best Practices:

  • First 30 seconds determine retention
  • Pattern interrupt every 30-60 seconds
  • Use chapters for longer videos
  • Pin comment to drive engagement
  • Respond to comments quickly

TikTok

Video Length:

  • Optimal: 15-30 seconds
  • Can go up to 10 minutes
  • Shorter often performs better

Structure:

  • Hook (first frame + first second)
  • Quick delivery (no fluff)
  • Payoff/punchline
  • Loop-friendly ending (optional)

Optimization:

  • Captions: Auto-captions or manual
  • Sounds: Trending audio increases reach
  • Hashtags: Mix trending + niche (3-5 total)
  • Text overlay: Key points, emphasis
  • Posting time: Test your audience

Best Practices:

  • Vertical format (9:16)
  • Fast-paced editing
  • Trend participation
  • Authentic, raw feel
  • Strong first frame (thumbnail)
  • Loop-friendly for rewatches

Instagram Reels

Video Length:

  • Optimal: 7-15 seconds
  • Can go up to 90 seconds
  • Shorter often performs better

Structure:

  • Hook (first frame)
  • Quick value delivery
  • Clear payoff
  • CTA in caption

Optimization:

  • Cover image: Choose compelling frame
  • Caption: Hook in first line
  • Hashtags: 3-5 relevant
  • Audio: Trending or original
  • Location tag: Increases reach

Best Practices:

  • Vertical format (9:16)
  • Text overlays for sound-off viewing
  • Trending audio when relevant
  • High-quality visuals
  • Consistent posting schedule
  • Engage with comments quickly

YouTube Shorts

Video Length:

  • Maximum: 60 seconds
  • Optimal: 15-30 seconds

Structure:

  • Immediate hook
  • Fast-paced content
  • Clear payoff
  • Loop-friendly

Optimization:

  • Vertical format (9:16)
  • #Shorts in title or description
  • Compelling first frame
  • Text overlays
  • Trending topics

Best Practices:

  • Repurpose TikTok/Reels content
  • Fast cuts and pacing
  • Clear, simple message
  • Strong visual hook
  • No watermarks from other platforms

Video Content Ideas by Platform

YouTube Ideas

Educational:

  • How-to tutorials
  • Explainer videos
  • Course-style series
  • Tool reviews
  • Case studies

Entertainment:

  • Vlogs
  • Challenges
  • Reactions
  • Storytelling
  • Behind-the-scenes

Hybrid:

  • "Day in the life" with lessons
  • Q&A with teaching moments
  • Mistakes and lessons learned

Short-Form Ideas (TikTok/Reels/Shorts)

Quick Tips:

  • One tip per video
  • Before/after demonstrations
  • Common mistakes
  • Quick wins

Trends:

  • Trending audio with your twist
  • Challenge participation
  • Duets and stitches
  • Trending formats

Storytelling:

  • Quick personal stories
  • Client success stories
  • Failure stories with lessons
  • "Things I wish I knew"

List Format:

  • "3 ways to..."
  • "5 signs that..."
  • "Top mistakes in..."
  • Countdown format

Thumbnail and Title Optimization

Thumbnail Best Practices

Visual Elements:

  • High contrast colors
  • Clear, readable text (3-5 words max)
  • Expressive face (if applicable)
  • Bright, well-lit
  • Consistent branding

Text on Thumbnail:

  • Large, bold font
  • High contrast with background
  • Complement title (don't repeat)
  • Create curiosity

Composition:

  • Rule of thirds
  • Clear focal point
  • Not cluttered
  • Recognizable at small size

Title Formulas

How-To:

  • "How to [Result] in [Timeframe]"
  • "How to [Result] Without [Common Obstacle]"
  • "How I [Achieved Result]"

List:

  • "[Number] Ways to [Result]"
  • "[Number] [Things] That [Result]"
  • "I Tried [Number] [Things]. Here's What Worked."

Curiosity:

  • "The [Thing] Nobody Tells You About [Topic]"
  • "Why [Common Belief] Is Wrong"
  • "What [Event] Taught Me About [Topic]"

Result-Focused:

  • "[Result] in [Timeframe]: Full Guide"
  • "From [Starting Point] to [End Point]"
  • "[Result] Without [Expected Requirement]"

Call-to-Action Placement

When to Include CTAs

Early CTA (First 30 seconds):

  • "If you're new here, subscribe for..."
  • "Drop a comment if you've experienced..."
  • Sets expectation for engagement

Mid-Roll CTA:

  • "If you're finding this helpful, hit like"
  • "Comment below with your thoughts"
  • Natural break in content

End CTA:

  • "Subscribe for more content like this"
  • "Check out this related video"
  • "Link in description for..."

CTA Best Practices

Be Specific: ❌ "Let me know what you think" ✅ "Comment 'YES' if you want more content like this"

Give a Reason: ❌ "Subscribe to my channel" ✅ "Subscribe so you don't miss the next video in this series"

Make it Easy: ❌ "Check out all my links" ✅ "Link in bio for the free template"


Video Series Planning

Series Formats

Educational Series:

  • Multi-part tutorial
  • Course-style progression
  • Topic deep-dives
  • Tool mastery series

Recurring Content:

  • Weekly tips
  • Monthly reviews
  • Q&A sessions
  • Behind-the-scenes

Challenge Series:

  • 30-day challenge
  • Experiment documentation
  • Transformation journey

Series Benefits

Audience Retention:

  • Viewers return for next episode
  • Builds anticipation
  • Creates habit

Content Planning:

  • Easier to batch create
  • Consistent posting schedule
  • Clear content calendar

Authority Building:

  • Demonstrates expertise depth
  • Comprehensive coverage
  • Positions as go-to resource

Video Production Checklist

Pre-Production

  • Script or outline prepared
  • Hook and CTA planned
  • Location and lighting checked
  • Equipment ready (camera, mic, lights)
  • B-roll list (if needed)

Production

  • Strong hook in first 3 seconds
  • Clear audio (no background noise)
  • Good lighting (face well-lit)
  • Stable footage (tripod or stabilization)
  • Multiple takes of key sections

Post-Production

  • Tight editing (cut dead air)
  • Text overlays for key points
  • B-roll inserted where relevant
  • Music/sound effects (if appropriate)
  • Color correction (if needed)
  • Captions/subtitles added

Publishing

  • Compelling thumbnail created
  • Optimized title (keywords + curiosity)
  • Description with keywords and links
  • Relevant tags/hashtags
  • End screen/cards added (YouTube)
  • Scheduled for optimal time

Common Video Content Mistakes

❌ Slow Start

Taking 10+ seconds to get to the point.

✅ Immediate Hook

Value or intrigue in first 3 seconds.


❌ Talking Head Only

Static shot with no visual variety.

✅ Visual Variety

B-roll, text overlays, multiple angles.


❌ Poor Audio

Background noise, echo, inconsistent levels.

✅ Clean Audio

Clear voice, minimal background noise, consistent levels.


❌ No Clear CTA

Video ends without telling viewers what to do.

✅ Clear Next Step

Specific action for viewers to take.


Usage

Apply these guidelines when creating:

  • YouTube videos (short and long-form)
  • TikTok content
  • Instagram Reels
  • YouTube Shorts
  • Video ads
  • Course content
  • Social media video

Remember: The first 3 seconds determine if someone watches. The first 30 seconds determine if they stay. Optimize ruthlessly for both.