aigroup-workflow 1.3.0 → 2.0.1

package/.claude/commands/fix-build.md

@@ -0,0 +1,32 @@
+---
+description: 派遣 build-error-resolver 修复构建/类型/依赖/配置错误，不建 session
+argument-hint: [失败命令；省略则用最近一次 build/typecheck]
+---
+
+# /fix-build
+
+轻量入口：只派 `build-error-resolver`，以最小 diff 让构建变绿。**不做架构调整、不做功能修改、不顺手重构**。
+
+## 使用
+
+```
+/fix-build                  # 主会话从最近的失败诊断
+/fix-build npm run build    # 指定要修复的命令
+/fix-build tsc --noEmit     # typecheck 失败
+```
+
+## 流程
+
+1. 主会话获取失败命令的完整输出（首次出问题就跑一次完整命令，捕获 stderr）
+2. `Agent({ subagent_type: "build-error-resolver", ... })` 派遣，传入：
+   - 失败命令
+   - 完整错误输出
+   - 项目栈（package.json / pyproject.toml / go.mod）
+3. build-error-resolver 按 `.claude/agents/build-error-resolver.md` 输出"修复报告"
+4. 主会话呈现 diff + 重跑证据（同一命令变绿）
+
+## 边界
+
+- 单一命令变绿即停，不顺手修其他失败
+- 不修测试断言（除非断言本身错误且必须报告）
+- 不做依赖大版本升级（除非失败信息明确要求）

package/.claude/commands/git-commit.md

@@ -1,4 +1,4 @@
-你是麦克斯 (Max)，项目经理。现在需要创建一个 Git 提交。
+主会话现在需要创建一个 Git 提交。
 
 ## 任务
 

package/.claude/commands/init-project.md

@@ -1,6 +1,6 @@
 ---
-description: 初始化项目 AI 上下文，生成/更新根级与模块级 CLAUDE.md 索引
-allowed-tools: Read(**), Write(CLAUDE.md, **/CLAUDE.md)
+description: 初始化项目 AI 上下文 — 根 CLAUDE.md 只做导航，详细内容进 docs/
+allowed-tools: Read(**), Write(CLAUDE.md, **/CLAUDE.md, docs/PROJECT_CONTEXT.md, docs/ARCHITECTURE.md)
 argument-hint: <项目摘要或名称>
 ---
 
@@ -8,73 +8,89 @@ argument-hint: <项目摘要或名称>
 
 `/init-project <项目摘要或名称>`
 
-## 目标
+## 落盘策略（铁律）
 
-以"根级简明 + 模块级详尽"的混合策略初始化项目 AI 上下文：
+**根 `CLAUDE.md` 永远只是导航**——一张索引表，记录每份详细文档的位置。≤100 行。**严禁**写入：项目愿景、架构图、模块清单、规范条目、Changelog 等任何"项目内容"。
 
-- 在仓库根生成/更新 `CLAUDE.md`（高层愿景、架构总览、模块索引、全局规范）。
-- 在识别的各模块目录生成/更新本地 `CLAUDE.md`（接口、依赖、入口、测试、关键文件等）。
-- ✨ **为了提升可读性，会在根 `CLAUDE.md` 中自动生成 Mermaid 结构图，并为每个模块 `CLAUDE.md` 添加导航面包屑**。
+详细内容按主题分散到 `docs/` 下：
 
-## ⚠️ aiGroup 框架保护（铁律）
+| 主题 | 落盘文件 |
+|------|----------|
+| 项目愿景 / 模块索引 / Mermaid 结构图 / 运行与开发 / 测试策略 / 变更记录 | `docs/PROJECT_CONTEXT.md` |
+| 架构总览（组件、数据流、跨切关注点、技术选型） | `docs/ARCHITECTURE.md` |
+| 编码规范 / Git / 测试 / 安全 / 性能 / Hooks 强制规则 | `docs/rules/<topic>.md` |
+| 模块级详细信息（入口、接口、依赖、数据模型、FAQ） | `<module>/CLAUDE.md` |
 
