@jennie-shawn/starwork 0.1.0-alpha.2 → 0.1.0-alpha.20

package/README.md

@@ -1,152 +1,218 @@
 # StarWork
 
-StarWork is an AI workspace protocol and toolkit for keeping long-running work organized across agents, projects, and sessions.
+StarWork 是一套面向 AI 的工作台协议和工具集，用来帮助用户把长期工作、跨会话协作、多项目管理和 AI 工作流组织清楚。
 
-It provides:
+它包含四个核心部分：
 
-- **Core**: workspace structures, roles, health checks, and project-state conventions.
-- **CLI**: commands for creating, checking, adapting, extending, and spawning workspaces.
-- **Packs**: scenario templates for common workflows.
-- **Skills**: Agent workflows that help Codex and other agents design StarWork workspaces.
+- **Core**：定义工作台应该长什么样，包括目录结构、角色边界、状态文件和健康检查规则。
+- **CLI**：提供 `init`、`doctor`、`knowledge`、`spawn`、`upgrade`、`adapt`、`pack install`、`multiagent` 等命令，用来创建、检查、升级、协作和扩展工作台。
+- **Packs**：场景模板包。当前 A 测阶段默认使用通用工作能力。
+- **Skills**：给 Codex 等 AI 工具使用的工作流说明，让 AI 能更可靠地帮用户设计和生成 StarWork 工作台。
 
-StarWork is currently in early A-test. The current package is intended for installation testing, workflow validation, and product feedback.
+当前版本处于 A 测阶段。npm `latest` 为 `@jennie-shawn/starwork@0.1.0-alpha.20`，适合测试安装流程、基础命令、工作台结构、AI Skill 使用体验和 MultiAgent 会话协作链路。
 
-## Install
+## 安装 CLI
 
-Install the CLI globally:
+全局安装：
 
 ```bash
 npm install -g @jennie-shawn/starwork
+starwork --version
 starwork --help
 ```
 
-Or run it without global installation:
+不全局安装，直接运行：
 
 ```bash
+npx @jennie-shawn/starwork --version
 npx @jennie-shawn/starwork --help
 ```
 
-## Install Skills
+## 安装 Skills
 
-StarWork skills are distributed through the `skills` CLI from the GitHub repository.
+StarWork skills 分两类管理：
 
-Install all StarWork skills for Codex:
+- 系统 Skill 通过 GitHub 仓库和 `skills` CLI 安装到 AI 工具的全局环境。
+- 工作台自带 Skill 跟着工作台走，例如项目中心自带 `starworkSpawn`，项目工作台自带 `neat-freak`。
+
+给 Codex 安装全部 StarWork 系统级 Skills：
 
 ```bash
-npx skills add jennie-shawn/starwork --skill '*' -g -a codex -y
+npx skills add jennie-shawn/StarWork -g -a codex -y
 ```
 
-Install individual skills:
+上面这条命令只安装 StarWork 系统级 Skills。当前默认面向 Codex；如果你使用其他 AI 工具，把 `-a codex` 换成对应名称。
 
-```bash
-npx skills add jennie-shawn/starwork --skill starworkInit -g -a codex -y
-npx skills add jennie-shawn/starwork --skill starworkSpawn -g -a codex -y
-```
+当前系统级 Skills：
+
+- `starworkInit`：帮助 AI 判断是创建项目工作台还是项目中心，选择语言；用户确认创建时，会带着 `starwork init` dry-run、执行并用 `doctor` 验证。
+- `starworkDoctor`：帮助 AI 基于 `starwork doctor --json` 解释目录问题、识别旧模板或类似项目中心的旧工作区；用户明确要求升级时，生成可预览、可确认的升级方案。
+- `starworkMultiagent`：帮助 AI 把“登记当前会话为常用智能体”“管理多 AI 分工”“跨会话指令”“读取其他 lane 状态”等请求转换成 `starwork multiagent` 命令组合。
+- `starworkKnowledge`：帮助 AI 开启和维护项目本地知识库；创建结构时先调用 `starwork knowledge`，整理内容时区分主题页和综合判断。
+
+说明：`starworkKnowledge` 是全局入口 Skill。项目开启知识库后，CLI 会把 `starworkKnowledgeProject` 安装到当前项目的 `.agents/skills/` 和 `.claude/skills/`，它不属于全局安装清单。
+
+Kit 随附 Skills 不走全局安装命令，它们跟着具体工作台走：
+
+- `starworkSpawn`：项目中心自带 Skill，帮助已有项目中心设计 `starwork spawn --blueprint` 工作台定制单。
+- `starworkAudit`：项目中心自带 Skill，帮助项目中心解读 `starwork audit --json`，判断它管理的项目工作台健康状况，并生成保守的 `starwork repair --blueprint` 修复蓝图。
+- `neat-freak`：项目工作台自带 Skill，帮助项目收尾、整理和归档。
+
+## 让 Agent 帮你安装
 
