@jennie-shawn/starwork 0.1.0-alpha.0

package/core/capabilities/local-identity/capability.md

@@ -0,0 +1,15 @@
+# Capability: local-identity v0.1
+
+`local-identity` 把用户、团队或项目身份信息直接存放在当前工作区内。
+
+## 新增
+
+```text
+identity/
+```
+
+## 规则
+
+- 将身份信息视为高稳定性参考材料。
+- 没有用户明确确认，不要改写身份内容。
+- 不要把身份文件当成任务日志或项目状态文件。

package/core/capabilities/local-identity/templates/identity/README.md

@@ -0,0 +1,5 @@
+# Identity
+
+这里放项目本地身份、偏好和长期稳定背景。
+
+除非用户明确要求更新，否则本目录默认只读。

package/core/capabilities/local-lessons/capability.md

@@ -0,0 +1,15 @@
+# Capability: local-lessons v0.1
+
+`local-lessons` 把可复用教训直接存放在当前项目工作区内。
+
+## 新增
+
+```text
+lessons/
+```
+
+## 规则
+
+- 教训必须可复用。
+- 教训应来自真实错误、修正或反复出现的模式。
+- 不要把 lessons 当成普通会议笔记或项目进度流水。

package/core/capabilities/local-lessons/templates/lessons/README.md

@@ -0,0 +1,5 @@
+# Lessons
+
+这里放项目内可复用教训。
+
+真正有用的教训应该能改变未来行为，而不只是总结发生了什么。

package/core/capabilities/main-repo-sync/capability.md