-根 `CLAUDE.md` 是 aiGroup 框架的导航入口（≤ 100 行），**绝对禁止**追加项目上下文内容。
+**根 CLAUDE.md 的唯一形态**（无论是否全新项目）：
 
-### 检测方法
+```markdown
+# CLAUDE.md
 
-读取现有根 `CLAUDE.md`，检查以下任一特征标记：
+> 项目 AI 上下文导航。详情见 `docs/`。
 
-- `## 角色：麦克斯 (Max)`
-- `## 全局铁律`
-- `## 行为门控`
-- `## 团队派遣`
+## 项目快照
+- 名称: <name>
+- 主语言 / 栈: <...>
+- 模块数: <n>
 
-### 保护策略
+## 知识库地图
 
-**检测到框架内容**：设置 `preserve_framework=true` 调用 `init-architect`。该代理会把项目上下文写入 `docs/PROJECT_CONTEXT.md`，**不碰**根 `CLAUDE.md`。
+| 需要了解 | 查阅 |
+|---------|------|
+| 项目愿景与模块索引 | `docs/PROJECT_CONTEXT.md` |
+| 架构总览 | `docs/ARCHITECTURE.md` |
+| 强制规则 | `docs/rules/` |
+| 派遣矩阵（若使用 aiGroup 框架）| `docs/rules/agents.md` |
+| 各模块详细信息 | `<module>/CLAUDE.md` |
 
-**未检测到框架内容**（全新项目）：设置 `preserve_framework=false`，按常规方式在根 `CLAUDE.md` 生成完整项目上下文。
+## 模块入口
 
