| 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
| 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 |
① 初始化 (未初始化仓库)
- 新仓 → main 直接跑
skein setup (纯机械, 不派 agent): 建 .skein/ + config + gitignore + 本地 .skein/spec 库 (直接落 rules/product/map/external 四 namespace 目录, 不经过旧两层结构)。完成即可用。
- 既有 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/ |
