@demig0d2/skills 1.0.0

package/skills/concept-expander/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: concept-expander
+version: 1.0.0
+description: |
+  Expands a rough book seed (1 paragraph, bullet points, or a vague idea) into a full,
+  structured concept document that the book-writer skill can consume directly. Use when
+  the user says "I have an idea for a book," "here's a rough concept," or provides a
+  seed that is too thin to drive the full writing workflow. Outputs a ready-to-use
+  concept document. Do NOT use for books where a full concept already exists.
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+# Concept Expander
+
+## Scripts
+
+**Validate concept document completeness** before passing to book-writer:
+```bash
+python scripts/validate_concept.py <concept.md>
+python scripts/validate_concept.py <concept.md> --strict   # stricter word count minimums
+python scripts/validate_concept.py <concept.md> --json     # machine-readable
+```
+Checks all required fields (logline, core question, reader, promise, unique angle,
+central tension, emotional arc, thematic clusters, genre) and scores completeness.
+Also validates the logline for banned words and word count.
+
+**Always run validation before handing the concept document to book-writer.**
+A concept that fails validation will produce a weaker structure in Module 2.
+
+You take a rough seed — a paragraph, a title, a feeling, a few bullet points — and develop
+it into a complete concept document that drives the entire book-writing workflow.
+
+---
+
+## TRIGGER
+
+Activate when the user provides:
+- A vague book idea ("I want to write a book about identity")
+- A single title or working title only
+- A rough paragraph summary
+- A list of themes with no structure
+- Anything too thin for book-writer Phase 1 to work with
+
+---
+
+## PROCESS
+
+### Step 1 — Seed Extraction
+Read the user's raw input. Identify:
+- The core emotional or intellectual question at the heart of the idea
+- Who this is likely for (implied audience)
+- What genre it maps to in Vivid's categories (Philosophy/Essay, Self-help/Motivational, Non-fiction/Technical)
+- Any natural tension or paradox in the idea (this is the engine of good books)
+
+### Step 2 — Clarifying Questions (if needed)
+If the seed is genuinely too sparse (under 3 usable signals), ask ONE round of targeted questions:
+
+```
+Before I expand this, a few quick questions:
+1. Who is this book for — what is their core pain or question?
+2. What do you want them to feel or understand by the last page that they don't feel now?
+3. Is there a personal story or experience at the root of this idea?
+4. Any books that exist in the same space that this should be different from?
+```
+
+Do not ask all four if some are already answerable from the seed.
+
+### Step 3 — Concept Document Generation
+Produce the full concept document in this format:
+
+---
+
+```
+BOOK CONCEPT DOCUMENT
+═══════════════════════════════════════════════════════
+
+WORKING TITLE: [compelling title + optional subtitle]
+ALTERNATE TITLES: [2 other options]
+
+LOGLINE (one sentence):
+[The book's entire premise in 25 words or fewer. If you can't say it in one sentence,
+the concept isn't tight enough yet.]
+
+THE CORE QUESTION:
+[The one question the book answers. Not a topic — a question. E.g., not "loneliness"
+but "Why does being surrounded by people sometimes feel lonelier than being truly alone?"]
+
+THE READER:
+Who they are: [demographic + psychographic sketch]
+What they're feeling right now: [their current emotional state]
+What they've already tried: [what hasn't worked for them]
+What they secretly want: [the real desire beneath the surface problem]
+
+THE PROMISE:
+[What the reader will have — know, feel, be able to do — after finishing this book
+that they don't have now. Be specific. Not "a better life" but exactly what changes.]
+
+GENRE: [Vivid's category]
+TONE: [e.g., raw/confessional, philosophical, instructional-personal, polemical]
+REGISTER: [e.g., intimate/direct, authoritative/grounded, exploratory/questioning]
+
+THE UNIQUE ANGLE:
+[What makes this book different from existing books on this topic. What does Vivid's
+lived experience add that a generic author couldn't? Be specific.]
+
+THE CENTRAL TENSION OR PARADOX:
+[Every great book has a tension at its core. E.g., "The more you chase connection,
+the more alone you feel." Name the paradox this book lives in.]
+
+EMOTIONAL ARC (reader's journey):
+Start: [where the reader is emotionally when they open page 1]
+Middle: [what they confront, what gets harder before it gets better]
+End: [what shifts — not necessarily solved, but transformed]
+
+THEMATIC CLUSTERS (7–10 themes/territories to explore):
+1. [Theme + one sentence on what to explore within it]
+2.
+3.
+4.
+5.
+6.
+7.
+[add more as needed]
+
+SIGNATURE ELEMENTS:
+[Recurring devices, structural choices, or content features that will define this book.
+E.g., "dual My Story / My Reflection structure," "opens each chapter with a paradox,"
+"uses no external citations — all insight is arrived at through lived experience"]
+
+COMPARABLE BOOKS (comp titles):
+[2–3 books this sits near in a bookstore — and crucially, how this is different from each]
+
+ESTIMATED SCOPE:
+[short / medium / full-length — with reasoning]
+
+POTENTIAL CHAPTER TERRITORIES (rough, pre-structure):
+[8–14 possible chapter-level questions or themes — these feed Phase 2 of book-writer]
+
+RISKS / BLIND SPOTS:
+[Honest assessment: what could make this book fall flat? What would a skeptical reader
+push back on? What does the author need to be careful not to oversimplify?]
+
+═══════════════════════════════════════════════════════
+```
+
+---
+
+## OUTPUT
+
+Deliver the complete concept document.
+Then add one line:
+
+```
+→ This concept document is ready for the book-writer skill. Upload it or paste it to begin.
+```
+
+---
+
+## QUALITY CHECKS
+
+Before delivering, verify:
+- [ ] Logline is under 25 words and doesn't use vague terms ("journey," "transformation," "discover")
+- [ ] Core question is a genuine question, not a topic
+- [ ] The unique angle names something specific Vivid brings — not generic
+- [ ] Thematic clusters are distinct from each other (no overlap)
+- [ ] The emotional arc has a real middle — not just start and end
+- [ ] Comparable books are real, named, and the differentiators are honest

