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 through one of the 5 enumerated first-party integrations (see docs/integrations/, ADR-019) — never through a code-loading mechanism.

Project status

Current release: 0.4.0 (2026-07-29). 0.4 is a second structural pass over the code 0.3.0 decomposed, and a large breaking release. The project is pre-1.0: per Semantic Versioning §4 anything may change without notice before 1.0.0, and this project uses that latitude. Read the changelog section for your target version before upgrading a story you have already run the optimization loop on.

Python 3.14+ only (requires-python = ">=3.14"). 0.3.0 supported 3.10–3.13; 0.4.0 does not, and no compatibility shim or deprecation window is provided.

Architecture in force. Five records define how 0.4 behaves — read them rather than this table:

ADR-001 through ADR-016 record the 0.3.0 decomposition; each carries its own Status header saying whether it is still in force. Index: docs/adr/.

Known residual gaps. Verified against the code, not aspirational:

• ADR-001 layering is not complete. cli_adapters/assessment_cli.py's cmd_setup and cmd_ingest carry ~650 lines of business logic — diagnostic-id minting, content-addressed hashing, and the entire supersession policy — that belongs in application/. Consequence: that policy is reachable only by spawning the CLI process; narrative_craft.api cannot invoke it. Owned as post-0.4 work; detail in ADR-001 § Known residual gap.
• JSON Schema format is still inert on five internal validators. gates/packet.py, assessment/ingest.py, optimization/ledger_validate.py, application/annotation_application.py, and critique/schema_io.py each construct a validator with no format_checker; only artifacts.py and validation.py enforce format. Extending enforcement was deferred out of 0.3.0 and has not landed in 0.4.0.
• Type checking is honest, not strict. The per-module ignore_errors escapes are gone and mypy src now checks the tree, but strict and disallow_untyped_defs are not adopted (measured cost: +118 and +63 errors); untyped function bodies and Any-return leakage go unchecked. pyrefly runs alongside mypy and is intended to replace it once clean.
• narrative_craft.api is UNSTABLE and deliberately partial — 13 functions; most state/assess/critique/loop subcommands are CLI-only. See docs/api.md.
• There is no upgrade path from a pre-0.4 ledger. upgrade-ledger was a one-time, pre-0.4 cutover tool and is permanently deleted (ADR-017); run the 0.3.x verbs before upgrading.

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

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, record identity superseded by ADR-018): once written, a record is never edited in place. Each recordId is a 26-character ULID (ADR-018), and a single authoritative reader hash-verifies every record it returns. There is no migration command — upgrade-ledger was a one-time, pre-0.4 cutover tool and has been permanently deleted (ADR-017); 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/. There is no free-form extensions object — that envelope was deleted (ADR-019). Unknown top-level keys are rejected; the 5 enumerated first-party integrations attach their own typed, closed-schema objects (ao3, bridge, remoteExecution) where they need artifact-attached metadata at all.

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
• First-party integrations (ADR-019: AO3 export, live bridge, remote execution, external-review interchange, vault knowledge/config)
• 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.