NovelParsingLibrary/{ImportedNovelTitle}/

Agent Compatibility: When checking the availability of professional agents, search in the order of

.claude/agents/{agent}.md

→

.opencode/agents/{agent}.md

→

.codex/agents/{agent}.toml

. Codex native sub-agent calls prioritize using the same-named

agent_type

; if the current Codex runtime returns

unknown agent_type

or does not expose the custom-agent registry, it must degrade to solo/direct. When

.zcode/

is detected, directly use solo/direct as well, because ZCode 3.3.4 does not execute project custom agents; report

Fallback: project custom agents unavailable -> solo

. Claude/OpenCode compatibility retains

subagent_type

.

Spawn Version Prompt (does not block spawn): First read

agents_version

from the project root

.story-deployed

. When it is inconsistent with the current version

agents_version: 25

(missing marker, missing/non-integer field, less than or greater than 25) proceed with file existence check and spawn as usual, while reporting

Notice: agents bundle version mismatch (project {N}, current version 25)

and prompting to re-run

/story-setup

before starting a new session; when greater than 25, additionally prompt to update oh-story-claudecode first, do not use the local old setup to downgrade and overwrite. Only when the agent file is missing or the runtime does not expose the custom agent, degrade to solo/direct and report

Fallback: ... -> solo

.

• {ImportedNovelTitle}

  : The novel that the user has already written halfway or completed, and now wants to reconstruct into a project; its analysis source is fixed as

  NovelParsingLibrary/{ImportedNovelTitle}/

  .

• {ReferenceNovelTitle}

  : An external reference work selected separately by the user; it must be an independent parsed product, with the source fixed as

  NovelParsingLibrary/{ReferenceNovelTitle}/

  , and must not point to the current import source.

• story-import

  can reuse the parsing pipeline to analyze

  {ImportedNovelTitle}

  , but must not register

  {ImportedNovelTitle}

  as the primary/secondary reference work, nor copy

  NovelParsingLibrary/{ImportedNovelTitle}/

  or the project

  Settings/

  into

  ReferenceWorks/

  .
• When the user does not explicitly select an external reference work, do not create a reference subdirectory or write "Primary Reference Novel"; this will be handled separately by the reference discovery workflow of story-long-write / story-short-write later.

1. Recommended Order: First run

   /story-setup

   (deploy hooks/agents/AGENTS), start a new/refreshed session, then run

   /story-import

   , and finally use

   /story-long-write Daily Update/Write Chapter N

   to continue writing.
2. Can also directly run

   /story-import

   : This skill will detect

   .story-deployed

   and professional agents before entering in-depth analysis; when not deployed, it will provide two options: "Go to setup first" or "Continue importing (serial downgrade)".
3. Current protocol project that has been imported before (has

   Tracking/_tracking-state.json

   under the novel title directory): Do not run the full import again; directly enter the novel title directory, confirm that

   .active-book

   points to the correct book, then use

   /story-long-write Daily Update

   or

   /story-long-write Write Chapter N

   to continue writing.
4. Old tracking projects of v0.7.2 or earlier (has

   Tracking/

   and manuscript, but no

   Tracking/_tracking-state.json

   ): Daily update will stop and require re-import, but no need to re-run full book parsing. Only rebuild the tracking, see "Old Tracking Project Migration" below.

Tracking/

Tracking/_tracking-state.json

Settings/

Outline/

NovelParsingLibrary/

Tracking/

1. Count the last complete chapter number

   N

   (the maximum value of

   Manuscript/Chapter NNN_*.md

   ).
2. Reconstruct the current state from the existing files in the old

   Tracking/

   (character status, foreshadowing, timeline, etc., file names according to the actual project situation) and the latest 3-5 chapters of the manuscript: core character snapshots, unrecovered foreshadowing, revealed timeline events, long-term constraints, next chapter commitments. Refer to references/character-state-reverse.md for the reverse method of character snapshots.
