# Skein Setup

> SKEIN 工作区初始化 + 结构维护。未初始化仓库 (无 .skein/ 或 SessionStart 提示) 一键 scaffold; 已初始化时按需手动优化 .skein 结构 (spec 类目重组 / 调规则 inclusion 加载策略 / config 调参), 改盘后 reindex。既有 trellis 仓迁移见 references/trellis-migration.md。幂等可重跑。

- Skill: `lazygophers/skein-setup` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add lazygophers/skein-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lazygophers/skein-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lazygophers (https://skillmd.com/u/lazygophers)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lazygophers/skein-setup

---


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

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

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

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

## 分流

```bash
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](../skein-spec/references/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/` |