cc-agentic-framework 1.14.1

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

@@ -0,0 +1,257 @@
+---
+id: writer-organizing-books-workflow
+module: writer
+name: writer-organizing-books-workflow
+description: Enforce book folder structure with domain-driven organization and single source of truth principles. Use when creating or restructuring book projects, world-building, or validating organization.
+scope: project-specific
+applicable-projects: writer
+capabilities-provided:
+  - book-organization
+  - domain-structure
+  - ssot-enforcement
+cli-commands:
+  init:
+    command: "writer init"
+    description: "Initialize a new book project"
+  create-part:
+    command: "writer create-part"
+    description: "Create a new part (story arc)"
+  create-chapter:
+    command: "writer create-chapter"
+    description: "Create a new chapter"
+  create-scene:
+    command: "writer create-scene"
+    description: "Create a new scene"
+  validate:
+    command: "writer validate"
+    description: "Validate book structure"
+---
+
+# Skill: Book Organization v2
+
+**Skill Name:** writer-organizing-books-workflow
+
+**Type:** Workflow Enforcement
+
+**Purpose:** Enforce domain-driven book organization with single source of truth (SSOT) principles
+
+**Version:** 2.0.0 (SSOT + DDD Hybrid)
+
+---
+
+## When to Use This Skill
+
+- Starting or restructuring book projects
+- Creating manuscript, character, or world files
+- Enforcing SSOT principles (no duplicate facts)
+- Validating domain organization
+- Moving or splitting world files
+
+---
+
+## Quick Start
+
+1. **Use CLI to create structures** - Don't create files manually
+2. **Each fact lives in ONE file** - Mark with `ssot: true` in frontmatter
+3. **Reference with markdown links** - `[text](path.md#anchor)` for cross-references
+4. **Diagrams are visual only** - `.mmd` files contain only Mermaid, no prose
+5. **Domains own their facts** - history/, magic/, politics/, geography/
+
+---
+
+## Core Principles (v2)
+
+### Principle 1: Domain-Driven Organization
+
+World content is organized by **domain**, not by file type:
+
+| Domain | Purpose | Key Files |
+|--------|---------|-----------|
+| `history/` | Everything temporal | `timeline-master.md`, `events/` |
+| `magic/` | All magic systems | `fundamental-laws.md`, `schools/`, `crystals/` |
+| `politics/` | Nations, governments | `arcane-empire/`, `trade-league/` |
+| `geography/` | Physical world | `caldris/`, `fourfold-sea.md` |
+| `artifacts/` | Plot-relevant objects | `ascendant-crystal.md` |
+| `core/` | Universal rules | `races.md`, `economy.md` |
+
+See: [DOMAINS.md](./DOMAINS.md) for complete domain specifications.
+
+### Principle 2: Single Source of Truth (SSOT)
+
+Each fact exists in exactly ONE file:
+
+```yaml
+---
+domain: magic
+ssot: true                    # This file is authoritative
+ssot-topic: crystal-mechanics # For what topic
+---
+```
+
+- **Never duplicate facts** - Reference instead
+- **Mark authority clearly** - Use `ssot: true` for authoritative files
+- **Update one place** - Changes propagate via links
+
+See: [SSOT-RULES.md](./SSOT-RULES.md) for reference patterns.
+
+### Principle 3: Navigatable Links
+
+Cross-references use standard markdown:
+
+```markdown
+See [Crystal Mechanics](../magic/crystals/mechanics.md#recharging) for details.
+```
+
+- Use relative paths
+- Include anchor links for specific sections
+- Works in VitePress, VS Code, and IDEs
+
+### Principle 4: Diagrams Are Visual Only
+
+Diagram files (`.mmd`) contain ONLY Mermaid code:
+
+```
+world/magic/diagrams/
+├── schools.mmd          # Mermaid diagram, no prose
+└── crystal-tech.mmd     # Mermaid diagram, no prose
+```
+
+- No prose descriptions in diagram files
+- Place diagrams inside their domain's `diagrams/` folder
+- Reference source files in frontmatter
+
+### Principle 5: No Baseline Directory
+
+Story opening state lives in **manuscript prerequisites**, not a separate baseline/:
+
+```yaml
+# In manuscript/part-001-the-journey/PART.md
+prerequisites:
+  world-state:
+    time-period: "Crystal Era, ~100 years after Iron Peace"
+    political-climate: "Uneasy peace, Trade League rising"
+  protagonist-state:
+    location: "Ladris, 80km from Nexus"
+    emotional: "Grief with hope and fear"
+```
+
+Character states live in character profiles, not baseline files.
+
+---
+
+## World Structure (v2)
+
+```
+world/
+├── index.md                    # World overview with domain links
+├── history/
+│   ├── index.md
+│   ├── timeline-master.md      # SSOT for temporal facts
+│   ├── diagrams/timeline.mmd
+│   ├── eras/
+│   └── events/
+├── magic/
+│   ├── index.md
+│   ├── fundamental-laws.md     # SSOT for power levels
+│   ├── diagrams/
+│   ├── schools/
+│   ├── crystals/
+│   └── spellcraft/
+├── politics/
+│   ├── index.md
+│   ├── diagrams/nations.mmd
+│   ├── arcane-empire/
+│   ├── trade-league/
+│   ├── light-dominion/
+│   └── vardun-crown/
+├── geography/
+│   ├── index.md
+│   ├── diagrams/
+│   ├── caldris/
+│   └── [other regions]/
+├── artifacts/
+├── core/
+├── creatures/
+└── transport/
+```
+
+See: [FOLDER-STRUCTURE.md](./FOLDER-STRUCTURE.md) for complete layout.
+
+---
+
+## Anti-Patterns (v2)
+
+**Duplicating facts across files**
+- Each fact in ONE file only
+- Reference, don't repeat
+- Fix: Add markdown links to source
+
+**Prose in diagram files**
+- `.mmd` files contain only Mermaid code
+- No explanatory text
+- Fix: Move prose to domain index or source file
+
+**Baseline files for story state**
+- No separate `baseline/` directory
+- Fix: Use manuscript prerequisites for world state
+- Fix: Use character profiles for character state
+
+**Cross-domain fact ownership**
+- Each domain owns its facts completely
+- Fix: Crystal mechanics → magic domain
+- Fix: National history → politics domain (reference history)
+
+**Creating files without CLI**
+- Loses auto-numbering consistency
+- Fix: Always use `writer create-*` commands
+
+---
+
+## Enforcement Checklist (v2)
+
+**When creating world files:**
+- [ ] File belongs to correct domain
+- [ ] Authority files have `ssot: true`
+- [ ] Cross-references use markdown links
+- [ ] No duplicate facts from other files
+- [ ] Diagram files contain only Mermaid
+
+**When modifying facts:**
+- [ ] Change in the SSOT file only
+- [ ] Update links if path changes
+- [ ] Run `writer validate` after changes
+
+**When restructuring:**
+- [ ] Use `git mv` to preserve history
+- [ ] Update all relative links
+- [ ] Verify diagrams moved to domain folders
+- [ ] No baseline/ directory exists
+
+---
+
+## Progressive Disclosure
+
+This skill uses progressive disclosure. Load supporting files as needed:
+
+- [DOMAINS.md](./DOMAINS.md) - Complete domain specifications
+- [SSOT-RULES.md](./SSOT-RULES.md) - Single source of truth patterns
+- [FOLDER-STRUCTURE.md](./FOLDER-STRUCTURE.md) - Complete folder layout
+- [METADATA-GUIDE.md](./METADATA-GUIDE.md) - YAML frontmatter specifications
+- [IMMUTABILITY-GUIDE.md](./IMMUTABILITY-GUIDE.md) - Mutability control system
+
+---
+
+**Skill Version:** 2.0.0
+
+**Module Version:** v2.0.0
+
+**Token Budget:** ~2.5K (SKILL.md ~1.5K + supporting docs ~1K)
+
+**Last Updated:** 2026-01-10
+
+**Changes from v1:**
+- Added domain-driven organization
+- Added SSOT principles
+- Removed baseline directory support
+- Diagrams moved into domains
+- Added navigatable link requirements

