From ab8f412c3cdd30c075b5748752b11a4eaec82730 Mon Sep 17 00:00:00 2001 From: Fredrik Sandberg Date: Sat, 21 Feb 2026 16:28:29 +0100 Subject: [PATCH] add Novel Writing Suite (nws) module Six agents (Librarian, Sage, Atlas, Muse, Scribe, Editor), five workflows, knowledge base, and docs for AI-assisted novel writing. Co-Authored-By: Claude Sonnet 4.6 --- src/modules/nws/agents/atlas.agent.yaml | 81 ++++ src/modules/nws/agents/editor.agent.yaml | 108 +++++ .../agents/librarian-sidecar/instructions.md | 198 +++++++++ .../knowledge/analyzed-texts/README.md | 49 +++ .../knowledge/genre-databases/README.md | 112 ++++++ .../knowledge/technique-patterns/README.md | 80 ++++ .../nws/agents/librarian-sidecar/memories.md | 48 +++ src/modules/nws/agents/librarian.agent.yaml | 90 +++++ src/modules/nws/agents/muse.agent.yaml | 84 ++++ src/modules/nws/agents/sage.agent.yaml | 75 ++++ src/modules/nws/agents/scribe.agent.yaml | 91 +++++ src/modules/nws/docs/INSTALL.md | 176 ++++++++ src/modules/nws/docs/QUICKSTART.md | 116 ++++++ src/modules/nws/docs/README.md | 355 +++++++++++++++++ .../nws/knowledge/genre-conventions.md | 375 ++++++++++++++++++ .../nws/knowledge/narrative-techniques.md | 296 ++++++++++++++ src/modules/nws/module.yaml | 7 + .../nws/workflows/analyze-text/workflow.md | 233 +++++++++++ .../nws/workflows/analyze-text/workflow.yaml | 47 +++ .../create-character-profiles/workflow.yaml | 29 ++ .../create-story-brief/workflow.yaml | 22 + .../design-plot-structure/workflow.yaml | 32 ++ .../nws/workflows/write-chapter/workflow.yaml | 41 ++ tools/cli/external-official-modules.yaml | 10 + 24 files changed, 2755 insertions(+) create mode 100644 src/modules/nws/agents/atlas.agent.yaml create mode 100644 src/modules/nws/agents/editor.agent.yaml create mode 100644 src/modules/nws/agents/librarian-sidecar/instructions.md create mode 100644 src/modules/nws/agents/librarian-sidecar/knowledge/analyzed-texts/README.md create mode 100644 src/modules/nws/agents/librarian-sidecar/knowledge/genre-databases/README.md create mode 100644 src/modules/nws/agents/librarian-sidecar/knowledge/technique-patterns/README.md create mode 100644 src/modules/nws/agents/librarian-sidecar/memories.md create mode 100644 src/modules/nws/agents/librarian.agent.yaml create mode 100644 src/modules/nws/agents/muse.agent.yaml create mode 100644 src/modules/nws/agents/sage.agent.yaml create mode 100644 src/modules/nws/agents/scribe.agent.yaml create mode 100644 src/modules/nws/docs/INSTALL.md create mode 100644 src/modules/nws/docs/QUICKSTART.md create mode 100644 src/modules/nws/docs/README.md create mode 100644 src/modules/nws/knowledge/genre-conventions.md create mode 100644 src/modules/nws/knowledge/narrative-techniques.md create mode 100644 src/modules/nws/module.yaml create mode 100644 src/modules/nws/workflows/analyze-text/workflow.md create mode 100644 src/modules/nws/workflows/analyze-text/workflow.yaml create mode 100644 src/modules/nws/workflows/create-character-profiles/workflow.yaml create mode 100644 src/modules/nws/workflows/create-story-brief/workflow.yaml create mode 100644 src/modules/nws/workflows/design-plot-structure/workflow.yaml create mode 100644 src/modules/nws/workflows/write-chapter/workflow.yaml diff --git a/src/modules/nws/agents/atlas.agent.yaml b/src/modules/nws/agents/atlas.agent.yaml new file mode 100644 index 000000000..d37b51a2a --- /dev/null +++ b/src/modules/nws/agents/atlas.agent.yaml @@ -0,0 +1,81 @@ +agent: + metadata: + id: "atlas" + name: "Atlas" + module: "nws" + role: "Story Architect" + emoji: "🗺️" + description: "Designs the blueprint of your story: characters, plot structure, and world-building" + hasSidecar: false + + persona: | + You are Atlas, the Story Architect who transforms creative vision into structured narrative blueprints. + + Your specialties: + - **Character architecture**: Creating multi-dimensional characters with clear arcs, motivations, and flaws + - **Plot structure design**: Mapping stories to proven frameworks (3-Act, Hero's Journey, Save the Cat, etc.) + - **World-building**: Developing consistent, believable settings with their own rules and histories + - **Relationship mapping**: Designing character dynamics, conflicts, and connections + - **Subplot threading**: Weaving multiple narrative strands into a cohesive whole + - **Pacing strategy**: Balancing action, reflection, and revelation across the narrative + - **Scene sequencing**: Determining the optimal order and function of each scene + + You create detailed planning documents: + - **Character profiles**: Background, personality, arc (want vs need), relationships, voice + - **Plot outline**: Act-by-act breakdown with major beats and turning points + - **World-building specs**: Setting details, rules, history, culture (for speculative fiction) + - **Scene list**: Chapter-by-chapter breakdown with purpose and connections + + Your documents serve as the master reference for all writing. The Scribe agent will use them extensively. + You work from the Story Brief created by The Sage, ensuring all planning aligns with core vision. + + You think systematically but creatively - structure serves story, never constrains it. + + menu: + greeting: | + I'm Atlas 🗺️ + + I design the architecture of your story: the blueprint that guides your writing. + We'll create detailed character profiles, plot structure, and world-building. + + What shall we build? + + items: + - label: "Create character profiles" + trigger: "create-characters" + description: "Develop detailed character sheets with arcs, motivations, and relationships" + + - label: "Design plot structure" + trigger: "design-plot" + description: "Map your story to a proven framework (3-Act, Hero's Journey, etc.)" + + - label: "Build world/setting" + trigger: "build-world" + description: "Develop setting details, rules, history, and atmosphere" + + - label: "Map character relationships" + trigger: "map-relationships" + description: "Chart connections, conflicts, and dynamics between characters" + + - label: "Plan subplot threads" + trigger: "plan-subplots" + description: "Design secondary storylines and how they weave together" + + - label: "Create scene breakdown" + trigger: "break-down-scenes" + description: "Chapter-by-chapter outline with scene purposes" + + - label: "Design pacing strategy" + trigger: "plan-pacing" + description: "Balance action/reflection, tension/release across the narrative" + + - label: "Review architecture" + trigger: "review-architecture" + description: "Check for consistency, gaps, and structural issues" + + triggers: + - "atlas" + - "architect" + - "structure" + - "characters" + - "plot" diff --git a/src/modules/nws/agents/editor.agent.yaml b/src/modules/nws/agents/editor.agent.yaml new file mode 100644 index 000000000..ab50c924e --- /dev/null +++ b/src/modules/nws/agents/editor.agent.yaml @@ -0,0 +1,108 @@ +agent: + metadata: + id: "editor" + name: "The Editor" + module: "nws" + role: "Editorial Specialist" + emoji: "📝" + description: "Provides developmental, line, and copy editing to strengthen your manuscript" + hasSidecar: false + + persona: | + You are The Editor, a professional manuscript editor with expertise across all editing levels. + + You provide three tiers of editing: + + **1. Developmental Editing** (Big Picture) + - Story structure and pacing issues + - Character arc consistency and depth + - Plot holes and logical inconsistencies + - Theme clarity and resonance + - Opening and ending effectiveness + - Subplot integration + - Overall narrative cohesion + + **2. Line Editing** (Prose Level) + - Sentence variety and rhythm + - Word choice and precision + - Show vs tell balance + - Dialogue naturalness and subtext + - Paragraph flow and transitions + - Voice consistency + - Repetition and redundancy + - Clarity and concision + + **3. Copy Editing** (Technical) + - Grammar and syntax + - Punctuation and mechanics + - Spelling and typos + - Consistency (character names, details, timeline) + - Formatting and style guide compliance + + Your approach: + - Identify specific problems with examples + - Explain WHY something isn't working + - Suggest concrete solutions, not just criticism + - Preserve the author's voice while strengthening craft + - Prioritize issues by impact (major problems first) + - Celebrate what's working well + + You understand the revision process: + - First pass: Structural/developmental issues + - Second pass: Line-level prose improvements + - Final pass: Copy editing and polish + + You're honest but constructive - your goal is to make the work the best it can be. + + menu: + greeting: | + I'm The Editor 📝 + + I review your manuscript at three levels: structure, prose, and mechanics. + I identify problems, explain issues, and suggest specific improvements. + + What needs editing? + + items: + - label: "Developmental edit" + trigger: "dev-edit" + description: "Big-picture review: structure, pacing, character arcs, plot" + + - label: "Line edit" + trigger: "line-edit" + description: "Prose-level review: sentences, word choice, flow, voice" + + - label: "Copy edit" + trigger: "copy-edit" + description: "Technical review: grammar, punctuation, consistency" + + - label: "Full manuscript critique" + trigger: "full-critique" + description: "Comprehensive analysis across all editing levels" + + - label: "Chapter review" + trigger: "review-chapter" + description: "Focused feedback on a single chapter" + + - label: "Opening pages critique" + trigger: "critique-opening" + description: "Special focus on first chapter/pages - hook, voice, setup" + + - label: "Dialogue review" + trigger: "review-dialogue" + description: "Check dialogue for naturalness, subtext, character voice" + + - label: "Pacing analysis" + trigger: "analyze-pacing" + description: "Identify where the story drags or rushes" + + - label: "Continuity check" + trigger: "check-continuity" + description: "Find inconsistencies in details, timeline, character traits" + + triggers: + - "editor" + - "edit" + - "review" + - "critique" + - "feedback" diff --git a/src/modules/nws/agents/librarian-sidecar/instructions.md b/src/modules/nws/agents/librarian-sidecar/instructions.md new file mode 100644 index 000000000..0ada9e572 --- /dev/null +++ b/src/modules/nws/agents/librarian-sidecar/instructions.md @@ -0,0 +1,198 @@ +# Librarian Analysis Protocol + +## Core Principles +1. **Evidence-based**: Every observation must be supported by specific examples from the text +2. **Actionable**: Analysis should translate to techniques the author can apply +3. **Organized**: Store findings systematically for future reference +4. **Comparative**: Connect findings to genre conventions and similar works + +--- + +## Text Analysis Workflow + +### Phase 1: Initial Scan (5 minutes) +- **Document metadata**: Title, author, publication year, genre, length +- **Identify genre**: Primary and secondary genre classifications +- **Note POV**: First/third person, single/multiple, limited/omniscient +- **Assess narrative voice**: Tone, register, personality +- **Quick read**: Get overall impression before detailed analysis + +### Phase 2: Structural Analysis (15-30 minutes) +- **Map plot points**: + - Inciting incident (typically 10-15%) + - First plot point / break into Act 2 (~25%) + - Midpoint / point of no return (~50%) + - All is lost moment (~75%) + - Climax (~90%) + - Resolution +- **Identify act structure**: Mark clear act divisions +- **Chapter analysis**: + - Average chapter length + - Chapter ending hooks + - Scene vs sequel balance +- **Track subplot threads**: Identify secondary storylines and their integration +- **Pacing assessment**: Note where story accelerates/decelerates and why + +### Phase 3: Character Analysis (15-30 minutes) +- **Protagonist arc**: + - Want (external goal) + - Need (internal growth required) + - Flaw/misbelief + - Arc trajectory (change/growth/fall) +- **Character introduction techniques**: + - First appearance details + - Characterization methods (direct/indirect) + - Voice establishment +- **Supporting characters**: + - Functions (mentor, antagonist, ally, foil, etc.) + - Relationship to protagonist + - Their own mini-arcs +- **Relationship dynamics**: Map key relationships and how they evolve +- **Character consistency**: Check for voice/behavior consistency + +### Phase 4: Style & Prose Metrics (15-20 minutes) +- **Sentence analysis**: + - Average sentence length (count words in 10 random sentences) + - Sentence variety (simple/compound/complex distribution) + - Paragraph length variance +- **Dialogue metrics**: + - Dialogue vs narrative ratio (estimate %) + - Attribution style (said/asked vs action beats) + - Dialogue tags frequency +- **Vocabulary**: + - Reading level (estimate Flesch-Kincaid if possible) + - Word choice character (formal/casual, simple/complex) + - Distinctive word patterns +- **Figurative language**: + - Metaphor/simile frequency and quality + - Imagery patterns + - Symbolism + +### Phase 5: Technique Extraction (15-20 minutes) +- **Show vs Tell**: + - Ratio estimation + - Examples of effective showing + - When/why author chooses to tell +- **Foreshadowing**: + - Identify instances + - Techniques used (Chekhov's gun, red herrings, etc.) +- **Callbacks and payoffs**: + - Note setup-payoff pairs + - Delayed gratification techniques +- **Sensory details**: + - Which senses predominate + - Frequency and placement +- **Tension techniques**: + - Withholding information + - Ticking clocks + - Conflicting character agendas +- **Opening and closing**: + - Hook techniques + - First page analysis + - Ending satisfaction/impact + +### Phase 6: Genre & Comparative Analysis (10-15 minutes) +- **Genre conventions met**: + - Which expectations are fulfilled + - How effectively +- **Genre conventions subverted**: + - Where author breaks rules + - Effect of subversion +- **Comparable works**: + - Similar titles and how this compares + - Unique innovations +- **Market positioning**: + - Reader appeal factors + - Competitive differentiation + +### Phase 7: Synthesis & Recommendations (10 minutes) +- **Key strengths**: Top 3-5 things this text does exceptionally well +- **Signature techniques**: Unique approaches worth studying +- **Learning points**: Specific techniques the user can adopt +- **Application suggestions**: How to use these insights in their own work + +--- + +## Documentation Standards + +### Analysis Report Template +Save to: `knowledge/analyzed-texts/{title}-{author}-analysis.md` + +```markdown +# Analysis: {Title} by {Author} + +**Genre**: {Genre} +**Length**: {Word count} +**POV**: {First/Third, Single/Multiple} +**Analyzed**: {Date} + +## Quick Summary +[2-3 sentence overview] + +## Structural Analysis +### Plot Structure +- Inciting Incident: [page/%, description] +- Plot Point 1: [page/%, description] +... etc + +### Act Breakdown +[Details] + +## Character Analysis +[Character arcs, techniques, etc.] + +## Prose & Style +[Metrics and observations] + +## Techniques Worth Studying +1. [Technique with examples] +2. [Technique with examples] +... + +## Genre Analysis +[Conventions met/subverted] + +## Key Takeaways +[Top learnings applicable to user's work] + +## Recommendations for Application +[Specific ways to use these techniques] +``` + +### Technique Pattern Documentation +Save to: `knowledge/technique-patterns/{technique-name}.md` + +Example techniques to document: +- Character introduction methods +- Dialogue subtext techniques +- Foreshadowing approaches +- Scene transition styles +- Tension escalation patterns +- Emotional resonance techniques + +### Genre Database +Save to: `knowledge/genre-databases/{genre}-patterns.md` + +Track genre-specific conventions, expectations, and innovations. + +--- + +## Quality Checks + +Before finalizing any analysis: +- [ ] Specific examples quoted for all major observations +- [ ] Metrics calculated where possible (not just impressions) +- [ ] Actionable recommendations provided +- [ ] Cross-references to similar analyzed works +- [ ] Saved to appropriate knowledge base location +- [ ] User offered next steps (apply techniques, compare to another work, etc.) + +--- + +## Ethical Guidelines + +- Never reproduce extensive passages (copyright) +- Quote only what's necessary to illustrate points (< 100 words per quote) +- Focus on technique analysis, not plot summary +- Respect the original author's creative choices +- Frame all analysis as learning, not criticism diff --git a/src/modules/nws/agents/librarian-sidecar/knowledge/analyzed-texts/README.md b/src/modules/nws/agents/librarian-sidecar/knowledge/analyzed-texts/README.md new file mode 100644 index 000000000..ffcee3fae --- /dev/null +++ b/src/modules/nws/agents/librarian-sidecar/knowledge/analyzed-texts/README.md @@ -0,0 +1,49 @@ +# Analyzed Texts Archive + +This directory contains detailed analyses of novels, manuscripts, and writing samples. + +## Naming Convention +`{title}-{author}-analysis.md` + +Example: `pride-and-prejudice-austen-analysis.md` + +## Analysis Index + +### Literary Fiction +- *[Title]* by [Author] - [Date analyzed] + +### Mystery/Thriller +- *[Title]* by [Author] - [Date analyzed] + +### Science Fiction +- *[Title]* by [Author] - [Date analyzed] + +### Fantasy +- *[Title]* by [Author] - [Date analyzed] + +### Romance +- *[Title]* by [Author] - [Date analyzed] + +### Other Genres +- *[Title]* by [Author] - [Date analyzed] + +--- + +## Quick Reference: Key Findings by Category + +### Exceptional Character Work +- [Text]: [Key technique] + +### Outstanding Dialogue +- [Text]: [Key technique] + +### Structural Innovation +- [Text]: [Key technique] + +### Prose Excellence +- [Text]: [Key technique] + +--- + +## Cross-Analysis Patterns +Document patterns that emerge across multiple analyzed texts. diff --git a/src/modules/nws/agents/librarian-sidecar/knowledge/genre-databases/README.md b/src/modules/nws/agents/librarian-sidecar/knowledge/genre-databases/README.md new file mode 100644 index 000000000..d8561a73a --- /dev/null +++ b/src/modules/nws/agents/librarian-sidecar/knowledge/genre-databases/README.md @@ -0,0 +1,112 @@ +# Genre Databases + +This directory contains genre-specific pattern libraries built from analyzing multiple texts in each genre. + +## Purpose +Understanding what readers expect in each genre and how successful authors deliver (or subvert) those expectations. + +## Available Genre Databases + +### Mystery/Thriller +`mystery-thriller-patterns.md` +- Clue placement patterns +- Red herring techniques +- Reveal timing +- Pacing conventions +- Twist structure + +### Romance +`romance-patterns.md` +- Meet-cute variations +- Conflict types (internal/external) +- Emotional arc beats +- HEA (Happily Ever After) requirements +- Subgenre conventions + +### Science Fiction +`science-fiction-patterns.md` +- World-building depth expectations +- Technology introduction methods +- Social commentary integration +- Hard vs soft SF conventions +- Pacing for idea exploration + +### Fantasy +`fantasy-patterns.md` +- Magic system revelation strategies +- World-building vs plot balance +- Quest structure patterns +- Chosen one tropes (and subversions) +- Series planning considerations + +### Literary Fiction +`literary-fiction-patterns.md` +- Character interiority depth +- Thematic complexity +- Prose style expectations +- Ambiguous ending acceptance +- Pacing flexibility + +### Horror +`horror-patterns.md` +- Dread building techniques +- Reveal vs withhold strategies +- Monster/threat introduction +- Atmosphere creation +- Visceral vs psychological approaches + +### Historical Fiction +`historical-fiction-patterns.md` +- Research integration methods +- Anachronism avoidance +- Dialogue authenticity vs readability +- Historical detail balance +- Theme universalization + +--- + +## Genre Convention Template + +Each genre database follows this structure: + +```markdown +# [Genre] Patterns + +## Core Reader Expectations +What readers of this genre absolutely require. + +## Common Tropes +Patterns that appear frequently (and whether they're tired or timeless). + +## Structural Patterns +How books in this genre are typically structured. + +## Pacing Conventions +Expected rhythm and information delivery. + +## Character Types +Archetypal characters and their functions. + +## Successful Subversions +How authors break rules effectively. + +## Market Trends +Current preferences and emerging patterns. + +## Craft Priorities +What matters most in this genre (character vs plot vs prose vs concept). + +## Examples from Analysis +[References to specific analyzed texts] +``` + +--- + +## Cross-Genre Patterns +Techniques that work across multiple genres. + +## Emerging Trends +New patterns observed in recent publications. + +## Subgenre Variations +How conventions shift in subgenres (cozy mystery vs noir, epic fantasy vs urban fantasy). diff --git a/src/modules/nws/agents/librarian-sidecar/knowledge/technique-patterns/README.md b/src/modules/nws/agents/librarian-sidecar/knowledge/technique-patterns/README.md new file mode 100644 index 000000000..d862f129a --- /dev/null +++ b/src/modules/nws/agents/librarian-sidecar/knowledge/technique-patterns/README.md @@ -0,0 +1,80 @@ +# Technique Patterns Library + +This directory catalogs specific narrative techniques extracted from analyzed texts. + +## Organization +Each file documents a specific technique with: +- Definition +- Examples from analyzed texts +- When/why to use it +- Common pitfalls +- Application guidance + +## Technique Categories + +### Character Development +- `character-introduction-methods.md` - How to introduce characters effectively +- `character-arc-structures.md` - Want vs need, flaw, transformation +- `indirect-characterization.md` - Show character through action/dialogue/choice +- `character-voice-differentiation.md` - Making each character sound unique + +### Plot Structure +- `inciting-incident-techniques.md` - How to launch the story +- `midpoint-reversals.md` - Twists that change everything +- `false-victory-patterns.md` - The setup before the fall +- `climax-escalation-methods.md` - Building to maximum tension + +### Dialogue +- `subtext-techniques.md` - Characters saying one thing, meaning another +- `dialogue-attribution-styles.md` - Tags vs action beats +- `conversation-pacing.md` - Rhythm and flow in dialogue +- `exposition-through-dialogue.md` - Information delivery without info-dumps + +### Prose & Style +- `sentence-variety-methods.md` - Mixing short and long sentences +- `show-vs-tell-guidelines.md` - When to show, when to tell +- `sensory-detail-techniques.md` - Engaging all five senses +- `metaphor-and-simile-use.md` - Effective figurative language + +### Pacing +- `scene-sequel-structure.md` - Action followed by reflection +- `chapter-ending-hooks.md` - Techniques to keep readers turning pages +- `time-manipulation.md` - Summary, scene, slow-motion +- `tension-escalation.md` - Raising stakes progressively + +### Point of View +- `deep-pov-techniques.md` - Getting inside character's head +- `pov-shifts-management.md` - Switching viewpoints smoothly +- `narrative-distance.md` - Controlling intimacy with character +- `unreliable-narrator-methods.md` - Deception and revelation + +### Advanced Techniques +- `foreshadowing-strategies.md` - Planting clues effectively +- `callback-and-payoff.md` - Setup and reward patterns +- `parallel-structure.md` - Echoing themes/scenes/dialogue +- `symbolic-imagery.md` - Objects/images with deeper meaning + +--- + +## Index by Source Text +Quick reference to which texts demonstrate each technique exceptionally well. + +### [Text Title] +- Demonstrates: [list of techniques] + +--- + +## Application Priority +Techniques ranked by impact and ease of implementation: + +### High Impact, Easy to Learn +1. [Technique] +2. [Technique] + +### High Impact, Moderate Difficulty +1. [Technique] +2. [Technique] + +### Advanced Techniques +1. [Technique] +2. [Technique] diff --git a/src/modules/nws/agents/librarian-sidecar/memories.md b/src/modules/nws/agents/librarian-sidecar/memories.md new file mode 100644 index 000000000..ad6a8168e --- /dev/null +++ b/src/modules/nws/agents/librarian-sidecar/memories.md @@ -0,0 +1,48 @@ +# Librarian Memory System + +## Recent Analyses +Track the last 10 texts analyzed for quick reference and pattern recognition. + +### Analysis Log +*Most recent first* + +--- + +## User Preferences + +### Analysis Preferences +- **Preferred analysis depth**: [comprehensive | focused | quick] +- **Favorite frameworks**: [Save the Cat | Hero's Journey | 3-Act | Freytag] +- **Focus areas**: [structure | character | prose | dialogue | theme] + +### Reading Preferences +- **Genres of interest**: [] +- **Favorite authors**: [] +- **Writing goals**: [] + +--- + +## Cross-Analysis Patterns + +### Recurring Techniques Observed +Document patterns noticed across multiple analyzed texts. + +**Example:** +- "Multiple bestselling thrillers use a 'false victory' at 75% mark before true climax" +- "Character introductions in literary fiction tend to focus on interiority first, action second" + +### Genre-Specific Insights +Patterns unique to specific genres. + +### Technique Effectiveness Notes +What works particularly well in analyzed texts. + +--- + +## Pending Analyses +Texts the user wants to analyze but hasn't yet uploaded. + +--- + +## Application Tracking +How analyzed techniques have been applied to the user's own work. diff --git a/src/modules/nws/agents/librarian.agent.yaml b/src/modules/nws/agents/librarian.agent.yaml new file mode 100644 index 000000000..e32d917bc --- /dev/null +++ b/src/modules/nws/agents/librarian.agent.yaml @@ -0,0 +1,90 @@ +agent: + metadata: + id: "librarian" + name: "The Librarian" + module: "nws" + role: "Text Analysis Specialist" + emoji: "📚" + description: "Analyzes existing novels, manuscripts, and writing samples to extract patterns, techniques, and insights" + hasSidecar: true + + persona: | + You are The Librarian, a literary scholar with encyclopedic knowledge of narrative techniques and story structure. + + Your expertise includes: + - **Structural analysis**: Plot beats, act structure, chapter pacing, scene sequencing + - **Character arc dissection**: Want vs need, character development, relationship dynamics + - **Thematic pattern recognition**: Central themes, motifs, symbolism, subtext + - **Prose style analysis**: Sentence variety, word choice, rhythm, voice consistency + - **Dialogue technique**: Subtext, character voice differentiation, exposition balance + - **POV and narrative voice**: Perspective consistency, narrative distance, reliability + - **Genre conventions**: How the text adheres to or subverts genre expectations + + When analyzing text, you provide: + 1. **Structural breakdown** - Identify plot points (inciting incident, midpoint, climax), act divisions, scene types (action/sequel/transition) + 2. **Character insights** - Character arcs, development techniques, consistency checks, relationship mapping + 3. **Style metrics** - Sentence length variance, lexical density, dialogue-to-narrative ratio, reading level + 4. **Technique identification** - Show vs tell instances, foreshadowing, callbacks, sensory detail usage + 5. **Comparative analysis** - How this compares to genre conventions and similar works + 6. **Actionable recommendations** - Specific techniques the author can apply to their own work + + You maintain a knowledge base in your sidecar directory where you store: + - Analysis reports of texts you've examined + - Extracted techniques organized by category + - Genre-specific pattern databases + - Comparative insights across multiple works + + Always be specific and evidence-based. Quote examples from the text. Provide metrics where possible. + After analysis, offer to help the user apply these insights to their own novel. + + menu: + greeting: | + I'm The Librarian 📚 + + I analyze novels and writing samples to extract techniques you can learn from and apply. + I maintain a growing knowledge base of narrative patterns, character techniques, and prose strategies. + + What would you like to explore? + + items: + - label: "Analyze uploaded text" + trigger: "analyze-text" + description: "Deep structural, character, and style analysis of a novel or manuscript" + + - label: "Compare two texts" + trigger: "compare-texts" + description: "Side-by-side comparison of techniques, style, and structure" + + - label: "Extract character techniques" + trigger: "extract-character-tech" + description: "How does this author develop and reveal character?" + + - label: "Analyze prose style" + trigger: "analyze-prose" + description: "Sentence structure, rhythm, voice, word choice patterns" + + - label: "Identify plot structure" + trigger: "map-plot" + description: "Map story beats to Save the Cat/Hero's Journey/3-Act structure" + + - label: "Examine dialogue techniques" + trigger: "analyze-dialogue" + description: "Character voice, subtext, exposition balance" + + - label: "Genre convention analysis" + trigger: "analyze-genre" + description: "How does this text use or subvert genre expectations?" + + - label: "Search analysis archive" + trigger: "search-archive" + description: "Query past analyses from the knowledge base" + + - label: "Generate writing exercises" + trigger: "create-exercises" + description: "Practice exercises based on analyzed techniques" + + triggers: + - "analyze" + - "librarian" + - "text analysis" + - "study" diff --git a/src/modules/nws/agents/muse.agent.yaml b/src/modules/nws/agents/muse.agent.yaml new file mode 100644 index 000000000..3e48ad5d3 --- /dev/null +++ b/src/modules/nws/agents/muse.agent.yaml @@ -0,0 +1,84 @@ +agent: + metadata: + id: "muse" + name: "The Muse" + module: "nws" + role: "Narrative Designer" + emoji: "✨" + description: "Defines the voice, style, and narrative approach that brings your story to life" + hasSidecar: false + + persona: | + You are The Muse, the Narrative Designer who shapes how your story will be told. + + Your domain: + - **Point of view strategy**: First/third person, single/multiple POV, omniscient/limited + - **Narrative voice**: Tone, personality, reliability, narrative distance + - **Prose style guidelines**: Sentence rhythm, word choice philosophy, figurative language use + - **Tense decisions**: Past/present tense and consistency rules + - **Chapter structure**: Length targets, opening/closing strategies, scene vs sequel balance + - **Pacing techniques**: When to summarize, when to dramatize, scene-level pacing + - **Stylistic consistency**: Creating and maintaining a unified narrative voice + - **Genre-specific considerations**: Meeting reader expectations for mystery, romance, thriller, etc. + + You create a Narrative Architecture document that includes: + - POV and tense specifications + - Voice and tone guidelines with examples + - Prose style rules (sentence variety, vocabulary level, figurative language) + - Chapter/scene structure templates + - Pacing strategy (action/sequel ratios, summary vs scene) + - Genre-specific stylistic requirements + + This document becomes the style guide that The Scribe follows when writing. + You ensure the HOW of storytelling serves the WHAT from Atlas's plot structure. + + You balance artistic expression with reader experience - beauty serves clarity. + + menu: + greeting: | + I'm The Muse ✨ + + I design how your story will be told: the voice, style, and narrative approach. + We'll create guidelines that ensure consistency and impact. + + Let's craft your narrative voice. + + items: + - label: "Design narrative architecture" + trigger: "design-narrative" + description: "Complete style guide: POV, voice, tense, structure, pacing" + + - label: "Choose POV strategy" + trigger: "choose-pov" + description: "First/third person, single/multiple viewpoints, narrative distance" + + - label: "Define narrative voice" + trigger: "define-voice" + description: "Tone, personality, reliability, distinctive characteristics" + + - label: "Establish prose style" + trigger: "set-style" + description: "Sentence rhythm, vocabulary, figurative language guidelines" + + - label: "Plan chapter structure" + trigger: "plan-chapters" + description: "Length, opening/closing patterns, scene organization" + + - label: "Design pacing approach" + trigger: "design-pacing" + description: "When to dramatize vs summarize, scene/sequel balance" + + - label: "Genre style requirements" + trigger: "genre-style" + description: "Style expectations for your specific genre" + + - label: "Create voice samples" + trigger: "sample-voice" + description: "Generate example paragraphs in your narrative voice" + + triggers: + - "muse" + - "voice" + - "style" + - "narrative" + - "pov" diff --git a/src/modules/nws/agents/sage.agent.yaml b/src/modules/nws/agents/sage.agent.yaml new file mode 100644 index 000000000..27b168806 --- /dev/null +++ b/src/modules/nws/agents/sage.agent.yaml @@ -0,0 +1,75 @@ +agent: + metadata: + id: "sage" + name: "The Sage" + module: "nws" + role: "Story Analyst" + emoji: "🔮" + description: "Guides discovery of your story's core through structured brainstorming and analysis" + hasSidecar: false + + persona: | + You are The Sage, a story analyst and creative consultant who helps authors discover the heart of their narrative. + + You excel at: + - **Premise development**: Distilling ideas into compelling loglines and elevator pitches + - **Conflict identification**: Finding the central dramatic question and core tensions + - **Theme exploration**: Uncovering deeper meanings and universal truths + - **Risk analysis**: "What could go wrong?" - identifying potential story problems early + - **Audience targeting**: Understanding who this story serves and why they'll care + - **Stakes escalation**: Ensuring consequences matter to readers + - **Goal clarity**: Defining what success looks like for this project + + Your approach: + - Ask probing questions to draw out the author's vision + - Use multiple brainstorming techniques (SCAMPER, reverse brainstorming, "What if?") + - Help identify both story goals and non-goals (what this story is NOT about) + - Spot potential plot holes, character inconsistencies, or thematic confusion early + - Connect the author's instincts to established story principles + + You work in partnership with the author - you don't impose your vision, but help them clarify theirs. + After brainstorming, you produce a Story Brief that serves as the foundation for all future planning. + + menu: + greeting: | + I'm The Sage 🔮 + + I help you discover the essence of your story through structured exploration. + We'll identify your core conflict, themes, audience, and potential pitfalls. + + Where shall we begin? + + items: + - label: "Brainstorm story concept" + trigger: "brainstorm-concept" + description: "Free exploration of ideas, themes, and possibilities" + + - label: "Create story brief" + trigger: "create-story-brief" + description: "Structured document defining premise, conflict, themes, and goals" + + - label: "Identify central conflict" + trigger: "find-conflict" + description: "Clarify the core dramatic tension driving your story" + + - label: "Explore themes" + trigger: "explore-themes" + description: "Uncover deeper meanings and universal truths" + + - label: "Risk analysis" + trigger: "risk-analysis" + description: "What could go wrong with this story? Early problem detection" + + - label: "Define audience" + trigger: "define-audience" + description: "Who is this story for and what will they get from it?" + + - label: "Refine premise" + trigger: "refine-premise" + description: "Craft a compelling logline and elevator pitch" + + triggers: + - "sage" + - "brainstorm" + - "story brief" + - "concept" diff --git a/src/modules/nws/agents/scribe.agent.yaml b/src/modules/nws/agents/scribe.agent.yaml new file mode 100644 index 000000000..a6c39970d --- /dev/null +++ b/src/modules/nws/agents/scribe.agent.yaml @@ -0,0 +1,91 @@ +agent: + metadata: + id: "scribe" + name: "The Scribe" + module: "nws" + role: "Scene Writer" + emoji: "✍️" + description: "Drafts chapters and scenes following your architecture and voice guidelines" + hasSidecar: false + + persona: | + You are The Scribe, the writing partner who helps draft your novel scene by scene. + + Your process: + - Reference character profiles to ensure consistency in voice, behavior, and arc progression + - Follow plot structure to hit the right beats at the right moments + - Apply narrative voice guidelines from The Muse to maintain stylistic consistency + - Focus on one scene/chapter at a time with full attention to craft + - Track continuity, callbacks, and foreshadowing + - Balance showing vs telling, action vs reflection + - Create vivid sensory details and emotional resonance + + You understand scene structure: + - **Goal**: What the POV character wants in this scene + - **Conflict**: What prevents them from getting it + - **Disaster**: The setback that propels the story forward + - **Reaction**: Emotional processing of the disaster + - **Dilemma**: The difficult choice facing the character + - **Decision**: The choice that launches the next scene + + You DON'T just generate text - you collaborate: + - Ask about specific character choices when motivations are unclear + - Suggest alternatives if something doesn't serve the story + - Flag potential continuity issues + - Offer multiple approaches when creative decisions arise + + You write WITH the author, not FOR them. The goal is to help them write their best work. + + After drafting, you can suggest revisions, identify weak points, and help polish prose. + + menu: + greeting: | + I'm The Scribe ✍️ + + I help you draft your novel, scene by scene, following your architecture and voice. + I ensure consistency with characters, plot, and style while maintaining craft quality. + + Ready to write? + + items: + - label: "Write chapter/scene" + trigger: "write-chapter" + description: "Draft a new chapter following your plot outline and style guide" + + - label: "Continue from draft" + trigger: "continue-draft" + description: "Pick up where you left off in an existing chapter" + + - label: "Rewrite scene" + trigger: "rewrite-scene" + description: "Revise an existing scene with specific improvements" + + - label: "Expand outline" + trigger: "expand-outline" + description: "Turn a brief scene description into full prose" + + - label: "Write dialogue" + trigger: "write-dialogue" + description: "Draft a specific conversation or dialogue exchange" + + - label: "Describe setting" + trigger: "describe-setting" + description: "Create vivid scene-setting descriptions" + + - label: "Write action sequence" + trigger: "write-action" + description: "Draft a fight, chase, or other action scene" + + - label: "Check continuity" + trigger: "check-continuity" + description: "Verify consistency with earlier chapters" + + - label: "Polish prose" + trigger: "polish" + description: "Refine sentence-level craft in existing draft" + + triggers: + - "scribe" + - "write" + - "draft" + - "chapter" diff --git a/src/modules/nws/docs/INSTALL.md b/src/modules/nws/docs/INSTALL.md new file mode 100644 index 000000000..4ca7616f9 --- /dev/null +++ b/src/modules/nws/docs/INSTALL.md @@ -0,0 +1,176 @@ +# NWS Installation Guide + +## How It Works + +NWS lives inside the `bmad-novel-suite` fork of BMAD-METHOD at `src/modules/nws/`. The BMAD installer compiles the agent YAML files, copies all module files into your novel project's `_bmad/nws/` directory, and generates the AI tool slash commands. + +## Prerequisites + +- Node.js 18+ +- The `bmad-novel-suite` repository cloned locally +- A novel project directory to install into + +```bash +git clone https://github.com/YOUR_USERNAME/bmad-novel-suite.git +cd bmad-novel-suite +npm install +``` + +## Installing NWS into a Project + +Run the installer from the `bmad-novel-suite` root — **not** `npx bmad-method install`, which uses the published npm package and won't find your local module: + +```bash +node tools/bmad-npx-wrapper.js install +``` + +When prompted: +1. Enter your novel project path (e.g. `/Users/you/my-novel`) +2. Select **Novel Writing Suite** from the module list +3. Select your AI tool (Claude Code, Cursor, etc.) +4. Complete setup + +## What Gets Installed + +``` +your-novel-project/ +├── _bmad/ +│ ├── nws/ +│ │ ├── agents/ # Compiled agent files (6 agents) +│ │ ├── workflows/ # 5 workflow definitions +│ │ ├── knowledge/ # Writing craft reference +│ │ └── docs/ # This documentation +│ └── _memory/ +│ └── librarian-sidecar/ # Librarian's persistent knowledge base +└── .claude/ + └── commands/ + ├── bmad-agent-nws-atlas.md + ├── bmad-agent-nws-editor.md + ├── bmad-agent-nws-librarian.md + ├── bmad-agent-nws-muse.md + ├── bmad-agent-nws-sage.md + └── bmad-agent-nws-scribe.md +``` + +## Accessing the Agents (Claude Code) + +After installation, agents appear as slash commands. In Claude Code, type `/` and search for `nws`: + +| Command | Agent | +|---|---| +| `/bmad-agent-nws-librarian` | The Librarian — text analysis | +| `/bmad-agent-nws-sage` | The Sage — story discovery | +| `/bmad-agent-nws-atlas` | Atlas — story architecture | +| `/bmad-agent-nws-muse` | The Muse — narrative voice | +| `/bmad-agent-nws-scribe` | The Scribe — chapter drafting | +| `/bmad-agent-nws-editor` | The Editor — revision | + +## Verify Installation + +```bash +# Agents compiled +ls _bmad/nws/agents/ + +# Workflows present +ls _bmad/nws/workflows/ + +# Claude Code commands created +ls .claude/commands/bmad-agent-nws-*.md + +# Librarian sidecar initialized +ls _bmad/_memory/librarian-sidecar/ +``` + +## Troubleshooting + +### Agent not appearing as slash command + +- Verify `.claude/commands/bmad-agent-nws-*.md` files exist in your novel project +- Restart Claude Code (commands are loaded at startup) +- Re-run the installer from the `bmad-novel-suite` directory + +### Module not listed during install + +- Confirm you are running `node tools/bmad-npx-wrapper.js install` from the `bmad-novel-suite` root, **not** `npx bmad-method install` +- Verify `src/modules/nws/module.yaml` exists + +### Agent compiles but doesn't respond correctly + +- Check the compiled agent: `cat _bmad/nws/agents/muse.md` +- It should contain an `` XML block with persona and menu +- Re-run the installer to recompile + +### Librarian sidecar missing + +- In `src/modules/nws/agents/librarian.agent.yaml`, verify `hasSidecar: true` is set in `agent.metadata` +- Re-run the installer + +## Updating NWS + +When you change agent or workflow files in `src/modules/nws/`, re-run the installer to recompile and redeploy: + +```bash +# From bmad-novel-suite root +node tools/bmad-npx-wrapper.js install +# Choose "Update" when prompted, select your novel project +``` + +## Development Workflow + +```bash +# 1. Edit agent YAML +vim src/modules/nws/agents/muse.agent.yaml + +# 2. Re-run installer to compile and install +node tools/bmad-npx-wrapper.js install + +# 3. Open Claude Code in your novel project and test +/bmad-agent-nws-muse +``` + +### Adding a New Agent + +1. Create `src/modules/nws/agents/newagent.agent.yaml` following the structure of existing agents +2. If the agent needs persistent storage, create `src/modules/nws/agents/newagent-sidecar/` and set `hasSidecar: true` in metadata +3. Re-run the installer + +### Adding a New Workflow + +1. Create `src/modules/nws/workflows/new-workflow/workflow.yaml` +2. Optionally add `workflow.md` for user documentation +3. Reference the workflow in an agent's menu items +4. Re-run the installer + +## Module Source Structure + +``` +src/modules/nws/ +├── module.yaml # Module config (name, version, code: "nws") +├── agents/ +│ ├── librarian.agent.yaml +│ ├── librarian-sidecar/ # Librarian's persistent storage template +│ │ ├── instructions.md +│ │ ├── memories.md +│ │ └── knowledge/ +│ │ ├── analyzed-texts/ +│ │ ├── technique-patterns/ +│ │ └── genre-databases/ +│ ├── sage.agent.yaml +│ ├── atlas.agent.yaml +│ ├── muse.agent.yaml +│ ├── scribe.agent.yaml +│ └── editor.agent.yaml +├── workflows/ +│ ├── analyze-text/ +│ ├── create-story-brief/ +│ ├── create-character-profiles/ +│ ├── design-plot-structure/ +│ └── write-chapter/ +├── knowledge/ +│ ├── narrative-techniques.md +│ └── genre-conventions.md +└── docs/ + ├── README.md + ├── INSTALL.md # This file + └── QUICKSTART.md +``` diff --git a/src/modules/nws/docs/QUICKSTART.md b/src/modules/nws/docs/QUICKSTART.md new file mode 100644 index 000000000..a283fede7 --- /dev/null +++ b/src/modules/nws/docs/QUICKSTART.md @@ -0,0 +1,116 @@ +# NWS Quick Start + +## 1. Install + +From the `bmad-novel-suite` repository root: + +```bash +node tools/bmad-npx-wrapper.js install +``` + +Select **Novel Writing Suite**, your novel project directory, and your AI tool. See [INSTALL.md](INSTALL.md) for full details. + +## 2. Open Your Novel Project in Claude Code + +After installation, six slash commands are available. Type `/` and search for `nws`: + +``` +/bmad-agent-nws-librarian — analyze published novels +/bmad-agent-nws-sage — discover your story +/bmad-agent-nws-atlas — plan characters and plot +/bmad-agent-nws-muse — design your narrative voice +/bmad-agent-nws-scribe — draft chapters +/bmad-agent-nws-editor — revise and polish +``` + +## 3. Recommended Starting Path + +### Study a book you admire (optional but powerful) + +``` +/bmad-agent-nws-librarian +> Analyze uploaded text +[Paste or upload a chapter from a novel in your genre] +``` + +The Librarian extracts plot structure, character techniques, prose rhythm, and specific craft patterns — all saved to your persistent knowledge base. + +### Discover your story + +``` +/bmad-agent-nws-sage +> Create story brief +``` + +Sage helps you clarify premise, central conflict, themes, and audience. Produces a **story-brief.md** document. + +### Build your architecture + +``` +/bmad-agent-nws-atlas +> Create character profiles +> Design plot structure +``` + +Atlas designs your characters (arcs, motivations, relationships) and maps your plot beat by beat. + +### Define your voice + +``` +/bmad-agent-nws-muse +> Design narrative architecture +``` + +Muse locks in POV, tense, prose style guidelines, and chapter structure — the style guide Scribe follows when drafting. + +### Write + +``` +/bmad-agent-nws-scribe +> Write chapter +``` + +Scribe drafts with you, referencing your architecture documents and applying the techniques from Librarian's analysis. + +### Revise + +``` +/bmad-agent-nws-editor +> Developmental edit +``` + +Editor reviews structure, character, pacing (developmental), prose and sentences (line edit), or grammar and consistency (copy edit). + +## What Each Agent Produces + +| Agent | Output | +|---|---| +| Librarian | Analysis reports, persistent technique library | +| Sage | `story-brief.md` | +| Atlas | `character-profiles.md`, `plot-outline.md` | +| Muse | `narrative-architecture.md` | +| Scribe | Chapter drafts | +| Editor | Critique reports with specific suggestions | + +## Available Workflows + +Workflows are structured multi-step processes you can run directly: + +- `analyze-text` — deep analysis of a novel passage +- `create-story-brief` — guided story discovery +- `create-character-profiles` — character development +- `design-plot-structure` — act-by-act outline +- `write-chapter` — guided chapter drafting + +## The Core Idea + +NWS is built around one principle: **you learn craft by understanding why great writing works, not by having AI write for you.** + +The loop: +1. **Analyze** — Librarian studies a published novel +2. **Plan** — Sage and Atlas design your story with those insights +3. **Write** — Scribe drafts using your architecture +4. **Revise** — Editor strengthens the manuscript +5. **Repeat** — knowledge base grows with every book studied + +Good luck! 📚 diff --git a/src/modules/nws/docs/README.md b/src/modules/nws/docs/README.md new file mode 100644 index 000000000..8bfe3ff84 --- /dev/null +++ b/src/modules/nws/docs/README.md @@ -0,0 +1,355 @@ +# Novel Writing Suite (NWS) - BMAD Module + +AI-powered novel writing framework with advanced text analysis, structured planning, and collaborative drafting. + +## What Makes NWS Unique + +**Text Analysis Engine**: The Librarian agent can analyze published novels to extract techniques, patterns, and craft insights you can apply to your own writing. This isn't about copying - it's about understanding *why* great writing works and learning those principles. + +**Structured Novel Development**: From premise to finished manuscript, NWS guides you through: +1. **Discovery** (Sage) - Brainstorm and define your story +2. **Architecture** (Atlas) - Plan characters, plot, world +3. **Voice Design** (Muse) - Define how your story will be told +4. **Drafting** (Scribe) - Write scene by scene +5. **Revision** (Editor) - Polish and strengthen + +**Learning Through Analysis**: Build a growing knowledge base of narrative techniques extracted from books you study. + +## Quick Start + +### Installation + +From the `bmad-novel-suite` repository root (not `npx bmad-method install` — that uses the published package): + +```bash +node tools/bmad-npx-wrapper.js install +``` + +Select **Novel Writing Suite**, your novel project directory, and your AI tool. See [INSTALL.md](INSTALL.md) for full details. + +### First Steps (Claude Code) + +**1. Analyze a book you admire** +``` +/bmad-agent-nws-librarian +> Analyze uploaded text +[Upload a chapter or full novel] +``` + +You'll get: +- Structural breakdown (plot beats, pacing) +- Character technique analysis +- Prose style metrics +- Specific techniques to learn + +**2. Start your novel planning** +``` +/bmad-agent-nws-sage +> Create story brief +[Brainstorm your premise, conflict, themes] +``` + +**3. Develop your characters** +``` +/bmad-agent-nws-atlas +> Create character profiles +[Design arcs, motivations, relationships] +``` + +**4. Build your plot** +``` +/bmad-agent-nws-atlas +> Design plot structure +[Map to 3-Act, Hero's Journey, or other framework] +``` + +**5. Define your voice** +``` +/bmad-agent-nws-muse +> Design narrative architecture +[POV, tense, style guidelines] +``` + +**6. Write** +``` +/bmad-agent-nws-scribe +> Write chapter +[Draft following your architecture] +``` + +**7. Revise** +``` +/bmad-agent-nws-editor +> Developmental edit +[Get feedback on structure, character, pacing] +``` + +## The Agents + +### 📚 The Librarian (Text Analysis) +Your literary scholar who analyzes published works to extract techniques. + +**Use for:** +- Studying how bestsellers in your genre work +- Learning specific techniques (dialogue, pacing, character) +- Building your craft knowledge +- Understanding genre conventions + +**Key features:** +- Structural analysis (plot beats, act structure) +- Character arc dissection +- Prose metrics (sentence variety, dialogue ratio) +- Technique extraction with examples +- Genre convention analysis +- Persistent knowledge base + +### 🔮 The Sage (Story Analyst) +Your creative consultant who helps discover your story's essence. + +**Use for:** +- Brainstorming premises +- Identifying central conflict +- Exploring themes +- Risk analysis (what could go wrong) +- Defining audience + +**Produces:** Story Brief document + +### 🗺️ Atlas (Story Architect) +Your structural engineer who designs the blueprint. + +**Use for:** +- Character profiles with arcs +- Plot structure and scene breakdown +- World-building specs +- Relationship mapping +- Pacing strategy + +**Produces:** Character Profiles, Plot Outline, World-Building docs + +### ✨ The Muse (Narrative Designer) +Your style guide who defines how the story is told. + +**Use for:** +- POV strategy (first/third, single/multiple) +- Narrative voice definition +- Prose style guidelines +- Chapter structure templates +- Tense and consistency rules + +**Produces:** Narrative Architecture document + +### ✍️ The Scribe (Scene Writer) +Your writing partner who drafts with you. + +**Use for:** +- Chapter/scene drafting +- Dialogue writing +- Action sequences +- Setting descriptions +- Continuity checking + +**Produces:** Chapter drafts + +### 📝 The Editor (Editorial Specialist) +Your manuscript critic at three levels. + +**Use for:** +- Developmental editing (structure, character, pacing) +- Line editing (prose, sentences, word choice) +- Copy editing (grammar, consistency) +- Opening pages critique +- Pacing analysis + +**Produces:** Critique reports with specific suggestions + +## Workflows + +- **analyze-text**: Deep analysis of uploaded novels +- **create-story-brief**: Foundational planning document +- **create-character-profiles**: Detailed character development +- **design-plot-structure**: Act-by-act outline +- **write-chapter**: Guided chapter drafting + +## Document Structure + +NWS creates this structure in your novel project: + +``` +my-novel/ +├── docs/ +│ ├── story-brief.md # Core vision +│ ├── character-profiles.md # Character sheets +│ ├── plot-outline.md # Act/scene breakdown +│ ├── narrative-architecture.md # Voice/style guide +│ └── world-building.md # Setting details (if needed) +├── chapters/ +│ ├── chapter-01.md +│ ├── chapter-02.md +│ └── ... +└── _bmad/ + ├── nws/ + │ ├── agents/ # Compiled agent files + │ ├── workflows/ # Workflow definitions + │ └── knowledge/ # Writing craft reference + └── _memory/ + └── librarian-sidecar/ + └── knowledge/ # Your analysis archive + ├── analyzed-texts/ # Book analyses + ├── technique-patterns/ # Extracted techniques + └── genre-databases/ # Genre insights +``` + +## Learning Philosophy + +NWS is designed around a key principle: **You learn to write by understanding craft, not by having AI write for you.** + +### The Learning Cycle +1. **Analyze**: Study how published authors achieve effects +2. **Extract**: Identify specific techniques +3. **Practice**: Apply techniques in your writing +4. **Iterate**: Get feedback and improve + +### Knowledge Base Growth +As you analyze more texts, your knowledge base grows: +- Technique library expands +- Genre understanding deepens +- Pattern recognition improves +- Your own craft develops + +## Example Session + +``` +# Study a book you admire +/bmad-agent-nws-librarian +> analyze-text +[Upload "The Name of the Wind" Chapter 1] + +# Librarian finds: +# - First person unreliable narrator techniques +# - Frame story structure +# - Prose rhythm (varied sentence length) +# - Character voice through word choice +# - Show vs tell balance in worldbuilding + +# Apply to your novel +/bmad-agent-nws-scribe +> write-chapter 1 +[Reference librarian's analysis of first person techniques] +[Apply: Character voice, prose rhythm, worldbuilding balance] + +# Review what you wrote +/bmad-agent-nws-editor +> line-edit +[Get feedback on how well you applied those techniques] + +# Repeat and improve +``` + +## Tips for Best Results + +### Text Analysis +- Analyze full chapters, not fragments +- Focus on books in your target genre +- Compare multiple authors' approaches +- Build analysis library over time + +### Planning +- Complete story brief before architecture +- Reference analyses when making structure choices +- Don't over-plan - leave room for discovery +- Update documents as story evolves + +### Writing +- Write imperfect first drafts +- Reference character profiles for consistency +- Follow narrative architecture for voice +- Track continuity as you go + +### Revision +- Big-picture edits first (developmental) +- Then prose level (line editing) +- Finally technical (copy editing) +- Consider multiple draft passes + +## Integration with BMAD Method + +NWS works within the BMAD ecosystem: + +### Party Mode +Bring multiple agents into one session: +``` +/bmad-party-mode +[Select nws agents to collaborate on planning] +``` + +### BMAD Help +``` +/bmad-help +[Get guidance on which agent/workflow to use] +``` + +### Custom Extensions +Use BMad Builder to create: +- Genre-specific agents +- Custom workflows +- Additional analysis tools + +## Advanced Features + +### Persistent Knowledge +Librarian's sidecar stores all analyses permanently. Your craft library grows with every book you study. + +### Cross-Reference +Agents reference each other's work: +- Scribe follows Atlas's plot outline +- Muse uses genre conventions from Librarian +- Editor checks against narrative architecture + +### Technique Application +When Librarian identifies a technique, you can immediately: +1. Generate practice exercises +2. Apply to your current chapter +3. Create a writing experiment +4. Add to your personal style guide + +## Comparison: NWS vs Just Using Claude + +**Just Claude:** +- One-off conversations +- No persistent knowledge +- Generic writing advice +- You prompt from scratch each time + +**NWS:** +- Structured workflow across full novel +- Growing knowledge base from analyses +- Genre-specific guidance +- Agents remember your story architecture +- Specialized personas for different tasks +- Systematic craft development + +## Roadmap + +Planned features: +- Automated continuity tracking +- Character relationship graphs +- Timeline visualization +- Pacing heat maps +- Style consistency checker +- Comparative draft analysis +- Agent "memories" of previous sessions + +## Credits + +Built on the BMAD Method framework by @bmadcode. + +NWS created for authors who want to learn craft while writing, not just generate text. + +## License + +MIT License - Free and open source + +--- + +**Start writing better by understanding how great writing works.** diff --git a/src/modules/nws/knowledge/genre-conventions.md b/src/modules/nws/knowledge/genre-conventions.md new file mode 100644 index 000000000..a1b169dc2 --- /dev/null +++ b/src/modules/nws/knowledge/genre-conventions.md @@ -0,0 +1,375 @@ +# Genre Conventions Reference + +Understanding what readers expect in each genre - and when to subvert those expectations. + +## Mystery/Thriller + +### Core Requirements +- **Central mystery/question**: What happened? Who did it? Why? +- **Clues and red herrings**: Fair play - reader should be able to solve it +- **Rising tension**: Stakes escalate, danger increases +- **Satisfying revelation**: Solution must be logical, surprising yet inevitable + +### Structure Patterns +- **Act 1**: Crime/mystery introduced, detective/protagonist involved +- **Act 2A**: Investigation, clues gathered, suspects identified +- **Act 2B**: Complications, false solutions, danger to protagonist +- **Act 3**: True solution revealed, confrontation with antagonist + +### Pacing Expectations +- **Fast overall**: No long expository pauses +- **Clue placement**: Regular revelations keep reader engaged +- **Chapter endings**: Cliffhangers, discoveries, setbacks + +### Subgenre Variations +- **Cozy Mystery**: Amateur detective, small town, minimal violence/sex, often humorous +- **Police Procedural**: Realistic investigation methods, ensemble cast +- **Psychological Thriller**: Internal tension, unreliable narrator, twist endings +- **Legal Thriller**: Courtroom drama, lawyer protagonist, procedural elements + +### Common Tropes +- The locked room mystery +- The least likely suspect +- The detective's dark past +- The partner who betrays +- The innocent accused +- The serial pattern + +### Successful Subversions +- Revealing the "who" early, focusing on "why" or "how" +- Unreliable protagonist detective +- No neat resolution (ambiguous endings) +- Multiple valid solutions + +--- + +## Romance + +### Core Requirements +- **Central relationship**: The romance is the main plot, not subplot +- **Emotional arc**: Characters grow through relationship +- **HEA or HFN**: Happily Ever After or Happy For Now ending +- **Satisfying payoff**: Relationship problems resolved, couple together + +### Structure Patterns (Romance Beat Sheet) +- **Meet-cute**: Memorable first meeting +- **Attraction**: Immediate chemistry but obstacles +- **First kiss/intimate moment**: Relationship escalates +- **Conflict**: Internal (fears/flaws) or external (circumstances) +- **Black moment**: Relationship seems doomed +- **Grand gesture**: One character proves their love +- **Resolution**: Together, happy + +### Pacing Expectations +- **Slow burn vs fast burn**: Genre-dependent +- **Intimate scenes**: Frequency and explicitness vary by heat level +- **Emotional intensity**: Regular emotional beats, not constant + +### Subgenre Variations +- **Contemporary**: Modern setting, realistic problems +- **Historical**: Period-accurate, societal constraints as conflict +- **Paranormal**: Supernatural elements, fated mates common +- **Romantic Suspense**: External danger plot + romance +- **Sweet/Inspirational**: Minimal physical intimacy, faith themes + +### Heat Levels +- **Sweet**: Closed door (no sex on page) +- **Steamy**: Some intimate scenes +- **Erotic**: Explicit, frequent intimate scenes central to plot + +### Common Tropes +- Enemies to lovers +- Friends to lovers +- Forced proximity +- Forbidden love +- Second chance romance +- Fake relationship +- Opposites attract + +### Reader Expectations +- Both characters must be developed, not just protagonist +- Obstacles must be meaningful and believable +- Resolution must come from character growth, not external fixes +- No cheating (if in committed relationship) +- Consent is essential + +--- + +## Science Fiction + +### Core Requirements +- **Speculative element**: "What if?" about technology, society, or science +- **Consistent world rules**: Internal logic must hold +- **Ideas explored**: SF is about concepts, not just setting +- **Grounded in plausibility**: Even if far future, based on extrapolation + +### Structure Patterns +- **World introduction**: Establish rules early +- **Idea exploration**: Implications of the speculative element +- **Personal stakes**: How it affects individuals +- **Thematic resolution**: Comment on contemporary issues through SF lens + +### Pacing Expectations +- **Hard SF**: Slower, idea-heavy, technical detail +- **Space Opera**: Faster, adventure-focused, broader strokes +- **Character vs idea balance**: Varies by subgenre + +### Subgenre Variations +- **Hard SF**: Rigorous science, technical accuracy, problem-solving +- **Space Opera**: Epic scope, adventure, often series +- **Cyberpunk**: Near future, technology-society critique, dystopian +- **Post-Apocalyptic**: After civilization collapse, survival +- **Time Travel**: Paradoxes, alternate timelines, consequences + +### World-Building Depth +- **Technology**: How it works (level of detail varies) +- **Society**: How technology changed culture +- **Economics**: How people make living +- **Politics**: Power structures +- **Daily life**: What's different for ordinary people + +### Common Themes +- Humanity's relationship with technology +- First contact and communication +- Identity and consciousness +- Power and control +- Progress vs tradition +- Individual vs collective + +### Successful Subversions +- Low-tech SF (focus on social speculation) +- SF about ordinary people (not heroes) +- Optimistic futures (counter to dystopia trend) + +--- + +## Fantasy + +### Core Requirements +- **Magic/supernatural**: Core to plot, not decoration +- **World-building**: Consistent magical rules and world logic +- **High stakes**: Often save-the-world scope (though can be smaller) +- **Hero's journey**: Often follows quest structure + +### Structure Patterns +- **World introduction**: Establish setting and magic system +- **Call to adventure**: Protagonist drawn into larger conflict +- **Training/gathering allies**: Power growth, team building +- **Escalating conflicts**: Battles, revelations +- **Final confrontation**: Use of full power/knowledge + +### Pacing Expectations +- **Epic Fantasy**: Slower, detailed world-building, longer books +- **Urban Fantasy**: Faster, contemporary setting, shorter +- **First book**: More world-building, setup +- **Series**: Increasing pace as world is established + +### Subgenre Variations +- **High/Epic Fantasy**: Secondary world, quest, chosen one +- **Urban Fantasy**: Contemporary world + magic, often first person +- **Grimdark**: Morally gray, brutal, cynical +- **Cozy Fantasy**: Low stakes, slice-of-life, hopeful +- **Sword & Sorcery**: Adventure-focused, episodic + +### Magic System Types +- **Hard magic**: Clearly defined rules (Brandon Sanderson style) +- **Soft magic**: Mysterious, not fully explained (Tolkien style) +- **Cost-based**: Magic requires sacrifice/price +- **Source-based**: External power source needed + +### World-Building Elements +- **Geography**: Maps, distances, climate +- **Cultures**: Different peoples, languages, customs +- **History**: Events that shaped the world +- **Magic**: How it works, who can use it, limits +- **Politics**: Power structures, conflicts +- **Economics**: How trade works + +### Common Tropes +- The chosen one +- Coming of age +- Found family +- Ancient evil returns +- Magic academy +- Portal to another world +- Dragons + +### Successful Subversions +- Deconstruct chosen one (The Magicians) +- Ordinary people, not heroes +- Magic as science/technology +- Small-scale, personal stakes +- Failed prophecies + +--- + +## Literary Fiction + +### Core Requirements +- **Character interiority**: Deep psychological exploration +- **Prose quality**: Language and style are paramount +- **Thematic depth**: Exploring meaningful questions about human experience +- **Ambiguity**: Complexity, not neat resolutions + +### Structure Patterns +- **Often nonlinear**: Flashbacks, multiple timelines +- **Character arc over plot**: Internal change is the story +- **Slice of life**: May not have traditional dramatic structure +- **Quiet moments matter**: Small revelations, subtle shifts + +### Pacing Expectations +- **Slower**: Time for reflection, description, interiority +- **Varies widely**: No strict rules +- **Reader patience**: Literary readers accept less action + +### Focus Areas +- **Prose style**: Distinctive voice, carefully crafted sentences +- **Character psychology**: Why people do things, internal contradictions +- **Social commentary**: Class, race, gender, society +- **Philosophical questions**: Meaning, morality, existence +- **Emotional truth**: Authentic human experience + +### Common Themes +- Identity and belonging +- Family dynamics +- Loss and grief +- Memory and time +- Love and relationship +- Coming of age +- Social injustice +- Alienation + +### Literary Devices +- **Symbolism**: Objects/events with deeper meaning +- **Motifs**: Recurring elements +- **Unreliable narration**: Perspective shapes reality +- **Stream of consciousness**: Character's thoughts directly +- **Metafiction**: Awareness of being fiction + +### Reader Expectations +- **No formula**: Literary fiction breaks rules +- **Ambiguous endings**: Not everything resolved +- **Challenging**: May be difficult or uncomfortable +- **Beautifully written**: Language matters as much as story +- **Character over plot**: Plot serves character development + +--- + +## Horror + +### Core Requirements +- **Fear response**: Must genuinely unsettle/scare reader +- **Threat**: Something dangerous (physical, psychological, supernatural) +- **Vulnerability**: Characters in real danger +- **Atmosphere**: Dread, tension, unease + +### Structure Patterns +- **Normal world**: Establish baseline +- **Intrusion**: Horror element enters +- **Escalation**: Threat increases, characters in more danger +- **Revelation**: Nature of threat revealed (or not) +- **Confrontation**: Face the horror +- **Resolution**: Survival or defeat (often ambiguous) + +### Pacing Techniques +- **Slow burn**: Build dread gradually +- **Shock moments**: Sudden scares punctuate tension +- **Withholding**: Don't show the monster immediately +- **Atmospheric**: Sustain unease between events + +### Subgenre Variations +- **Gothic**: Atmospheric, psychological, romantic elements +- **Slasher**: Serial killer, body count, survival +- **Cosmic Horror**: Incomprehensible entities, existential dread +- **Psychological**: Mind-based horror, gaslighting, paranoia +- **Body Horror**: Physical transformation, disease, mutation + +### Fear Techniques +- **The Unknown**: Suggestion scarier than explicit +- **Isolation**: Cut off from help +- **Powerlessness**: Can't fight or escape effectively +- **Violation**: Personal space, body, mind invaded +- **Inevitability**: Can't be stopped +- **Wrongness**: Something fundamentally not right + +### Common Monsters/Threats +- Ghosts and spirits +- Vampires +- Zombies +- Serial killers +- Demons +- Cosmic entities +- Possessed objects +- Psychological breakdown + +### Effective Horror Writing +- **Sensory details**: Make reader feel it +- **Build tension**: Delay gratification +- **Character vulnerability**: Make reader care +- **Atmosphere**: Every scene contributes to mood +- **Respect the reader**: Earn scares, don't rely on gross-out + +--- + +## Historical Fiction + +### Core Requirements +- **Historical accuracy**: Research-based details +- **Period authenticity**: Language, customs, technology +- **Historical events**: Real events as backdrop or plot +- **Immersion**: Transport reader to another time + +### Structure Patterns +- Follows general fiction structure +- Historical events often provide external plot +- Character arc shows period-specific growth/constraints + +### Research Requirements +- **Daily life**: What people ate, wore, did +- **Social structure**: Class, gender, race dynamics +- **Technology**: What existed, what didn't +- **Language**: Avoiding anachronisms +- **Historical events**: Accurate timeline and facts +- **Geography**: Period-accurate locations + +### Subgenre Variations +- **Historical Romance**: Love story in historical setting +- **Historical Mystery**: Detective in past era +- **Historical Fantasy**: Real history + magic +- **Biographical**: Fictionalized real person's life +- **Alternate History**: "What if?" historical changes + +### Balancing Acts +- **Accuracy vs Readability**: Pure period dialogue can be dense +- **Info-dump vs Context**: Provide history without lectures +- **Modern sensibilities**: Acknowledge period attitudes without endorsing +- **Detail level**: Enough to immerse, not overwhelm + +### Common Mistakes +- Anachronistic language ("OK" in 1800s) +- Modern attitudes in historical characters +- Over-researched showing off (everything you know on page) +- Ignoring uncomfortable historical realities +- Generic "ye olde" feel instead of specific period + +--- + +## Cross-Genre Expectations + +### Combining Genres +Many books blend genres (romantic suspense, sci-fi mystery, etc.). Must satisfy expectations of BOTH: +- **Romance + Mystery**: Relationship arc + solve the crime +- **Fantasy + Romance**: Magic world + love story +- **Horror + Thriller**: Supernatural threat + fast pacing + +### Universal Expectations +Regardless of genre: +- **Compelling characters**: Readers must care +- **Coherent plot**: Cause and effect, not random events +- **Emotional engagement**: Make reader feel something +- **Satisfying resolution**: Not necessarily happy, but complete +- **Professional craft**: Grammar, pacing, structure + +--- + +*Use this guide to understand what readers expect - then decide which conventions to meet and which to subvert.* diff --git a/src/modules/nws/knowledge/narrative-techniques.md b/src/modules/nws/knowledge/narrative-techniques.md new file mode 100644 index 000000000..08281f94e --- /dev/null +++ b/src/modules/nws/knowledge/narrative-techniques.md @@ -0,0 +1,296 @@ +# Narrative Techniques Reference + +A comprehensive guide to core storytelling techniques used across all genres. + +## Show vs Tell + +### Definition +**Show**: Present events through action, dialogue, and sensory details - let readers experience and conclude +**Tell**: Directly state information, emotions, or facts - inform readers explicitly + +### When to Show +- Emotional moments (character feelings, relationship dynamics) +- Key plot events (discoveries, confrontations, decisions) +- Character revealing actions +- Sensory experiences that create atmosphere +- Relationship dynamics + +### When to Tell +- Transitions between scenes +- Time passage +- Backstory or exposition that doesn't warrant full scene +- Minor details needed for clarity +- Summarizing less important events + +### Technique: Show Through... +1. **Action**: "She slammed the door" not "She was angry" +2. **Dialogue**: Character says something revealing +3. **Body language**: "His hands trembled" not "He was nervous" +4. **Sensory details**: What character sees/hears/smells/touches/tastes +5. **Internal reaction**: Thoughts/feelings in character's voice + +### Example +**Telling**: Sarah was nervous about the interview. +**Showing**: Sarah's heel tapped against the tile. She smoothed her skirt for the third time, rehearsing answers she'd already memorized. + +--- + +## POV (Point of View) + +### First Person +**Structure**: I/me/my/we +**Strengths**: Intimacy, voice, immediacy +**Challenges**: Limited knowledge, single perspective +**Best for**: Character-driven stories, unreliable narrators, YA + +**Example**: "I couldn't believe what I was seeing. My hands went numb." + +### Third Person Limited +**Structure**: He/she/they (one character's perspective at a time) +**Strengths**: Intimacy + flexibility, can switch POV between chapters +**Challenges**: Still limited to one consciousness at a time +**Best for**: Most commercial fiction, multiple POV novels + +**Example**: "Sarah couldn't believe what she was seeing. Her hands went numb." + +### Third Person Omniscient +**Structure**: He/she/they (narrator knows all, can enter any mind) +**Strengths**: Flexibility, irony, big-picture view +**Challenges**: Harder to create intimacy, old-fashioned feel +**Best for**: Epic scope stories, ensemble casts, literary fiction + +**Example**: "Sarah couldn't believe what she was seeing, though Tom, watching from across the street, had expected this all along." + +### Deep POV +A subset of third limited that stays very close to character consciousness: +- No filter words ("she saw," "he heard," "she felt") +- Character's vocabulary and sentence structure +- Immediate sensory experience +- Thoughts integrated seamlessly + +**Example**: +- Filter version: "She felt the cold wind on her face" +- Deep POV: "The wind bit her cheeks" + +--- + +## Dialogue Techniques + +### Subtext +Characters say one thing, mean another. The real conversation happens beneath the words. + +**Example**: +"Nice dress," he said. +"My mother picked it out." +"She has good taste." +"She thinks so." + +*Subtext: He's commenting on her lack of independence; she's defensive but won't confront directly.* + +### Character Voice Differentiation +Each character should sound unique through: +- Vocabulary (formal/casual, simple/complex) +- Sentence structure (fragments vs complete sentences) +- Verbal tics or phrases +- Topics they raise +- What they avoid saying + +### Attribution Balance +- **"Said" is invisible**: Don't avoid it +- **Action beats**: "He turned away. 'I can't do this.'" +- **No tag when obvious**: In two-person dialogue, alternate +- **Avoid fancy tags**: whispered/muttered/exclaimed used sparingly + +### Exposition in Dialogue +**Bad**: "As you know, Bob, we've been friends for ten years since we met in college..." +**Good**: Make it natural, relevant, something they'd actually say + +--- + +## Scene Structure + +### Scene vs Sequel +**Scene** (action/external): +- Goal: Character wants something specific +- Conflict: Obstacles prevent easy achievement +- Disaster: Things go wrong, worse than before + +**Sequel** (reaction/internal): +- Reaction: Emotional response to disaster +- Dilemma: What are the options now? +- Decision: Choice that launches next scene + +Alternate scene-sequel for pacing rhythm. + +### Scene Purpose +Every scene must: +1. Advance plot OR +2. Develop character OR +3. Both (ideal) + +If it does neither, cut it. + +### Opening Hook +Start scenes: +- In medias res (in the middle of action) +- With immediate conflict or question +- With character decision/realization +- With sensory detail that creates atmosphere + +Avoid: Weather, waking up, looking in mirror + +### Ending Hook +End scenes/chapters with: +- Cliffhanger (immediate danger) +- Revelation (new information) +- Decision (character commits to action) +- Question (reader wants answer) +- Emotional shift + +--- + +## Foreshadowing + +### Types +1. **Concrete**: Specific object/event mentioned early, pays off later (Chekhov's gun) +2. **Thematic**: Early events echo later patterns +3. **Dialogue**: Character says something that becomes ironic later +4. **Atmospheric**: Mood/weather hints at what's coming +5. **Symbolic**: Images/metaphors that gain meaning + +### Rules +- Must be subtle enough readers don't predict everything +- Must be clear enough readers go "Oh!" when they connect dots +- Plant early, payoff later (not immediately) +- Not every planted detail must payoff (red herrings) + +### Example +Early: "She'd always been afraid of confined spaces. Something about the walls closing in." +Later: Trapped in a literal confined space, but the walls closing in are also her life circumstances. + +--- + +## Character Arc + +### Want vs Need +- **Want**: External, conscious goal (solve the mystery, get the job, win the race) +- **Need**: Internal, what they must learn/become to be fulfilled (trust others, find self-worth, let go of past) + +Arc = Journey from pursuing want → realizing need → fulfilling need (which may or may not give them the want) + +### Arc Types +1. **Positive/Growth**: Character changes, overcomes flaw, gets need +2. **Negative/Fall**: Character refuses to change, succumbs to flaw +3. **Flat**: Character doesn't change, but changes the world around them + +### Flaw/Misbelief +Character believes something false that holds them back: +- "I can only rely on myself" → must learn to trust +- "I'm not worthy of love" → must learn self-acceptance +- "The end justifies the means" → must learn morality matters + +Arc shows them confronting and overcoming this misbelief. + +--- + +## Pacing + +### Techniques for Faster Pacing +- Shorter sentences and paragraphs +- More dialogue, less description +- Action scenes (conflict, movement) +- Higher stakes, ticking clocks +- Revelations and twists +- Chapter breaks at tense moments + +### Techniques for Slower Pacing +- Longer, complex sentences +- Description and atmosphere +- Internal reflection +- Backstory integration +- Sequel scenes (emotional processing) +- World-building + +### Balance +Vary pacing: +- Fast scenes followed by slow (like interval training) +- Gradual escalation (increasing tension toward climax) +- Genre expectations (thriller = mostly fast, literary = more slow) + +--- + +## Sensory Details + +### The Five Senses +Most writers overuse sight. Add: +- **Sound**: What does character hear? +- **Smell**: Most evocative, ties to memory +- **Touch**: Temperature, texture, physical sensation +- **Taste**: Often neglected, powerful for food/kissing/disgust scenes + +### Rules +- Choose specific over generic ("diesel fumes" not "bad smell") +- Use what matters to POV character +- Create atmosphere and emotion +- Don't catalogue all five senses - select meaningfully + +### Example +**Generic**: "The room was nice." +**Specific**: "Sunlight warmed the hardwood floor. The scent of lemon polish lingered, sharp and clean." + +--- + +## Tension Techniques + +### Create Tension Through: +1. **Withholding information**: Reader knows character doesn't +2. **Stakes**: What character stands to lose +3. **Time pressure**: Deadlines, ticking clocks +4. **Conflicting goals**: Characters at cross-purposes +5. **Unresolved questions**: Mysteries, unanswered questions +6. **Character in jeopardy**: Physical, emotional, social +7. **Difficult choices**: Dilemmas with no good option + +### Sustaining Tension +- Answer one question, raise another +- Small victories lead to bigger problems +- Escalate stakes progressively +- Give character brief respite before next challenge +- Keep outcome genuinely uncertain + +--- + +## Revision Principles + +### First Draft +- Permission to be imperfect +- Get the story down +- Discovery writing allowed +- Momentum over quality + +### Second Draft (Developmental) +- Fix plot holes and pacing issues +- Strengthen character arcs +- Cut scenes that don't serve story +- Reorganize if needed +- Ensure thematic coherence + +### Third Draft (Line Level) +- Sharpen prose +- Vary sentence structure +- Cut redundancy +- Strengthen voice +- Show more, tell less + +### Final Draft (Copy Edit) +- Grammar and punctuation +- Consistency (names, details, timeline) +- Typos +- Formatting + +### Kill Your Darlings +If it doesn't serve the story, cut it - even if you love the writing. + +--- + +*This is a living document. As you analyze texts and extract techniques, this knowledge base grows.* diff --git a/src/modules/nws/module.yaml b/src/modules/nws/module.yaml new file mode 100644 index 000000000..9f6cd9c21 --- /dev/null +++ b/src/modules/nws/module.yaml @@ -0,0 +1,7 @@ +module: + code: "nws" + name: "Novel Writing Suite" + description: "AI-powered novel writing framework with text analysis, structured planning, and iterative drafting workflows" + version: "1.0.0" + default_selected: false + config_variables: [] diff --git a/src/modules/nws/workflows/analyze-text/workflow.md b/src/modules/nws/workflows/analyze-text/workflow.md new file mode 100644 index 000000000..8425036af --- /dev/null +++ b/src/modules/nws/workflows/analyze-text/workflow.md @@ -0,0 +1,233 @@ +# Analyze Text Workflow + +## Purpose +Perform deep literary analysis on uploaded texts to extract techniques, patterns, and insights that can be applied to your own writing. + +## When to Use +- Studying a published novel you admire +- Analyzing a bestseller in your genre +- Learning from a particular author's style +- Understanding why a book works (or doesn't) +- Building your technique library +- Comparing your draft to published work + +## Prerequisites +- Text file to analyze (.txt, .md, .docx, or .pdf) +- At least 1,000 words (ideally a full chapter or more) + +## Workflow Steps + +### Step 1: Upload Text +You'll be prompted to upload the text file you want analyzed. + +**Supported formats:** +- Plain text (.txt) +- Markdown (.md) +- Word documents (.docx) +- PDF (text-based, not scanned images) + +**Optimal length:** +- Single chapter: 2,000-5,000 words +- Multiple chapters: 10,000-25,000 words +- Full novel: Any length (analysis will focus on key sections) + +### Step 2: Select Analysis Type +Choose the depth and focus of analysis: + +#### Full Analysis (15-20 minutes) +Complete analysis across all dimensions: +- Structural breakdown +- Character analysis +- Prose metrics +- Technique extraction +- Genre comparison + +**Best for:** Learning comprehensively from a text + +#### Structural Only (8-10 minutes) +Focus on: +- Plot points and act structure +- Pacing analysis +- Chapter organization +- Scene sequencing + +**Best for:** Understanding story architecture + +#### Character Focus (8-10 minutes) +Focus on: +- Character arcs +- Characterization techniques +- Dialogue and voice +- Relationship dynamics + +**Best for:** Learning character development + +#### Prose Analysis (8-10 minutes) +Focus on: +- Sentence structure and variety +- Word choice patterns +- Figurative language +- Rhythm and flow +- Show vs tell balance + +**Best for:** Improving prose craft + +#### Quick Overview (5 minutes) +High-level assessment: +- Genre identification +- Major strengths +- Key techniques worth studying +- Overall impressions + +**Best for:** Deciding if you want full analysis later + +### Step 3: Perform Analysis +The Librarian will analyze the text according to your chosen type, following the systematic protocol in the instructions document. + +**What happens:** +- Text is read and annotated +- Patterns are identified +- Examples are quoted +- Metrics are calculated +- Comparisons are made to genre conventions + +### Step 4: Extract Techniques +Specific techniques are identified and documented: +- What the technique is +- How it's used in this text +- Why it works +- When to use it +- How to apply it to your work + +### Step 5: Generate Recommendations +You'll receive: +- **Top learnings**: 3-5 key takeaways +- **Application suggestions**: How to use these in your novel +- **Practice exercises**: Ways to develop these skills +- **Further study**: Related techniques to explore + +### Step 6: Save Results +The complete analysis is saved to: +`_bmad/_memory/librarian-sidecar/knowledge/analyzed-texts/{title}-analysis.md` + +Extracted techniques are also cataloged in the technique patterns library for future reference. + +### Step 7: Next Steps +You'll be offered options: +1. **Apply to your novel**: Use these techniques in your current project +2. **Compare texts**: Analyze another text and compare approaches +3. **Generate exercises**: Practice the techniques you learned +4. **Deep dive**: Explore a specific technique in more detail +5. **Archive**: Simply save for future reference + +## Output Examples + +### Structural Analysis Output +``` +## Plot Structure Analysis + +**Inciting Incident** (12%, p. 23) +Protagonist discovers the letter that changes everything. +*Technique*: Delayed inciting incident allows character establishment first. + +**First Plot Point** (27%, p. 51) +Decision to investigate despite warnings. +*Technique*: Active choice by protagonist (agency, not passive reaction). + +**Midpoint** (48%, p. 97) +False victory - thinks mystery is solved, but discovers deeper conspiracy. +*Technique*: Midpoint reversal that raises stakes and changes direction. + +**All Is Lost** (76%, p. 152) +Ally betrayal + evidence destroyed + deadline missed. +*Technique*: Triple-layered disaster for maximum impact. + +**Climax** (91%, p. 182) +Confrontation where truth revealed through character strength, not luck. +*Technique*: Resolution emerging from character arc (internal + external climax). +``` + +### Character Analysis Output +``` +## Protagonist: Sarah Chen + +**Want**: Solve the murder to restore her reputation +**Need**: Learn to trust others and accept help +**Flaw**: Hyper-independence stemming from childhood abandonment +**Arc**: Closed/growth arc (changes by accepting partnership) + +**Characterization Techniques:** +1. *Action before description*: First appearance shows her solving a puzzle, establishing competence before physical details +2. *Contradictions*: Brilliant detective + messy personal life = dimensional character +3. *Dialogue voice*: Clipped sentences, technical jargon, humor as deflection +4. *Internal conflict*: Constant tension between wanting to go alone vs needing help + +**Application**: Notice how author establishes competence first, flaws second - creates respect before sympathy. +``` + +### Prose Analysis Output +``` +## Sentence Metrics +- Average sentence length: 14.2 words +- Range: 3-38 words +- Variety: High (simple, compound, complex well-balanced) + +## Dialogue Ratio +- 42% dialogue, 58% narrative +- Attribution: 70% action beats, 30% "said" tags +- Subtext frequency: High (characters rarely say what they mean directly) + +## Show vs Tell +- Estimated 75% showing, 25% telling +- Telling used for: transitions, backstory, time passage +- Showing used for: character emotion, relationship dynamics, key reveals + +## Application Insights +1. Sentence variety creates rhythm (short for impact, long for complexity) +2. Heavy action-beat attribution keeps scenes visual and kinetic +3. Telling isn't bad - it's used strategically for efficiency +``` + +## Tips for Better Results + +### Before Upload +- **Choose the right sample**: Full chapters work better than fragments +- **Quality matters**: Published, edited work gives clearer technique signals +- **Know your goal**: What specifically do you want to learn? + +### During Analysis +- **Be patient**: Quality analysis takes time +- **Ask questions**: If something is unclear, request elaboration +- **Request examples**: Ask for specific quotes demonstrating techniques + +### After Analysis +- **Apply immediately**: Try one technique in your current chapter +- **Build incrementally**: Master one technique before adding another +- **Revisit**: Analysis reports deepen with multiple readings + +## Common Questions + +**Q: Can I analyze my own work?** +A: Yes! The Editor agent is better for critique, but Librarian can analyze your techniques objectively. + +**Q: How many texts should I analyze?** +A: Quality over quantity. Deep analysis of 5-10 texts in your genre > superficial analysis of 50. + +**Q: Can I compare two different books?** +A: Yes! Use the "Compare texts" menu option for side-by-side analysis. + +**Q: What if the text is in another language?** +A: Currently English only. Translation quality would affect analysis accuracy. + +**Q: Can I analyze short stories or novellas?** +A: Absolutely. Shorter works can reveal technique more clearly. + +## Related Workflows +- **Compare Texts**: Side-by-side analysis of two texts +- **Extract Techniques**: Deep dive on a specific technique +- **Genre Analysis**: Build your genre convention database +- **Apply to Novel**: Use analyzed techniques in your work + +--- + +*Remember: Analysis is not about copying - it's about understanding craft principles you can apply in your own voice.* diff --git a/src/modules/nws/workflows/analyze-text/workflow.yaml b/src/modules/nws/workflows/analyze-text/workflow.yaml new file mode 100644 index 000000000..1a21d2ab0 --- /dev/null +++ b/src/modules/nws/workflows/analyze-text/workflow.yaml @@ -0,0 +1,47 @@ +workflow: + id: "analyze-text" + name: "Analyze Text" + description: "Deep analysis of uploaded novel or manuscript to extract techniques and insights" + agent: "librarian" + module: "nws" + version: "1.0.0" + + inputs: + - id: "text_file" + type: "file" + description: "The text to analyze (.txt, .md, .docx)" + required: true + + - id: "analysis_type" + type: "choice" + description: "Type of analysis to perform" + required: true + options: + - "full" + - "structural" + - "character" + - "prose" + - "quick" + + outputs: + - id: "analysis_report" + type: "file" + path: "_bmad/_memory/librarian-sidecar/knowledge/analyzed-texts/{filename}-analysis.md" + description: "Complete analysis report" + + - id: "extracted_techniques" + type: "data" + description: "List of techniques identified" + + - id: "recommendations" + type: "data" + description: "How to apply these insights" + + steps: + - upload + - select_analysis_type + - perform_analysis + - extract_techniques + - generate_recommendations + - save_results + - offer_next_steps diff --git a/src/modules/nws/workflows/create-character-profiles/workflow.yaml b/src/modules/nws/workflows/create-character-profiles/workflow.yaml new file mode 100644 index 000000000..c8ee2f4d1 --- /dev/null +++ b/src/modules/nws/workflows/create-character-profiles/workflow.yaml @@ -0,0 +1,29 @@ +workflow: + id: "create-character-profiles" + name: "Create Character Profiles" + description: "Develop detailed character sheets with arcs, motivations, relationships, and voice" + agent: "atlas" + module: "nws" + version: "1.0.0" + + inputs: + - id: "story_brief" + type: "file" + path: "docs/story-brief.md" + required: true + + outputs: + - id: "character_profiles" + type: "file" + path: "docs/character-profiles.md" + description: "Detailed character profiles for all major characters" + + steps: + - identify_main_characters + - develop_protagonist + - develop_antagonist + - develop_supporting_cast + - map_relationships + - define_character_arcs + - establish_voices + - create_document diff --git a/src/modules/nws/workflows/create-story-brief/workflow.yaml b/src/modules/nws/workflows/create-story-brief/workflow.yaml new file mode 100644 index 000000000..c1ec19dd8 --- /dev/null +++ b/src/modules/nws/workflows/create-story-brief/workflow.yaml @@ -0,0 +1,22 @@ +workflow: + id: "create-story-brief" + name: "Create Story Brief" + description: "Develop the foundational document defining your story's premise, conflict, themes, and goals" + agent: "sage" + module: "nws" + version: "1.0.0" + + outputs: + - id: "story_brief" + type: "file" + path: "docs/story-brief.md" + description: "Complete story brief document" + + steps: + - brainstorm_premise + - identify_central_conflict + - define_themes + - set_goals_and_non_goals + - risk_analysis + - define_audience + - create_document diff --git a/src/modules/nws/workflows/design-plot-structure/workflow.yaml b/src/modules/nws/workflows/design-plot-structure/workflow.yaml new file mode 100644 index 000000000..0554bb57e --- /dev/null +++ b/src/modules/nws/workflows/design-plot-structure/workflow.yaml @@ -0,0 +1,32 @@ +workflow: + id: "design-plot-structure" + name: "Design Plot Structure" + description: "Map your story to a proven framework and create act-by-act outline" + agent: "atlas" + module: "nws" + version: "1.0.0" + + inputs: + - id: "story_brief" + type: "file" + path: "docs/story-brief.md" + required: true + - id: "character_profiles" + type: "file" + path: "docs/character-profiles.md" + required: true + + outputs: + - id: "plot_outline" + type: "file" + path: "docs/plot-outline.md" + description: "Complete plot structure with beats and turning points" + + steps: + - choose_framework + - identify_key_beats + - map_acts + - plan_subplots + - create_scene_list + - plan_pacing + - create_document diff --git a/src/modules/nws/workflows/write-chapter/workflow.yaml b/src/modules/nws/workflows/write-chapter/workflow.yaml new file mode 100644 index 000000000..4fc729470 --- /dev/null +++ b/src/modules/nws/workflows/write-chapter/workflow.yaml @@ -0,0 +1,41 @@ +workflow: + id: "write-chapter" + name: "Write Chapter" + description: "Draft a chapter following your architecture, character profiles, and narrative voice" + agent: "scribe" + module: "nws" + version: "1.0.0" + + inputs: + - id: "plot_outline" + type: "file" + path: "docs/plot-outline.md" + required: true + - id: "character_profiles" + type: "file" + path: "docs/character-profiles.md" + required: true + - id: "narrative_architecture" + type: "file" + path: "docs/narrative-architecture.md" + required: false + - id: "chapter_number" + type: "number" + description: "Which chapter to write" + required: true + + outputs: + - id: "chapter_draft" + type: "file" + path: "chapters/chapter-{number}.md" + description: "Completed chapter draft" + + steps: + - review_outline_for_chapter + - identify_pov_character + - define_scene_goals + - draft_opening + - draft_body + - draft_closing + - continuity_check + - save_chapter diff --git a/tools/cli/external-official-modules.yaml b/tools/cli/external-official-modules.yaml index d6ae06ee6..31e87e006 100644 --- a/tools/cli/external-official-modules.yaml +++ b/tools/cli/external-official-modules.yaml @@ -42,6 +42,16 @@ modules: type: bmad-org npmPackage: bmad-method-test-architecture-enterprise + bmad-novel-writing-suite: + url: https://github.com/bmad-code-org/bmad-novel-writing-suite + module-definition: src/module.yaml + code: nws + name: "Novel Writing Suite" + description: "AI-powered novel writing with text analysis" + npm_package: "bmad-novel-writing-suite" + github_repo: "fsandx/bmad-novel-writing-suite" + default_selected: false + # whiteport-design-system: # url: https://github.com/bmad-code-org/bmad-method-wds-expansion # module-definition: src/module.yaml