code-workspace-zhuiyi 0.1.0-beta.1

package/artifacts/templates/agents/skills/code-workspace-resolve-branch/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: code-workspace-resolve-branch
+description: Resolve `PROJECT_BRANCH_MISMATCH` for one or more already selected Code Workspace projects before project work. Use this Skill whenever targeted verification reports registered/actual branch mismatches; it gathers canonical facts, presents a deterministic structured choice, delegates every automatic direction to the branch CLI, and verifies branch alignment.
+---
+
+# Resolve Workspace Project Branches
+
+Resolve only the already selected registered project or projects. This Skill owns branch reconciliation only; Workspace Guard decides whether project work can resume.
+
+## Inspect canonical facts
+
+Run one command from the Workspace for all selected projects whose targeted verification reported `PROJECT_BRANCH_MISMATCH`. Pass each project name as a separate argument; do not join names with commas:
+
+```bash
+code-w project branch inspect "<project-a>" "<project-b>" --json
+```
+
+For one project, require the existing standard envelope whose `data` contains all of: `project.name`, `project.location`, `registeredBranch`, `actualBranch`, `matches`, `worktreeClean`, `registeredBranchExists`, and `remoteBranchCandidates`. For several projects, read the ordered `data.results`; each successful result contains those facts in its `data`, while failed results are explained by the top-level diagnostics. Do not infer or independently inspect missing values.
+
+Keep failed inspections paused and exclude them from the choice, but continue with every project whose canonical facts were returned. If no project was inspected successfully, report the collected diagnostics and stop.
+
+If `matches` is already true, omit that project from the choice and proceed to branch-alignment verification. Do not inspect or include projects outside the already selected scope.
+
+## Keep the ASK structure stable
+
+Different models may choose different wording, but preserve the following presentation shape so users can scan the same information consistently:
+
+```text
+[mismatch introduction and request for a decision]
+
+[multi-project only: A:] [project name]
+[registered-branch label]: [registered branch][optional annotation when the branch is missing locally]
+[actual-branch label]: [actual branch][optional annotation when the worktree is unclean]
+
+[multi-project only: B:] [project name]
+[registered-branch label]: [registered branch][optional annotation]
+[actual-branch label]: [actual branch][optional annotation]
+
+[continue in inspection order, with one blank line between project blocks]
+
+[choice prompt; for one project, state that only available choices are shown]
+1. [use the registered branch]
+2. [accept the actual branch]
+3. [handle manually without an automatic Git operation]
+
+[request a decision for each project]
+
+[multi-project only: reply-format heading]
+[explain that one number applies to every project, while labelled selections such as A1 B2 C3 apply per project]
+[explain that labels are case-insensitive and commas, spaces, or line breaks are accepted as separators]
+
+[multi-project only, and only when a choice is unavailable: important-notes heading]
+[project label]: choice 1 is unavailable — [one canonical reason]
+[one line for each additional project/reason]
+
+[multi-project only: explain that an unavailable selection is re-asked only for that project, valid selections are retained, and no state changes occur until every selection is valid and complete]
+```
+
+Ask rules:
+
+- Replace the bracketed instructions with user-facing text without exposing them. Keep inspection order, three non-bulleted lines per project, blank lines between projects, and only the two abnormal annotations shown in the template.
+- Choice 1 is available when the worktree is clean and either the registered branch exists locally or exactly one `remoteBranchCandidates` entry is available. When only a remote-tracking candidate is available, explain that choosing 1 will create a local tracking branch; do not fetch implicitly. Choices 2 and 3 remain available. Do not recommend a default or invent another recovery direction.
+- For one project, omit everything marked multi-project only, state that only available choices are shown, and preserve the semantic numbers of those choices.
+- For several projects, keep stable letter labels and all three choices. Include every applicable unavailable reason, with one project and one reason per line.
+- Accept either one bare number for every project or labelled selections, never both. In labelled mode, accept partial replies, but treat unknown labels or options and duplicate or conflicting labels as invalid. Retain other valid selections and re-ask only for missing, unavailable, or invalid projects.
+- Do not mutate state until all choices are valid and complete. If an ASK control cannot preserve the template, use a normal user-facing question.
+
+## Apply valid choices through the CLI
+
+- Group every project that selected choice 1 into one `code-w project branch use-registered "<project-a>" "<project-b>" --allow-remote --yes --json` invocation. Include only projects for which choice 1 is available. `--allow-remote` is harmless for projects whose local registered branch already exists and permits creation only from an existing unique remote-tracking branch.
+- Group every project that selected choice 2 into one `code-w project branch accept-actual "<project-a>" "<project-b>" --yes --json` invocation.
+- For choice 3, keep that project paused until the user confirms manual resolution is complete. Do not reuse any pre-resolution branch facts.
+
+If the registered branch is absent both locally and from remote-tracking refs, do not add `--remote` automatically. Tell the user that an explicit direct CLI invocation such as `project branch use-registered <name> --remote origin --yes --json` is required to authorize network fetch.
+
+After all choices are valid and complete, run each non-empty automatic direction group once. A batch command can return `ok: false` after still completing other projects, so inspect its ordered results instead of treating the whole group as unprocessed. Continue with the other automatic direction group even when the first group contains failures. Do not fall back to direct Git commands, direct Workspace configuration editing, or an improvised recovery direction.
+
+## Verify branch alignment in one targeted batch
+
+After both automatic direction groups finish, collect projects whose operations succeeded or skipped together with projects that were already matching during inspection, discard their cached branch-dependent context, and run one branch-only verification. After the user confirms one or more manual resolutions, verify those confirmed projects the same way:
+
+```bash
+code-w project branch verify "<project-a>" "<project-b>" --json
+```
+
+Use each result independently. A successful result means branch reconciliation is complete and branch alignment has been verified for that project; a failed result remains unresolved. Complete all independent automatic operations and branch verification before giving one consolidated report of inspected failures, successful changes, skips, branch-verification failures, and projects awaiting manual handling.
+
+Hand successful projects back to Workspace Guard. Later non-branch project issues do not reopen or fail this Skill. If later branch drift is observed, the Guard may invoke this Skill again. Do not inspect any registered project outside the selected scope.

