webnovel-plan

Outline Planning

Main agent responsibilities: incrementally refine the volume outline/timeline/chapter outline based on the master outline, write new settings back into the setting collection, and refresh the Story System writing contract. Do not redo the global story, and do not rewrite the entire master outline or setting collection.

Execution Principles

Only perform incremental completion; do not rewrite the entire master outline or setting collection.
Lock the volume-level pacing first, then split chapters in batches.
The timeline is a hard constraint; all chapter outlines must include a time field.
If a conflict is found between the master outline and the settings, block first, then wait for the user's ruling.
Priority chain: explicit user requirements > master outline core conflict and volume-end climax > timeline hard constraints > skill default process > reference suggestions.

Blocking Conditions

The project root is invalid or the master outline is missing.
The master outline is missing volume name / chapter range / core conflict / volume-end climax → block and request the user to complete it.
Step 2 / Step 8 finds a setting conflict → mark BLOCKER, and wait for the user's ruling.
During batch chapter splitting, if time jumps backward without being marked as a flashback → block the current batch.
Step 9 validation fails → only redo the failed batch; do not overwrite the entire volume.

Environment Preparation

export WORKSPACE_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
export SKILL_ROOT="${CLAUDE_PLUGIN_ROOT}/skills/webnovel-plan"
export SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
export PROJECT_ROOT="$(python "${SCRIPTS_DIR}/webnovel.py" --project-root "${WORKSPACE_ROOT}" where)"

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" placeholder-scan --format text

Run at both the start and end of planning placeholder-scan; if placeholders are found during the plan stage, warn first and complete the relevant files; before entering chapter writing, the current chapter-related entities must not retain [待...] / 暂名 / {占位}。

Reading Strategy (triggered by stage; do not pre-read all references)

Each reference is read only when triggered by the corresponding Step, and section-based reading is preferred: first use Grep to match ^#{2,4} to locate the title anchor line number, then use Read 's offset/limit to retrieve the target section.

