OpenWriterControle/.opencode/context/content/copywriting-frameworks.md
Darren Hinde c8f7103cb6
refactor(evals): consolidate documentation and enhance test infrastructure (#56)
* feat(agents): implement category-based agent organization system

- Organize agents into domain categories (core, development, content, data, product, learning)
- Move 10 agents to category subdirectories with proper git rename tracking
- Update 13 subagents with category and type metadata in frontmatter
- Add category metadata files (0-category.json) documenting common patterns
- Implement local registry fallback in install script for offline development
- Add comprehensive validation suite with 15 automated tests (100% pass rate)
- Enhance registry validation with duplicate ID and consistency checks
- Update eval framework with intelligent path resolution (backward compatible)
- Archive legacy eval structure to _archive/ for reference
- Update all documentation to reflect category-based structure
- Bump version to 0.5.0 with accurate CHANGELOG

Technical Details:
- 23 agents organized (10 category agents, 13 subagents)
- 6 category directories created
- Path resolution supports both agent IDs and category paths
- Registry schema updated to v2.0.0
- 159 files changed, 872 insertions(+), 10738 deletions(-)

BREAKING CHANGE: Agent file paths now use category structure. Update references from .opencode/agent/openagent.md to .opencode/agent/core/openagent.md. Eval framework maintains backward compatibility via path resolution.

* refactor(evals): consolidate documentation and enhance test infrastructure

- Remove temporary project tracking files (PHASE_5_COMPLETE, PROJECT_COMPLETE, etc.)
- Consolidate evaluation framework docs into main README
- Enhance test execution with improved logging and multi-prompt support
- Move system-builder from core to meta category
- Add comprehensive test suites for openagent with organized structure
- Create evaluation test structure for all subagents
- Clean up archived workflows and redundant documentation
- Update registry to reflect new agent organization
- Add shared test templates and golden test patterns

* feat(ci): add manual trigger support for bot-created PRs in validate-registry workflow

- Add pr_number input to workflow_dispatch for manually triggering validation
- Fetch PR details dynamically when triggered manually
- Support both automatic (PR event) and manual (workflow_dispatch) triggers
- Enable validation of bot-created PRs like automated version bumps
- Update branch detection and push logic to handle both trigger types
- Add documentation explaining how to manually trigger for bot PRs

* feat(evals): add explicit context file validation to test framework

- Add expectedContextFiles field to test YAML schema for explicit context file specification
- Enhance context-loading-evaluator to support both auto-detect and explicit validation modes
- Update documentation with comprehensive guide and examples
- Clean up archived legacy test structure (90+ old test files)
- Add new example tests demonstrating explicit context validation
- Backward compatible with existing tests

* feat(evals): add multi-agent logging system and performance optimizations

Implement comprehensive multi-agent logging and performance improvements for the eval framework.

Task 01: Multi-Agent Logging System
- Add complete hierarchical logging module (evals/framework/src/logging/)
  - SessionTracker: tracks parent-child delegation hierarchies
  - MultiAgentLogger: pretty-prints logs with visual indentation
  - Formatters: box characters and emoji formatting
  - 37 passing unit tests (session-tracker, logger, integration)
- Integrate with SDK event stream handler
  - Hook into session.created, message.updated, message.part.updated events
  - Real-time child session detection via timestamp heuristics
  - Message deduplication for cleaner output
- Enable in debug mode only (<1% performance overhead)
- Add demo script and comprehensive documentation

Task 02: Performance Optimizations
- Reduce grace period from 5s to 2s (67% reduction, 10-20% faster tests)
- Add PerformanceMetricsEvaluator for bottleneck identification
  - Collects tool latencies, inference time, idle time
  - Provides full performance visibility
- Update smoke test to validate delegation (core feature)
  - Replace simple read test with multi-agent delegation test
  - Tests both parent and child agent functionality
  - Validates multi-agent logging system

Results:
- 37 unit tests passing
- Smoke test passing (95/100 score)
- Clean hierarchical logging output
- 10-20% faster test execution
- Full multi-agent visibility

Files changed: 16 files, +2678 lines
Time saved: ~6-8 days (completed in 6 hours vs 3-5 day estimate)

* feat(evals): show child agent execution in non-debug mode

- Enable MultiAgentLogger in both debug and non-debug modes
- Add verbose parameter to control output level
- Non-verbose mode shows concise child session lifecycle:
  - Child agent started message
  - Child agent completed with duration
- Verbose mode (--debug) shows full delegation hierarchy
- Update documentation to reflect new behavior

This provides visibility into delegation without overwhelming output,
giving confidence that child agents are actually running.

* feat(evals): improve delegation testing and behavior validation

Major improvements to eval framework:

Test Suite:
- Add 00-smoke-test.yaml (basic read operation)
- Rename 01-smoke-test.yaml → 02-delegation-test.yaml (delegation test)
- Add simple-responder test agent for delegation testing
- Add debug test: simple-subagent-call.yaml

Evaluators:
- Add agent-model-evaluator.ts for agent/model validation
- Enhance behavior-evaluator.ts with detailed task tool output
- Improve delegation-evaluator.ts with better evidence tracking

Schema & Execution:
- Add expectedAgent and expectedModel to test schema
- Improve test executor with better logging and error handling

Documentation:
- Update evals/README.md with new features and performance improvements
- Remove outdated MULTI_AGENT_LOGGING_COMPLETE.md

Registry:
- Add simple-responder test agent to registry

Fixes:
- Fix dashboard.sh path resolution

These changes provide better visibility into delegation, improved test
coverage, and clearer validation of agent behavior.

* chore: add GitHub Actions workflow and plugin documentation

- Add .github/workflows/evals/run-evaluations.yml for automated eval testing
- Add dev/ai-tools/opencode/plugins/Plugin-inspiration.md for plugin development reference
2025-12-18 09:52:11 +00:00

284 lines
6.7 KiB
Markdown

# Copywriting Frameworks
**Category**: content
**Purpose**: Proven copywriting frameworks and persuasive writing techniques
**Used by**: copywriter
---
## Overview
Effective copywriting follows proven frameworks that guide readers through awareness, interest, desire, and action. This guide covers the most effective frameworks for different contexts.
## Core Frameworks
### 1. AIDA (Attention, Interest, Desire, Action)
**Classic framework for persuasive copy**:
**Attention**: Grab attention with a compelling headline
```
"Stop Wasting Hours on Manual Data Entry"
```
**Interest**: Build interest with relevant benefits
```
"Our automation tool processes 1000 entries in minutes,
not hours. No coding required."
```
**Desire**: Create desire by showing transformation
```
"Join 10,000+ businesses that saved 20 hours per week
and reduced errors by 95%."
```
**Action**: Clear call-to-action
```
"Start Your Free 14-Day Trial - No Credit Card Required"
```
### 2. PAS (Problem, Agitate, Solve)
**Effective for pain-point driven copy**:
**Problem**: Identify the reader's problem
```
"Struggling to keep your team aligned on project deadlines?"
```
**Agitate**: Amplify the pain
```
"Missed deadlines lead to frustrated clients, lost revenue,
and team burnout. Every day without a solution costs you money."
```
**Solve**: Present your solution
```
"ProjectSync keeps everyone on the same page with real-time
updates, automated reminders, and visual timelines."
```
### 3. BAB (Before, After, Bridge)
**Show transformation clearly**:
**Before**: Current state (pain)
```
"You're spending 3 hours daily answering the same customer
questions via email."
```
**After**: Desired state (pleasure)
```
"Imagine having those 3 hours back to focus on growing your
business while customers get instant answers 24/7."
```
**Bridge**: How to get there
```
"Our AI chatbot learns from your knowledge base and handles
80% of customer inquiries automatically."
```
### 4. FAB (Features, Advantages, Benefits)
**Product-focused framework**:
**Features**: What it is
```
"Built-in analytics dashboard with real-time reporting"
```
**Advantages**: What it does
```
"Track campaign performance instantly without switching tools"
```
**Benefits**: What it means for them
```
"Make data-driven decisions faster and increase ROI by 30%"
```
### 5. The 4 Ps (Picture, Promise, Prove, Push)
**Storytelling approach**:
**Picture**: Paint a vivid picture
```
"Picture this: It's Monday morning. Instead of drowning in
emails, you're reviewing last week's wins with your team."
```
**Promise**: Make a clear promise
```
"We'll help you reclaim 10 hours per week by automating
your busywork."
```
**Prove**: Back it up with evidence
```
"Over 5,000 teams have saved an average of 12 hours weekly.
Here's what they say..."
```
**Push**: Call to action
```
"Join them today - start your free trial now."
```
## Headline Formulas
### 1. How-To Headlines
```
"How to [Achieve Desired Result] Without [Common Obstacle]"
"How to Double Your Sales in 30 Days Without Paid Ads"
```
### 2. Number Headlines
```
"[Number] Ways to [Achieve Result]"
"7 Proven Strategies to Boost Email Open Rates"
```
### 3. Question Headlines
```
"Are You Making These [Number] [Mistakes]?"
"Are You Making These 5 SEO Mistakes?"
```
### 4. Negative Headlines
```
"Stop [Doing Wrong Thing] and Start [Doing Right Thing]"
"Stop Guessing and Start Growing with Data-Driven Marketing"
```
### 5. Benefit-Driven Headlines
```
"[Achieve Result] in [Timeframe] with [Solution]"
"Launch Your Online Store in 24 Hours with Shopify"
```
## Emotional Triggers
### 1. Fear of Missing Out (FOMO)
```
"Limited spots available - only 10 left"
"Offer ends tonight at midnight"
"Join 50,000 early adopters"
```
### 2. Social Proof
```
"Trusted by Fortune 500 companies"
"4.9/5 stars from 10,000+ reviews"
"As featured in Forbes, TechCrunch, and Wired"
```
### 3. Authority
```
"Recommended by industry experts"
"Developed by former Google engineers"
"Award-winning customer support"
```
### 4. Reciprocity
```
"Free 30-day trial - no credit card required"
"Download our free guide"
"Get instant access to our resource library"
```
### 5. Scarcity
```
"Only 5 seats left for this cohort"
"Flash sale - 24 hours only"
"Limited edition - won't be restocked"
```
## Writing Techniques
### 1. Power Words
**Action words**:
- Discover, Unlock, Transform, Boost, Accelerate
- Proven, Guaranteed, Exclusive, Limited, Secret
**Emotional words**:
- Amazing, Incredible, Stunning, Revolutionary
- Effortless, Simple, Easy, Quick, Instant
### 2. Sensory Language
**Engage the senses**:
```
Instead of: "Good coffee"
Write: "Rich, aromatic coffee with notes of dark chocolate"
Instead of: "Fast software"
Write: "Lightning-fast software that responds instantly"
```
### 3. Specificity
**Be concrete, not vague**:
```
Vague: "Save money"
Specific: "Save $1,247 per year"
Vague: "Many customers"
Specific: "12,847 customers in 47 countries"
```
### 4. Active Voice
**Use active, not passive**:
```
Passive: "Your data is protected by encryption"
Active: "We encrypt your data with military-grade security"
```
## Best Practices
1. **Know your audience** - Write for one specific person
2. **Focus on benefits, not features** - What's in it for them?
3. **Use simple language** - Write at 8th-grade reading level
4. **Create urgency** - Give readers a reason to act now
5. **Tell stories** - Stories are memorable and persuasive
6. **Use social proof** - Testimonials, case studies, numbers
7. **Remove friction** - Make it easy to take action
8. **Test everything** - A/B test headlines, CTAs, copy
9. **Edit ruthlessly** - Cut unnecessary words
10. **Read it aloud** - Does it sound natural?
## Anti-Patterns
- ❌ **Jargon and buzzwords** - Confuses readers
- ❌ **Passive voice** - Weakens your message
- ❌ **Vague claims** - "Best in class" without proof
- ❌ **Too many CTAs** - Confuses and dilutes action
- ❌ **Focusing on features** - Readers care about benefits
- ❌ **Long paragraphs** - Hard to scan and read
- ❌ **No clear value proposition** - Why should they care?
- ❌ **Ignoring objections** - Address concerns proactively
## Copy Checklist
Before publishing, ask:
- [ ] Does the headline grab attention?
- [ ] Is the value proposition clear in 5 seconds?
- [ ] Are benefits emphasized over features?
- [ ] Is there social proof or credibility?
- [ ] Is there a clear, compelling CTA?
- [ ] Have I addressed objections?
- [ ] Is the copy scannable (headers, bullets, short paragraphs)?
- [ ] Does it pass the "so what?" test?
- [ ] Is it free of jargon and complex language?
- [ ] Have I created urgency or scarcity?
## References
- Breakthrough Advertising by Eugene Schwartz
- The Copywriter's Handbook by Robert Bly
- Influence by Robert Cialdini
- Made to Stick by Chip & Dan Heath