package/artifacts/templates/agents/skills/code-workspace-resolve-branch/evals/evals.json

@@ -0,0 +1,45 @@
+{
+  "skill_name": "code-workspace-resolve-branch",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Use the Skill to present the ASK only; do not run a CLI command or resolve the branch. Canonical inspection facts: one project named api, registered branch main, actual branch feature/login, matches false, worktreeClean true, registeredBranchExists true.",
+      "expected_output": "A concise single-project ASK with one unlabeled three-line project block and all three available choices.",
+      "files": [],
+      "expectations": [
+        "The project name, registered branch, and actual branch appear on three consecutive non-bulleted lines.",
+        "The choice prompt states that the displayed choices are available choices.",
+        "Choices 1, 2, and 3 are shown with their stable semantics.",
+        "No letter label, reply-format section, or important-notes section is shown.",
+        "No CLI command or state change is performed."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Use the Skill to present the ASK only; do not run a CLI command or resolve the branch. Canonical inspection facts: one project named api, registered branch main, actual branch feature/login, matches false, worktreeClean false, registeredBranchExists false.",
+      "expected_output": "A single-project ASK that annotates both abnormal facts and shows only choices 2 and 3 with their original numbers.",
+      "files": [],
+      "expectations": [
+        "The registered-branch line indicates that the branch is missing locally.",
+        "The actual-branch line indicates that the worktree is unclean.",
+        "Choice 1 is omitted while choices 2 and 3 retain their semantic numbers.",
+        "The choice prompt states that only available choices are shown.",
+        "No reply-format section or important-notes section is shown.",
+        "No CLI command or state change is performed."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Use the Skill to present and validate a multi-project ASK without running a CLI command. Canonical facts in order: api has registered main, actual feature/api, worktreeClean true, registeredBranchExists true; worker has registered main, actual feature/worker, worktreeClean false, registeredBranchExists false; web has registered main, actual feature/web, worktreeClean true, registeredBranchExists false. After presenting the ASK, process the user reply `1 B2`.",
+      "expected_output": "A three-project ASK with stable blocks and complete unavailable reasons, followed by rejection of the mixed global-and-labelled reply without changing state.",
+      "files": [],
+      "expectations": [
+        "Projects A, B, and C appear in inspection order with three non-bulleted lines per project and blank lines between blocks.",
+        "All three choices and the multi-project reply-format section are shown.",
+        "The important-notes section contains two separate choice-1 reasons for project B and one reason for project C.",
+        "The reply `1 B2` is rejected because bare-number and labelled modes cannot be mixed.",
+        "No project selection is executed and no CLI command or state change is performed."
+      ]
+    }
+  ]
+}

package/artifacts/templates/claude/commands/code-workspace/add-projects.md

