@mytechtoday/augment-extensions 0.4.0 → 0.5.0

package/augment-extensions/writing-standards/screenplay/styles/rules/voice-over.md

@@ -0,0 +1,500 @@
+# Voice-Over Driven Narrative Style
+
+**Category**: Screenplay Narrative Style  
+**Type**: Technical/Tonal  
+**Complexity**: Medium-High
+
+## Overview
+
+Voice-over driven narrative uses narration as a primary storytelling device, with the narrator's voice providing context, commentary, insight, or counterpoint to visual action. This style creates intimate connection with narrator while allowing complex temporal and psychological storytelling.
+
+## Core Concept
+
+Voice-over screenwriting uses the human voice as a narrative instrument, creating direct communication between narrator and audience. The power lies in the unique intimacy of voice, the ability to access internal thoughts, and the capacity to bridge time and space. Success requires finding the right voice, balancing narration with visual storytelling, and ensuring voice-over enhances rather than replaces cinematic storytelling.
+
+## Definition
+
+A voice-over driven narrative uses narration as a primary storytelling element, with a character's or narrator's voice providing essential context, commentary, or insight that shapes how the audience experiences the visual narrative.
+
+## Structural Requirements
+
+### Requirement 1: Distinctive Voice
+
+**Description**: Narrator must have unique, compelling voice with personality and perspective.
+
+**Why It Matters**: Voice-over lives or dies on the quality and distinctiveness of the voice.
+
+**Implementation**:
+- Create specific vocal personality
+- Establish clear perspective and attitude
+- Develop consistent tone
+- Make voice memorable
+
+**Examples**:
+- ✅ **Good**: Cynical detective with world-weary wit (Sunset Boulevard)
+- ❌ **Bad**: Generic, personality-free narration
+
+**Film Reference**: A Clockwork Orange (1971) - Alex's distinctive slang-filled narration.
+
+---
+
+### Requirement 2: Visual-Verbal Relationship
+
+**Description**: Voice-over must have purposeful relationship to visuals—complement, contradict, or expand.
+
+**Why It Matters**: Voice-over should enhance cinema, not replace it.
+
+**Implementation**:
+- Avoid describing what we see
+- Use voice-over for what visuals can't show
+- Create ironic counterpoint when effective
+- Complement visuals with context
+
+**Examples**:
+- ✅ **Good**: Narrator describes inner thoughts while visuals show contradictory actions
+- ❌ **Bad**: "I walked into the room" while showing character walking into room
+
+**Film Reference**: Goodfellas (1990) - Voice-over provides context visuals can't convey.
+
+---
+
+### Requirement 3: Temporal Flexibility
+
+**Description**: Voice-over enables fluid movement through time and perspective.
+
+**Why It Matters**: Narration can bridge time periods and provide retrospective insight.
+
+**Implementation**:
+- Use voice-over to jump through time
+- Provide retrospective commentary
+- Connect disparate time periods
+- Create temporal layers
+
+**Examples**:
+- ✅ **Good**: Older narrator reflecting on past events we're watching
+- ❌ **Bad**: Voice-over locked to present moment only
+
+**Film Reference**: The Shawshank Redemption (1994) - Red's narration spans decades.
+
+---
+
+### Requirement 4: Internal Access
+
+**Description**: Voice-over provides access to narrator's thoughts, feelings, and perspective.
+
+**Why It Matters**: Narration can reveal what visuals and dialogue cannot.
+
+**Implementation**:
+- Share internal monologue
+- Reveal hidden motivations
+- Express unspoken thoughts
+- Provide psychological insight
+
+**Examples**:
+- ✅ **Good**: Narrator reveals thoughts they'd never speak aloud
+- ❌ **Bad**: Voice-over only states obvious external facts
+
+**Film Reference**: Taxi Driver (1976) - Travis's disturbed internal monologue.
+
+---
+
+### Requirement 5: Narrative Purpose
+
+**Description**: Voice-over must serve clear narrative function beyond convenience.
+
+**Why It Matters**: Lazy voice-over becomes crutch for weak visual storytelling.
+
+**Implementation**:
+- Justify voice-over's existence
+- Ensure it serves story needs
+- Avoid using as exposition dump
+- Make narration essential
+
+**Examples**:
+- ✅ **Good**: Voice-over provides unique perspective impossible to show
+- ❌ **Bad**: Voice-over explains plot because visuals are unclear
+
+**Film Reference**: Fight Club (1999) - Narrator's voice essential to unreliable narrative.
+
+---
+
+### Requirement 6: Tonal Consistency
+
+**Description**: Voice-over tone must remain consistent or evolve purposefully.
+
+**Why It Matters**: Inconsistent narration breaks audience connection.
+
+**Implementation**:
+- Establish clear tonal baseline
+- Maintain consistent voice
+- Evolve tone only with purpose
+- Match voice to story needs
+
+**Examples**:
+- ✅ **Good**: Cynical noir voice maintained throughout
+- ❌ **Bad**: Tone shifts randomly between scenes
+
+**Film Reference**: The Big Lebowski (1998) - The Stranger's folksy tone consistent throughout.
+
+---
+
+## Pacing Guidelines
+
+### Overall Rhythm
+
+- Voice-over creates rhythmic punctuation
+- Balance narration with silence
+- Use voice-over to control pacing
+- Create rhythm through narration patterns
+
+### Scene Length
+
+- Voice-over can compress or expand time
+- Narration allows quick scene transitions
+- Montages with voice-over bridge time
+- Flexible scene length
+
+### Act Structure
+
+- Voice-over can mark act transitions
+- Narration provides structural signposts
+- Retrospective framing device
+- Flexible structure
+
+### Transitions
+
+- Voice-over bridges scenes smoothly
+- Narration connects disparate moments
+- Temporal jumps via voice-over
+- Seamless transitions
+
+## Visual Storytelling
+
+### Camera Work
+
+- Visuals must work with narration
+- Show what voice-over doesn't say
+- Create visual-verbal counterpoint
+- Cinematic storytelling maintained
+
+### Visual Motifs
+
+- Visual elements complement narration
+- Recurring images with voice-over
+- Symbolic visuals with commentary
+- Layered meaning
+
+### Action Lines
+
+- Describe visuals clearly
+- Note voice-over placement
+- Balance description with narration
+- Visual storytelling priority
+
+**Example**:
+```
+INT. DINER - NIGHT
+
+Jake sits alone, coffee growing cold.
+
+JAKE (V.O.)
+I'd been waiting three hours. She wasn't coming. I knew that. But I kept waiting anyway.
+
+He stares at the door. Doesn't touch his coffee.
+```
+
+## Dialogue Approach
+
+### Dialogue Style
+
+- Balance voice-over with spoken dialogue
+- Narration and dialogue serve different functions
+- Voice-over more literary, dialogue more natural
+- Distinct voices for narration vs. speech
+
+### Subtext
+
+- Voice-over can reveal subtext
+- Or create ironic distance from dialogue
+- Narration exposes what's unspoken
+- Layered meaning
+
+### Formatting
+
+- V.O. (voice-over) for narration
+- Clear distinction from dialogue
+- Placement indicates timing
+- Standard formatting
+
+**Example**:
+```
+SARAH
+Everything's fine.
+
+SARAH (V.O.)
+Nothing was fine. Everything was falling apart.
+
+She forces a smile.
+```
+
+## Technical Formatting
+
+### Page Layout
+
+- Standard screenplay format
+- V.O. clearly marked
+- Voice-over placement clear
+- Balance narration with action
+
+### Scene Headings
+
+- Standard headings
+- Voice-over doesn't replace scene setting
+- Clear visual locations
+- Temporal markers when needed
+
+### Special Elements
+
+- MONTAGE with voice-over
+- SERIES OF SHOTS with narration
+- FLASHBACK with voice-over framing
+- Clear technical notation
+
+## Strengths and Limitations
+
+### Strengths
+
+- Intimate connection with narrator
+- Access to internal thoughts
+- Temporal flexibility
+- Complex storytelling enabled
+- Unique perspective
+- Literary quality
+
+### Limitations
+
+- Risk of over-reliance on narration
+- Can replace visual storytelling
+- May feel dated or literary
+- Requires strong writing
+- Can become exposition dump
+- Passive storytelling risk
+
+### Best Use Cases
+
+- Noir and detective stories
+- Memoir and biographical films
+- Complex temporal narratives
+- Character studies
+- Literary adaptations
+- Retrospective narratives
+
+## Film Examples
+
+### Example 1: Sunset Boulevard (1950)
+
+**Director**: Billy Wilder
+
+**Why This Style Works**: Dead narrator provides ironic, cynical voice-over creating noir masterpiece.
+
+**Key Stylistic Moments**:
+- **Opening**: Dead man narrates his own death
+- **Cynical Commentary**: World-weary Hollywood observations
+- **Retrospective Irony**: Knowing the ending colors everything
+
+**Techniques Used**:
+- Dead narrator (ultimate retrospective)
+- Cynical, witty voice
+- Ironic counterpoint to visuals
+- Noir voice-over perfected
+
+**Structural Analysis**: Voice-over frames entire narrative as flashback from death.
+
+---
+
+### Example 2: Goodfellas (1990)
+
+**Director**: Martin Scorsese
+
+**Why This Style Works**: Henry and Karen's voice-overs provide insider perspective on mob life.
+
+**Key Stylistic Moments**:
+- **"As far back as I can remember..."**: Iconic opening
+- **Dual Narrators**: Henry and Karen's perspectives
+- **Insider Knowledge**: Voice-over provides context visuals can't
+
+**Techniques Used**:
+- Multiple narrators
+- Insider perspective
+- Temporal compression via voice-over
+- Voice-over as storytelling engine
+
+**Structural Analysis**: Voice-over enables decades-spanning narrative with intimate detail.
+
+---
+
+### Example 3: The Shawshank Redemption (1994)
+
+**Director**: Frank Darabont
+
+**Why This Style Works**: Red's voice-over provides warmth, wisdom, and emotional anchor.
+
+**Key Stylistic Moments**:
+- **"I must admit..."**: Red's reflective observations
+- **Hope Theme**: Voice-over articulates central theme
+- **Temporal Bridges**: Narration spans decades
+
+**Techniques Used**:
+- Warm, reflective voice
+- Thematic commentary
+- Temporal flexibility
+- Emotional anchor
+
+**Structural Analysis**: Voice-over provides continuity across decades and emotional center.
+
+---
+
+### Example 4**: A Clockwork Orange (1971)
+
+**Director**: Stanley Kubrick
+
+**Why This Style Works**: Alex's distinctive slang-filled narration creates unique linguistic world.
+
+**Key Stylistic Moments**:
+- **Nadsat Slang**: Invented language in narration
+- **Unreliable Narrator**: Alex's perspective questionable
+- **Direct Address**: Intimate connection with audience
+
+**Techniques Used**:
+- Distinctive linguistic style
+- Unreliable narration
+- Direct audience address
+- Voice as character
+
+**Structural Analysis**: Voice-over creates linguistic and psychological world.
+
+---
+
+### Example 5: Fight Club (1999)
+
+**Director**: David Fincher
+
+**Why This Style Works**: Narrator's voice-over essential to unreliable narrative and twist.
+
+**Key Stylistic Moments**:
+- **Insomniac Rambling**: Stream-of-consciousness style
+- **Unreliable Narration**: Voice-over misleads deliberately
+- **Direct Address**: Breaking fourth wall
+
+**Techniques Used**:
+- Unreliable narrator
+- Stream-of-consciousness
+- Voice-over as misdirection
+- Essential to twist
+
+**Structural Analysis**: Voice-over enables unreliable narrative essential to story.
+
+---
+
+## Integration with Other Features
+
+### Compatible Genres
+
+- **Noir**: Classic voice-over territory
+- **Crime**: Insider perspective valuable
+- **Drama**: Internal access deepens emotion
+- **Comedy**: Comedic narration (The Big Lebowski)
+- **Thriller**: Unreliable narrators create suspense
+
+### Compatible Themes
+
+- **Memory**: Retrospective narration natural
+- **Identity**: Internal voice explores self
+- **Morality**: Narrator can provide moral commentary
+- **Time**: Voice-over bridges temporal gaps
+- **Perspective**: Narration provides unique viewpoint
+
+### Style Variations
+
+- **Noir voice-over**: Cynical, world-weary (Sunset Boulevard)
+- **Memoir voice-over**: Reflective, nostalgic (Shawshank)
+- **Unreliable voice-over**: Misleading narration (Fight Club)
+- **Comic voice-over**: Humorous narration (The Big Lebowski)
+
+## Common Pitfalls
+
+### Pitfall 1: Describing What We See
+
+**Problem**: Voice-over narrates obvious visual information.
+
+**Solution**: Use voice-over only for what visuals can't convey.
+
+**Example**: Goodfellas uses voice-over for context and insider knowledge, not description.
+
+---
+
+### Pitfall 2: Exposition Dump
+
+**Problem**: Voice-over becomes lazy way to deliver backstory and information.
+
+**Solution**: Integrate exposition naturally. Show when possible, tell only when necessary.
+
+**Example**: Shawshank integrates exposition into Red's natural reflections.
+
+---
+
+### Pitfall 3: Replacing Visual Storytelling
+
+**Problem**: Over-reliance on narration instead of showing through action.
+
+**Solution**: Balance voice-over with strong visual storytelling.
+
+**Example**: Sunset Boulevard maintains strong visual storytelling despite heavy narration.
+
+---
+
+### Pitfall 4: Inconsistent Voice
+
+**Problem**: Narrator's tone, style, or perspective shifts randomly.
+
+**Solution**: Maintain consistent voice or evolve it purposefully.
+
+**Example**: A Clockwork Orange maintains Alex's distinctive voice throughout.
+
+---
+
+### Pitfall 5: Unnecessary Narration
+
+**Problem**: Using voice-over when story doesn't require it.
+
+**Solution**: Ensure voice-over serves essential narrative function.
+
+**Example**: Fight Club's voice-over is essential to unreliable narrative structure.
+
+---
+
+## Best Practices
+
+1. **Create distinctive voice** - Make narrator memorable and unique
+2. **Avoid describing visuals** - Use voice-over for what we can't see
+3. **Establish clear purpose** - Know why story needs narration
+4. **Balance with visuals** - Don't replace cinematic storytelling
+5. **Maintain consistency** - Keep voice consistent or evolve purposefully
+6. **Use for internal access** - Reveal thoughts and feelings
+7. **Create temporal flexibility** - Bridge time periods effectively
+8. **Write well** - Voice-over requires strong writing
+
+## Resources
+
+- "Voice-Over Narration in Film" by Sarah Kozloff - Comprehensive study
+- "Sunset Boulevard" screenplay by Billy Wilder and Charles Brackett - Noir voice-over master class
+- "Goodfellas" screenplay by Nicholas Pileggi and Martin Scorsese - Multiple narrators
+- "The Shawshank Redemption" screenplay by Frank Darabont - Warm, reflective voice-over
+- "Fight Club" screenplay by Jim Uhls - Unreliable narrator
+
+---
+
+**Depth Coverage**: 85%
+**Last Updated**: 2026-01-31
+**Version**: 1.0.0
+

