narrative-craft 0.2.0

A standalone five-phase story development, critique, revision, and verification toolkit.

Narrative Craft

Narrative Craft is a standalone, local-first toolkit for shaping, drafting, critiquing, revising, verifying, and exporting stories. It provides a Python package, a narrative-craft CLI, an installable agent skill, versioned schemas, and English, Traditional Chinese, and mixed-language examples.

Narrative Craft has no required service, agent framework, repository checkout, or rendering system. External tools integrate only through public artifacts in .narrativecraft/ or the narrative_craft.extensions capability protocols.

Install

uv tool install narrative-craft
# or
pipx install narrative-craft
# or
pip install narrative-craft

Development checkout:

git clone https://github.com/clchinkc/narrative-craft.git
cd narrative-craft
uv sync
uv run narrative-craft doctor

Python 3.10–3.13 is supported.

Quick start

mkdir my-story && cd my-story
narrative-craft init --id my-story --title "My Story" --manuscript en
narrative-craft status
narrative-craft lint --file scene-1.md --lang en
narrative-craft assess setup --state .narrativecraft/state.json --round 1
narrative-craft critique setup --state .narrativecraft/state.json --round 1 --all
narrative-craft loop kickoff
narrative-craft verify --state .narrativecraft/state.json --round 1 --diagnostic CD-1-1
narrative-craft export ao3 --state .narrativecraft/state.json --out export

Use --manuscript zh-Hant for Traditional Chinese or mixed for bilingual prose. Run narrative-craft help for the complete command tree and narrative-craft doctor after installation.

Five phases

1. SHAPE establishes intent, structure, characters, world rules, themes, and author-owned constraints.
2. BUILD+LINT drafts scenes and runs deterministic checks.
3. POLISH improves prose without silently changing author intent.
4. CRITIQUE creates a neutral review packet, accepts native or external normalized findings, and routes accepted findings.
5. PUBLISH verifies frozen lines and prepares an export. Publishing itself is always an author action.

The 13-step optimization loop is a meta-cycle over these five phases; it is not a sixth phase. See docs/optimization-loop.md.

Workspace and public artifacts

narrative-craft init creates:

.narrativecraft/
├── state.json
├── events.jsonl
├── review-packet.json
├── review-findings.json
├── gate-packet.json
├── verification.json
├── report.json
├── handoff.md
├── backups/
└── passes/

Validate an artifact or the whole workspace:

narrative-craft validate --schema report --path .narrativecraft/report.json
narrative-craft validate --workspace .

Schemas are in schemas/; valid samples are in examples/contracts/. Unknown integration data belongs under each artifact's extensions object.

Documentation

• Installation
• Quick start
• Pipeline
• Optimization loop
• Locales and bilingual workflows
• Native critique
• Author gates
• Failure modes
• Falsification and rollback
• State format
• Extension contracts
• Versioned schema index
• Migration from the embedded implementation
• Release process

Repository layout

src/narrative_craft/       Python package and CLI
skills/narrative-craft/    independently installable agent skill
spec/                  optimization and locale specifications
schemas/               public JSON Schema contracts
assets/                runtime rubric and templates
docs/                  user and extension documentation
examples/              English, Traditional Chinese, mixed, and failure examples
tests/                 independent package and workflow tests

Development

uv sync
uv run pytest -q
uv run ruff check .
uv build

See CONTRIBUTING.md and SECURITY.md.

License

MIT. See LICENSE.