@@ -0,0 +1,133 @@
+# Capability: main-repo-sync v0.1
+
+`main-repo-sync` 描述主库与卫星项目之间的 Hub + Satellite 模型。
+
+它不只是共享身份或共享教训，而是一整套协同模型：
+
+- Hub 是规则源、可复用知识源、项目注册表、skill 来源和消息路由层。
+- Satellites 是具体执行工作区。
+- 初始化时复制稳定快照。
+- 部分资源以只读链接方式挂载。
+- 同步元数据记录在 `.core-sync.json`。
+- 项目发现依赖 Hub 的 registry。
+- 可复用更新通过 inbox / review 流程回写。
+
+## 核心模型
+
+一句话：
+
+> Hub 负责共享、可复用、可审计的公共机制；每个 Satellite 负责自己的项目事实和执行过程。
+
+这意味着 Hub 可以发现、初始化、同步和联络 Satellite，但 Hub 不会变成这些项目的进度数据库。
+
+## Hub 职责
+
+Hub 维护跨项目可复用资源：
+
+- `identity/`
+- `lessons/`
+- `.internal/` 协议
+- `knowledge/` 或语言 profile 映射后的知识入口
+- 共享 skills
+- 项目注册表
+- 跨项目消息路由
+- 可复用内容回写审核队列
+
+Hub 不应该存放项目特定的执行内容。
+
+## Satellite 工作区职责
+
+Satellite 工作区负责具体项目执行：
+
+- 项目状态
+- 当前工作
+- 过程材料
+- 项目正式事实源
+- 项目专属决策和产出
+
+Satellite 可以包含来自主库的快照或链接，但这些资源默认仍然是共享参考层。
+
+## Satellite 必需层
+
+一个由 Hub 管理的 Satellite 通常包含这些固定层：
+
+- `AGENTS.md`
+- `CLAUDE.md`
+- `README.md`
+- `.core-sync.json`
+- 一个可见的主库同步说明，例如 `_系统/主库同步/README.md` 或 `_system/hub-sync/README.md`
+- 主库身份快照，例如 `_系统/身份/`
+- 主库教训快照，例如 `_系统/教训/`
+- `.internal/`
+- `.obsidian/`
+- `知识/` 或 `knowledge/` 作为只读链接
+- `_系统/上下文/当前项目.md` 或 `_system/context/current-projects.md`，作为项目状态事实源
+- `_系统/任务/` 或 `_system/tasks/`
+- `_系统/跨项目/` 或 `_system/cross-project/`
+
+中文卫星项目当前使用 `_系统/上下文/当前项目.md`，中文本地单项目使用 `_系统/上下文/项目状态.md`。两者都是同一个 Core 角色在不同 preset 下的映射，不能同时独立维护。
+
+## 同步语义
+
+| 资源 | 在 Satellite 中的形态 | 默认同步语义 |
+|---|---|---|
+| `identity/` | 复制快照 | 初始化自主库；后续更新需要手动确认。 |
+| `lessons/` | 复制快照 | 初始化自主库；项目特定教训先留在本地，确认可复用后再回写。 |
+| `.internal/` | 复制指定协议文件 | 只同步稳定协议，例如回写协议和合并策略。 |
+| `.obsidian/` | 复制配置 | 提供默认 Obsidian 本地行为。 |
+| `knowledge/` | 只读软链接 | 主库仍然是事实源。 |
+| `.core-sync.json` | 本地元数据 | 记录来源路径、版本、同步时间、挂载资源和 skills。 |
+| shared skills | 软链接 | 不要把共享 skills 复制成项目内独立分叉。 |
+
+## Registry 边界
+
+Hub 的 `项目/registry.json` 存放项目发现与同步元数据：
+
+- 项目 ID
+- 名称
+- 路径
+- 状态
+- 创建日期
+- last_sync 时间
+- Core 版本
+- 同步模式
+- 共享资源
+
+它不能存放项目进度正文。
+
+项目进度留在 Satellite 工作区内，通常位于：
+
+- `_系统/上下文/当前项目.md`
+- `_system/context/current-projects.md`
+- 或 profile 声明的 Core v0.1 项目状态角色文件
+
+## 状态读取顺序
+
+工具和 adapters 应按以下顺序读取项目状态：
+
+1. 工作区规则或 preset 声明的状态文件
+2. `_系统/上下文/当前项目.md`
+3. `_system/context/current-projects.md`
+4. `_系统/上下文/项目状态.md`
+5. `_system/context/project-status.md`
+
+如果多个文件同时存在，工作区规则必须明确唯一事实源。其他文件应作为别名、指针或生成副本，而不是第二份独立维护的状态文件。
+
+## 回写边界
+
+Satellite 工作区中出现的可复用建议，应通过主库审核流程回写，例如 `.incoming/`。
+
+跨项目 handoff 用于项目之间的请求、依赖、通知和交接。它不能替代主库的可复用知识审核队列。
+
+| 机制 | 用途 | 是否改变 Hub 正式内容 |
+|---|---|---:|
+| `.incoming/` | Satellite 向 Hub 提交候选身份、教训、报告或知识更新。 | 只有 Hub 审核后才会改变。 |
+| cross-project handoff | 一个项目向另一个项目发送请求、同步、依赖或回复。 | 不会。 |
+
+## 生命周期
+
+| 状态 | 含义 | Hub 行为 |
+|---|---|---|
+| `active` | 项目正在推进。 | 纳入正常项目发现和状态读取。 |
+| `paused` | 项目有意暂停，但未来可能恢复。 | 保留 registry 记录和项目事实，不把沉默视为异常。 |
+| `archived` | 项目作为历史参考。 | 保留 registry 记录和项目目录；实时汇总时默认跳过。 |

package/core/capabilities/main-repo-sync/templates/.core-sync.example.json

@@ -0,0 +1,31 @@
+{
+  "core_source": "digital-twin-core",
+  "core_source_path": "/Users/shuxinding/digital-twin-core",
+  "core_version": "main@<commit-hash>",
+  "synced_at": "YYYY-MM-DDTHH:mm:ss+08:00",
+  "sync_mode": "bootstrap-copy",
+  "synced_resources": {
+    "identity": {
+      "mode": "snapshot-copy",
+      "path": "identity/"
+    },
+    "lessons": {
+      "mode": "snapshot-copy",
+      "path": "lessons/"
+    },
+    "internal_protocols": {
+      "mode": "selected-copy",
+      "path": ".internal/"
+    },
+    "obsidian": {
+      "mode": "config-copy",
+      "path": ".obsidian/"
+    },
+    "knowledge": {
+      "mode": "symlink-readonly",
+      "source": "/Users/shuxinding/digital-twin-core/knowledge",
+      "mount_path": "knowledge/"
+    }
+  },
+  "skills": []
+}

