GitHub Novel Serialization Skill

Overview

This Skill orchestrates AI-assisted novel writing and GitHub-based serialization. It provides a modular, harness-engineered system for generating world-building documents, character sheets, chapter drafts, continuity verification, and GitHub publishing — covering the full creative lifecycle from concept to release.

Output Language

All generated novel content MUST be output in the language specified by the user via the {{OUTPUT_LANGUAGE}} variable (default: English). Infrastructure and metadata files remain in English to ensure cross-tool compatibility. See README FOR AI.md — Section 0.3 for the authoritative declaration.

Quick Start

1. Plan — Define novel parameters (genre, setting, themes, target length) using prompts/01-implement-method.md
2. Build — Generate world-building document via modules/worldbuilding/ sub-skill
3. Draft — Create character sheets (modules/character-design/) then draft chapters (modules/chapter-writing/)
4. Verify — Run continuity checks via modules/continuity-check/ and prompts/02-robustness-checks.md
5. Publish — Tag and release via modules/publishing-workflow/ and .github/workflows/novel-release.yml

Module Index

Workflow Pipeline

Note: The following is a visual DAG pipeline diagram, not executable code.

Plan          →  Define parameters, set {{OUTPUT_LANGUAGE}}
  │
  ▼
Build         →  World-building document (modules/worldbuilding/)
  │
  ▼
Draft         →  Character sheets (modules/character-design/) → Chapter drafts (modules/chapter-writing/)
  │
  ▼
Verify        →  Continuity check (modules/continuity-check/) + Robustness checks (prompts/02-robustness-checks.md)
  │
  ▼
Publish       →  Git tag + GitHub Release (modules/publishing-workflow/)

Feedback Loop: Verification output feeds back into Draft step for iterative refinement.

Quick Reference: File Conventions

• Chapter files: chapters/ch-{number}-{title}.md, zero-padded to 3 digits (e.g., ch-001-the-beginning.md) so that lexical sort equals numeric sort
• World-building docs: worldbuilding/{domain}.md (e.g., worldbuilding/magic-system.md)
• Character sheets: characters/{name}.md
• State files: state/{type}.md (timeline, character-states, thread-ledger, location-states)
• All Markdown files: UTF-8, LF line endings, 2-space indentation
• YAML frontmatter: Required on all SKILL.md files and on every chapter file (method-patterns-publishing.md Section 3). Optional on other novel content files (world-building docs, character sheets), where the CC license header serves as metadata. Where frontmatter and the CC header coexist, frontmatter goes first at byte 0.

Quick Reference: Git Conventions

• Branch naming: feat/{module-name}, fix/{issue-id}, chore/{description}
• Commit format: type(module): concise description (e.g., feat(worldbuilding): add magic system template)
• Tag format: v{major}.{minor}.{patch} (e.g., v1.2.3) or chapter-{number} for chapter releases
• Release workflow: Automated via .github/workflows/novel-release.yml on tag push

Quick Reference: Continuity State

Maintain the following state files in state/ directory:

The continuity tracker owns every state file above (spec Section 5.2); other modules propose updates rather than writing state directly, preserving role isolation (spec Section 6).

Verification Gates

Before publishing any chapter, ALL of the following gates must pass:

• Review gate — review_all.py reports no FAIL; every WARN has been reviewed by a human
• Continuity consistency — Character names, locations, timeline events match state files
• Style consistency — Voice, tense, register match established style rules
• Plot logic — Causality holds; motivations are clear; foreshadowing payoffs are tracked
• Pacing analysis — Scene-to-sequel ratio is balanced; tension curve is intentional
• Dialogue authenticity — Each character has distinguishable voice patterns
• License compliance — Generated content includes CC BY-NC-SA 4.0 license header
• File naming — Chapter file follows ch-{number}-{title}.md convention
• State updated — Timeline, character states, and thread ledger are current
• Line count compliance — No file exceeds 500 lines (see Section 8.1 splitting rule)

Cross-References

• Templates & Methodology: references/method-patterns.md (master) and its split modules (worldbuilding, character, chapter, continuity, publishing)
• Glossary: references/glossary.md — domain terminology and conventions
• Worked Examples: references/examples/ — example-worldbuilding.md, example-character-sheet.md, example-chapter-draft.md
• Implementation Prompt: prompts/01-implement-method.md — full novel generation prompt template
• Robustness Checks: prompts/02-robustness-checks.md — multi-dimensional quality check prompt
• Prompt Usage Guide: prompts/README.md — how to use dual-mode prompt templates
• Shared Scripts: scripts/README.md — catalog and invocation conventions for humanizer_check.py (de-AI-tone gate), _list_hits.py, _promote_draft.py (draft→release sync), _sync_draft.py (errata write-back), and the review gate family: review_all.py (all-in-one review report), review_scale.py (word-count), review_continuity.py (cross-chapter consistency), review_rationality.py (plot logic), review_punctuation.py (punctuation & orthography), backed by _review_lib.py. Scripts live in this repo only; invoke them from the subproject root.
• Subprojects: SUBPROJECTS.md — registered independent novel subprojects (own git repo and remote), their locations and which scripts they consume.

Constraints & Boundaries

1. SKILL.md is index + quick-reference ONLY — no code templates, no long-form methodology. All templates live in references/.
2. No file exceeds 500 lines — split into sub-modules when approaching the limit (see references/method-patterns.md split protocol).
3. prompts/ folder is DUAL-MODE — files are standalone copy-paste templates for humans, NOT for agent auto-invocation.
4. Harness Engineering compliance — constraint-before-generation, structured memory, verification gates, modular decomposition, and feedback loops are mandatory.
5. Every module is independently usable — no circular dependencies between modules; each has a single responsibility.
6. Output language — All generated novel content respects {{OUTPUT_LANGUAGE}}; infrastructure files remain in English.
7. Dual licensing — Skill infrastructure: GPL-3.0; Generated novel content: CC BY-NC-SA 4.0. Every novel file must include the CC license header.
8. State persistence — State is persisted in structured Markdown files, not in conversation context.
9. Progressive disclosure — Layer 1: SKILL.md (index) → Layer 2: references/ (templates) → Layer 3: examples/ (worked examples).
10. Human-in-the-loop — Publishing workflow requires manual Git tag creation; prompts enable human oversight.