@jspg-ai/coding-bb 0.0.3-beta.21 → 0.0.3-beta.23

package/config/workspace-agents.sample.md

@@ -1,45 +1,50 @@
-# 业务空间使用说明（AI Agent 导航）
-
-本目录是由 `@jspg-ai/coding-bb` 初始化的**多仓库联动开发业务空间**。
-进入本目录工作时，请先按本文件理解目录职责与协作约定，再动手。
-
-## 核心约定
-
-1. **双模式开发**：涉及**应用代码**的需求在 `.worktrees/worktree-<需求名>/` 隔离目录内进行（worktree 模式，默认）；完全不触碰应用代码的需求（openspec 产物、docs、空间配置）可直接在空间根开发（轻量模式，提交 main 后即 push）。**AI 会话始终停在空间根**（worktree 内不装 AI 配置）。
-2. **AI 配置安装在空间根**：编码规范、OpenSpec 命令、worktree 管理技能都装在本目录（`cbb setup` / `cbb update` 安装）；worktree 内**不安装** AI 配置，AI 会话始终以空间根为基础。
-3. **涉及应用代码的新需求先建 worktree**：使用 `/cbb-worktree-init <需求名>`（skill 形态，各工具写法见文末），或直接自然语言说"为 <需求名> 创建工作空间"。它会为 `workspace-config.json` 中的全量关联应用同步创建同名 worktree。
-4. **开发命令在本会话执行，写操作按模式定落点**：需求提案 / 实现 / 验证 / 归档（`/opsx:propose` → `/opsx:apply` → `/opsx:verify` → `/opsx:archive`）在空间根会话执行；worktree 模式下所有产生写操作的命令（git commit / openspec / 构建 / 测试 / 文件修改）必须以 `.worktrees/worktree-<需求名>/`（或其应用子目录）为工作目录（显式 `cd` 或绝对路径），**不得往主分支提交应用代码**；轻量模式在空间根直接写、提交 main 后即 push。
-5. **关联应用增减只改配置**：编辑 `workspace-config.json` 的 `apps` 数组（`name` / `repo` / `side` / `desc`），然后用同一需求名重跑 worktree 初始化即幂等补齐；不要手工 `git clone` 应用仓库。
-6. **不要绕过 worktree 直接修改 `.codespace/`**。`.codespace/` 是工具维护的基准代码，不是开发区；应用代码改动任何模式都必须走 worktree。
-
-## 目录结构与职责
-
-| 路径 | 职责 | 维护方式 |
-|------|----------|----------|
-| `workspace-config.json` | 关联应用清单，所有应用联动的唯一数据源 | 人工编辑 |
-| `.codespace/` | 各关联应用的基准代码（每个应用一个子目录） | `cbb setup` 与 worktree 流程自动 clone / fetch；**勿手动编辑**；已 gitignore，不提交 |
-| `.worktrees/` | 需求隔离开发区（每个需求一个 `worktree-<需求名>/` 目录） | worktree 命令自动创建 / 清理；不提交（首次执行 worktree 流程时自动加入 .gitignore） |
-| `openspec/` | OpenSpec 工作流配置（`config.yaml` + `schemas/`） | 由 cbb 安装；变更产物（`openspec/changes/` 等）worktree 模式在**需求工作树内**生成随需求分支提交，轻量模式直接在空间根生成提交 main |
-| `.claude/` `.qoder/` `.opencode/` `.workbuddy/` `.trae/` | AI 工具适配目录：编码规范规则、OpenSpec 命令、worktree 管理技能（skill 形态） | 由 cbb 按 setup 时选择的工具安装；已 gitignore，不提交，勿手动改 |
-| `.cbb/` | cbb 安装清单与状态（`.managed-by-cbb`、`.last-tools`） | 由 cbb 管理；**勿手动编辑** |
-
-## 典型流程
-
-```
-本目录：对 AI 说"为 <需求名> 创建工作空间"（或 /cbb-worktree-init <需求名>）
-  → 继续在当前会话开发：写操作命令以 .worktrees/worktree-<需求名>/ 为工作目录
-    （/opsx:propose → /opsx:apply → /opsx:verify）
-  → 说"提交并推送"（或 /cbb-worktree-push）→ 结尾会提案生成 MR 预填链接（提往测试分支）
-  → 测试环境验收通过 → /opsx:archive → 正式合并走公司流程
-  → 全链路完成后说"关闭工作空间"（或 /cbb-worktree-close）
-```
-
-> 轻量模式（需求完全不涉及应用代码）跳过上述流程：空间根直接 `/opsx:*` 全程 → 提交 main → 立即 push。
-
-> worktree 管理三件套（init / close / push）以 **skill 形态**分发：既能被 AI 在对话中按意图**自动触发**，也能用斜杠命令手动指定（`/cbb-worktree-init` 等，各工具一致）。OpenSpec 命令为 `/opsx:propose`（opencode 扁平化为 `/opsx-propose`）。
-
----
-
-本文件由 `@jspg-ai/coding-bb` 生成（仅缺失时写入，之后不会覆盖或删除，可自由增补团队约定）。
-
-> ⓘ 本文件仅供导航；目录纪律以 cbb 安装的编码规范规则（`cbb-ai-behavior.md` 第 8 条）为准，该规则随 `cbb update` 更新。
+# 业务空间使用说明（AI Agent 导航）
+
+本目录是由 `@jspg-ai/coding-bb` 初始化的**多仓库联动开发业务空间**。
+进入本目录工作时，请先按本文件理解目录职责与协作约定，再动手。
+
+## 核心约定
+
+1. **双模式开发，用户选择制**：接到需求先问"要不要隔离/并行"——要 → **worktree 模式**（`/cbb-worktree-init <需求名>`，隔离目录、可多需求并行）；不要 → **本地模式**（`/cbb-local-mode`，根与 `.codespace/<app>/` 就地切同名分支、当前会话直接干）。两模式能力对称（都能改 workspace 内容与应用代码、都强制分支隔离、交付都走 MR），agent 只给推荐，用户拍板。模式选错零代价：本地模式中途重跑 `/cbb-worktree-init` 即升级隔离（分支复用，提交随身带走）。
+2. **基准 = `origin/main`（唯一真相源）**：`.codespace/<app>/` 是各应用的**标准本地检出（视图）**——main 检出是基准快照，本地模式下可 checkout 到需求分支暂态占用（收尾恢复）。读"main 现状"先看检出分支或用 `git show main:<path>`，不要默认工作区即基准。
+3. **严禁直接在 main 检出上提交载荷**：分支感知 pre-commit hook 会机械拦截（workspace 仓库仅放行控制面白名单：`workspace-config.json` / `.gitignore` / `AGENTS.md` / `openspec/config.yaml` / `openspec/schemas/**`；应用仓库 main 全拦）——被拦是防线生效，不是故障；`--no-verify` 仅限用户显式要求。
+4. **开发会话开在开发目录**：本地模式 = 当前会话原地（根检出分支后）；worktree 模式 = 新会话开进 `.worktrees/worktree-<需求名>/`（AI 配置已 junction，`/opsx:*` 等命令可用）——相对路径原样生效。空间根会话保留作**控制面**（模式调度、worktree 生灭、`cbb update`）。
+5. **远端推送唯一出口 = "提交并推送"**（`/cbb-worktree-push`，dry-run 预览 → 确认 commit 信息 → push → MR 预填链接）。worktree 创建流程零远端操作（lazy push）。
+6. **开工前必做状态自检**：对 `cbb-local-mode` 说开工（或跑其状态自检）——干净态零交互；**遗留态（上一需求没收尾）必须先由用户决策**（继续 / 收尾 / 升级 / 丢弃）。本地模式一次只承载一个需求；并行需求走 worktree 模式（互不干扰）。
+7. **关联应用增减只改配置**：编辑 `workspace-config.json` 的 `apps` 数组（`name` / `repo` / `side` / `desc`），然后重跑对应模式技能即幂等补齐；不要手工 `git clone` 应用仓库。
+
+## 目录结构与职责
+
+| 路径 | 职责 | 维护方式 |
+|------|----------|----------|
+| `workspace-config.json` | 关联应用清单，所有应用联动的唯一数据源 | 人工编辑（控制面白名单，可直接提交 main） |
+| `.codespace/` | 各应用的**标准本地检出**（基准 = `origin/main`） | `cbb setup` 与技能自动 clone / fetch；本地模式可在其中**切需求分支开发**（main 检出禁改）；已 gitignore，不提交 |
+| `.worktrees/` | 需求隔离开发区（每个需求一个 `worktree-<需求名>/`，内含 AI 配置 junction） | worktree 技能自动创建 / 清理；已 gitignore，不提交 |
+| `openspec/` | OpenSpec 工作流配置（`config.yaml` + `schemas/`） | `config.yaml`/`schemas/` 为控制面白名单（`cbb update` 部署，可直改）；变更产物（`openspec/changes/`）落需求分支随 MR 合入 |
+| `.claude/` `.qoder/` `.opencode/` `.workbuddy/` `.trae/` | AI 工具适配目录：编码规范规则、OpenSpec 命令、技能 | 由 cbb 按 setup 时选择的工具安装（**唯一物理副本在此**）；worktree 内经 junction 引用同一份；已 gitignore，不提交，勿手动改 |
+| `.cbb/` | cbb 安装清单与状态（`.managed-by-cbb`、`.last-tools`） | 由 cbb 管理；**勿手动编辑** |
+
+## 典型流程
+
+```
+需求进来 → 选模式（agent 推荐 + 用户拍板）
+  ├─ 本地模式（单线程快改）：
+  │    /cbb-local-mode（自检 → 确认布局 → 根+涉及 app 就地切分支）
+  │    → 当前会话直接开发：/opsx:propose → apply → verify
+  │    → 说"提交并推送"（push 技能自动发现本地布局）→ MR 预填链接
+  │    → 验收通过 → /opsx:archive → MR 合并 → 收尾（各仓库回 main + 删分支）
+  └─ worktree 模式（并行 / 隔离）：
+       /cbb-worktree-init <需求名>（建分支+worktree+AI 配置 junction，不推远端）
+       → 开发会话开进 .worktrees/worktree-<需求名>/ → opsx 全流程
+       → 说"提交并推送" → MR 预填链接（测试分支）
+       → 测试环境验收 → /opsx:archive → 正式合并走公司流程
+       → 说"关闭工作空间"（/cbb-worktree-close）
+```
+
+> worktree 管理技能（init / close / push）与本地模式技能（cbb-local-mode）均以 **skill 形态**分发：既能被 AI 在对话中按意图**自动触发**（如"为 xxx 创建工作空间"、"本地模式开发"、"提交并推送"、"关闭工作空间"），也能用斜杠命令手动指定（各工具一致）。OpenSpec 命令为 `/opsx:propose`（opencode 扁平化为 `/opsx-propose`）。
+
+---
+
+本文件由 `@jspg-ai/coding-bb` 生成（仅缺失时写入，之后不会覆盖或删除，可自由增补团队约定）。
+
+> ⓘ 本文件仅供导航；开发模式纪律以 cbb 安装的编码规范规则（`cbb-ai-behavior.md` 第 8 条）为准，该规则随 `cbb update` 更新。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jspg-ai/coding-bb",
-  "version": "0.0.3-beta.21",
+  "version": "0.0.3-beta.23",
   "description": "整合业界热门且高价值的工具、框架与技能，为 AI CODING AGENT 提供统一的行为准则与工作流，辅助开发者将需求高效落地为符合规范的代码",
   "main": "cbb/lib/install/init.js",
   "bin": {
@@ -19,7 +19,7 @@
   "scripts": {
     "sync:shared": "node scripts/sync-shared.js",
     "pretest": "node scripts/sync-shared.js --check",
-    "test": "node test/lib/install/cleanup.test.js && node test/lib/utils/settings.test.js && node test/lib/utils/gitignore.test.js && node test/lib/utils/version.test.js && node test/lib/install/workspaces.test.js && node test/lib/utils/checkbox.test.js && node test/lib/utils/output.test.js && node test/lib/install/cli-help.test.js && node test/lib/install/adapters.test.js && node test/lib/wiki/wiki-publish.test.js && node test/lib/wiki/wiki-parse-args.test.js && node test/lib/wiki/wiki-split.test.js && node test/lib/superpowers/superpowers.test.js && node test/worktrees/push-branches.test.js && node test/worktrees/commit-worktrees.test.js && node test/worktrees/push-worktrees.test.js && node test/worktrees/check-env-deep.test.js && node test/worktrees/create-worktrees.test.js && node test/worktrees/make-mr-urls.test.js && node test/lib/install/setup-decision.test.js && node test/lib/openspec/protected-paths.test.js"
+    "test": "node test/lib/install/cleanup.test.js && node test/lib/utils/settings.test.js && node test/lib/utils/gitignore.test.js && node test/lib/utils/githook.test.js && node test/lib/utils/version.test.js && node test/lib/install/workspaces.test.js && node test/lib/utils/checkbox.test.js && node test/lib/utils/output.test.js && node test/lib/install/cli-help.test.js && node test/lib/install/adapters.test.js && node test/lib/wiki/wiki-publish.test.js && node test/lib/wiki/wiki-parse-args.test.js && node test/lib/wiki/wiki-split.test.js && node test/lib/superpowers/superpowers.test.js && node test/worktrees/push-branches.test.js && node test/worktrees/commit-worktrees.test.js && node test/worktrees/push-worktrees.test.js && node test/worktrees/check-env-deep.test.js && node test/worktrees/create-worktrees.test.js && node test/worktrees/make-mr-urls.test.js && node test/lib/install/setup-decision.test.js && node test/lib/openspec/protected-paths.test.js"
   },
   "keywords": [
     "cbb",