package/augment-extensions/writing-standards/screenplay/themes/README.md

@@ -0,0 +1,158 @@
+# Screenplay Themes Module
+
+**Version**: 1.0.0  
+**Type**: Writing Standards  
+**Category**: Screenplay
+
+## Overview
+
+This module provides comprehensive thematic integration rules and guidelines for screenplay writing across 15+ universal themes. Each theme includes core concepts, integration strategies across acts, character connection techniques, and real-world film examples.
+
+## Key Features
+
+- **15+ Universal Themes**: Redemption, Love, Revenge, Identity, Power, Survival, Friendship, Betrayal, Growth, Isolation, Justice, Ambition, Fate, Technology, Environment
+- **Integration Guidelines**: How to weave themes throughout your screenplay
+- **85% Depth Coverage**: Each theme documented with 5-8 core rules and integration strategies
+- **Film Examples**: 3-5 real film examples per theme with specific thematic moments
+- **Modular Activation**: Select only the themes you need
+
+## Installation
+
+### With CLI (Recommended)
+```bash
+augx link writing-standards/screenplay/themes
+```
+
+### Manual Setup
+1. Copy `augment-extensions/writing-standards/screenplay/themes/` to your project
+2. Reference theme files in your `.augment/` configuration
+3. Configure active themes in `.augment/screenplay-config.json`
+
+## Configuration
+
+Create or update `.augment/screenplay-config.json`:
+
+```json
+{
+  "screenplay_enhancements": {
+    "enabled": true,
+    "features": {
+      "themes": {
+        "enabled": true,
+        "selected": ["redemption", "identity", "power"]
+      }
+    }
+  }
+}
+```
+
+## Directory Structure
+
+```
+themes/
+├── module.json           # Module metadata
+├── README.md             # This file
+├── rules/                # Theme-specific integration rules
+│   ├── redemption.md
+│   ├── love.md
+│   ├── revenge.md
+│   ├── identity.md
+│   ├── power.md
+│   ├── survival.md
+│   ├── friendship.md
+│   ├── betrayal.md
+│   ├── growth.md
+│   ├── isolation.md
+│   ├── justice.md
+│   ├── ambition.md
+│   ├── fate.md
+│   ├── technology.md
+│   └── environment.md
+└── examples/
+    └── theme-integrations.md
+```
+
+## Usage
+
+### Selecting Themes
+
+When developing a screenplay, select the primary theme(s) that apply:
+
+```json
+{
+  "themes": {
+    "selected": ["redemption", "betrayal"]
+  }
+}
+```
+
+### Applying Theme Rules
+
+AI agents will automatically apply the selected theme rules when:
+- Developing character arcs
+- Structuring plot points
+- Writing dialogue with subtext
+- Creating thematic payoffs
+
+### Multiple Themes
+
+Most screenplays explore multiple themes. Select all relevant themes:
+
+```json
+{
+  "themes": {
+    "selected": ["love", "sacrifice", "identity"]
+  }
+}
+```
+
+The module will help ensure thematic consistency and integration across all selected themes.
+
+## Theme Coverage
+
+### Core Themes (15)
+- **Redemption**: Character seeks to atone for past mistakes
+- **Love**: Romantic, familial, or platonic connection
+- **Revenge**: Character driven by desire for retribution
+- **Identity**: Character discovers or questions who they are
+- **Power**: Struggle for control, authority, or influence
+- **Survival**: Physical or emotional fight to endure
+- **Friendship**: Bonds formed through shared experience
+- **Betrayal**: Trust broken, loyalty tested
+- **Growth**: Character transformation and maturation
+- **Isolation**: Physical or emotional separation
+- **Justice**: Quest for fairness and moral balance
+- **Ambition**: Drive to achieve goals at any cost
+- **Fate**: Destiny vs. free will
+- **Technology**: Impact of technological advancement
+- **Environment**: Ecological concerns and nature's role
+
+## Character Count
+
+**Total**: ~TBD characters (will be calculated after content creation)
+
+## Contents
+
+- `rules/redemption.md` - Redemption theme integration and examples
+- `rules/love.md` - Love theme integration and examples
+- `rules/revenge.md` - Revenge theme integration and examples
+- `rules/identity.md` - Identity theme integration and examples
+- `rules/power.md` - Power theme integration and examples
+- `rules/survival.md` - Survival theme integration and examples
+- `rules/friendship.md` - Friendship theme integration and examples
+- `rules/betrayal.md` - Betrayal theme integration and examples
+- `rules/growth.md` - Growth theme integration and examples
+- `rules/isolation.md` - Isolation theme integration and examples
+- `rules/justice.md` - Justice theme integration and examples
+- `rules/ambition.md` - Ambition theme integration and examples
+- `rules/fate.md` - Fate theme integration and examples
+- `rules/technology.md` - Technology's Impact theme integration and examples
+- `rules/environment.md` - Environmental Concerns theme integration and examples
+- `examples/theme-integrations.md` - Complete theme integration examples
+
+## Related Modules
+
+- `writing-standards/screenplay/genres` - Genre-specific conventions
+- `writing-standards/screenplay/styles` - Narrative style guidelines
+- `writing-standards/screenplay` - Core screenplay standards
+

package/augment-extensions/writing-standards/screenplay/themes/examples/.gitkeep

@@ -0,0 +1,2 @@
+# Placeholder for themes/examples directory
+