@jennie-shawn/starwork 0.1.0-alpha.0

package/skills/starworkInit-spec.md

@@ -0,0 +1,585 @@
+# `starworkInit` Skill SPEC
+
+## 状态
+
+- 版本：v0.1 draft
+- 所属模块：StarWork Skills
+- Skill 名称：`starworkInit`
+- 相关命令：`starwork init`
+- 实现状态：未实现
+- 目标：帮助 Agent 把用户“我想建一个工作台”的模糊需求，整理成可预览、可执行、可解释的 StarWork 初始化方案
+
+## 一句话定义
+
+`starworkInit` 是 StarWork 初始化设计 skill。
+
+它不是 `starwork init` 命令本身，而是命令执行前的 AI 设计助手：
+
+```text
+用户说想建工作台
+  ↓
+starworkInit skill 追问和判断
+  ↓
+初始化方案 / init blueprint
+  ↓
+starwork init 或未来 starwork init --blueprint
+  ↓
+可用 StarWork 工作台
+```
+
+## 为什么它是 skill，不是 CLI 规格
+
+`init` 处在用户最早期的入口。此时用户往往还没想清楚：
+
+- 是要单项目，还是多项目中枢
+- 是轻量工作台，还是长期事项型工作台
+- 是否需要 Pack
+- 正式成果应该放哪里
+- 当前推进过程应该放哪里
+- 是否有自己的命名习惯
+- 是否未来会升级成 Hub + Satellite
+
+这些不是 CLI 参数能一次问清的，而是 Agent 应该通过对话帮用户梳理。
+
+所以本 SPEC 的主角是：
+
+> Agent 如何判断、如何追问、如何输出初始化方案。
+
+CLI 的 `init --blueprint` 只是未来承接这个方案的执行入口。
+
+## 与 `starworkSpawn` 的关系
+
+| Skill | 用户状态 | 目标 | 依赖 Hub |
+|---|---|---|---:|
+| `starworkInit` | 还没有工作台 | 从 0 设计并创建工作台 | 否 |
+| `starworkSpawn` | 已有 Hub | 从 Hub 派生一个项目工作台 | 是 |
+
+`starworkInit` 解决的是：
+
+```text
+我要建立什么样的工作系统？
+```
+
+`starworkSpawn` 解决的是：
+
+```text
+这个 Hub 下的新项目要长什么样？
+```
+
+二者可以共享“blueprint”思想，但不应共用同一个 schema。
+
+## Skill 输入
+
+用户可能会这样触发：
+
+- “帮我建一个 StarWork 工作台”
+- “我要初始化一个内容创作工作台”
+- “我想建一个多项目管理系统”
+- “我想用 StarWork 管一个长期项目”
+- “这个工作台的目录我想定制一下”
+- “init 有没有类似 spawn blueprint 的定制能力”
+
+skill 应在这些场景下启动。
+
+## Skill 输出
+
+根据用户需求成熟度，`starworkInit` 可以输出三种结果。
+
+### 1. 初始化建议
+
+当用户还在讨论阶段，输出一份人能读懂的建议：
+
+```text
+建议使用：single-matter
+基础 Kit：local-matter
+Pack：content-creator
+正式成果：发布记录/
+当前工作：事项/
+额外目录：账号定位/、选题池/、素材库/
+原因：这是长期内容工作台，需要事项追踪和内容生产闭环。
+```
+
+### 2. 初始化定制单
+
+当用户要求落地方案时，生成：
+
+```text
+<workspace>-init/
+├── init-blueprint.json
+├── rules/
+│   ├── file-boundaries.md
+│   ├── workflow.md
+│   └── startup.md
+└── seed/
+    └── ...
+```
+
+### 3. 执行指令
+
+当用户准备测试时，给出命令：
+
+```bash
+starwork init --target <workspace-path> --blueprint <init-blueprint.json> --dry-run
+starwork init --target <workspace-path> --blueprint <init-blueprint.json> --yes
+starwork doctor --target <workspace-path>
+```
+
+注意：当前 CLI 尚未实现 `init --blueprint`，因此在实现前应说明这是目标命令形态；当前可执行路径仍是普通 `starwork init` 加后续手工调整或未来 CLI 实现。
+
+## 交互流程
+
+`starworkInit` 不应该像填表工具一样一上来问一长串问题。
+
+它应该像一个会带路的顾问：先判断岔路，再决定哪些问题需要问、哪些问题根本不用问。
+
+### 总流程
+
+```text
+Step 1 判断工作台类型
+  ├─ hub：跳过 Step 2 / Step 3，直接进入 Hub 初始化建议
+  └─ single：继续判断是否需要事项
+
+Step 2 判断是否需要事项
+  ├─ 需要：single-matter
+  └─ 不需要：single-light
+
+Step 3 判断 Pack
+  ├─ 使用现成 Pack：general / content-creator
+  └─ 暂不支持深度定制其他 Pack
+
+Step 4 判断是否需要定制工作台
+  ├─ 不需要：输出标准初始化建议
+  └─ 需要：进入 Step 5-7 的友好采访
+
+Step 5 采访正式成果放哪里
+Step 6 采访日常工作在哪里发生
+Step 7 采访额外固定区域和 Agent 规则
+```
+
+### Step 1：判断工作台类型
+
+先问：
+
+```text
+你是想管理一个具体项目，还是建立一个能管理多个项目的中枢？
+```
+
+判断：
+
+| 用户意图 | 推荐工作区 |
+|---|---|
+| 一个具体项目、资料整理、轻量输出 | `single-light` |
+| 一个长期项目、跨会话推进、需要事项 | `single-matter` |
+| 管理多个项目、统一身份/教训/知识/skills | `hub` |
+
+如果用户说“以后可能会有很多项目”，但当前只是一个项目，优先建议：
+
+```text
+先用 single-matter；等多项目需求明确后再建 Hub。
+```
+
+除非用户明确要建立多项目中枢。
+
+#### Hub 分支
+
+如果判断为 `hub`，就不要继续追问“是否需要事项”和“选择哪个 Pack”。
+
+Hub 的核心不是一个项目怎么推进，而是统一维护：
+
+- 身份和长期偏好
+- 跨项目经验教训
+- 共享知识
+- skills
+- 多个项目的注册、分发和回收
+
+因此 Hub 分支应直接输出：
+
+```text
+建议类型：hub
+基础 Kit：hub
+Pack：无须选择；Hub 使用中枢管理结构
+事项：不作为 Hub 初始化必选项
+下一步：确认 Hub 名称、项目注册区域、是否需要预置 skills/ 和 .incoming/
+```
+
+### Step 2：判断是否需要事项
+
+仅当 Step 1 判断为 `single-light` 或 `single-matter` 候选时，才进入这一步。
+
+问：
+
+```text
+这个工作会不会持续数周以上，或者需要多次接力？
+```
+
+判断：
+
+- 需要长期推进、复盘、交接：`single-matter`
+- 只是放资料、写草稿、收成果：`single-light`
+- 管理多个项目：返回 Step 1，改为 `hub`
+
+### Step 3：判断 Pack
+
+仅当 Step 1 不是 `hub` 时，才进入这一步。
+
+问：
+
+```text
+这个工作台主要用于什么场景？
+```
+
+判断：
+
+| 场景 | 推荐 Pack |
+|---|---|
+| 泛用资料、草稿、项目推进 | `general` |
+| 内容创作、自媒体、发布复盘 | `content-creator` |
+| 多项目中枢管理 | `hub-management` |
+
+规则：
+
+- 通用工作也是 Pack：`general`
+- Hub 不在 init 交互里让用户选择 Pack；Hub 使用中枢管理结构
+- 不要把一次性目录偏好误判成新 Pack
+- 重复出现的行业/岗位结构才考虑沉淀为 Pack
+- v0.1 只支持对 `general` Pack 做定制修改
+- 如果用户选择 `content-creator`，可以安装现成 Pack，但暂不进入自定义 Pack 结构采访
+
+### Step 4：判断是否需要定制工作台
+
+这是 Step 4-7 之前必须插入的判断节点。
+
+问法要轻，不要让用户感觉自己在设计数据库：
+
+```text
+你想先用标准结构，还是希望我帮你按自己的工作习惯稍微改一下目录和规则？
+```
+
+判断：
+
+| 用户选择 | 后续动作 |
+|---|---|
+| 标准结构就行 | 输出标准 Kit + Pack 初始化建议 |
+| 想改一下 | 进入 Step 5-7 |
+| 不确定 | 给 2-3 个具体例子帮用户判断 |
+
+可以这样解释：
+
+```text
+标准结构像直接入住酒店；定制结构像把书桌、收纳盒和常用文件夹按你的习惯摆好。
+如果你还没形成稳定习惯，先用标准结构更省心。
+```
+
+v0.1 的定制边界：
+
+- 只支持基于 `general` Pack 做目录和规则定制
+- 不支持定制 `content-creator` Pack 的内部结构
+- 不支持定制 Hub 的中枢结构
+- 不把单次定制升级成新 Pack
+
+### Step 5：采访正式成果位置
+
+问：
+
+```text
+哪些东西算“最终确认、以后要回看的成果”？
+```
+
+更友好的问法：
+
+```text
+等这个工作台用一段时间后，你最希望未来的自己回来翻到什么？
+是最终交付物、发布记录、客户确认版，还是项目清单？
+```
+
+常见映射：
+
+| 用户说法 | formal_source |
+|---|---|
+| 最终成果、交付物、确认版本 | `输出/确认成果/` 或 `交付物/确认版本/` |
+| 已发布内容、发布记录 | `发布记录/` |
+| 项目清单、项目注册 | `项目/` |
+
+如果用户答不上来，可以先给默认建议：
+
+```text
+如果没有特别偏好，我会把正式成果放在“输出/确认成果/”，这样它和草稿、过程材料不会混在一起。
+```
+
+### Step 6：采访日常工作区
+
+问：
+
+```text
+日常推进过程主要在哪里发生？
+```
+
+更友好的问法：
+
+```text
+你平时会在哪里“干活”？
+比如写草稿、放参考资料、记录推进过程、整理待办和阶段判断。
+```
+
+常见映射：
+
+| 工作方式 | business_work_area |
+|---|---|
+| 事项推进 | `事项/` |
+| 轻量资料整理 | `参考资料/` |
+| 内容草稿推进 | `草稿与脚本/` 或 `事项/` |
+| Hub 管理 | `项目/` |
+
+如果用户说“就是普通项目”，默认：
+
+```text
+single-light：参考资料/
+single-matter：事项/
+```
+
+### Step 7：采访额外目录和 Agent 规则
+
+只添加未来确实会使用的目录。
+
+推荐问法：
+
+```text
+除了标准结构外，有没有你明确会反复使用的固定区域？
+```
+
+更友好的问法：
+
+```text
+有没有一些东西你每次都想单独放，不想和别的文件混在一起？
+比如会议纪要、客户沟通、版本记录、素材库、复盘。
+```
+
+可以建议：
+
+- `会议纪要/`
+- `版本记录/`
+- `客户沟通/`
+- `资料库/`
+- `项目复盘/`
+
+避免：
+
+- 含义重叠的目录
+- 只为好看创建的目录
+- 与 Pack 已有目录重复的目录
+
+至少考虑两类规则：
+
+```text
+rules/file-boundaries.md
+rules/workflow.md
+```
+
+可选：
+
+```text
+rules/startup.md
+rules/handoff.md
+```
+
+规则应具体说明：
+
+- 哪类信息放哪里
+- 什么时候写正式成果
+- 什么时候写事项
+- 哪些目录只读
+- 哪些内容需要用户确认
+
+不要写泛泛的“提高效率”“保持清晰”。
+
+### 采访原则
+
+Step 5-7 的采访要避免抽象词，尽量用“你平时怎么做”的语言。
+
+推荐方式：
+
+- 一次只问一个问题
+- 先给用户选项，再允许用户自由描述
+- 用户说不清时，用默认值推进
+- 每问完一轮，都用一句话复述当前判断
+
+例如：
+
+```text
+我先按“正式成果放在 输出/确认成果/，日常推进放在 事项/”理解。
+这样草稿和确认版不会混在一起。你看这个分法顺不顺手？
+```
+
+## Init Blueprint 建议结构
+
+当需要产出机器可读方案时，使用：
+
+```json
+{
+  "schema": "starwork.init_blueprint.v0.1",
+  "name": "我的项目工作台",
+  "workspace_type": "single-matter",
+  "kit": "local-matter",
+  "language": "zh",
+  "pack": "general",
+  "paths": {
+    "formal_source": "输出/确认成果/",
+    "business_work_area": "事项/"
+  },
+  "folders": [
+    "会议纪要/",
+    "客户沟通/",
+    "版本记录/"
+  ],
+  "agent_rules": [
+    {
+      "slot": "workspace.file_boundaries",
+      "from": "rules/file-boundaries.md"
+    },
+    {
+      "slot": "workspace.workflow",
+      "from": "rules/workflow.md"
+    }
+  ],
+  "seed": [
+    {
+      "from": "seed/会议纪要/README.md",
+      "to": "会议纪要/README.md",
+      "on_conflict": "error"
+    }
+  ]
+}
+```
+
+## Blueprint 字段建议
+
+| 字段 | 说明 |
+|---|---|
+| `schema` | 固定为 `starwork.init_blueprint.v0.1`。 |
+| `name` | 工作台名称。 |
+| `description` | 工作台说明，可写入项目状态。 |
+| `workspace_type` | `single-light`、`single-matter` 或 `hub`。 |
+| `kit` | `local-starter`、`local-matter` 或 `hub`。 |
+| `language` | v0.1 先使用 `zh`。 |
+| `pack` | 标准初始化可选择 `general` 或已有场景 Pack；v0.1 定制 blueprint 只支持 `general`。 |
+| `paths.formal_source` | 正式成果位置。 |
+| `paths.business_work_area` | 当前工作区。 |
+| `folders` | 额外目录。 |
+| `agent_rules` | 要注入的规则文件。 |
+| `seed` | 初始化占位文件。 |
+
+## 必须遵守的判断边界
+
+### 不用 init 创建卫星项目
+
+如果用户要在已有 Hub 下创建项目，应转向 `starworkSpawn`：
+
+```text
+已有 Hub + 新项目 = starworkSpawn
+从 0 建工作台 = starworkInit
+```
+
+### 不把一次性偏好做成 Pack
+
+如果用户只是想把 `发布记录/` 改成 `成品库/`，这是 Init Blueprint。
+
+如果用户想创建一套未来反复给内容创作者使用的完整结构，才考虑 Pack。
+
+### 不污染 Kit
+
+skill 不能建议用户修改：
+
+```text
+product/core/kits/
+```
+
+Kit 是基础骨架，不服务于单次定制。
+
+### 不让 blueprint 决定真实 target
+
+真实写入位置必须来自命令参数或用户明确指定。
+
+Blueprint 可以描述“工作台是什么”，不应该擅自决定“写到机器哪里”。
+
+## 输出模板
+
+当用户要求“先说方案”时：
+
+```markdown
+## 初始化建议
+
+- 工作区类型：
+- Kit：
+- Pack：
+- 正式成果：
+- 当前工作区：
+- 额外目录：
+- 需要注入的规则：
+
+## 为什么这样选
+
+...
+
+## 后续执行
+
+当前可用：
+...
+
+未来 blueprint 执行：
+...
+```
+
+当用户要求“生成定制单”时：
+
+```text
+<workspace>-init/
+├── init-blueprint.json
+├── rules/file-boundaries.md
+├── rules/workflow.md
+└── seed/...
+```
+
+## 与 CLI 的关系
+
+`starworkInit` 的第一目标不是运行 CLI，而是生成正确方案。
+
+CLI 后续应支持：
+
+```bash
+starwork init --target <path> --blueprint <init-blueprint.json> --dry-run
+starwork init --target <path> --blueprint <init-blueprint.json> --yes
+```
+
+但在 CLI 实现前，skill 应该诚实说明：
+
+```text
+当前 CLI 还没有 init --blueprint 执行能力；这份定制单先作为实现依据。
+```
+
+## 待确认问题
+
+1. `starworkInit` 是否需要先落成 skill，再实现 CLI `init --blueprint`？
+2. 是否允许一个 Init Blueprint 安装多个 Pack？
+3. Hub 初始化是否需要专门的 Hub Init Blueprint 子模式？
+4. 是否要把 `init_blueprint` 和 `spawn_blueprint` 抽出共享字段规范？
+5. `starworkInit` 生成的 blueprint 是否应能被后续升级为 Pack preset？
+
+## 结论
+
+`starworkInit` 的核心不是“多一个命令参数”，而是：
+
+```text
+帮用户把还没想清楚的工作台需求，整理成一张可执行施工单。
+```
+
+它让 StarWork 初始化从：
+
+```text
+选一个模板
+```
+
+升级为：
+
+```text
+Agent 帮用户设计工作台，CLI 负责稳定落地。
+```