package/core/capabilities/main-repo-sync/templates/.internal/README.md

@@ -0,0 +1,5 @@
+# Internal Protocols
+
+This directory contains selected protocol snapshots copied from the main repository.
+
+It is not a project workspace. Do not put project drafts, task notes, or outputs here.

package/core/capabilities/matter-mode/capability.md

@@ -0,0 +1,46 @@
+# Capability: matter-mode v0.1
+
+Matter Mode 是用于长期工作追踪的模式。
+
+## 新增
+
+中文 profile 默认映射为：
+
+```text
+事项/注册表.md
+事项/<matter-id>/
+```
+
+英文 profile 可映射为 `matters/registry.md` 和 `matters/<matter-id>/`。
+
+## 事项结构
+
+中文 profile 默认结构为：
+
+```text
+事项/<matter-id>/
+├── README.md
+├── 进度.md
+├── 笔记.md
+├── 草稿/
+└── 交接.md
+```
+
+## 规则
+
+- 事项注册表是索引，不是进度日志。
+- 单个 matter 目录是过程工作区，不是最终事实源。
+- 成熟草稿必须晋升到项目正式事实源。
+- 创建、暂停和归档 matter 应由事项维护规则或 skill 处理。
+
+## Skill 要求
+
+Matter Mode 应配套 `matter-workspace` 使用。
+
+在当前主库中，参考 skill 位于：
+
+```text
+/Users/shuxinding/digital-twin-core/skills/matter-workspace/
+```
+
+当 CLI 支持 Matter Mode 时，应安装或软链接该 skill，而不是复制成一个独立分叉。

package/core/capabilities/matter-mode/templates/matters/_matter-template/README.md

@@ -0,0 +1,17 @@
+# 事项标题
+
+## 目标
+
+待填写。
+
+## 范围
+
+待填写。
+
+## 不在范围内
+
+待填写。
+
+## 正式事实源晋升目标
+
+待填写。

package/core/capabilities/matter-mode/templates/matters/_matter-template/drafts/.gitkeep

@@ -0,0 +1 @@
+

package/core/capabilities/matter-mode/templates/matters/_matter-template/handoff.md

@@ -0,0 +1,3 @@
+# Handoff
+
+这里记录跨 Agent 或跨项目交接说明。

package/core/capabilities/matter-mode/templates/matters/_matter-template/notes.md

@@ -0,0 +1,5 @@
+# Notes
+
+这里记录讨论笔记、调研笔记和过程判断。
+
+不要把它当成正式事实源。

package/core/capabilities/matter-mode/templates/matters/_matter-template/progress.md

@@ -0,0 +1,5 @@
+# Progress
+
+- Created: 待填写
+- Status: active
+- Next step: 待填写

package/core/capabilities/matter-mode/templates/matters/registry.md

@@ -0,0 +1,16 @@
+# Matters Registry
+
+## Active
+
+| matter_id | status | codex_thread_id | path | updated |
+|---|---|---|---|---|
+
+## Paused
+
+| matter_id | status | codex_thread_id | path | updated |
+|---|---|---|---|---|
+
+## Archived
+
+| matter_id | status | codex_thread_id | path | archived_at |
+|---|---|---|---|---|

package/core/capabilities/skill-mount/capability.md

@@ -0,0 +1,24 @@
+# Capability: skill-mount v0.1
+
+`skill-mount` 描述主库共享 skills 如何提供给卫星项目使用。
+
+## 规则
+
+共享 skills 应通过软链接挂载，而不是复制成项目内独立分叉。
+
+典型挂载方式：
+
+```text
+.agents/skills/<skill-name> -> /path/to/main-repo/skills/<skill-name>
+.claude/skills/<skill-name> -> /path/to/main-repo/skills/<skill-name>
+```
+
+## 边界
+
+- 共享 skills 仍然由主库拥有。
+- 项目专用 skill 修改必须放在项目专用 skill 路径中。
+- 卫星项目不能把软链接的共享 skill 当成本地项目代码来改。
+
+## CLI 职责
+
+CLI 应通过创建软链接安装共享 skills，并把挂载信息记录到 `.core-sync.json`。

package/core/capabilities/starter-outputs/capability.md