3. Construct JSON according to the initialization transaction format in references/tracking-transaction.md, write

   N

   in

   last_chapter

   (do not fake chapter-by-chapter records for Chapter 1..N), and execute

   tracking_commit.py init

   .

4. init

   will move the entire old tracking structure into

   Tracking/_OldTrackingArchive/

   as-is before building the current protocol — old content is not deleted or involved in parsing, reserved for the author to review.
5. Run

   tracking_commit.py check

   to confirm passing, then return to

   /story-long-write Daily Update

   to continue writing.

continuity_risks

"Do you want to turn this book into a continuable writing engineering project (Settings/Outline/Manuscript/Tracking, can continue writing Chapter N+1), or only need a parsed library analysis?"

• Want a continuable project → proceed with full story-import (Phase 2 parsing + Phase 3 migration).
• Only need analysis / parsed library → directly use

  /story-long-analyze

  (short stories use

  /story-short-analyze

  ), stop at the parsed library, do not enter Phase 3 migration.

1. Automatic Detection: Identify the novel title (if any), total chapters, total word count, chapter format from the text
2. User Confirmation:
   • Imported Novel Title: {Automatically detected or user input}
   • Genre: {Provided by user}
   • Target Platform: {Qidian/Fanqie/Jinjiang/Other}
   • Completed: {Yes/No (unfinished up to Chapter N)}
   • Length Type: Long Novel / Short Story — automatically detected according to references/length-routing.md (user explicit declaration > structural signals > word count fallback), and repeat the detection result to the user for confirmation. The determination result decides whether Phase 3 follows the long novel or short story path.
   • Is the last chapter complete: Complete Chapter / Unfinished Draft (half-written). If it is an unfinished draft, prompt the user and record "Unfinished draft up to Chapter N" in the context, let the user decide whether to "Continue writing based on the unfinished chapter" or "Complete it first then import". story-import only records the user's decision, does not make the choice for the user.
3. External Reference Work (Optional, Separated from Import Source): When the user has explicitly specified an external reference work, record

   {ReferenceNovelTitle}

   and confirm that

   NovelParsingLibrary/{ReferenceNovelTitle}/

   is an independent parsed product of this reference work; do not use

   {ImportedNovelTitle}

   or the newly generated parsing directory as a candidate. Do not ask additional questions when the user does not specify, mark as "Unbound", and hand it over to the reference discovery workflow of the writing skill later.
4. Output Confirmation: Show the detected chapter range, word count, determined length type, last chapter status, and "External Reference Work: {ReferenceNovelTitle/Unbound}" to the user, start analysis after confirmation.

• First read

  .story-deployed

  and execute the top Spawn version gate; even if the old

  chapter-extractor

  file is still on the disk, it cannot be reused.
• Only after

  agents_version: 25

  passes, check the Phase 2 long novel parallel agent in the order of

  .claude/agents/chapter-extractor.md

  →

  .opencode/agents/chapter-extractor.md

  →

  .codex/agents/chapter-extractor.toml

  .
• If

  target_cli

  in

  .story-deployed

  includes

  zcode

  , the missing project agents are the expected state of ZCode 3.3.4: do not prompt for redeployment, directly enter analysis in serial solo/direct mode and report fallback.

"Detected that the current project has not deployed writing infrastructure. It is recommended to run

/story-setup

before importing, otherwise the parallel chapter-extractor agent cannot be used during the in-depth analysis phase."

1. Go to setup first: Pause the import, run

   /story-setup

   , and re-trigger

   /story-import

   after deployment is completed;
2. Continue importing: Accept the downgrade of Phase 2 to serial processing (long novel chapter-by-chapter summarization is not parallel, slower speed, but complete deliverables).

Plot/Rhythm.md

Plot/EmotionModules.md

_progress.md

schema_version: 2

Plot/Rhythm.md

