aigroup-workflow 1.2.7 → 2.0.0

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.
+"""

package/.codex/config.toml

@@ -0,0 +1,93 @@
+#:schema https://developers.openai.com/codex/config-schema.json
+
+# aiGroup — Codex 本地配置
+#
+# 用法：
+# - 拷贝到 ~/.codex/config.toml 作为全局默认
+# - 或保留在项目根 .codex/config.toml 作为项目级配置
+#
+# 文档参考：
+# - https://developers.openai.com/codex/config-reference
+# - https://developers.openai.com/codex/multi-agent
+
+# ---------- Runtime ----------
+# model / model_provider 留空，使用 Codex CLI 当前默认，除非明确要固定版本
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+web_search = "live"
+
+# ---------- Persistent Instructions ----------
+# 持久指令在每次 prompt 后追加（与 model_instructions_file 替换不同）
+persistent_instructions = """
+Follow project AGENTS.md as the source of truth.
+Load skills by task intent, not by role ownership.
+aiGroup has retired the legacy three-role model (ella/jarvis/kyle) — do not delegate by those names.
+Use the multi-agent roles declared below for exploration, planning, implementation, review, build fixing, and docs research.
+"""
+
+# ---------- MCP Servers ----------
+# aiGroup 项目级精简基线。遵守 docs/rules/performance.md：
+# 单项目启用 MCP < 10，活跃工具 < 80；重型服务器放到用户级配置按需叠加。
+[mcp_servers.github]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-github"]
+startup_timeout_sec = 30
+
+[mcp_servers.context7]
+command = "npx"
+args = ["-y", "@upstash/context7-mcp@latest"]
+startup_timeout_sec = 30
+
+[mcp_servers.memory]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-memory"]
+startup_timeout_sec = 30
+
+[mcp_servers.sequential-thinking]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+startup_timeout_sec = 30
+
+# 按需取消注释：
+# [mcp_servers.playwright]
+# command = "npx"
+# args = ["-y", "@playwright/mcp@latest", "--extension"]
+# startup_timeout_sec = 30
+#
+# [mcp_servers.exa]
+# url = "https://mcp.exa.ai/mcp"
+
+# ---------- Features ----------
+[features]
+multi_agent = true
+
+# ---------- Profiles ----------
+# 切换：codex -p <name>
+[profiles.strict]
+approval_policy = "on-request"
+sandbox_mode = "read-only"
+web_search = "cached"
+
+[profiles.yolo]
+approval_policy = "never"
+sandbox_mode = "workspace-write"
+web_search = "live"
+
+# ---------- Codex 原生 Persona ----------
+# 仅保留 Codex 自身需要"切换 persona"的 3 个场景。
+# 其他工作（planning / implementation / build-fixing）由 Codex 主对话 + 加载对应 skill 完成。
+[agents]
+max_threads = 3
+max_depth = 1
+
+[agents.explorer]
+description = "Read-only codebase explorer for gathering evidence before changes are proposed."
+config_file = "agents/explorer.toml"
+
+[agents.reviewer]
+description = "Code, security, and test-gap reviewer. Prioritizes correctness and regressions."
+config_file = "agents/reviewer.toml"
+
+[agents.docs_researcher]
+description = "API, framework, and release-note verification via documentation sources."
+config_file = "agents/docs-researcher.toml"

package/.codex-plugin/plugin.json

@@ -0,0 +1,33 @@
+{
+  "name": "aigroup-workflow",
+  "version": "1.3.0",
+  "description": "Codex-ready aiGroup workflows — shared skills, AGENTS.md guidance, Codex personas, and staged delegation for AI team collaboration.",
+  "author": {
+    "name": "shuaishuai-li"
+  },
+  "repository": "https://github.com/shuaishuai-li/ai-agent-workflowGroup",
+  "license": "MIT",
+  "keywords": [
+    "codex",
+    "agents",
+    "skills",
+    "workflow",
+    "ai-team",
+    "multi-agent"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.codex/config.toml",
+  "interface": {
+    "displayName": "aiGroup Workflow",
+    "shortDescription": "Shared skills plus Codex/Claude Code adapters for AI team workflows.",
+    "longDescription": "aiGroup provides a dual-harness AI collaboration framework. Specialist agents replace the legacy designer/developer/QA role triad; skills live as the canonical cross-platform workflow surface. Codex gets 3 native personas (explorer/reviewer/docs_researcher); Claude Code gets full specialist agents, slash commands, and hook automation.",
+    "category": "Productivity",
+    "capabilities": ["Read", "Write"],
+    "defaultPrompt": [
+      "Read AGENTS.md first; the agent dispatch table is shared with Claude Code in docs/rules/agents.md.",
+      "Load skills by task intent (skills/<name>/SKILL.md), not by legacy role ownership.",
+      "Switch to reviewer persona for correctness, security, and test gaps before completion.",
+      "For build/typecheck failures, load skills/systematic-debugging in main chat — no separate persona needed."
+    ]
+  }
+}

package/AGENTS.md

@@ -0,0 +1,76 @@
+# AGENTS.md
+
+> 平台中立的 agent 协作入口。Codex CLI 与其他 harness 读本文件；Claude Code 读 `CLAUDE.md`。
+> 两端共享主源：`agents/` / `skills/` / `docs/` / `scripts/`。
+
+## Project Overview
+
+aiGroup is a **dual-harness AI team collaboration framework**. The main agent decomposes requirements and delegates to specialist agents. It does NOT directly write code, design UI, or run tests.
+
+## Architecture
+
+| 目录 | 内容 |
+|------|------|
+| `agents/` | **agent 源池**（52 个，开发态分发位置） |
+| `skills/` | **skill 源池**（扁平 `skills/<name>/SKILL.md`） |
+| `commands/` | 斜杠命令源 |
+| `.claude/agents/` | Claude Code 实际启用的 agent（由 `aigroup init` 按需复制） |
+| `.codex/agents/` | Codex 原生 persona TOML（3 个：explorer / reviewer / docs_researcher） |
+| `.codex/config.toml` | Runtime + MCP + persona 配置 |
+| `docs/` | 知识库主源（架构、规则、流程） |
+| `docs/rules/` | 强制规则集（agents / coding-style / git-workflow / testing / security / performance / hooks） |
+| `manifests/` | 安装清单（agent / skill 分组） |
+| `.orchestration/<session>/` | Agent 协作产物工作区 |
+| `scripts/orchestration/` | 协调 CLI（session.cjs） |
+| `scripts/hooks/` | hook dispatcher + checks（Codex 端需手动调用） |
+
+## Available Agents
+
+源池 `agents/<name>.md` 共 52 个，由 `aigroup init` 按 manifest 模块选择安装：
+
+| 模块 | 默认 | 数量 | 说明 |
+|------|------|------|------|
+| `agents-core` | ✅ | 12 | ECC 派遣规则的 10 个 + init-architect / get-current-datetime |
+| `agents-quality` | ⏤ | 9 | 代码质量分析 |
+| `agents-language` | ⏤ | 16 | 各语言 reviewer / build-resolver |
+| `agents-ops` | ⏤ | 8 | 运维与工作流操作 |
+| `agents-domain` | ⏤ | 9 | 特殊领域（a11y / healthcare / opensource / gan-* / seo） |
+
+详细派遣矩阵见 `docs/rules/agents.md`。
+
+> **agent 体系两端共享一份**——不存在"Claude 专项 agent vs Codex role adapter"对照表。Codex 端在主对话中加载对应 skill 即可达成同样效果。
+
+## Codex 端独有
+
+`.codex/agents/` 下的 3 个 persona TOML 是 **Codex 原生 multi-agent 机制**，仅在需要切换 sandbox / reasoning_effort 时使用：
+
+| Persona | 用途 |
+|---------|------|
+| `explorer` | 只读 sandbox，证据收集 |
+| `reviewer` | 高 reasoning，代码 + 安全审查 |
+| `docs_researcher` | 带网络访问，API / 文档查证 |
+
+切换：`/agent <persona>`。完整 Codex 端说明见 `.codex/AGENTS.md`。
+
+## 知识库地图
+
+| 需要了解 | 查阅 |
+|---------|------|
+| Agent 派遣矩阵 | `docs/rules/agents.md` |
+| 强制规则（铁律 / 编码 / Git / 测试 / 安全 / 性能 / Hooks） | `docs/rules/` |
+| Codex 端差异（模型 / MCP / persona / 无 hook 兜底） | `.codex/AGENTS.md` |
+| 工作流 phase 心智模型 | `docs/workflow-pipeline.md` |
+| 危险信号 | `docs/red-flags.md` |
+| 项目实例上下文 | `docs/PROJECT_CONTEXT.md` |
+
+## Codex 限制（必须知道）
+
+- **No hooks** — Codex 不支持 hook 事件；必须主动运行 `node scripts/hooks/dispatcher.cjs stop`
+- **No slash commands** — 用主对话 + `/agent <persona>`，不识别 `.claude/commands/`
+- **No `Agent({ subagent_type })` 语法** — 派遣 = 主对话加载对应 skill；persona 切换 = `/agent`
+
+详见 `.codex/AGENTS.md`。
+
+## Claude Code 兼容
+
+Claude Code 用户使用 `CLAUDE.md` 作为入口，通过 `Agent({ subagent_type })` 派遣安装在 `.claude/agents/` 下的 agent。两端的派遣规则都以 `docs/rules/agents.md` 为唯一事实源。

package/CLAUDE.md

@@ -1,86 +1,29 @@
-# 角色：麦克斯 (Max) — 项目经理
+# CLAUDE.md
 
-你是麦克斯 (Max)，项目经理兼用户个人助理。不直接写代码、做设计或做测试，价值在于需求分析、任务拆解、驱动工作流、进度跟踪、风险预警、熵管理，以及通过 Agent 工具派遣子代理整合成果。
+This file provides guidance to Claude Code when working in this repository.
 
-## 全局铁律
+## Project Overview
 
-```
-1. 证据优于断言 — 任何完成声明必须附带验证证据
-2. 流程不可跳过 — 工作流管道的每个环节必须走完
-3. 不确定时先问 — 宁可多问一句，不要假设
-4. 门控先行 — 派遣子 Agent 前必须执行状态机门控检查
-```
+aiGroup is a **dual-harness AI team collaboration framework** (Claude Code + Codex). The main session analyzes requirements, decomposes tasks, and **delegates to specialist subagents** — it does NOT directly write code, design UI, or run tests.
 
-## 行为门控（每次任务必读）
+| 目录 | 内容 |
+|------|------|
+| `agents/` | Agent 源池（开发态分发位置，由 `aigroup init` 选装到 `.claude/agents/`） |
+| `skills/` | Skill 源池（扁平 `skills/<name>/SKILL.md`） |
+| `docs/` | 知识库主源 |
+| `manifests/` | 安装清单（agent / skill 分组定义） |
+| `.orchestration/<session>/` | Agent 协作产物工作区（按 session/worker 三件套） |
+| `scripts/orchestration/session.cjs` | 协调 CLI |
+| `scripts/hooks/dispatcher.cjs` | hook dispatcher（手动调用入口） |
 
-收到非简单任务时，Max **必须**用状态机驱动 8 阶段流程，不可跳步：
-
-```
-简单任务 → workflow-state.sh exempt <原因>
-非简单任务 → workflow-state.sh init <名称> → 按阶段读取 SKILL → 产出产物 → advance
-  需求收集 → 需求验证 → 方案设计 → 任务拆解 → 实施开发 → 测试验证 → 文档更新 → 分支收尾
-```
-
-**禁止**：design 完成前派遣 Jarvis；planning 完成前派遣 Jarvis；development 完成前派遣 Kyle
-
-状态机命令 → `scripts/harness/workflow-state.sh`（status/init/advance/gate/reset/exempt）
-
-简单任务豁免：纯知识问答、单行修改、配置调整、文档笔误。判断标准：涉及 2+ 文件或设计决策就走完整管道。
-
-**豁免 ≠ 自己动手**：豁免的是 8 阶段流程，不是派遣规则。涉及代码、设计、测试或验证，无论任务大小，必须派遣对应子 Agent（Jarvis/Ella/Kyle）执行，禁止在当前对话中角色切换。
-
-## 知识库地图
+## 知识库地图（按需查阅）
 
 | 需要了解 | 查阅 |
 |---------|------|
+| Agent 派遣规则（什么时候派谁、并行、多视角） | `docs/rules/agents.md` |
+| 通用强制规则（编码 / Git / 测试 / 安全 / 性能 / Hooks） | `docs/rules/` |
+| 各语言专项规则（cpp / golang / java / python / rust / typescript / web 等） | `docs/rules/<lang>/` |
 | 项目架构、目录结构 | `docs/ARCHITECTURE.md` |
-| 工作流管道详细规则 | `docs/workflow-pipeline.md` |
-| 团队成员与派遣规则 | `docs/dispatch-rules.md` |
-| Git/代码/注释规范 | `docs/coding-standards.md` |
+| 工作流 phase 心智模型 | `docs/workflow-pipeline.md` |
 | 危险信号与阻止行动 | `docs/red-flags.md` |
-| 质量评分与健康度追踪 | `docs/QUALITY_SCORE.md` |
-| 技术债追踪 | `docs/tech-debt-tracker.md` |
-| Harness 转向循环 | `docs/steering-loop.md` |
-
-## 工作流技能
-
-| 阶段 | 技能 | 路径 |
-|------|------|------|
-| 需求收集 | brainstorming | `skills/max/workflow/brainstorming/` |
-| 需求验证 | requirement-validation | `skills/max/workflow/requirement-validation/` |
-| 方案设计 | solution-design | `skills/max/workflow/solution-design/` |
-| 任务拆解 | writing-plans | `skills/max/workflow/writing-plans/` |
-| 实施开发 | subagent-driven-development | `skills/max/workflow/subagent-driven-development/` |
-| 测试验证 | testing | `skills/max/workflow/testing/` |
-| 文档更新 | documentation | `skills/max/workflow/documentation/` |
-| 分支收尾 | finishing-a-development-branch | `skills/max/workflow/finishing-a-development-branch/` |
-
-横切技能：systematic-debugging、verification-before-completion、entropy-management
-
-### PM 辅助技能
-
-| 场景 | 技能 | 路径 |
-|------|------|------|
-| 竞品分析 | competitive-analysis | `skills/max/competitive-analysis/` |
-| 会议纪要 | meeting-notes | `skills/max/meeting-notes/` |
-| PRD 撰写 | prd-template | `skills/max/prd-template/` |
-| 干系人汇报 | stakeholder-update | `skills/max/stakeholder-update/` |
-| 用户研究综合 | user-research-synthesis | `skills/max/user-research-synthesis/` |
-
-## 团队派遣（Agent 工具）
-
-三人已注册为 Claude Code 原生子代理（`.claude/agents/{ella,jarvis,kyle}.md`），用 `subagent_type` 派遣：
-
-| 成员 | 角色 | 派遣方式 |
-|------|------|---------|
-| 艾拉 (Ella) | UI/UX 设计师 | `Agent({ subagent_type: "ella", description: "...", prompt: "..." })` |
-| 贾维斯 (Jarvis) | 全栈开发 | `Agent({ subagent_type: "jarvis", description: "...", prompt: "..." })` |
-| 凯尔 (Kyle) | 质量保障（测试+验证） | `Agent({ subagent_type: "kyle", description: "...", prompt: "..." })` |
-
-产物工作区：`.dev-agents/shared/`（`designs/ tasks/ reviews/ templates/`）
-
-## Harness 自检
-
-开发完成后运行 `scripts/harness/run-all.sh`，按 [FAIL] 提示的 [FIX] 修复直至全部通过。
-
-<!-- aiGroup 框架边界（init-architect 保留区至此，以下由 /init-project 生成） -->
+| 项目实例上下文（/init-project 生成） | `docs/PROJECT_CONTEXT.md` |