story-setup: Infrastructure Deployment for Web Novel Writing Toolset

Phase 1: Detect Project Status

SKILL.md

references/

agent-references

templates

opencode

codex

zcode

openclaw

reasonix

generic

scripts/merge-claude-settings.py

scripts/merge-codex-hooks.py

scripts/copy-path-safety.py

npx skills add zenstory-ai/oh-story-claudecode -y -g

The criterion is "whether

SKILL.md

exists": Only check the

references/

at the same level as the executing

SKILL.md

. The project's

.claude/skills/story-setup/

,

.codex/skills/story-setup/

and OpenCode's

skills/story-setup/

only have

references/agent-references/

and do not contain

SKILL.md

, so they will not be the execution directory, and do not use them for verification. The project copies of ZCode / OpenClaw / Reasonix / generic are full skill copies with their own

SKILL.md

, and the 8 subdirectories are complete, so verify as usual.

1. Check if the current directory has been deployed (

   .story-deployed

   exists)

   • agents_version

     is missing, non-integer or less than

     25

     → Mark as pending update, continue with current deployment

   • agents_version: 25

     → Use AskUserQuestion to confirm whether to redeploy; clearly state in the prompt that redeployment only refreshes project files using the current local skill package, to get a new version of the skill itself, you need to update oh-story-claudecode first (via

     npx skills add

     or marketplace), then run /story-setup again

   • agents_version

     is greater than

     25

     → The current story-setup is older than the project deployment; stop to avoid downgrade overwriting, prompt to update oh-story-claudecode first, do not write any deployment files
   • At the same time, read the

     target_cli

     field. For deployed projects, follow the value in the sentinel: When non-empty (multi-end combination separated by commas is retained as-is), skip steps 5-12 below for environment detection and selection, and redeploy directly according to these ends. Only when the field is missing or empty, fall back to detection. When the user explicitly requests to add or remove target ends, use AskUserQuestion to modify based on the existing value, and write the modified value back to the sentinel.
2. Check if there is a book title directory (a directory containing a

   追踪/

   subdirectory, or a user-defined structure)
   • Exists → Identify as a long-form project, display current project information
   • Does not exist → Identify as a new project or short-form project
3. Check if

   .claude/settings.local.json

   exists
   • Exists → Read existing configuration, merge later
   • Does not exist → Create a new file later
4. Check if

   .active-book

   file exists
   • Exists → Display current active book title
   • Does not exist → Skip
5. Check if

   opencode.json

   or

   .opencode/

   exists
   • Exists → Identify as an opencode project,

     target_cli = opencode

   • Does not exist → Skip
6. Check

   .codex/

   ,

   .codex/config.toml

   ,

   .codex/agents/

   ,

   .codex/hooks.json

   , Codex section in

   AGENTS.md

   • Exists → Identify as a Codex project,

     target_cli = codex

   • Does not exist → Skip
7. Check

   .zcode/

   ,

   .zcode/config.json

   ,

   zcode.json

   ,

   .zcode/skills/

   ,

   .zcode/commands/

   , ZCode section in

   AGENTS.md

   • Exists → Identify as a ZCode project,

     target_cli = zcode

   • Does not exist → Skip
8. Check

   openclaw.json

   ,

   .openclaw/

   , or OpenClaw section in

   AGENTS.md

   (title line contains "网文写作工具集（OpenClaw）")
   • Exists → Identify as an OpenClaw project,

     target_cli = openclaw

   • Does not exist → Skip
9. Check

   .reasonix/

   ,

   reasonix-plugin.json

   ,

   REASONIX.md

   , or Reasonix section in

   AGENTS.md

   (title line contains "网文写作工具集（Reasonix）")
   • Exists → Identify as a Reasonix project,

     target_cli = reasonix

   • Does not exist → Skip