package/skills/starworkSpawn/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: starworkSpawn
+description: Use this skill when a user wants to design or generate a customized StarWork satellite workspace for `starwork spawn --blueprint`, including choosing starter vs matter mode, drafting blueprint.json, writing project rules, planning seed files, and explaining how to execute and validate the spawn.
+---
+
+# starworkSpawn
+
+使用这个 skill，把用户的项目想法转成 StarWork Spawn Blueprint（工作台定制单）。
+
+Spawn Blueprint 是一个小型配置包：
+
+- `blueprint.json`：机器可读的结构和路径配置
+- `rules/*.md`：项目专属 Agent 规则
+- `seed/**`：可选的初始化占位文件
+
+Blueprint 由 `starwork spawn --blueprint` 执行。除非用户明确要求落地文件，否则这个 skill 只负责设计，不直接修改用户的 Hub 或目标工作区。
+
+## 参考
+
+需要字段细节、校验规则或命令行为时，读取：
+
+```text
+../../cli/spawn-blueprint-spec.md
+```
+
+不要在 skill 内重复维护完整 schema，避免和 SPEC 漂移。
+
+## 工作流程
+
+1. 识别用户要创建的工作台。
+   - 项目是什么？
+   - 是短期轻量项目，还是长期推进项目？
+   - 是否需要事项、决策、交接记录或跨会话追踪？
+
+2. 选择基础模式。
+   - 长期项目、多步骤工作、跨会话协作、需要事项追踪时，使用 `matter`。
+   - 轻量项目、主要只需要资料和成果输出时，才使用 `starter`。
+
+3. 判断应该用 Blueprint 还是 Pack。
+   - 一次性项目定制，用 Blueprint。
+   - 多个项目或多个用户会反复复用的结构，再建议沉淀为 Pack。
+   - 不要把每个目录偏好都做成 Pack。
+
+4. 设计工作台路径。
+   - 定义 `formal_source`：确认成果或最终交付物放在哪里。
+   - 定义 `business_work_area`：当前工作在哪里推进。
+   - 只新增未来确实会用到的目录。
+   - 避免装饰性、含义模糊的目录。
+
+5. 编写项目规则。
+   - `rules/file-boundaries.md`：不同信息分别应该放哪里。
+   - `rules/workflow.md`：Agent 如何在工作台里推进工作。
+   - `rules/handoff.md`：只有涉及跨项目或跨会话交接时才创建。
+
+6. 产出或更新文件。
+   - 用户只是讨论时，用文字描述方案。
+   - 用户要求实现时，创建 blueprint 文件夹和文件。
+   - 用 `blueprint.json` 管结构，用 Markdown 管 Agent 规则；不要把长规则塞进 JSON。
+
+7. 说明执行方式。
+   - 先用 `starwork spawn --blueprint ... --dry-run` 预览。
+   - 确认后再执行，或使用 `--yes`。
+   - 最后用 `starwork doctor` 检查。
+
+## 输出结构
+
+实现 blueprint 包时使用：
+
+```text
+<project>-blueprint/
+├── blueprint.json
+├── rules/
+│   ├── file-boundaries.md
+│   ├── workflow.md
+│   └── handoff.md
+└── seed/
+    └── ...
+```
+
+`handoff.md` 和 `seed/` 是可选的，不要创建空的可选文件。
+
+## 约束
+
+- `blueprint.json` 不写 Hub 路径和 target 路径，它们属于 CLI 参数。
+- 不覆盖用户文件。
+- 不修改 Kit 源目录。
+- 不直接写 Hub，除非通过 `starwork spawn` 的 registry 登记行为。
+- 不删除 `AGENTS.md`、`.starwork/`、`.core-sync.json`、`_系统/`、`知识/` 或 skill 链接。
+- 除非用户有明确理由，否则优先新增清晰目录，而不是重命名系统目录。
+- Markdown 规则要具体、可执行，避免泛泛的效率建议。
+
+## 最小示例
+
+```json
+{
+  "schema": "starwork.spawn_blueprint.v0.1",
+  "name": "内容产品官网",
+  "project_id": "content-site",
+  "base": {
+    "mode": "matter",
+    "kit": "satellite-matter",
+    "language": "zh"
+  },
+  "paths": {
+    "formal_source": "交付物/确认版本/",
+    "business_work_area": "事项/"
+  },
+  "folders": [
+    "资料库/",
+    "草稿/",
+    "会议纪要/",
+    "版本记录/",
+    "交付物/确认版本/"
+  ],
+  "agent_rules": [
+    {
+      "slot": "project.file_boundaries",
+      "from": "rules/file-boundaries.md"
+    },
+    {
+      "slot": "project.workflow",
+      "from": "rules/workflow.md"
+    }
+  ]
+}
+```
+
+## 执行命令
+
+根据用户机器上的实际路径替换：
+
+```bash
+starwork spawn --hub <hub-path> --target <target-path> --blueprint <blueprint.json> --dry-run
+starwork spawn --hub <hub-path> --target <target-path> --blueprint <blueprint.json> --yes
+starwork doctor --target <target-path>
+```