-Available skills:
+如果你希望让 AI 帮你完成安装，可以把下面这段提示词发给 Codex、Claude Code 或其他能操作终端的 AI：
 
-- `starworkInit`: helps an agent design a friendly `starwork init` plan for a new workspace.
-- `starworkSpawn`: helps an agent design a `starwork spawn --blueprint` plan for a satellite workspace.
+```text
+请帮我安装并验证 StarWork。
+
+请先阅读 StarWork 的 Agent 安装指南，再按文档执行：
+https://raw.githubusercontent.com/jennie-shawn/StarWork/main/docs/agent-install-guide.md
+
+请先只完成 CLI 和 Skills 的安装验证，不要默认创建工作区。安装完成后，先询问我是否需要继续创建或测试 StarWork 工作区；如果需要，再进入 starworkInit 流程。
+```
 
-## Quick Start
+更完整的 Agent 操作流程见 [Agent 安装指南](docs/agent-install-guide.md)。
 
-Create a single-project workspace:
+## 快速开始
+
+创建一个项目工作台：
 
 ```bash
 starwork init \
-  --type single-matter \
+  --type project \
   --pack general \
+  --language zh \
   --name "StarWork A Test" \
   --target ~/Desktop/starwork-a-test \
   --yes
 ```
 
-Check the workspace:
+检查工作台：
 
 ```bash
 starwork doctor --target ~/Desktop/starwork-a-test
 ```
 
-Create a multi-project Hub:
+可选：给项目开启知识库：
+
+```bash
+starwork knowledge init --target ~/Desktop/starwork-a-test --dry-run
+starwork knowledge init --target ~/Desktop/starwork-a-test --yes
+starwork knowledge status --target ~/Desktop/starwork-a-test --json
+```
+
+创建一个项目中心：
 
 ```bash
 starwork init \
   --type hub \
-  --name "StarWork Hub A Test" \
+  --language zh \
+  --name "StarWork Project Center A Test" \
   --target ~/Desktop/starwork-hub-a-test \
   --yes
 ```
 
-Spawn a project from the Hub:
+从项目中心创建一个项目工作台：
 
 ```bash
 starwork spawn \
   --hub ~/Desktop/starwork-hub-a-test \
   --name "Alpha Project" \
   --target ~/Desktop/starwork-alpha-project \
-  --mode matter \
+  --language zh \
   --yes
 ```
 
-Check the spawned project:
+检查生成的项目：
 
 ```bash
 starwork doctor --target ~/Desktop/starwork-alpha-project
 ```
 
-## CLI Commands
+从项目中心巡检项目：
+
+```bash
+starwork audit --hub ~/Desktop/starwork-hub-a-test
+```
+
+## CLI 能力
 
 ```text
 starwork init
 starwork doctor
+starwork knowledge
 starwork spawn
+starwork upgrade
 starwork adapt
 starwork pack install
+starwork multiagent
 ```
 
-Current capabilities:
+## 产品规划资料
+
+StarWork 的功能规划、版本 SPEC、讨论沉淀、参考资料和验收材料统一放在：
+
+```text
+product/planning/
+```
+
+其中独立功能按功能点归档：
+
+```text
+product/planning/features/<feature>/
+```
+
+正式用户文档和 HTML 阅读稿仍放在 `product/docs/`。
+
+当前能力：
 
