scrivener-create-project

Scrivener: Create or Fork a Project

You help the writer start a new .scriv project from scratch, or fork an existing one into a separate working copy they can experiment on without risking the original. A .scriv is a structured package: it must stay valid and openable in Scrivener 3, so scaffold it deliberately, not by guesswork.

When to Use

• "Create a new Scrivener project" / "start a new .scriv" / "scaffold a project"
• "Make a copy of this project so I can experiment" (fork / Save-As)
• The user wants a blank manuscript they can then import into or edit

Toolkit support

Need	Command	Status
Scaffold a new project	new-project <path> [--template <name>] [--import <dir|file>]	🔜 planned
Copy a project to a new working copy	fork <src> <dst>	🔜 planned
Timestamped zip of the whole project	backup [--out <dir>]	✅ available now
Validate a package	verify	✅ available now
Add binder items after scaffolding	add, rename, move (see scrivener-edit)	✅ available now

Be honest with the user: new-project and fork are roadmap, not in the CLI yet. Until they ship, use the two workarounds below.

Fork today (the supported workaround)

To make a working copy you can experiment on, do NOT edit the original. Two safe options, both available now:

1. backup the source — produces a timestamped zip; unzip it to a new path and open that copy. This is the closest available equivalent to fork.

   python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py backup \
     --project "/path/MyNovel.scriv" --out "/path/forks"
   # then unzip the resulting zip to "/path/MyNovel-experiment.scriv"
   

2. Copy the package directory (.scriv is a folder/bundle). After copying, always validate the copy before editing it:

   cp -R "/path/MyNovel.scriv" "/path/MyNovel-experiment.scriv"
   python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py verify \
     --project "/path/MyNovel-experiment.scriv"
   

Then point all subsequent commands at the copy. Tell the user the original is untouched.

Create a blank project today (hand-built minimum)

new-project is planned, so when the user needs a new project now, hand-build the minimum valid package. The full byte-level layout is in references/new-project-structure.md; the essentials:

• A <Name>.scrivx whose <Binder> contains exactly three special root folders: a DraftFolder, a ResearchFolder, and a TrashFolder (identified by Type, not by title).
• Files/version.txt containing 23 (the format version for Scrivener 3).
• A Files/Data/ directory (empty is fine — items only get a Data/<UUID>/ folder once they have content).

Special root folders have no Data/<UUID> directory, and that is normal, not corruption. After building it, run verify and open it in Scrivener once to let it regenerate UI/autosave files.

python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py verify \
  --project "/path/NewProject.scriv"

Once the skeleton opens, switch to scrivener-import to bring text in, or scrivener-edit to add chapters and scenes.

Templates (planned)

When new-project --template <name> ships, templates resolve <$template_*> placeholders (e.g. <$template_title>, <$template_author>) into project metadata and starter binder items. There is no template engine in the CLI today — note this to the user and offer the hand-built blank project plus add instead. See references/new-project-structure.md for the placeholder convention.

Safety

• Have the user close the project in Scrivener and let cloud sync (Dropbox/iCloud) finish before you copy or edit any .scriv.
• When forking, operate on the copy; never mutate the original.
• docs.checksum mismatches in a copied project are advisory, never corruption — offer repair --checksums if the user cares, don't block on it.
• Titles are not unique; once items exist, address mutating commands by UUID.

Related skills

• scrivener-format — canonical .scriv package format; the structure this skill scaffolds against.
• scrivener-import — bring files/research into the new project.
• scrivener-edit — add, move, rename, and restructure binder items after the skeleton exists.
• scrivener-integrity — verify, backup, repair for the copy you make.