-### 模块级 CLAUDE.md
+| 模块 | 路径 | 一句话职责 |
+|------|------|-----------|
+| ... | ... | ... |
+```
 
-模块级 `<module>/CLAUDE.md` 不受此保护限制，正常生成/更新。
+## Phases
 
-## 编排说明
+### 1. 时间戳
 
-**步骤 1**：调用 `get-current-datetime` 子智能体获取当前时间戳。
+派遣 `get-current-datetime` 获取当前 UTC 时间戳。
 
-**步骤 2**：调用一次 `init-architect` 子智能体，输入：
+### 2. 调度 init-architect
 
-- `project_summary`: $ARGUMENTS
-- `current_timestamp`: (来自步骤1的时间戳)
-- `preserve_framework`: true/false（基于上述检测结果）
+```
+Agent({
+  subagent_type: "init-architect",
+  project_summary: $ARGUMENTS,
+  current_timestamp: <step 1>
+})
+```
 
-## 执行策略（由 Agent 自适应决定，不需要用户传参）
+`init-architect` 负责：
 
-- **阶段 A：全仓清点（轻量）**
-  快速统计文件与目录，识别模块根（package.json、pyproject.toml、go.mod、apps/_、packages/_、services/\* 等）。
-- **阶段 B：模块优先扫描（中等）**
-  对每个模块做"入口/接口/依赖/测试/数据模型/质量工具"的定点读取与样本抽取。
-- **阶段 C：深度补捞（按需）**
-  若仓库较小或模块规模较小，则扩大读取面；若较大，则对高风险/高价值路径分批追加扫描。
-- **覆盖率度量与可续跑**
-  输出"已扫描文件数 / 估算总文件数、已覆盖模块占比、被忽略/跳过原因"，并列出"建议下一步深挖的子路径"。重复运行 `/init-project` 时按上次索引做**增量更新**与**断点续扫**。
+- 自适应三档扫描（全仓清点 → 模块优先 → 深度补捞），自决读取深度与断点续扫
+- 写入 `docs/PROJECT_CONTEXT.md`（项目愿景、Mermaid 结构图、模块索引、运行/测试策略、Changelog）
+- 写入 `docs/ARCHITECTURE.md`（架构总览：组件、数据流、跨切关注点）
+- 写入各模块 `<module>/CLAUDE.md`（顶部带相对路径面包屑）
+- 写入 / 更新根 `CLAUDE.md` 为**纯导航形态**——若已存在内容是项目内容（非导航）则保留不动，新内容并入 `docs/PROJECT_CONTEXT.md`
+- 写入 `.claude/index.json`（扫描元数据 + 覆盖率 + 缺口清单）
 
-## 安全与边界
+### 3. 摘要回报
 
-- 只读/写文档与索引，不改源代码。
-- 默认忽略常见生成物与二进制大文件。
-- 结果在主对话打印"摘要"，全文写入仓库。
-- **绝不覆盖 aiGroup 框架内容**（角色定义、工作流管道、派遣规则等）。
+从 agent 返回体中提取并打印：
 
-## 输出要求
+- 根 `CLAUDE.md` 状态：新建（导航模板）/ 已存在（保留不动）
+- `docs/PROJECT_CONTEXT.md` 是否创建/更新（含主要章节）
+- `docs/ARCHITECTURE.md` 是否创建/更新
+- 识别的模块数量与路径
+- 每个模块 `CLAUDE.md` 的生成/更新情况
+- ✨ Mermaid 结构图与面包屑导航是否生成
+- 覆盖率与主要缺口
+- 若被上限截断：列出下一步推荐补扫路径
 
-- 在主对话中打印"初始化结果摘要"，包含：
-  - 根级 CLAUDE.md 保护状态（preserve_framework 值；是否已检测并跳过写入）。
-  - `docs/PROJECT_CONTEXT.md` 是否创建/更新、主要栏目概览。
-  - ✨ **是否检测到 aiGroup 框架并已保护**（明确说明）。
-  - 识别的模块数量及其路径列表。
-  - 每个模块 `CLAUDE.md` 的生成/更新情况。
-  - ✨ **明确提及"已生成 Mermaid 结构图"和"已为 N 个模块添加导航面包屑"**。
-  - 覆盖率与主要缺口。
-  - 若未读全：说明"为何到此为止"，并列出**推荐的下一步**（例如"建议优先补扫：packages/auth/src/controllers"）。
+## 硬约束（由 init-architect 执行）
+
+- 只读/写文档与 `.claude/index.json`，不改源代码
+- 默认忽略 `node_modules/`、`.git/`、构建产物、二进制
+- **根 `CLAUDE.md` 只能是导航形态**；若现有内容非导航（含项目愿景 / 架构 / 模块详情等），保留不动并把新内容追加到 `docs/PROJECT_CONTEXT.md`
+- 时间戳来自 step 1，不由 agent 自行生成

package/.claude/commands/plan.md

@@ -0,0 +1,32 @@
+---
+description: 派遣 planner agent 输出实施计划，不建 session
+argument-hint: <任务描述>
+---
+
+# /plan
+
+轻量入口：只派 `planner`，不创建 orchestration session。适合**已知需求、需要拆解步骤**的中小型任务。
+
+## 使用
+
+`/plan $ARGUMENTS`
+
+## 流程
+
+1. 主会话用 `Agent({ subagent_type: "planner", ... })` 派遣 planner，传入：
+   - 任务描述（`$ARGUMENTS`）
+   - 当前 git 状态摘要（`git status` + `git log --oneline -10`）
+2. planner 按 `.claude/agents/planner.md` 的输出格式产出实施计划
+3. 主会话把计划呈现给用户，等待 CONFIRM 后再实施
+4. **不要**自动开始实施——计划是讨论稿，不是执行令
+
+## 与 `/workflow-start` 的区别
+
+| 维度 | `/plan` | `/workflow-start` |
+|------|---------|-------------------|
+| 是否建 session | 否 | 是 |
+| 适用规模 | 单 agent 输出即够 | 涉及 ≥2 个 worker 协作 |
+| 后续流程 | 用户自决，不强制 phase 链 | 8 phase 心智模型 |
+| 产物归属 | 直接呈现给用户 | `.orchestration/<session>/<worker>/handoff.md` |
+
+何时升级到 `/workflow-start`：planner 输出后用户判断需要多 worker 协作（如同时要架构决策 + 测试规划），可手动 `node scripts/orchestration/session.cjs init <name>` 升级。

package/.claude/commands/review.md

@@ -0,0 +1,29 @@
+---
+description: 派遣 code-reviewer agent 审查当前改动，不建 session
+argument-hint: [文件 / 范围；省略则审 git diff]
+---
+
+# /review
+
+轻量入口：只派 `code-reviewer`，输出双阶段审查（Stage 1 规格符合性 + Stage 2 代码质量）。
+
+## 使用
+
+```
+/review                 # 审 git diff（HEAD vs working）
+/review src/auth/       # 审指定路径
+/review HEAD~3..HEAD    # 审某个 commit 区间
+```
+
+## 流程
+
+1. 主会话识别审查范围（`$ARGUMENTS` 或 `git diff --name-only HEAD`）
+2. `Agent({ subagent_type: "code-reviewer", ... })` 派遣，传入：
+   - 范围内变更文件清单
+   - 计划/PRD（如有）作为 Stage 1 基准
+3. code-reviewer 按 `.claude/agents/code-reviewer.md` 的输出格式产出 **Stage 1 + Stage 2** 报告
+4. 主会话呈现报告；安全敏感（auth/支付/PII）发现时建议追加派 `security-reviewer`
+
+## 与 `/workflow-start` 的区别
+
+`/review` 是"审一下"——不写 handoff、不进 session。如果是工作流中的 phase 6（测试验证），用 `/workflow-start` 走完整流程，code-reviewer 的产物会写入 `.orchestration/<session>/code-reviewer/handoff.md`。

package/.claude/commands/tdd.md

@@ -0,0 +1,32 @@
+---
+description: TDD 流程：派 tdd-guide 走 Red → Green → Refactor，不建 session
+argument-hint: <功能描述>
+---
+
+# /tdd
+
+轻量 TDD 流程：Red → Green → Refactor。**不建 session**，直接派 `tdd-guide` 端到端处理。
+
+## 使用
+
+`/tdd $ARGUMENTS`
+
+## 流程
+
+`Agent({ subagent_type: "tdd-guide", ... })` 派遣，传入：
+
+- 功能描述（`$ARGUMENTS`）
+- 项目栈与现有测试约定
+- 任务：先写失败测试 → 写最小实现 → 测试变绿 → 必要时重构
+
+`tdd-guide` 内部完成 Red-Green-Refactor 循环，主会话不需要再分阶段拆派。
+
+主会话验证：让 `tdd-guide` 在最终响应中附 **测试全绿的证据**（命令 + 输出）。
+
+## 后续审查
+
+代码变更落定后，建议再派 `code-reviewer`（必要时加 `security-reviewer`）做双阶段审查。
+
+## 与 `/workflow-start` 的区别
+
+`/tdd` 适合**已知功能边界**的小到中型增量。如果还需要架构决策或跨模块协作，先 `/plan` 或 `/workflow-start`。

package/.claude/commands/workflow-start.md

@@ -0,0 +1,87 @@
+---
+description: 启动一个分阶段工作流会话，按需裁剪 phase 并派遣专项 agent
+argument-hint: <任务名>
+---
+
+## 用法
+
+`/workflow-start <任务名>`
+
+主会话作为唯一的 orchestrator，按以下 phase 推进任务；**每个 phase 按需裁剪**——不是所有任务都要跑完 8 phase（bugfix 可能只需要 planning + development + testing）。
+
+## 启动步骤
+
+1. **确认任务名**——若 `$ARGUMENTS` 为空，向用户询问 slug 化的短名（如 `refactor-auth`、`add-payment`）。
+2. **创建 session**：
+
+   ```bash
+   node scripts/orchestration/session.cjs init <任务名>
+   ```
+
+3. **评估裁剪**：读完需求后明确告诉用户"这个任务会跑哪些 phase，为什么"。
+
+## Phases（按需裁剪）
+
+每个 phase 都按这个格式执行：
+
+- **目标**一句话说明
+- **负责 agent**（用 `Agent({ subagent_type: "..." })` 派遣；主会话不亲自实现）
+- **worker 目录**：`.orchestration/<session>/<worker>/`
+- **产物**：主会话把 agent 响应写入 `handoff.md`，然后 `session.cjs set-status <session> <worker> completed`
+
+| # | Phase | 负责 agent / skill | worker 目录 |
+|---|-------|--------------------|-------------|
+| 1 | 需求收集 | 主会话 + `skills/requirement-engineering` | `.orchestration/<session>/architect/` (requirements.md) |
+| 2 | 需求验证 | 主会话 + `skills/requirement-engineering` | 同上，追加验证结论 |
+| 3 | 方案设计 | `architect` | `.orchestration/<session>/architect/handoff.md` |
+| 4 | 任务拆解 | `planner` | `.orchestration/<session>/planner/handoff.md` |
+| 5 | 实施开发（TDD） | `tdd-guide` | `.orchestration/<session>/tdd-guide/handoff.md` |
+| 6 | 测试验证 | `code-reviewer`（安全敏感加 `security-reviewer`、`e2e-runner` 或 `rust-reviewer` 等） | `.orchestration/<session>/code-reviewer/handoff.md` |
+| 7 | 文档更新 | 主会话（必要时派实现 agent 协助） | 直接改 docs/；在 session README 留笔记 |
+| 8 | 分支收尾 | 主会话 + `skills/finishing-a-development-branch` | 在 session README 总结 |
+
+## 裁剪示例
+
+| 任务类型 | 建议 phases |
+|---------|------------|
+| 纯 bugfix | 4 → 5 → 6 |
+| 小功能增补 | 3 → 4 → 5 → 6 |
+| 新模块 / 架构决策 | 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 |
+| 重构 | 3 → 4 → 5 → 6 |
+| 纯文档 | 7（直接做，不用走 session） |
+
+## 状态真相源
+
+唯一真相源是 `.orchestration/<session>/<worker>/status.md`（由 `session.cjs set-status` 维护）。不要引入第二个状态机。
+
+## 横切 skill（任何 phase 可触发）
+
+- `skills/systematic-debugging`（调试时）
+- `skills/verification-before-completion`（声称完成前）
+- `skills/entropy-management`（感知到漂移时）
+
+## 不启动 session 的情况
+
+- 单行修改、配置项调整、文档笔误 —— 直接做
+- 纯知识问答、方案讨论 —— 直接答
+- 探索性代码调研 —— 直接读文件即可
+
+判断标准：如果**没有 ≥2 个 worker 产物**、也**没有需要事后追溯的证据链**，就不要建 session。
+
+## 命令矩阵（按任务规模选）
+
+| 命令 | 是否建 session | 适用任务 |
+|------|---------------|---------|
+| 直接对话 | 否 | 笔误、单行修改、知识问答 |
+| `/plan <任务>` | 否 | 已知需求，需要拆步骤 |
+| `/review` | 否 | 审一下 git diff |
+| `/fix-build` | 否 | 修构建/类型错误 |
+| `/tdd <功能>` | 否 | TDD 增量开发 |
+| `/workflow-start <任务名>` | **是** | 需要 ≥2 个 worker 协作、需追溯证据链 |
+| `/init-project <名称>` | 否 | 项目初始化（生成 CLAUDE.md 索引） |
+
+## 参考
+
+- 派遣规则：`docs/rules/agents.md`
+- 危险信号：`docs/red-flags.md`
+- Phase 心智模型：`docs/workflow-pipeline.md`

package/.claude/hooks.json

@@ -5,7 +5,7 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash scripts/harness/hook-post-edit.sh",
+          "command": "node scripts/hooks/dispatcher.cjs post-edit",
           "timeout": 10
         }
       ]
@@ -17,7 +17,7 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash scripts/harness/hook-stop.sh",
+          "command": "node scripts/hooks/dispatcher.cjs stop",
           "timeout": 30
         }
       ]
@@ -29,7 +29,7 @@
       "hooks": [
         {
           "type": "command",
-          "command": "bash scripts/harness/hook-subagent-stop.sh",
+          "command": "node scripts/hooks/dispatcher.cjs subagent-stop",
           "timeout": 15
         }
       ]

package/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "aigroup-workflow",
+  "version": "1.3.0",
+  "description": "AI team workflow harness for Claude Code — specialist agents, shared skills, slash commands, hooks, and staged delegation pipeline.",
+  "author": {
+    "name": "shuaishuai-li"
+  },
+  "repository": "https://github.com/shuaishuai-li/ai-agent-workflowGroup",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "agents",
+    "skills",
+    "workflow",
+    "harness",
+    "ai-team"
+  ],
+  "skills": ["./skills/"],
+  "commands": ["./.claude/commands/"]
+}

package/.codex/AGENTS.md

@@ -0,0 +1,107 @@
+# aiGroup for Codex CLI
+
+> 本文件是根 `AGENTS.md` 的 Codex 专属补充。**agent 派遣规则与 Claude Code 端共享一份**——见 `docs/rules/agents.md`。
+> 本文件只讲 Codex 端独有的：模型 / Skills 加载方式 / MCP / Codex 原生 persona / 无 hook 兜底。
+
+## 模型推荐
+
+| 任务类型 | 推荐模型 |
+|----------|----------|
+| 常规编码、测试、格式化 | GPT 5.4 |
+| 复杂功能、架构 | GPT 5.4 |
+| 代码审查、安全 | GPT 5.4（reasoning_effort = high） |
+| 只读探索、文档研究 | GPT 5.4（reasoning_effort = medium） |
+
+## Skills 加载
+
+Skills 主源位于 `skills/<name>/SKILL.md`，跨平台共享。Codex 端**按任务意图加载文件路径**——不像 Claude Code 那样自动发现。
+
+常用入口：
+
+- `skills/writing-plans/SKILL.md` — 规划
+- `skills/requirement-engineering/SKILL.md` — 需求收集与验证
+- `skills/architecture-designer/SKILL.md` — 架构设计
+- `skills/api-designer/SKILL.md` — API 契约
+- `skills/code-reviewer/SKILL.md` — 代码审查
+- `skills/security-reviewer/SKILL.md` — 安全审查
+- `skills/tdd-guide/SKILL.md` / `skills/test-master/SKILL.md` — 测试
+- `skills/systematic-debugging/SKILL.md` — 调试
+- `skills/verification-before-completion/SKILL.md` — 完成前验证
+
+完整分类见 `manifests/install-modules.json`。
+
+## Codex 原生 Persona
+
+`.codex/config.toml` 声明的 3 个 persona——**不是和 Claude agent 一一映射**，而是 Codex 自身需要"切换 sandbox / reasoning_effort"才生效的场景：
+
+| Persona | 用途 |
+|---------|------|
+| `explorer` | 只读 sandbox，证据收集与执行路径追踪 |
+| `reviewer` | 高 reasoning，代码 + 安全审查 |
+| `docs_researcher` | API / 文档 / 版本行为查证（带网络访问） |
+
+切换方式：
+
+```bash
+/agent explorer
+/agent reviewer
+/agent docs_researcher
+```
+
+**其他工作（planning / implementation / build-fixing）由 Codex 主对话直接做**——加载对应 skill 即可，无需切 persona。这也是与 ECC 一致的做法。
+
+## MCP 服务器
+
+项目级基线（`.codex/config.toml`）启用：GitHub、Context7、Memory、Sequential-Thinking。
+
+预算规则见 `docs/rules/performance.md`：单项目启用 MCP 少于 10 个，活跃工具少于 80 个。Playwright / Exa 按需取消注释。重型服务器（Supabase、Firecrawl、Cloudflare）推荐放到用户级 `~/.codex/config.toml`，不要进入项目默认必启基线。
+
+## 与 Claude Code 的关键差异
+
+| 特性 | Claude Code | Codex CLI |
+|------|-------------|-----------|
+| Hooks | 自动触发 PostToolUse / Stop / SubagentStop | **不支持** —— 必须主动运行 dispatcher |
+| Skill 发现 | 启动时自动加载 `skills/` | 按路径手动加载 |
+| 命令 | `/slash` commands（`.claude/commands/`） | 主对话指令 + `/agent <persona>` |
+| 子代理派遣 | `Agent({ subagent_type })` 工具调用 | 主对话直接对话；persona 通过 `/agent` 切换 |
+| 安全强制 | Hook + 指令 | 指令 + sandbox 模式（`read-only` / `workspace-write`） |
+| MCP | 完整支持 | `config.toml` 或 `codex mcp add` |
+
+## 无 Hooks 的兜底强制
+
+Codex 端必须**主动**执行以下动作（Claude Code 由 hooks 自动）：
+
+1. 任何变更完成 → 跑 `node scripts/hooks/dispatcher.cjs stop`
+2. 进入 reviewer persona 审完代码 → 跑 `node scripts/hooks/dispatcher.cjs subagent-stop`
+3. 安全敏感代码（auth / 支付 / PII / 外部输入）→ 强制走 reviewer persona，不能跳过
+4. 提交前跑 `npm audit` / `pip-audit` / `bundle audit`
+5. `git diff` 人肉过一遍再推
+
+## 常用命令
+
+```bash
+# 进入项目
+codex
+
+# 指定 profile（严格只读 / 放任修改）
+codex -p strict
+codex -p yolo
+
+# 切换到 persona
+/agent explorer
+/agent reviewer
+/agent docs_researcher
+
+# MCP 检查
+codex mcp list
+```
+
+## 完整 agent 派遣表
+
+参见 `docs/rules/agents.md`——agent 体系**两端共享**，没有"对照映射表"。Codex 端要派"等价于 Claude `tdd-guide`"的工作时：
+
+- 切回主对话（不需要 persona）
+- 加载 `skills/tdd-guide/SKILL.md` + 对应框架 / 栈 skill（如 `skills/react-expert/SKILL.md`）
+- 按 rules/agents.md 中 `tdd-guide` 的输出格式执行
+
+审查工作走 `reviewer` persona，调研走 `explorer` persona，文档查证走 `docs_researcher` persona——这三个是 Codex 因 sandbox / reasoning 配置不同**才需要**切换的场景。

package/.codex/agents/docs-researcher.toml

@@ -0,0 +1,14 @@
+model = "gpt-5.4"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+You are the aiGroup Codex docs researcher.
+
+Verify API, framework, and third-party library behavior against authoritative sources.
+- Use web_search and context7 MCP when available to confirm current behavior.
+- Check official docs, release notes, and breaking-change lists before answering.
+- Cite the source URL and version for every non-trivial claim.
+- Do NOT write code; produce a concise research memo with: question, source, answer, impact on the current task.
+- Flag any deprecated APIs or version mismatches against project dependencies.
+"""

package/.codex/agents/explorer.toml

@@ -0,0 +1,14 @@
+model = "gpt-5.4"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+You are the aiGroup Codex explorer.
+
+Stay in exploration mode. Gather evidence only — do not propose fixes unless the parent agent asks.
+- Read AGENTS.md first.
+- Trace real execution paths; cite files and line numbers.
+- Prefer targeted search (rg) and file reads over broad scans.
+- Return findings as a structured report: files touched, key symbols, call sites, suspected risk surface.
+- Load skills by task intent, not by legacy role (e.g. skills/systematic-debugging/SKILL.md).
+"""

package/.codex/agents/reviewer.toml

@@ -0,0 +1,16 @@
+model = "gpt-5.4"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+You are the aiGroup Codex reviewer.
+
+Review like an owner. Report findings only; do not rewrite code.
+- Prioritize correctness, behavioral regressions, missing tests, and security issues.
+- Lead with concrete findings citing file paths and line numbers.
+- Confidence filter: report only when >80% sure it is a real issue.
+- Consolidate similar issues; skip pure style preferences.
+- For security-sensitive areas (auth, payments, PII, external input), load skills/security-reviewer/SKILL.md and apply OWASP Top 10 check.
+- Output: findings grouped by severity (CRITICAL/HIGH/MEDIUM/LOW), followed by a verdict — APPROVE / REQUEST_CHANGES / BLOCK.
+- Include validation evidence (test results, audit output) when relevant.
+"""