-- `init`: creates a local starter workspace, local matter workspace, or multi-project Hub.
-- `doctor`: checks workspace health, required files, Pack installation, and blueprint customization.
-- `spawn`: creates and registers a satellite project from an existing Hub.
-- `adapt`: generates Agent-specific adapter files for Claude Code, Cursor, and related tools.
-- `pack install`: installs supported Packs into compatible workspaces.
+- `init`：创建项目工作台或项目中心；交互默认推荐项目工作台。
+- `doctor`：检查工作台是否完整、关键文件是否还在；也会为旧模板和类似项目中心的旧工作区列出目录线索，交给 `starworkDoctor` 判断。
+- `knowledge`：开启、检查和按确认方案整理项目本地知识库；成功开启后安装项目内知识库助手，默认不会移动旧 `知识/` 或 `knowledge/`。
+- `spawn`：从已有项目中心创建并登记项目工作台，支持中文或英文目录镜像。
+- `upgrade`：按 `starworkDoctor` skill 生成的升级蓝图，把历史模板或类似项目中心的旧工作区安全接入 StarWork 工作台。
+- `adapt`：生成 Claude Code、Cursor 等 AI 工具的适配文件；Cursor 仅支持只读 transcript 摘要，Trae 仅支持人工操作入口。
+- `pack install`：向兼容工作台安装支持的场景能力。
+- `multiagent`：为同一项目建立自定义 AI 职责位、绑定会话、登记跨 lane 共享输出，并支持会话观察、launch 和格式化跨会话指令；`instruct` 由 CLI 运行时判断宿主能力，不能标准投递时返回 `manual_handoff_required`。Cursor 绑定只用于 `read/status --host` 的只读摘要，Trae 绑定会转人工或 unsupported。
 
-## Repository Structure
+## 仓库结构
 
 ```text
 .
-├── core/       # StarWork Core protocol, kits, profiles, and presets
-├── cli/        # CLI implementation and command specifications
-├── packs/      # Scenario Packs
-├── skills/     # Agent skills
-├── schemas/    # Structured schemas
-├── adapters/   # Agent adapter rules
-├── examples/   # Examples and sample snippets
-└── docs/       # Product documentation and A-test guides
+├── core/       # StarWork Core 协议、Kit、Profile、Preset
+├── cli/        # CLI 实现和命令规格
+├── packs/      # 场景 Pack
+├── skills/     # 系统级 AI skills
+├── kit-skills/ # Kit 自带 AI skills
+├── schemas/    # 结构化 schema
+├── adapters/   # AI 工具适配规则
+├── examples/   # 示例
+├── docs/       # 产品文档和 A 测指南
+└── planning/   # 功能规划、版本 SPEC、讨论、参考和验收
 ```
 
-## A-test Notes
+## A 测反馈重点
 
-This release is intended for early testers. Please focus feedback on:
+请优先反馈：
 
-- whether the CLI installs and runs cleanly;
-- whether generated workspace structures are easy to understand;
-- whether `doctor` explains problems clearly;
-- whether Hub + Satellite workflows feel natural;
-- whether `starworkInit` and `starworkSpawn` can be discovered and used by Codex.
+- CLI 是否能顺利安装和运行。
+- `init` 创建的工作台结构是否容易理解。
+- `doctor` 的检查结果是否能指导修复问题。
+- 项目中心创建和管理项目工作台的流程是否自然。
+- 系统 Skill 是否能被 AI 正确识别和调用。
+- 项目中心自带的 `starworkSpawn`、项目工作台自带的 `neat-freak` 是否能在对应工作台内被正确发现。
 
-For a fuller test script, see [docs/alpha-test-guide.md](docs/alpha-test-guide.md).
+更完整的测试脚本见 [A 测安装指南](docs/alpha-test-guide.md)。
 
-## Development
+## 开发
 
-Run the test suite:
+运行测试：
 
 ```bash
 npm test
 ```
 