package/framework/modules/writer/skills/writer/organizing-books/SSOT-RULES.md

@@ -0,0 +1,214 @@
+---
+title: "Single Source of Truth Rules"
+type: skill-support
+skill: writer-organizing-books-workflow
+---
+
+# Single Source of Truth (SSOT) Rules
+
+Guidelines for maintaining one authoritative source for each fact.
+
+## The Core Principle
+
+**Each fact exists in exactly ONE file.** All other mentions reference that file.
+
+### What Counts as a Fact?
+
+| Is a Fact | Not a Fact |
+|-----------|------------|
+| "Iron Peace signed ~100 years ago" | Narrative mention in manuscript |
+| "Ascendant Crystal is self-sustaining" | Character's speculation about it |
+| "Nexus is 80km from Ladris" | Character traveling that distance |
+| "15 power levels exist" | Reference to power system |
+
+Facts are **world truths**. Narrative uses of facts are not duplications.
+
+---
+
+## SSOT Frontmatter
+
+Authority files use these frontmatter fields:
+
+```yaml
+---
+id: magic-crystal-mechanics
+title: "Mana Crystal Mechanics"
+domain: magic                    # Which domain owns this
+ssot: true                       # This is THE source of truth
+ssot-topic: crystal-mechanics    # What topic this covers
+mutability: immutable            # Can this change?
+last-updated: 2026-01-10
+---
+```
+
+### Field Definitions
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `domain` | Yes | Which domain owns this file |
+| `ssot` | If authoritative | Marks as single source of truth |
+| `ssot-topic` | If ssot:true | What topic this file is authoritative for |
+| `mutability` | Recommended | immutable, append-only, or expandable |
+
+---
+
+## Reference Patterns
+
+### Pattern 1: Inline Link
+
+For quick references in prose:
+
+```markdown
+The [15-level power system](../magic/fundamental-laws.md#power-levels)
+determines mage classifications.
+```
+
+### Pattern 2: Cross-Reference Section
+
+For comprehensive references at file end:
+
+```markdown
+## Cross-Reference
+
+- [Crystal Mechanics](../magic/crystals/mechanics.md) - How crystals work
+- [Crystal Types](../magic/crystals/types.md) - Blue, Ascendant, Sunburst, Crimson
+- [Politics Overview](../politics/index.md) - Four powers
+```
+
+### Pattern 3: Anchor Links
+
+For specific sections:
+
+```markdown
+See [Recharging Mechanics](../magic/crystals/mechanics.md#recharging-mechanics)
+for details on crystal power cycles.
+```
+
+**Anchor Convention:**
+- Lowercase with hyphens: `#recharging-mechanics`
+- Match actual heading text
+- Use kebab-case
+
+---
+
+## What NOT to Do
+
+### Anti-Pattern 1: Duplicating Facts
+
+```markdown
+# In world/politics/arcane-empire/nation.md
+## Crystal Technology
+
+The Blue Crystal uses the following grades:
+- Industrial: Basic stability...
+- Commercial: Standard reliability...
+[COPYING FROM magic/crystals/mechanics.md - WRONG!]
+```
+
+**Correct:**
+```markdown
+## Crystal Technology
+
+Caldris is catching up on crystal technology invented by the Trade League.
+See [Crystal Mechanics](../../magic/crystals/mechanics.md) for grade specifications.
+```
+
+### Anti-Pattern 2: Parallel Versions
+
+Having both `timeline.md` AND `timeline-master.md` with overlapping content.
+
+**Correct:** One authoritative file, others reference it or are deleted.
+
+### Anti-Pattern 3: Prose in Diagrams
+
+```markdown
+# world/diagrams/timeline.md
+
+## Era Descriptions
+
+The Pre-Arcane Era lasted from ~1300-1100 years ago...
+[PROSE IN DIAGRAM FILE - WRONG!]
+```
+
+**Correct:** Diagrams (`.mmd`) contain only Mermaid code. Prose in domain files.
+
+---
+
+## When Facts Need to Appear Multiple Times
+
+Sometimes the same fact is relevant in multiple contexts.
+
+### Solution: Reference, Don't Repeat
+
+**In `history/events/iron-peace.md`:**
+```markdown
+The Iron Peace treaty (~100 years ago) established the Four Powers as
+recognized sovereigns. This created the political framework still
+governing Asterra.
+
+See: [Politics Overview](../../politics/index.md) for current Four Powers status.
+```
+
+**In `politics/index.md`:**
+```markdown
+The Four Powers were established by the [Iron Peace](../history/events/iron-peace.md)
+treaty (~100 years ago).
+```
+
+Both reference, neither duplicates the full event narrative.
+
+---
+
+## Updating SSOT Files
+
+### Process
+
+1. **Identify the SSOT file** for the fact you're changing
+2. **Make the change** in that one file
+3. **Check references** - links still work?
+4. **Run validation** - `writer validate`
+
+### What Happens to References?
+
+- Markdown links automatically show updated content
+- No need to update every file that references the fact
+- Only update if the file path or anchor changes
+
+---
+
+## Finding the SSOT for a Fact
+
+### Method 1: Check Frontmatter
+
+Look for `ssot: true` and `ssot-topic:` matching your topic.
+
+### Method 2: Domain Logic
+
+| Fact Type | Look In |
+|-----------|---------|
+| When something happened | `history/timeline-master.md` or `events/` |
+| How magic works | `magic/` directory |
+| Who rules where | `politics/[nation]/` |
+| Where things are | `geography/[region]/` |
+| Plot objects | `artifacts/` |
+
+### Method 3: Search
+
+```bash
+grep -r "ssot-topic: crystal-mechanics" world/
+```
+
+---
+
+## Validation
+
+Run `writer validate` to check:
+- All `ssot: true` files have `ssot-topic`
+- No duplicate `ssot-topic` values
+- Links resolve correctly
+- Domain frontmatter matches file location
+
+---
+
+**Version:** 2.0.0
+**Last Updated:** 2026-01-10

