Novel-Writer-OpenSpec — Summary

Novel-Writer-OpenSpec (published as novelspec on npm) is a domain port of OpenSpec methodology to fiction writing — specifically Chinese web novel (网络小说) creation. It applies OpenSpec's specs/ (confirmed settings) + changes/ (proposed changes) separation to manage novel world-building, character design, and chapter outlines as verifiable specifications with ADDED/MODIFIED/REMOVED delta tracking. The novelspec CLI provides init, validate, list, archive, and show commands, plus AI slash commands for Claude/Cursor/Windsurf. With 29 stars and TypeScript source, it is the most mature creative-writing application of spec-driven development in the corpus.

Compared to seeds: closest to openspec (same artifact structure, same delta format, same CLI conventions) applied to the fiction domain. No seed covers non-software domains. The key insight is that "character consistency" and "setting coherence" in long-form fiction are the same class of problem as "interface consistency" in software — both benefit from a spec layer that accumulates canonical state and tracks changes with explicit rationale.

Novel-Writer-OpenSpec — Overview

Origin

Published by wordflowlab (GitHub). October 2025. npm package: novelspec v0.2.4. TypeScript codebase with interactive CLI using @inquirer/core.

The README description (Chinese): "基于 OpenSpec 方法论的小说创作管理工具" — "Novel creation management tool based on OpenSpec methodology."

Philosophy

The core analogy:

• Software interface spec → Novel character spec (姓名, 年龄, 性格 = name, age, personality)
• Software API spec → Novel worldbuilding spec (魔法体系, 地理 = magic system, geography)
• Software feature spec → Novel chapter outline spec

The tool solves the "character collapse" (人设崩塌) problem in AI-assisted long-form fiction: when writing across hundreds of chapters with AI, the AI forgets earlier character decisions. A spec layer gives the AI a persistent source of truth.

Related Project

From README:

"Novel-Writer - 基于 Spec-Kit 的小说创作工具" — the same author built a spec-kit-based version first.

This is the OpenSpec-methodology version of that earlier Spec-Kit-based tool.

Directory Conventions

The tool uses novelspec/ instead of openspec/ as the root directory, mirroring the OpenSpec layout:

novelspec/
├── project.md          # Project conventions (创作原则、风格指南)
├── AGENTS.md           # AI assistant instructions
├── specs/              # Confirmed settings (唯一真相)
│   ├── characters/     # Character specs
│   ├── worldbuilding/  # World specs
│   └── outline/        # Story outline
└── changes/            # Change proposals
    └── archive/
chapters/               # Generated chapter content (output)

AI Integration

Supports: Claude Code, Cursor, Windsurf (via .claude/, .cursor/ directories in the repo).

Novel-Writer-OpenSpec — Architecture

Distribution

• Type: npm-package (novelspec)
• Version: 0.2.4
• Install: npm install -g novelspec

Runtime Requirements

• Node.js (version not specified, likely >= 16)
• npm

Repository Structure

novel-writer-openspec/
├── src/
│   ├── cli.ts           # CLI entry point
│   ├── commands/
│   │   ├── init.ts      # Interactive wizard
│   │   ├── validate.ts  # Spec format validation
│   │   ├── list.ts      # List changes/specs
│   │   ├── show.ts      # Show change details
│   │   └── archive.ts   # Archive + merge specs
│   ├── core/
│   │   ├── parser.ts
│   │   ├── validator.ts
│   │   └── template-manager.ts
│   └── utils/
│       └── file-ops.ts
├── templates/
│   ├── project.md.template
│   ├── AGENTS.md.template
│   ├── characters/      # Character spec templates
│   ├── worldbuilding/   # World spec templates
│   └── outline/         # Outline spec templates
├── .claude/             # Claude Code settings
├── .cursor/             # Cursor settings
└── openspec/            # The tool uses OpenSpec to manage itself

Key Dependency: @inquirer/core

The init command uses an elaborate TUI with ASCII art lettering, progress spinners, and multi-select tool selectors. This is the most visually sophisticated init experience in the batch.

Directory Convention Difference

Uses novelspec/ root instead of openspec/ — prevents collision with OpenSpec if both are used in the same project.

Novel-Writer-OpenSpec — Components

CLI Binary: novelspec

Validated Spec Format

The validator checks:

• proposal.md contains Why/What/Impact sections
• tasks.md uses checkbox format
• spec files contain Requirement + Scenario structure
• Every Requirement has at least one Scenario

AI Slash Commands

Templates (domain-specific)

Spec Category Types

MCP Servers

None.

Novel-Writer-OpenSpec — Uniqueness

differs_from_seeds

Closest seed: openspec (same artifact structure: specs/, changes/, proposal.md, tasks.md, delta format, ADDED/MODIFIED/REMOVED sections, archive command). The architectural delta is a complete domain port to creative writing: spec categories are characters/, worldbuilding/, outline/ instead of software capabilities; the problem being solved is character consistency and setting coherence rather than API contracts and interface specifications. The CLI is renamed novelspec and uses novelspec/ root directory. No seed addresses non-software domains. The closest analogy in the corpus is how taskmaster-ai is often used for non-software task management even though it was designed for coding — but unlike that incidental usage, this is an intentional domain port with purpose-built templates and validation rules.

Positioning

Proof-of-concept that OpenSpec's core insight — "AI needs a spec layer to stay consistent" — applies equally to long-form fiction. The "character collapse" problem in AI-assisted Chinese web novel writing (AI forgets character traits established 50 chapters ago) is structurally identical to the "API drift" problem in AI-assisted software development. Both benefit from a canonical state file the AI reads before generating content.

Cross-Reference

The same author has a Spec-Kit-based version: https://github.com/wordflowlab/novel-writer — suggesting the author actively compared spec frameworks and found OpenSpec's delta format more suitable for novel evolution than Spec-Kit's gherkin-first approach.

Observable Failure Modes

1. Chinese-only UX: the CLI output is Chinese — non-Chinese users will find the validation messages opaque
2. No AI enforcement: unlike software specs that can be tested, there is no automated way to verify that generated chapters "comply" with specs — only human review can catch spec violations
3. Outline/chapters split: chapter content lives in chapters/ outside novelspec/ — the AI must read both locations for full context
4. Last commit Oct 2025: 7 months without updates. The npm package may not support current AI tool configurations.