@@ -0,0 +1,25 @@
+# Capability: starter-outputs v0.1
+
+Starter Outputs 是面向不使用 Matter Mode 用户的轻量工作模式。
+
+## 新增
+
+```text
+references/
+outputs/drafts/
+outputs/final/
+```
+
+## 规则
+
+- `references/` 存放原始资料，默认只读。
+- `outputs/drafts/` 存放等待审阅的 AI 草稿。
+- `outputs/final/` 存放用户确认后的成果。
+- 这个能力不要求存在 `matters/`。
+
+## 适合场景
+
+- 学员入门模板
+- 小型项目
+- 单次会话交付
+- 更喜欢简单文件夹、不想使用事项追踪的用户

package/core/capabilities/starter-outputs/templates/outputs/drafts/README.md

@@ -0,0 +1,5 @@
+# Drafts
+
+这里放用户确认前的 AI 生成草稿。
+
+草稿不是正式事实源。

package/core/capabilities/starter-outputs/templates/outputs/final/README.md

@@ -0,0 +1,5 @@
+# Final Outputs
+
+这里放用户确认后的成果。
+
+项目可以选择其他正式事实源；但在 Starter Mode 中，本目录是默认确认成果位置。

package/core/capabilities/starter-outputs/templates/references/README.md

@@ -0,0 +1,5 @@
+# References
+
+这里放原始资料。
+
+本目录默认只读。除非用户明确要求，不要改写原始资料。

package/core/core-v0.1-protocol.md

