aigroup-workflow 1.3.0 → 2.0.0

package/cli/utils/scaffold.mjs

@@ -1,101 +1,153 @@
 /**
  * 脚手架工具 — 文件复制、配置管理、模板变量替换
+ *
+ * Phase 4 起本模块由 manifests/install-modules.json 驱动安装内容：
+ * - skill 安装不再按三角色，而是按模块（workflow / product / design / engineering / quality）
+ * - Claude / Codex 的适配层文件分组独立装
  */
 
 import { existsSync, mkdirSync, readdirSync, statSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs'
-import { join, relative, dirname } from 'node:path'
+import { join, dirname } from 'node:path'
 
-// ─── 框架资产清单 ───
-// 定义从包根目录复制到用户项目的文件映射
+// ─── 基础文件（必装） ───
 
-/** 基础文件（必装） */
+/** 双端共享的入口与主源文档 */
 export const BASE_FILES = [
   'CLAUDE.md',
-  'docs/ARCHITECTURE.md',
+  'AGENTS.md',
   'docs/README.md',
   'docs/workflow-pipeline.md',
-  'docs/dispatch-rules.md',
-  'docs/coding-standards.md',
   'docs/red-flags.md',
-  'docs/QUALITY_SCORE.md',
-  'docs/tech-debt-tracker.md',
-  'docs/steering-loop.md',
+  'docs/rules/README.md',
+  'docs/rules/agents.md',
+  'docs/rules/coding-style.md',
+  'docs/rules/git-workflow.md',
+  'docs/rules/testing.md',
+  'docs/rules/security.md',
+  'docs/rules/performance.md',
+  'docs/rules/hooks.md',
+  'manifests/install-modules.json',
 ]
 
-/** 基础目录（必装） */
+/** 语言专项规则目录（采用 ECC 原版，按需复制整个目录） */
+export const RULES_LANGUAGE_DIRS = [
+  'docs/rules/cpp',
+  'docs/rules/csharp',
+  'docs/rules/dart',
+  'docs/rules/golang',
+  'docs/rules/java',
+  'docs/rules/kotlin',
+  'docs/rules/perl',
+  'docs/rules/php',
+  'docs/rules/python',
+  'docs/rules/rust',
+  'docs/rules/swift',
+  'docs/rules/typescript',
+  'docs/rules/web',
+]
+
+/** 空目录结构（必装；session/worker 由 session.cjs 按需创建） */
 export const BASE_DIRS = [
   'scripts/harness',
-  '.dev-agents/shared/tasks',
-  '.dev-agents/shared/designs',
-  '.dev-agents/shared/reviews',
+  'scripts/hooks',
+  'scripts/orchestration',
+  '.orchestration/.logs',
   'docs/templates',
-  'skills/max/workflow/brainstorming',
-  'skills/max/workflow/requirement-validation',
-  'skills/max/workflow/solution-design',
-  'skills/max/workflow/writing-plans',
-  'skills/max/workflow/subagent-driven-development',
-  'skills/max/workflow/testing',
-  'skills/max/workflow/documentation',
-  'skills/max/workflow/finishing-a-development-branch',
-  'skills/max/workflow/systematic-debugging',
-  'skills/max/workflow/verification-before-completion',
-  'skills/max/workflow/entropy-management',
-  'skills/max/competitive-analysis',
-  'skills/max/meeting-notes',
-  'skills/max/prd-template',
-  'skills/max/stakeholder-update',
-  'skills/max/user-research-synthesis',
 ]
 
-/** Hooks 和通用命令（必装） */
-export const HOOKS_FILES = [
+/**
+ * Agent 源池目录（开发态分发位置）。
+ * init 时按用户选择的 agent 模块从这里复制到 .claude/agents/。
+ */
+export const AGENT_SOURCE_DIR = 'agents'
+
+/** Claude Code hooks + commands + plugin 元数据 */
+export const CLAUDE_CORE_FILES = [
   '.claude/hooks.json',
   '.claude/commands/init-project.md',
   '.claude/commands/git-commit.md',
-  '.claude/agents/init-architect.md',
-  '.claude/agents/get-current-datetime.md',
+  '.claude/commands/workflow-start.md',
+  '.claude/commands/plan.md',
+  '.claude/commands/review.md',
+  '.claude/commands/fix-build.md',
+  '.claude/commands/tdd.md',
+  '.claude-plugin/plugin.json',
 ]
 
-/** 角色资产（原生子代理：`.claude/agents/{name}.md`） */
-export const AGENT_ASSETS = {
-  jarvis: {
-    label: '贾维斯 (Jarvis) — 全栈开发工程师',
-    agents: ['.claude/agents/jarvis.md'],
-    skills: ['skills/jarvis'],
-  },
-  ella: {
-    label: '艾拉 (Ella) — UI/UX 设计师',
-    agents: ['.claude/agents/ella.md'],
-    skills: ['skills/ella'],
-  },
-  kyle: {
-    label: '凯尔 (Kyle) — 质量保证工程师',
-    agents: ['.claude/agents/kyle.md'],
-    skills: ['skills/kyle'],
-  },
+/** Codex 适配层（config + 3 个 Codex 原生 persona TOML + plugin 元数据） */
+export const CODEX_CORE_FILES = [
+  '.codex/AGENTS.md',
+  '.codex/config.toml',
+  '.codex/agents/explorer.toml',
+  '.codex/agents/reviewer.toml',
+  '.codex/agents/docs-researcher.toml',
+  '.codex-plugin/plugin.json',
+]
+
+// ─── Manifest 加载 ───
+
+const MANIFEST_PATH = 'manifests/install-modules.json'
+
+/**
+ * 读取安装清单
+ */
+export function loadManifest(pkgRoot) {
+  const path = join(pkgRoot, MANIFEST_PATH)
+  if (!existsSync(path)) {
+    return { version: 0, modules: [] }
+  }
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'))
+  } catch {
+    return { version: 0, modules: [] }
+  }
 }
 
-/** 可更新的资产（update 命令使用） */
-export const UPDATABLE_DIRS = [
-  'scripts/harness',
-  'skills/max/workflow',
-  'skills/max/competitive-analysis',
-  'skills/max/meeting-notes',
-  'skills/max/prd-template',
-  'skills/max/stakeholder-update',
-  'skills/max/user-research-synthesis',
-]
+/**
+ * 获取所有 skill 模块
+ */
+export function getSkillModules(pkgRoot) {
+  return loadManifest(pkgRoot).modules.filter(m => m.kind === 'skills')
+}
 
-export const UPDATABLE_FILES = [
-  '.claude/hooks.json',
-  '.claude/agents/jarvis.md',
-  '.claude/agents/ella.md',
-  '.claude/agents/kyle.md',
-  '.claude/commands/init-project.md',
-  '.claude/commands/git-commit.md',
-  '.claude/agents/init-architect.md',
-  '.claude/agents/get-current-datetime.md',
-]
+/**
+ * 获取默认安装的 skill 模块 id
+ */
+export function getDefaultSkillModuleIds(pkgRoot) {
+  return getSkillModules(pkgRoot)
+    .filter(m => m.defaultInstall)
+    .map(m => m.id)
+}
+
+/**
+ * 获取所有 agent 模块（仅 Claude target，含按 agents 列表分组的）
+ */
+export function getAgentModules(pkgRoot) {
+  return loadManifest(pkgRoot).modules.filter(
+    m => m.kind === 'agents' && Array.isArray(m.agents)
+  )
+}
+
+/**
+ * 获取默认安装的 agent 模块 id
+ */
+export function getDefaultAgentModuleIds(pkgRoot) {
+  return getAgentModules(pkgRoot)
+    .filter(m => m.defaultInstall)
+    .map(m => m.id)
+}
+
+/**
+ * 列出 agent 源池中所有可用的 agent 名（不含 .md 后缀）
+ */
+export function listAvailableAgents(pkgRoot) {
+  const dir = join(pkgRoot, AGENT_SOURCE_DIR)
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter(f => f.endsWith('.md'))
+    .map(f => f.slice(0, -3))
+    .sort()
+}
 
 // ─── 文件操作 ───
 
@@ -114,10 +166,7 @@ export function copyDirRecursive(src, dest, options = {}) {
     const srcPath = join(src, entry)
     const destPath = join(dest, entry)
 
-    // 跳过 .git、node_modules 等
     if (entry === '.git' || entry === 'node_modules') continue
-
-    // 自定义过滤
     if (filter && !filter(srcPath, entry)) continue
 
     const stat = statSync(srcPath)
@@ -146,6 +195,13 @@ export function copySingleFile(src, dest, overwrite = false) {
   return true
 }
 
+/**
+ * 确保目录存在（空目录也创建）
+ */
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+}
+
 /**
  * 模板变量替换
  */
@@ -162,9 +218,6 @@ export function processTemplate(filePath, variables) {
 
 const CONFIG_FILE = '.aigroup.json'
 
-/**
- * 读取用户项目的 aigroup 配置
- */
 export function readConfig(projectRoot) {
   const configPath = join(projectRoot, CONFIG_FILE)
   if (!existsSync(configPath)) return null
@@ -175,9 +228,6 @@ export function readConfig(projectRoot) {
   }
 }
 
-/**
- * 写入配置
- */
 export function writeConfig(projectRoot, config) {
   const configPath = join(projectRoot, CONFIG_FILE)
   writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8')
@@ -187,15 +237,23 @@ export function writeConfig(projectRoot, config) {
 
 /**
  * 执行完整的脚手架安装
- * @param {string} pkgRoot - npm 包根目录（模板资产所在）
+ *
+ * @param {string} pkgRoot - npm 包根目录
  * @param {string} projectRoot - 用户项目目录
  * @param {object} options
- * @param {string[]} options.agents - 选择的角色 ['jarvis', 'ella', 'kyle']
- * @param {boolean} options.overwrite - 是否覆盖已有文件
+ * @param {string[]} [options.modules] - 要安装的 skill 模块 id 列表（不传则装所有 defaultInstall）
+ * @param {string[]} [options.targets] - 目标 harness ['claude', 'codex']（不传则双端都装）
+ * @param {boolean} [options.overwrite] - 是否覆盖已有文件
  * @returns {{ totalCopied: number, sections: object[] }}
  */
 export function scaffold(pkgRoot, projectRoot, options = {}) {
-  const { agents = ['jarvis', 'ella', 'kyle'], overwrite = false } = options
+  const {
+    modules = null,
+    agentModules = null,
+    targets = ['claude', 'codex'],
+    overwrite = false,
+  } = options
+
   const sections = []
   let totalCopied = 0
 
@@ -205,75 +263,188 @@ export function scaffold(pkgRoot, projectRoot, options = {}) {
     const ok = copySingleFile(join(pkgRoot, file), join(projectRoot, file), overwrite)
     if (ok) baseCopied++
   }
-  sections.push({ name: '基础文件', count: baseCopied })
+  sections.push({ name: '基础文件（入口 + 主源文档 + 清单）', count: baseCopied })
   totalCopied += baseCopied
 
   // 2. 基础目录
-  let dirCopied = 0
   for (const dir of BASE_DIRS) {
-    dirCopied += copyDirRecursive(join(pkgRoot, dir), join(projectRoot, dir), { overwrite })
+    const src = join(pkgRoot, dir)
+    const dest = join(projectRoot, dir)
+    if (existsSync(src)) {
+      totalCopied += copyDirRecursive(src, dest, { overwrite })
+    } else {
+      ensureDir(dest)
+    }
   }
-  sections.push({ name: '工作流技能 + 传感器', count: dirCopied })
-  totalCopied += dirCopied
+  sections.push({ name: '传感器 + 协作产物目录', count: totalCopied - baseCopied })
 
-  // 3. Hooks
-  let hooksCopied = 0
-  for (const file of HOOKS_FILES) {
-    const ok = copySingleFile(join(pkgRoot, file), join(projectRoot, file), overwrite)
-    if (ok) hooksCopied++
+  // 2b. 语言专项规则（13 个目录，递归复制）
+  let langRulesCopied = 0
+  for (const dir of RULES_LANGUAGE_DIRS) {
+    langRulesCopied += copyDirRecursive(join(pkgRoot, dir), join(projectRoot, dir), { overwrite })
   }
-  sections.push({ name: 'Hooks 配置', count: hooksCopied })
-  totalCopied += hooksCopied
+  sections.push({ name: '语言专项规则（cpp/golang/java/python/rust/ts/...）', count: langRulesCopied })
+  totalCopied += langRulesCopied
+
+  // 3. Claude Code 适配层（commands + hooks + plugin；agent 由独立步骤按选择安装）
+  if (targets.includes('claude')) {
+    let claudeCopied = 0
+    for (const file of CLAUDE_CORE_FILES) {
+      const ok = copySingleFile(join(pkgRoot, file), join(projectRoot, file), overwrite)
+      if (ok) claudeCopied++
+    }
+    sections.push({ name: 'Claude Code 核心（commands + hooks + plugin）', count: claudeCopied })
+    totalCopied += claudeCopied
+
+    // 3b. Agent 模块（按用户选择，从 agents/ 源池复制到 .claude/agents/）
+    const allAgentModules = getAgentModules(pkgRoot)
+    const selectedAgentIds = agentModules || getDefaultAgentModuleIds(pkgRoot)
 
-  // 4. 角色资产
-  for (const agentId of agents) {
-    const agent = AGENT_ASSETS[agentId]
-    if (!agent) continue
     let agentCopied = 0
+    const installedAgents = new Set()
+    for (const modId of selectedAgentIds) {
+      const mod = allAgentModules.find(m => m.id === modId)
+      if (!mod || !Array.isArray(mod.agents)) continue
+      for (const agentName of mod.agents) {
+        if (installedAgents.has(agentName)) continue
+        const src = join(pkgRoot, AGENT_SOURCE_DIR, `${agentName}.md`)
+        const dest = join(projectRoot, '.claude/agents', `${agentName}.md`)
+        const ok = copySingleFile(src, dest, overwrite)
+        if (ok) {
+          agentCopied++
+          installedAgents.add(agentName)
+        }
+      }
+    }
+    sections.push({
+      name: `Claude agent（${installedAgents.size} 个：${[...installedAgents].slice(0, 5).join(', ')}${installedAgents.size > 5 ? '…' : ''}）`,
+      count: agentCopied,
+    })
+    totalCopied += agentCopied
+  }
 
-    for (const file of agent.agents) {
+  // 4. Codex 适配层
+  if (targets.includes('codex')) {
+    let codexCopied = 0
+    for (const file of CODEX_CORE_FILES) {
       const ok = copySingleFile(join(pkgRoot, file), join(projectRoot, file), overwrite)
-      if (ok) agentCopied++
-    }
-    for (const dir of agent.skills) {
-      agentCopied += copyDirRecursive(join(pkgRoot, dir), join(projectRoot, dir), { overwrite })
+      if (ok) codexCopied++
     }
+    sections.push({ name: 'Codex 适配（config + roles + plugin）', count: codexCopied })
+    totalCopied += codexCopied
+  }
 
-    sections.push({ name: agent.label, count: agentCopied })
-    totalCopied += agentCopied
+  // 5. Skill 模块（manifest 驱动）
+  const allSkillModules = getSkillModules(pkgRoot)
+  const selectedIds = modules || getDefaultSkillModuleIds(pkgRoot)
+
+  for (const modId of selectedIds) {
+    const mod = allSkillModules.find(m => m.id === modId)
+    if (!mod) continue
+
+    // 过滤：该模块是否适用于任一选中的 target
+    const modTargets = mod.targets || ['claude', 'codex']
+    if (!modTargets.some(t => targets.includes(t))) continue
+
+    let modCopied = 0
+    for (const path of mod.paths) {
+      modCopied += copyDirRecursive(join(pkgRoot, path), join(projectRoot, path), { overwrite })
+    }
+    sections.push({
+      name: `skill 模块: ${modId} — ${mod.description || ''}`,
+      count: modCopied,
+    })
+    totalCopied += modCopied
   }
 
   return { totalCopied, sections }
 }
 
 /**
- * 执行增量更新（只更新技能和传感器）
+ * 执行增量更新（按配置中的 modules 和 targets 覆盖更新）
  */
 export function scaffoldUpdate(pkgRoot, projectRoot) {
   const sections = []
   let totalCopied = 0
 
-  // 更新目录（覆盖）
-  for (const dir of UPDATABLE_DIRS) {
-    const copied = copyDirRecursive(join(pkgRoot, dir), join(projectRoot, dir), { overwrite: true })
-    totalCopied += copied
+  const config = readConfig(projectRoot)
+  const modules = config?.modules || getDefaultSkillModuleIds(pkgRoot)
+  const targets = config?.targets || ['claude', 'codex']
+
+  // 传感器
+  const sensorCopied = copyDirRecursive(
+    join(pkgRoot, 'scripts/harness'),
+    join(projectRoot, 'scripts/harness'),
+    { overwrite: true }
+  )
+  sections.push({ name: 'Harness 传感器', count: sensorCopied })
+  totalCopied += sensorCopied
+
+  // Claude adapter（如启用）：commands + hooks + plugin + 已选 agent 模块
+  if (targets.includes('claude')) {
+    let claudeCopied = 0
+    for (const file of CLAUDE_CORE_FILES) {
+      const ok = copySingleFile(join(pkgRoot, file), join(projectRoot, file), true)
+      if (ok) claudeCopied++
+    }
+    // 已安装的 agent 模块按 config 覆盖更新
+    const agentModules = config?.agentModules || getDefaultAgentModuleIds(pkgRoot)
+    const allAgentModules = getAgentModules(pkgRoot)
+    const installedAgents = new Set()
+    for (const modId of agentModules) {
+      const mod = allAgentModules.find(m => m.id === modId)
+      if (!mod || !Array.isArray(mod.agents)) continue
+      for (const agentName of mod.agents) {
+        if (installedAgents.has(agentName)) continue
+        const src = join(pkgRoot, AGENT_SOURCE_DIR, `${agentName}.md`)
+        const dest = join(projectRoot, '.claude/agents', `${agentName}.md`)
+        const ok = copySingleFile(src, dest, true)
+        if (ok) {
+          claudeCopied++
+          installedAgents.add(agentName)
+        }
+      }
+    }
+    sections.push({ name: `Claude Code 适配层（含 ${installedAgents.size} 个 agent）`, count: claudeCopied })
+    totalCopied += claudeCopied
   }
-  sections.push({ name: '工作流技能 + 传感器', count: totalCopied })
 
-  // 更新命令/子代理文件（覆盖）
-  let cmdCopied = 0
-  const config = readConfig(projectRoot)
-  const agents = config?.agents || ['jarvis', 'ella', 'kyle']
-  const roleIds = new Set(['jarvis', 'ella', 'kyle'])
-  for (const file of UPDATABLE_FILES) {
-    // 角色子代理文件：仅更新用户选中的角色
-    const m = file.match(/agents\/([\w-]+)\.md$/)
-    if (m && roleIds.has(m[1]) && !agents.includes(m[1])) continue
+  // Codex adapter（如启用）
+  if (targets.includes('codex')) {
+    let codexCopied = 0
+    for (const file of CODEX_CORE_FILES) {
+      const ok = copySingleFile(join(pkgRoot, file), join(projectRoot, file), true)
+      if (ok) codexCopied++
+    }
+    sections.push({ name: 'Codex 适配层', count: codexCopied })
+    totalCopied += codexCopied
+  }
+
+  // Skill 模块
+  const allSkillModules = getSkillModules(pkgRoot)
+  for (const modId of modules) {
+    const mod = allSkillModules.find(m => m.id === modId)
+    if (!mod) continue
+    let modCopied = 0
+    for (const path of mod.paths) {
+      modCopied += copyDirRecursive(
+        join(pkgRoot, path),
+        join(projectRoot, path),
+        { overwrite: true }
+      )
+    }
+    sections.push({ name: `skill 模块: ${modId}`, count: modCopied })
+    totalCopied += modCopied
+  }
+
+  // 基础文档与清单（覆盖）
+  let docsCopied = 0
+  for (const file of BASE_FILES) {
     const ok = copySingleFile(join(pkgRoot, file), join(projectRoot, file), true)
-    if (ok) cmdCopied++
+    if (ok) docsCopied++
   }
-  sections.push({ name: '命令/子代理文件', count: cmdCopied })
-  totalCopied += cmdCopied
+  sections.push({ name: '主源文档 + 清单', count: docsCopied })
+  totalCopied += docsCopied
 
   return { totalCopied, sections }
 }
@@ -283,5 +454,5 @@ export function scaffoldUpdate(pkgRoot, projectRoot) {
  */
 export function isInitialized(projectRoot) {
   return existsSync(join(projectRoot, 'CLAUDE.md'))
-    && existsSync(join(projectRoot, 'scripts/harness/run-all.sh'))
+    && existsSync(join(projectRoot, 'scripts/hooks/dispatcher.cjs'))
 }

package/docs/README.md

@@ -1,29 +1,46 @@
-# aiGroup 知识库索引
-
-本目录是项目的**唯一事实源 (Single Source of Truth)**，所有架构决策、规范、质量标准均版本化存储于此。
-
-Agent 应按需检索本目录下的文档，而非依赖 CLAUDE.md 中的简短描述。
-
-## 文档地图
-
-| 文档 | 用途 | 更新频率 |
-|------|------|---------|
-| [ARCHITECTURE.md](ARCHITECTURE.md) | 项目架构总览、目录结构、模块职责 | 架构变更时 |
-| [workflow-pipeline.md](workflow-pipeline.md) | 强制工作流管道详细规则 | 流程调整时 |
-| [dispatch-rules.md](dispatch-rules.md) | 团队成员派遣规则与上下文传递 | 角色变更时 |
-| [coding-standards.md](coding-standards.md) | Git 规范、代码规范、注释规则 | 标准更新时 |
-| [red-flags.md](red-flags.md) | Max 必须阻止的危险信号与对应行动 | 发现新模式时 |
-| [QUALITY_SCORE.md](QUALITY_SCORE.md) | 各模块质量评分与健康度追踪 | 每次审查后 |
-| [tech-debt-tracker.md](tech-debt-tracker.md) | 已知技术债与偿还计划 | 持续更新 |
-| [steering-loop.md](steering-loop.md) | Harness 转向循环：问题→编码为规则→自动执行 | 发现重复问题时 |
-| [PROJECT_CONTEXT.md](PROJECT_CONTEXT.md) | 项目实例上下文（/init-project 生成） | 项目初始化时 |
-
-## 子目录
-
-- `templates/` — 静态文档模板（PRD / 实现计划 / 代码审查等）
-
-## 使用原则
-
-1. **渐进式披露** — Agent 先读 CLAUDE.md 获取全局地图，按需深入本目录
-2. **仓库即事实** — 所有约束、决策、规范必须存在于仓库文件中，不依赖口头约定
-3. **文档即代码** — 文档与代码同步更新，过期文档由熵管理流程清理
+# aiGroup 知识库索引
+
+本目录是项目的**唯一事实源 (Single Source of Truth)**，所有架构决策、规范均版本化存储于此。
+
+Agent 应按需检索本目录下的文档，而非依赖 CLAUDE.md / AGENTS.md 中的简短描述。
+
+## 文档地图
+
+### 强制规则（必读）
+
+| 文档 | 主题 |
+|------|------|
+| [rules/README.md](rules/README.md) | Rules 总入口（Rules vs Skills 边界） |
+| [rules/agents.md](rules/agents.md) | Agent 派遣铁律 + 启动协议 + 反模式 |
+| [rules/coding-style.md](rules/coding-style.md) | 编码风格、命名、错误处理、中文注释 |
+| [rules/git-workflow.md](rules/git-workflow.md) | Conventional Commits、Git 安全 |
+| [rules/testing.md](rules/testing.md) | TDD、覆盖率、AAA 模式 |
+| [rules/security.md](rules/security.md) | 安全清单、密钥管理、OWASP |
+| [rules/performance.md](rules/performance.md) | MCP / tool 预算、上下文卫生 |
+| [rules/hooks.md](rules/hooks.md) | Hooks 使用（Claude 自动 / Codex 手动） |
+
+### 派遣与流程
+
+| 文档 | 用途 |
+|------|------|
+| [rules/agents.md](rules/agents.md) | **Agent 派遣完整矩阵**（agent 模块分组、handoff 内容、反模式） |
+| [workflow-pipeline.md](workflow-pipeline.md) | 工作流 phase 心智模型（按需裁剪） |
+
+### 治理
+
+| 文档 | 用途 |
+|------|------|
+| [red-flags.md](red-flags.md) | 主会话必须阻止的危险信号与对应行动 |
+| [PROJECT_CONTEXT.md](PROJECT_CONTEXT.md) | 项目实例上下文（/init-project 生成） |
+
+## 子目录
+
+- `rules/` — 强制规则集（按领域切分）
+- `templates/` — 静态文档模板（PRD / 实现计划 / 代码审查等）
+
+## 使用原则
+
+1. **渐进式披露** — Agent 先读 CLAUDE.md / AGENTS.md 获取全局地图，按需深入本目录
+2. **仓库即事实** — 所有约束、决策、规范必须存在于仓库文件中，不依赖口头约定
+3. **Rules vs Skills** — Rules 决定**必须做什么**；Skills 决定**怎么做**
+4. **文档即代码** — 文档与代码同步更新

package/docs/red-flags.md

@@ -1,24 +1,29 @@
-# 危险信号检测（Red Flags）
-
-Max 在工作流中必须持续监测以下危险信号。检测到任何一个时，**立即阻止并采取对应行动**。
-
-## 信号清单
-
-| # | 危险信号 | 行动 | 严重度 |
-|---|---------|------|--------|
-| 1 | 需求不清就开始编码 | 停下来，启动 brainstorming | 🔴 高 |
-| 2 | 没有实现计划就开始开发 | 停下来，先写 writing-plans | 🔴 高 |
-| 3 | Jarvis 说"搞定了"但没有验证证据 | 要求运行测试并展示输出 | 🔴 高 |
-| 4 | Kyle 审查只做了一个阶段 | 要求完成两阶段审查 | 🟡 中 |
-| 5 | 审查发现问题但直接跳过 | 要求 Jarvis 修复后重新审查 | 🔴 高 |
-| 6 | 有人想跳过工作流环节 | 拒绝，除非符合简单任务豁免 | 🔴 高 |
-| 7 | 使用"应该没问题""看起来对了" | 要求提供验证命令和输出证据 | 🟡 中 |
-| 8 | 同一类错误反复出现 | 运行 `bash scripts/harness/logs-query.sh --hotspots --days 30` 查看高频失败项，再触发 [转向循环](steering-loop.md) | 🟡 中 |
-| 9 | 文档与代码不一致 | 触发 [熵管理](../skills/max/workflow/entropy-management/SKILL.md)，修复漂移 | 🟡 中 |
-| 10 | Harness 传感器长期无告警 | 审查传感器有效性，可能检测不足 | 🟡 中 |
-
-## 升级机制
-
-- 🔴 高：立即中断当前流程，回到正确阶段
-- 🟡 中：在当前阶段结束前处理
-- 信号 #8 是 Harness Engineering 的核心：**重复问题不应靠人工反复修正，而应编码为自动化约束**
+# 危险信号检测（Red Flags）
+
+主会话必须持续监测以下危险信号。检测到任何一个时，**立即阻止并采取对应行动**。
+
+**适用范围**：
+- **始终生效**：信号 #3、#5、#7、#8、#9、#10、#11 —— 与运行模式无关
+- **仅工作流模式生效**：信号 #1、#2、#4、#6 —— 默认模式下用户未启动管道，这些不触发
+
+## 信号清单
+
+| # | 危险信号 | 行动 | 严重度 | 适用 |
+|---|---------|------|--------|------|
+| 1 | 需求不清就开始编码 | 停下来，建议用户 `/workflow-start` 启动 brainstorming | 🔴 高 | 工作流模式 |
+| 2 | 没有实现计划就开始开发 | 停下来，先写 writing-plans | 🔴 高 | 工作流模式 |
+| 3 | 实现 agent 说"搞定了"但没有验证证据 | 要求运行测试并展示输出 | 🔴 高 | 始终 |
+| 4 | code-reviewer 审查只做了一个阶段 | 要求完成两阶段审查 | 🟡 中 | 工作流模式 |
+| 5 | 审查发现问题但直接跳过 | 要求对应实现 agent 修复后重新审查 | 🔴 高 | 始终 |
+| 6 | 工作流中有人想跳过关键 phase | 说清楚跳过的理由，让用户确认（phase 按需裁剪，但不能无声跳过） | 🔴 高 | 工作流模式 |
+| 7 | 使用"应该没问题""看起来对了" | 要求提供验证命令和输出证据 | 🟡 中 | 始终 |
+| 8 | 同一类错误反复出现 | 运行 `bash scripts/harness/logs-query.sh --hotspots --days 30` 查看高频失败项 | 🟡 中 | 始终 |
+| 9 | 文档与代码不一致 | 触发 [熵管理](../skills/entropy-management/SKILL.md)，修复漂移 | 🟡 中 | 始终 |
+| 10 | Harness 传感器长期无告警 | 审查传感器有效性，可能检测不足 | 🟡 中 | 始终 |
+| 11 | 主会话直接写代码/做设计/做测试 | 立即停下，按任务类型派遣专项 agent 执行 | 🔴 高 | 始终 |
+
+## 升级机制
+
+- 🔴 高：立即中断当前流程，回到正确阶段
+- 🟡 中：在当前阶段结束前处理
+- 信号 #8 是 Harness Engineering 的核心：**重复问题不应靠人工反复修正，而应编码为自动化约束**