@@ -0,0 +1,23 @@
+---
+description: When explicitly invoked with one or more project paths, inspect Git worktrees read-only, generate concise project context, register the completed local records, and apply Agent directory authorization.
+argument-hint: "<project path> [additional project paths]"
+---
+
+Run this workflow only when the user explicitly invokes `/code-workspace:add-projects` and provides one or more project paths. Do not infer this invocation from a general request to inspect, update, or add a project. The values in `$ARGUMENTS` are the project paths; preserve quoted paths as single arguments. If no path is provided, ask the user for one or more paths and do not inspect or modify anything.
+
+Expected invocation: `/code-workspace:add-projects /absolute/path/to/project-a /absolute/path/to/project-b`
+
+Before inspecting projects, run `code-workspace language --json` once. Require the standard envelope fields `schemaVersion`, `ok`, `command`, `data`, and `diagnostics`, then use `data.language` and the labels in `data.projectContext` for every generated project context in this invocation.
+
+For each supplied path:
+
+1. Run `code-workspace project inspect "<path>" --json`. Treat only its location, branch, manifest-file list, README-file list, and top-level entry list as CLI-verified facts.
+2. Inspect the repository read-only. Read only what is needed to understand it, starting with README files, root manifests, and relevant entry points or module directories. Do not modify the project repository.
+3. Produce a complete project record with `name`, canonical `location`, current `branch`, a concise semantic `type`, and `context`.
+4. Generate `context` as concise, stable project navigation for an AI that has not read the repository. Use exactly four semantic lines in this order: `responsibility`, `technologyStack`, `codeLocations`, and `projectBoundary`. Prefix each line with the corresponding label returned in `data.projectContext`; do not translate or replace those labels yourself. Write descriptions in the returned workspace `data.language`. Keep project names, paths, branches, technology names, identifiers, and code symbols unchanged. Prefer 150-400 Chinese characters or comparable English length. Do not include exhaustive dependencies, volatile command details, filler, or unsupported guesses.
+
+Present all completed records for confirmation. After confirmation, write them to a temporary JSON document with `schemaVersion: 1` and a non-empty `projects` array, then run `code-workspace project add --projects-file <temporary-json-file> --yes --json` followed by `code-workspace project verify --json`.
+
+Do not hand-edit `.code-workspace/config.yaml` or permission files. Completion requires successful registration, authorization application, and project verification.
+
+$ARGUMENTS

package/artifacts/templates/codex/hooks.json

@@ -0,0 +1,86 @@
+{
+  "description": "Report Codex Agent lifecycle events to Code Workspace Monitor.",
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "code-w monitor report",
+            "timeout": 1
+          }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "code-w monitor report",
+            "timeout": 1
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "code-w monitor report",
+            "timeout": 1
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "code-w monitor report",
+            "timeout": 1
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "code-w monitor report",
+            "timeout": 1
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "code-w monitor report",
+            "timeout": 1
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "code-w monitor report",
+            "timeout": 1
+          }
+        ]
+      }
+    ]
+  }
+}

package/artifacts/templates/codex/skills/code-workspace-add-projects/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: code-workspace-add-projects
+description: When explicitly invoked with one or more project paths, inspect Git worktrees read-only, generate concise AI project context, register the completed records locally, and apply Agent directory authorization.
+---
+
+# Add local projects
+
+Run this workflow only when the user explicitly invokes `$code-workspace-add-projects` and provides one or more project paths. Do not infer this invocation from a general request to inspect, update, or add a project. The arguments after the skill name are the project paths; preserve quoted paths as single arguments. If no path is provided, ask the user for one or more paths and do not inspect or modify anything.
+
+Expected invocation: `$code-workspace-add-projects /absolute/path/to/project-a /absolute/path/to/project-b`
+
+Before inspecting projects, run `code-workspace language --json` once. Require the standard envelope fields `schemaVersion`, `ok`, `command`, `data`, and `diagnostics`, then use `data.language` and the labels in `data.projectContext` for every generated project context in this invocation.
+
+For each supplied path:
+
+1. Run `code-workspace project inspect "<path>" --json`. Treat only its location, branch, manifest-file list, README-file list, and top-level entry list as CLI-verified facts.
+2. Inspect the repository read-only. Read only what is needed to understand it, starting with README files, root manifests, and relevant entry points or module directories. Do not modify the project repository.
+3. Produce a complete project record with `name`, canonical `location`, current `branch`, a concise semantic `type`, and `context`.
+4. Generate `context` as concise, stable project navigation for an AI that has not read the repository. Use exactly four semantic lines in this order: `responsibility`, `technologyStack`, `codeLocations`, and `projectBoundary`. Prefix each line with the corresponding label returned in `data.projectContext`; do not translate or replace those labels yourself. Write descriptions in the returned workspace `data.language`. Keep project names, paths, branches, technology names, identifiers, and code symbols unchanged. Prefer 150-400 Chinese characters or comparable English length. Do not include exhaustive dependencies, volatile command details, filler, or unsupported guesses.
+
+Present all completed records for confirmation. After confirmation, write them to a temporary JSON document with `schemaVersion: 1` and a non-empty `projects` array, then run:
+
+```bash
+code-workspace project add --projects-file <temporary-json-file> --yes --json
+code-workspace project verify --json
+```
+
+Do not hand-edit `.code-workspace/config.yaml` or permission files. Completion requires successful registration, authorization application, and project verification.