package/skills/concept-expander/scripts/validate_concept.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""
+validate_concept.py — Validate a concept document for completeness
+
+Checks that a concept document has all required fields before
+it enters the book-writer pipeline. Scores completeness and
+flags missing or thin sections.
+
+Usage:
+    python validate_concept.py <concept.md>
+    python validate_concept.py <concept.md> --json
+    python validate_concept.py <concept.md> --strict
+"""
+
+import sys
+import re
+import json
+import argparse
+from pathlib import Path
+
+# ─── Required Fields ──────────────────────────────────────────────────────────
+
+REQUIRED_FIELDS = [
+    {
+        "key": "working_title",
+        "patterns": [r"WORKING TITLE:", r"Title:"],
+        "min_words": 2,
+        "weight": "required",
+        "label": "Working title",
+    },
+    {
+        "key": "logline",
+        "patterns": [r"LOGLINE", r"One[- ]sentence", r"Premise:"],
+        "min_words": 10,
+        "max_words": 30,
+        "weight": "required",
+        "label": "Logline (≤25 words)",
+    },
+    {
+        "key": "core_question",
+        "patterns": [r"CORE QUESTION", r"THE CORE QUESTION", r"Central question"],
+        "min_words": 8,
+        "weight": "required",
+        "label": "Core question",
+    },
+    {
+        "key": "reader",
+        "patterns": [r"THE READER", r"Reader:", r"Audience:"],
+        "min_words": 15,
+        "weight": "required",
+        "label": "Reader profile",
+    },
+    {
+        "key": "promise",
+        "patterns": [r"THE PROMISE", r"Promise:", r"What they gain"],
+        "min_words": 10,
+        "weight": "required",
+        "label": "The promise",
+    },
+    {
+        "key": "unique_angle",
+        "patterns": [r"UNIQUE ANGLE", r"THE UNIQUE ANGLE", r"What makes this different"],
+        "min_words": 15,
+        "weight": "required",
+        "label": "Unique angle",
+    },
+    {
+        "key": "central_tension",
+        "patterns": [r"CENTRAL TENSION", r"PARADOX", r"The tension"],
+        "min_words": 8,
+        "weight": "required",
+        "label": "Central tension / paradox",
+    },
+    {
+        "key": "emotional_arc",
+        "patterns": [r"EMOTIONAL ARC", r"Arc:", r"Start:", r"Journey:"],
+        "min_words": 20,
+        "weight": "required",
+        "label": "Emotional arc",
+    },
+    {
+        "key": "thematic_clusters",
+        "patterns": [r"THEMATIC CLUSTERS", r"Themes:", r"Chapter territories"],
+        "min_words": 30,
+        "weight": "required",
+        "label": "Thematic clusters (7–10)",
+    },
+    {
+        "key": "comparable_books",
+        "patterns": [r"COMPARABLE BOOKS", r"Comp titles", r"Similar books"],
+        "min_words": 10,
+        "weight": "recommended",
+        "label": "Comparable books",
+    },
+    {
+        "key": "risks",
+        "patterns": [r"RISKS", r"BLIND SPOTS", r"Risks:"],
+        "min_words": 10,
+        "weight": "recommended",
+        "label": "Risks / blind spots",
+    },
+    {
+        "key": "genre",
+        "patterns": [r"GENRE:", r"Genre:"],
+        "min_words": 1,
+        "weight": "required",
+        "label": "Genre",
+    },
+]
+
+# Banned logline words
+BANNED_LOGLINE_WORDS = ["journey", "transformation", "discover", "explore", "delve", "embark"]
+
+
+def find_field(text: str, field: dict) -> tuple[bool, str, int]:
+    """Return (found, extracted_text, word_count)."""
+    for pattern in field["patterns"]:
+        match = re.search(pattern, text, re.IGNORECASE)
+        if match:
+            # Extract text after this heading until next all-caps heading or end
+            start = match.end()
+            remainder = text[start:start + 600]
+            # Stop at next heading-like line
+            stop = re.search(r"\n[A-Z]{3,}[\s:]", remainder)
+            extracted = remainder[:stop.start() if stop else 400].strip()
+            words = len(extracted.split())
+            return True, extracted, words
+    return False, "", 0
+
+
+def validate_logline(text: str) -> list:
+    """Check logline specifically for quality."""
+    issues = []
+    logline_match = re.search(r"LOGLINE[^\n]*\n(.{10,200})", text, re.IGNORECASE)
+    if logline_match:
+        logline = logline_match.group(1).strip()
+        words = len(logline.split())
+        if words > 25:
+            issues.append(f"Logline is {words} words — should be ≤25")
+        for banned in BANNED_LOGLINE_WORDS:
+            if banned in logline.lower():
+                issues.append(f"Logline contains banned word: '{banned}'")
+    return issues
+
+
+def validate_concept(filepath: str, strict: bool = False) -> dict:
+    path = Path(filepath)
+    if not path.exists():
+        print(f"Error: File not found: {filepath}", file=sys.stderr)
+        sys.exit(1)
+
+    text = path.read_text(encoding="utf-8")
+    total_words = len(text.split())
+
+    results = []
+    score = 0
+    max_score = 0
+
+    for field in REQUIRED_FIELDS:
+        found, extracted, word_count = find_field(text, field)
+        is_required = field["weight"] == "required"
+        field_score = 2 if is_required else 1
+        max_score += field_score
+
+        issues = []
+        if not found:
+            issues.append(f"Field not found")
+        else:
+            min_words = field.get("min_words", 0)
+            max_words = field.get("max_words", 9999)
+            if word_count < min_words:
+                issues.append(f"Too thin ({word_count} words, min {min_words})")
+            if word_count > max_words:
+                issues.append(f"Too long ({word_count} words, max {max_words})")
+
+        if not issues:
+            score += field_score
+
+        results.append({
+            "field": field["label"],
+            "key": field["key"],
+            "weight": field["weight"],
+            "found": found,
+            "word_count": word_count,
+            "issues": issues,
+            "pass": len(issues) == 0,
+        })
+
+    # Logline quality check
+    logline_issues = validate_logline(text)
+
+    completeness = round((score / max_score) * 100) if max_score else 0
+    required_passing = all(r["pass"] for r in results if r["weight"] == "required")
+
+    return {
+        "file": str(path),
+        "total_words": total_words,
+        "score": score,
+        "max_score": max_score,
+        "completeness_pct": completeness,
+        "ready": required_passing and completeness >= 80,
+        "fields": results,
+        "logline_issues": logline_issues,
+    }
+
+
+def print_report(result: dict):
+    ready_icon = "✓" if result["ready"] else "✗"
+    print(f"\n{'═' * 60}")
+    print(f"  CONCEPT DOCUMENT VALIDATION")
+    print(f"  File: {result['file']}")
+    print(f"{'═' * 60}")
+    print(f"  Completeness: {result['completeness_pct']}%  ({result['score']}/{result['max_score']} points)")
+    print(f"  Status: {ready_icon} {'READY for book-writer' if result['ready'] else 'NOT READY — fix required fields'}")
+
+    print(f"\n  {'FIELD':<35} {'STATUS':<12} {'WORDS'}")
+    print(f"  {'─' * 55}")
+
+    for field in result["fields"]:
+        if field["pass"]:
+            status = "✓ ok"
+        else:
+            status = "✗ " + (field["issues"][0][:20] if field["issues"] else "?")
+        req = " *" if field["weight"] == "required" else "  "
+        print(f"  {req}{field['field']:<33} {status:<12} {field['word_count']}")
+
+    if result["logline_issues"]:
+        print(f"\n  LOGLINE ISSUES:")
+        for issue in result["logline_issues"]:
+            print(f"    ⚠ {issue}")
+
+    missing = [f for f in result["fields"] if not f["pass"] and f["weight"] == "required"]
+    if missing:
+        print(f"\n  REQUIRED FIXES ({len(missing)}):")
+        for f in missing:
+            for issue in f["issues"]:
+                print(f"    ✗ {f['field']}: {issue}")
+
+    print(f"\n  (* = required field)")
+    print(f"{'═' * 60}\n")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("concept_file")
+    parser.add_argument("--json", action="store_true")
+    parser.add_argument("--strict", action="store_true")
+    args = parser.parse_args()
+
+    result = validate_concept(args.concept_file, args.strict)
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print_report(result)

package/skills/continuity-tracker/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: continuity-tracker
+version: 1.0.0
+description: |
+  Maintains a running continuity log across all chapters of a book in progress. Tracks
+  established facts, recurring metaphors, tone decisions, narrative commitments, and
+  chapter summaries so nothing contradicts itself across a long manuscript. Use after
+  each chapter is finalized to update the log, and before each new chapter is written
+  to brief the book-writer on what's been established. Essential for books over 5 chapters.
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+# Continuity Tracker
+
+## Scripts
+
+The continuity log (`continuity_log.json`) persists all tracking data across sessions.
+Run these scripts to manage it — never edit the JSON manually.
+
+**Initialize log at project start:**
+```bash
+python scripts/log_manager.py init "Book Title"
+```
+
+**After each finalized chapter — update log:**
+```bash
+python scripts/log_manager.py add-chapter 3 "Aloneness Is Not the Enemy"
+python scripts/log_manager.py add-fact "Author walked miles to save money"
+python scripts/log_manager.py add-insight 3 "Aloneness and loneliness are distinct"
+python scripts/log_manager.py add-metaphor 3 "invisible chains beginning to loosen"
+python scripts/log_manager.py add-thread "Ch.3 raised idea of earned freedom — needs depth in Ch.7"
+```
+
+**Before each new chapter — check for conflicts:**
+```bash
+python scripts/conflict_check.py chapter_draft.md --log continuity_log.json
+```
+Scan the draft against retired metaphors, delivered insights, and established facts
+before finalizing. Surfaces potential contradictions with line-level detail.
+
+**View full log / summary:**
+```bash
+python scripts/log_manager.py show
+python scripts/log_manager.py summary
+python scripts/log_manager.py threads   # open threads only
+```
+
+**Close a resolved thread:**
+```bash
+python scripts/log_manager.py threads          # find index
+python scripts/log_manager.py close-thread 0  # close by index
+```
+
+## References
+
+`references/log_schema.md` — Full log JSON schema and CLI quick reference.
+Read when: setting up the log for a new project or adding custom fields.
+
+You are the book's memory. You track everything that has been established so the
+manuscript stays internally consistent — in logic, tone, narrative, and voice.
+No contradictions. No repetition of insights already delivered. No forgotten threads.
+
+---
+
+## TRIGGER
+
+Activate:
+1. **After each chapter is finalized** → update the Continuity Log
+2. **Before each new chapter is written** → output the Continuity Brief for that chapter
+3. **When user asks** "what have I already covered?", "have I used this metaphor before?",
+   "does this contradict anything earlier?"
+
+---
+
+## THE CONTINUITY LOG
+
+The log is a living document. It grows with each chapter. Structure:
+
+```
+CONTINUITY LOG — [Book Title]
+Last updated after: Chapter [N]
+═══════════════════════════════════════════════════════
+
+BOOK-LEVEL COMMITMENTS
+───────────────────────────────────────────────────────
+These were established in front matter / introduction and must not be contradicted:
+
+• [commitment 1 — e.g., "Author frames himself as someone who lived this, not an expert"]
+• [commitment 2 — e.g., "Book promises no quick fixes — lasting transformation only"]
+• [commitment 3]
+[add as discovered]
+
+═══════════════════════════════════════════════════════
+
+ESTABLISHED FACTS & NARRATIVE DETAILS
+───────────────────────────────────────────────────────
+Facts about the author's story that have been stated and must remain consistent:
+
+• [fact — e.g., "Father passed away during author's degree years"]
+• [fact — e.g., "Author lived in a tiny penthouse apartment alone"]
+• [fact — e.g., "Author walked miles to save money on transport"]
+• [fact — e.g., "Author cooked rice and lentils, stretched groceries"]
+[add per chapter]
+
+═══════════════════════════════════════════════════════
+
+METAPHORS & IMAGES USED (per chapter)
+───────────────────────────────────────────────────────
+Track to avoid: (a) repetition of same image, (b) contradictory images for same concept
+
+Ch.1: [metaphors used — e.g., "loneliness as deafening scream," "silence pressing in"]
+Ch.2: [metaphors used]
+Ch.3: [metaphors used]
+[update each chapter]
+
+AVAILABLE FOR FUTURE USE (not yet used):
+• [strong image from research bank or concept doc that hasn't appeared yet]
+
+RETIRED (used — do not repeat):
+• [list]
+
+═══════════════════════════════════════════════════════
+
+CORE INSIGHTS DELIVERED (per chapter)
+───────────────────────────────────────────────────────
+Track to avoid restating the same insight in different words across chapters.
+Each insight should appear once, deeply — not scattered thinly across chapters.
+
+Ch.1: [central insight delivered — e.g., "Loneliness as mirror of self-relationship"]
+Ch.2: [central insight — e.g., "Chasing connection from fear, not love, creates neediness"]
+Ch.3: [central insight]
+[update each chapter]
+
+═══════════════════════════════════════════════════════
+
+TONE DECISIONS
+───────────────────────────────────────────────────────
+Tone choices that have been established and should be maintained:
+
+• Register: [e.g., "intimate and confessional in My Story sections"]
+• Reader address: [e.g., "direct 'you' in Reflection sections, not 'one' or 'people'"]
+• Author position: [e.g., "always in-process, never above the reader — no 'I've solved this'"]
+• Emotional ceiling: [e.g., "darkest content already appeared in Ch.1 — Ch.5+ should feel lighter but not falsely resolved"]
+
+═══════════════════════════════════════════════════════
+
+STRUCTURAL PATTERNS ESTABLISHED
+───────────────────────────────────────────────────────
+• Section format: [e.g., "My Story then My Reflection — both present in all chapters so far"]
+• Chapter length pattern: [e.g., "Ch.1: 2,400w / Ch.2: 2,200w / Ch.3: 2,600w — avg ~2,400w"]
+• Opening style: [e.g., "All chapters open with immersive scene in My Story — maintain"]
+• Closing style: [e.g., "All chapters close with a single standalone insight sentence"]
+
+═══════════════════════════════════════════════════════
+
+OPEN THREADS (introduced but not resolved)
+───────────────────────────────────────────────────────
+Themes, questions, or narrative elements that were raised and need to pay off:
+
+• [thread — e.g., "Ch.2 mentioned 'the small proof that my life has value' — this needs deeper exploration"]
+• [thread]
+• [thread]
+
+Flag these for the book-writer when their resolution chapter arrives.
+
+═══════════════════════════════════════════════════════
+
+CHAPTER SUMMARIES
+───────────────────────────────────────────────────────
+One-paragraph summary per completed chapter (for quick reference during later chapters):
+
+Ch.1 — [Title]: [summary]
+Ch.2 — [Title]: [summary]
+[add each chapter]
+
+═══════════════════════════════════════════════════════
+```
+
+---
+
+## CONTINUITY BRIEF (Pre-Chapter Output)
+
+Before the book-writer begins each new chapter, output this brief:
+
+```
+CONTINUITY BRIEF — Before Writing Chapter [N]: [Title]
+═══════════════════════════════════════════════════════
+
+WHAT'S BEEN ESTABLISHED (relevant to this chapter):
+• [facts, decisions, tone commitments relevant to this chapter's theme]
+
+OPEN THREADS TO RESOLVE IN THIS CHAPTER (if any):
+• [threads from the log that this chapter should address]
+
+METAPHORS TO AVOID (already used):
+• [list of images already in play — don't repeat]
+
+INSIGHTS TO NOT REPEAT:
+• [insights already delivered that this chapter's theme might accidentally echo]
+
+TONE REMINDERS:
+• [any tone decisions particularly relevant to this chapter]
+
+WORD COUNT GUIDANCE:
+• Previous chapters averaged [X] words. Target [Y–Z] for this chapter.
+
+═══════════════════════════════════════════════════════
+Proceed to write Chapter [N].
+```
+
+---
+
+## UPDATE PROCESS (Post-Chapter)
+
+After each chapter is finalized:
+1. Extract all new facts, metaphors, insights, tone decisions, open threads
+2. Add chapter summary
+3. Update the log
+4. Confirm: "Continuity Log updated. [N] new items added. [X] open threads now active."
+
+---
+
+## CONTRADICTION DETECTION
+
+When reviewing a chapter, check against the log:
+- Do any facts contradict established narrative details?
+- Does the author's position (in-process vs. resolved) contradict what's been established?
+- Are any metaphors repeated with different or conflicting meaning?
+- Is an insight being delivered that was already fully delivered in a prior chapter?
+
+If yes → flag immediately before the chapter proceeds to humanizer:
+```
+⚠ CONTINUITY CONFLICT DETECTED
+Chapter [N] contains: [description of conflict]
+Conflicts with: [Chapter X, specific detail]
+Resolution options:
+1. [option]
+2. [option]
+```
+
+---
+
+## BEHAVIOR RULES
+
+- Update the log AFTER every finalized chapter — do not wait until the end
+- Brief the book-writer BEFORE every new chapter — do not skip
+- Flag open threads proactively — do not let them die silently
+- Track word counts per chapter to flag if the manuscript is drifting from target scope