@jennie-shawn/starwork 0.1.0-alpha.0

package/packs/pack-structure-spec.md

@@ -0,0 +1,315 @@
+# StarWork Pack Structure SPEC
+
+## 状态
+
+- 版本：v0.1 draft
+- 所属模块：StarWork Packs
+- 目标：定义 Pack 源包的结构、声明方式、多语言镜像和 CLI 组装方式
+- 相关命令：`starwork init`、`starwork pack install`
+
+## 一句话定义
+
+Pack 是 StarWork 的场景定制模板。
+
+它不直接等于一套中文目录，也不直接等于一套英文目录。Pack 的核心是“业务角色和业务流”，语言层再决定这些角色在用户工作区里叫什么、规则怎么写、模板用哪种语言。
+
+## 核心判断
+
+Pack 应拆成两层：
+
+```text
+pack.json
+  语言无关：Pack ID、适配工作区、业务角色、业务流、规则插槽、模板 ID、seed ID
+
+languages/<language>.json
+  语言相关：显示名称、目录路径、默认覆盖、规则文件、模板文件、seed 文件
+```
+
+这样同一个 Pack 可以生成中文工作台，也可以生成英文镜像，而不需要维护两套互相漂移的 Pack。
+
+## 推荐目录结构
+
+```text
+content-creator/
+├── pack.json
+├── README.md
+├── languages/
+│   ├── zh.json
+│   └── en.json
+├── rules/
+│   ├── zh/
+│   │   ├── overview.md
+│   │   ├── workflow.md
+│   │   ├── file-boundaries.md
+│   │   └── review.md
+│   └── en/
+│       ├── overview.md
+│       ├── workflow.md
+│       ├── file-boundaries.md
+│       └── review.md
+├── templates/
+│   ├── zh/
+│   │   ├── content-brief.md
+│   │   ├── publish-record.md
+│   │   └── weekly-review.md
+│   └── en/
+│       ├── content-brief.md
+│       ├── publish-record.md
+│       └── weekly-review.md
+└── seed/
+    ├── zh/
+    │   ├── 账号定位/
+    │   └── 选题池/
+    └── en/
+        ├── account-profile/
+        └── ideas/
+```
+
+## `pack.json`
+
+`pack.json` 是 Pack 的语言无关声明。
+
+它回答：
+
+- Pack ID 是什么
+- 适配哪些工作区类型
+- 需要哪些 Core capability
+- 有哪些业务角色
+- 业务流如何从一个角色流向另一个角色
+- 有哪些规则插槽
+- 有哪些模板 ID
+- 有哪些 seed ID
+
+示例：
+
+```json
+{
+  "schema": "starwork.pack.v0.1",
+  "id": "content-creator",
+  "version": "0.1.0",
+  "compatible_core": "0.1",
+  "supports_workspace_types": ["single-light", "single-matter"],
+  "requires_capabilities": [],
+  "roles": {
+    "account_profile": { "kind": "strategy" },
+    "ideas": { "kind": "pipeline" },
+    "materials": { "kind": "source" },
+    "drafts": { "kind": "work_in_progress" },
+    "published": { "kind": "formal_source" },
+    "review": { "kind": "learning_loop" }
+  },
+  "flow": ["account_profile", "ideas", "materials", "drafts", "published", "review"],
+  "rules": [
+    { "id": "overview", "slot": "pack.overview" },
+    { "id": "workflow", "slot": "pack.workflow" }
+  ],
+  "templates": [
+    { "id": "content-brief" },
+    { "id": "publish-record" }
+  ],
+  "seed": [
+    { "id": "ideas", "role": "ideas" }
+  ]
+}
+```
+
+注意：`pack.json` 不写 `选题池/`、`ideas/` 这类具体路径。路径属于语言层。
+
+## `languages/<language>.json`
+
+语言文件决定 Pack 在某种语言镜像下如何落地。
+
+它回答：
+
+- 给用户看的 Pack 名称是什么
+- 每个业务角色映射到哪个目录
+- 默认正式事实源在哪里
+- 默认业务工作区在哪里
+- 规则片段读取哪些 Markdown
+- 模板读取哪些 Markdown
+- seed 文件写到哪里
+
+中文示例：
+
+```json
+{
+  "language": "zh",
+  "name": "自媒体内容创作者 Pack",
+  "paths": {
+    "ideas": "选题池/",
+    "materials": "素材库/",
+    "drafts": "草稿与脚本/",
+    "published": "发布记录/"
+  },
+  "overrides": {
+    "formal_source": "发布记录/",
+    "business_work_area": "草稿与脚本/"
+  },
+  "rules": [
+    { "slot": "pack.overview", "from": "rules/zh/overview.md" }
+  ],
+  "templates": [
+    { "id": "content-brief", "from": "templates/zh/content-brief.md", "description": "单篇内容大纲模板" }
+  ],
+  "seed": [
+    { "from": "seed/zh/选题池/README.md", "to": "选题池/README.md", "on_conflict": "create_new" }
+  ]
+}
+```
+
+英文示例：
+
+```json
+{
+  "language": "en",
+  "name": "Content Creator Pack",
+  "paths": {
+    "ideas": "ideas/",
+    "materials": "materials/",
+    "drafts": "drafts-and-scripts/",
+    "published": "published/"
+  },
+  "overrides": {
+    "formal_source": "published/",
+    "business_work_area": "drafts-and-scripts/"
+  }
+}
+```
+
+## 组装流程
+
+CLI 安装 Pack 时，应按以下顺序执行：
+
+1. 读取 Kit / preset，确定工作区类型和语言。
+2. 读取 Pack `pack.json`。
+3. 读取 Pack `languages/<language>.json`。
+4. 合并得到本次安装用的 Pack 配置。
+5. 校验 Core 版本、工作区类型和 capabilities。
+6. 用语言层 `paths` 创建场景目录。
+7. 用语言层 `rules` 渲染 Markdown 片段，并注入 Agent 入口文件。
+8. 用语言层 `seed` 生成占位文件写入计划。
+9. 用语言层 `templates` 登记或复制业务模板。
+10. 展示预览。
+11. 用户确认后写入。
+12. 更新 `.starwork/workspace.json`。
+
+当前 v0.1 实现仍是简单组装器：直接复制现成 Kit 目录，再把 Pack 规则追加到 `AGENTS.md` 的“场景规则”部分。
+
+## 占位符
+
+规则片段、模板和 seed 文件可以使用占位符。
+
+建议支持：
+
+```text
+{{pack.id}}
+{{pack.name}}
+{{pack.language}}
+{{paths.<key>}}
+{{overrides.formal_source}}
+{{overrides.business_work_area}}
+{{workspace.name}}
+{{workspace.type}}
+```
+
+v0.1 不支持复杂条件语法、循环语法和脚本执行。
+
+## 写入安全
+
+Pack 安装必须遵守 StarWork 的安全写入原则：
+
+- 不静默覆盖用户已有内容
+- 不删除用户文件
+- 不移动用户文件
+- 不改写已确认事项记录
+- 不改写已确认决策记录
+- 冲突时生成旁路文件或提示用户手动合并
+
+Pack 可以创建新目录、新模板、新 seed 文件，也可以更新 CLI 状态文件。
+
+## Pack 可以覆盖什么
+
+Pack 可以覆盖 Kit 预留的场景配置：
+
+- `formal_source`
+- `business_work_area`
+- 场景默认目录
+- 场景规则片段
+- 场景模板清单
+- 初始化后的推荐下一步
+
+Pack 不能覆盖 Core 基础角色：
+
+- Agent 入口角色
+- 项目状态索引角色
+- 当前工作索引角色
+- 事项注册表角色
+- 决策记录角色
+
+一句话：
+
+```text
+Pack 可以改变业务怎么流动，但不能拆掉工作区的仪表盘。
+```
+
+## CLI 内部状态
+
+Pack 安装后，应写入 `.starwork/workspace.json`。
+
+示例：
+
+```json
+{
+  "schema": "starwork.workspace.v0.1",
+  "core": "0.1",
+  "workspace_type": "single-matter",
+  "kit": "local-matter",
+  "packs": [
+    {
+      "id": "content-creator",
+      "version": "0.1.0",
+      "installed_at": "2026-05-12"
+    }
+  ],
+  "language": "zh",
+  "paths": {
+    "formal_source": "发布记录/",
+    "business_work_area": "草稿与脚本/"
+  }
+}
+```
+
+`.starwork/workspace.json` 是 CLI 状态，不是项目事实源。
+
+## v0.1 实现状态
+
+当前第一版实现已补齐：
+
+1. `general` 默认 Pack。
+2. `content-creator` 场景 Pack。
+3. `hub-management` 管理 Pack。
+4. `languages/zh.json` 和 `languages/en.json` 多语言结构。
+5. CLI 根据语言文件读取 Pack 路径、规则、模板和 seed。
+6. CLI 的简单占位符渲染器。
+7. CLI 的写入计划、dry-run 预览和冲突旁路文件机制。
+
+后续仍需要补齐：
+
+1. `starwork.pack.v0.1` JSON Schema 文件。
+2. Kit 侧更正式的规则插槽设计。
+3. Pack 校验命令。
+4. 多 Pack 安装时的冲突策略。
+5. 真正根据英文 Kit 自动选择英文 Pack 镜像的完整 init 入口。
+
+## 验收标准
+
+Pack 结构 v0.1 可验收，至少满足：
+
+- Pack 可以用 `pack.json` 描述语言无关的业务角色和业务流。
+- Pack 可以用 `languages/<language>.json` 描述不同语言下的路径、规则、模板和 seed。
+- Pack 不需要直接提供完整 `AGENTS.md`。
+- CLI 可以把 Kit 和 Pack 规则片段组装成最终 Agent 入口文件。
+- Pack 可以覆盖正式成果路径和业务工作区路径。
+- Pack 不能破坏 Core 基础角色。
+- 通用工作也能表达为默认 Pack。
+- 自媒体内容创作者 Pack 可以按此结构落地。

