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, and it never imports or executes third-party code (no ancestor-directory config discovery, no entry-point plugin loading — see ADR-007). External tools integrate only through public artifacts written directly into the story directory (story-state.json, .semantic/, .critique/) or a versioned extension-capabilities.json descriptor (see docs/extension-contracts.md) — never through a code-loading mechanism.

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
printf '# Scene 1\nThe harbor light blinked twice.\n' > scene-1.md
narrative-craft lint --file scene-1.md --lang en
narrative-craft state add-scene --file story-state.json \
  --number 1 --title "Scene 1" --content-file scene-1.md
narrative-craft assess setup --state story-state.json --round 1
narrative-craft critique setup --state story-state.json --round 1 --all
narrative-craft loop kickoff
# narrative-craft verify --state story-state.json --round 1 --diagnostic <id>
narrative-craft export ao3 --state story-state.json --output export.html

narrative-craft verify re-judges an applied change against a diagnostic id already logged in story-state.json; see Quick start for a runnable example.

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.

Programmatic use

Shelling out to the CLI is the primary integration path. If you need to call narrative-craft from Python in the same process, narrative_craft.api is the only supported surface — 13 functions (create_story/read_story/lint/lint_scene/assess/ critique_setup/critique_ingest/export_ao3/loop_status/ loop_events/validate_artifact/validate_workspace/doctor), all of which raise typed exceptions and never call sys.exit/print. It is pre-1.0 UNSTABLE. Every other module is internal and may change without notice. See docs/api.md.

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. The critique gate is advisory only — it never blocks a phase transition or infers author approval (ADR-012).
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

The story directory itself IS the workspace — there is no separate dot-prefixed workspace directory. narrative-craft init creates:

story-state.json          # canonical machine state (single-track SSOT)
.semantic/
├── loop-log.jsonl         # sole sovereignty record for the optimization loop
├── checkpoints/
├── handoffs/
└── passes/
.critique/
└── rounds/

.semantic/loop-log.jsonl is an immutable append-only ledger (ADR-003): once written, a record is never edited in place. A ledger written before 0.3.0 must be migrated exactly once — narrative-craft upgrade-ledger --apply — before any 0.3.0 command will read it; see CHANGELOG.md for the full breaking-change writeup.

Other public artifacts (review-packet.json, review-findings.json, gate-packet.json, verification.json, report.json, handoff.md) are exchanged as plain files at whatever path a command writes them to or an extension expects; events.jsonl never needs to be persisted — loop events derives the event stream from .semantic/loop-log.jsonl on demand.

Validate an artifact or the whole workspace:

narrative-craft validate --schema report --path examples/contracts/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
• Loop-record contracts
• Locales and bilingual workflows
• Native critique
• Author gates
• Failure modes
• Falsification and rollback
• State format
• Extension contracts
• Versioned schema index
• narrative_craft.api reference
• Architecture decision records
• Migration from the embedded implementation
• Release process
• Changelog — pre-1.0, see the loud breaking-change notice for 0.3.0

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, API, and architecture-decision 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.