10. Check the general section in

    AGENTS.md

    (title line contains "网文写作工具集（通用 Agent / Web AI）")
    • Exists → Identify as a general Web AI project,

      target_cli = generic

    • Does not exist → Skip

    Steps 8-10 only recognize mutually exclusive markers for each end.

    metadata.openclaw

    in

    skills/*/SKILL.md

    is not used as an OpenClaw signal: All 13 skills have this field, and the

    skills/

    deployed by the three skills-only paths of OpenClaw / Reasonix / generic look the same, so using it to judge will misidentify the latter two as OpenClaw.

    .agents/skills/

    is also shared by Codex and Reasonix, so it is not used alone. The real distinguishing point for the three ends is the title line of their respective

    AGENTS.md

    templates.

11. If

    .claude/

    or

    CLAUDE.md

    , OpenCode, Codex, ZCode, OpenClaw, Reasonix, and generic markers exist at the same time → Use AskUserQuestion to let the user select the target environment (options: Claude Code / OpenCode / Codex / ZCode / OpenClaw / Reasonix / General Web AI or other Agent / Any combination)
12. If none of the seven types of markers exist (brand new project) → Use AskUserQuestion to let the user select the target environment
    • User selects opencode →

      target_cli = opencode

      , create

      opencode.json

      and

      .opencode/

      during deployment
    • User selects claude-code → Process according to existing logic
    • User selects codex →

      target_cli = codex

      , create

      .codex/

      during deployment
    • User selects zcode →

      target_cli = zcode

      , merge root

      AGENTS.md

      during deployment, do not create project custom agents
    • User selects openclaw →

      target_cli = openclaw

      , copy OpenClaw-compatible skills to project

      skills/

      during deployment
    • User selects reasonix →

      target_cli = reasonix

      , copy skills to project

      skills/

      and write Reasonix version

      AGENTS.md

      during deployment, do not create project custom agents/hooks
    • User selects General Web AI / other Agent →

      target_cli = generic

      , deploy general

      AGENTS.md

      and project local

      skills/

      ; do not write platform-specific hooks/agents
    • User selects multiple ends →

      target_cli = subset of claude-code,opencode,codex,zcode,openclaw,reasonix,generic

      (only includes the ends selected by the user)

Phase 2: Deploy Infrastructure

create only if absent

Source path

Target path

scripts/copy-path-safety.py

SKILL.md

Path.resolve

realpath

samefile

status: same

copy_allowed: true

source_missing

unsafe_target_within_source

filesystem_identity_error

.agents/skills → ../skills

agent-references/

{.claude,.codex,.zcode}/skills/story-setup/references/agent-references/

skills/story-setup/references/agent-references/

skills/story-setup/skills/

Step 1: Deployment Checklist (Mechanically Verifiable)

skills/story-setup/references/templates/CLAUDE.md.tmpl

CLAUDE.md

skills/story-setup/references/templates/hooks/

.claude/hooks/

session-*.sh

detect-story-gaps.sh

validate-story-commit.sh

guard-outline-before-prose.sh

check-prose-after-write.sh

story_hook_core.js

story_hook_cli.js

lib/common.sh

lib/sentinel.sh

story_hook_core.js

skills/story-setup/references/templates/rules/*.md

.claude/rules/*.md

paths

skills/story-setup/references/templates/agents/*.md

.claude/agents/*.md

skills/story-setup/references/agent-references/*.md

.claude/skills/story-setup/references/agent-references/*.md

story-setup/references/agent-references/*.md

skills/story-setup/references/templates/settings-hooks.json

.claude/settings.local.json

skills/story-setup/scripts/merge-claude-settings.py

skills/story-setup/scripts/copy-path-safety.py

copy_allowed: true

.story-deployed

agents_version

setup_skill_version

target_cli

resolver_strategy

references_dir

skills/story-setup/references/opencode/AGENTS.md.tmpl

AGENTS.md

skills/story-setup/references/opencode/agents/

.opencode/agents/

model:

skills/story-setup/references/opencode/plugin.ts

.opencode/plugins/story-hooks.ts

skills/story-setup/references/opencode/story_hook_core.js

.opencode/plugins/lib/story_hook_core.js

skills/story-setup/references/opencode/commands/

.opencode/commands/

skills/story-setup/references/opencode/opencode.json.patch

opencode.json

skills/story-setup/references/agent-references/

skills/story-setup/references/agent-references/

skills/story-setup/references/opencode/pre-commit.sh

.git/hooks/pre-commit

skills/story-setup/references/codex/AGENTS.md.tmpl

AGENTS.md

skills/story-setup/references/codex/agents/

.codex/agents/

name

description

developer_instructions

skills/story-setup/references/codex/hooks/hooks.json

.codex/hooks.json

skills/story-setup/references/codex/hooks/{story_codex_hook.py,run-story-hook.sh,run-story-hook.cmd}

.codex/hooks/

skills/story-setup/scripts/merge-codex-hooks.py

skills/story-setup/references/agent-references/

.codex/skills/story-setup/references/agent-references/

skills/story-setup/references/zcode/AGENTS.md.tmpl

AGENTS.md

$story-*

skills/{browser-cdp,story*}/

.zcode/skills/{browser-cdp,story*}/

SKILL.md

skills/story-setup/references/zcode/commands/

.zcode/commands/

skills/story-setup/references/zcode/hooks/story_zcode_hook.js

.zcode/hooks/story_zcode_hook.js

skills/story-setup/references/zcode/hooks/story_hook_core.js

.zcode/hooks/story_hook_core.js

skills/story-setup/references/zcode/config.json.patch

.zcode/config.json

hooks.enabled=true

.zcode/config.json

skills/story-setup/references/openclaw/AGENTS.md.tmpl

AGENTS.md

skills/story-setup/references/generic/AGENTS.md.tmpl

AGENTS.md

skills/story-setup/references/reasonix/AGENTS.md.tmpl

AGENTS.md

skills/{browser-cdp,story*}/

skills/{browser-cdp,story*}/

SKILL.md

skills/story-setup/references/agent-references/

opencode.json Merge Algorithm

opencode.json.patch

1. Read the existing

   opencode.json

   (if exists), parse JSON
2. Merge the

   plugin

   array: Add

   ./.opencode/plugins/story-hooks.ts

   to the array and deduplicate
3. Retain other existing configuration fields of the user (such as

   permission

   ,

   model

   ,

   provider

   ), do not overwrite
4. Write the merged

   opencode.json

Step 2: Deploy CLAUDE.md

• Read

  skills/story-setup/references/templates/CLAUDE.md.tmpl

• Replace placeholders (see "Template Placeholders" section below)
• Write to project root directory

  CLAUDE.md

  (if it already exists, process according to "CLAUDE.md Merge Strategy")

Step 3: Deploy Hooks

• Recursively copy the complete directory tree: Copy

  skills/story-setup/references/templates/hooks/

  to the user's project

  .claude/hooks/

• Must retain the subdirectory

  lib/

  , where:

  • lib/common.sh

    provides

    project_root

    ,

    discover_active_book

    ,

    discover_all_books

  • lib/sentinel.sh

    provides

    .story-deployed

    field reading
• Only need to set execution permissions (

  chmod +x

  ) for

  .claude/hooks/*.sh

  ;

  lib/*.sh

  is sourced by hooks, no need for executable bits

Step 4: Deploy Rules

• Read all

  .md

  files under

  skills/story-setup/references/templates/rules/

• Copy to the

  .claude/rules/

  directory of the user's project

Step 5: Deploy Agents

• Read all

  .md

  files under

  skills/story-setup/references/templates/agents/

• Copy to the

  .claude/agents/

  directory of the user's project
• Agent files are managed by story-setup and can be safely overwritten; redeploy according to the version detection results in

  UPGRADING.md

  during version upgrade
• When

  target_cli

  contains opencode, execute Step 1 of "Configure OpenCode Agent Model" to cache existing

  model:

  before overwriting

  .opencode/agents/

  . This step is written later in this section, but must be run first — if you follow the order and overwrite first then cache, the user's configured model will be lost.
• Must start a new session after deployment: Agents are only registered when the session starts; the reason and the report copy that must be output are in "Output Installation Report" in "Verify Installation".

Agent Compatibility Handling

• Agent frontmatter is mainly based on Claude Code; OpenCode's

  .opencode/agents/*.md

  and Codex's

  .codex/agents/*.toml

  are directly copied from pre-generated products under

  references/opencode/agents/

  and

  references/codex/agents/

  , which are the only sources for deployment. The pre-generated products are maintained by

  scripts/sync-opencode.py

  and

  scripts/generate-codex-agents.py

  at the root of the oh-story-claudecode repository; these two scripts are repository maintenance tools, not distributed with story-setup, and do not need to be called during deployment.
• ZCode 3.3.4 does not deploy project agents: Its custom sub-agents only support user-level

  ~/.zcode/agents/

  , and the

  agents

  in the plugin manifest is not currently executed. Do not create

  .zcode/agents/

  or modify the user's home; related Skills must directly use solo/direct and report fallback.
• OpenClaw Phase 1 does not deploy agents: OpenClaw only deploys skills, and skills related to agent collaboration must be downgraded to solo/direct according to existing fallback rules, do not directly copy Claude/OpenCode agent frontmatter as OpenClaw agents.
• After deployment to the project, the reference materials referenced in the agent must use the intra-skill copy path

  story-setup/references/agent-references/*.md

  ; do not reference references from other skills across skills. Each adapter only uses the current specification prefix: Claude Code uses

  .claude/skills/

  , OpenCode / OpenClaw / Reasonix / generic use

  skills/

  , Codex uses

  .codex/skills/

  , ZCode uses

  .zcode/skills/

  ; does not traverse historical alternative paths at runtime.

Deploy Agent References

• Copy all

  .md

  files under

  skills/story-setup/references/agent-references/

  to

  .claude/skills/story-setup/references/agent-references/

  in the project
• Verification: For every occurrence of

  story-setup/references/agent-references/<file>.md

  in agents or references,

  <file>.md

  must exist in both the source package and the target package

Deploy Codex Agents (when target_cli contains codex)

• Read all

  .toml

  files under

  skills/story-setup/references/codex/agents/

  , copy to the user's project

  .codex/agents/

• Agent files are managed by story-setup and can be safely overwritten; the TOML in

  references/codex/agents/

  is deterministically generated from Claude agent templates by

  scripts/generate-codex-agents.py

  at the root of the repository and committed to the repository, deployment only does copying
• Verify that each TOML can be parsed and contains Codex required fields:

  name

  ,

  description

  ,

  developer_instructions

• Read-only responsibility agents (

  chapter-extractor

  ,

  consistency-checker

  ,

  story-explorer

  ) must retain

  sandbox_mode = "read-only"

• Must trust + start a new Codex session after deployment (report copy and fallback rules are in "Verify Codex Deployment"); if

  unknown agent_type

  is returned at runtime, the caller must downgrade to solo/direct and report fallback.
• Synchronously copy

  skills/story-setup/references/agent-references/

  to

  .codex/skills/story-setup/references/agent-references/

  as the main path for intra-project reference materials of Codex agents

Configure OpenCode Agent Model

Only execute when

target_cli

contains

opencode

. When OpenCode sub-agents do not specify a model, they inherit the main model, resulting in low-cost Agents also consuming main model quotas. This step automatically detects the user's model and writes the

model:

field.

Step 1: Retain Existing Model Configuration (must be executed before replacing

.opencode/agents/

)

replace

model:

.opencode/agents/*.md

model:

Step 2: Get Model List

opencode models --verbose

opencode models

provider/model

• Success → Enter "Model Classification"
• Timeout → Retry once (cache may not be preheated); if still timeout, fill in the existing

  model:

  with the cache from "Retain Existing Model Configuration", skip automatic configuration, and output manual configuration guide in the installation report
• Failure (command does not exist, output is empty, etc.) → Same as above: Fill in the cache from "Retain Existing Model Configuration", skip automatic configuration, output manual configuration guide

Step 3: Model Classification

--verbose

nemotron-3-ultra-free

ultra

--verbose

/

-

.

_

minimax-m3

[minimax, m3]

mini

max

claude-haiku-4.5

[claude, haiku, 4, 5]

haiku

haiku

flash

mini

nano

lite

sonnet

plus

opus

pro

ultra

max

• A model may match keywords of multiple grades, take the highest grade
• Models that do not match any keywords in keyword fallback are still included in candidate additional suggestions (all are included in cost classification), and listed in the installation report, prompting "Can be used via custom input"
• Within the same grade, if multiple model providers are included, prioritize models from well-known providers (anthropic, openai, google, deepseek)

Step 4: Step-by-Step Interactive Selection

Question: "Select model for low-cost Agents (chapter-extractor, consistency-checker, story-explorer):"
Options:
  - provider/model-id
  - provider/model-id
  - Custom input (manually enter full model ID, ID spelling errors will only be exposed at runtime)
  - Skip, use main model (cost may be higher)

Question: "Select model for writing quality-critical Agents (narrative-writer, character-designer, story-researcher):"
Options:
  - provider/model-id
  - provider/model-id
  - Custom input (do not use low-end models, which will affect text quality; ID spelling errors will only be exposed at runtime)
  - Skip, use main model (main model quality is usually sufficient)

Question: "Select model for command Agent (story-architect):"
Options:
  - provider/model-id
  - provider/model-id
  - Custom input (manually enter full model ID, ID spelling errors will only be exposed at runtime)
  - Skip, use main model (cost may be higher)

• Display up to 5 candidates, truncate if more than 5 and prompt "For more models, use custom input". Pop up AskUserQuestion at each level regardless of whether the number of candidates is 0, options must include: candidate models (if any),

  Custom input

  ,

  Retain existing model

  (the model of this agent cached in "Retain Existing Model Configuration", do not display this item if none),

  Skip, use main model

  . When candidates are 0, still pop up the window, and give a corresponding warning in the question description + list unclassified/ungraded models for reference — do not silently skip interaction (otherwise the user cannot access custom input).

• Custom input

  : User enters full

  provider/model-id

  ; verify it is a single line, no control characters, matches

  ^[A-Za-z0-9._-]+/[A-Za-z0-9._:+-]+$

  before writing, if not, prompt to re-enter or choose to skip.

• Retain existing model

  : Write back the model of this agent cached in "Retain Existing Model Configuration" (preserve the user's previous configuration during redeployment), not counted as "skip".

• Skip, use main model

  : Explicitly clear — do not write the

  model:

  field for this agent, the agent inherits the main model. To retain previous configuration, select

  Retain existing model

  .
• When candidates are 0 at each level, give prompts in the question description:
  • Low-end: "No low-cost models detected, these 3 agents will use the main model, cost may be higher"
  • Mid-end: "No matching mid-end models detected. narrative-writer, character-designer, story-researcher will use the main model. This configuration is reasonable if the main model quality is sufficient; if cost reduction is needed, specify a mid-end model not lower than the main model quality via custom input, or select from the ungraded models below."
  • High-end: "No high-end models detected, story-architect will use the main model"

Step 5: Write model Field

.opencode/agents/*.md

model:

---

permission:

---
description: ...
mode: subagent
permission:
  read: allow
  edit: deny
steps: 12
model: provider/model-id
---

• If the agent file already has a

  model:

  field (redeployment scenario), replace the value of this top-level

  model:

  , do not add duplicate keys

• Retain existing model

  : Write back the model of this agent cached in "Retain Existing Model Configuration"

• Skip, use main model

  : Do not write the

  model:

  field
• For levels that failed/timeout and did not reach this step: Fill in

  model:

  with the cache from "Retain Existing Model Configuration", avoiding overwriting the user's previous configuration due to replace

Step 6: Merge Hook Registrations to settings.local.json

1. Detect Python according to existing cross-platform rules:

   for PYBIN in python3 python py; do "$PYBIN" -c "" 2>/dev/null && break; done

   ; stop if no available interpreter, do not manually write or simplify merging.
2. Call

   "$PYBIN" "{story-setup skill directory}/scripts/merge-claude-settings.py" --existing "{project}/.claude/settings.local.json" --template "{story-setup skill directory}/references/templates/settings-hooks.json" --output "{project}/.claude/settings.local.json"

   .
3. The helper will remove all historical registrations of known story-setup hooks, then append the current template; therefore, matcher/timeout/if can be upgraded with the version, while user hooks and unknown top-level fields mixed in the old block are retained as-is. Parse JSON after writing, verify that each template command exists once, user configuration is still present, then re-run the helper to compare file bytes to confirm idempotency.

Codex hooks.json Merge Algorithm (when target_cli contains codex)

.codex/hooks.json

.codex/hooks/story_codex_hook.py

run-story-hook.sh

run-story-hook.cmd

1. Locate the current story-setup skill directory, read

   references/codex/hooks/hooks.json

   as the only current template, read the project's

   .codex/hooks.json

   (treat as empty object if it does not exist).
2. Detect available Python according to existing cross-platform rules:

   for PYBIN in python3 python py; do "$PYBIN" -c "" 2>/dev/null && break; done

   ; stop if no available interpreter, do not manually write or simplify JSON merging.
3. Call

   "$PYBIN" "{story-setup skill directory}/scripts/merge-codex-hooks.py" --existing "{project}/.codex/hooks.json" --template "{story-setup skill directory}/references/codex/hooks/hooks.json" --output "{project}/.codex/hooks.json"

   . This helper will identify three types of managed identities: old direct call

   story_codex_hook.py

   , current

   run-story-hook.sh

   and

   run-story-hook.cmd

   , first remove all known managed registrations, then append the current template.
4. Retain non-story-setup hooks, matcher blocks and unknown top-level fields already present in the user's configuration. Repeated execution must be idempotent;禁止再按原始

   command

   字符串追加去重，否则 v17 直调命令会与 v18 launcher 双重注册。
5. Parse JSON after writing to verify: The number of old direct call

   story_codex_hook.py

   commands is 0, each of the 6 current template registrations exists exactly once, user hooks and unknown top-level fields are still present. Then prompt the user: The project's

   .codex/

   layer needs to be trusted by Codex, non-managed command hooks also need to be reviewed/trusted in

   /hooks

   before running; on Windows, use

   commandWindows

   , the launcher locates the project's

   .codex/hooks/

   from the current directory upwards, consistent with the nested directory behavior of POSIX paths.

ZCode Deployment Algorithm (when target_cli contains zcode)

.zcode/agents

.zcode/rules

1. Copy the 13 directories containing

   SKILL.md

   under the current repository's

   skills/

   to

   .zcode/skills/{skill-name}/

   ; only replace these known directories, retain other Skills of the user.
2. Copy

   references/zcode/commands/*.md

   to

   .zcode/commands/

   ; only replace 13 commands with the same name, retain other Commands of the user.
3. Copy

   references/zcode/hooks/story_zcode_hook.js

   and

   references/zcode/hooks/story_hook_core.js

   to

   .zcode/hooks/

   .
4. Read

   references/zcode/config.json.patch

   and the existing

   .zcode/config.json

   (if only the root

   zcode.json

   exists, still create

   .zcode/config.json

   to carry oh-story project Hooks, do not modify the root file):
   • Retain all unknown fields, MCP, plugins, skills/commands disable overrides of the user;
   • Hooks mutual exclusion (avoid double triggering): If this project runs via the installed oh-story plugin (marketplace installation,

     hooks.json

     in

     .zcode-plugin/plugin.json

     at the repository root has globally registered SessionStart/PreToolUse/PostToolUse), then skip merging the

     hooks

     block of

     config.json.patch

     into

     .zcode/config.json

     below — the plugin manifest has already registered these hooks, merging again will cause the same event to run twice (PreToolUse intercepted twice, PostToolUse injected twice). Only merge hooks when the plugin is not installed (directly cloned / manually imported references). When uncertain, take "Whether ZCode has registered this set of hooks via this plugin" as the criterion; non-hook fields of skills/commands/hook files/AGENTS and config are deployed as usual via both paths.
   • Merge hooks (only when plugin is not installed): Set

     hooks.enabled: true

     ; retain if the user already has a larger

     timeoutMs

     , otherwise take the template value; deduplicate and append SessionStart, PreToolUse, PostToolUse in

     hooks.events

     by

     event + matcher + process command + args

     ; do not copy PreCompact, PostCompact, SessionEnd, SubagentStop, Notification which are not supported by ZCode.
5. Write the root

   AGENTS.md

   according to "AGENTS.md Merge Strategy" using

   references/zcode/AGENTS.md.tmpl

   .
6. Write

   zcode

   or multi-end combination to

   target_cli

   in

   .story-deployed

   , write

   .zcode/skills/story-setup/references/agent-references

   to

   references_dir

   .
7. The installation report must clearly state: ZCode 3.3.4 does not execute project/plugin custom agents, full/lean multi-Agent requests will be stably downgraded to solo/direct; the system requires an available

   node

   command to run project Hooks.

.zcode-plugin/plugin.json

.zcode/skills

$story-setup

.zcode/config.json

config.json.patch

.zcode/config.json

OpenClaw skills-only Deployment Algorithm (when target_cli contains openclaw)

1. Read all story skill directories containing

   SKILL.md

   under the current repository's

   skills/

   (13:

   browser-cdp

   and

   story*

   ).
2. Write to the target project's

   skills/{skill-name}/

   , only replace these story-setup managed known skill directories; retain other directories of the user under

   skills/

   .
3. Each

   SKILL.md

   must meet OpenClaw frontmatter constraints:

   name

   /

   description

   are single-line key-value pairs,

   metadata

   is a single-line JSON object and contains

   metadata.openclaw

   .
4. Copy

   skills/story-setup/references/openclaw/AGENTS.md.tmpl

   to the project's

   AGENTS.md

   , merge according to "AGENTS.md Merge Strategy".
5. Write

   openclaw

   or multi-end combination to

   target_cli

   in

   .story-deployed

   ; write

   skills/story-setup/references/agent-references

   to

   references_dir

   for OpenClaw.
6. Prompt items in the installation report are in Step 10 of Phase 3.

Reasonix skills-only Deployment Algorithm (when target_cli contains reasonix)

AGENTS.md

1. Read all story skill directories containing

   SKILL.md

   under the current repository's

   skills/

   (13:

   browser-cdp

   and

   story*

   ) to the target project's

   skills/{skill-name}/

   ; only replace these story-setup managed known skill directories, retain other directories of the user.
2. Create a relative symlink

   .agents/skills → ../skills

   in the project root (shared with Codex's skill root), so that Reasonix can discover these skills when natively scanning

   .agents/skills

   ; if it is already a symlink pointing to

   skills/

   , retain it, if it is occupied as a normal directory, do not overwrite and prompt in the installation report. Skip this step when symlink is not enabled on Windows, instead use the root

   reasonix-plugin.json

   for

   reasonix plugin install

   .
3. Copy

   skills/story-setup/references/reasonix/AGENTS.md.tmpl

   to the project's

   AGENTS.md

   , merge according to "AGENTS.md Merge Strategy".
4. Write

   reasonix

   or multi-end combination to

   target_cli

   in

   .story-deployed

   ; write

   skills/story-setup/references/agent-references

   to

   references_dir

   for Reasonix.
5. Prompt items in the installation report are in Step 12 of Phase 3.

General Web AI / Other Agent Deployment Algorithm (when target_cli contains generic)

1. Copy all story skill directories containing

   SKILL.md

   under the current repository's

   skills/

   (13:

   browser-cdp

   and

   story*

   ) to the target project's

   skills/{skill-name}/

   ; only replace these story-setup managed known skill directories, retain other directories of the user.
2. Copy

   skills/story-setup/references/generic/AGENTS.md.tmpl

   to the project's

   AGENTS.md

   , merge according to "AGENTS.md Merge Strategy".
3. Write

   generic

   or multi-end combination to

   target_cli

   in

   .story-deployed

   ; write

   skills/story-setup/references/agent-references

   to

   references_dir

   for generic.
4. Prompt items in the installation report are in Step 11 of Phase 3.

Step 7: Create Deployment Marker

• Create

  .story-deployed

  file (sentinel file)
• Write the following fields (YAML

  key: value

  format, read by

  references/templates/hooks/lib/sentinel.sh

  in hooks):

  deployed_at: <date -u +"%Y-%m-%dT%H:%M:%SZ">
  agents_version: 25
  setup_skill_version: 1.2.7
  target_cli: claude-code (or opencode, codex, zcode, openclaw, reasonix, generic, or any combination thereof)
  resolver_strategy: project-local-skill-reference
  references_dir: .claude/skills/story-setup/references/agent-references (Codex writes .codex/skills/...; ZCode writes .zcode/skills/...; OpenClaw / Reasonix / generic write skills/...; multi-end uses comma separation)

• This file is used by session-start.sh and writing skills to detect deployment status and avoid repeated prompts
• When target_cli contains claude-code, also create a one-time marker file

  .claude/.agents-pending-restart

  (empty file is sufficient). session-start.sh will confirm that agents have been registered with the new session when the next session starts, and automatically delete this marker — used to confirm "restart has taken effect" to the user. ZCode does not create this marker because it does not deploy project agents.
• If

  .story-deployed

  exists but

  agents_version

  is missing, non-integer or less than

  25

  , update hooks/agents/rules/reference bundle according to this process (specific changes see

  UPGRADING.md

  ); if greater than

  25

  , stop in Phase 1 and do not downgrade overwrite

Phase 3: Verify Installation

1. Verify hook registration:
   • Check if the hooks field in

     .claude/settings.local.json

     is correct
   • Check if the scripts under

     .claude/hooks/

     exist and have execution permissions
   • Check if

     .claude/hooks/lib/common.sh

     and

     .claude/hooks/lib/sentinel.sh

     exist
2. Verify rules path:
   • Check if the rule files under

     .claude/rules/

     exist and contain

     paths

     frontmatter
3. Verify agents:
   • Check if the 7 agent definition files under

     .claude/agents/

     exist
4. Verify agent reference bundle:
   • Check if the reference files under

     .claude/skills/story-setup/references/agent-references/

     are complete
   • Check that all

     story-setup/references/agent-references/<file>.md

     can resolve to the deployed bundle
5. Verify deployment marker:
   • Check if

     .story-deployed

     exists and contains timestamp,

     agents_version: 25

     ,

     setup_skill_version: 1.2.7

     ,

     target_cli

     ,

     resolver_strategy

     ,

     references_dir

6. Output installation report:
   • List all deployed files
   • List matters needing attention (such as existing configurations have been merged)
   • ⚠️ Restart Prompt (must be output prominently): This deployment wrote to

     .claude/agents/

     , but these custom agents are only registered as

     subagent_type

     by Claude Code when the "session starts".Please start a new Claude Code session before writing, otherwise when story-review / story-long-write etc. try to spawn

     story-architect

     ,

     narrative-writer

     etc. in the current session, they will get "subagent_type unavailable" and downgrade to solo (single perspective, losing multi-agent collaboration). To judge whether it takes effect: Run

     /story-review

     in the new session, if the report header is

     Effective Mode: full/lean

     , registration is successful; if it is

     Fallback: ... -> solo

     , it means you are still in the old session or not registered.
   • You can use

     /story-long-write

     or

     /story-short-write

     after restart
   • If "Configure OpenCode Agent Model" was executed, output Agent model configuration summary:

     Agent Model Configuration:
       story-architect          → <high-end model> (provider/model-id)
       narrative-writer         → <mid-end model> (provider/model-id)
       character-designer       → <mid-end model> (provider/model-id)
       story-researcher         → <mid-end model> (provider/model-id)
       chapter-extractor        → <low-end model> (provider/model-id)
       consistency-checker      → <low-end model> (provider/model-id)
       story-explorer           → <low-end model> (provider/model-id)

   • If automatic detection fails (

     opencode models

     is unavailable), output manual configuration guide:

     Unable to automatically detect model list. The following Agents are not configured with models and will use the main model, cost may be higher:
       - chapter-extractor (recommended to use low-cost model)
       - consistency-checker (recommended to use low-cost model)
       - story-explorer (recommended to use low-cost model)
     
     Manual configuration method: Edit .opencode/agents/{agent-name}.md, add to frontmatter:
       model: provider/model-id
     
     Available model list and cost can be viewed via opencode models --verbose (output includes cost/context per model).
     Model library and pricing see OpenCode official model source https://models.dev/.

7. Verify opencode deployment (only when target_cli contains opencode):
   • Check if the 7 agent definition files under

     .opencode/agents/

     exist, and the frontmatter contains

     mode: subagent

     and

     permission

     fields
   • Check if

     .opencode/plugins/story-hooks.ts

     exists
   • Check if

     .opencode/plugins/lib/story_hook_core.js

     exists and passes

     node --check

     (imported by story-hooks.ts, shared prose guard core with identical bytes to

     .zcode

     copy; placed in

     lib/

     subdirectory to avoid OpenCode's automatic discovery of single-layer

     .opencode/plugins/*.js

     plugins)
   • Check if the 13 command files under

     .opencode/commands/

     exist
   • Check if the reference files under

     skills/story-setup/references/agent-references/

     are complete and the quantity is the same as the source directory
   • Check if the

     plugin

     array in

     opencode.json

     contains the story-hooks entry
   • Check if

     .git/hooks/pre-commit

     exists and has execution permissions (skip execution permission check on Windows)
   • Check if the frontmatter of agent files under

     .opencode/agents/

     can be parsed by YAML, and

     model:

     (if configured) is a valid top-level scalar, not just grep for

     model:

     substring
8. Verify Codex deployment (only when target_cli contains codex):
   • Check if

     AGENTS.md

     contains Codex story skill routing sections
   • Check if 7

     .toml

     agent definition files under

     .codex/agents/

     exist and can be parsed
   • Check if

     .codex/hooks.json

     exists and is JSON valid, Unix

     command

     is only started via

     run-story-hook.sh

     , Windows

     commandWindows

     is only started via

     run-story-hook.cmd

     ; no registration of direct call

     story_codex_hook.py

     exists
   • Check if

     .codex/hooks/story_codex_hook.py

     ,

     run-story-hook.sh

     ,

     run-story-hook.cmd

     exist, Python syntax is valid, POSIX/Windows launcher can locate project root from nested cwd
   • Check if the reference files under

     .codex/skills/story-setup/references/agent-references/

     are complete and the quantity is the same as the source directory
   • The installation report must prompt: Codex needs to trust the project's

     .codex/

     configuration layer, and review/trust non-managed hooks in

     /hooks

     ; start a new Codex session after deployment to make custom agents take effect; if the current runtime still returns

     unknown agent_type

     , downgrade to solo/direct according to the fallback rules of each skill
9. Verify ZCode deployment (only when target_cli contains zcode):
   • Check if the root

     AGENTS.md

     contains ZCode

     $story-*

     routing, outline guard and solo/direct fallback
   • Check 13 Skills under

     .zcode/skills/

     and 13 Commands under

     .zcode/commands/

     , verify frontmatter and naming
   • Check if

     .zcode/hooks/story_zcode_hook.js

     ,

     .zcode/hooks/story_hook_core.js

     exist and pass

     node --check

   • Check if

     .zcode/config.json

     is JSON valid, and verify according to hooks mutual exclusion branch in Step 4 of "ZCode Deployment Algorithm": When oh-story plugin is not installed,

     hooks.enabled=true

     , only register ZCode supported events, all

     process

     args point to project Hook; when oh-story plugin is installed (

     .zcode-plugin/plugin.json

     has globally registered these hooks), instead verify that

     .zcode/config.json

     does not contain (or has removed) these oh-story hook registrations —do not merge the hooks block of

     config.json.patch

     back to make verification pass, otherwise the same event will be triggered twice
   • Check if

     .zcode/skills/story-setup/references/agent-references/

     is complete and all reference paths can be resolved
   • Call SessionStart, PreToolUse deny/allow, PostToolUse with fixture, confirm stdout is empty when no discovery, and conforms to ZCode strict JSON when there is output
   • The installation report must prompt: ZCode 3.3.4 does not execute project/plugin custom agents, full/lean multi-Agent requests will be stably downgraded to solo/direct; Hook depends on

     node

     in PATH; start a new ZCode session after deployment to refresh Skills/Commands/AGENTS.md
10. Verify OpenClaw deployment (only when target_cli contains openclaw):
    • Check if

      AGENTS.md

      contains OpenClaw story skill routing sections
    • Check if 13 story skill directories under

      skills/

      exist, and each

      SKILL.md

      contains single-line

      name

      , single-line

      description

      , single-line JSON

      metadata.openclaw

    • Check if the reference files under

      skills/story-setup/references/agent-references/

      are complete and the quantity is the same as the source directory
    • The installation report must prompt: OpenClaw Phase 1 is skills-only; OpenClaw agents/hooks are not deployed, runtime hard interception is unavailable, outline guard before writing prose, commit reminder, session/compact automatic injection only serve as soft constraints within skills; OpenClaw snapshots eligible skills when the session starts, if commands/skills do not appear after deployment, start a new OpenClaw session or wait for skills watcher to refresh
11. Verify General Web AI / Other Agent deployment (only when target_cli contains generic):
    • Check if

      AGENTS.md

      contains general story skill routing sections
    • Check if 13 story skill directories under

      skills/

      exist, and each

      SKILL.md

      is readable
    • Check if the reference files under

      skills/story-setup/references/agent-references/

      are complete and the quantity is the same as the source directory
    • The installation report must prompt: generic does not deploy platform-specific hooks/custom agents; hard interception such as outline guard, commit reminder, session/compact injection and multi-agent collaboration are executed according to soft constraints within skills or solo/direct fallback
12. Verify Reasonix deployment (only when target_cli contains reasonix):
    • Check if

      AGENTS.md

      contains Reasonix story skill routing sections and solo/direct fallback instructions
    • Check if 13 story skill directories under

      skills/

      exist, and each

      SKILL.md

      is readable
    • Check if the project's

      .agents/skills

      is a symlink pointing to

      skills/

      (POSIX; allows Reasonix native scanning to discover skills); when symlink is not created on Windows, instead confirm that the root

      reasonix-plugin.json

      can be used for

      reasonix plugin install

    • Check if the reference files under

      skills/story-setup/references/agent-references/

      are complete and the quantity is the same as the source directory
    • The installation report must prompt: Reasonix is currently skills-only; Reasonix hooks/custom agents are not deployed, outline guard before writing prose, commit reminder, session/compact automatic injection only serve as soft constraints within skills, Skills involving professional Agents use solo/direct fallback; use

      reasonix doctor capabilities

      to verify skill discovery, if new skills do not appear after deployment, start a new Reasonix session or use root

      reasonix-plugin.json

      for native plugin installation

Template Placeholders

{项目名}

{书名}

{项目名}

{目标平台}

{作者名}

CLAUDE.md Merge Strategy

1. Prioritize identifying story-setup managed block markers (if the old project already has markers, only replace the content within the markers)
2. If no markers exist, read the user's existing CLAUDE.md and split into section map by

   ##

   titles
3. Read the template CLAUDE.md.tmpl and split in the same way
4. Standard sections in the template (Skill routing table, file structure, collaboration rules, restore context after Compact) override the user's sections with the same name
5. User's unique sections (custom content) retained unchanged
6. For unknown conflicts, use AskUserQuestion to let the user choose which version to retain

AGENTS.md Merge Strategy (OpenCode / Codex / ZCode / OpenClaw / Reasonix / generic)

1. Prioritize identifying story-setup managed block markers (if the old project already has markers, only replace the content within the markers)
2. If no markers exist, read the user's existing AGENTS.md and split into section map by

   ##

   titles
3. OpenCode uses

   skills/story-setup/references/opencode/AGENTS.md.tmpl

   ; Codex uses

   skills/story-setup/references/codex/AGENTS.md.tmpl

   ; ZCode uses

   skills/story-setup/references/zcode/AGENTS.md.tmpl

   ; OpenClaw uses

   skills/story-setup/references/openclaw/AGENTS.md.tmpl

   ; Reasonix uses

   skills/story-setup/references/reasonix/AGENTS.md.tmpl

   ; General Web AI / Other Agents use

   skills/story-setup/references/generic/AGENTS.md.tmpl

4. Standard sections in the template (Skill routing table, file structure, collaboration rules, restore context after Compact) override sections with the same name; user's unique sections are retained
5. When deploying to multiple ends, retain only one copy of general paragraphs common to Codex/OpenCode/ZCode/OpenClaw/Reasonix/generic; tool-specific instructions are distinguished by subsections to avoid overwriting each other

Redeployment

• .story-deployed

  does not exist → New installation, execute all of Phase 2

• .story-deployed

  exists and

  agents_version: 25

  → Prompt that it has been deployed, use AskUserQuestion to confirm whether to redeploy; clearly state in the prompt that redeployment only refreshes project files using the current local skill package, skill updates are done via

  npx skills add

  or marketplace

• .story-deployed

  exists but

  agents_version

  is missing, non-integer or less than

  25

  → Prompt that update is needed, re-execute Phase 2 to overwrite agents/hooks/rules/reference bundle, CLAUDE.md / AGENTS.md / settings.local.json / .codex/hooks.json / .zcode/config.json follow merge strategy

• .story-deployed

  exists and

  agents_version

  is greater than

  25

  → Current skill version is too old, stop and prompt to update oh-story-claudecode first; do not overwrite updated deployment in the project

Reference Materials

story_hook_core.js

story_hook_cli.js

lib/common.sh

lib/sentinel.sh

check-prose-after-write.sh

cat>

tee

Process Connection

/story-long-write

/story-short-write

/story-import

/browser-cdp

/name

$name

/skill name