skein-setup

name	skein-setup
description	SKEIN 工作区初始化 + 结构维护。未初始化仓库 (无 .skein/ 或 SessionStart 提示) 一键 scaffold; 已初始化时按需手动优化 .skein 结构 (spec 类目重组 / 调规则 inclusion 加载策略 / config 调参), 改盘后 reindex。既有 trellis 仓迁移见 references/trellis-migration.md。幂等可重跑。
argument-hint	[trellis 迁移模式: 缺省=兼容保留 .trellis 数据, 完全删除 .trellis]
arguments	[trellis 迁移模式: 缺省=兼容保留 .trellis 数据, 完全删除 .trellis]
model	sonnet
effort	medium
user-invocable	true

skein-setup — 初始化 / 结构维护

🔒 全局流程规则（状态机/调度/优先级等）以 skein-flow/references/ 为单一真值源。

两用途：① 未初始化仓库 → 建 .skein/ 工作区；② 已初始化 → 手动优化 .skein/ 结构。幂等 — 重跑安全。

触发: 用户显式要求初始化 / 迁移 / 维护 SKEIN 工作区, 或 SessionStart hook 注入「无 .skein/」提示后 main 主动调用。

分流

skein setup   # 幂等 scaffold + 输出 manifest JSON

manifest / 现状	用途	见
无 .skein/ (trellis_present:false)	① 初始化 — main 直接跑, 纯机械	下 §初始化
已有 .skein/, spec/ 已是 rules/product/map/external 新结构	② 结构维护 — 用户手动优化	下 §结构维护
已有 .skein/, 检出 spec/core/ (旧两层结构残留)	② 的前置 — 提示迁移新 namespace 结构, 用户拒绝仍可继续②用旧路径	../skein-spec/references/migration-v2.md
检测到 .trellis/ (trellis_present:true)	① 的一种场景 — 派 agent 语义迁移	references/trellis-migration.md

① 初始化 (未初始化仓库)

1. 新仓 → main 直接跑 skein setup (纯机械, 不派 agent): 建 .skein/ + config + gitignore + 本地 .skein/spec 库 (直接落 rules/product/map/external 四 namespace 目录, 不经过旧两层结构)。完成即可用。
2. 既有 trellis 仓 (.trellis/) → 🛑 检测到 .trellis/ 时 main 用 AskUserQuestion 让用户选迁移模式 (缺省兼容 · STOP, --full 整删不可逆): 兼容 (留 .trellis/ 数据) / --full (整删 .trellis/); 接线 (hooks/scripts/settings) 两模式都删。据选定跑 setup 或 setup --full, 语义迁移 (派 skein-setup agent) 详见 references/trellis-migration.md (目标结构同 §②旧结构检出: 四 namespace)。

旧两层结构检出 (spec/core/ 存在, 独立于 trellis 迁移)

已初始化仓 (.skein/ 已存在) 若检出 spec/core/ 目录 (旧 core/recall 两层, 迁移新 namespace×inclusion 结构前的遗留) → 🛑 main 用 AskUserQuestion 提示「检测到旧两层结构, 是否迁移新 namespace 结构 (rules/product/map/external)」。用户同意 → 走 migration-v2.md 两阶段流程 (阶段 1 机械改名无损, 阶段 2 语义分拣 product/map 无硬性完成线)。用户拒绝 → 旧结构继续可用 (skein-spec 各命令兼容旧路径读取, 新写入统一走新结构), 不阻塞正常使用, 不强迁。

② 结构维护 (已初始化, 用户手动优化)

用户想调整 .skein/ 布局时用。可调项 + 落地方式：

想改	怎么改	收尾
并发上限 (max_active)	直接 Edit .skein/config.yaml	无
spec 类目重组 (类目 = namespace 内子目录, 自由取名 git/test/arch/build/style/domain/ops...)	移动 / 改名 .skein/spec/<namespace>/<category>/*.md (namespace 自由目录, 默认 rules/product/map/external)	skein-spec reindex
调加载策略 (页过重超 spec.always_budget 会告警, 数值见 .skein/config.yaml)	改规则文件 frontmatter 的 inclusion: (always/auto/fileMatch/manual 四值, 与 namespace 正交), 不要搬文件 — 目录 = namespace(内容类型), 与加载策略无关; 或跑 skein-spec degrade <cat>/<name> 自动改 (always→auto)	skein-spec reindex
新增一条规则	skein-spec sediment --namespace <ns> [--inclusion always|auto] --category <cat> --topic <主题> --title <T>	追加为主题文件章节 + 自动 reindex

• 改 spec 盘后必 reindex — 索引 (三份 index.md) 落后于实际盘面 = 召回失效。
• task.json / task.md 禁手改 — 经 skein task create/confirm/... 命令维护, PreToolUse hook 硬阻直接写。

铁律 (通用)

• 幂等 — 已初始化重跑不覆盖 (config/spec 存在则跳过); .skein/spec 已存在则不重复拷贝。
• spec 盘面变更后 reindex — 手动重组 / 迁移后同步索引。
• task 状态经脚本 — 不直接编辑 .skein/task*。

✅ 正向配方 (命中反面=流程错误)

🔒 铁律: 幂等可重跑; task.json/task.md 经脚本不经手改 (PreToolUse hook 硬阻)。

场景	正确做法 (❌ 反面)
改 .skein/task*	经 skein task create/confirm/... 命令改 (❌ 手改绕脚本 → PreToolUse hook 硬阻 + 破坏索引一致性)
改 spec 盘面后	必跑 skein-spec reindex (❌ 不 reindex → 三份 index.md 落后盘面 = 召回失效)
检测到 .trellis/	先 AskUserQuestion 选兼容 / --full 再迁移 (❌ 直接 setup --full → 未问用户整删可能丢数据)
已初始化仓重跑	正常重跑, config/spec 存在则跳过 (❌ 当报错 → setup 幂等, 重跑安全不覆盖)
规则归类	默认 namespace=rules + inclusion=auto, inclusion=always 只留命令式硬契约 (❌ 什么都堆进 always 常驻 → 超预算告警, 稀释硬约束)
检出 spec/core/ 旧结构	AskUserQuestion 征同意再走 migration-v2 两阶段迁移 (❌ 不问用户直接批量改路径, 或放任旧结构不提示)

失败模式 (if-then 三段式: 触发 → 一线修复 → 仍失败兜底)

触发	一线修复	仍失败兜底
skein setup 报错	读 manifest JSON error 字段定位 (权限 / 路径占用 / 已存在)	仍失败 → 报用户, 禁手工拼凑 .skein/
skein-spec reindex 报错	读 stderr 定位 (类目名非法 / 路径)	仍失败 → 停手报用户, 禁半写坏索引
trellis 迁移中断	数据仍在 .trellis/ (兼容模式未删), 重跑迁移	仍中断 → 报用户, 禁手工拼凑 .skein/