package/artifacts/templates/user-guide/en-US.md

@@ -0,0 +1,97 @@
+# Code Workspace User Guide
+
+A short reminder for using Code Workspace after initialization.
+
+## Add workspace projects
+
+Codex:
+
+```text
+$code-workspace-add-projects /absolute/path/to/project-a /absolute/path/to/project-b
+```
+
+Claude Code:
+
+```text
+/code-workspace:add-projects /absolute/path/to/project-a /absolute/path/to/project-b
+```
+
+Review the project records and confirm when prompted. The add-projects skill runs `code-workspace language --json`, uses `data.projectContext` from the standard result envelope, and writes each generated project context in `data.language`.
+
+## Upgrade Code Workspace
+
+Upgrade the global package, update the current workspace's managed files, then verify health:
+
+```bash
+npm install -g @icebearx-ai/code-workspace@latest
+code-w update
+code-w doctor
+```
+
+`update` refreshes managed instructions, Workspace skills, hooks, and this guide. It stops if a managed file contains unknown local changes. Review the file first; use `--force` only when replacing those changes is intentional.
+
+## Workspace language
+
+Choose the Workspace language during initialization, or pass it explicitly:
+
+```bash
+code-w init --language en-US
+code-w language
+```
+
+The selected preference is stored at `workspace.language` in `.code-workspace/config.yaml`. Change an initialized workspace with:
+
+```bash
+code-w update --language en-US
+```
+
+This also switches this managed guide. Existing project context is not translated.
+
+## Use the Agent monitor
+
+Start one global monitor for all workspaces:
+
+```bash
+code-w monitor
+```
+
+Open the printed local URL. The dashboard shows workspaces, execution state, pending approvals, completed turns, and live signals. Monitor language is selected on the page and is independent of `workspace.language`.
+
+Use another port when necessary:
+
+```bash
+code-w monitor --port 8080
+```
+
+Each participating workspace must use the same URL in `.code-workspace/config.yaml`. After initialization, review and trust the project hooks with `/hooks` in Codex.
+
+## Practical commands
+
+```bash
+# Check installation and workspace health
+code-w doctor
+
+# Update all managed files
+code-w update
+
+# Apply Agent project directory authorization
+code-w permissions apply --yes
+
+# Validate local projects
+code-w project verify
+code-w project verify <project-name>
+```
+
+Directory access is authorized by the user. Code Workspace shows the requested changes, applies and verifies them, and reports the result. `permissions apply` grants missing registered-project access without revoking additional directories. Ordinary `update` does not change authorization.
+
+Add `--json` when a query result is consumed by Codex or a script.
+
+## Workspace skills
+
+- `$code-workspace-add-projects` — inspect and register local Git projects with concise AI-generated navigation context.
+- `$code-workspace-resolve-branch` — safely resolve a selected project's branch mismatch and confirm branch alignment.
+
+| Purpose | Codex | Claude Code |
+| --- | --- | --- |
+| Add workspace projects | `$code-workspace-add-projects` | `/code-workspace:add-projects` |
+| Resolve a project branch mismatch | `$code-workspace-resolve-branch` | `/code-workspace-resolve-branch` |

package/artifacts/templates/user-guide/zh-CN.md

