fdw

Fiction-driven workflow CLI. A TypeScript CLI tool for managing fiction-driven workflows.

Prerequisites

• Node.js 20.19.0 or later
• pnpm 10.23.0 or later

Install

pnpm install

Build

pnpm build

Produces dist/bin/fdw.js (the compiled binary).

Test

pnpm test

Runs the Vitest test suite.

Lint

pnpm lint

Runs ESLint over src/ and test/.

Usage

node dist/bin/fdw.js --version
node dist/bin/fdw.js --help
node dist/bin/fdw.js init
node dist/bin/fdw.js init --book-markdown
node dist/bin/fdw.js update

fdw init

Initialize FDW-managed project files in the current directory. World builder skill templates are installed by default.

node dist/bin/fdw.js init

Expected successful output includes a deterministic summary line:

FDW_INIT_RESULT status=initialized created=<n> unchanged=<n> managed=<n>

Installed files include base framework assets, world builder output stubs, and world builder skill files:

• openspec/config.yaml
• schemas/fictionspec/spec.md
• templates/story-outline.md
• templates/world-builder/world-overview.md
• templates/world-builder/magic-system.md
• templates/world-builder/factions.md
• templates/world-builder/timeline.md
• .github/skills/world-builder/overview.md
• .github/skills/world-builder/timeline.md
• .github/skills/world-builder/factions.md
• .github/skills/world-builder/magic-system.md

If run again in an already initialized project, it is idempotent and reports:

FDW_INIT_RESULT status=already_initialized created=0 unchanged=<n> managed=<n>

Existing projects: Run fdw update after upgrading the package to receive updated world builder templates and skill files.

Scaffold markdown book assets

Install baseline markdown book directories and a deterministic Makefile:

node dist/bin/fdw.js init --book-markdown

This mode requires a previously initialized project (fdw init).

Expected successful output includes:

FDW_INIT_RESULT status=book_markdown_initialized created=<n> unchanged=<n> skipped=<n> conflicts=<n> managed=<n>

Generated scaffold assets include:

• templates/book-markdown/scenes/index.md
• templates/book-markdown/chapters/chapter-01.md
• templates/book-markdown/chapters/chapter-02.md
• templates/book-markdown/compiled/manuscript.md
• Makefile

Quickstart build commands:

make chapters
make book

fdw update

Refresh FDW-managed project files previously installed by init.

node dist/bin/fdw.js update

Expected successful output includes:

FDW_UPDATE_RESULT status=updated created=<n> updated=<n> unchanged=<n> managed=<n>

If the project is not initialized, update exits non-zero with:

FDW_UPDATE_ERROR reason=not_initialized message=No FDW project found. Run "fdw init" first.

World Builder Skills

fdw init installs two sets of world builder assets into every project:

| Asset type | Install location | Purpose | |---|---|---| | Output stubs | templates/world-builder/ | Markdown templates for author-populated world documents | | Skill files | .github/skills/world-builder/ | Agent instruction files defining per-aspect commands |

Agent Commands

Each skill file defines a canonical agent command that authors invoke inside their AI agent (GitHub Copilot, Claude, Cursor, etc.). The agent reads the skill file and follows its execution instructions.

| Command | Skill file | Output artifact | |---|---|---| | /world:overview | .github/skills/world-builder/overview.md | world/world-overview.md | | /world:timeline | .github/skills/world-builder/timeline.md | world/timeline.md | | /world:factions | .github/skills/world-builder/factions.md | world/factions.md | | /world:magic-system | .github/skills/world-builder/magic-system.md | world/magic-system.md |

How Skills Work

Each skill follows a three-step execution pattern:

1. Fill-then-ask — the agent extracts facts from the author's input and populates all directly mappable fields in the output stub before asking any questions. Only unresolved required fields trigger follow-up questions.
2. Continuity check — before finalising output, the agent compares candidate content against existing world files and reports hard contradictions or weak continuity links, each with a source-citation link to the referenced file.
3. Guidance-based conflict resolution — when a contradiction is detected the agent asks the author which version is correct rather than silently overwriting existing content.

Receiving Updated Skill Files

Skill files are managed assets. Run fdw update in an existing project to refresh them:

node dist/bin/fdw.js update

If you have customised a skill file at its target path, fdw update skips that file and reports it as skipped/conflicts to avoid data loss.