cc-agentic-framework 1.14.1

package/framework/modules/writer/skills/writer/building-worlds/SKILL.md

@@ -0,0 +1,313 @@
+---
+id: building-worlds
+module: writer
+name: building-worlds
+description: Design fantasy worlds with coherent magic systems, cultures, history, and geography. Project-agnostic principles from Sanderson, Tolkien, Jemisin, Le Guin, and Martin.
+scope: framework
+capabilities-provided:
+  - world-design
+  - magic-system-design
+  - culture-building
+  - consistency-enforcement
+---
+
+# Skill: Building Worlds
+
+**Purpose:** Design coherent fantasy worlds with internally consistent magic, cultures, geography, and history.
+
+**Version:** 1.0.0
+
+**Scope:** Framework-level (project-agnostic)
+
+---
+
+## When to Use This Skill
+
+- Designing or refining magic systems
+- Creating cultures and societies
+- Building historical timelines
+- Designing geography and environment
+- Ensuring world consistency across a series
+- Planning information revelation to readers
+
+**Do NOT use for:**
+- File organization (use `organizing-books`)
+- Prose style and writing craft (use `writing-prose`)
+- Character development (separate concern)
+
+---
+
+## Core Philosophy
+
+### The Three Pillars of World-Building
+
+| Pillar | Source | Principle |
+|--------|--------|-----------|
+| **Depth Over Density** | Sanderson | Expand what exists before adding new elements |
+| **Internal Logic** | Tolkien | Every element connects to world's core truth |
+| **Grounded Fantasy** | Jemisin | Anchor magic in something tangible and real |
+
+### The Master World-Builders
+
+**Brandon Sanderson** - The Architect
+- Hard magic systems with clear rules
+- Three Laws of Magic
+- "Worldbuilder's disease" prevention
+- Limitations create story, not powers
+
+**J.R.R. Tolkien** - The Subcreator
+- Internal consistency as primary virtue
+- Language shapes culture shapes history
+- Myth and legend as world memory
+- Depth through implication, not exposition
+
+**N.K. Jemisin** - The Grounder
+- Anchor magic in tangible concepts (geology, physics)
+- Oppression systems with real-world logic
+- Magic costs reflect real sacrifices
+- Theme and world are inseparable
+
+**Ursula K. Le Guin** - The Anthropologist
+- Cultures as complete systems
+- Economics shapes society
+- Maps reveal world logic
+- Every custom has origin
+
+**George R.R. Martin** - The Gardener
+- Discover world through writing
+- Consequences as world-building
+- Political complexity
+- Character-driven revelation
+
+---
+
+## The Architect-Gardener Spectrum
+
+| Approach | Best For | Risk |
+|----------|----------|------|
+| **Pure Architect** | Hard magic, mystery plots | Sterile, over-planned |
+| **Hybrid** (Recommended) | Most fantasy | Requires discipline |
+| **Pure Gardener** | Character-driven stories | Inconsistency, retcons |
+
+**Hybrid Approach:**
+1. Plan foundation (magic rules, core history, geography)
+2. Discover details through writing (customs, minor characters)
+3. Lock rules once established (use immutability system)
+
+---
+
+## The World-Building Pyramid
+
+Build from bottom to top. Each layer depends on those below.
+
+```
+        /\
+       /  \  POLISH
+      /    \  Minor customs, regional variations
+     /------\
+    /        \  DETAIL
+   /          \  Cultures, economics, religion
+  /------------\
+ /              \  STRUCTURE
+/                \  Geography, major history, power systems
+------------------
+    FOUNDATION
+    Core premise, magic rules, physical laws
+```
+
+### Layer 1: Foundation (Establish First)
+
+**Must define before writing:**
+- Core world premise/conflict
+- Magic system rules (if magic exists)
+- Physical laws that differ from reality
+- What makes this world unique
+
+**Questions to answer:**
+- What is the one thing readers must understand?
+- What rules can never be broken?
+- What distinguishes this from generic fantasy?
+
+### Layer 2: Structure (Build on Foundation)
+
+**Define early, refine as needed:**
+- Continental geography and climate
+- Major historical events (world-shaping)
+- Power structures (who rules, why)
+- Major factions and their relationships
+
+### Layer 3: Detail (Fill in as Needed)
+
+**Develop when story requires:**
+- Specific cultures and customs
+- Economic systems and trade
+- Religious beliefs and practices
+- Daily life details
+
+### Layer 4: Polish (Discover Through Writing)
+
+**Let these emerge organically:**
+- Minor customs and superstitions
+- Regional dialect variations
+- Character-specific knowledge
+- Small-scale traditions
+
+---
+
+## Sanderson's Three Laws of Magic
+
+### First Law: Understanding = Satisfaction
+
+> "An author's ability to solve conflict with magic is directly proportional to how well the reader understands said magic."
+
+| Magic Type | Reader Understanding | Problem-Solving Role |
+|------------|---------------------|---------------------|
+| **Hard Magic** | High (rules clear) | Can solve problems directly |
+| **Soft Magic** | Low (mysterious) | Creates wonder, complicates problems |
+| **Hybrid** | Partial | Strategic use of both |
+
+**Implication:** If magic solves the climax, readers must understand how it works beforehand.
+
+### Second Law: Limitations > Powers
+
+> "Weaknesses, limits, and costs are more interesting than powers."
+
+**Types of Limitations:**
+- **Costs:** What you pay to use magic (energy, health, sanity, materials)
+- **Weaknesses:** What makes you vulnerable (kryptonite-style)
+- **Scope Limits:** What magic cannot affect
+
+**The Superman Test:** What makes Superman interesting?
+1. His code of ethics (self-imposed limit)
+2. Kryptonite (external weakness)
+
+Without limits, there's no story.
+
+### Third Law: Expand Before Adding
+
+> "Before adding something new to your magic, see if you can expand what you already have."
+
+**Depth beats breadth.** One well-developed power system is more satisfying than ten shallow ones.
+
+**Signs of Worldbuilder's Disease:**
+- Adding new magic types to solve each problem
+- Endless list of abilities with no depth
+- Readers can't track what's possible
+
+---
+
+## The Five Consistency Pillars
+
+Maintain these for reader trust. See [CONSISTENCY-PILLARS.md](./CONSISTENCY-PILLARS.md) for details.
+
+| Pillar | Rule | Violation Example |
+|--------|------|-------------------|
+| **Magic Has Costs** | Power requires sacrifice | Free healing with no exhaustion |
+| **Geography Matters** | Distance and terrain are real | Three-week journey in one day |
+| **History Has Weight** | Past shapes present visibly | War 20 years ago, no consequences |
+| **Cultures Have Logic** | Every custom has origin | Random taboos with no reason |
+| **Power Has Limits** | No one is omnipotent | Wizard who could solve everything but doesn't |
+
+---
+
+## The Iceberg Principle
+
+**Show 10%, imply 90%.** The world should feel deeper than what's on the page.
+
+### Above Water (What Readers See)
+- Current events and immediate conflicts
+- Physical details of present locations
+- Active characters and relationships
+- Surface-level cultural practices
+
+### Below Water (What You Know)
+- Deep history beyond what's relevant
+- Distant lands and their politics
+- Complete magical theory
+- Economic systems and trade networks
+- Religious doctrine and philosophy
+
+**Key insight:** You must know the 90% to write the 10% convincingly, but you must NOT put the 90% on the page.
+
+---
+
+## Quick Decision Tables
+
+### Magic System Type Selection
+
+| Story Need | Choose | Why |
+|------------|--------|-----|
+| Protagonist solves problem with magic | Hard | Reader must understand rules |
+| Magic creates atmosphere/wonder | Soft | Mystery enhances immersion |
+| Magic-based conflict/competition | Hard | Clear stakes require clear rules |
+| Magic as metaphor/theme | Soft | Flexibility serves meaning |
+| Training/progression arc | Hard | Measurable growth |
+
+### Culture Complexity Levels
+
+| Story Role | Depth Needed | Development Time |
+|------------|--------------|------------------|
+| Protagonist's home | Deep | Full pyramid |
+| Major faction | Medium | Layers 1-3 |
+| Visited briefly | Surface | Layers 1-2 |
+| Mentioned only | Minimal | One distinct trait |
+
+---
+
+## Anti-Patterns to Avoid
+
+### Worldbuilder's Disease
+**Symptom:** Endless planning, no writing
+**Cure:** Stop when you have enough to start; discover the rest
+
+### The Info-Dump
+**Symptom:** Paragraphs of history/exposition
+**Cure:** Reveal through action, dialogue, discovery
+
+### The Monoculture
+**Symptom:** Entire nation has one personality
+**Cure:** Add regional, class, generational variation
+
+### The Convenient Exception
+**Symptom:** Rules break when plot needs it
+**Cure:** Lock rules; rewrite plot instead
+
+### The Kitchen Sink
+**Symptom:** Every fantasy creature/system included
+**Cure:** Third Law - expand before adding
+
+---
+
+## Progressive Disclosure
+
+Load supporting files as needed:
+
+| File | When to Load |
+|------|--------------|
+| [MAGIC-SYSTEMS.md](./MAGIC-SYSTEMS.md) | Designing/refining magic |
+| [CULTURE-BUILDING.md](./CULTURE-BUILDING.md) | Creating societies |
+| [CONSISTENCY-PILLARS.md](./CONSISTENCY-PILLARS.md) | Checking world logic |
+| [GEOGRAPHY-HISTORY.md](./GEOGRAPHY-HISTORY.md) | Physical world or timeline |
+| [REVELATION-CHECKLIST.md](./REVELATION-CHECKLIST.md) | Planning information reveals |
+
+---
+
+## Integration with Other Skills
+
+| Task | Primary Skill | Supporting |
+|------|--------------|------------|
+| Where to put world files | `organizing-books` | - |
+| How magic feels in prose | `writing-prose` | `building-worlds` |
+| What magic can do | `building-worlds` | - |
+| Dialogue revealing culture | `writing-prose` | `building-worlds` |
+| Cultural consistency | `building-worlds` | - |
+
+---
+
+**Skill Version:** 1.0.0
+
+**Token Budget:** ~2K (this file) + ~8K (supporting files)
+
+**Last Updated:** 2026-01-11
+
+**Research Sources:** Brandon Sanderson (Laws of Magic, 2025 Lectures), J.R.R. Tolkien (On Fairy-Stories, subcreation theory), N.K. Jemisin (Broken Earth craft), Ursula K. Le Guin (Steering the Craft), George R.R. Martin (architect vs gardener)

