lazygophers/skein-setup

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

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

触发: 用户显式 /skein-setup, 或 SessionStart hook 注入「无 .skein/」提示后 main 主动调用。

分流

skein setup   # 幂等 scaffold + 输出 manifest JSON

| manifest / 现状 | 用途 | 见 | | ------------------------------------------- | ---------------------------------- | --------------------------------- | | 无 .skein/ (trellis_present:false) | ① 初始化 — main 直接跑, 纯机械 | 下 §初始化 | | 已有 .skein/ | ② 结构维护 — 用户手动优化 | 下 §结构维护 | | 检测到 .trellis/ (trellis_present:true) | ① 的一种场景 — 派 agent 语义迁移 | references/trellis-migration.md |

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

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

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

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

| 想改 | 怎么改 | 收尾 | | ----------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------- | ------------ | | 并发上限 (max_active / max_parallel) | 直接 Edit .skein/config.yaml | 无 | | spec 类目重组 (类目 = 层内子目录, 自由取名 git/test/arch/build/style/domain/ops...) | 移动 / 改名 .skein/spec/<layer>/<category>/*.md | skein-spec reindex | | core↔recall 层调 (core 常驻过重, >8000 字符会告警) | 把规则文件从 spec/core/ 移到 spec/recall/ (或反向) | skein-spec reindex | | 新增一条规则 | skein-spec sediment --layer <core | recall> --category <cat> --title <T> | 自动 reindex |

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

铁律 (通用)

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

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

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

| 场景 | 正确做法 (❌ 反面) | | ------------------------ | ------------------------------------------------------------------------------------- | | 改 .skein/task* | 经 skein create/start/... 命令改 (❌ 手改绕脚本 → PreToolUse hook 硬阻 + 破坏索引一致性) | | 改 spec 盘面后 | 必跑 skein-spec reindex (❌ 不 reindex → 三份 index.md 落后盘面 = 召回失效) | | 检测到 .trellis/ | 先 AskUserQuestion 选兼容 / --full 再迁移 (❌ 直接 setup --full → 未问用户整删可能丢数据) | | 已初始化仓重跑 | 正常重跑, config/spec 存在则跳过 (❌ 当报错 → setup 幂等, 重跑安全不覆盖) | | 规则归层 | 默认 recall, core 只留命令式硬契约 (❌ 什么都堆进 core 常驻 → >8000 字符告警, 稀释硬约束) |

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

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