package/schemas/README.md

@@ -0,0 +1,3 @@
+# Schemas
+
+这里存放 StarWork Core、Pack、CLI 使用的结构化 schema。

package/skills/README.md

@@ -0,0 +1,17 @@
+# StarWork Skills
+
+这里存放 StarWork 自研 Agent skill。
+
+Skill 的职责不是替代 CLI，而是帮助 Agent 更可靠地理解用户意图、生成配置、组织规则和调用 StarWork 工具。
+
+## 路由规则
+
+- 与 Core 协议相关的事实源放在 `product/core/`。
+- 与 CLI 命令相关的规格和实现放在 `product/cli/`。
+- 与 Pack 场景相关的正式包放在 `product/packs/`。
+- 与 Agent 工作流相关、可被复用为 skill 的内容放在 `product/skills/`。
+
+## 当前 Skills
+
+- `starworkSpawn/`：帮助 Agent 设计 `starwork spawn --blueprint` 工作台定制单。
+- `starworkInit/`：帮助 Agent 设计 `starwork init` 初始化方案和 init blueprint。详细 SPEC 见 `starworkInit-spec.md`。

package/skills/starworkInit/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: starworkInit
+description: Use this skill when a user wants to initialize a new StarWork workspace, choose between single-light, single-matter, and hub workspace types, decide whether matters or Packs are needed, design friendly init interview flows, draft init blueprints, and explain how `starwork init` should execute and validate the result.
+---
+
+# starworkInit
+
+使用这个 skill，把用户“我想建一个工作台”的模糊需求，整理成 StarWork 初始化方案。
+
+`starworkInit` 不是 `starwork init` 命令本身。它负责在命令执行前帮用户判断：
+
+- 应该建单项目工作台，还是多项目中枢
+- 是否需要事项机制
+- 是否需要 Pack
+- 是否需要定制目录和 Agent 规则
+- 最终应该如何执行和检查
+
+除非用户明确要求落地文件，否则这个 skill 只负责设计方案，不直接创建工作台。
+
+## 参考
+
+需要完整字段、边界和待确认问题时，读取：
+
+```text
+../starworkInit-spec.md
+```
+
+不要在 skill 内重复维护完整 schema，避免和 SPEC 漂移。
+
+## 决策流程
+
+按分支判断，不要一次问完所有问题。
+
+```text
+Step 1 判断工作台类型
+  ├─ hub：跳过 Step 2 / Step 3，直接给 Hub 初始化建议
+  └─ single：继续判断事项
+
+Step 2 判断是否需要事项
+  ├─ 需要：single-matter
+  └─ 不需要：single-light
+
+Step 3 判断 Pack
+  ├─ general：可继续判断是否定制
+  └─ 其他现成 Pack：只安装现成 Pack，暂不深度定制
+
+Step 4 判断是否需要定制工作台
+  ├─ 不需要：输出标准初始化建议
+  └─ 需要：进入友好采访
+
+Step 5 采访正式成果放哪里
+Step 6 采访日常工作在哪里发生
+Step 7 采访额外固定区域和 Agent 规则
+```
+
+## Step 1：判断工作台类型
+
+先问：
+
+```text
+你是想管理一个具体项目，还是建立一个能管理多个项目的中枢？
+```
+
+判断：
+
+- 一个具体项目、轻量资料和成果：`single-light`
+- 一个长期项目、跨会话推进、需要追踪：`single-matter`
+- 管理多个项目、统一身份/教训/知识/skills：`hub`
+
+如果用户只是说“以后可能会有很多项目”，但当前只有一个项目，优先建议 `single-matter`。只有用户明确要建立多项目中枢时，才推荐 `hub`。
+
+### Hub 分支
+
+如果判断为 `hub`，不要继续问“是否需要事项”和“选哪个 Pack”。
+
+直接输出 Hub 初始化建议：
+
+- 工作区类型：`hub`
+- 基础 Kit：`hub`
+- Pack：不让用户选择；Hub 使用中枢管理结构
+- 事项：不是 Hub 初始化必选项
+- 后续确认：Hub 名称、项目注册区域、是否预置 `skills/` 和 `.incoming/`
+
+## Step 2：判断是否需要事项
+
+仅当 Step 1 是单项目时才问：
+
+```text
+这个工作会不会持续数周以上，或者需要多次接力？
+```
+
+判断：
+
+- 需要长期推进、复盘、交接：`single-matter`
+- 只是放资料、写草稿、收成果：`single-light`
+- 用户改口说要管理多个项目：回到 Step 1，改为 `hub`
+
+## Step 3：判断 Pack
+
+仅当不是 Hub 时才问：
+
+```text
+这个工作台主要用于什么场景？
+```
+
+判断：
+
+- 泛用资料、草稿、项目推进：`general`
+- 内容创作、自媒体、发布复盘：`content-creator`
+- 其他场景：先说明 v0.1 没有专门 Pack，默认用 `general`
+
+约束：
+
+- 通用工作也是 Pack：`general`
+- Hub 不在 init 里选择 Pack
+- 不把一次性目录偏好误判成新 Pack
+- v0.1 只支持基于 `general` Pack 做定制修改
+- 用户选择 `content-creator` 时，可以安装现成 Pack，但不进入自定义 Pack 结构采访
+
+## Step 4：判断是否定制
+
+在问正式成果、当前工作区、额外目录之前，先问：
+
+```text
+你想先用标准结构，还是希望我帮你按自己的工作习惯稍微改一下目录和规则？
+```
+
+判断：
+
+- 标准结构就行：输出标准 Kit + Pack 初始化建议
+- 想改一下：进入 Step 5-7
+- 不确定：给 2-3 个例子帮用户判断
+
+解释时可以说：
+
+```text
+标准结构像直接入住酒店；定制结构像把书桌、收纳盒和常用文件夹按你的习惯摆好。
+如果你还没形成稳定习惯，先用标准结构更省心。
+```
+
+## Step 5-7：友好采访
+
+采访要像聊天，不要像配置表。
+
+### 正式成果
+
+问：
+
+```text
+等这个工作台用一段时间后，你最希望未来的自己回来翻到什么？
+是最终交付物、发布记录、客户确认版，还是项目清单？
+```
+
+常见映射：
+
+- 最终成果、交付物、确认版本：`输出/确认成果/`
+- 已发布内容、发布记录：`发布记录/`
+- 项目清单、项目注册：`项目/`
+
+如果用户答不上来，默认用 `输出/确认成果/`。
+
+### 日常工作区
+
+问：
+
+```text
+你平时会在哪里“干活”？
+比如写草稿、放参考资料、记录推进过程、整理待办和阶段判断。
+```
+
+常见映射：
+
+- 事项推进：`事项/`
+- 轻量资料整理：`参考资料/`
+- 内容草稿推进：`草稿与脚本/` 或 `事项/`
+
+默认：
+
+- `single-light`：`参考资料/`
+- `single-matter`：`事项/`
+
+### 额外目录和规则
+
+问：
+
+```text
+有没有一些东西你每次都想单独放，不想和别的文件混在一起？
+比如会议纪要、客户沟通、版本记录、素材库、复盘。
+```
+
+只新增未来确实会反复使用的目录。避免含义重叠、只为好看、或与 Pack 已有目录重复的目录。
+
+至少考虑两类规则：
+
+- `rules/file-boundaries.md`：不同信息放哪里
+- `rules/workflow.md`：Agent 如何推进工作
+
+规则要具体、可执行，避免泛泛的效率建议。
+
+## 输出方式
+
+用户还在讨论时，输出初始化建议：
+
+```markdown
+## 初始化建议
+
+- 工作区类型：
+- Kit：
+- Pack：
+- 正式成果：
+- 当前工作区：
+- 额外目录：
+- 需要注入的规则：
+
+## 为什么这样选
+
+...
+
+## 后续执行
+
+...
+```
+
+用户要求生成定制单时，创建：
+
+```text
+<workspace>-init/
+├── init-blueprint.json
+├── rules/
+│   ├── file-boundaries.md
+│   └── workflow.md
+└── seed/
+    └── ...
+```
+
+不要创建空的可选目录或文件。
+
+## 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"
+    }
+  ]
+}
+```
+
+## 执行命令
+
+当前 CLI 尚未实现 `init --blueprint` 时，要诚实说明这是目标命令形态。
+
+未来执行方式：
+
+```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>
+```
+
+## 约束
+
+- 不用 init 创建卫星项目；已有 Hub 下创建项目应转向 `starworkSpawn`。
+- 不建议用户修改 `product/core/kits/`。
+- 不让 blueprint 决定真实 target 路径，目标路径必须来自命令参数或用户明确指定。
+- 不把一次性偏好做成 Pack。
+- 不覆盖用户已有文件。
+- 一次只问一个问题；用户说不清时，用默认值推进并复述判断。

package/skills/starworkInit/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "StarWork Init"
+  short_description: "设计 StarWork 初始化方案"
+  default_prompt: "Use $starworkInit to design a friendly StarWork init plan for a new workspace."
+
+policy:
+  allow_implicit_invocation: true