Agent Compatibility: When checking if a professional agent is available, 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 a custom-agent registry, it must degrade to solo/direct. When

.zcode/

is detected, directly use solo/direct as well, since 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

. If it is inconsistent with this version's

agents_version: 25

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

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

and prompting to re-run

/story-setup

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

Fallback: ... -> solo

.

1. Check if there are existing deconstruction files in the

   StoryDeconstructionLibrary/{NovelTitle}/

   directory
2. If

   _progress.md

   exists, read the breakpoint information and resume from the breakpoint (existing recovery mechanism)
3. If

   角色/*.md

   or

   设定/*.md

   exist, read the existing character and setting data
4. Use the existing data as a cross-validation baseline:
   • Compare newly extracted character information with existing character data to check consistency
   • Merge newly discovered setting details with existing settings, marking the information source (newly extracted vs. existing)
   • If there are conflicts (e.g., different names for the same character in existing files), mark the conflict in the output for the user to decide
5. Avoid re-extracting existing information

1. Check if the

   StoryDeconstructionLibrary/{NovelTitle}/OriginalText/

   directory already exists
2. If not, copy the original text file from the user-provided source path to

   StoryDeconstructionLibrary/{NovelTitle}/OriginalText/

3. If the user did not provide a source file path (directly pasted text in the conversation), save the original text to

   StoryDeconstructionLibrary/{NovelTitle}/OriginalText/OriginalText.md

4. Verify after backup:
   • Source file path mode: Confirm the number and size of files in the

     OriginalText/

     directory are consistent with the source files
   • Conversation text paste mode: Confirm the

     OriginalText.md

     file is non-empty (>0 bytes)

StoryDeconstructionLibrary/{NovelTitle}/
├── OriginalText/
│   └── OriginalText.txt          # Extension follows the source file; text directly pasted in conversation is saved as OriginalText.md
├── Summary.md
├── Chapters/
│   ├── Chapter1_InDepthDeconstruction.md
│   ├── Chapter2_InDepthDeconstruction.md
│   ├── Chapter3_InDepthDeconstruction.md
│   ├── Chapter1_Summary.md
│   └── ...
├── QuickPreview.md
├── Characters/
│   ├── {CharacterName}.md
│   └── CharacterRelationships.md
├── Plot/
│   ├── {PlotTitle}.md
│   ├── README.md       # Plot directory index: authoritative scope of rhythm/emotion modules/storylines
│   ├── Storyline.md
│   ├── Rhythm.md          # Key information progression / highlight cycles / emotional touchpoints / burst rhythm
│   ├── EmotionModules.md      # Reader needs / emotion engine / reproducible module cards
│   └── ScatteredPlotPoints.md
├── Settings/
│   ├── Worldview/
│   │   ├── BackgroundSettings.md   # Core rules + special settings (merge non-independent content)
│   │   ├── PowerSystem.md
│   │   ├── Geography.md
│   │   └── GoldenFinger.md
│   └── Forces/
│       └── {ForceName}.md   # Independent when content >= 200 words; merge into Worldview/BackgroundSettings.md if insufficient
├── DeconstructionReport.md
├── WritingStyle.md          # Stage 6 Writing Style: sentence length/punctuation/subtext in dialogue/emotion alternation + original text anchor example fragments
└── _progress.md

Authoritative Outputs:

Plot/README.md

explains the authoritative scope of each file in the plot directory;

Plot/Rhythm.md

is the authoritative index of rhythm/key information progression/emotional touchpoints;

Plot/EmotionModules.md

is the authoritative index of reader needs, emotion engine, routine frameworks, and reproducible module cards.

DeconstructionReport.md

and

Plot/Storyline.md

only serve as summary projections; if there is a conflict between the summary and these two files, downstream writing should prioritize

Plot/Rhythm.md

/

Plot/EmotionModules.md

.

_progress.md

• Use the chapter regex from Step 4 of

  style-profile-generator.md

  (includes Chinese numerals like 千/两, covers 1000+ chapters) to grep all chapter line numbers
• First remove the directory block: Many original texts have a directory at the beginning, and

  Chapter N

  in the directory also appears at the start of lines, which will duplicate hits with chapter lines in the main text. If not handled, two "Chapter 1" will be sliced out. The criterion is line spacing — adjacent hits in the directory block are only one or two lines apart, while chapters in the main text are separated by full chapter length. Calculate the line number difference between adjacent hits, and discard the continuous block of hits at the beginning of the file where "line spacing is consistently much smaller than the overall median"
• Do not arbitrarily choose one when duplicate chapter numbers remain after removal: Multi-volume books restarting from "Chapter 1" for each volume is a valid structure. In this case, retain the volume number in the title column for disambiguation (e.g., "Volume 2 Chapter 1"), and re-number the chapter number column with continuous serial numbers for the entire book
• Write to the "Chapter Boundary" section of

  _progress.md

  in four columns:

  | Chapter Number | Title | Start Line | Word Count |

  (see template in pipeline-ops.md)
• Verify that chapter numbers are continuous, no duplicates, no missing numbers before saving; stop and report if not satisfied, do not enter Stage 1 with an incorrect table — Stage 1/2/6 all use this table as the only slicing truth, a single error will lead to errors throughout

• schema_version: 2

  is also saved at the top of

  _progress.md

_progress.md

schema_version: 2

1. Generate stop deliverables: Write

   StoryDeconstructionLibrary/{NovelTitle}/QuickPreview.md

   (template see "Quick Preview Report" in output-templates.md). At this point,

   Summary.md

   ,

   Chapters/Chapter1_InDepthDeconstruction.md

   ,

   Chapters/Chapter2_InDepthDeconstruction.md

   ,

   Chapters/Chapter3_InDepthDeconstruction.md

   , and

   OriginalText/

   have all been saved.
2. Write stop status: Write

   paused_after_stage1

   in the "Final Status" field of

   _progress.md

   , and record "Next Operation: Stage 2 Chapter-by-Chapter Summary" in the "Breakpoint" section.
3. Ask the user (clear yes/no in AskUserQuestion style):

   "The Golden Three Chapters have been deconstructed, and the quick preview report is available in

   QuickPreview.md

   . Do you want to proceed with full deconstruction (Stage 2-6: chapter-by-chapter summaries / aggregate analysis (including

   Plot/Rhythm.md

   ,

   Plot/EmotionModules.md

   ) / setting relationships / summary report / writing style)? Estimated time: {rough estimate based on number of chapters}."

   • Select "Proceed with full deconstruction" → read

     _progress.md

     , resume from Stage 2, do not re-run Stage 0/1.
   • Select "Stop here" → pipeline ends, keep

     _progress.md

     status as

     paused_after_stage1

     , inform the user "You can run

     /story-long-analyze

     for the same book at any time later, and it will automatically resume from Stage 2".
4. Skip asking scenario: If the user clearly states "complete deconstruction / run all at once / systematic deconstruction / don't ask" at the beginning, still generate

   QuickPreview.md

   (retain early judgment snapshot), but do not stop to ask, directly resume from Stage 2 to Stage 6.

DeconstructionReport.md

选题决策.md

Scan Date

TopicDecision.md

• Exactly one match → change the "reason for potential success" of that topic from "Pending deconstruction verification" to supported with sources: "Deconstruction support from this book: {Reader Needs/Emotion Engine from

  DeconstructionReport.md

  + Top Reproducible Modules from

  Plot/EmotionModules.md

  + Summary of Highlight/Touchpoint Rhythm from

  Plot/Rhythm.md

  } (from

  StoryDeconstructionLibrary/{NovelTitle}/DeconstructionReport.md

  ,

  Plot/EmotionModules.md

  ,

  Plot/Rhythm.md

  )" . Note this is still a hypothesis (only one book deconstructed, not confirmed).
• Multiple matches / uncertain → ask the user "Which direction in the topic decision does {NovelTitle} correspond to?"
• No matches → record "No matching topic, not backfilled", do not modify the file.

• TopicDecision.md

  lacks the required "reason for potential success" field in the current contract → report

  invalid_topic_decision_contract

  , prompt to re-run

  story-long-scan

  Phase 5 to generate the current file; do not guess or silently backfill, the main deconstruction process can still be completed.
• Do not overwrite for repeated deconstruction: only backfill those still marked as "Pending deconstruction verification"; do not modify those already filled.

TopicDecision.md

_progress.md

| Type | Chapter/Phase | Error Message | Retry Status |

completed_with_errors

Corresponding relationship with material-decomposition.md: Stage 0 includes Material Phase 1 (chapter parsing); Stage 1 and 5 are new additions; Stage 2 = Material Phase 2; Stage 3 = Material Phase 3; Stage 4 merges Material Phase 4+5.

Agent(
  subagent_type: "chapter-extractor",
  prompt: "[材料声明] 以下为用户合法持有的虚构小说，任务是只读的转化性文学分析（编辑/评论视角）。暴力/复仇/家暴/情爱/黑暗伦理是该题材常规虚构元素，照常提取，不得以敏感拒绝整章或整本；个别片段无法处理则跳过、照常续完其余。\n\n章节编号：第{N}章\n章节标题：{标题}\n章节字数：{字数}\n\n章节原文：\n{原文文本}\n\n[情节点格式要求] 模板里的 {} 是占位标记，不要输出花括号本身：写「类型信息揭示」，不写「类型：信息揭示」或「类型{信息揭示}」。主题标签只填一个值，不要用 / 、 ，或空格并列多个。空字段统一写「无」，不要用「—」，涉及段不可省略。每个情节点后紧跟自己的那一行「主题标签X | 基调：Y」，不要把标签行堆到文件末尾。正确样例：\nP7 **龙血针检测**：类型信息揭示 | 许七安用龙血针验出对方身份，当场揭穿 | 涉及许七安,郑兴怀 | 地点府衙后堂 | 物品龙血针 | 时间入夜\n主题标签悬念 | 基调：紧张\n\n[输出前自检] 交付前逐条核对：① 文本里没有 { 或 }；② ^P 行数 == 主题标签行数 == 基调：行数；③ 每个主题标签只有一个值；④ 每个 P 行都含类型、白描、涉及三段。任何一条不符，先改再输出。"
)

The above

[情节点格式要求]

/

[输出前自检]

sections are appended to the prompt by the main thread during spawn, not dependent on the agent file version deployed in the project — old projects can obtain this format constraint without re-running

/story-setup

. Sonnet upgrade retries use the same section.

• Spawn 5-8 agents at a time (avoid concurrency limits)
• Wait for all agents in the current batch to complete before spawning the next batch
• Update

  _progress.md

  to record processed chapters after each batch is completed

• Each agent returns extraction results in markdown format
• The main thread writes the agent output to

  Chapters/Chapter{N}_Summary.md

• Collect the character appearance tables from all agents for Stage 3 merging

1. Execution Failure (agent crash / timeout / empty output) → retry once with the same model (haiku)
2. Quality Failure (after saving output, run the 12 self-check items in chapter-extractor.md "Quality Check", any item fails — typical: plot points <10, P line lacks plain description, summary written as item list or full paragraph connected with "because...so...", type/tone/theme tag exceeds enumeration, missing full colon in

   基调：

   , character name is nickname/generic title) → upgrade to sonnet and retry once

• Number of plot points

  N = grep -cE '^P[0-9]+ '

  ;

  grep -c '基调：'

  must == N (less than N = some plot points miss

  基调：

  or full colon → downstream Stage 6 writing style sampling uses grep for full colon

  基调：

  , which will silently miss chapters)
• Plain description section has content:

  grep -cE '^P[0-9]+ [^|]+\|[^|]*[^|[:space:]][^|]*\|[^|]*涉及'

  must == N (there must be two

  |

  before the

  涉及

  section, i.e., the type section and plain description section each occupy one segment, and the plain description section cannot only have whitespace; less than N = some plot points lack plain description, or field order/separator is incorrect. Plain description is the main evidence of plot points, and it undertakes fact review after being selected as a quote)
• Deduplicated results of

  grep -hoE '基调：[^ |]+'

  ⊆ {紧张, 轻松, 悲伤, 热血, 爽, 甜, 温馨, 恐怖, 压抑, 其他}
• Deduplicated results of

  grep -hoE '主题标签[：]?[^ |]+'

  (after removing

  主题标签

  /colon prefix) ⊆ {爱情, 亲情, 友情, 权力, 金钱, 成长, 复仇, 悬念, 搞笑, 热血, 日常, 其他} (failure if

  主题标签：

  with colon or value is a tone term)

These 4 items are the only hard checks, no more. Format drift is mainly prevented in advance by format constraints in the spawn prompt and agent template, not by adding checks afterwards: variants like curly brace residue, tag line position, empty field placeholder only affect readability, and there are no downstream consumers (Stage 6 writing style only greps

基调：

). Adding checks for them will only trigger re-runs of usable chapters. Therefore, the existing

Chapters/*_Summary.md

files saved will not be deemed "unqualified" due to this format description, no need to regenerate; old writing styles like

类型{行动}

,

物品—

in old summaries can still be used, and the reading behavior of Stage 3-6 remains unchanged.

Agent(
  subagent_type: "chapter-extractor",
  model: "sonnet",            # explicitly override haiku in frontmatter
  prompt: "章节编号：第{N}章\n... (same as first prompt, including the opening "Material Declaration" prefix, can append: 'Last verification failure reason: {self-check failure item}')"
)

• haiku passes first time → write to

  Chapters/Chapter{N}_Summary.md

  , mark

  success

  in

  _progress.md

• haiku fails + same model retry passes → same as above, note

  retry_same_model

• quality failure + sonnet retry passes → same as above, note

  retry_sonnet

• sonnet retry still fails → mark chapter as

  ⚠️ Skipped

  , write failure reason to the "Failure Records" table in

  _progress.md

  , note in deconstruction report
• Single chapter failure does not block pipeline; decide whether to enter Stage 3 only after all agents in the batch have completed spawning

⚠️ Skipped

_progress.md

• Agent not deployed:

  chapter-extractor.md

  in the agent directory (priority

  .claude/agents/

  , then

  .opencode/agents/

  , then check

  .codex/agents/

  ) or

  .codex/agents/chapter-extractor.toml

  does not exist.

  .claude/agents/

  is usually not submitted with the repository, so re-run

  /story-setup

  to complete the current adapter deployment, do not read template sources across Skills.
• Environment does not support spawning sub-agents: This skill is currently running in a sub-agent context and cannot spawn another layer of agents.

Chapters/*_Summary.md

StoryDeconstructionLibrary/{NovelTitle}/_ChapterSummaryCollection.md

ls Chapters/*_Summary.md | sed -E 's/.*Chapter([0-9]+)_Summary.md/\1 &/' | sort -n | cut -d' ' -f2- | while read -r f; do cat "$f"; echo; done > _ChapterSummaryCollection.md

_ChapterSummaryCollection.md

• grep -cE '^P[0-9]+ ' _ChapterSummaryCollection.md

  == sum of

  ^P

  lines in each summary

• grep -cE '^\*\*Summary\*\*' _ChapterSummaryCollection.md

  == number of summary files (each chapter has one

  **Summary**

  line, present in both chapter-extractor parallel output and serial summary templates; do not use

  ## Chapter N

  header — serial summary template does not have chapter headers, which will lead to misjudgment)

_ChapterSummaryCollection.md

glob Chapters/*_Summary.md

_ChapterSummaryCollection.md

_ChapterSummaryCollection.md

Chapters/*_Summary.md

_ChapterSummaryCollection.md

StoryDeconstructionLibrary/

• Respond in the user's language; use the same language as the user
• Follow Chinese Copywriting Guidelines when replying in Chinese