@@ -0,0 +1,97 @@
+# Code Workspace 用户指南
+
+这是一份在初始化完成后使用 Code Workspace 的简明指南。
+
+## 添加工作区项目
+
+Codex：
+
+```text
+$code-workspace-add-projects /absolute/path/to/project-a /absolute/path/to/project-b
+```
+
+Claude Code：
+
+```text
+/code-workspace:add-projects /absolute/path/to/project-a /absolute/path/to/project-b
+```
+
+根据提示检查项目记录并确认。add-projects skill 会运行 `code-workspace language --json`，使用标准结果信封中的 `data.projectContext` 标签，并以 `data.language` 生成项目 context。
+
+## 升级 Code Workspace
+
+先升级全局软件包，再更新当前工作区的托管文件，最后检查健康状态：
+
+```bash
+npm install -g @icebearx-ai/code-workspace@latest
+code-w update
+code-w doctor
+```
+
+`update` 会更新托管指令、Workspace 技能、Hook 和本指南。如果托管文件包含未知的本地修改，更新会停止。请先检查文件；只有明确要覆盖这些修改时才使用 `--force`。
+
+## 工作区语言
+
+初始化时可选择 Workspace 语言，也可以显式指定：
+
+```bash
+code-w init --language zh-CN
+code-w language
+```
+
+所选偏好保存在 `.code-workspace/config.yaml` 的 `workspace.language`。已有工作区可通过以下命令切换语言：
+
+```bash
+code-w update --language zh-CN
+```
+
+该操作也会切换本托管指南。已有项目 context 不会自动翻译。
+
+## 使用 Agent Monitor
+
+为所有工作区启动一个全局 Monitor：
+
+```bash
+code-w monitor
+```
+
+打开命令输出的本地地址。面板会显示工作区、执行状态、待授权请求、已完成轮次和实时信号。Monitor 语言在页面中单独选择，与 `workspace.language` 相互独立。
+
+必要时可使用其他端口：
+
+```bash
+code-w monitor --port 8080
+```
+
+所有参与监控的工作区都必须在 `.code-workspace/config.yaml` 中使用相同 URL。初始化后，请在 Codex 中使用 `/hooks` 检查并信任项目 Hook。
+
+## 实用命令
+
+```bash
+# 检查安装和工作区健康状态
+code-w doctor
+
+# 更新所有托管文件
+code-w update
+
+# 应用 Agent 项目目录授权
+code-w permissions apply --yes
+
+# 校验本地项目
+code-w project verify
+code-w project verify <project-name>
+```
+
+目录访问由用户授权。Code Workspace 负责展示请求的变更、实施并验证变更，以及报告结果。`permissions apply` 只补齐已注册项目缺失的授权，不撤销额外目录。普通 `update` 不会改变授权。
+
+查询结果需要交给 Codex 或脚本处理时，可添加 `--json`。
+
+## Workspace Skills
+
+- `$code-workspace-add-projects` — 检查并注册本地 Git 项目，同时生成供 AI 导航使用的简洁 context。
+- `$code-workspace-resolve-branch` — 安全解决选中项目的分支不一致问题，并确认分支对齐。
+
+| 用途 | Codex | Claude Code |
+| --- | --- | --- |
+| 添加工作区项目 | `$code-workspace-add-projects` | `/code-workspace:add-projects` |
+| 解决项目分支不一致 | `$code-workspace-resolve-branch` | `/code-workspace-resolve-branch` |

package/assets/i18n-icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" viewBox="0 0 24 24" class="vt-locales-btn-icon" data-v-6229553e=""><path d="M0 0h24v24H0z" fill="none"></path><path d=" M12.87 15.07l-2.54-2.51.03-.03c1.74-1.94 2.98-4.17 3.71-6.53H17V4h-7V2H8v2H1v1.99h11.17C11.5 7.92 10.44 9.75 9 11.35 8.07 10.32 7.3 9.19 6.69 8h-2c.73 1.63 1.73 3.17 2.98 4.56l-5.09 5.02L4 19l5-5 3.11 3.11.76-2.04zM18.5 10h-2L12 22h2l1.12-3h4.75L21 22h2l-4.5-12zm-2.62 7l1.62-4.33L19.12 17h-3.24z " class="css-c4d79v"></path></svg>

package/assets/logo-vector.svg

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg"
+     width="1254" height="1254" viewBox="0 0 1254 1254"
+     role="img" aria-label="Geometric teal-blue logo">
+  <defs>
+    <linearGradient id="logoGradient" x1="320" y1="175" x2="860" y2="1080" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#19AEB8"/>
+      <stop offset="0.48" stop-color="#087DA5"/>
+      <stop offset="1" stop-color="#07528C"/>
+    </linearGradient>
+  </defs>
+
+  <g fill="none"
+     stroke="url(#logoGradient)"
+     stroke-width="118"
+     stroke-linecap="butt"
+     stroke-linejoin="round">
+    <path d="M 794 289
+             L 630 184
+             L 291 394
+             L 291 786
+             L 630 1020
+             L 973 786
+             L 973 393
+             L 914 354"/>
+    <path d="M 850 386
+             L 617 526
+             L 617 850"/>
+  </g>
+</svg>

package/bin/code-workspace.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+const { main } = require("../src/cli");
+const { renderResult } = require("../src/cli/renderer");
+const { failure } = require("../src/cli/result");
+
+const json = process.argv.some((arg) => arg === "--json" || arg.startsWith("--json="));
+
+main(process.argv)
+  .then((result) => renderResult(result, { json }))
+  .catch((error) => renderResult(failure(error), { json }));