@@ -0,0 +1,201 @@
+# StarWork Core v0.1 协议总览
+
+本文是 StarWork Core v0.1 的第一阅读入口。
+
+如果只读一篇文档，先读这篇。它解释 Core 是什么、不是什么、最小工作区需要什么、可选能力如何组合，以及 Core 与 CLI、Kit、Pack、Adapter 的边界。
+
+## 一句话定义
+
+StarWork Core 是一个开源的 AI 工作区协议。
+
+它定义人和 AI Agent 如何在同一个项目工作区里长期协作：开始前读什么、当前工作写哪里、项目状态放哪里、过程材料和正式成果如何分开、哪些内容默认只读、哪些动作需要用户确认。
+
+Core 不负责把这些协议自动生成出来。稳定生成、检查和升级工作区，是 StarWork CLI 的职责。
+
+## Core 不是什么
+
+Core 不是一个文件夹模板集合。
+
+文件夹只是协议的可见载体。真正重要的是每个文件和目录背后的角色、边界和维护规则。
+
+Core 也不是 CLI。
+
+Core 说明什么是对的；CLI 负责把它稳定创建出来、检查出来、迁移出来。
+
+Core 也不是 Pack。
+
+Pack 是某个具体场景的工作流包，例如自媒体内容创作者 Pack。Core 只提供所有场景都能共用的工作区地基。
+
+Core 也不是 Agent Runtime。
+
+Core 不替代 Claude Code、Codex、Cursor、Trae 等底层 Agent。它让这些 Agent 进入同一个长期工作系统。
+
+## 最小工作区
+
+一个 Core v0.1 工作区至少需要三个角色：
+
+| 角色 | 解决什么问题 |
+|---|---|
+| `agent.entry_rules` | Agent 进来之后先读什么规则。 |
+| `system.context.project_status` | 项目目标、阶段、重点、风险、正式事实源在哪里。 |
+| `system.tasks.current_work` | 当前正在推进什么，下一次 Agent 从哪里接上。 |
+
+注意：这些是角色，不是强制文件名。
+
+中文工作区可以把它们映射成：
+
+```text
+AGENTS.md
+_系统/上下文/项目状态.md
+_系统/任务/当前工作.md
+```
+
+在当前主库 + 卫星项目模式下，为兼容已有机制，项目状态也可能映射成：
+
+```text
+_系统/上下文/当前项目.md
+```
+
+关键规则是：一个工作区只能有一个项目状态事实源。不能同时维护两份互相独立的状态文件。
+
+## 正式事实源
+
+每个 Core 工作区都必须声明正式事实源在哪里。
+
+正式事实源是项目最终承认的内容位置。它可能叫：
+
+- `product/`
+- `outputs/final/`
+- `docs/`
+- 其他项目自己声明的目录
+
+Core 不强制正式事实源必须叫 `product/`。
+
+过程材料不能被悄悄当成正式事实源。比如 matter 草稿、会议笔记、AI 草稿，都必须经过用户确认或明确晋升，才能进入正式事实源。
+
+## v0.1 可选能力
+
+Core v0.1 把额外功能做成 capabilities。能力可以组合，但不能改变最小工作区角色的含义。
+
+| 能力 | 作用 |
+|---|---|
+| `starter-outputs` | 提供 `references/`、`outputs/drafts/`、`outputs/final/` 的轻量工作流。 |
+| `matter-mode` | 提供事项机制，适合长期项目和跨会话接力；具体路径由语言 profile 决定。 |
+| `decisions` | 提供高影响决策记录，不记录普通会议流水；具体文件名由语言 profile 决定。 |
+| `local-identity` | 在项目内维护本地身份信息。 |
+| `local-lessons` | 在项目内维护本地可复用教训。 |
+| `main-repo-sync` | 支持主库 + 多个卫星项目的 Hub + Satellite 模型。 |
+| `skill-mount` | 通过软链接挂载主库共享 skills。 |
+
+## 五种首批形态
+
+v0.1 先保留五种工作区形态。Kit 名称不携带语言标签；当前正式 Kit 默认以中文 profile 落地，其他语言通过 profile 扩展。
+
+| Preset | 面向谁 | 默认特点 |
+|---|---|---|
+| `local-starter` | 学员、轻量单项目用户 | 本地身份/教训，轻量输入输出工作流，不启用事项。 |
+| `local-matter` | 单项目长期用户 | 本地身份/教训，启用 Matter Mode 和高影响决策。 |
+| `satellite-starter` | 接入主库的轻量卫星项目 | 主库分发身份、教训、知识、skills；卫星项目不默认启用事项。 |
+| `satellite-matter` | 主库 + 多卫星项目用户 | 主库分发身份、教训、知识、skills；卫星项目维护自己的事项和正式事实源。 |
+| `hub` | 多项目管理中枢用户 | 统一维护身份、教训、知识、skills、项目注册表和跨项目联络。 |
+
+Preset 是配方，不是协议本身。它选择 profile、capabilities 和默认正式事实源。
+
+## Kit 的定位
+
+Kit 是 preset 组装出来的可复制模板包。
+
+Kit 可以手工维护，也可以由 CLI 生成。它不是 Core 协议事实源。
+
+事实源关系是：
+
+```text
+baseline + profiles + capabilities + presets -> kit
+```
+
+当前 v0.1 的 kit 可作为参考实现，帮助人和 Agent 理解协议落地后的样子。
+
+未来稳定生成 kit，应由 CLI 控制，而不是要求普通用户靠阅读协议手工无误生成。
+
+## Core 与 CLI 的边界
+
+Core 负责定义协议：
+
+- 角色含义
+- 文件边界
+- 可选能力
+- 兼容规则
+- 哪些内容默认只读
+- 哪些动作需要确认
+
+CLI 负责执行协议：
+
+- `starwork init`：根据 preset 初始化工作区。
+- `starwork doctor`：检查工作区是否符合 Core。
+- `starwork adapt`：生成或更新 Agent 适配文件。
+- `starwork pack install`：安装场景 Pack。
+
+一句话：
+
+> Core 定义什么是对的；CLI 保证稳定造出来。
+
+## 单项目与多项目
+
+Core 支持单项目工作区，也支持主库 + 多卫星项目。
+
+单项目工作区中，身份、教训、项目状态和产物都可以在项目内维护。
+
+多项目工作区中，采用 Hub + Satellite 模型：
+
+- Hub 维护跨项目共享身份、教训、知识、skills、项目注册表、跨项目联络和回写审核。
+- Satellite 维护自己的项目状态、当前工作、事项过程、项目决策和正式事实源。
+
+Hub 可以读取 Satellite 的项目状态，但不能把项目进度正文复制进 registry。
+
+Satellite 也不能把主库快照、共享知识或软链接 skills 当成本地内容随意改写。
+
+## 事项机制
+
+Matter Mode 是增强能力，不是所有用户必需能力。
+
+学员或轻量用户可以只使用 `references/outputs`。
+
+长期项目、跨会话接力、复杂推进过程更适合使用事项机制。中文 Kit 使用 `事项/`，英文 Kit 可使用 `matters/`。
+
+启用 Matter Mode 时，应配套事项维护规则或 skill。否则目录存在了，但创建、更新、暂停、归档的动作仍然容易混乱。
+
+## 决策记录
+
+决策记录是可选能力，不是必需文件。中文 Kit 使用 `_系统/上下文/决策.md`，英文 Kit 可使用 `decisions.md`。
+
+它只记录高影响、已确认、会影响未来多个工作动作的决策。
+
+它不记录：
+
+- 普通会议纪要
+- 单个草稿的临时选择
+- 每日任务流水
+- 尚未确认的讨论过程
+
+## v0.1 封版标准
+
+Core v0.1 可以封版，至少需要满足：
+
+- 普通人能读懂 Core 是什么、不是什么。
+- Agent 能知道开始前读哪里、当前工作写哪里、正式事实源在哪里。
+- 五种首批工作区形态边界清楚。
+- 单项目和多项目不互相污染。
+- Matter Mode 是可选增强，不强迫所有用户使用。
+- Kit 被定位为参考实现或 CLI 输出，不被误认为协议事实源。
+- CLI 的职责被清楚留出，但不在 Core 中实现。
+
+## 后续进入 CLI 前要确认
+
+进入 CLI v0.1 前，需要确认：
+
+- `starwork init` 首批支持哪些 preset。
+- `starwork doctor` 检查哪些 Core 健康项。
+- `starwork adapt` 首先适配哪些 Agent。
+- `starwork pack install content-creator` 与 Core 的边界在哪里。
+
+这些问题属于 CLI 设计，不属于 Core 协议本体。