package/framework/modules/writer/skills/writer/organizing-books/DOMAINS.md

@@ -0,0 +1,212 @@
+---
+title: "Domain Organization Guide"
+type: skill-support
+skill: writer-organizing-books-workflow
+---
+
+# Domain Organization Guide
+
+Complete specifications for the domain-driven world structure.
+
+## Domain Definitions
+
+### History Domain (`world/history/`)
+
+**Purpose:** Everything temporal - eras, events, timeline
+
+**Authority Files:**
+| File | SSOT Topic | Description |
+|------|------------|-------------|
+| `timeline-master.md` | temporal-facts | Complete historical record |
+| `events/*.md` | specific-events | Individual event narratives |
+
+**Subdirectories:**
+- `eras/` - Era descriptions and philosophy
+- `events/` - Individual historical events
+- `diagrams/` - Timeline visualizations (.mmd only)
+
+**Cross-Domain References:**
+- Reference `politics/` for national histories
+- Reference `magic/` for magical history context
+
+---
+
+### Magic Domain (`world/magic/`)
+
+**Purpose:** All magic systems, crystals, power levels
+
+**Authority Files:**
+| File | SSOT Topic | Description |
+|------|------------|-------------|
+| `fundamental-laws.md` | power-levels | 15-level power system |
+| `index.md` | magic-overview | Five schools summary |
+| `crystals/mechanics.md` | crystal-mechanics | How crystals work |
+| `crystals/types.md` | crystal-types | Crystal generations |
+| `crystals/applications.md` | crystal-uses | Devices and infrastructure |
+
+**Subdirectories:**
+- `schools/` - Individual magic school details (arcane, elemental, spiritforge, light, nature)
+- `crystals/` - Crystal technology (mechanics, types, applications)
+- `spellcraft/` - Casting mechanics, spell libraries
+- `diagrams/` - Magic system visualizations (.mmd only)
+
+---
+
+### Politics Domain (`world/politics/`)
+
+**Purpose:** Nations, governments, cultures, political dynamics
+
+**Authority Files:**
+| File | SSOT Topic | Description |
+|------|------------|-------------|
+| `index.md` | politics-overview | Four powers summary |
+| `[nation]/nation.md` | national-identity | Core nation identity |
+| `[nation]/government.md` | governance | Political structure |
+| `[nation]/culture.md` | cultural-facts | Social norms and values |
+
+**Nation Directories:**
+- `arcane-empire/` - Caldris (Arcane State)
+- `trade-league/` - Sunshine Coast (former colonies)
+- `light-dominion/` - Ormyr (faith-state)
+- `vardun-crown/` - Karrak (warrior culture)
+
+**Diagrams:** `diagrams/nations.mmd`
+
+---
+
+### Geography Domain (`world/geography/`)
+
+**Purpose:** Physical world, regions, cities, routes
+
+**Authority Files:**
+| File | SSOT Topic | Description |
+|------|------------|-------------|
+| `index.md` | geography-overview | World map logic |
+| `fourfold-sea.md` | central-trade | Maritime trade theater |
+| `[region]/region.md` | regional-geography | Continental details |
+| `[region]/[city].md` | city-facts | City specifications |
+
+**Region Directories:**
+- `caldris/` - The White Ring (Arcane Empire territory)
+- `sunshine-coast/` - Coinshore (Trade League)
+- `ormyr/` - Light Dominion continent
+- `karrak/` - Vardun Crown territory
+
+**Diagrams:** `diagrams/world-map.mmd`, `diagrams/caldris-map.mmd`
+
+---
+
+### Artifacts Domain (`world/artifacts/`)
+
+**Purpose:** Plot-relevant objects with detailed specifications
+
+**Authority Files:**
+| File | SSOT Topic | Description |
+|------|------------|-------------|
+| `ascendant-crystal.md` | ascendant-artifact | The protagonist's crystal |
+| `sunburst-crystal.md` | sunburst-artifact | Lost prototype |
+| `crimson-crystal.md` | crimson-artifact | Future threat |
+
+---
+
+### Core Domain (`world/core/`)
+
+**Purpose:** Universal rules not specific to other domains
+
+**Files:**
+- `races.md` - Playable races
+- `classes.md` - Magical vocations
+- `languages-calendar.md` - Languages and time
+- `economy.md` - Trade and currency
+- `religion.md` - Faith systems
+- `architecture.md` - Building styles
+- `warfare.md` - Military systems
+
+---
+
+### Creatures Domain (`world/creatures/`)
+
+**Purpose:** Threats and monsters by danger level
+
+**Files:**
+- `overview.md` - Creature classification
+- `common-threats.md` - Everyday dangers
+- `serious-threats.md` - Significant monsters
+- `catastrophic-threats.md` - World-level threats
+
+---
+
+### Transport Domain (`world/transport/`)
+
+**Purpose:** Movement systems and routes
+
+**Files:**
+- `overview.md` - Transport methods
+- `[nation]-routes.md` - Nation-specific systems
+
+---
+
+## Domain Boundary Rules
+
+### What Goes Where
+
+| Content Type | Domain | Example |
+|--------------|--------|---------|
+| When something happened | history | "Iron Peace signed ~100 years ago" |
+| How magic works | magic | "15-level power system" |
+| Who rules where | politics | "Apex Order governs Caldris" |
+| Where things are | geography | "Nexus is coastal" |
+| Plot objects | artifacts | "Ascendant Crystal properties" |
+| Universal rules | core | "Common language exists" |
+
+### Cross-Domain References
+
+When content spans domains, the rule is:
+1. **Primary fact** lives in its natural domain
+2. **Other domains reference** with markdown links
+
+**Example:**
+- Crystal technology → `magic/crystals/`
+- How Trade League uses crystals → `politics/trade-league/nation.md` (references magic)
+- Where crystals are mined → `geography/caldris/region.md` (references magic)
+
+### Diagram Placement
+
+Diagrams live **inside their domain**:
+
+```
+world/history/diagrams/timeline.mmd      # NOT world/diagrams/
+world/magic/diagrams/schools.mmd         # NOT world/diagrams/
+world/politics/diagrams/nations.mmd      # NOT world/diagrams/
+world/geography/diagrams/world-map.mmd   # NOT world/diagrams/
+```
+
+---
+
+## Creating New Domain Content
+
+### Adding a New File
+
+1. Determine correct domain
+2. Choose appropriate subdirectory
+3. Add SSOT frontmatter if authoritative
+4. Reference related files with markdown links
+5. Run `writer validate` to check structure
+
+### Adding a New Subdirectory
+
+1. Ensure it belongs to the domain's purpose
+2. Create `index.md` for navigation
+3. Update domain `index.md` to link new subdirectory
+
+### Moving Content Between Domains
+
+1. Use `git mv` to preserve history
+2. Update all incoming links
+3. Update the file's `domain:` frontmatter
+4. Verify no orphaned references
+
+---
+
+**Version:** 2.0.0
+**Last Updated:** 2026-01-10