Plot/EmotionModules.md

• Example wording: When starting in-depth analysis, declare "Parse this book in 'Full Parsing, Run Once, Do Not Stop to Ask' mode to ensure all outputs from Stage 2-6 are produced".
• Fallback: If the runtime actually still stops at the Stage 1 question, story-import automatically selects "Continue Full Parsing", never pass the stop question to the user.
• When the environment detection (Phase 1) finds that the chapter-extractor agent is not deployed and the user chooses "Continue Importing", Stage 2 chapter-by-chapter summarization downgrades to serial processing, deliverables are still complete, only speed is slower.

NovelParsingLibrary/{ImportedNovelTitle}/_meta.json

stages_completed

ParsingReport.md

PlotNodes.md

WritingTechniques.md

OriginalText/

NovelParsingLibrary/{ImportedNovelTitle}/_archive_{timestamp}/

genre_detected

_meta.json

• Example wording: When starting in-depth analysis, declare "The length of 《{ImportedNovelTitle}》 has been confirmed as Short Story (genre {Genre}, about {N} words total), Step 2 continues directly as Short Story, Step 4 is processed as Overwrite and Archive, genre recognition runs as usual to ensure all outputs from Stage 2-6 are produced".
• Fallback: If the runtime still throws "This text has {N} words, which is relatively long, it is recommended to use

  /story-long-analyze

  " or a gray area question "Between short/long, parse as short or long?", always reply word-for-word according to the determination locked in Phase 1: "Continue as Short Story", never pass the routing question to the user.

Detailed pipeline description can be found in story-long-analyze (run

/story-long-analyze

), only summary is listed here.