package/core/kits/README.md

@@ -0,0 +1,15 @@
+# Core Kits
+
+Kits 是由 presets 组装出来、可供用户复制使用的工作区模板包。
+
+它们不是协议事实源。事实源是：
+
+```text
+baseline/ + profiles/ + capabilities/ + presets/
+```
+
+在 v0.1 阶段，kits 可以手工组装。后续 `starwork init` 应根据 presets 生成 kits。
+
+## 结构参考
+
+- [Kit Structure Reference](./kit-structure-reference.md)

package/core/kits/hub/.incoming/README.md

@@ -0,0 +1,5 @@
+# Incoming
+
+这里存放等待审核的共享内容候选。
+
+候选内容确认后，才能进入正式身份、教训、知识或 skills。

package/core/kits/hub/AGENTS.md

@@ -0,0 +1,26 @@
+# StarWork 多项目中枢规则
+
+## 开始前先读
+
+1. `_系统/上下文/项目状态.md`
+2. `_系统/任务/当前工作.md`
+3. `项目/registry.json`
+
+## 中枢职责
+
+- 维护跨项目共享身份、教训、知识和 skills。
+- 维护项目注册表和跨项目联络机制。
+- 审核候选回写内容。
+
+## 写入边界
+
+- 项目注册信息写入 `项目/registry.json`。
+- 跨项目联络写入 `项目/联络/`。
+- 候选共享内容先写入 `.incoming/`。
+- 具体项目的进度正文留在各自项目内，不复制进中枢。
+
+## 需要确认
+
+- 修改身份、教训、共享知识或正式 skill。
+- 合并 `.incoming/` 中的候选内容。
+- 创建、暂停或归档项目注册。

package/core/kits/hub/README.md

@@ -0,0 +1,25 @@
+# 多项目管理中枢 Kit
+
+Preset: `hub`
+
+适合希望建立主库 / 中枢的用户。
+
+## 包含
+
+- `AGENTS.md`
+- `_系统/上下文/项目状态.md`
+- `_系统/任务/当前工作.md`
+- `identity/`
+- `lessons/`
+- `知识/`
+- `skills/`
+- `项目/`
+- `.incoming/`
+
+## 不包含
+
+- 业务项目的正式事实源
+- 卫星项目初始化
+- 自媒体、产品经理等业务 Pack
+
+卫星项目创建应由后续专门命令完成。