Trigger	Reading Method	File
Step 4	Full text	`${SKILL_ROOT}/../../templates/output/大纲-卷节拍表.md`
Step 5	Full text	`${SKILL_ROOT}/../../templates/output/大纲-卷时间线.md`
Step 6 always	Section	`${SKILL_ROOT}/../../references/genre-profiles.md`(only the current genre's `### 2.x` section)
Step 6 always	Full text	`${SKILL_ROOT}/../../references/shared/strand-weave-pattern.md`
Chapter outline splitting always	Section	`${SKILL_ROOT}/../../references/outlining/plot-signal-vs-spoiler.md`
Step 6 needs excitement points	Section	`${SKILL_ROOT}/../../references/shared/cool-points-guide.md`
Step 6/7 needs conflict	Section	`${SKILL_ROOT}/references/outlining/conflict-design.md`
Step 6/7 specific pacing	Section	`${SKILL_ROOT}/references/outlining/genre-volume-pacing.md`
Step 7 read-through power analysis	Section	`${SKILL_ROOT}/../../references/reading-power-taxonomy.md`
Step 7 chapter outline refinement + node specifications	Section	`${SKILL_ROOT}/references/outlining/chapter-planning.md`

CSV creation references use retrieval-based reading, not cat the entire table:

python -X utf8 "${SCRIPTS_DIR}/reference_search.py" --skill plan --table 爽点与节奏 --query "{卷级核心冲突}" --genre "${GENRE}"
python -X utf8 "${SCRIPTS_DIR}/reference_search.py" --skill plan --table 桥段套路 --query "{卷级核心冲突}" --genre "${GENRE}"
python -X utf8 "${SCRIPTS_DIR}/reference_search.py" --skill plan --table 命名规则 --query "角色命名" --genre "${GENRE}"

Execution Flow

Step 1: Load project data and confirm prerequisites

# 项目配置/投影状态（兼容读取，不作为写后事实真源）
cat "$PROJECT_ROOT/.webnovel/state.json"

# 总纲（全局蓝图）；确认卷名/章节范围/核心冲突/卷末高潮，不足则阻断
cat "$PROJECT_ROOT/大纲/总纲.md"

# 题材（来自 init 配置快照，后续 CSV 检索和裁决匹配依赖此值）；写后主链真源仍是 .story-system/
GENRE="$(python -X utf8 -c "import json; s=json.load(open('${PROJECT_ROOT}/.webnovel/state.json',encoding='utf-8')); pi=s.get('project_info',{}); print(pi.get('genre') or s.get('project',{}).get('genre',''))")"

Read the setting collection as needed:设定集/世界观.md、设定集/力量体系.md、设定集/主角卡.md、设定集/反派设计.md、.webnovel/idea_bank.json。

Cross-volume state reading(when there are already completed volumes, i.e., when there are files under .webnovel/summaries/ , this must be executed):

# 最近 5 章摘要
for ch in $(seq $((START_CH - 5)) $((START_CH - 1))); do
  cat "$PROJECT_ROOT/.webnovel/summaries/ch$(printf '%04d' $ch).md" 2>/dev/null
done

# 核心角色当前状态 / 核心关系当前状态 / 活跃伏笔（跨卷未回收）
python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" knowledge query-entity-state --entity "{protagonist_id}" --at-chapter {上一卷最后章}
python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" knowledge query-relationships --entity "{protagonist_id}" --at-chapter {上一卷最后章}
python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" memory-contract get-open-loops

Step 2: Complete the setting baseline

Move the setting collection from a skeleton into a "plannable, writable" state. Complete incrementally; do not clear or rewrite the entire file; if conflicts are found, list them first and block.

设定集/世界观.md: World boundaries, social structure, and uses of key locations.
设定集/力量体系.md: Realm chain, limits, costs, and cooldowns.
设定集/主角卡.md: Desires, flaws, initial resources, and limits.
设定集/反派设计.md: Minor/medium/major villain tiers and mirror relationships.

Step 3: Select the target volume and confirm the scope

Confirm the volume name, chapter range, core conflict, and whether there are any special requirements (POV, emotional line, genre shift).

Step 4: Generate the volume beat sheet

Load template ${SKILL_ROOT}/../../templates/output/大纲-卷节拍表.md。

Hard requirements: The midpoint reversal must be filled in; if there truly is none, write "None (reason: ...)"; the crisis chain must escalate at least 3 times; the new hook at the end of the volume must be able to land on the unresolved question at the end of the final chapter.

Output file:大纲/第{volume_id}卷-节拍表.md

Step 5: Generate the volume timeline table

Load template ${SKILL_ROOT}/../../templates/output/大纲-卷时间线.md。

Hard requirements: The time system and the time span of this volume must be clearly specified; if there are countdown events, list them and mark them as D-N.

Output file:大纲/第{volume_id}卷-时间线.md

Step 6: Generate the volume outline skeleton

Required reading ${SKILL_ROOT}/../../references/genre-profiles.md and ${SKILL_ROOT}/../../references/shared/strand-weave-pattern.md; read the payoff / conflict / pacing reference as needed (see the reading strategy table).

The volume outline must clearly specify: volume summary, key characters and villain tiers, Strand distribution, payoff density planning, foreshadowing planning, and constraint trigger planning.

Cross-volume consistency check (must be performed for non-first volumes):

Foreshadowing not yet recovered from the previous volume must appear in the new volume's foreshadowing plan (either continue advancing it or mark it for recovery).
Changes in character relationships must carry over; it cannot be treated as if the previous volume never happened.
The protagonist's abilities / realm must carry over, neither regressing nor skipping levels (unless there is a plot explanation).

Step 7: Generate chapter outlines in batches

Batch rules: default 10章/批; for complex genres or multiple parallel lines, reduce to 8章/批; for simple progression stories, relax to 12章/批; it is not recommended to exceed 12章。

Read as needed ${SKILL_ROOT}/../../references/reading-power-taxonomy.md and ${SKILL_ROOT}/references/outlining/chapter-planning.md。

Each chapter must include: goal, resistance, cost, time anchor, in-chapter time span, time difference from the previous chapter, countdown status, payoff, Strand, villain tier, POV/protagonist, key entities, changes in this chapter, unresolved question at the end of the chapter, hook, and structured nodes CBN、CPNs、CEN、必须覆盖节点、本章禁区。

Structured nodes

The node format is uniformly 主体 | 动作/变化 | 对象/结果(a writing execution skeleton; strict SVO grammar is not required). For the complete format description, field details, and examples, see ${SKILL_ROOT}/references/outlining/chapter-planning.md in the "Structured Node Specification"; read it by section as needed, and do not inline it in this file.

Core constraints:

Each chapter has exactly 1 CBN、2-4 个 CPN, exactly 1 CEN；CPNs arranged in chronological order.
Adjacent chapters CEN -> 下一章 CBN must logically connect (except for the first and last chapters).
必须覆盖节点At most 4, recommended CBN + CEN + 1~2 个核心 CPN; optional nodes are only suggestions and are not the main basis for fail.
本章禁区No more than 5 items; write only the hard forbidden zones that absolutely must not occur in this chapter, and do not write style-related suggestions.
Backward compatibility: When old project chapter outlines lack the above fields, the downstream process executes normally and only skips the structured check.

Output file:大纲/第{volume_id}卷-详细大纲.md

Step 8: Write the newly added settings back into the existing setting collection

Input: volume beat sheet, volume timeline table, detailed volume outline, existing setting collection files.

Write-back rules: only incrementally supplement the relevant paragraphs; write new characters into character cards or character groups; write new factions / locations / rules into the worldview or power system; write new villain tiers into the villain design.

Hard rule: If a conflict with the master outline or existing settings is found, mark BLOCKER and stop subsequent updates.

Step 9: Verify, save, and update status

Must pass: the beat sheet / timeline table / detailed outline all exist and are non-empty; every chapter has complete time fields; the timeline is monotonically increasing; the countdown advances correctly; new settings have been written back;BLOCKER=0; when there are nodes, adjacent chapters CEN -> CBN have no obvious logical conflict and each chapter必须覆盖节点does not exceed 4.

After all validations pass, generate the explicit structured write-back file 大纲/第{volume_id}卷-总纲写回.json(only write the foreshadowing / open loops explicitly listed in the plan; inferring from the free text of the volume outline is prohibited):

{
  "next_volume_anchor": {
    "volume": 2,
    "volume_name": "下一卷卷名",
    "core_conflict": "下一卷核心冲突",
    "volume_end_climax": "下一卷卷末高潮"
  },
  "foreshadow_writeback": [
    {"content": "本卷规划明确新增的伏笔", "buried_chapter": "第10章", "payoff_chapter": "", "level": "卷级"}
  ],
  "open_loop_writeback": [
    {"content": "本卷结束后仍持续开放的问题", "buried_chapter": "", "payoff_chapter": "", "level": "持续开放环"}
  ]
}

Perform the minimal master outline write-back (only update 大纲/总纲.md 's V+1 volume name / core conflict / volume-end climax and foreshadowing table; do not generate the next volume's detailed outline / beat sheet / timeline / chapter outline):

python "${SCRIPTS_DIR}/webnovel.py" --project-root "$PROJECT_ROOT" master-outline-sync \
  --volume {volume_id} \
  --writeback-file "大纲/第{volume_id}卷-总纲写回.json" \
  --format text

Update status:

python "${SCRIPTS_DIR}/webnovel.py" --project-root "$PROJECT_ROOT" update-state -- \
  --volume-planned {volume_id} \
  --chapters-range "{start}-{end}"

Step 10: Refresh the Story System writing contract (must be executed when this planning has landed on specific chapters)

genre is read from the state.json initialization configuration snapshot; the pre-writing main-chain source of truth is the .story-system/ contract tree. The real CHAPTER_GOALmust first be parsed from the detailed outline; passing {章纲目标} / 第N章章纲目标 and similar placeholder text is prohibited.

GENRE="$(python -X utf8 -c "import json; s=json.load(open('${PROJECT_ROOT}/.webnovel/state.json',encoding='utf-8')); pi=s.get('project_info',{}); print(pi.get('genre') or s.get('project',{}).get('genre',''))")"

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" story-system "${CHAPTER_GOAL}" \
  --genre "${GENRE}" --chapter {chapter_num} --persist --emit-runtime-contracts --format both

After generation, .story-system/MASTER_SETTING.json、.story-system/volumes/、.story-system/chapters/、.story-system/reviews/ must be treated as the main-chain input for subsequent writing. Before entering chapter writing, the current chapter's related entities' [待...] / 暂名 / {占位}。

Hard failure conditions

The beat sheet / timeline table / detailed outline does not exist or is empty.
The mid-section reversal is missing and no reason is given.
Any chapter lacks a time field; the time jumps backward without being marked as a flashback; countdown arithmetic conflicts.
Obvious conflict with the master outline's core conflict or the volume-end climax.
There exists BLOCKER that is undecided.

Recovery rules

Only redo the failed batch; do not overwrite the entire volume's files.
When the last batch is invalid, only delete and rewrite that batch.
Only update the status after all validations pass.

Author-friendly process prompts and recovery contract

Before planning begins, first explain that this session will go through: check the master outline and settings -> generate the beat sheet -> generate the timeline -> split chapter outlines -> write back new settings -> refresh the writing contract. Process prompts should use the author's language and must not directly output raw JSON, tracebacks, or long command logs; technical details are written to .webnovel/logs/run_last.log：

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" run-log \
  --event plan-progress \
  --payload-json "{\"stage\": \"plan\", \"volume\": {volume_id}}" \
  --format text

Each process prompt must not exceed two lines and should only state the current action and its impact, for example "Splitting this volume's chapter outlines: will clearly write each chapter's goal, time anchor, and forbidden zones." Minimal-interruption confirmation strategy: by default keep moving forward; only ask when there is a master outline / settings conflict, a timeline backward jump, a volume-end hook tradeoff, or a need to overwrite existing planning.

When user adjudication is needed, use limited options and explain the impact; for example, follow the master outline / modify settings / pause planning. When stuck, must explain the blocker, what has been completed, and recovery suggestions, for example "The beat sheet and timeline have been retained; splitting chapters 21-30 failed; rerunning /webnovel-plan {volume_id} will only redo the failed batch."

Only for unrecoverable failures should the final report prompt .webnovel/logs/run_last.log; at other times only keep logs and do not disturb the author. The wrap-up must call the author report helper:

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" user-report \
  --stage plan \
  --volume {volume_id} \
  --format text

Author-friendly final report contract

The final reply must be author-facing and must not output raw JSON, tracebacks, or long command logs. Use a fixed three-part structure and begin with a one-sentence overall status:

总状态：已完成 / 部分完成 / 需要你处理 / 未完成。

一、产生的文件与完成情况
- ...

二、过程中遇到的问题与异常耗时
- 已自动处理：...
- 建议确认：...
- 必须处理：...

三、下一步建议
- ...

Must report:

大纲/第{volume_id}卷-节拍表.md。
大纲/第{volume_id}卷-时间线.md。
大纲/第{volume_id}卷-详细大纲.md。
Which setting collection files the new settings were written back to.
大纲/第{volume_id}卷-总纲写回.json。
master-outline-sync、update-state, and whether the Story System contract refresh is complete.
Whether placeholders, the timeline, and node continuity pass.

Exception classification:

Automatically handled: only redo failed batches, fill in non-blocking placeholders, and rerun contract refresh.
Recommended confirmation: newly added character names, faction names, and end-of-volume hooks need the author to take a look.
Must handle: master outline / setting conflicts, timeline jumps backward,BLOCKER undecided, and placeholder remnants related to the current chapter.

Next-step suggestions must use task-oriented language + copyable commands, for example:

- 接下来可以写第一章：
  /webnovel-write 1

Do not write token statistics; if troubleshooting is needed, only provide the log path or suggest running /webnovel-doctor。