package/framework/modules/writer/skills/writer/organizing-books/WORLD-STRUCTURE.md

@@ -0,0 +1,222 @@
+# World Data Structure
+
+## Overview
+
+The world-building system organizes all world facts with hash-based immutability controls to ensure consistency across a series while allowing controlled expansion.
+
+## Directory Structure
+
+```
+world/
+├── WORLD.md                       # World overview
+├── world.lock.json               # Immutability lock (hash registry)
+│
+├── core/                         # IMMUTABLE - fundamental laws
+│   ├── _manifest.json           # Directory manifest
+│   ├── fundamental-laws.md      # Physics, causality
+│   └── creation-myth.md         # World origins
+│
+├── magic/                        # IMMUTABLE
+│   ├── _manifest.json
+│   ├── overview.md              # Quick summary (~300 tokens)
+│   └── systems/                 # Individual magic systems
+│       └── {system-name}.md
+│
+├── geography/                    # EXPANDABLE
+│   ├── _manifest.json
+│   ├── overview.md              # Summary (~500 tokens)
+│   ├── climate.md
+│   └── regions/
+│       ├── _index.md            # Quick reference
+│       └── {region-name}/
+│           ├── region.md
+│           └── locations/
+│
+├── nations/                      # EXPANDABLE
+│   ├── _manifest.json
+│   ├── _index.md
+│   └── {nation-name}/
+│       ├── nation.md
+│       ├── culture.md
+│       └── government.md
+│
+├── history/                      # APPEND-ONLY
+│   ├── _manifest.json
+│   ├── timeline.md              # Master chronology
+│   └── events/
+│       └── {event-name}.md
+│
+├── characters/                   # EXPANDABLE
+│   ├── _index.md
+│   └── {character-name}/
+│       └── profile.md
+│
+├── artifacts/                    # EXPANDABLE
+│   ├── _manifest.json
+│   └── {artifact-name}.md
+│
+└── baseline/                     # Book starting state
+    ├── BASELINE.md
+    ├── world-state.md
+    └── character-states/
+```
+
+## Directory Types
+
+### IMMUTABLE Directories
+
+**Directories:** `core/`, `magic/`
+
+**Characteristics:**
+- Content is hash-locked at creation
+- Cannot be modified after establishment
+- Pre-commit hooks verify hash matches
+- Changes require explicit unlock (with confirmation)
+
+**Use Cases:**
+- Fundamental laws of physics
+- Magic system rules
+- Creation myths
+- Core world mechanics
+
+**Rationale:** These establish the "rules of the game" that readers and the AI rely on. Changing them mid-series breaks consistency.
+
+### APPEND-ONLY Directories
+
+**Directories:** `history/`
+
+**Characteristics:**
+- Original content is hash-locked
+- Can add new sections at end
+- Original sections cannot be modified
+- All additions logged in frontmatter
+
+**Use Cases:**
+- Historical events
+- Timelines
+- Past occurrences
+
+**Rationale:** History cannot be rewritten, but new events can be discovered or added.
+
+### EXPANDABLE Directories
+
+**Directories:** `geography/`, `nations/`, `characters/`, `artifacts/`
+
+**Characteristics:**
+- Can add new sub-items (files, locations, characters)
+- Existing sub-items cannot be modified
+- Cannot remove established sub-items
+- All expansions logged in manifest
+
+**Use Cases:**
+- Geographic regions (can add new ones)
+- Nations and cultures
+- Character roster
+- Artifacts and items
+
+**Rationale:** The world can grow, but established facts remain consistent.
+
+## Manifest Files
+
+Each directory contains a `_manifest.json` that:
+- Lists all facts in that directory
+- Stores content hashes for verification
+- Tracks token estimates for context loading
+- Records summaries for quick reference
+- Logs expansion history
+
+## World Lock File
+
+`world.lock.json` at the root serves as the master registry:
+- Maps all immutable facts to their hashes
+- Tracks append-only fact versions
+- Records expandable fact expansions
+- Enforces validation rules via pre-commit hooks
+
+## Token Management
+
+Each fact includes:
+- `token-count`: Full content token estimate
+- `summary-token-count`: Summary-only token estimate
+- `summary-available`: Whether summary exists
+
+This enables:
+- Loading summaries only when full detail not needed
+- Budget-aware context loading
+- Efficient multi-fact context assembly
+
+## Baseline System
+
+The `baseline/` directory stores the world state at the start of each book:
+- Which facts are established
+- Character locations and knowledge
+- Active conflicts
+- Reader knowledge vs. AI knowledge
+- Token budget for baseline loading
+
+This allows the AI to:
+- Start each book with correct context
+- Know what the reader knows at that point
+- Maintain consistency across series
+- Avoid spoiling future reveals
+
+## File Naming Conventions
+
+### Facts
+- `{category-name}.md` for general facts
+- `{specific-item}.md` for specific entities
+- `_index.md` for directory quick reference
+- `_manifest.json` for directory metadata
+
+### IDs
+- Pattern: `world-{category}-{name}`
+- Examples:
+  - `world-core-physics`
+  - `world-magic-elementalism`
+  - `world-geography-northern-wastes`
+  - `world-nations-empire-of-sol`
+  - `world-history-great-war`
+
+## Hash Algorithm
+
+All content hashes use SHA-256 of:
+- YAML frontmatter (excluding `content-hash` field itself)
+- Markdown content (normalized line endings)
+- Computed on file creation
+- Verified on pre-commit
+
+## Version Management
+
+Facts use semantic versioning:
+- `1.0.0`: Initial establishment
+- `1.1.0`: Minor addition (append-only)
+- `1.0.1`: Metadata/summary update only
+- `2.0.0`: Major change (requires unlock)
+
+## Dependencies
+
+Facts can declare dependencies:
+```yaml
+depends-on:
+  - world-core-physics
+  - world-magic-elementalism
+```
+
+This enables:
+- Validation of fact relationships
+- Context loading in correct order
+- Impact analysis for changes
+
+## Referenced-By Tracking
+
+Facts track what references them:
+```yaml
+referenced-by:
+  - book-01-chapter-05
+  - book-02-chapter-12
+```
+
+This enables:
+- Finding which content uses a fact
+- Assessing impact of potential changes
+- Consistency validation across books