-Preview the npm package contents:
+预览 npm 包内容：
 
 ```bash
 npm pack --dry-run

package/adapters/README.md

@@ -3,3 +3,37 @@
 这里存放不同 Agent 的适配层，如 Codex、Claude Code、Cursor、Trae 等。
 
 适配层不混入 StarWork Core。
+
+## 当前定位
+
+Adapter 是 StarWork 的全局宿主适配层，不只服务 MultiAgent。
+
+它负责把 StarWork 工作台协议翻译成不同 AI 宿主能正确读取、正确行动、正确保存上下文的方式，包括：
+
+- 规则入口
+- Skill 识别
+- 会话能力
+- transcript / memory 边界
+- 宿主 CLI / API 探测
+- 私有状态安全边界
+
+## v0.1 当前进度
+
+Host Adapter v0.1 已先落地底座：
+
+- `contract.md`：定义 adapter profile、工作台 adapter state 和宿主安全边界。
+- `codex/`、`claude-code/`、`cursor/`、`trae/`：分别维护 `profile.json`、`rules.md`、`safety.md`。
+- `starwork adapt <host|all> --capabilities`：只读输出宿主能力，不改工作台。
+- `starwork adapt <host|all>`：写入宿主规则入口、Skill 目录和 `.starwork/adapters.json`。
+- `starwork doctor --host <host|all>`：检查宿主入口、Skill 目录、Cursor / Trae frontmatter、Trae disabled config 和不安全能力声明。
+- `starwork init --adapter <host|all>`：初始化完成后继续生成对应宿主入口。
+- `starwork multiagent`：Claude Code 可用 `CLAUDE_CODE_SESSION_ID` 绑定和 `claude --resume` 继续命令；Cursor 仅做 `agent-transcripts/<uuid>/<uuid>.jsonl` 只读摘要；Trae 仅保留人工操作入口；二者都不伪装后台送达。
+
+Cursor transcript 路径兼容、Claude Code 真实本机 transcript 路径适配和更完整用户文档仍需继续 A 测打磨。Trae 会话私有存储不作为 StarWork 读取目标。
+
+产品规划事实源见：
+
+```text
+product/planning/features/host-adapters/specs/v0.1.md
+product/planning/features/host-adapters/specs/v0.1-implementation.md
+```

package/adapters/claude-code/profile.json

@@ -0,0 +1,55 @@
+{
+  "schema": "starwork.adapter.profile.v0.1",
+  "host": "claude-code",
+  "label": "Claude Code",
+  "version": "0.1",
+  "rules": {
+    "entry_file": "CLAUDE.md",
+    "can_generate_entry": "supported",
+    "can_update_entry": "partial",
+    "supports_project_scope": "supported",
+    "supports_nested_rules": "unknown"
+  },
+  "skills": {
+    "system_install": "manual",
+    "project_mount": "manual",
+    "primary_project_dir": ".claude/skills/",
+    "project_mount_dirs": [".claude/skills/", ".agents/skills/"],
+    "host_native_dirs": [".claude/skills/"],
+    "global_dirs": ["~/.claude/skills/"],
+    "conflict_priority": [".claude/skills/", ".agents/skills/"],
+    "discovery": "manual",
+    "trigger_style": "rules-guided",
+    "adapter_rule_required": true
+  },
+  "sessions": {
+    "detect_current": "supported",
+    "rename": "partial",
+    "list": "partial",
+    "read": "supported",
+    "continue": "supported",
+    "send_message": "manual",
+    "create": "partial",
+    "pin": "unsupported",
+    "archive": "unsupported"
+  },
+  "memory": {
+    "transcript_read": "supported",
+    "transcript_write": "unsupported",
+    "summary_visible": "unsupported",
+    "project_memory": "supported",
+    "export": "partial"
+  },
+  "commands": {
+    "cli_available": "partial",
+    "api_available": "unsupported",
+    "requires_auth": "partial",
+    "can_probe": "supported"
+  },
+  "safety": {
+    "private_paths_readonly": ["~/.claude/projects/**", "~/.claude/sessions/**"],
+    "never_write_paths": ["~/.claude/projects/**/*.jsonl", "~/.claude.json"],
+    "destructive_commands": ["claude project purge"],
+    "degradation_required": ["sessions.send_message", "sessions.pin", "sessions.archive"]
+  }
+}

package/adapters/claude-code/rules.md

@@ -0,0 +1,13 @@
+# Claude Code Adapter Rules
+
+Claude Code uses `CLAUDE.md` as its project rule entry.
+
+The entry should point Claude Code back to:
+
+- `AGENTS.md`
+- `.starwork/workspace.json`
+- `.starwork/skills.json`
+- `.claude/skills/`
+- `.agents/skills/`
+
+Claude Code can bind or resume sessions, and transcripts may be read as candidate evidence. It cannot safely receive background messages to another session in StarWork v0.1.

package/adapters/claude-code/safety.md

@@ -0,0 +1,6 @@
+# Claude Code Adapter Safety
+
+- Never write Claude Code transcript JSONL files.
+- Never write `~/.claude.json`.
+- Never run destructive commands such as `claude project purge`.
+- Treat transcript content as candidate evidence only, not as StarWork formal memory.

package/adapters/codex/profile.json

@@ -0,0 +1,55 @@
+{
+  "schema": "starwork.adapter.profile.v0.1",
+  "host": "codex",
+  "label": "Codex",
+  "version": "0.1",
+  "rules": {
+    "entry_file": "AGENTS.md",
+    "can_generate_entry": "supported",
+    "can_update_entry": "partial",
+    "supports_project_scope": "supported",
+    "supports_nested_rules": "partial"
+  },
+  "skills": {
+    "system_install": "supported",
+    "project_mount": "supported",
+    "primary_project_dir": ".agents/skills/",
+    "project_mount_dirs": [".agents/skills/"],
+    "host_native_dirs": [".agents/skills/"],
+    "global_dirs": ["~/.agents/skills/"],
+    "conflict_priority": [".agents/skills/"],
+    "discovery": "partial",
+    "trigger_style": "rules-guided",
+    "adapter_rule_required": true
+  },
+  "sessions": {
+    "detect_current": "partial",
+    "rename": "supported",
+    "list": "supported",
+    "read": "supported",
+    "continue": "supported",
+    "send_message": "supported",
+    "create": "supported",
+    "pin": "partial",
+    "archive": "unsupported"
+  },
+  "memory": {
+    "transcript_read": "partial",
+    "transcript_write": "unsupported",
+    "summary_visible": "partial",
+    "project_memory": "supported",
+    "export": "partial"
+  },
+  "commands": {
+    "cli_available": "supported",
+    "api_available": "partial",
+    "requires_auth": "partial",
+    "can_probe": "supported"
+  },
+  "safety": {
+    "private_paths_readonly": [],
+    "never_write_paths": [],
+    "destructive_commands": [],
+    "degradation_required": ["sessions.archive"]
+  }
+}

package/adapters/codex/rules.md

@@ -0,0 +1,12 @@
+# Codex Adapter Rules
+
+Codex uses `AGENTS.md` as the primary project rule entry.
+
+The adapter should ensure Codex can find:
+
+- `AGENTS.md`
+- `.starwork/workspace.json`
+- `.starwork/skills.json`
+- `.agents/skills/`
+
+Codex can support automatic MultiAgent `launch`, `read`, and `instruct`, but completion must still be verified through StarWork state and target thread reads.

package/adapters/codex/safety.md

@@ -0,0 +1,5 @@
+# Codex Adapter Safety
+
+- Do not write Codex private runtime state.
+- Do not treat thread history as StarWork formal project memory.
+- If a turn is started but completion is not observed, report `started_unverified`, not completed delivery.

package/adapters/contract.md

@@ -0,0 +1,64 @@
+# StarWork Host Adapter Contract
+
+Host Adapter is the StarWork layer that translates the workspace protocol for a concrete AI host.
+
+It does not redefine Core, Kit, or Pack structure. It records what each host can read, generate, mount, inspect, continue, or only handle manually.
+
+## Profile Schema
+
+Each built-in host has:
+
+```text
+product/adapters/<host>/profile.json
+product/adapters/<host>/rules.md
+product/adapters/<host>/safety.md
+```
+
+`profile.json` must use:
+
+```json
+{
+  "schema": "starwork.adapter.profile.v0.1",
+  "host": "cursor",
+  "label": "Cursor",
+  "version": "0.1",
+  "rules": {},
+  "skills": {},
+  "sessions": {},
+  "memory": {},
+  "commands": {},
+  "safety": {}
+}
+```
+
+## Capability Levels
+
+Only these values are valid:
+
+```text
+supported | partial | manual | unsupported | unknown
+```
+
+- `supported`: stable automatic behavior.
+- `partial`: available but incomplete, environment-dependent, or not stable enough to promise.
+- `manual`: StarWork can generate instructions or handoff text, but the user must act.
+- `unsupported`: not supported or not safe to rely on.
+- `unknown`: not researched enough to make a promise.
+
+`partial`, `manual`, and `unknown` must never be described as automatic completion.
+
+## State
+
+Workspace adapter state lives in:
+
+```text
+.starwork/adapters.json
+```
+
+`.starwork/workspace.json.adapters` remains a short compatibility summary only.
+
+## Safety Rules
+
+Adapters must not write host private transcripts, private databases, encrypted stores, or global configuration unless the user explicitly asks for a documented host-level action.
+
+Host private history is never a StarWork source of truth.

package/adapters/cursor/profile.json

@@ -0,0 +1,60 @@
+{
+  "schema": "starwork.adapter.profile.v0.1",
+  "host": "cursor",
+  "label": "Cursor",
+  "version": "0.1",
+  "rules": {
+    "entry_file": ".cursor/rules/starwork.mdc",
+    "can_generate_entry": "supported",
+    "can_update_entry": "partial",
+    "supports_project_scope": "supported",
+    "supports_nested_rules": "supported"
+  },
+  "skills": {
+    "system_install": "manual",
+    "project_mount": "supported",
+    "primary_project_dir": ".cursor/skills/",
+    "project_mount_dirs": [".cursor/skills/", ".agents/skills/"],
+    "host_native_dirs": [".cursor/skills/", ".agents/skills/", ".claude/skills/", ".codex/skills/"],
+    "global_dirs": ["~/.cursor/skills/", "~/.agents/skills/", "~/.claude/skills/", "~/.codex/skills/"],
+    "conflict_priority": [".cursor/skills/", ".agents/skills/", ".claude/skills/", ".codex/skills/"],
+    "discovery": "supported",
+    "trigger_style": "native-skill-discovery",
+    "adapter_rule_required": true,
+    "frontmatter": {
+      "required": ["name", "description"],
+      "name_pattern": "^[a-z0-9-]+$",
+      "name_matches_parent": true
+    }
+  },
+  "sessions": {
+    "detect_current": "partial",
+    "list": "partial",
+    "read": "partial",
+    "continue": "manual",
+    "send_message": "manual",
+    "create": "unsupported",
+    "rename": "partial",
+    "pin": "unsupported",
+    "archive": "unsupported"
+  },
+  "memory": {
+    "transcript_read": "partial",
+    "transcript_write": "unsupported",
+    "summary_visible": "unknown",
+    "project_memory": "supported",
+    "export": "partial"
+  },
+  "commands": {
+    "cli_available": "partial",
+    "api_available": "unsupported",
+    "requires_auth": "partial",
+    "can_probe": "partial"
+  },
+  "safety": {
+    "private_paths_readonly": ["~/Library/Application Support/Cursor/**"],
+    "never_write_paths": ["~/Library/Application Support/Cursor/**/*.vscdb", "~/Library/Application Support/Cursor/**/*.sqlite"],
+    "destructive_commands": [],
+    "degradation_required": ["sessions.pin", "sessions.archive"]
+  }
+}

package/adapters/cursor/rules.md

@@ -0,0 +1,7 @@
+# Cursor Adapter Rules
+
+Cursor uses `.cursor/rules/starwork.mdc` as the StarWork entry.
+
+Cursor can discover project Skills from `.cursor/skills/` and `.agents/skills/`, and can also see compatible `.claude/skills/` and `.codex/skills/` directories. StarWork still treats `.starwork/skills.json` as the project Skill fact source.
+
+Cursor session automation is read-only in v0.2. StarWork may summarize `agent-transcripts/<uuid>/<uuid>.jsonl` for `multiagent read/status --host`, but must not write Cursor transcripts, create chats, or claim automatic cross-session delivery.

package/adapters/cursor/safety.md

@@ -0,0 +1,6 @@
+# Cursor Adapter Safety
+
+- Do not write Cursor private databases or chat history.
+- Only summarize Cursor `agent-transcripts/<uuid>/<uuid>.jsonl` as incomplete host observation.
+- Do not treat Cursor transcript or UI state as StarWork formal memory.
+- Do not claim background delivery unless a supported, verified route exists.