Plot/*.md

Plot/README.md

Plot/Storyline.md

Plot/Rhythm.md

Plot/EmotionModules.md

Settings/*.md

Characters/*.md

Plot/Rhythm.md

Plot/EmotionModules.md

NovelParsingLibrary/{ImportedNovelTitle}/WritingStyle.md

ReferenceWorks/

Detailed pipeline description can be found in story-short-analyze (run

/story-short-analyze

), only summary is listed here.

NovelParsingLibrary/{ImportedNovelTitle}/

ParsingReport.md

PlotNodes.md

WritingTechniques.md

_meta.json

• Track progress through progress files when interrupted
• New session reads progress files to locate breakpoints
• Resume from the starting chapter of the block where the breakpoint is located
• Long novel progress file format follows the progress paragraph convention of the story-long-analyze parsing pipeline, including current stage, last processed chapter, list of completed stages, update time

Manuscript/

Chapter_XXX_ChapterTitle.md

• Identify chapter separators (Chapter X, 第X章, etc.)
• Extract chapter titles
• Pad numbers with zeros for alignment (Chapter 1 → Chapter 001)
• Keep original text content unchanged

Plot/Storyline.md

Plot/*.md

QuickPreview.md

• Original text has clear volume boundaries (has volume-level titles like "Volume 1", "第一卷", etc.) → directly divide according to the original text volume boundaries, no need to ask.
• Original text has no clear volume boundaries → do not mechanically cut by "20-40 chapters per volume". Detect candidate volume boundaries based on storyline/scene switching/large time jumps, show the candidate division plan to the user, wait for user confirmation before finalizing the volume outline; before user confirmation,

  Outline/Outline.md

  only records the candidate plan.

undefined

• Function: {Inferred from plot analysis}
• Core Event: {One sentence}
• Starting State → Ending State: {Inferred from character arc}

**Volume Outline**: After volume division is confirmed, aggregate from plot files to generate `Outline/VolumeOutline_VolumeX.md`, according to the "Volume Outline Reverse-engineering" template format in [structure-mapping-long.md](references/structure-mapping-long.md).

**Detailed Chapter Outline**: Reverse-engineered from chapter summaries to generate `Outline/DetailedOutline_ChapterXXX.md`:

```markdown

• Core Event: {Extracted from summary}
• Word Count Target: {Actual word count of original text}
• Target Emotion: {Extracted from chapter tone/emotion curve; write [To be supplemented] if unknown}
• Chapter Opening Hook: [To be supplemented]
• Highlight: {Inferred from plot nodes; write [To be supplemented] if no clear evidence}

• Cause: {Summarized from plot nodes; write [To be supplemented] if unknown}
• Development: {Summarized from plot nodes; write [To be supplemented] if unknown}
• Twist: {Summarized from plot nodes; write [To be supplemented] if unknown}
• Climax: {Summarized from plot nodes; write [To be supplemented] if unknown}
• Ending: {What action/scene/line the original text ends with; write [To be supplemented] if unknown}

• Main Plot Advancement: {Reverse-engineered from plot unit index/summary}
• Subplot Advancement: {Write "None" or [To be supplemented] if no evidence}
• Event Line / Task Line: {External event chain}
• Emotional Line / Relationship Line: {Write only if there is evidence; otherwise "No explicit" or [To be supplemented]}
• Logical Line: Cause → Action → Result → Consequence/New Problem

• Appearance Order: {Order of appearance of characters/forces/key objects in the summary}
• Character Relationship Changes: {Before this chapter → After this chapter; write [To be supplemented] if unknown}
• Perspective/Information Gap: {Who knows what; readers know what; protagonist misjudges what; write [To be supplemented] if unknown}

• Plot Node Sequence (Fill in the table below line by line; reverse-engineered from summary plot nodes):

• Action Cost (Optional)/Benefit Attribution: {Write only if there is evidence; action cost can be omitted, do not force creation; write [To be supplemented] if unknown}

• Ending Setting: {What action or scene the original text ends with; unresolved issues; motivation for next chapter; write [To be supplemented] if unknown}
• Chapter Closing Hook: [To be supplemented]

> Fields that cannot be stably judged from the original text summary, such as hooks, character relationship changes, subplots/emotional lines, action cost/benefit attribution, are uniformly marked `[To be supplemented]`; story-import only reverse-engineers blueprints with evidence, does not fabricate relationships or subplots to fill fields.

scripts/tracking_commit.py init

1. Import Cut-off Chapter: Write the last complete chapter N into

   last_chapter

   of the initialization transaction. The tool records

   imported_through_chapter=N

   in meta; there are no daily update transactions for imported old chapters, do not fake chapter-by-chapter increments for Chapter 1..N, and start continuation from N+1. If it is mistakenly written as 50 during init, Chapter 51..N can still be added chapter-by-chapter with

   append

   (one transaction per chapter, chapter numbers must be consecutive), but it is necessary to construct transactions for each written old chapter; do not delete

   Tracking/

   and start over —

   _OldTrackingArchive/

   is also inside.
2. Current Core Character Snapshots: Reverse-engineer the status of protagonists, antagonists, and core supporting characters up to Chapter N from the parsed book deliverables, write into

   character_snapshots

   of the initialization JSON. The output is generated by the tool to

   Tracking/CharacterStatus/{CharacterName}.md

   ; algorithm see references/character-state-reverse.md.
3. Current Foreshadowing Status: Generate

   foreshadow

   from foreshadowing/recovery events with manuscript evidence. Only keep one line of current status per ID; future designs that have not been actually laid out are kept in the outline, not written into

   Foreshadowing.md

   .
4. Facts and Reader Perception: Generate key events into

   timeline_events

   . Write objective facts, what readers know up to Chapter N, and actual revelation status for the same event; future planned revelation chapters must not be disguised as occurred facts.
5. Continuation Status Card Input: Prepare current position, long-term constraints, active core characters, quick notes of the last three chapters, next chapter commitments, and continuity risks.

   Context.md

   is generated by the tool with fixed 7 columns, do not stuff writing style, file indexes, general to-dos, or quality check counts into the continuation status card.
6. Execute Initialization: Detect Python 3 according to the current platform (

   python3

   →

   python

   →

   py -3

   ), execute:

   When there are early files in the project

   Tracking/

   that do not belong to the current protocol, there is no need to manually clean them:

   init

   will first move them all into

   Tracking/_OldTrackingArchive/

   as-is, then build the current protocol in place. Old content is retained for the author to review, not involved in parsing, and the current status is completely determined by the current import input; if

   init

   fails verification, no files are moved.

   text

   {PYTHON} {story-import skill root}/scripts/tracking_commit.py init --project {project root} --input {initialization transaction.json}
   {PYTHON} {story-import skill root}/scripts/tracking_commit.py check --project {project root}

Tracking/
├── _tracking-state.json
├── Context.md
├── ChapterByChapterRecords/                 # No files are added for imported old chapters, continuation starts from Chapter N+1
├── CharacterStatus/{CharacterName}.md
├── Foreshadowing.md
├── Timeline/
│   ├── AuthorTruth.md
│   └── ReaderKnown.md

last_chapter

NovelParsingLibrary/{ReferenceNovelTitle}/

{Project}/ReferenceWorks/{ReferenceNovelTitle}/

NovelParsingLibrary/{ImportedNovelTitle}/

Settings/

• The selected external reference work lacks

  Plot/Rhythm.md

  or

  Plot/EmotionModules.md

  → do not register or generate a half-set reference view; report

  module_or_rhythm_required_missing

  and prompt to re-run

  /story-long-analyze

  Stage 3+ for

  {ReferenceNovelTitle}

  . The core project migration of this book is not rolled back due to this.
• Other structured subdirectories are missing → prompt according to existing import missing items, do not block project creation

NovelParsingLibrary/{ReferenceNovelTitle}/WritingStyle.md

{Project}/ReferenceWorks/{ReferenceNovelTitle}/WritingStyle.md

• No writing style file in the parsing library (analyze did not run Stage 6) → prompt the user to re-run

  /story-long-analyze

  before synchronization in the import report; missing writing style will be fail-fast blocked before daily update
• Old writing style file already exists in the project reference → overwrite (latest parsed deliverable takes precedence), inform in the import report

NovelParsingLibrary/{ImportedNovelTitle}/

{ShortStoryTitle}/

Short story projects are completely different from long novels: The short story manuscript is a single file

Manuscript.md

(no chapter splitting), does not generate long novel-specific directories like

Tracking/

,

Outline/

,

Manuscript/

. Do not mistakenly create these directories during migration.

{Title}/Settings.md

ParsingReport.md

WritingTechniques.md

• Core Framework: Aligns with the story-short-write core framework template (basic information, one-sentence synopsis, core twist, emotion design, character sketch).
• Book Continuation Baseline: Write the story structure, emotion rhythm, core twist mechanism, and existing writing techniques of the written content into the continuation baseline section; this is the book's internal context, not a reference summary.

• Long Novel: Complete import quality list can be found at the end of references/structure-mapping-long.md (including manuscript file count comparison, independent core character snapshots, author/reader timeline isolation,

  tracking_commit.py check

  passed, volume division confirmed by user, etc.).
• Short Story: Quality list can be found in the quality check list at the end of references/structure-mapping-short.md (including

  Manuscript.md

  single file exists and format is compliant,

  Settings.md

  contains core framework + book continuation baseline, no long novel-specific directories mistakenly created, etc.).

• Manuscript: {N} chapters
• Character Files: {M} pieces
• Outline: Outline.md + {V} volume outlines + {N} detailed chapter outlines
• Tracking: Unique structured state + independent derived snapshots of core characters + current foreshadowing view + dual timeline views + empty chapter-by-chapter records directory + fixed 7-column context
• Settings: {Number of worldview files} pieces
• External Reference Works: {Unbound / Synchronized from

  NovelParsingLibrary/{ReferenceNovelTitle}/

  to

  ReferenceWorks/{ReferenceNovelTitle}/

  / Binding failed and repair actions}

• Chapter opening/closing hooks in detailed outlines need to be supplemented
• The three-part classification of core gimmicks in genre positioning needs to be confirmed
• Foreshadowing in foreshadowing tracking has been reviewed

• Tracking/Timeline/ReaderKnown.md

  does not reveal facts in

  AuthorTruth.md

  that have not been disclosed yet
• Volume division has been confirmed (when original text has no clear volume boundaries)

• NovelParsingLibrary/{ImportedNovelTitle}/

  has not been copied to the project

  ReferenceWorks/

  , and this book has not been registered as its own reference work
• If an external reference work is bound, the

  Primary Reference Work

  and

  Reference Works List

  in

  Settings/GenrePositioning.md

  only include independent

  {ReferenceNovelTitle}

  , and the synchronization source is consistent with the directory name

• Run

  /story-review lean

  to review the import result
• Run

  /story-long-write

  + "Daily Update" to start continuation

**Short Story Import Completion Report**:

• Manuscript.md (single file, {Y} words)
• Settings.md (core framework + book continuation baseline)
• SectionOutline.md ({N} sections)
• External Reference Works: {Unbound /

  ReferenceWorks/{ReferenceNovelTitle}/

  synchronized / Binding failed and repair actions}

• All files marked [To be supplemented] have been reviewed
• Chapter opening/closing hooks in section outlines need to be supplemented
• Foreshadowing clues of core twists have been confirmed

• Run

  /story-short-write

  Phase 3 to start continuation

undefined

• Set

  .active-book

  to point to the imported novel/title directory
• Confirm that the project can be recognized by the corresponding writing skill (long novel → story-long-write, short story → story-short-write)
• Optional Verification: If the project has deployed the story-explorer agent (first check if

  story-explorer.md

  exists under

  .claude/agents/

  ; if not, check

  .opencode/agents/

  , then

  .codex/agents/

  ), spawn

  Agent(subagent_type: "story-explorer", prompt: "Project Directory: {dir}\nQuery Type: progress\nQuery Parameters: Import Verification")

  to cross-verify the integrity of migrated data

Environment deployment detection has been completed in Phase 1 "Pre-Environment Detection", no repeated detection here.

This section only applies to long novel imports. Short stories are full migrated as single files, no incremental import needs.

1. Batch Parsing: In the first phase, only deeply parse the first 50 chapters + full book summary, then parse more chapters into

   NovelParsingLibrary/

   as needed.
2. Tracking in One Go: Write the last written chapter number N into

   last_chapter

   of the initialization transaction, not 50 of the first phase parsing.

   imported_through_chapter

   is written once by

   init

   and not updated later; chapter-by-chapter transactions only accept chapter numbers starting from N+1; do not fake chapter-by-chapter records for Chapter 1..N, start continuation from N+1. If it is mistakenly written as 50 during init, Chapter 51..N can still be added chapter-by-chapter with

   append

   (one transaction per chapter, chapter numbers must be consecutive), but it is necessary to construct transactions for each written old chapter; do not delete

   Tracking/

   and start over —

   _OldTrackingArchive/

   is also inside.
3. Context Summary: Generate simplified summaries (200 words per chapter) for chapters that have not been deeply parsed, for reverse-engineering the current state.

references/structure-mapping-long.md

references/structure-mapping-short.md

references/character-state-reverse.md

references/state-tracking.md

references/format-and-structure.md

The detailed chapter outline template format for long novels can be found in story-long-write (Phase 3 Detailed Outline section); the short story core framework template can be found in story-short-write (Core Framework section). These are plain text guidelines, story-import does not load files from the corresponding skills.

• Reply in the user's language, use the same language as the user
• Chinese replies follow the Chinese Copywriting Guidelines